feat(ios): W3 UI layer + integration CI + ntfy docs

T-iOS-11: TerminalScreen/KeyBar/TerminalViewModel + KeyByteMap (byte-for-byte keybar.ts, arrows excluded from UIKeyCommand to preserve DECCKM)
T-iOS-12: PairingScreen/VM — confirm-before-network (zero-call assertions), §5.4 four-tier warnings, Host construction per contract ruling
T-iOS-13: SessionListScreen/VM — Tunables-paced polling with leak-free teardown, optimistic kill+rollback, pending via overlay (LiveSessionInfo has no pending field)
T-iOS-14: GateBanner/PlanGateSheet/AwayDigestView/GateViewModel — three-way mapping from SessionCore Affordance single source, tap-epoch guard, per-epoch haptics
T-iOS-16: IntegrationTests vs real Node server (10 tests: origin guards, mirror, kill-close vs exit-frame differential, 16MiB+ESC/C0 replay) + ios.yml own-sources coverage gate (red-once demoed)
T-iOS-17: ios/README.md ntfy chapter (read-only verification, file:line cites)
Verified: 224 unit + 10 integration tests green; 5/5 semantic spot-checks; zero Owns violations

ios/App/WebTerm/ViewModels/TerminalViewModel.swift

@@ -0,0 +1,301 @@
+import Foundation
+import Observation
+import SessionCore
+import WireProtocol
+
+/// Terminal screen state (T-iOS-11, plan §3.5): consumes the engine's
+/// `SessionEvent` stream on the MainActor and turns it into UI state — output
+/// forwarded to SwiftTerm, connection banner, non-retryable failure copy and
+/// the read-only exit state. All outbound traffic (key bar, hardware key
+/// commands, SwiftTerm delegate) funnels through here into ONE ordered queue.
+///
+/// Testability / stream-sharing decision (documented per task brief):
+/// `engine.events` is a single-consumer `AsyncStream`, and GateViewModel
+/// (T-iOS-14) must eventually observe `.gate`/`.digest` from the SAME stream.
+/// So the events stream is injected SEPARATELY from the engine: today callers
+/// pass `engine.events` verbatim (tests do exactly that, over
+/// `TestSupport.FakeTransport`); the T-iOS-15 wiring may pass a fan-out branch
+/// instead without touching this class.
+///
+/// Swift 6 strict concurrency: the class is `@MainActor`, the terminal sink is
+/// `@MainActor`-typed — `feed()` off the main actor cannot compile.
+@MainActor
+@Observable
+final class TerminalViewModel {
+    // MARK: - UI state model
+
+    /// Connection banner state (mirrors the web client's status line:
+    /// public/terminal-session.ts `SessionStatus`).
+    enum ConnectionBanner: Equatable {
+        case none
+        case connecting
+        /// Retry `attempt` fires after `next` (ReconnectMachine ladder 1s→30s).
+        case reconnecting(attempt: Int, next: Duration)
+    }
+
+    /// Which terminal the user is looking at: a live one, a dead-for-good one
+    /// (non-retryable failure), or a finished one (read-only).
+    enum TerminalPhase: Equatable {
+        case live
+        /// Non-retryable terminal failure — actionable copy instead of a spinner.
+        case failed(message: String)
+        /// The shell exited; the terminal stays readable but accepts no input.
+        case exited(code: Int, reason: String?)
+    }
+
+    /// Actionable copy for `.failed(.replayTooLarge)` (plan §3.2 / §3.2.1
+    /// coupling warning): reconnecting would deterministically fail forever,
+    /// so the user must change a knob, not wait.
+    static let replayTooLargeMessage =
+        "服务器 scrollback 超过客户端上限，请调低 SCROLLBACK_BYTES 或调高客户端上限"
+
+    private(set) var banner: ConnectionBanner = .none
+    private(set) var phase: TerminalPhase = .live
+    /// Server-adopted session id (ALWAYS the server-issued one — persisting it
+    /// per host is the T-iOS-15 wiring's job via `LastSessionStore`).
+    private(set) var sessionId: UUID?
+
+    /// Read-only = no input reaches the PTY (exit / terminal failure). Resize
+    /// is NOT gated here — the engine owns terminal-state dropping.
+    var isReadOnly: Bool { phase != .live }
+
+    /// Single render input for `ReconnectBanner`: terminal phases win over
+    /// transient connection states.
+    var bannerModel: ReconnectBanner.Model? {
+        switch phase {
+        case .failed(let message):
+            return .failed(message: message)
+        case .exited(let code, let reason):
+            return .exited(code: code, reason: reason)
+        case .live:
+            break
+        }
+        switch banner {
+        case .none:
+            return nil
+        case .connecting:
+            return .connecting
+        case .reconnecting(let attempt, let next):
+            return .reconnecting(attempt: attempt, retryIn: next)
+        }
+    }
+
+    // MARK: - Dependencies & plumbing (not observed)
+
+    @ObservationIgnored private let engine: SessionEngine
+    @ObservationIgnored private let events: AsyncStream<SessionEvent>
+    @ObservationIgnored private var consumeTask: Task<Void, Never>?
+    /// Where output bytes go (SwiftTerm's `feed(text:)`). `@MainActor`-typed:
+    /// feeding off the main actor is a compile error.
+    @ObservationIgnored private var terminalSink: (@MainActor (String) -> Void)?
+    /// Output that arrived before the SwiftTerm view existed; flushed in order
+    /// the moment the sink attaches (replay must never be dropped).
+    @ObservationIgnored private var pendingOutput: [String] = []
+    /// Ordered outbound queue: UIKit callbacks are synchronous, `engine.send`
+    /// is async — one pump task preserves submission order (two quick key taps
+    /// must never race each other onto the wire).
+    @ObservationIgnored private var sendQueue: [ClientMessage] = []
+    @ObservationIgnored private var isPumping = false
+
+    // MARK: - Test-visible diagnostics & deterministic barriers (internal)
+
+    /// Events applied so far — `waitUntilProcessed` barrier counter.
+    @ObservationIgnored private(set) var processedEventCount = 0
+    /// Sends handed to the engine so far — `waitUntilForwarded` barrier counter.
+    @ObservationIgnored private(set) var forwardedSendCount = 0
+    /// Input dropped because the terminal is read-only (exit/failed).
+    @ObservationIgnored private(set) var droppedReadOnlyInputCount = 0
+    /// Test tap, called after each event is applied (state already coherent).
+    @ObservationIgnored var onEventApplied: (@MainActor (SessionEvent) -> Void)?
+
+    private struct CountWaiter {
+        let target: Int
+        let continuation: CheckedContinuation<Void, Never>
+    }
+
+    @ObservationIgnored private var eventWaiters: [CountWaiter] = []
+    @ObservationIgnored private var sendWaiters: [CountWaiter] = []
+
+    // MARK: - Lifecycle
+
+    /// - Parameters:
+    ///   - engine: send-side dependency (`send` only — `open`/`close` belong to
+    ///     the T-iOS-15 wiring that constructs the engine).
+    ///   - events: the event stream to consume; pass `engine.events` unless a
+    ///     fan-out branch is needed (see type doc).
+    init(engine: SessionEngine, events: AsyncStream<SessionEvent>) {
+        self.engine = engine
+        self.events = events
+    }
+
+    /// Begin consuming events. Idempotent — a second call is a no-op (the
+    /// stream has exactly one consumer).
+    func start() {
+        guard consumeTask == nil else { return }
+        consumeTask = Task { [weak self] in
+            guard let events = self?.events else { return }
+            for await event in events {
+                guard let self else { return }
+                self.apply(event)
+            }
+            self?.releaseAllWaiters() // stream over — never leave a test hanging
+        }
+    }
+
+    /// Stop consuming (screen torn down). Does NOT close the engine — detach
+    /// vs. keep-running is the T-iOS-15 lifecycle owner's call.
+    func stop() {
+        consumeTask?.cancel()
+        consumeTask = nil
+        releaseAllWaiters()
+    }
+
+    // MARK: - Terminal output sink
+
+    /// Attach the SwiftTerm feed target. Buffered output (anything that
+    /// arrived before the view existed) flushes immediately, in order.
+    func attachTerminalSink(_ sink: @escaping @MainActor (String) -> Void) {
+        terminalSink = sink
+        let buffered = pendingOutput
+        pendingOutput = []
+        for chunk in buffered {
+            sink(chunk)
+        }
+    }
+
+    // MARK: - Outbound (KeyBar / UIKeyCommand / SwiftTerm delegate)
+
+    /// Key-bar or hardware key press: bytes resolved through `KeyByteMap`
+    /// (the single source of truth — plan §7 T-iOS-11).
+    func send(key: KeyByteMap.Key) {
+        sendInput(KeyByteMap.bytes(for: key))
+    }
+
+    /// Raw input bytes, verbatim (invariant #9 — no content filtering).
+    /// Dropped (and counted) while the terminal is read-only.
+    func sendInput(_ data: String) {
+        guard !isReadOnly else {
+            droppedReadOnlyInputCount += 1
+            return
+        }
+        enqueueSend(.input(data: data))
+    }
+
+    /// Terminal geometry changed (SwiftTerm `sizeChanged`). Always forwarded —
+    /// the engine validates bounds and owns terminal-state dropping.
+    func sendResize(cols: Int, rows: Int) {
+        enqueueSend(.resize(cols: cols, rows: rows))
+    }
+
+    // MARK: - Event application (single consumer, MainActor)
+
+    private func apply(_ event: SessionEvent) {
+        switch event {
+        case .connection(let state):
+            applyConnection(state)
+        case .adopted(let id):
+            sessionId = id // ALWAYS adopt the server-issued id
+        case .output(let data):
+            deliverOutput(data)
+        case .exited(let code, let reason):
+            phase = .exited(code: code, reason: reason)
+        case .gate, .telemetry, .digest:
+            break // GateViewModel's domain (T-iOS-14; wired in T-iOS-15)
+        }
+        processedEventCount += 1
+        onEventApplied?(event)
+        resumeEventWaiters()
+    }
+
+    private func applyConnection(_ state: ConnectionState) {
+        switch state {
+        case .connecting:
+            banner = .connecting
+        case .connected:
+            banner = .none
+        case .reconnecting(let attempt, let next):
+            banner = .reconnecting(attempt: attempt, next: next)
+        case .closed:
+            banner = .none // deliberate end; exit/failure phase (if any) stays
+        case .failed(.replayTooLarge):
+            banner = .none
+            phase = .failed(message: Self.replayTooLargeMessage)
+        }
+    }
+
+    private func deliverOutput(_ data: String) {
+        guard let terminalSink else {
+            pendingOutput = pendingOutput + [data]
+            return
+        }
+        terminalSink(data)
+    }
+
+    // MARK: - Ordered send pump
+
+    private func enqueueSend(_ message: ClientMessage) {
+        sendQueue = sendQueue + [message]
+        guard !isPumping else { return }
+        isPumping = true
+        Task { await self.pumpSendQueue() }
+    }
+
+    private func pumpSendQueue() async {
+        while let next = sendQueue.first {
+            sendQueue = Array(sendQueue.dropFirst())
+            await engine.send(next)
+            forwardedSendCount += 1
+            resumeSendWaiters()
+        }
+        isPumping = false
+    }
+
+    // MARK: - Deterministic test barriers (no polling, no real sleeps)
+
+    /// Suspends until at least `eventCount` events have been applied.
+    func waitUntilProcessed(eventCount target: Int) async {
+        await withCheckedContinuation { continuation in
+            guard processedEventCount < target else {
+                continuation.resume()
+                return
+            }
+            eventWaiters = eventWaiters + [CountWaiter(target: target, continuation: continuation)]
+        }
+    }
+
+    /// Suspends until at least `sendCount` messages were handed to the engine.
+    func waitUntilForwarded(sendCount target: Int) async {
+        await withCheckedContinuation { continuation in
+            guard forwardedSendCount < target else {
+                continuation.resume()
+                return
+            }
+            sendWaiters = sendWaiters + [CountWaiter(target: target, continuation: continuation)]
+        }
+    }
+
+    private func resumeEventWaiters() {
+        let satisfied = eventWaiters.filter { $0.target <= processedEventCount }
+        eventWaiters = eventWaiters.filter { $0.target > processedEventCount }
+        for waiter in satisfied {
+            waiter.continuation.resume()
+        }
+    }
+
+    private func resumeSendWaiters() {
+        let satisfied = sendWaiters.filter { $0.target <= forwardedSendCount }
+        sendWaiters = sendWaiters.filter { $0.target > forwardedSendCount }
+        for waiter in satisfied {
+            waiter.continuation.resume()
+        }
+    }
+
+    private func releaseAllWaiters() {
+        let all = eventWaiters + sendWaiters
+        eventWaiters = []
+        sendWaiters = []
+        for waiter in all {
+            waiter.continuation.resume()
+        }
+    }
+}