create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/api/remote-sessions.js

@@ -0,0 +1,1326 @@
+'use strict';
+
+// Landing-throughput WP-5 shard S1 (design doc §5 D-10 "move-only", §6 "Shard module seam",
+// §8 WP-5, §9 S-21..S-27): four remote-session handlers move out of server.js VERBATIM --
+// handleRemoteApi, _sendRemoteTerminalSubmission, _selectRemoteTerminalChoiceBody and
+// _observeRemoteSubmission. Each body is identical to server.js's declaration 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 --from HEAD:coding-task-manager/server.js \
+//     --to coding-task-manager/lib/api/remote-sessions.js \
+//     --names handleRemoteApi,_sendRemoteTerminalSubmission,_selectRemoteTerminalChoiceBody,_observeRemoteSubmission
+//
+// This module registers NO routes. The /api/remote/ prefix stays dispatched by
+// lib/api/access.js (`_deps.handleRemoteApi`); server.js now points that key at this module's
+// export instead of its own (deleted) declaration. Callers left in server.js reach the moved
+// functions through this module's exports (D-10 rule 4).
+//
+// Injected deps (D-10 rule 1), per function:
+//   handleRemoteApi (52): QRCode, REMOTE_TERMINAL_SUBMIT_DELAY_MS, REMOTE_TERMINAL_SUBMIT_SETTLE_MAX_MS, REMOTE_TERMINAL_SUBMIT_SETTLE_QUIET_MS, _activateDeferredSession, _cancelWalleSessionTurn, _createRemoteSubmissionRecord, _getHeadlessRows, _healRemoteSubmissionRows, _injectSessionInterrupt, _isLiveTerminalSession, _isWalleChatThreadId, _isWalleModelConfigurableSession, _mainDbCensus, _persistWalleSessionModelPreference, _recordRuntimeInputAcceptedForSession, _recordRuntimeInputResultForSession, _remoteCommandRuntime, _remoteHostedPairingReady, _remoteRelayBootInstance, _remoteRelayStatusPayload, _remoteSessionSummary, _remoteSubmissionPublic, _respondToRemoteApproval, _runtimeInputBaseForSession, _selectRemoteTerminalChoice, _selectResumePromptChoice, _sendRemoteJson, _sendRemoteWalleThreadMessage, _snapshotOutputMarker, _storeRemoteSubmissionStatus, _waitForTerminalRenderSettle, _walleModelSelectionForActiveSession, _writeLockBusyApiError, closeWsForDeviceIds, dbModule, deliverAcpSubmission, emitHumanSubmit, handleInput, handleWalleMessage, isAcpSession, mobileAuthStore, readMobileJsonBody, recordSessionDiagnostic, remoteRelayProtocol, remoteRelayStore, remoteSubmissionObserver, requestOrigin, sessions, terminalComposerState, walleClient.
+//   _sendRemoteTerminalSubmission (33): REMOTE_TERMINAL_SUBMIT_DELAY_MS, REMOTE_TERMINAL_SUBMIT_SETTLE_MAX_MS, REMOTE_TERMINAL_SUBMIT_SETTLE_QUIET_MS, _createRemoteSubmissionRecord, _getHeadlessViewportRead, _instanceIdentityAccess, _isLiveTerminalSession, _markQueueAutosendDirty, _ownerRecovery, _providerActivelyGenerating, _recordRuntimeInputAcceptedForSession, _recordRuntimeInputResultForSession, _remoteTerminalSubmissionBlocker, _remoteTerminalSubmissionText, _remoteTerminalSubmissionWritePayload, _runtimeInputBaseForSession, _runtimeInputFailureResultForError, _scheduleRemoteSubmissionObservation, _snapshotOutputMarker, _storeRemoteSubmissionStatus, _terminalProcessGeneration, _waitForTerminalRenderSettle, dbModule, handleInput, promptSubmissionContract, recordSessionDiagnostic, remoteRelayStore, remoteTerminalTarget, rootDeliveryRuntime, rootTerminalInputGateway, sessions, stripAnsi, telemetry.
+//   _selectRemoteTerminalChoiceBody (12): SELECT_CHOICE_FRAME_GAP_MS, _getHeadlessTextRead, _isLiveTerminalSession, _recordRuntimeInputAcceptedForSession, _recordRuntimeInputResultForSession, _resumeChoiceClickRepair, _runtimeInputBaseForSession, _waitForTerminalRenderSettle, handleInput, recordSessionDiagnostic, sessions, terminalChoice.
+//   _observeRemoteSubmission (17): REMOTE_SUBMISSION_FINAL_STATUSES, REMOTE_SUBMISSION_OBSERVE_DELAYS_MS, REMOTE_TERMINAL_ENTER_RETRY_MIN_ELAPSED_MS, _getHeadlessRows, _isLiveTerminalSession, _isWebPromptSubmission, _readPromptSubmissionByMessageId, _remoteSubmissionDurablePromptMatch, _remoteSubmissionObservationCurrent, _scheduleRemoteSubmissionObservation, _snapshotOutputMarker, _storeRemoteSubmissionStatus, handleInput, recordSessionDiagnostic, remoteSubmissionObserver, sessions, submissionAck.
+//
+// Mutability (D-10 rule 2): the only dep that is `let` in server.js and reassigned there is
+// _ownerRecovery (declared server.js:674, assigned server.js:7922), so server.js injects it as a
+// GETTER. Every other dep is an immutable `const`/function declaration and is passed by value.
+// No moved body assigns to any server.js top-level binding (checked mechanically).
+//
+// Two D-10 rule 1 notes:
+//   1. handleRemoteApi's one inline `require('./lib/env-flags')` is the ONE non-verbatim line: it
+//      becomes this module's own static `require('../env-flags')` (same file, path relative to
+//      lib/api/). Injecting server.js's `require` instead is a loader-value transfer the public
+//      runtime closure guard refuses, so move-only-check reports exactly this one difference.
+//   2. A dep in SHORTHAND object-property position cannot carry the prefix without changing
+//      Property.shorthand, which move-only-check compares. handleInput is bound at
+//      module scope and assigned in configure() instead.
+//
+// WP-15 (docs/deepseek-harness-acp-agent-2026-10-28.html): handleRemoteApi's `sendSessionMessage`
+// is no longer byte-identical to server.js's declaration -- a LIVE ACP (DeepSeek Harness) session
+// has no ptyProcess, so the phone's reply was refused `session_not_live` at this door. The door now
+// admits it and hands the prompt to the SAME lane the desktop uses (`dshPromptLane.wrapDeliver` ->
+// `deliverAcp`), injected as `deliverAcpSubmission({sessionId, text, parentReceiptId, source,
+// attachments})`; `isAcpSession` (lib/session-transport.js) is the predicate. The phone's message id
+// becomes the receipt/submission id, so the lane's own storeStatus (_storeRemoteSubmissionStatus)
+// updates the row the phone polls. A non-live ACP session (no `_acpProcess`, or exited) keeps the
+// existing `session_not_live` / deferred-activate answers, and a PTY session is untouched.
+
+let _deps = null;
+let handleInput = null;
+
+
+function configure(deps = {}) {
+  _deps = deps;
+  handleInput = deps.handleInput;
+}
+
+async function handleRemoteApi(req, res, url) {
+  const db = _deps.dbModule.getDb();
+
+  try {
+    if (url.pathname === '/api/remote/status' && req.method === 'GET') {
+      _deps._sendRemoteJson(res, 200, await _deps._remoteRelayStatusPayload(req));
+      return true;
+    }
+
+    if (url.pathname === '/api/remote/registry' && req.method === 'GET') {
+      _deps._sendRemoteJson(res, 200, { ok: true, registry: _deps.remoteRelayProtocol.publicRegistry() });
+      return true;
+    }
+
+    if (url.pathname === '/api/remote/audit' && req.method === 'GET') {
+      const limit = Math.max(1, Math.min(500, Number(url.searchParams.get('limit') || 100)));
+      _deps._sendRemoteJson(res, 200, { ok: true, audit: _deps.remoteRelayStore.listAudit(db, { limit }) });
+      return true;
+    }
+
+    if (url.pathname === '/api/remote/submissions' && req.method === 'GET') {
+      const limit = Math.max(1, Math.min(200, Number(url.searchParams.get('limit') || 50)));
+      const sessionId = String(url.searchParams.get('session_id') || url.searchParams.get('sessionId') || '').trim();
+      const sinceMs = Math.max(0, Number(url.searchParams.get('since_ms') || url.searchParams.get('sinceMs') || 0) || 0);
+      const originalSessionSnapshots = new Map(_deps.sessions);
+      await _deps._remoteCommandRuntime.handleSubmissionsGet({
+        req, url, sessionId, sinceMs, limit,
+        sendJson: (code, payload) => _deps._sendRemoteJson(res, code, payload),
+        formatSubmission: _deps._remoteSubmissionPublic,
+        isRequestCurrent: () => req.aborted !== true && req.destroyed !== true
+          && res.destroyed !== true && res.writableEnded !== true,
+        healBeforeReply: async (submissions, originalScope) => {
+          const healingScope = Object.freeze({ ...originalScope, sessionSnapshots: originalSessionSnapshots });
+          try {
+            return await _deps._mainDbCensus.runOutsideRequestZone(() => _deps._healRemoteSubmissionRows(submissions, healingScope));
+          } catch (error) {
+            console.warn(`[remote-submissions] heal failed: ${error.message}`);
+            return submissions;
+          }
+        },
+      });
+      return true;
+    }
+
+    if (url.pathname === '/api/remote/pairing-claims' && req.method === 'POST') {
+      const body = await _deps.readMobileJsonBody(req, 64 * 1024);
+      const status = await _deps.remoteRelayStore.buildRemoteStatus(db);
+      if (!_deps._remoteHostedPairingReady(status)) {
+        _deps._sendRemoteJson(res, 400, {
+          ok: false,
+          error: 'hosted_pairing_unavailable',
+          message: 'Hosted Walle Relay pairing is not connected yet.',
+        });
+        return true;
+      }
+      const origin = body.origin || _deps.requestOrigin(req);
+      const label = String(body.label || 'Owner iPhone').trim() || 'Owner iPhone';
+      const scopes = body.scopes || ['read', 'respond'];
+      const claim = await _deps.mobileAuthStore.createDeviceClaim(db, {
+        label,
+        scopes,
+        origin,
+        createdBy: req.ctmAuth?.deviceId || 'walle-remote-setup',
+      });
+      const hostedPairUrl = new URL(`/pair/${encodeURIComponent(claim.id)}`, status.instance.mobile_url);
+      hostedPairUrl.searchParams.set('secret', claim.secret);
+      hostedPairUrl.searchParams.set('instance', status.instance.id);
+      const hostedPairUrlText = hostedPairUrl.toString();
+      const qrDataUrl = await _deps.QRCode.toDataURL(hostedPairUrlText, { margin: 1, scale: 5 });
+      await _deps.remoteRelayStore.insertAudit(db, {
+        accountId: status.instance.relay_account_id,
+        instanceId: status.instance.id,
+        action: 'pairing_claim_create',
+        risk: 'medium',
+        result: 'allow',
+        metadata: {
+          claim_id: claim.id,
+          scopes: claim.scopes,
+          hosted_pairing_available: false,
+        },
+      });
+      _deps._sendRemoteJson(res, 200, {
+        ok: true,
+        claim: {
+          ...claim,
+          qr_data_url: qrDataUrl,
+          local_pair_url: claim.claimUrl,
+          hosted_pair_url: hostedPairUrlText,
+          pairing_url: hostedPairUrlText,
+        },
+        relay: status.relay,
+      });
+      return true;
+    }
+
+    const revokeMatch = url.pathname.match(/^\/api\/remote\/devices\/([^/]+)\/revoke$/);
+    if (revokeMatch && req.method === 'POST') {
+      const deviceId = decodeURIComponent(revokeMatch[1]);
+      await _deps.mobileAuthStore.revokeDeviceToken(db, deviceId);
+      _deps.closeWsForDeviceIds([deviceId]);
+      await _deps.remoteRelayStore.insertAudit(db, {
+        deviceId,
+        action: 'device_revoke',
+        risk: 'medium',
+        result: 'allow',
+      });
+      _deps._sendRemoteJson(res, 200, { ok: true });
+      return true;
+    }
+    if (url.pathname === '/api/remote/messages' && req.method === 'POST') {
+      let body;
+      try {
+        body = await _deps.readMobileJsonBody(req, 256 * 1024);
+      } catch {
+        _deps._sendRemoteJson(res, 400, { ok: false, error: 'invalid_remote_command', code: 'invalid_remote_command' });
+        return true;
+      }
+      const rawMessage = body?.message || body;
+      const preflight = await _deps._remoteCommandRuntime.freshHttpContext(req, url);
+      if (!preflight.ok) {
+        _deps._sendRemoteJson(res, preflight.status, { ok: false, error: preflight.code, code: preflight.code });
+        return true;
+      }
+      const status = {
+        instance: _deps._remoteRelayBootInstance ? {
+          ..._deps._remoteRelayBootInstance,
+          relay_account_id: String(_deps._remoteRelayBootInstance.relay_account_id || require('../env-flags').strFlag('WALLE_RELAY_ACCOUNT_ID', '') || ''),
+        } : null,
+      };
+      const bound = _deps.remoteRelayProtocol.bindTrustedEnvelope(rawMessage, {
+        accountId: status.instance?.relay_account_id || 'local',
+        instanceId: status.instance?.id,
+        deviceId: preflight.auth?.deviceId || '',
+      });
+      if (!bound.ok) {
+        const unavailable = bound.error === 'trusted_target_unavailable';
+        _deps._sendRemoteJson(res, unavailable ? 503 : 400, bound);
+        return true;
+      }
+      const message = _deps.remoteRelayProtocol.normalizeEnvelope(bound.message);
+      const guard = _deps._remoteCommandRuntime.inputGuard(message);
+      if (guard) { _deps._sendRemoteJson(res, guard.status, guard.payload); return true; }
+      const initialEnvelope = _deps.remoteRelayProtocol.authorizeRemoteEnvelope(message, preflight.auth);
+      if (!initialEnvelope.ok) {
+        const code = String(initialEnvelope.code || initialEnvelope.error || 'unauthorized');
+        const statusCode = Number(initialEnvelope.status) || (code === 'unauthorized' ? 401 : 400);
+        _deps._sendRemoteJson(res, statusCode, { ok: false, error: code, code });
+        return true;
+      }
+      const result = await _deps._remoteCommandRuntime.execute({
+        namespace: preflight.namespace,
+        message,
+        auth: preflight.auth,
+        trustedTransport: {
+          account_id: message.account_id,
+          instance_id: message.instance_id,
+          device_id: message.device_id,
+          created_at: message.created_at || '',
+        },
+        authorize: async () => {
+          const current = await _deps._remoteCommandRuntime.freshHttpContext(req, url, preflight.namespace);
+          if (!current.ok) return current;
+          const envelope = _deps.remoteRelayProtocol.authorizeRemoteEnvelope(message, current.auth);
+          if (!envelope.ok) {
+            const code = String(envelope.code || envelope.error || 'unauthorized');
+            const statusCode = Number(envelope.status) || (code === 'unauthorized' ? 401 : 400);
+            return { ok: false, code, status: statusCode };
+          }
+          return { ok: true };
+        },
+        handlers: {
+          instanceStatus: () => _deps._remoteRelayStatusPayload(req),
+          listSessions: () => ({
+            ok: true,
+            sessions: Array.from(_deps.sessions.values()).map(_deps._remoteSessionSummary).filter(Boolean),
+          }),
+          getSession: (sessionId) => {
+            const session = _deps.sessions.get(sessionId);
+            return session ? { ok: true, session: _deps._remoteSessionSummary(session) } : { ok: false, error: 'session_not_found' };
+          },
+          wallEStatus: async () => {
+            try {
+              const upstream = await _deps.walleClient.requestJson('/api/wall-e/status');
+              return { ok: upstream.status < 400, status: upstream.json?.data || upstream.json || null };
+            } catch (err) {
+              return { ok: false, error: err.message || 'wall_e_unavailable' };
+            }
+          },
+          activateSession: async (sessionId, body = {}, message = {}) => {
+            return _deps._activateDeferredSession(req, sessionId, body, message);
+          },
+          sendSessionMessage: async (sessionId, text, body = {}, message = {}) => {
+            const session = _deps.sessions.get(sessionId);
+            if (!session) return { ok: false, error: 'session_not_found' };
+            if (!text.trim()) return { ok: false, error: 'message_required' };
+            // WP-15: a LIVE DeepSeek Harness (ACP) session is a child on pipes with no ptyProcess,
+            // so _isLiveTerminalSession below can never admit it -- the phone's reply used to be
+            // refused `session_not_live` here. It is driven by the SAME prompt lane the desktop
+            // uses (dshPromptLane.wrapDeliver -> deliverAcp), injected as deliverAcpSubmission; the
+            // phone's message id is the receipt id, so the lane's own storeStatus
+            // (_storeRemoteSubmissionStatus) updates the very row the phone polls for
+            // received/delivered/failed. Attachments ride body.attachments exactly as WP-11 defines
+            // them. Anything that is not live (no _acpProcess, or exited) falls through to the
+            // existing refusal below, which is what a deferred dsh placeholder needs.
+            if (_deps.isAcpSession(session) && session._acpProcess && session.status !== 'exited' && session.status !== 'closed') {
+              const acpMessageId = String(message.id || '').trim();
+              if (acpMessageId) await _deps._createRemoteSubmissionRecord(sessionId, text, {
+                messageId: acpMessageId,
+                deviceId: message.device_id || req.ctmAuth?.deviceId || '',
+                messageType: message.type || 'session.send_message',
+                source: 'mobile',
+              });
+              const acpDelivered = await _deps.deliverAcpSubmission({
+                sessionId, text, parentReceiptId: acpMessageId, source: 'mobile', attachments: body.attachments,
+              });
+              if (acpDelivered && acpDelivered.ok === true) _deps.emitHumanSubmit(sessionId);
+              return acpDelivered;
+            }
+            if (!_deps._isLiveTerminalSession(session)) {
+              // A deferred placeholder (post-restart, no PTY yet) can be revived from the
+              // phone. Tell the client so it offers Activate instead of retrying forever.
+              if (session._restoreDeferred) {
+                return {
+                  ok: false,
+                  error: 'session_not_live',
+                  restore_deferred: true,
+                  activate_required: true,
+                  message: 'This session is asleep on your Mac. Activate it to send.',
+                };
+              }
+              return {
+                ok: false,
+                error: 'session_not_live',
+                message: 'This session is not accepting terminal input.',
+              };
+            }
+            const delivered = await _sendRemoteTerminalSubmission(req, sessionId, text, { message, messageId: message.id, deviceId: message.device_id || req.ctmAuth?.deviceId || '', messageType: message.type || 'session.send_message', body });
+            if (delivered && delivered.ok === true) _deps.emitHumanSubmit(sessionId); // WP-5 D-13: once per accepted phone message
+            return delivered;
+          },
+          respondApproval: async (sessionId, decision, body = {}, message = {}) => {
+            return _deps._respondToRemoteApproval(req, sessionId, decision, body, message);
+          },
+          selectChoice: async (sessionId, body = {}, message = {}) => {
+            return body.generation != null
+              ? _deps._selectResumePromptChoice(req, sessionId, body, message)
+              : _deps._selectRemoteTerminalChoice(req, sessionId, body, message);
+          },
+          submitSessionInput: async (sessionId, body = {}, message = {}) => {
+            const session = _deps.sessions.get(sessionId);
+            if (!session) return { ok: false, error: 'session_not_found' };
+            const runtimeInput = _deps._runtimeInputBaseForSession(sessionId, session, {
+              inputId: message.id ? `remote:${message.id}` : '',
+              message,
+              messageId: message.id,
+              deviceId: message.device_id || req.ctmAuth?.deviceId || '',
+              messageType: message.type || 'session.submit_input',
+              mode: 'inline',
+              source: 'mobile',
+              text: '',
+              action: 'session.submit_input',
+              appendUserInputEvent: false,
+              metadata: { key: 'enter' },
+            });
+            _deps._recordRuntimeInputAcceptedForSession(sessionId, session, runtimeInput);
+            if (!_deps._isLiveTerminalSession(session)) {
+              _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', 'session_not_live');
+              return { ok: false, error: 'session_not_live', message: 'This session is not accepting terminal control input.' };
+            }
+            // A line-editor TUI (Claude Code / Codex) swallows an Enter that
+            // arrives before it has committed the composer's current contents,
+            // leaving the reply stuck in the composer — the exact failure the
+            // full phone-send path avoids by waiting for the terminal to settle
+            // before pressing Enter. This Submit-current-input button used to
+            // fire a bare \r instantly, so a tap could no-op and the agent kept
+            // waiting. Wait for render settle first, then press Enter, and
+            // report whether the terminal actually advanced instead of blindly
+            // claiming success.
+            const beforeEnterMarker = _deps._snapshotOutputMarker(session);
+            await _deps._waitForTerminalRenderSettle(session, {
+              minMs: _deps.REMOTE_TERMINAL_SUBMIT_DELAY_MS,
+              maxMs: _deps.REMOTE_TERMINAL_SUBMIT_SETTLE_MAX_MS,
+              quietMs: _deps.REMOTE_TERMINAL_SUBMIT_SETTLE_QUIET_MS,
+            });
+            const live = _deps.sessions.get(sessionId);
+            if (!_deps._isLiveTerminalSession(live)) {
+              _deps._recordRuntimeInputResultForSession(sessionId, live || session, runtimeInput, 'rejected', 'session_not_live_before_enter');
+              return { ok: false, error: 'session_not_live', message: 'The session stopped before CTM could press Enter.' };
+            }
+            const composerRows = await _deps._getHeadlessRows(sessionId, 900); // an unreadable screen is not proof the composer is empty
+            if (Array.isArray(composerRows) && _deps.terminalComposerState(composerRows).empty) {
+              _deps._recordRuntimeInputResultForSession(sessionId, live, runtimeInput, 'rejected', 'composer_empty');
+              return { ok: false, error: 'composer_empty', message: 'There is nothing typed in the terminal to submit.' };
+            }
+            handleInput({ auth: req.ctmAuth }, { id: sessionId, data: '\r' }, { authenticatedRemote: true });
+            // Give the agent a beat to accept (clear the composer / start a turn),
+            // then check whether the terminal output advanced past the Enter.
+            await _deps._waitForTerminalRenderSettle(_deps.sessions.get(sessionId), {
+              minMs: _deps.REMOTE_TERMINAL_SUBMIT_DELAY_MS,
+              maxMs: _deps.REMOTE_TERMINAL_SUBMIT_SETTLE_MAX_MS,
+              quietMs: _deps.REMOTE_TERMINAL_SUBMIT_SETTLE_QUIET_MS,
+            });
+            const advanced = _deps.remoteSubmissionObserver.terminalSubmissionAcceptedByMarker({
+              beforeEnterMarker,
+              markerNow: _deps._snapshotOutputMarker(_deps.sessions.get(sessionId)),
+            }).accepted;
+            _deps.recordSessionDiagnostic(sessionId, 'remote-submit-current-input', {
+              source: 'remote-api',
+              message_id: message.id || '',
+              device_id: message.device_id || req.ctmAuth?.deviceId || '',
+              advanced,
+            });
+            _deps._recordRuntimeInputResultForSession(sessionId, _deps.sessions.get(sessionId) || session, runtimeInput, advanced ? 'delivered' : 'deferred', advanced ? 'enter_advanced' : 'enter_no_advance');
+            return { ok: true, delivered: true, submitted: advanced, key: 'enter' };
+          },
+          cancelSessionStream: (sessionId, body = {}, message = {}) => {
+            const session = _deps.sessions.get(sessionId);
+            if (!session) return { ok: false, error: 'session_not_found' };
+            if (session.type === 'walle') {
+              return _deps._cancelWalleSessionTurn(sessionId, 'remote-api');
+            }
+            if (!_deps._isLiveTerminalSession(session)) {
+              return {
+                ok: false,
+                error: 'session_not_live',
+                message: 'This session is not accepting terminal control input.',
+              };
+            }
+            const interrupt = _deps._injectSessionInterrupt(session, 'remote');
+            if (!interrupt.ok) return { ok: false, error: interrupt.reason };
+            // Mirror the sibling remote-approval-deny diagnostic (this handler writes
+            // the exact same turn-aborting escape byte, just from a different phone
+            // action) so "who sent the escape" is attributable from this call site too.
+            _deps.recordSessionDiagnostic(sessionId, 'remote-cancel-stream', {
+              source: 'remote-api',
+              messageId: message.id || '',
+              key: 'escape',
+            });
+            return { ok: true, delivered: true, key: 'escape' };
+          },
+          navigatePromptHistory: (sessionId, direction) => {
+            const session = _deps.sessions.get(sessionId);
+            if (!session) return { ok: false, error: 'session_not_found' };
+            if (!session.ptyProcess || session.status === 'exited' || session.status === 'closed') {
+              return {
+                ok: false,
+                error: 'session_not_live',
+                message: 'This session is not accepting terminal control input.',
+              };
+            }
+            const data = direction === 'previous' ? '\x1b[A' : '\x1b[B';
+            handleInput({ auth: req.ctmAuth }, { id: sessionId, data }, { authenticatedRemote: true });
+            return { ok: true, delivered: true, direction, key: direction === 'previous' ? 'arrow_up' : 'arrow_down' };
+          },
+          sendWalleMessage: async (sessionId, text, body = {}, message = {}) => {
+            const submission = await _deps._createRemoteSubmissionRecord(sessionId, text, {
+              message,
+              messageId: message.id,
+              deviceId: message.device_id || req.ctmAuth?.deviceId || '',
+              messageType: message.type || 'wall_e.send_message',
+            });
+            const runtimeInput = _deps._runtimeInputBaseForSession(sessionId, _deps.sessions.get(sessionId), {
+              inputId: message.id ? `remote:${message.id}` : '',
+              message,
+              messageId: message.id,
+              deviceId: message.device_id || req.ctmAuth?.deviceId || '',
+              messageType: message.type || 'wall_e.send_message',
+              adapter: 'walle',
+              mode: 'inline',
+              source: 'mobile',
+              text,
+              attachments: Array.isArray(body.attachments) ? body.attachments : [],
+              action: 'wall_e.send_message',
+              metadata: { transport: 'remote-wall-e' },
+            });
+            _deps._recordRuntimeInputAcceptedForSession(sessionId, _deps.sessions.get(sessionId), runtimeInput);
+            const session = _deps.sessions.get(sessionId);
+            if (!session && _deps._isWalleChatThreadId(sessionId)) {
+              const result = await _deps._sendRemoteWalleThreadMessage(sessionId, text, body);
+              _deps._recordRuntimeInputResultForSession(
+                sessionId,
+                null,
+                runtimeInput,
+                result.ok ? 'delivered' : 'rejected',
+                result.ok ? 'walle_default_chat_delivered' : (result.error || 'walle_chat_failed')
+              );
+              if (submission) {
+                _deps._storeRemoteSubmissionStatus(sessionId, message.id, result.ok ? 'durable_user_message_seen' : 'failed', {
+                  reason: result.ok ? 'walle_default_chat_delivered' : (result.error || 'walle_chat_failed'),
+                  message: result.ok ? 'Wall-E accepted this phone reply.' : (result.message || result.error || 'Wall-E could not accept this phone reply.'),
+                  source: 'wall-e',
+                });
+              }
+              return submission ? { ...result, submission_id: message.id, submission_status: result.ok ? 'durable_user_message_seen' : 'failed' } : result;
+            }
+            if (!session) {
+              if (submission) _deps._storeRemoteSubmissionStatus(sessionId, message.id, 'failed', { reason: 'session_not_found', message: 'Session was not found.', source: 'remote-api' });
+              _deps._recordRuntimeInputResultForSession(sessionId, null, runtimeInput, 'rejected', 'session_not_found');
+              return { ok: false, error: 'session_not_found', submission_id: message.id || undefined, submission_status: submission ? 'failed' : undefined };
+            }
+            if (session.type !== 'walle') {
+              if (submission) _deps._storeRemoteSubmissionStatus(sessionId, message.id, 'failed', { reason: 'not_walle_session', message: 'This is not a Wall-E session.', source: 'remote-api' });
+              _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', 'not_walle_session');
+              return { ok: false, error: 'not_walle_session', submission_id: message.id || undefined, submission_status: submission ? 'failed' : undefined };
+            }
+            if (!text.trim()) {
+              if (submission) _deps._storeRemoteSubmissionStatus(sessionId, message.id, 'failed', { reason: 'message_required', message: 'Message text is required.', source: 'remote-api' });
+              _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', 'message_required');
+              return { ok: false, error: 'message_required', submission_id: message.id || undefined, submission_status: submission ? 'failed' : undefined };
+            }
+            const attachments = Array.isArray(body.attachments) ? body.attachments : [];
+            const explicitModel = body.model_id || body.model || '';
+            const explicitProvider = body.model_provider || body.provider || '';
+            await _deps.handleWalleMessage({ auth: req.ctmAuth }, {
+              id: sessionId,
+              text,
+              attachments,
+              echoUser: true,
+              displayText: text,
+              model: explicitModel || session.model_id || '',
+              provider: explicitProvider || session.model_provider || '',
+              model_registry_id: body.model_registry_id || body.modelRegistryId || session.model_registry_id || '',
+              model_provider_id: body.model_provider_id || body.modelProviderId || session.model_provider_id || '',
+              modelPinned: body.modelPinned === true || body.model_pinned === true || !!explicitModel || !!session.model_pinned,
+              allowProviderFallback: explicitModel ? false : !session.model_pinned,
+              runtimeInputId: runtimeInput.inputId,
+              messageId: message.id || '',
+              source: 'remote-api',
+            });
+            if (submission) {
+              _deps._storeRemoteSubmissionStatus(sessionId, message.id, 'durable_user_message_seen', {
+                reason: 'walle_session_delivered',
+                message: 'Wall-E accepted this phone reply.',
+                source: 'wall-e',
+              });
+            }
+            return { ok: true, delivered: true, submission_id: message.id || undefined, submission_status: submission ? 'durable_user_message_seen' : undefined };
+          },
+          setWalleModel: async (sessionId, body = {}) => {
+            const session = _deps.sessions.get(sessionId);
+            if (!session) return { ok: false, error: 'session_not_found' };
+            if (!_deps._isWalleModelConfigurableSession(session)) return { ok: false, error: 'not_walle_session' };
+            const pref = await _deps._persistWalleSessionModelPreference(session, {
+              model_id: body.model_id || body.model || '',
+              model_provider: body.model_provider || body.provider || '',
+              model_registry_id: body.model_registry_id || body.modelRegistryId || '',
+              model_provider_id: body.model_provider_id || body.provider_id || '',
+              scope: body.scope || 'session',
+              source: 'phone',
+              pinned: body.pinned !== false,
+            });
+            const selection = _deps._walleModelSelectionForActiveSession(session);
+            return {
+              ok: true,
+              delivered: true,
+              model_id: selection.model_id || null,
+              model_provider: selection.model_provider || null,
+              model_registry_id: selection.model_registry_id || '',
+              model_provider_id: selection.model_provider_id || '',
+              model_pinned: !!selection.model_pinned,
+              cleared: !pref,
+            };
+          },
+        },
+      });
+      _deps._sendRemoteJson(res, _deps._remoteCommandRuntime.httpStatus(result), result);
+      return true;
+    }
+  } catch (err) {
+    // A write-lock-busy error (cold-Dropbox boot storm saturating the db-owner worker)
+    // must surface as a retryable 503, never the raw "SQLite write lock busy … <lock path>"
+    // string — that leaked to the phone as a red error banner after a restart.
+    const busy = _deps._writeLockBusyApiError(err);
+    if (busy) {
+      _deps._sendRemoteJson(res, busy.status, { ok: false, ...busy.body });
+    } else if (url.pathname === '/api/remote/messages' || url.pathname === '/api/remote/submissions') {
+      _deps._sendRemoteJson(res, 503, {
+        ok: false,
+        error: 'remote_command_auth_unavailable',
+        code: 'remote_command_auth_unavailable',
+      });
+    } else {
+      _deps._sendRemoteJson(res, 400, {
+        ok: false,
+        error: err && err.message ? err.message : 'remote_api_error',
+      });
+    }
+    return true;
+  }
+
+  return false;
+}
+
+async function _sendRemoteTerminalSubmission(req, sessionId, text, options = {}) {
+  _deps._ownerRecovery.assertAdmission(sessionId);
+  const captureTarget = session => _deps.remoteTerminalTarget.captureRemoteTerminalTarget(sessionId, session, _deps.sessions, _deps._terminalProcessGeneration);
+  const resolved = typeof _deps.rootTerminalInputGateway === 'undefined'
+    ? (() => {
+      const session = _deps.sessions.get(sessionId);
+      return { ok: true, canonical: false, session, target: captureTarget(session),
+        messageId: String(options.messageId || options.message_id || options.message?.id || '').trim(),
+        messageType: options.messageType || options.message_type || options.message?.type || 'session.send_message',
+        source: options.source };
+    })()
+    : _deps.rootTerminalInputGateway.resolveSubmission(sessionId, options, captureTarget);
+  if (!resolved.ok) return {
+    ok: false, error: 'root_permit_invalid', reason: resolved.reason || 'root_permit_invalid', retryable: false,
+  };
+  const initialSession = resolved.session;
+  const target = resolved.target;
+  const canonicalRoot = resolved.canonical === true;
+  const messageId = resolved.messageId,
+    deviceId = String(options.deviceId || options.device_id || options.message?.device_id || req?.ctmAuth?.deviceId || '').trim(),
+    messageType = resolved.messageType;
+  const rootJobLifetime = canonicalRoot ? _deps.rootDeliveryRuntime.getRootDeliveryJobLifetime(options.rootDeliveryPermit) : null;
+  const rootJobCurrent = () => !canonicalRoot || (rootJobLifetime && _deps.rootDeliveryRuntime.isRootDeliveryJobLifetimeCurrent(rootJobLifetime, sessionId, messageId)
+    && rootJobLifetime.databaseHandle === _deps.dbModule.getDb() && rootJobLifetime.instanceId === _deps._instanceIdentityAccess.getCachedInstanceId()
+    && rootJobLifetime.session === initialSession && _deps.sessions.get(sessionId) === initialSession && target.isCurrent());
+  if (canonicalRoot && !rootJobCurrent()) return { ok: false, error: 'root_permit_invalid', reason: 'root_permit_invalid', retryable: false };
+  const storeStatus = (id, status, details) => _deps._storeRemoteSubmissionStatus(sessionId, id, status, details, canonicalRoot ? rootJobLifetime : undefined);
+  let beforeMarker = '', startedAt = Date.now();
+  const submissionLabel = messageType === 'web.submit_prompt'
+    ? 'prompt'
+    : 'phone reply';
+  const runtimeInput = _deps._runtimeInputBaseForSession(sessionId, initialSession, {
+    inputId: options.runtimeInputId || options.runtime_input_id || (messageId ? `remote:${messageId}` : ''),
+    message: options.message,
+    messageId,
+    deviceId,
+    messageType,
+    mode: 'inline',
+    source: options.source || 'mobile',
+    text,
+    attachments: Array.isArray(options.body && options.body.attachments) ? options.body.attachments : [],
+    action: options.action || 'session.send_message',
+    metadata: {
+      transport: 'remote-terminal',
+      messageType,
+    },
+  });
+  const replacedResult = () => _deps.remoteTerminalTarget.terminalTargetReplacedResult(
+    messageId, options.source || 'remote-api', result => storeStatus(messageId, 'needs_attention', result));
+  if (messageId && !options.remoteSubmissionPreRecorded) {
+    const submission = await _deps._createRemoteSubmissionRecord(sessionId, text, {
+      messageId,
+      deviceId,
+      messageType,
+      source: options.source || 'remote-api',
+    });
+    if (!rootJobCurrent()) return replacedResult();
+    if (!_deps.promptSubmissionContract.isConfirmedSubmissionRecord(submission, { messageId, sessionId, messageType, text }, _deps.remoteRelayStore.remoteSubmissionConflict)) return Object.assign(_deps.promptSubmissionContract.unconfirmedRecordResult(), { submission_id: messageId, submission_status: 'blocked' });
+  }
+  if (!rootJobCurrent() || (target.session && target.ptyProcess && !target.isCurrent())) return replacedResult();
+  if (!options.runtimeInputPreRecorded) _deps._recordRuntimeInputAcceptedForSession(sessionId, initialSession, runtimeInput);
+  const blocker = _deps._remoteTerminalSubmissionBlocker(sessionId, initialSession, Date.now(), { text });
+  if (blocker) {
+    if (messageId) {
+      storeStatus(messageId, canonicalRoot ? 'needs_attention' : 'blocked', {
+        reason: blocker.reason || blocker.error || 'blocked',
+        message: blocker.message || `CTM could not deliver this ${submissionLabel}.`,
+        retryable: blocker.retryable === true,
+        source: options.source || 'remote-api',
+      });
+      if (!canonicalRoot) _deps._markQueueAutosendDirty(sessionId, blocker.reason || blocker.error);
+    }
+    _deps._recordRuntimeInputResultForSession(
+      sessionId,
+      initialSession,
+      runtimeInput,
+      canonicalRoot ? 'deferred' : _deps._runtimeInputFailureResultForError(blocker.error),
+      blocker.reason || blocker.error || 'blocked'
+    );
+    _deps.recordSessionDiagnostic(sessionId, 'remote-terminal-submit-blocked', blocker);
+    try {
+      _deps.telemetry.track('remote_terminal_submit_blocked', {
+        session_id: String(sessionId || '').slice(0, 8),
+        error: blocker.error || 'blocked',
+        reason: blocker.reason || '',
+      });
+    } catch {}
+    return messageId
+      ? { ...blocker, retryable: canonicalRoot ? false : blocker.retryable === true,
+        submission_id: messageId, submission_status: canonicalRoot ? 'needs_attention' : 'blocked' }
+      : blocker;
+  }
+  if (!rootJobCurrent() || !target.isCurrent()) return replacedResult();
+  // Acquire synchronously after the blocker so concurrent submits cannot interleave.
+  const attempt = _deps.remoteTerminalTarget.acquireRemoteTerminalAttempt(initialSession);
+  if (!attempt) return replacedResult();
+  try {
+    if (!rootJobCurrent() || !target.isExecutionCurrent(attempt)) return replacedResult();
+    beforeMarker = _deps._snapshotOutputMarker(initialSession);
+    const data = _deps._remoteTerminalSubmissionText(text);
+    const writePayload = _deps._remoteTerminalSubmissionWritePayload(initialSession, data);
+    const bracketedPaste = writePayload !== data;
+    // Read viewport only after admission; failure is weak evidence, not a refusal.
+    if (!rootJobCurrent() || !target.isExecutionCurrent(attempt)) return replacedResult();
+    const preSubmitRead = await _deps._getHeadlessViewportRead(sessionId, 700);
+    if (!rootJobCurrent() || !target.isExecutionCurrent(attempt)) return replacedResult();
+    const submittedWhileGenerating = preSubmitRead.ok
+      && _deps._providerActivelyGenerating(initialSession, _deps.stripAnsi(String(preSubmitRead.text || '')));
+    let beforeEnterMarker = '';
+    const writeResult = await _deps.promptSubmissionContract.executeTerminalWriteSequence({
+      payload: writePayload,
+      // Normalize every admission refusal for the write-sequence contract.
+      write: payload => canonicalRoot
+        ? _deps.rootTerminalInputGateway.writeRootInput({
+          permit: options.rootDeliveryPermit,
+          sessionId,
+          payload,
+          target,
+          attempt,
+          handleInput,
+        })
+        : _deps.remoteTerminalTarget.writeRemoteTerminalInput({
+          handleInput,
+          request: { auth: req.ctmAuth },
+          message: { id: sessionId, data: payload },
+          isTerminalTargetCurrent: target.isCurrent,
+          isTerminalAttemptCurrent: attempt.ownsInitialSession,
+        }),
+      onTextWritten: () => {
+        if (!rootJobCurrent() || !target.isExecutionCurrent(attempt)) return;
+        if (messageId) {
+          storeStatus(messageId, 'typed_to_pty', {
+            reason: 'text_written',
+            message: 'CTM typed this prompt into the terminal.',
+            source: options.source || 'remote-api',
+          });
+        }
+        _deps.recordSessionDiagnostic(sessionId, 'remote-terminal-submit-text', {
+          chars: data.length,
+          multiline: data.includes('\n'),
+          bracketedPaste,
+          enterDelayMs: _deps.REMOTE_TERMINAL_SUBMIT_DELAY_MS,
+        });
+      },
+      settle: async () => {
+        if (!rootJobCurrent() || !target.isExecutionCurrent(attempt)) return;
+        await _deps._waitForTerminalRenderSettle(initialSession, {
+          minMs: _deps.REMOTE_TERMINAL_SUBMIT_DELAY_MS,
+          maxMs: _deps.REMOTE_TERMINAL_SUBMIT_SETTLE_MAX_MS,
+          quietMs: _deps.REMOTE_TERMINAL_SUBMIT_SETTLE_QUIET_MS,
+        });
+        return rootJobCurrent() && target.isExecutionCurrent(attempt);
+      },
+      isLive: () => rootJobCurrent() && target.isExecutionCurrent(attempt) && _deps._isLiveTerminalSession(initialSession),
+      onBeforeEnter: () => {
+        if (rootJobCurrent() && target.isExecutionCurrent(attempt)) beforeEnterMarker = _deps._snapshotOutputMarker(initialSession);
+      },
+    });
+    const session = initialSession;
+    if (!rootJobCurrent() || target.wasReplaced() || !target.isExecutionCurrent(attempt)) return replacedResult();
+    if (!writeResult.ok) {
+      // A refused text write is retryable only when the underlying blocker is transient.
+      if (writeResult.error === 'terminal_input_refused') {
+        const innerReason = String(writeResult.reason || 'pty_unavailable');
+        const reason = `terminal_input_${innerReason}`;
+        const retryable = !canonicalRoot && innerReason !== 'read_only' && innerReason !== 'owner_mismatch';
+        // Text may already be present, so an Enter refusal cannot retry the whole prompt.
+        if (writeResult.stage === 'enter') {
+          const message = `The text reached the terminal, but CTM could not press Enter (${reason}).`;
+          if (messageId) {
+            storeStatus(messageId, 'needs_attention', {
+              reason: 'enter_refused_after_text',
+              retryable: false,
+              message,
+              source: options.source || 'remote-api',
+            });
+          }
+          _deps.recordSessionDiagnostic(sessionId, 'remote-terminal-submit-enter-refused', { reason });
+          _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'deferred', 'enter_refused_after_text');
+          return {
+            ok: false,
+            error: 'enter_refused_after_text',
+            reason,
+            retryable: false,
+            message,
+            submission_id: messageId || undefined,
+            submission_status: messageId ? 'needs_attention' : undefined,
+          };
+        }
+        const message = `CTM could not type into this terminal (${reason}).`;
+        const refusedStatus = canonicalRoot ? 'needs_attention' : 'blocked';
+        if (messageId) {
+          storeStatus(messageId, refusedStatus, {
+            reason,
+            retryable,
+            message,
+            source: options.source || 'remote-api',
+          });
+          if (!canonicalRoot) _deps._markQueueAutosendDirty(sessionId, reason);
+        }
+        _deps.recordSessionDiagnostic(sessionId, 'remote-terminal-submit-write-refused', { reason, retryable });
+        _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput,
+          canonicalRoot ? 'deferred' : 'rejected', reason);
+        return {
+          ok: false,
+          error: 'terminal_input_refused',
+          reason,
+          retryable,
+          message,
+          submission_id: messageId || undefined,
+          submission_status: messageId ? refusedStatus : undefined,
+        };
+      }
+      if (messageId) {
+        storeStatus(messageId, 'failed', {
+          reason: 'session_not_live_before_enter',
+          message: 'The text reached the terminal, but the session stopped before CTM could press Enter.',
+          source: options.source || 'remote-api',
+        });
+      }
+      _deps.recordSessionDiagnostic(sessionId, 'remote-terminal-submit-enter-skipped', { reason: 'session_not_live' });
+      _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', 'session_not_live_before_enter');
+      return {
+        ok: false,
+        error: 'session_not_live',
+        message: 'The text reached the terminal, but the session stopped before CTM could press Enter.',
+        submission_id: messageId || undefined,
+        submission_status: messageId ? 'failed' : undefined,
+      };
+    }
+    if (!rootJobCurrent() || !target.isExecutionCurrent(attempt)) return replacedResult();
+    if (messageId) {
+      storeStatus(messageId, 'observing', {
+        reason: 'enter_sent',
+        message: `CTM pressed Enter and is waiting for the agent to accept the ${submissionLabel}.`,
+        source: options.source || 'remote-api',
+      });
+      if (!rootJobCurrent() || !target.isExecutionCurrent(attempt)) return replacedResult();
+      _deps._scheduleRemoteSubmissionObservation({
+        sessionId,
+        messageId,
+        text: data,
+        beforeMarker,
+        beforeEnterMarker,
+        startedAt,
+        auth: canonicalRoot ? null : req.ctmAuth,
+        rootJobLifetime: canonicalRoot ? rootJobLifetime : undefined,
+        source: options.source || 'remote-api',
+        submittedWhileGenerating,
+        preSubmitReadOk: preSubmitRead.ok,
+        preSubmitReadReason: preSubmitRead.reason || '',
+      });
+    }
+    if (!rootJobCurrent() || !target.isExecutionCurrent(attempt)) return replacedResult();
+    if (!options.confirmDelivery) {
+      _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'delivered', 'enter_sent');
+    }
+    _deps.recordSessionDiagnostic(sessionId, 'remote-terminal-submit-enter', { enterDelayMs: _deps.REMOTE_TERMINAL_SUBMIT_DELAY_MS });
+    return {
+      ok: true,
+      delivered: true,
+      submitted: true,
+      submission_id: messageId || undefined,
+      submission_status: messageId ? 'observing' : undefined,
+    };
+  } finally {
+    attempt.release();
+  }
+}
+
+async function _selectRemoteTerminalChoiceBody(req, sessionId, body = {}, message = {}, options = {}) {
+  const session = _deps.sessions.get(sessionId);
+  if (!session) return { ok: false, error: 'session_not_found' };
+  if (!_deps._isLiveTerminalSession(session)) return { ok: false, error: 'session_not_live', message: 'This session is not accepting terminal input.' };
+  const choiceCallerIsRemoteHttp = !!(req && req.ctmAuth);
+  const choiceInputWs = choiceCallerIsRemoteHttp ? { auth: req.ctmAuth } : req;
+  const choiceInputOptions = { authenticatedRemote: choiceCallerIsRemoteHttp }, targetValue = String(body.value ?? body.index ?? '').trim();
+  const targetLabel = String(body.label || '').trim();
+  const submitOnly = body.submit === true || String(body.action || '').toLowerCase() === 'submit';
+  if (!submitOnly && !targetValue && !targetLabel) {
+    return { ok: false, error: 'invalid_choice', message: 'No choice option was specified.' };
+  }
+  const choiceText = typeof body.text === 'string' ? body.text : ''; // typed after a free-text option is selected
+  if (choiceText.length > 4000) return { ok: false, error: 'invalid_choice_text', message: 'The reply is too long.' };
+  const expectedFingerprint = String(body.fingerprint || '').trim();
+  const runtimeInput = _deps._runtimeInputBaseForSession(sessionId, session, {
+    inputId: message.id ? `remote:${message.id}` : '',
+    message,
+    messageId: message.id,
+    deviceId: message.device_id || req.ctmAuth?.deviceId || '',
+    messageType: message.type || 'session.select_choice',
+    mode: 'inline',
+    source: 'mobile',
+    text: targetLabel || targetValue || (submitOnly ? 'submit' : ''),
+    action: 'session.select_choice',
+    appendUserInputEvent: false,
+    metadata: {
+      value: targetValue,
+      label: targetLabel,
+      submitOnly,
+      expectedFingerprint,
+    },
+  });
+  _deps._recordRuntimeInputAcceptedForSession(sessionId, session, runtimeInput);
+
+  const inputGuardFailure = () => {
+    if (typeof options.validateBeforeInput !== 'function') return null;
+    try {
+      const result = options.validateBeforeInput();
+      if (result == null || result === true || result.ok === true) return null;
+      if (result && result.ok === false) return result;
+    } catch {}
+    return { ok: false, error: 'session_not_live' };
+  };
+
+  const read = await _deps._getHeadlessTextRead(sessionId, 700);
+  const initialGuardFailure = inputGuardFailure();
+  if (initialGuardFailure) return initialGuardFailure;
+  if (!read.ok) {
+    // WE COULD NOT SEE — this is not proof there is no menu. Return before any repair logic; an
+    // unreadable screen is not evidence of anything.
+    _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', 'choice_read_unavailable');
+    _deps.recordSessionDiagnostic(sessionId, 'remote-choice-select-blocked', {
+      reason: 'choice_read_unavailable',
+      readReason: read.reason,
+      messageId: message.id || '',
+    });
+    return {
+      ok: false,
+      error: 'choice_read_unavailable',
+      message: 'CTM could not read this terminal — try again.',
+    };
+  }
+  const screen = read.text;
+  const menu = _deps.terminalChoice.extractTerminalChoice(screen);
+  if (!menu) {
+    _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', 'choice_prompt_not_found');
+    _deps.recordSessionDiagnostic(sessionId, 'remote-choice-select-blocked', {
+      reason: 'choice_prompt_not_found',
+      hasScreen: !!screen.trim(),
+      messageId: message.id || '',
+    });
+    _deps._resumeChoiceClickRepair(sessionId, session, screen);
+    return {
+      ok: false,
+      error: 'choice_prompt_not_found',
+      message: 'CTM could not find an active choice menu in this terminal.',
+    };
+  }
+  if (expectedFingerprint && menu.fingerprint !== expectedFingerprint) {
+    // The phone (cleaned tail) and the server (raw headless grid) can legitimately
+    // capture a different trailing-option SET for the SAME live menu — Claude's
+    // AskUserQuestion widget appends layout-sensitive options ("Type something",
+    // "Chat about this") behind a divider, and the phone parses the divider-stripped
+    // tail while the server parses the raw grid, so a row-window includes/excludes a
+    // trailing option and the set fingerprints differ. A strict fingerprint match
+    // rejected every such tap as stale. Reconcile the SPECIFIC tapped option instead:
+    // if it is still present in the live menu by value+label, treat it as the same
+    // menu and proceed (the value/label keystroke match below + the post-navigation
+    // closed-loop verify are the real safety net). Submit-only taps have no single
+    // option to reconcile, so they keep the strict check.
+    const reconciled = !submitOnly
+      && _deps.terminalChoice.tappedOptionStillPresent(menu, targetValue, targetLabel);
+    if (!reconciled) {
+      _deps.recordSessionDiagnostic(sessionId, 'remote-choice-select-blocked', {
+        reason: 'choice_stale',
+        expected: expectedFingerprint,
+        actual: menu.fingerprint,
+        messageId: message.id || '',
+      });
+      _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', 'choice_stale');
+      return {
+        ok: false,
+        error: 'choice_stale',
+        message: 'This menu changed before your tap arrived. CTM refreshed it — try again.',
+        fingerprint: menu.fingerprint,
+      };
+    }
+    _deps.recordSessionDiagnostic(sessionId, 'remote-choice-fingerprint-soft-mismatch', {
+      expected: expectedFingerprint,
+      actual: menu.fingerprint,
+      value: targetValue,
+      label: targetLabel.slice(0, 80),
+      messageId: message.id || '',
+    });
+  }
+
+  if (submitOnly) {
+    const submitPlan = _deps.terminalChoice.planFormSubmitKeystrokes(menu);
+    if (!submitPlan) {
+      _deps.recordSessionDiagnostic(sessionId, 'remote-choice-submit-blocked', {
+        reason: menu.requiresSubmit ? 'choice_form_no_checked_option' : 'choice_not_submit_form',
+        messageId: message.id || '',
+      });
+      _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', menu.requiresSubmit ? 'choice_form_no_checked_option' : 'choice_not_submit_form');
+      return {
+        ok: false,
+        error: menu.requiresSubmit ? 'choice_form_no_checked_option' : 'choice_not_submit_form',
+        message: menu.requiresSubmit
+          ? 'Choose an option before submitting this form.'
+          : 'The active choice menu does not have a separate submit step.',
+      };
+    }
+    for (const frame of submitPlan.frames) {
+      const guardFailure = inputGuardFailure();
+      if (guardFailure) return guardFailure;
+      handleInput(choiceInputWs, { id: sessionId, data: frame }, choiceInputOptions);
+      if (frame.startsWith('\x1b')) {
+        await new Promise((resolve) => setTimeout(resolve, _deps.SELECT_CHOICE_FRAME_GAP_MS));
+      }
+    }
+    _deps.recordSessionDiagnostic(sessionId, 'remote-choice-submit', {
+      strategy: submitPlan.strategy,
+      checkedValues: menu.options.filter((option) => option.checked).map((option) => option.value),
+      source: 'remote-api',
+      messageId: message.id || '',
+    });
+    _deps._recordRuntimeInputResultForSession(sessionId, _deps.sessions.get(sessionId) || session, runtimeInput, 'delivered', 'choice_submit');
+    return {
+      ok: true,
+      delivered: true,
+      submitted: true,
+      strategy: submitPlan.strategy,
+      checkedValues: menu.options.filter((option) => option.checked).map((option) => option.value),
+    };
+  }
+
+  const plan = _deps.terminalChoice.planChoiceKeystrokes({
+    options: menu.options,
+    selectedIndex: menu.selectedIndex,
+    targetValue,
+    targetLabel,
+  });
+  if (!plan) {
+    _deps._recordRuntimeInputResultForSession(sessionId, session, runtimeInput, 'rejected', 'choice_option_not_found');
+    return {
+      ok: false,
+      error: 'choice_option_not_found',
+      message: 'CTM could not match that option against the live menu.',
+    };
+  }
+
+  // Move the highlight (arrows) or pre-type the number, leaving Enter for last.
+  for (const frame of plan.navFrames) {
+    const guardFailure = inputGuardFailure();
+    if (guardFailure) return guardFailure;
+    handleInput(choiceInputWs, { id: sessionId, data: frame }, choiceInputOptions);
+    if (plan.navFrames.length > 1 || frame.startsWith('\x1b')) {
+      await new Promise((resolve) => setTimeout(resolve, _deps.SELECT_CHOICE_FRAME_GAP_MS));
+    }
+  }
+
+  // Closed-loop verify: for arrow navigation, confirm the target is now highlighted
+  // before committing, so a miscount never confirms the wrong option.
+  if (plan.strategy === 'arrows' && plan.navFrames.length) {
+    await _deps._waitForTerminalRenderSettle(_deps.sessions.get(sessionId), { minMs: 80, maxMs: 600, quietMs: 120 });
+    const verifyRead = await _deps._getHeadlessTextRead(sessionId, 700);
+    if (!verifyRead.ok) {
+      // An unreadable screen is not proof the option did not land. Stay conservative — never
+      // commit — but report unverified (choice_read_unavailable) rather than choice_verify_failed
+      // so the client retries instead of giving up.
+      _deps.recordSessionDiagnostic(sessionId, 'remote-choice-select-blocked', {
+        reason: 'choice_read_unavailable',
+        readReason: verifyRead.reason,
+        stage: 'verify',
+        messageId: message.id || '',
+      });
+      _deps._recordRuntimeInputResultForSession(sessionId, _deps.sessions.get(sessionId) || session, runtimeInput, 'rejected', 'choice_read_unavailable');
+      return {
+        ok: false,
+        error: 'choice_read_unavailable',
+        message: 'CTM could not read this terminal — try again.',
+      };
+    }
+    const after = _deps.terminalChoice.extractTerminalChoice(verifyRead.text);
+    const landed = after && after.options[plan.targetOrdinal] && after.options[plan.targetOrdinal].selected;
+    if (!landed) {
+      _deps.recordSessionDiagnostic(sessionId, 'remote-choice-select-blocked', {
+        reason: 'choice_verify_failed',
+        targetOrdinal: plan.targetOrdinal,
+        delta: plan.delta,
+        messageId: message.id || '',
+      });
+      _deps._recordRuntimeInputResultForSession(sessionId, _deps.sessions.get(sessionId) || session, runtimeInput, 'rejected', 'choice_verify_failed');
+      return {
+        ok: false,
+        error: 'choice_verify_failed',
+        message: 'CTM could not confirm the highlighted option, so nothing was selected. Try again.',
+        fingerprint: after?.fingerprint || '',
+      };
+    }
+  }
+
+  const live = _deps.sessions.get(sessionId);
+  if (!_deps._isLiveTerminalSession(live)) {
+    _deps._recordRuntimeInputResultForSession(sessionId, live || session, runtimeInput, 'rejected', 'session_not_live_before_choice_commit');
+    return {
+      ok: false,
+      error: 'session_not_live',
+      message: 'The session stopped before CTM could confirm your choice.',
+    };
+  }
+  const commitGuardFailure = inputGuardFailure();
+  if (commitGuardFailure) return commitGuardFailure;
+  // Enter commits the option; for a free-text option the typed reply follows once the input has opened, then Enter.
+  const typedReply = choiceText.replace(/[\x00-\x1f\x7f]+/g, ' ').trim();
+  const typeReply = typedReply && menu.options[plan.targetOrdinal]?.freeText;
+  const commitFrames = typeReply ? [plan.commitFrame, typedReply, _deps.terminalChoice.ENTER] : [plan.commitFrame];
+  for (const [i, data] of commitFrames.entries()) { if (i === 1) await _deps._waitForTerminalRenderSettle(_deps.sessions.get(sessionId), { minMs: 80, maxMs: 600, quietMs: 120 }); handleInput(choiceInputWs, { id: sessionId, data }, choiceInputOptions); }
+  _deps.recordSessionDiagnostic(sessionId, 'remote-choice-select', {
+    value: targetValue,
+    label: targetLabel.slice(0, 80),
+    strategy: plan.strategy,
+    delta: plan.delta ?? null,
+    source: 'remote-api',
+    messageId: message.id || '',
+  });
+  _deps._recordRuntimeInputResultForSession(sessionId, live || session, runtimeInput, 'delivered', 'choice_committed');
+  return {
+    ok: true,
+    delivered: true,
+    requiresSubmit: !!menu.requiresSubmit,
+    submitted: !menu.requiresSubmit,
+    value: targetValue || menu.options[plan.targetOrdinal]?.value || '',
+    label: targetLabel || menu.options[plan.targetOrdinal]?.label || '',
+    strategy: plan.strategy,
+  };
+}
+
+async function _observeRemoteSubmission(context, attempt = 0) {
+  const { sessionId, messageId, text, beforeMarker, beforeEnterMarker, startedAt } = context;
+  const isCurrent = () => _deps._remoteSubmissionObservationCurrent(context);
+  const storeStatus = (status, details) => _deps._storeRemoteSubmissionStatus(sessionId, messageId, status, details, context.rootJobLifetime);
+  if (!isCurrent()) return;
+  const current = await _deps._readPromptSubmissionByMessageId(messageId);
+  if (!isCurrent() || !current || _deps.REMOTE_SUBMISSION_FINAL_STATUSES.has(current.status)) return;
+  if (context.rootJobLifetime !== undefined && (current.message_id !== messageId
+      || current.session_id !== sessionId || current.message_type !== 'web.submit_prompt')) return;
+  const canonicalPrivateWeb = _deps._isWebPromptSubmission(current) && String(current.message_id || messageId).startsWith('remote-v2:');
+  if (canonicalPrivateWeb && !context.rootJobLifetime) return;
+  const submissionSource = context.source || current.result?.source || 'remote-api';
+  const submissionLabel = _deps._isWebPromptSubmission(current) ? 'prompt' : 'phone reply';
+
+  const session = context.rootJobLifetime ? context.rootJobLifetime.session : _deps.sessions.get(sessionId);
+  if (!_deps._isLiveTerminalSession(session)) {
+    await storeStatus('failed', {
+      reason: 'session_exited_during_observation',
+      message: `The session exited before CTM could confirm this ${submissionLabel}.`,
+      attempts: attempt,
+      source: submissionSource,
+      evidenceSource: 'session-lifecycle',
+    });
+    if (!isCurrent()) return;
+    return;
+  }
+
+  // The status-bus busy stamp is in memory; the durable match below resolves transcript files on
+  // the read pool, which can queue for minutes under load (2026-10-21: a prompt the agent took up
+  // 0.2 s after Enter stayed "Still confirming..." for 90 s behind resolveSessionFiles). An idle
+  // submission is confirmed by the busy stamp the moment it exists. Mid-turn submissions are not:
+  // the session was busy anyway (D-3).
+  const submittedWhileGenerating = !!context.submittedWhileGenerating;
+  if (!submittedWhileGenerating && Number(session?._lastBusyStatusAt || 0) >= Number(startedAt || 0)) {
+    storeStatus('response_started', {
+      reason: 'session_marked_busy_after_submit',
+      message: `The agent started working after the ${submissionLabel} was submitted.`,
+      attempts: attempt,
+      source: submissionSource,
+      evidenceSource: 'status-bus',
+    });
+    return;
+  }
+
+  const durableMatch = await _deps._remoteSubmissionDurablePromptMatch(sessionId, text, {
+    minTimestampMs: Number(startedAt || 0) || 0,
+    timestampToleranceMs: 120000,
+  });
+  if (!isCurrent()) return;
+  if (durableMatch.matched) {
+    storeStatus('durable_user_message_seen', {
+      reason: durableMatch.evidenceSource === 'transcript-tail' ? 'transcript_tail_match' : 'prompt_index_match',
+      message: `The agent transcript now contains this ${submissionLabel}.`,
+      attempts: attempt,
+      source: submissionSource,
+      evidenceSource: durableMatch.evidenceSource || 'message-index',
+    });
+    return;
+  }
+
+  const rows = await _deps._getHeadlessRows(sessionId, 900);
+  if (!isCurrent()) return;
+  const rowsKnown = Array.isArray(rows);
+  // D-3: a prompt typed while the agent was already generating is confirmed
+  // ONLY by its on-screen echo or a durable transcript row (checked above) —
+  // "status bus went busy" and "an agent progress line appeared" are both
+  // true anyway mid-turn, so they cannot be used as delivery evidence here.
+  // Fix round 1, finding 3: the tri-state ('composer'/'echoed'/'absent', ❯-aware)
+  // drives ONLY the mid-turn path below. The idle path's `promptStillVisible`
+  // (fed into markerEvidence, enter-retry, and needs_attention) must keep using
+  // the byte-identical-to-base legacyPromptDetail so a prompt stuck at Claude's
+  // idle ❯ composer still resolves the pre-WP-3 way (waiting_for_confirmation →
+  // needs_attention), never a false response_started from the new glyph handling.
+  const promptState = rowsKnown
+    ? _deps.remoteSubmissionObserver.terminalSubmittedPromptState(rows, text)
+    : 'absent';
+  const legacyDetail = rowsKnown
+    ? _deps.remoteSubmissionObserver.legacyPromptDetail(rows, text)
+    : { activePromptVisible: false, agentProgressAfterPrompt: false };
+  const promptStillVisible = submittedWhileGenerating
+    ? promptState === 'composer'
+    : legacyDetail.activePromptVisible;
+  const markerNow = _deps._snapshotOutputMarker(session);
+  const markerAcceptance = _deps.submissionAck.markerEvidence({
+    sessionAlive: true,
+    beforeMarker,
+    beforeEnterMarker,
+    markerNow,
+    promptStillVisible,
+  });
+  const elapsedMs = Date.now() - Number(startedAt || Date.now());
+
+  if (!isCurrent()) return;
+  _deps.recordSessionDiagnostic(sessionId, 'remote-submission-observe-state', {
+    messageId,
+    attempt,
+    elapsedMs,
+    beforeMarker,
+    beforeEnterMarker,
+    markerNow,
+    promptState,
+    legacyActivePromptVisible: !!legacyDetail.activePromptVisible,
+    legacyAgentProgressAfterPrompt: !!legacyDetail.agentProgressAfterPrompt,
+    markerAccepted: !!markerAcceptance.accepted,
+    markerReason: markerAcceptance.reason || '',
+    rowsKnown,
+    enterRetried: !!context.enterRetried,
+    submittedWhileGenerating,
+    // Minor 8: surface whether the mid-turn pre-submit read succeeded, so a
+    // job that silently fell back to the idle ladder (a failed viewport read
+    // treated `submittedWhileGenerating` as false) is visible in diagnostics.
+    preSubmitReadOk: context.preSubmitReadOk !== undefined ? !!context.preSubmitReadOk : undefined,
+    preSubmitReadReason: context.preSubmitReadReason || '',
+  });
+
+  if (submittedWhileGenerating) {
+    // Finding 1: mid-turn accepted-evidence is durable (checked above) →
+    // echoed → composer/Enter-retry (below) → unconfirmed. NO busy-stamp
+    // rung, NO agent-progress rung, and NO marker-acceptance rung — the
+    // marker fires whenever `_outputBytesCounter` moved, which the agent's
+    // own streaming does constantly mid-turn, so it is not delivery evidence
+    // for this path at all.
+    if (promptState === 'echoed') {
+      storeStatus('queued_by_agent', {
+        reason: 'agent_queue_echo',
+        message: 'The agent queued this prompt for its next turn.',
+        attempts: attempt,
+        source: submissionSource,
+        evidenceSource: 'terminal-tail',
+      });
+      return;
+    }
+  } else {
+    if (legacyDetail.agentProgressAfterPrompt && elapsedMs >= 500) {
+      storeStatus('response_started', {
+        reason: 'terminal_progress_after_prompt',
+        message: `The terminal shows agent progress after the ${submissionLabel}.`,
+        attempts: attempt,
+        source: submissionSource,
+        evidenceSource: 'terminal-tail',
+      });
+      return;
+    }
+
+    if (markerAcceptance.accepted && elapsedMs >= 2000) {
+      storeStatus('accepted_by_terminal', {
+        reason: markerAcceptance.reason,
+        message: `The terminal advanced after CTM pressed Enter for this ${submissionLabel}.`,
+        attempts: attempt,
+        source: submissionSource,
+        evidenceSource: 'terminal-tail',
+      });
+      return;
+    }
+  }
+
+  // S-2 (final fix wave): mid-turn, the agent's own streaming moves the
+  // output marker constantly, so gating the retry on `markerNow ===
+  // beforeEnterMarker` (the idle rule -- "nothing happened since Enter")
+  // never holds and the retry rung is unreachable; a mid-turn composer
+  // re-check has no such marker-stillness signal to offer anyway. Gate the
+  // mid-turn case on the tri-state read (`promptState === 'composer'`) and
+  // elapsed time alone. The idle ladder's marker-stillness gate is
+  // byte-identical to base.
+  const enterRetryEligible = submittedWhileGenerating
+    ? promptState === 'composer'
+    : (rowsKnown && promptStillVisible && markerNow === beforeEnterMarker);
+  if (
+    beforeEnterMarker
+    && !canonicalPrivateWeb
+    && enterRetryEligible
+    && !context.enterRetried
+    && elapsedMs >= _deps.REMOTE_TERMINAL_ENTER_RETRY_MIN_ELAPSED_MS
+  ) {
+  const retrySession = context.rootJobLifetime ? context.rootJobLifetime.session : _deps.sessions.get(sessionId);
+    if (_deps._isLiveTerminalSession(retrySession)) {
+      const retryBeforeEnterMarker = _deps._snapshotOutputMarker(retrySession);
+      handleInput({ auth: context.auth || {} }, { id: sessionId, data: '\r' }, { authenticatedRemote: true });
+      storeStatus('observing', {
+        reason: 'enter_retry_sent',
+        message: `The ${submissionLabel} was still visible at the prompt, so CTM pressed Enter one more time and is waiting for confirmation.`,
+        attempts: attempt + 1,
+        source: submissionSource,
+        evidenceSource: 'observer',
+      });
+      if (!isCurrent()) return;
+      _deps.recordSessionDiagnostic(sessionId, 'remote-terminal-submit-enter-retry', {
+        messageId,
+        attempt,
+        elapsedMs,
+        beforeEnterMarker,
+        retryBeforeEnterMarker,
+      });
+      if (!isCurrent()) return;
+      _deps._scheduleRemoteSubmissionObservation({
+        ...context,
+        beforeEnterMarker: retryBeforeEnterMarker,
+        enterRetried: true,
+        retryStartedAt: Date.now(),
+      }, attempt + 1);
+      return;
+    }
+    if (!isCurrent()) return;
+    _deps.recordSessionDiagnostic(sessionId, 'remote-terminal-submit-enter-retry-skipped', {
+      messageId,
+      reason: 'session_not_live',
+      elapsedMs,
+    });
+  }
+
+  if (rowsKnown && promptStillVisible && elapsedMs >= 3500) {
+    storeStatus('needs_attention', {
+      reason: 'prompt_still_visible_after_enter',
+      message: `CTM typed this ${submissionLabel}, but the terminal did not show a post-Enter transition and it still appears at the prompt.`,
+      attempts: attempt,
+      source: submissionSource,
+      evidenceSource: 'terminal-tail',
+    });
+    return;
+  }
+
+  if (attempt < _deps.REMOTE_SUBMISSION_OBSERVE_DELAYS_MS.length) {
+    storeStatus('observing', {
+      reason: promptStillVisible ? 'prompt_visible_waiting_for_agent' : 'waiting_for_confirmation',
+      message: `CTM delivered the ${submissionLabel} and is waiting for the agent transcript to confirm it.`,
+      attempts: attempt + 1,
+      source: submissionSource,
+      evidenceSource: 'observer',
+    });
+    _deps._scheduleRemoteSubmissionObservation(context, attempt + 1);
+    return;
+  }
+
+  const unconfirmed = _deps.remoteSubmissionObserver.unconfirmedSubmissionResult({ promptStillVisible, submissionLabel });
+  storeStatus('needs_attention', {
+    ...unconfirmed,
+    attempts: attempt,
+    source: submissionSource,
+    evidenceSource: 'observer',
+  });
+}
+module.exports = {
+  configure,
+  handleRemoteApi,
+  _sendRemoteTerminalSubmission,
+  _selectRemoteTerminalChoiceBody,
+  _observeRemoteSubmission,
+};