AgentRuntimeProcessTests.swift

import XCTest

@testable import Omi_Computer

private struct TokenRefreshAuthorization: Equatable, Sendable {
  let ownerID: String
  let generation: UInt64
}

private actor DelayedOwnerBoundTokenRefreshHarness {
  private var ownerId: String? = "owner-a"
  private var generation: UInt64 = 0
  private var fetchStarted = false
  private var fetchStartedWaiter: CheckedContinuation<Void, Never>?
  private var pendingFetch: CheckedContinuation<String, Error>?
  private(set) var fetchedOwnerIds: [String] = []
  private(set) var sentToken: String?
  private(set) var sentOwnerId: String?

  func captureAuthorization() -> TokenRefreshAuthorization? {
    guard let ownerId else { return nil }
    return TokenRefreshAuthorization(ownerID: ownerId, generation: generation)
  }

  func isAuthorizationCurrent(_ authorization: TokenRefreshAuthorization) -> Bool {
    ownerId == authorization.ownerID && generation == authorization.generation
  }

  func fetchAuthHeader(expectedOwnerId: String) async throws -> String {
    fetchedOwnerIds.append(expectedOwnerId)
    return try await withCheckedThrowingContinuation { continuation in
      pendingFetch = continuation
      fetchStarted = true
      fetchStartedWaiter?.resume()
      fetchStartedWaiter = nil
    }
  }

  func waitUntilFetchStarted() async {
    if fetchStarted { return }
    await withCheckedContinuation { continuation in
      fetchStartedWaiter = continuation
    }
  }

  func replaceOwnerASessionAndCompleteFetch(header: String) -> Bool {
    ownerId = nil
    generation &+= 1
    ownerId = "owner-a"
    generation &+= 1
    guard let pendingFetch else { return false }
    self.pendingFetch = nil
    pendingFetch.resume(returning: header)
    return true
  }

  func recordSend(token: String, ownerId: String) -> Bool {
    sentToken = token
    sentOwnerId = ownerId
    return true
  }

  func snapshot() -> (fetchedOwnerIds: [String], sentToken: String?, sentOwnerId: String?) {
    (fetchedOwnerIds, sentToken, sentOwnerId)
  }
}

private actor GatedRuntimeStartupHarness {
  private var launchCount = 0
  private var launchStarted = false
  private var launchStartedWaiter: CheckedContinuation<Void, Never>?
  private var releaseContinuation: CheckedContinuation<Void, Never>?

  func launch(receipt: UInt64) async -> UInt64 {
    launchCount += 1
    launchStarted = true
    launchStartedWaiter?.resume()
    launchStartedWaiter = nil
    await withCheckedContinuation { continuation in
      releaseContinuation = continuation
    }
    return receipt
  }

  func waitUntilLaunchStarted() async {
    if launchStarted { return }
    await withCheckedContinuation { continuation in
      launchStartedWaiter = continuation
    }
  }

  func release() -> Bool {
    guard let releaseContinuation else { return false }
    self.releaseContinuation = nil
    releaseContinuation.resume()
    return true
  }

  func launches() -> Int { launchCount }
}

private actor ContextProjectionRaceHarness {
  private var generation = 1
  private var events: [String] = []
  private var admissionAttempts = 0

  func record(_ event: String) {
    events.append(event)
  }

  func advance(_ event: String) {
    generation += 1
    events.append(event)
  }

  func freshness() -> AgentContextFreshness {
    AgentContextFreshness(
      version: "snapshot-v\(generation)",
      generation: generation,
      rendererFingerprint: "renderer-v\(generation)",
      capabilityVersion: "capabilities-v\(generation)"
    )
  }

  func recordAdmissionAttempt() -> Int {
    admissionAttempts += 1
    events.append("admission_attempt_\(admissionAttempts)")
    return admissionAttempts
  }

  func snapshot() -> [String] { events }
}

private actor GateAdmissionOrderProbe {
  private(set) var order: [String] = []

  func append(_ value: String) {
    order.append(value)
  }

  func snapshot() -> [String] {
    order
  }
}

/// Signals are latched, not edge-triggered. The signaller and its waiter run on
/// separate tasks, so nothing orders `signalEntered()` before `waitUntilEntered()`
/// (or `release()` before `waitUntilReleased()`); an unlatched signal that lands
/// first is dropped and its waiter suspends forever, which hangs the whole suite
/// until the per-suite budget kills it. The other probes in this file latch the
/// same way.
private actor GateHoldProbe {
  private var hasEntered = false
  private var hasReleased = false
  private var enteredWaiter: CheckedContinuation<Void, Never>?
  private var releaseContinuation: CheckedContinuation<Void, Never>?

  func waitUntilEntered() async {
    if hasEntered { return }
    await withCheckedContinuation { enteredWaiter = $0 }
  }

  func signalEntered() {
    hasEntered = true
    enteredWaiter?.resume()
    enteredWaiter = nil
  }

  func waitUntilReleased() async {
    if hasReleased { return }
    await withCheckedContinuation { releaseContinuation = $0 }
  }

  func release() {
    hasReleased = true
    releaseContinuation?.resume()
    releaseContinuation = nil
  }
}

private final class GateGrantCancellationRaceProbe: @unchecked Sendable {
  private let lock = NSLock()
  private let resumeGrantedWaiter = DispatchSemaphore(value: 0)
  private var waiterRegistered = false
  private var grantPaused = false
  private var registrationWaiter: CheckedContinuation<Void, Never>?
  private var grantWaiter: CheckedContinuation<Void, Never>?

  func signalWaiterRegistered() {
    lock.lock()
    waiterRegistered = true
    let waiter = registrationWaiter
    registrationWaiter = nil
    lock.unlock()
    waiter?.resume()
  }

  func waitUntilWaiterRegistered() async {
    await withCheckedContinuation { continuation in
      lock.lock()
      if waiterRegistered {
        lock.unlock()
        continuation.resume()
        return
      }
      registrationWaiter = continuation
      lock.unlock()
    }
  }

  func pauseGrantedHandoff() {
    lock.lock()
    grantPaused = true
    let waiter = grantWaiter
    grantWaiter = nil
    lock.unlock()
    waiter?.resume()
    resumeGrantedWaiter.wait()
  }

  func waitUntilGrantPaused() async {
    await withCheckedContinuation { continuation in
      lock.lock()
      if grantPaused {
        lock.unlock()
        continuation.resume()
        return
      }
      grantWaiter = continuation
      lock.unlock()
    }
  }

  func resumeGrantedHandoff() {
    resumeGrantedWaiter.signal()
  }
}

private actor ContextProjectionTaskBox {
  private var task: Task<Void, Never>?

  func store(_ task: Task<Void, Never>) {
    self.task = task
  }

  func wait() async {
    await task?.value
  }
}

private enum CredentialRefreshShouldNotRun: Error {
  case invoked
}

private actor CredentialFreeControlStartProbe {
  private var startupCredentialFetches = 0
  private var runtimeCredentialRefreshes = 0
  private var ownerSynchronizations = 0

  func attemptStartupCredentialFetch() throws -> String? {
    startupCredentialFetches += 1
    throw CredentialRefreshShouldNotRun.invoked
  }

  func attemptRuntimeCredentialRefresh() throws -> Bool {
    runtimeCredentialRefreshes += 1
    throw CredentialRefreshShouldNotRun.invoked
  }

  func synchronizeOwner() {
    ownerSynchronizations += 1
  }

  func snapshot() -> (startupCredentialFetches: Int, runtimeCredentialRefreshes: Int, ownerSynchronizations: Int) {
    (startupCredentialFetches, runtimeCredentialRefreshes, ownerSynchronizations)
  }
}

private actor ContextAdmissionRetryTestState {
  private(set) var attempts: [AgentContextFreshness?] = []
  private(set) var refreshCount = 0

  func recordRefresh() {
    refreshCount += 1
  }

  func recordAttempt(_ context: AgentContextFreshness?) -> Int {
    attempts.append(context)
    return attempts.count
  }

  func snapshot() -> (attempts: [AgentContextFreshness?], refreshCount: Int) {
    (attempts, refreshCount)
  }
}

final class AgentRuntimeProcessTests: XCTestCase {
  func testHermeticFaultModelTokenIsNonProductionOnlyAndAvoidsFirebaseRefresh() {
    let environment = [
      AgentRuntimeCredentialPolicy.hermeticFaultModelTokenEnvironmentKey: "fault-suite-model-token"
    ]

    let token = AgentRuntimeCredentialPolicy.hermeticFaultModelToken(
      isNonProduction: true,
      bundleIdentifier: AgentRuntimeCredentialPolicy.hermeticFaultBundleIdentifier,
      environment: environment)
    XCTAssertEqual(token, "fault-suite-model-token")
    XCTAssertFalse(
      AgentRuntimeCredentialPolicy.requiresManagedCredentials(
        requestedCredentials: true,
        isNonProduction: true,
        hermeticFaultModelToken: token),
      "the isolated fault backend must exercise its injected response without Firebase")
    XCTAssertNil(
      AgentRuntimeCredentialPolicy.hermeticFaultModelToken(
        isNonProduction: false,
        bundleIdentifier: AgentRuntimeCredentialPolicy.hermeticFaultBundleIdentifier,
        environment: environment),
      "production must never accept a harness-supplied model token")
    XCTAssertNil(
      AgentRuntimeCredentialPolicy.hermeticFaultModelToken(
        isNonProduction: true,
        bundleIdentifier: "com.omi.some-other-dev-bundle",
        environment: environment),
      "only the named fault bundle may opt into the inert model token")
    XCTAssertNil(
      AgentRuntimeCredentialPolicy.hermeticFaultModelToken(
        isNonProduction: true,
        bundleIdentifier: AgentRuntimeCredentialPolicy.hermeticFaultBundleIdentifier,
        environment: [
          AgentRuntimeCredentialPolicy.hermeticFaultModelTokenEnvironmentKey: "   "
        ]))
  }

  func testNonProductionJournalControlStartDoesNotRefreshCredentials() async throws {
    let probe = CredentialFreeControlStartProbe()

    XCTAssertFalse(
      AgentRuntimeCredentialPolicy.requiresManagedCredentials(
        requestedCredentials: false,
        isNonProduction: true))
    XCTAssertTrue(
      AgentRuntimeCredentialPolicy.requiresManagedCredentials(
        requestedCredentials: false,
        isNonProduction: false),
      "production must never permit a credential-free runtime start")
    XCTAssertTrue(
      AgentRuntimeCredentialPolicy.requiresManagedCredentials(
        requestedCredentials: true,
        isNonProduction: true),
      "normal model starts must remain credential-required")

    let authHeader = try await AgentRuntimeProcess.startupAuthHeader(
      requiresCredentials: false,
      fetchAuthHeader: {
        try await probe.attemptStartupCredentialFetch()
      })
    XCTAssertNil(authHeader)

    await AgentBridge.synchronizeAuthorityForStart(
      requiresCredentials: false,
      refreshCredentials: {
        try await probe.attemptRuntimeCredentialRefresh()
      },
      refreshOwner: {
        await probe.synchronizeOwner()
      })

    let snapshot = await probe.snapshot()
    XCTAssertEqual(snapshot.startupCredentialFetches, 0)
    XCTAssertEqual(snapshot.runtimeCredentialRefreshes, 0)
    XCTAssertEqual(snapshot.ownerSynchronizations, 1)
  }

  func testPinnedPiMonoSessionsFetchTokenAfterHarnessSwitch() async throws {
    XCTAssertFalse(
      AgentRuntimeCredentialPolicy.shouldRequirePiMonoCredentials(
        preferredAdapterIsPiMono: false,
        requestedCredentials: true,
        isNonProduction: false),
      "ACP/Hermes/OpenClaw must still start without a managed token")
    XCTAssertTrue(
      AgentRuntimeCredentialPolicy.requiresManagedCredentials(
        requestedCredentials: true,
        isNonProduction: false),
      "production alternate-harness starts must still fetch the managed token")
    XCTAssertTrue(
      AgentRuntimeCredentialPolicy.shouldRequirePiMonoCredentials(
        preferredAdapterIsPiMono: true,
        requestedCredentials: true,
        isNonProduction: false))

    var fetches = 0
    let header = try await AgentRuntimeProcess.startupAuthHeader(
      requiresCredentials: AgentRuntimeCredentialPolicy.requiresManagedCredentials(
        requestedCredentials: true,
        isNonProduction: false),
      fetchAuthHeader: {
        fetches += 1
        return "Bearer pinned-session-token"
      })
    XCTAssertEqual(fetches, 1)
    XCTAssertEqual(header, "Bearer pinned-session-token")

    var skippedFetches = 0
    let skipped = try await AgentRuntimeProcess.startupAuthHeader(
      requiresCredentials: AgentRuntimeCredentialPolicy.requiresManagedCredentials(
        requestedCredentials: false,
        isNonProduction: true),
      fetchAuthHeader: {
        skippedFetches += 1
        return "Bearer should-not-fetch"
      })
    XCTAssertEqual(skippedFetches, 0)
    XCTAssertNil(skipped)
  }

  func testNamedBundleStartupUsesValidSeededCredentialWithoutForcedRefresh() {
    XCTAssertFalse(
      AgentRuntimeCredentialPolicy.shouldForceRefreshAtStartup(
        isNonProduction: true,
        isDesktopLocalProfile: false),
      "a named bundle has no Firebase SDK session to satisfy a forced refresh")
    XCTAssertFalse(
      AgentRuntimeCredentialPolicy.shouldForceRefreshAtStartup(
        isNonProduction: true,
        isDesktopLocalProfile: true),
      "the local harness owns its credential lifecycle")
    XCTAssertTrue(
      AgentRuntimeCredentialPolicy.shouldForceRefreshAtStartup(
        isNonProduction: false,
        isDesktopLocalProfile: false),
      "production and Beta starts must continue forcing a fresh credential")
  }

  func testKernelJournalMutationClosesTheRuntimeReplayBoundary() async throws {
    let runtime = AgentRuntimeProcess()
    let turn = try XCTUnwrap(
      KernelJournalTurn(dictionary: [
        "conversationId": "conversation",
        "turnId": "turn-terminal",
        "turnSeq": 1,
        "conversationGeneration": 1,
        "generationBaseTurnSeq": 0,
        "producerId": "producer",
        "payloadHash": "hash",
        "role": "assistant",
        "surfaceKind": "main_chat",
        "content": "Done",
        "status": "completed",
        "origin": "chat",
        "contentBlocks": [],
        "resources": [],
        "metadataJson": "{}",
        "createdAtMs": 1,
        "updatedAtMs": 1,
      ]))

    await runtime.dispatchJournalTurnChangedForTesting(turn)

    var lifecycle = await runtime.bridgeLifecycleSnapshotForTesting()
    XCTAssertTrue(lifecycle.settledTurnIDs.contains("turn-terminal"))
    XCTAssertEqual(
      lifecycle.reduce(.walFrame(turnID: "turn-terminal")),
      [.rejectWALFrame(turnID: "turn-terminal")])
  }

  func testRuntimeHandshakeRejectsStaleV2RuntimeWithoutRequiredCapability() throws {
    let valid = try XCTUnwrap(
      AgentRuntimeProcess.RuntimeMessage.parse(
        #"{"type":"init","protocolVersion":2,"sessionId":"","agentControlTools":[],"runtimeVersion":"1.0.0","runtimeCapabilities":["journal_import_remote_turn","runtime_adapter_availability","chat_first_capability_projection"]}"#
      ))
    let handshake = try AgentRuntimeProcess.validateRuntimeHandshake(valid)
    XCTAssertEqual(handshake.protocolVersion, AgentRuntimeProcess.expectedProtocolVersion)
    XCTAssertTrue(handshake.capabilities.contains("journal_import_remote_turn"))

    let stale = try XCTUnwrap(
      AgentRuntimeProcess.RuntimeMessage.parse(
        #"{"type":"init","protocolVersion":2,"sessionId":"","agentControlTools":[],"runtimeVersion":"1.0.0","runtimeCapabilities":[]}"#
      ))
    XCTAssertThrowsError(try AgentRuntimeProcess.validateRuntimeHandshake(stale))

    let wrongProtocol = try XCTUnwrap(
      AgentRuntimeProcess.RuntimeMessage.parse(
        #"{"type":"init","protocolVersion":1,"sessionId":"","agentControlTools":[],"runtimeVersion":"1.0.0","runtimeCapabilities":["journal_import_remote_turn","runtime_adapter_availability","chat_first_capability_projection"]}"#
      ))
    XCTAssertThrowsError(try AgentRuntimeProcess.validateRuntimeHandshake(wrongProtocol))
  }

  func testJournalDeadlineAcceptsResultAfterSQLiteBusyWindowWithoutWallClockDelay() {
    let simulatedArrivalNanoseconds: UInt64 = 6_170_000_000
    XCTAssertEqual(
      AgentRuntimeJournalTimeoutPolicy.sqliteBusyWindowNanoseconds,
      5_000_000_000
    )
    XCTAssertEqual(AgentRuntimeJournalTimeoutPolicy.ipcSlackNanoseconds, 5_000_000_000)
    XCTAssertGreaterThan(
      AgentRuntimeJournalTimeoutPolicy.deadlineNanoseconds,
      AgentRuntimeJournalTimeoutPolicy.sqliteBusyWindowNanoseconds
    )
    XCTAssertLessThan(
      simulatedArrivalNanoseconds,
      AgentRuntimeJournalTimeoutPolicy.deadlineNanoseconds
    )
    XCTAssertTrue(
      AgentRuntimeJournalTimeoutPolicy.allowsCorrelatedResult(
        elapsedNanoseconds: simulatedArrivalNanoseconds
      )
    )
  }

  func testJournalDeadlineClassifiesExactAndLaterArrivalsAsTimedOut() {
    let deadline = AgentRuntimeJournalTimeoutPolicy.deadlineNanoseconds
    XCTAssertEqual(deadline, 10_000_000_000)
    XCTAssertFalse(
      AgentRuntimeJournalTimeoutPolicy.allowsCorrelatedResult(
        elapsedNanoseconds: deadline
      ),
      "the actor removes the request at the exact deadline before late results can route"
    )
    XCTAssertFalse(
      AgentRuntimeJournalTimeoutPolicy.allowsCorrelatedResult(
        elapsedNanoseconds: deadline + 1_170_000_000
      ),
      "post-deadline results remain unroutable"
    )
  }

  // MARK: - CHAT-02 agent stall hook

  func testSuspendStreamNoOpsWithoutRunningProcess() async {
    // External contract: the debug suspend never reports success without a real
    // suspend — it returns an error (prod-gated in the test host, or no running
    // process on a dev bundle), never suspended:true, and never SIGSTOPs a bogus pid.
    let result = await AgentRuntimeProcess.shared.debugSuspendStream(durationMs: 190_000)
    XCTAssertNotEqual(result["suspended"], "true")
    XCTAssertNotNil(result["error"])
  }

  func testResumeStreamNoOpsWithoutProcess() {
    // debugResumeStream is nonisolated now (off-actor SIGCONT) — no await needed.
    let result = AgentRuntimeProcess.shared.debugResumeStream()
    XCTAssertNotEqual(result["resumed"], "true")
    XCTAssertNotNil(result["error"])
  }

  func testAgentStallHookIsNonProdGatedAndSafe() throws {
    let processSource = try String(
      contentsOf: URL(fileURLWithPath: #filePath)
        .deletingLastPathComponent().deletingLastPathComponent()
        .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift"),
      encoding: .utf8)
    // Production gate, live-process guard, real signals, bounded window, and a
    // generation-guarded auto-resume so a forgotten resume can't wedge the agent.
    for needle in [
      "func debugSuspendStream(durationMs: Int)",
      "guard AppBuild.isNonProduction else",
      "process.isRunning, process.processIdentifier > 0",
      "kill(pid, SIGSTOP)",
      "kill($0, SIGCONT)",
      "min(durationMs, 300_000)",
      "generation == self.generation",
    ] {
      XCTAssertTrue(processSource.contains(needle), "AgentRuntimeProcess missing stall-hook invariant: \(needle)")
    }

    let bridgeSource = try String(
      contentsOf: URL(fileURLWithPath: #filePath)
        .deletingLastPathComponent().deletingLastPathComponent()
        .appendingPathComponent("Sources/DesktopAutomationBridge.swift"),
      encoding: .utf8)
    for needle in ["name: \"suspend_agent_stream\"", "name: \"resume_agent_stream\""] {
      XCTAssertTrue(bridgeSource.contains(needle), "bridge missing action: \(needle)")
    }
    // Both actions must be behind the non-prod guard.
    let suspendIdx = bridgeSource.range(of: "name: \"suspend_agent_stream\"")!.lowerBound
    let afterSuspend = String(bridgeSource[suspendIdx...].prefix(600))
    XCTAssertTrue(
      afterSuspend.contains("AppBuild.isNonProduction"),
      "suspend_agent_stream must be gated to non-production bundles")
  }

  func testV2ResultParsingPreservesCanonicalAndAdapterIds() {
    let line = """
      {"type":"result","protocolVersion":2,"requestId":"req-1","clientId":"client-1","sessionId":"omi-1","runId":"run-1","attemptId":"attempt-1","adapterSessionId":"acp-1","terminalStatus":"succeeded","text":"done","costUsd":1.25,"inputTokens":3,"outputTokens":4,"cacheReadTokens":5,"cacheWriteTokens":6}
      """

    let message = AgentRuntimeProcess.RuntimeMessage.parse(line)

    XCTAssertEqual(message?.kind, .result)
    XCTAssertEqual(message?.requestId, "req-1")
    XCTAssertEqual(message?.clientId, "client-1")
    XCTAssertEqual(
      message?.requestKey, AgentRuntimeProcess.RuntimeMessage.RequestKey(clientId: "client-1", requestId: "req-1"))
    XCTAssertEqual(message?.payload["sessionId"] as? String, "omi-1")
    XCTAssertEqual(message?.payload["adapterSessionId"] as? String, "acp-1")
    XCTAssertEqual(message?.payload["terminalStatus"] as? String, "succeeded")
  }

  func testTurnActivityParsingPreservesRequestCorrelationWithoutContent() throws {
    let message = try XCTUnwrap(
      AgentRuntimeProcess.RuntimeMessage.parse(
        #"{"type":"turn_activity","phase":"running","protocolVersion":2,"requestId":"quiet-1","clientId":"client-1","sessionId":"omi-1","runId":"run-1","attemptId":"attempt-1"}"#
      ))

    XCTAssertEqual(message.kind, .turnActivity)
    XCTAssertEqual(
      message.requestKey,
      AgentRuntimeProcess.RuntimeMessage.RequestKey(clientId: "client-1", requestId: "quiet-1")
    )
    XCTAssertEqual(message.payload["phase"] as? String, "running")
    XCTAssertNil(message.payload["text"])
  }

  func testCancelAckRoutesByRequestId() {
    let message = AgentRuntimeProcess.RuntimeMessage.parse(
      #"{"type":"cancel_ack","protocolVersion":2,"requestId":"cancel-me","clientId":"client-1","accepted":true,"dispatchAttempted":true,"adapterAcknowledged":false}"#
    )

    XCTAssertEqual(message?.kind, .cancelAck)
    XCTAssertEqual(
      message?.requestKey, AgentRuntimeProcess.RuntimeMessage.RequestKey(clientId: "client-1", requestId: "cancel-me"))
    XCTAssertEqual(message?.payload["accepted"] as? Bool, true)
    XCTAssertEqual(message?.payload["adapterAcknowledged"] as? Bool, false)
  }

  func testInitMessageCarriesAdvertisedAgentControlTools() {
    let message = AgentRuntimeProcess.RuntimeMessage.parse(
      #"{"type":"init","sessionId":"","agentControlTools":["list_agent_sessions","spawn_background_agent"]}"#
    )

    XCTAssertEqual(message?.kind, .initMessage)
    XCTAssertEqual(
      message?.payload["agentControlTools"] as? [String], ["list_agent_sessions", "spawn_background_agent"])
  }

  func testControlToolResultRoutesByRequestId() {
    let message = AgentRuntimeProcess.RuntimeMessage.parse(
      #"{"type":"control_tool_result","protocolVersion":2,"requestId":"control-1","clientId":"client-1","ownerId":"owner-1","name":"inspect_agent_artifacts","result":"{\"ok\":true,\"artifacts\":[]}"}"#
    )

    XCTAssertEqual(message?.kind, .controlToolResult)
    XCTAssertEqual(
      message?.requestKey, AgentRuntimeProcess.RuntimeMessage.RequestKey(clientId: "client-1", requestId: "control-1"))
    XCTAssertEqual(message?.payload["ownerId"] as? String, "owner-1")
    XCTAssertEqual(message?.payload["name"] as? String, "inspect_agent_artifacts")
    XCTAssertEqual(message?.payload["result"] as? String, #"{"ok":true,"artifacts":[]}"#)
  }

  func testDirectControlWireAndResultValidationAreOwnerBound() {
    let request = AgentRuntimeProcess.directControlToolWireMessage(
      clientId: "client-1",
      requestId: "control-1",
      ownerId: "owner-a",
      name: "spawn_agent",
      input: ["objective": "Inspect memories"])

    XCTAssertEqual(request["type"] as? String, "direct_control_tool")
    XCTAssertEqual(request["ownerId"] as? String, "owner-a")
    XCTAssertTrue(
      AgentRuntimeProcess.isDirectControlResultOwnerCurrent(
        expectedOwnerId: "owner-a",
        expectedOwnerEpoch: 1,
        resultOwnerId: "owner-a",
        currentOwnerId: "owner-a",
        currentOwnerEpoch: 1))
    XCTAssertFalse(
      AgentRuntimeProcess.isDirectControlResultOwnerCurrent(
        expectedOwnerId: "owner-a",
        expectedOwnerEpoch: 1,
        resultOwnerId: nil,
        currentOwnerId: "owner-a",
        currentOwnerEpoch: 1))
    XCTAssertFalse(
      AgentRuntimeProcess.isDirectControlResultOwnerCurrent(
        expectedOwnerId: "owner-a",
        expectedOwnerEpoch: 1,
        resultOwnerId: "owner-b",
        currentOwnerId: "owner-a",
        currentOwnerEpoch: 1))
    XCTAssertFalse(
      AgentRuntimeProcess.isDirectControlResultOwnerCurrent(
        expectedOwnerId: "owner-a",
        expectedOwnerEpoch: 1,
        resultOwnerId: "owner-a",
        currentOwnerId: "owner-b",
        currentOwnerEpoch: 2))
    XCTAssertFalse(
      AgentRuntimeProcess.isDirectControlResultOwnerCurrent(
        expectedOwnerId: "owner-a",
        expectedOwnerEpoch: 1,
        resultOwnerId: "owner-a",
        currentOwnerId: "owner-a",
        currentOwnerEpoch: 3))
  }

  func testLocalProviderRuntimeOwnerHandshakePrecedesOwnerScopedStartupWork() throws {
    let handshake = AgentRuntimeProcess.runtimeOwnerHandshakeWireMessage(ownerId: "signed-in-owner")
    XCTAssertEqual(handshake["type"] as? String, "refresh_owner")
    XCTAssertEqual(handshake["ownerId"] as? String, "signed-in-owner")
    XCTAssertNil(handshake["token"])

    // omi-test-quality: source-inspection -- static contract: every harness must synchronize daemon owner authority before owner-scoped legacy migration; wire and resource-layout behavior are tested directly beside this ordering guard
    let bridgeSource = try sourceFile("Chat/AgentBridge.swift")
    let startRange = try XCTUnwrap(
      bridgeSource.range(
        of: "func start(\n    authorizationSnapshot:"))
    let restartRange = try XCTUnwrap(
      bridgeSource.range(
        of: "\n  func restart() async throws",
        range: startRange.upperBound..<bridgeSource.endIndex))
    let startBody = String(bridgeSource[startRange.lowerBound..<restartRange.lowerBound])
    let handshakeRange = try XCTUnwrap(
      startBody.range(
        of: "await synchronizeRuntimeAuthority(\n          authorizationSnapshot: authorizationSnapshot,"))
    let migrationRange = try XCTUnwrap(
      startBody.range(
        of: "await migrateLegacyMainChatSessionsIfNeeded("))
    XCTAssertLessThan(handshakeRange.lowerBound, migrationRange.lowerBound)
    XCTAssertTrue(bridgeSource.contains("synchronizeAuthorityForStart("))
    XCTAssertTrue(bridgeSource.contains("runtime.refreshRuntimeOwner("))
  }

  func testRuntimeStartupSingleFlightLaunchesExactlyOnceForConcurrentSameKey() async throws {
    let singleFlight = AgentRuntimeStartupSingleFlight<String, UInt64>()
    let harness = GatedRuntimeStartupHarness()
    let first = Task {
      try await singleFlight.run(key: "owner-a:generation-1") {
        await harness.launch(receipt: 41)
      }
    }
    await harness.waitUntilLaunchStarted()
    let second = Task {
      try await singleFlight.run(key: "owner-a:generation-1") {
        await harness.launch(receipt: 99)
      }
    }

    var observedTwoParticipants = false
    for _ in 0..<10_000 {
      if await singleFlight.participantCountForTesting() == 2 {
        observedTwoParticipants = true
        break
      }
      await Task.yield()
    }
    XCTAssertTrue(observedTwoParticipants)
    let launchesBeforeRelease = await harness.launches()
    let released = await harness.release()
    XCTAssertEqual(launchesBeforeRelease, 1)
    XCTAssertTrue(released)

    let firstReceipt = try await first.value
    let secondReceipt = try await second.value
    XCTAssertEqual(firstReceipt, 41)
    XCTAssertEqual(secondReceipt, 41)
    let finalLaunches = await harness.launches()
    XCTAssertEqual(finalLaunches, 1)
  }

  func testRuntimeStartupSingleFlightRejectsDifferentOwnerGenerationWhileSuspended() async throws {
    let singleFlight = AgentRuntimeStartupSingleFlight<String, UInt64>()
    let harness = GatedRuntimeStartupHarness()
    let first = Task {
      try await singleFlight.run(key: "owner-a:generation-1") {
        await harness.launch(receipt: 7)
      }
    }
    await harness.waitUntilLaunchStarted()

    do {
      _ = try await singleFlight.run(key: "owner-a:generation-2") { 8 }
      XCTFail("new owner generation must not join an older credential-bearing launch")
    } catch BridgeError.restarting {
      // Expected: caller retries only after the exact older flight terminates.
    } catch {
      XCTFail("unexpected mismatch error: \(error)")
    }

    let launchesBeforeRelease = await harness.launches()
    let released = await harness.release()
    XCTAssertEqual(launchesBeforeRelease, 1)
    XCTAssertTrue(released)
    let receipt = try await first.value
    XCTAssertEqual(receipt, 7)
  }

  func testOwnerBoundTokenRefreshDropsDelayedTokenAcrossSameOwnerSessionReplacement() async throws {
    let harness = DelayedOwnerBoundTokenRefreshHarness()
    let refreshTask = Task {
      try await AgentBridge.refreshOwnerBoundToken(
        captureAuthorization: {
          await harness.captureAuthorization()
        },
        authorizationOwnerId: { authorization in
          authorization.ownerID
        },
        isAuthorizationCurrent: { authorization in
          await harness.isAuthorizationCurrent(authorization)
        },
        fetchAuthHeader: { expectedOwnerId in
          try await harness.fetchAuthHeader(expectedOwnerId: expectedOwnerId)
        },
        sendToken: { token, expectedOwnerId, _ in
          await harness.recordSend(token: token, ownerId: expectedOwnerId)
        }
      )
    }

    await harness.waitUntilFetchStarted()
    let resumed = await harness.replaceOwnerASessionAndCompleteFetch(
      header: "Bearer owner-a-token")
    XCTAssertTrue(resumed)
    let refreshed = try await refreshTask.value
    XCTAssertFalse(refreshed)

    let snapshot = await harness.snapshot()
    XCTAssertEqual(snapshot.fetchedOwnerIds, ["owner-a"])
    XCTAssertNil(snapshot.sentToken, "stale owner-A token must never reach the runtime sender")
    XCTAssertNil(snapshot.sentOwnerId, "stale refresh must not mutate runtime owner credentials")
  }

  func testRuntimeRefreshTokenWireRequiresCapturedOwnerToRemainCurrent() {
    let authorized = AgentRuntimeProcess.refreshTokenWireMessage(
      token: "owner-a-token",
      expectedOwnerId: "owner-a",
      currentOwnerId: "owner-a"
    )

    XCTAssertEqual(authorized?["type"] as? String, "refresh_token")
    XCTAssertEqual(authorized?["token"] as? String, "owner-a-token")
    XCTAssertEqual(authorized?["ownerId"] as? String, "owner-a")
    XCTAssertNil(
      AgentRuntimeProcess.refreshTokenWireMessage(
        token: "owner-a-token",
        expectedOwnerId: "owner-a",
        currentOwnerId: "owner-b"
      ))
    XCTAssertNil(
      AgentRuntimeProcess.refreshTokenWireMessage(
        token: "owner-a-token",
        expectedOwnerId: "owner-a",
        currentOwnerId: nil
      ))
  }

  func testOwnerRuntimeRevocationWireAndCorrelatedReceiptShape() {
    let wire = AgentRuntimeProcess.revokeOwnerRuntimeWireMessage(
      clientId: "runtime-owner-transition",
      requestId: "revoke-1",
      ownerId: "owner-a")
    XCTAssertEqual(wire["type"] as? String, "revoke_owner_runtime")
    XCTAssertEqual(wire["protocolVersion"] as? Int, 2)
    XCTAssertEqual(wire["requestId"] as? String, "revoke-1")
    XCTAssertEqual(wire["clientId"] as? String, "runtime-owner-transition")
    XCTAssertEqual(wire["ownerId"] as? String, "owner-a")

    let receipt = AgentRuntimeProcess.RuntimeMessage.parse(
      #"{"type":"owner_runtime_revoked","protocolVersion":2,"requestId":"revoke-1","clientId":"runtime-owner-transition","ownerId":"owner-a","ok":true,"duplicate":false,"revokedRunIds":["run-1"],"invalidatedBindingIds":["binding-1"]}"#
    )
    XCTAssertEqual(receipt?.kind, .ownerRuntimeRevoked)
    XCTAssertEqual(
      receipt?.requestKey,
      AgentRuntimeProcess.RuntimeMessage.RequestKey(
        clientId: "runtime-owner-transition",
        requestId: "revoke-1"))
    XCTAssertEqual(receipt?.payload["ownerId"] as? String, "owner-a")
    XCTAssertEqual(receipt?.payload["revokedRunIds"] as? [String], ["run-1"])
    XCTAssertEqual(receipt?.payload["invalidatedBindingIds"] as? [String], ["binding-1"])
  }

  func testRuntimeNodeResourceLookupSupportsAppAndSwiftPMTestLayoutsWithoutFatalAccessor() {
    let appBundle = URL(fileURLWithPath: "/Applications/omi-test.app")
    let testBundle = URL(fileURLWithPath: "/tmp/debug/Omi ComputerPackageTests.xctest")
    let executable =
      testBundle
      .appendingPathComponent("Contents/MacOS/Omi ComputerPackageTests")
    let candidates = AgentRuntimeProcess.runtimeResourceExecutableCandidates(
      named: "node",
      bundleURLs: [appBundle, testBundle],
      executableURL: executable)

    XCTAssertTrue(
      candidates.contains(
        "/Applications/omi-test.app/Contents/Resources/Omi Computer_Omi Computer.bundle/Contents/Resources/node"))
    XCTAssertTrue(
      candidates.contains(
        "/tmp/debug/Omi Computer_Omi Computer.bundle/node"))
    XCTAssertFalse(candidates.isEmpty)
  }

  func testLegacyMainChatAliasReceiptRoutesByRequestAndOwner() {
    let message = AgentRuntimeProcess.RuntimeMessage.parse(
      #"{"type":"legacy_main_chat_sessions_imported","protocolVersion":2,"requestId":"legacy-1","clientId":"client-1","ownerId":"owner-1","acceptedEntries":[{"chatId":"default","agentSessionId":"ses-1"}],"acceptedCount":1,"importedCount":1}"#
    )

    XCTAssertEqual(message?.kind, .legacyMainChatSessionsImported)
    XCTAssertEqual(
      message?.requestKey,
      AgentRuntimeProcess.RuntimeMessage.RequestKey(clientId: "client-1", requestId: "legacy-1")
    )
    XCTAssertEqual(message?.payload["ownerId"] as? String, "owner-1")
  }

  func testLegacyMainChatAliasImportWireMessageCarriesOwnerAndEntries() {
    let entry = LegacyMainChatSessionAliasEntry(chatId: "default", agentSessionId: "ses-1")
    let message = AgentRuntimeProcess.importLegacyMainChatSessionsWireMessage(
      clientId: "client-1",
      requestId: "legacy-1",
      ownerId: "owner-1",
      entries: [entry]
    )

    XCTAssertEqual(message["type"] as? String, "import_legacy_main_chat_sessions")
    XCTAssertEqual(message["protocolVersion"] as? Int, 2)
    XCTAssertEqual(message["ownerId"] as? String, "owner-1")
    XCTAssertEqual(
      message["entries"] as? [[String: String]],
      [["chatId": "default", "agentSessionId": "ses-1"]]
    )
  }

  func testAuthorizedToolExecutionCarriesLedgerIdentityWithoutRequestScope() {
    let message = AgentRuntimeProcess.RuntimeMessage.parse(
      #"{"type":"authorized_tool_execution","protocolVersion":2,"invocationId":"invoke-1","ownerId":"owner-1","sessionId":"session-1","runId":"run-1","attemptId":"attempt-1","profileGeneration":2,"manifestVersion":1,"manifestDigest":"sha256:test","daemonBootEpoch":"boot-1","executionGeneration":3,"toolName":"get_memories","input":{},"inputHash":"sha256:e3b0","effectClass":"read_only","retryPolicy":"safe_retry","surfaceKind":"background_agent","externalRefKind":null,"externalRefId":null,"originatingUserText":"find memories","precedingAssistantText":null,"runMode":"act","chatMode":null}"#
    )

    XCTAssertEqual(message?.kind, .authorizedToolExecution)
    XCTAssertNil(message?.requestKey)
    XCTAssertEqual(message?.payload["invocationId"] as? String, "invoke-1")
    XCTAssertEqual(message?.payload["attemptId"] as? String, "attempt-1")
  }

  func testSwiftHasNoCapabilityAuthorityOrRequestScopedExecution() throws {
    let processSourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let processSource = try String(contentsOf: processSourceURL, encoding: .utf8)

    XCTAssertTrue(processSource.contains("AuthorizedToolExecution.parse("))
    XCTAssertTrue(processSource.contains(#"case .authorizedToolExecution:"#))
    XCTAssertFalse(processSource.contains("RunToolCapabilityRegistry"))
    XCTAssertFalse(processSource.contains("toolCapabilities"))
    XCTAssertFalse(processSource.contains("tool_capability_register"))
    XCTAssertFalse(processSource.contains("guard let request = routedRequest(for: message) else"))
  }

  func testV2MessagesWithoutClientIdDoNotHaveRequestKey() {
    let message = AgentRuntimeProcess.RuntimeMessage.parse(
      #"{"type":"result","protocolVersion":2,"requestId":"req-1","sessionId":"omi-1","runId":"run-1","attemptId":"attempt-1","terminalStatus":"succeeded","text":"done"}"#
    )

    XCTAssertEqual(message?.kind, .result)
    XCTAssertNil(message?.requestKey)
  }

  func testHarnessModeMapsNamedAdapters() {
    XCTAssertEqual(AgentRuntimeProcess.adapterId(forHarnessMode: "piMono"), "pi-mono")
    XCTAssertEqual(AgentRuntimeProcess.adapterId(forHarnessMode: "pi-mono"), "pi-mono")
    XCTAssertEqual(AgentRuntimeProcess.adapterId(forHarnessMode: "hermes"), "hermes")
    XCTAssertEqual(AgentRuntimeProcess.adapterId(forHarnessMode: "openclaw"), "openclaw")
    XCTAssertEqual(AgentRuntimeProcess.adapterId(forHarnessMode: "openClaw"), "openclaw")
    XCTAssertNil(AgentRuntimeProcess.adapterId(forHarnessMode: "unknown"))
  }

  func testPiMonoAliasUsesCanonicalAdapterForAuthGuards() throws {
    let processSourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let processSource = try String(contentsOf: processSourceURL, encoding: .utf8)

    XCTAssertTrue(
      processSource.contains("let preferredAdapterId = AgentRuntimeRouting.adapterId(for: preferredHarness)"))
    XCTAssertTrue(processSource.contains("preferredAdapterId == .piMono"))
    XCTAssertFalse(processSource.contains(#"preferredHarnessMode == "piMono""#))

    let bridgeSourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentBridge.swift")
    let bridgeSource = try String(contentsOf: bridgeSourceURL, encoding: .utf8)

    XCTAssertTrue(
      bridgeSource.contains(
        "AgentRuntimeProcess.adapterId(forHarnessMode: harnessMode) == AgentAdapterId.piMono.rawValue"))
    XCTAssertTrue(bridgeSource.contains("shouldRequirePiMonoCredentials("))
    XCTAssertTrue(bridgeSource.contains("shouldFetchManagedToken"))
    XCTAssertFalse(bridgeSource.contains("if adapterId == AgentAdapterId.piMono.rawValue"))
    XCTAssertTrue(
      bridgeSource.contains(
        "if requiresCredentials {\n      ensureTokenRefreshTask(authorizationSnapshot: authorizationSnapshot)"))
    XCTAssertFalse(bridgeSource.contains("guard isPiMonoHarness else { return false }"))
    XCTAssertFalse(bridgeSource.contains(#"harnessMode == "piMono""#))
  }

  func testPiMonoInvalidTokenRetriesAfterForcedAuthRefresh() throws {
    let bridgeSourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentBridge.swift")
    let bridgeSource = try String(contentsOf: bridgeSourceURL, encoding: .utf8)

    XCTAssertTrue(bridgeSource.contains("error.isSessionAuthenticationFailure"))
    XCTAssertTrue(bridgeSource.contains("!bridgeOutputTracker.hasOutput"))
    XCTAssertTrue(bridgeSource.contains("private final class BridgeOutputTracker: @unchecked Sendable"))
    XCTAssertTrue(bridgeSource.contains("refreshing token and retrying once"))
    // The refresh must convert real auth failures to authMissing so ChatProvider
    // routes to the sign-in recovery CTA, while propagating CancellationError so a
    // cancelled request is not misrouted to auth recovery.
    XCTAssertTrue(bridgeSource.contains("catch is CancellationError"))
    XCTAssertTrue(bridgeSource.contains("throw CancellationError()"))
    XCTAssertTrue(bridgeSource.contains("catch {"))
    XCTAssertTrue(bridgeSource.contains("throw BridgeError.authMissing"))
    XCTAssertFalse(bridgeSource.contains("guard try await refreshAuthToken()"))
    XCTAssertFalse(bridgeSource.contains("(try? await refreshAuthToken()) == true"))
    XCTAssertTrue(bridgeSource.contains("let retryRequestId = UUID().uuidString"))
  }

  func testNamedBundleStateDirectoriesAreIsolated() {
    let home = URL(fileURLWithPath: "/tmp/test-home")

    let firstState = AgentRuntimeProcess.defaultStateDirectory(
      bundleIdentifier: "com.omi.omi-ticket-five-a",
      homeDirectory: home
    )
    let secondState = AgentRuntimeProcess.defaultStateDirectory(
      bundleIdentifier: "com.omi.omi-ticket-five-b",
      homeDirectory: home
    )
    let firstArtifacts = AgentRuntimeProcess.defaultArtifactsDirectory(
      bundleIdentifier: "com.omi.omi-ticket-five-a",
      homeDirectory: home
    )
    let secondArtifacts = AgentRuntimeProcess.defaultArtifactsDirectory(
      bundleIdentifier: "com.omi.omi-ticket-five-b",
      homeDirectory: home
    )

    XCTAssertNotEqual(firstState, secondState)
    XCTAssertNotEqual(firstArtifacts, secondArtifacts)
    XCTAssertTrue(firstState.hasSuffix("AgentRuntime/com.omi.omi-ticket-five-a"))
    XCTAssertTrue(secondState.hasSuffix("AgentRuntime/com.omi.omi-ticket-five-b"))
    XCTAssertTrue(firstArtifacts.hasSuffix("Artifacts/com.omi.omi-ticket-five-a"))
    XCTAssertTrue(secondArtifacts.hasSuffix("Artifacts/com.omi.omi-ticket-five-b"))
  }

  func testCompatibilitySessionIdPrefersAdapterSession() {
    let withAdapter = AgentBridge.QueryResult(
      text: "done",
      costUsd: 0,
      omiSessionId: "omi-session",
      runId: "run",
      attemptId: "attempt",
      adapterSessionId: "adapter-session",
      terminalStatus: "succeeded",
      inputTokens: 0,
      outputTokens: 0,
      cacheReadTokens: 0,
      cacheWriteTokens: 0
    )
    let withoutAdapter = AgentBridge.QueryResult(
      text: "done",
      costUsd: 0,
      omiSessionId: "omi-session",
      runId: "run",
      attemptId: "attempt",
      adapterSessionId: nil,
      terminalStatus: "succeeded",
      inputTokens: 0,
      outputTokens: 0,
      cacheReadTokens: 0,
      cacheWriteTokens: 0
    )

    XCTAssertEqual(withAdapter.adapterSessionId, "adapter-session")
    XCTAssertEqual(withoutAdapter.omiSessionId, "omi-session")
    XCTAssertNil(withoutAdapter.adapterSessionId)
  }

  @MainActor
  func testEveryNonTaskQueryResultLayerFailsClosedWithoutTypedSuccess() throws {
    XCTAssertEqual(AgentQueryTerminalStatus(wireValue: "succeeded"), .succeeded)
    XCTAssertEqual(AgentQueryTerminalStatus(wireValue: "cancelled"), .cancelled)
    XCTAssertEqual(AgentQueryTerminalStatus(wireValue: nil), .invalid(nil))
    XCTAssertEqual(AgentQueryTerminalStatus(wireValue: "future_terminal"), .invalid("future_terminal"))

    let successfulBridgeResult = AgentBridge.QueryResult(
      text: "accepted",
      costUsd: 0,
      omiSessionId: "omi-session",
      runId: "run",
      attemptId: "attempt",
      adapterSessionId: nil,
      terminalStatus: "succeeded",
      inputTokens: 0,
      outputTokens: 0,
      cacheReadTokens: 0,
      cacheWriteTokens: 0
    )
    let successfulClientResult = AgentClient.QueryResult(successfulBridgeResult)
    XCTAssertEqual(try successfulBridgeResult.requireSucceeded().text, "accepted")
    XCTAssertEqual(try successfulClientResult.requireSucceeded().text, "accepted")
    XCTAssertEqual(
      try ChatProvider.requireSuccessfulQueryResult(successfulClientResult).text,
      "accepted"
    )

    for rawStatus in [nil, "future_terminal", "failed", "timed_out", "orphaned", "cancelled"] as [String?] {
      let bridgeResult = AgentBridge.QueryResult(
        text: "not successful",
        costUsd: 0,
        omiSessionId: "omi-session",
        runId: "run",
        attemptId: "attempt",
        adapterSessionId: nil,
        terminalStatus: rawStatus,
        inputTokens: 0,
        outputTokens: 0,
        cacheReadTokens: 0,
        cacheWriteTokens: 0
      )
      let clientResult = AgentClient.QueryResult(bridgeResult)
      let label = "\(String(describing: rawStatus)) must fail closed"
      XCTAssertThrowsError(try bridgeResult.requireSucceeded(), label)
      XCTAssertThrowsError(try clientResult.requireSucceeded(), label)
      XCTAssertThrowsError(try ChatProvider.requireSuccessfulQueryResult(clientResult), label)
    }
  }

  func testSharedRuntimeDoesNotTrackCurrentHarnessMode() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    XCTAssertFalse(source.contains("currentHarnessMode"))
    XCTAssertFalse(source.contains("harness changed"))
    XCTAssertFalse(source.contains(#""adapterId": harnessMode == "piMono" ? "pi-mono" : "acp""#))
  }

  func testLocalAdapterDiscoveryRunsForSharedRuntimeStartup() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    XCTAssertTrue(source.contains("applyLocalAgentEnvironment(to: &env)"))
    XCTAssertFalse(source.contains("applyLocalAgentEnvironment(to: &env, adapterId: preferredAdapterId)"))
    XCTAssertFalse(source.contains("guard adapterId == .hermes || adapterId == .openclaw else"))
    XCTAssertTrue(source.contains(#"env["HOME"] = home"#))
    XCTAssertTrue(source.contains(#"env["HERMES_HOME"] = "\(home)/.hermes""#))
    XCTAssertTrue(source.contains(#""\(home)/.hermes/hermes-agent/venv/bin""#))
    XCTAssertTrue(source.contains("existingPath.split(separator: \":\").map(String.init) + adapterPathDirs"))
    XCTAssertFalse(source.contains("+ trustedPathDirs + adapterPathDirs"))
    XCTAssertFalse(source.contains("adapterPathPrefixDirs + existingPath.split"))
    XCTAssertTrue(source.contains(#"env["PATH"] = pathElements.joined(separator: ":")"#))
    XCTAssertTrue(source.contains(#"env["OMI_OPENCLAW_ADAPTER_COMMAND"]"#))
    XCTAssertTrue(source.contains(#"env["OMI_HERMES_ADAPTER_COMMAND"]"#))
  }

  func testJITQABackendTupleIsPreservedInAgentChildEnvironment() {
    let localTuple = [
      "OMI_PYTHON_API_URL": "http://127.0.0.1:18080",
      "OMI_DESKTOP_API_URL": "http://127.0.0.1:18081",
      "OMI_AUTH_API_URL": "http://127.0.0.1:18080",
      "OMI_ENV_STAGE": "dev",
    ]
    let localChild = AgentRuntimeProcess.childBackendRoutingEnvironment(
      baseEnvironment: localTuple,
      rustBase: "http://127.0.0.1:18081"
    )
    XCTAssertEqual(localChild["OMI_PYTHON_API_URL"], "http://127.0.0.1:18080")
    XCTAssertEqual(localChild["OMI_DESKTOP_API_URL"], "http://127.0.0.1:18081")
    XCTAssertEqual(localChild["OMI_AUTH_API_URL"], "http://127.0.0.1:18080")
    XCTAssertEqual(localChild["OMI_ENV_STAGE"], "dev")
    XCTAssertEqual(localChild["OMI_API_BASE_URL"], "http://127.0.0.1:18081/v2")

    let deployedTuple = [
      "OMI_PYTHON_API_URL": "https://api.omiapi.com",
      "OMI_DESKTOP_API_URL": "https://desktop-backend-dt5lrfkkoa-uc.a.run.app",
      "OMI_AUTH_API_URL": "https://api.omiapi.com",
      "OMI_ENV_STAGE": "dev",
    ]
    let deployedChild = AgentRuntimeProcess.childBackendRoutingEnvironment(
      baseEnvironment: deployedTuple,
      rustBase: "https://desktop-backend-dt5lrfkkoa-uc.a.run.app/"
    )
    XCTAssertEqual(deployedChild["OMI_PYTHON_API_URL"], "https://api.omiapi.com")
    XCTAssertEqual(deployedChild["OMI_AUTH_API_URL"], "https://api.omiapi.com")
    XCTAssertEqual(
      deployedChild["OMI_API_BASE_URL"],
      "https://desktop-backend-dt5lrfkkoa-uc.a.run.app/v2"
    )
    XCTAssertFalse(deployedChild.values.contains { $0.contains("api.omi.me") })
  }

  @MainActor
  func testUsableByokEnvironmentSuppressesAllKeysWhenOneProviderIsKnownBad() {
    let savedSelectedProvider = UserDefaults.standard.string(forKey: .byokLLMProvider)
    let savedKeys = Dictionary(
      uniqueKeysWithValues: BYOKProvider.allCases.map { provider in
        (provider, UserDefaults.standard.string(forKey: provider.storageKey))
      })
    let savedFingerprints = APIKeyService.enrolledFingerprints()
    defer {
      for provider in BYOKProvider.allCases {
        if let saved = savedKeys[provider] ?? nil {
          UserDefaults.standard.set(saved, forKey: provider.storageKey)
        } else {
          UserDefaults.standard.removeObject(forKey: provider.storageKey)
        }
      }
      CredentialHealthManager.shared.reset()
      APIKeyService.persistEnrolledFingerprints([:])
      if let savedSelectedProvider {
        UserDefaults.standard.set(savedSelectedProvider, forKey: .byokLLMProvider)
      } else {
        UserDefaults.standard.removeObject(forKey: .byokLLMProvider)
      }
      APIKeyService.persistEnrolledFingerprints(savedFingerprints)
    }

    for provider in BYOKProvider.allCases {
      UserDefaults.standard.set("sk-agent-\(provider.rawValue)", forKey: provider.storageKey)
    }
    APIKeyService.persistEnrolledFingerprints(
      Dictionary(
        uniqueKeysWithValues: BYOKProvider.allCases.map {
          ($0.rawValue, APIKeyService.byokFingerprint("sk-agent-\($0.rawValue)"))
        }))
    UserDefaults.standard.set(BYOKLLMProvider.openai.rawValue, forKey: .byokLLMProvider)
    let openAIKey = APIKeyService.byokKey(.openai)!
    // usableBYOKEnvironment() gates on isByokActive, which requires the
    // selected provider's key to be enrolled (#11454's fingerprint contract),
    // separately from the per-request health suppression this test exercises.
    APIKeyService.persistEnrolledFingerprints([
      BYOKProvider.openai.rawValue: APIKeyService.byokFingerprint(openAIKey)
    ])
    CredentialHealthManager.shared.recordProviderFailure(
      .providerAuthFailed(provider: .openai, mode: .byok),
      provider: .openai,
      authMode: .byok,
      fingerprint: APIKeyService.byokFingerprint(openAIKey),
      context: "test")

    let result = AgentRuntimeProcess.usableBYOKEnvironment()

    XCTAssertTrue(result.values.isEmpty)
    XCTAssertEqual(result.suppressedProviders, [.openai])
  }

  @MainActor
  func testUsableByokEnvironmentIncludesAllKeysWhenAllProvidersAreUsable() {
    let savedSelectedProvider = UserDefaults.standard.string(forKey: .byokLLMProvider)
    let savedKeys = Dictionary(
      uniqueKeysWithValues: BYOKProvider.allCases.map { provider in
        (provider, UserDefaults.standard.string(forKey: provider.storageKey))
      })
    let savedFingerprints = APIKeyService.enrolledFingerprints()
    defer {
      for provider in BYOKProvider.allCases {
        if let saved = savedKeys[provider] ?? nil {
          UserDefaults.standard.set(saved, forKey: provider.storageKey)
        } else {
          UserDefaults.standard.removeObject(forKey: provider.storageKey)
        }
      }
      CredentialHealthManager.shared.reset()
      APIKeyService.persistEnrolledFingerprints([:])
      if let savedSelectedProvider {
        UserDefaults.standard.set(savedSelectedProvider, forKey: .byokLLMProvider)
      } else {
        UserDefaults.standard.removeObject(forKey: .byokLLMProvider)
      }
      APIKeyService.persistEnrolledFingerprints(savedFingerprints)
    }

    for provider in BYOKProvider.allCases {
      UserDefaults.standard.set("sk-agent-\(provider.rawValue)", forKey: provider.storageKey)
    }
    APIKeyService.persistEnrolledFingerprints(
      Dictionary(
        uniqueKeysWithValues: BYOKProvider.allCases.map {
          ($0.rawValue, APIKeyService.byokFingerprint("sk-agent-\($0.rawValue)"))
        }))
    UserDefaults.standard.set(BYOKLLMProvider.openrouter.rawValue, forKey: .byokLLMProvider)
    // usableBYOKEnvironment() gates on isByokActive, which requires the
    // selected provider's key to be enrolled (#11454's fingerprint contract).
    APIKeyService.persistEnrolledFingerprints([
      BYOKProvider.openrouter.rawValue: APIKeyService.byokFingerprint("sk-agent-openrouter")
    ])

    let result = AgentRuntimeProcess.usableBYOKEnvironment()

    XCTAssertEqual(result.values[AgentRuntimeProcess.byokEnvironmentKey(for: .openrouter)], "sk-agent-openrouter")
    XCTAssertEqual(result.values[AgentRuntimeProcess.byokEnvironmentKey(for: .deepgram)], "sk-agent-deepgram")
    XCTAssertNil(result.values[AgentRuntimeProcess.byokEnvironmentKey(for: .openai)])
    XCTAssertNil(result.values[AgentRuntimeProcess.byokEnvironmentKey(for: .anthropic)])
    XCTAssertNil(result.values[AgentRuntimeProcess.byokEnvironmentKey(for: .gemini)])
    XCTAssertTrue(result.suppressedProviders.isEmpty)
  }

  func testRemoveInheritedByokEnvironmentScrubsPrefixCaseInsensitively() {
    var env = [
      "OMI_BYOK_OPENAI": "stale-openai",
      "omi_byok_experimental": "stale-experimental",
      "OmI_bYoK_LEGACY": "stale-legacy",
      "OMI_AUTH_TOKEN": "token",
      "PATH": "/usr/bin",
    ]

    AgentRuntimeProcess.removeInheritedBYOKEnvironment(from: &env)

    XCTAssertNil(env["OMI_BYOK_OPENAI"])
    XCTAssertNil(env["omi_byok_experimental"])
    XCTAssertNil(env["OmI_bYoK_LEGACY"])
    XCTAssertEqual(env["OMI_AUTH_TOKEN"], "token")
    XCTAssertEqual(env["PATH"], "/usr/bin")
  }

  func testPiMonoStartupRefreshesAuthTokenAndFiltersByokEnvironment() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)
    let whitespaceNormalizedSource = source.split(whereSeparator: \.isWhitespace).joined(separator: " ")

    XCTAssertTrue(source.contains("Self.removeInheritedBYOKEnvironment(from: &env)"))
    XCTAssertTrue(source.contains("let byok = await Self.usableBYOKEnvironment()"))
    XCTAssertTrue(
      whitespaceNormalizedSource.contains(
        "let forceRefreshToken = preferredAdapterId == .piMono "
          + "&& AgentRuntimeCredentialPolicy.shouldForceRefreshAtStartup("
      ))
    XCTAssertTrue(source.contains("isDesktopLocalProfile: DesktopLocalProfile.isEnabled"))
    XCTAssertTrue(source.contains("getAuthHeader("))
    XCTAssertTrue(source.contains("forceRefresh: forceRefreshToken"))
    XCTAssertTrue(source.contains("expectedUserId: authorizationSnapshot.ownerID"))
    XCTAssertFalse(
      source.contains(
        "log(\"AgentRuntimeProcess: pi-mono BYOK active, forwarding \\(BYOKProvider.allCases.count) user keys\")"))
    XCTAssertTrue(source.contains("forwarding \\(byok.values.count) usable user keys"))
  }

  func testOpenClawAdapterCommandUsesSiblingNodeWhenAvailable() throws {
    let tempDir = FileManager.default.temporaryDirectory
      .appendingPathComponent("openclaw-command-\(UUID().uuidString)", isDirectory: true)
    try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
    defer { try? FileManager.default.removeItem(at: tempDir) }

    let nodePath = tempDir.appendingPathComponent("node").path
    let openClawPath = tempDir.appendingPathComponent("openclaw").path
    FileManager.default.createFile(atPath: nodePath, contents: Data("#!/bin/sh\n".utf8))
    FileManager.default.createFile(atPath: openClawPath, contents: Data("#!/usr/bin/env node\n".utf8))
    try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: nodePath)
    try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: openClawPath)

    let command = AgentRuntimeProcess.openClawAdapterCommand(openClawPath: openClawPath)

    XCTAssertEqual(command, "'\(nodePath)' '\(openClawPath)' acp")
  }

  func testOpenClawAdapterCommandFallsBackToLauncherWithoutSiblingNode() throws {
    let tempDir = FileManager.default.temporaryDirectory
      .appendingPathComponent("openclaw-command-\(UUID().uuidString)", isDirectory: true)
    try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
    defer { try? FileManager.default.removeItem(at: tempDir) }

    let openClawPath = tempDir.appendingPathComponent("openclaw").path
    FileManager.default.createFile(atPath: openClawPath, contents: Data("#!/usr/bin/env node\n".utf8))
    try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: openClawPath)

    let command = AgentRuntimeProcess.openClawAdapterCommand(openClawPath: openClawPath)

    XCTAssertEqual(command, "'\(openClawPath)' acp")
  }

  func testOpenClawDiscoveryFindsXDGFnmInstall() throws {
    let home = FileManager.default.temporaryDirectory
      .appendingPathComponent("openclaw-fnm-home-\(UUID().uuidString)", isDirectory: true)
    defer { try? FileManager.default.removeItem(at: home) }

    let bin =
      home
      .appendingPathComponent(".local/share/fnm/node-versions/v24.12.0/installation/bin", isDirectory: true)
    try FileManager.default.createDirectory(at: bin, withIntermediateDirectories: true)
    let openClaw = bin.appendingPathComponent("openclaw")
    FileManager.default.createFile(atPath: openClaw.path, contents: Data("#!/bin/sh\n".utf8))
    try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: openClaw.path)

    let directories = AgentRuntimeProcess.localAdapterSearchDirectories(home: home.path)
    let discovered = AgentRuntimeProcess.firstExecutable(named: "openclaw", in: directories)

    XCTAssertEqual(discovered, openClaw.path)
    XCTAssertLessThan(
      try XCTUnwrap(directories.firstIndex(of: openClaw.deletingLastPathComponent().path)),
      try XCTUnwrap(directories.firstIndex(of: "/opt/homebrew/bin")),
      "A home-scoped FNM installation must take precedence over machine-wide Homebrew."
    )
  }

  func testStdoutReaderIsEventDrivenInsteadOfDetachedAvailableDataLoop() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    let readerStart = try XCTUnwrap(source.range(of: "private func startReadingStdout()"))
    let readerEnd = try XCTUnwrap(source.range(of: "private func processStdoutData("))
    let reader = String(source[readerStart.lowerBound..<readerEnd.lowerBound])

    XCTAssertTrue(reader.contains("handle.readabilityHandler = { [weak self] handle in"))
    // The implementation now uses a generation-guarded signature; match the current
    // function name without coupling the test to the exact parameter list.
    XCTAssertTrue(source.contains("func processStdoutData("))
    XCTAssertFalse(reader.contains("Task.detached { [weak self] in"))
    XCTAssertFalse(reader.contains("while !Task.isCancelled"))
  }

  func testStdoutChunksAreReorderedBeforeJSONLFraming() {
    let frame =
      Data(
        #"{"type":"context_snapshot","protocolVersion":2,"requestId":"context-1","clientId":"client-1","ownerId":"owner-1","snapshot":{}}"#
          .utf8
      ) + Data([UInt8(ascii: "\n")])
    let split = frame.count / 2
    let first = Data(frame[..<split])
    let second = Data(frame[split...])
    var buffer = AgentRuntimeOrderedStdoutBuffer()

    XCTAssertTrue(buffer.ingest(second, sequence: 1).isEmpty)
    let lines = buffer.ingest(first, sequence: 0)
    let parsed = lines.compactMap { lineData -> AgentRuntimeProcess.RuntimeMessage? in
      guard let line = String(data: lineData, encoding: .utf8) else { return nil }
      return AgentRuntimeProcess.RuntimeMessage.parse(line)
    }

    XCTAssertEqual(lines.count, 1)
    XCTAssertEqual(parsed.count, 1, "ordered delivery must produce zero malformed JSONL frames")
    XCTAssertEqual(parsed.first?.kind, .contextSnapshot)
    XCTAssertEqual(parsed.first?.requestId, "context-1")
  }

  func testFailedRuntimeStartLeavesTypedRecoverableLifecycleState() {
    var lifecycle = AgentRuntimeBridgeLifecycle()
    XCTAssertEqual(lifecycle.reduce(.spawn), [.launchBridge])
    XCTAssertEqual(
      lifecycle.reduce(.spawnFailure(.exitedDuringStartup)),
      [.surfaceFailedStart(.exitedDuringStartup)])
    XCTAssertEqual(lifecycle.state, .failedStart)
    XCTAssertEqual(lifecycle.startFailure, .exitedDuringStartup)
    XCTAssertFalse(lifecycle.acceptsWALFrames)
  }

  func testProcessExitBeforeInitUsesTypedFailedStartRetryDisposition() {
    var lifecycle = AgentRuntimeBridgeLifecycle()
    XCTAssertEqual(lifecycle.reduce(.spawn), [.launchBridge])

    let failure = AgentRuntimeProcess.startFailure(for: BridgeError.processExited)
    XCTAssertEqual(failure, .exitedDuringStartup)
    XCTAssertEqual(
      lifecycle.reduce(.spawnFailure(failure)),
      [.surfaceFailedStart(.exitedDuringStartup)],
      "the production termination path emits this effect before it resumes the pending init waiter")
    XCTAssertEqual(lifecycle.state, .failedStart)
    XCTAssertEqual(lifecycle.startFailure, .exitedDuringStartup)
    XCTAssertFalse(lifecycle.acceptsWALFrames)
  }

  func testSharedRestartUsesReducerOwnedDrainAndRestartStates() {
    var lifecycle = AgentRuntimeBridgeLifecycle()
    _ = lifecycle.reduce(.spawn)
    _ = lifecycle.reduce(.handshakeSucceeded)
    XCTAssertEqual(lifecycle.reduce(.modeSwitchRequested), [.beginDrain])
    XCTAssertEqual(lifecycle.reduce(.drainRequested), [.beginDrain])
    XCTAssertEqual(lifecycle.state, .draining)
    _ = lifecycle.reduce(.kill)
    XCTAssertEqual(lifecycle.reduce(.restart), [.restartBridge])
    XCTAssertEqual(lifecycle.state, .restarting)
  }

  func testAbandonedRestartAlwaysLeavesDrainStateRestartable() {
    var lifecycle = AgentRuntimeBridgeLifecycle()
    _ = lifecycle.reduce(.spawn)
    _ = lifecycle.reduce(.handshakeSucceeded)
    _ = lifecycle.reduce(.modeSwitchRequested)
    _ = lifecycle.reduce(.drainRequested)
    XCTAssertEqual(lifecycle.state, .draining)

    // `AgentRuntimeProcess.restart` takes this path if its initiating client
    // unregisters or is cancelled after it begins draining. The reducer must
    // not leave the shared daemon wedged behind that departed client.
    XCTAssertEqual(lifecycle.reduce(.kill), [.closeWAL])
    XCTAssertEqual(lifecycle.state, .stopped)
    XCTAssertEqual(lifecycle.reduce(.spawn), [.launchBridge])
    XCTAssertEqual(lifecycle.state, .starting)
  }

  func testStartupAdmissionLaunchesTheFirstBridgeAndJoinsOnlyAnActiveFlight() {
    XCTAssertFalse(
      AgentRuntimeStartupAdmission.shouldJoin(
        lifecycleState: .stopped,
        hasActiveStartupAttempt: false))
    XCTAssertFalse(
      AgentRuntimeStartupAdmission.shouldJoin(
        lifecycleState: .starting,
        hasActiveStartupAttempt: false),
      "the launch owner marks the reducer starting before its flight is installed")
    XCTAssertTrue(
      AgentRuntimeStartupAdmission.shouldJoin(
        lifecycleState: .starting,
        hasActiveStartupAttempt: true))
    XCTAssertTrue(
      AgentRuntimeStartupAdmission.shouldJoin(
        lifecycleState: .running,
        hasActiveStartupAttempt: false))
  }

  func testAppSurfacesUseDirectControlToolOnly() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    XCTAssertFalse(source.contains("func requestScopedControlTool("))
    XCTAssertFalse(source.contains(#""type": "control_tool""#))
    XCTAssertTrue(source.contains("func directControlTool("))
    XCTAssertTrue(source.contains("activeControlRequests[requestKey]"))
    XCTAssertTrue(source.contains("completeControlRequest(message)"))
    XCTAssertTrue(source.contains("if !sent, let request = takeActiveControlRequest(requestKey)"))
    XCTAssertTrue(source.contains("failure.map(BridgeError.agentRuntimeFailure) ?? BridgeError.agentError(raw)"))
    XCTAssertTrue(source.contains("request.continuation.resume(returning: queryResult(from: message))"))
    XCTAssertFalse(source.contains(#"terminalStatus: payload["terminalStatus"] as? String ?? "succeeded""#))
  }

  func testDirectControlToolRequestsUseDedicatedSignedInOwnerEnvelope() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    XCTAssertTrue(source.contains("func directControlTool("))
    XCTAssertTrue(source.contains("RuntimeOwnerIdentity.captureAuthorizationSnapshot()"))
    XCTAssertTrue(source.contains("try assertAuthorization(authorizationSnapshot)"))
    XCTAssertTrue(source.contains("advertisedAgentControlTools.contains(name)"))
    XCTAssertTrue(source.contains("Agent runtime does not advertise direct control tool"))
    XCTAssertTrue(source.contains(#""type": "direct_control_tool""#))
    XCTAssertTrue(source.contains(#""ownerId": ownerId"#))
    XCTAssertTrue(source.contains("let expectedOwnerId: String"))
    XCTAssertTrue(source.contains("let expectedOwnerEpoch: UInt64"))
    XCTAssertTrue(source.contains("resultOwnerId == expectedOwnerId"))
    XCTAssertTrue(source.contains("currentOwnerId == expectedOwnerId"))
    XCTAssertTrue(source.contains("currentOwnerEpoch == expectedOwnerEpoch"))
  }

  func testAuthorizedToolResultsEchoExactLedgerTupleWithoutRequestScope() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    XCTAssertTrue(source.contains("completeAuthorizedToolExecution("))
    XCTAssertTrue(source.contains(#""type": "authorized_tool_execution_result""#))
    XCTAssertTrue(source.contains(#""invocationId": command.invocationID"#))
    XCTAssertTrue(source.contains(#""profileGeneration": command.profileGeneration"#))
    XCTAssertTrue(source.contains(#""manifestDigest": command.manifestDigest"#))
    XCTAssertTrue(source.contains(#""daemonBootEpoch": command.daemonBootEpoch"#))
    XCTAssertTrue(source.contains(#""executionGeneration": command.executionGeneration"#))
    XCTAssertTrue(source.contains(#""inputHash": command.inputHash"#))
    XCTAssertFalse(source.contains(#""requestId": command."#))
    XCTAssertFalse(source.contains(#""clientId": command."#))
  }

  func testStartupTimeoutResumesInitContinuations() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    XCTAssertTrue(source.contains("resumeInitContinuations(throwing: BridgeError.timeout)"))
    XCTAssertFalse(source.contains("withThrowingTaskGroup(of: Void.self)"))
  }

  func testOutOfMemoryDiagnosticRequiresConfirmedRuntimeSignature() {
    XCTAssertTrue(
      AgentRuntimeProcess.isConfirmedOutOfMemoryDiagnostic(
        "FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory"
      )
    )
    XCTAssertTrue(
      AgentRuntimeProcess.isConfirmedOutOfMemoryDiagnostic(
        "FatalProcessOutOfMemory: Zone Allocation failed"
      )
    )
    XCTAssertTrue(
      AgentRuntimeProcess.isConfirmedOutOfMemoryDiagnostic(
        "Failed to reserve virtual memory for CodeRange"
      )
    )

    XCTAssertFalse(
      AgentRuntimeProcess.isConfirmedOutOfMemoryDiagnostic(
        "Provider returned: the requested model is out of memory for this prompt"
      )
    )
    XCTAssertFalse(
      AgentRuntimeProcess.isConfirmedOutOfMemoryDiagnostic(
        "The browser extension reported out of memory while reading a page"
      )
    )
  }

  func testRuntimeDoesNotTreatGenericAbortSignalsAsOutOfMemory() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    XCTAssertTrue(
      source.contains("let likelyOOM = lastExitWasOOM || oomDiagnosticLatch.isConfirmed(generation: processGeneration)")
    )
    XCTAssertFalse(source.contains("exitCode == 134"))
    XCTAssertFalse(source.contains("exitCode == 133"))
  }

  func testStderrOutOfMemoryLatchIsSynchronousAndGenerationScoped() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    XCTAssertTrue(source.contains("oomDiagnosticLatch.markIfConfirmed(text, generation: expectedGeneration)"))
    XCTAssertTrue(source.contains("private final class AgentRuntimeOOMDiagnosticLatch: @unchecked Sendable"))
    XCTAssertTrue(source.contains("guard self.generation == generation else { return }"))
    XCTAssertFalse(source.contains("Task { await self?.markOOM"))
  }

  func testIntentionalStopInvalidatesOldProcessGenerationBeforeTerminating() throws {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources/Chat/AgentRuntimeProcess.swift")
    let source = try String(contentsOf: sourceURL, encoding: .utf8)

    let stopStart = try XCTUnwrap(
      source.range(
        of: "private func stopProcess(resumeRequestsWith error: BridgeError) async"))
    let stopEnd = try XCTUnwrap(
      source.range(
        of: "private func startReadingStdout()",
        range: stopStart.upperBound..<source.endIndex))
    let stopBody = String(source[stopStart.lowerBound..<stopEnd.lowerBound])
    XCTAssertTrue(stopBody.contains("await cancelAndDrainAuthorizedToolExecutionTasks()"))
    XCTAssertTrue(stopBody.contains("markRuntimeOwnerAuthorityDirty()"))
    let generationAdvance = try XCTUnwrap(stopBody.range(of: "processGeneration &+= 1"))
    let gracefulStop = try XCTUnwrap(stopBody.range(of: "sendJson([\"type\": \"stop\"])"))
    let terminate = try XCTUnwrap(stopBody.range(of: "proc?.terminate()"))
    XCTAssertLessThan(generationAdvance.lowerBound, gracefulStop.lowerBound)
    XCTAssertLessThan(generationAdvance.lowerBound, terminate.lowerBound)
  }

  func testIsAliveRequiresUnderlyingProcessRunning() throws {
    let source = try agentRuntimeSource()
    XCTAssertTrue(source.contains("let processRunning = process?.isRunning ?? false"))
    XCTAssertTrue(source.contains("return processRunning"))
    XCTAssertTrue(source.contains("recordAgentRuntimeStaleAliveCheck"))
  }

  func testUnexpectedExitRecordsHealthEvent() throws {
    let source = try agentRuntimeSource()
    XCTAssertTrue(source.contains("recordAgentRuntimeUnexpectedExit"))
    XCTAssertTrue(source.contains("recovery_action=restart_on_next_send"))
  }

  func testEnsureBridgeStartedPreparesCrashRecoveryBeforeRestart() throws {
    let chatSource = try sourceFile("Providers/ChatProvider.swift")
    XCTAssertTrue(chatSource.contains("prepareForCrashRecovery()"))
    XCTAssertTrue(chatSource.contains("agent bridge process died, will restart"))

    let bridgeSource = try sourceFile("Chat/AgentBridge.swift")
    XCTAssertTrue(bridgeSource.contains("func prepareForCrashRecovery()"))
    XCTAssertTrue(bridgeSource.contains("registered = false"))
  }

  func testContextAdmissionMismatchRefreshesCompleteFreshnessAndRetriesOnce() async throws {
    let initial = AgentContextFreshness(
      version: "snapshot-v1",
      generation: 7,
      rendererFingerprint: "renderer-v1",
      capabilityVersion: "capabilities-v1"
    )
    let refreshed = AgentContextFreshness(
      version: "snapshot-v2",
      generation: 8,
      rendererFingerprint: "renderer-v2",
      capabilityVersion: "capabilities-v2"
    )
    let state = ContextAdmissionRetryTestState()

    let gate = AgentContextAdmissionGate()
    let result: String = try await AgentContextAdmissionRetry.run(
      expectedContext: initial,
      gate: gate,
      refresh: {
        await state.recordRefresh()
        return refreshed
      },
      attempt: { context in
        let attemptNumber = await state.recordAttempt(context)
        if attemptNumber == 1 {
          throw Self.contextProjectionMismatchBridgeError()
        }
        return "admitted"
      }
    )

    let snapshot = await state.snapshot()
    XCTAssertEqual(result, "admitted")
    XCTAssertEqual(snapshot.refreshCount, 1)
    XCTAssertEqual(snapshot.attempts, [initial, refreshed])
  }

  func testContextAdmissionGateConvergesAfterWarmupContextAdvance() async throws {
    let harness = ContextProjectionRaceHarness()
    await harness.record("warmup")
    let warmupContext = await harness.freshness()
    await harness.advance("context_advanced_between_warmup_and_admission")

    let gate = AgentContextAdmissionGate()
    let queuedAdvance = ContextProjectionTaskBox()
    let admission = Task { () throws -> (String, [String]) in
      await queuedAdvance.store(
        Task {
          do {
            try await gate.withExclusiveAccess {
              await harness.advance("context_advanced_during_admission")
            }
          } catch {
            // Cancellation while waiting for the gate is expected in some races.
          }
        })
      await Task.yield()

      let result: String = try await AgentContextAdmissionRetry.run(
        expectedContext: warmupContext,
        gate: gate,
        refresh: { await harness.freshness() },
        attempt: { candidate in
          _ = await harness.recordAdmissionAttempt()
          let currentContext = await harness.freshness()
          guard candidate == currentContext else {
            throw BridgeError.agentError("context_snapshot_projection_mismatch")
          }
          return "admitted"
        }
      )
      return (result, await harness.snapshot())
    }

    let (result, eventsInsideAdmission) = try await admission.value
    await queuedAdvance.wait()

    XCTAssertEqual(result, "admitted")
    XCTAssertEqual(
      eventsInsideAdmission,
      [
        "warmup",
        "context_advanced_between_warmup_and_admission",
        "context_advanced_during_admission",
        "admission_attempt_1",
        "admission_attempt_2",
      ],
      "refresh+admit stay under the gate; queued writers may advance during attempts outside it"
    )
    let finalEvents = await harness.snapshot()
    XCTAssertEqual(finalEvents.last, "admission_attempt_2")
  }

  /// The interleaving the two gate-hold tests below hit when the signalling task wins
  /// the race: an edge-triggered probe drops both signals and suspends here forever.
  func testGateHoldProbeObservesSignalsDeliveredBeforeItsWaitersSuspend() async {
    let holdProbe = GateHoldProbe()

    await holdProbe.signalEntered()
    await holdProbe.release()

    await holdProbe.waitUntilEntered()
    await holdProbe.waitUntilReleased()
  }

  func testContextAdmissionGateCancelledWaiterDoesNotStealTurn() async throws {
    let gate = AgentContextAdmissionGate()
    final class CancelledWaiterProbe: @unchecked Sendable {
      var acquiredGate = false
    }
    let cancelledWaiterProbe = CancelledWaiterProbe()
    let enteredOrder = GateAdmissionOrderProbe()
    let holdProbe = GateHoldProbe()

    let first = Task {
      try await gate.withExclusiveAccess {
        await enteredOrder.append("first")
        await holdProbe.signalEntered()
        await holdProbe.waitUntilReleased()
        return "first"
      }
    }

    await holdProbe.waitUntilEntered()

    let second = Task {
      _ = try? await gate.withExclusiveAccess {
        cancelledWaiterProbe.acquiredGate = true
        await enteredOrder.append("second")
        return "second"
      }
    }
    second.cancel()

    let third = Task {
      try await gate.withExclusiveAccess {
        await enteredOrder.append("third")
        return "third"
      }
    }

    await holdProbe.release()
    let thirdResult = try await third.value
    XCTAssertEqual(thirdResult, "third")
    let firstResult = try await first.value
    XCTAssertEqual(firstResult, "first")
    XCTAssertFalse(cancelledWaiterProbe.acquiredGate)
    let order = await enteredOrder.snapshot()
    XCTAssertEqual(order, ["first", "third"])
    _ = await second.result
  }

  func testContextAdmissionGateCancellationAfterGrantResumesWaiterOnce() async throws {
    let raceProbe = GateGrantCancellationRaceProbe()
    let gate = AgentContextAdmissionGate(
      onWaiterRegistered: { raceProbe.signalWaiterRegistered() },
      beforeResumingGrantedWaiter: { raceProbe.pauseGrantedHandoff() }
    )
    let holdProbe = GateHoldProbe()

    let first = Task {
      try await gate.withExclusiveAccess {
        await holdProbe.signalEntered()
        await holdProbe.waitUntilReleased()
      }
    }
    await holdProbe.waitUntilEntered()

    let second = Task {
      _ = try? await gate.withExclusiveAccess {}
    }
    await raceProbe.waitUntilWaiterRegistered()

    await holdProbe.release()
    await raceProbe.waitUntilGrantPaused()
    second.cancel()
    raceProbe.resumeGrantedHandoff()

    try await first.value
    _ = await second.result
    let third: String = try await gate.withExclusiveAccess { "third" }
    XCTAssertEqual(third, "third")
  }

  func testContextAdmissionSecondMismatchFailsWithoutAnotherRefreshOrRetry() async {
    let initial = AgentContextFreshness(
      version: "snapshot-v1",
      generation: 11,
      rendererFingerprint: "renderer-v1",
      capabilityVersion: "capabilities-v1"
    )
    let refreshed = AgentContextFreshness(
      version: "snapshot-v2",
      generation: 12,
      rendererFingerprint: "renderer-v2",
      capabilityVersion: "capabilities-v2"
    )
    let state = ContextAdmissionRetryTestState()

    let gate = AgentContextAdmissionGate()
    do {
      let _: String = try await AgentContextAdmissionRetry.run(
        expectedContext: initial,
        gate: gate,
        refresh: {
          await state.recordRefresh()
          return refreshed
        },
        attempt: { context in
          _ = await state.recordAttempt(context)
          throw Self.contextProjectionMismatchBridgeError()
        }
      )
      XCTFail("expected the second projection mismatch to fail closed")
    } catch let error as BridgeError {
      XCTAssertTrue(error.isContextSnapshotProjectionMismatch)
    } catch {
      XCTFail("unexpected error: \(error)")
    }

    let snapshot = await state.snapshot()
    XCTAssertEqual(snapshot.refreshCount, 1)
    XCTAssertEqual(snapshot.attempts, [initial, refreshed])
  }

  func testSessionQueryUsesGatedRetryWithoutHoldingGateForStreaming() throws {
    let source = try sourceFile("Chat/AgentClient.swift")
    let sessionQueryStart = try XCTUnwrap(
      source.range(of: "func query(\n      prompt: String,\n      session: AgentSurfaceSession,"))
    let sessionQueryEnd = try XCTUnwrap(
      source.range(of: "  static func makeSession", range: sessionQueryStart.upperBound..<source.endIndex))
    let sessionQueryBody = String(source[sessionQueryStart.lowerBound..<sessionQueryEnd.lowerBound])
    XCTAssertTrue(sessionQueryBody.contains("AgentContextAdmissionRetry.run("))
    XCTAssertFalse(
      sessionQueryBody.contains(
        "withContextAdmissionAccess {\n        try Task.checkCancellation()\n        return QueryResult("),
      "streaming query must not hold the admission gate for the entire bridge.query call"
    )
  }

  func testContextAdmissionMismatchClassifierRequiresExactRuntimeCode() {
    XCTAssertTrue(contextProjectionMismatchError().isContextSnapshotProjectionMismatch)
    XCTAssertFalse(
      BridgeError.agentError("prefix context_snapshot_projection_mismatch suffix")
        .isContextSnapshotProjectionMismatch
    )
    XCTAssertFalse(
      BridgeError.agentRuntimeFailure(
        AgentRuntimeFailure(
          code: "runtime_query_failed",
          userMessage: "context_snapshot_projection_mismatch",
          technicalMessage: nil,
          source: "adapter_execution",
          adapterId: nil,
          provider: nil,
          retryable: false
        )
      ).isContextSnapshotProjectionMismatch
    )
  }

  private func contextProjectionMismatchError() -> BridgeError {
    Self.contextProjectionMismatchBridgeError()
  }

  private static func contextProjectionMismatchBridgeError() -> BridgeError {
    .agentRuntimeFailure(
      AgentRuntimeFailure(
        code: "runtime_query_failed",
        userMessage: "context_snapshot_projection_mismatch",
        technicalMessage: "context_snapshot_projection_mismatch",
        source: "runtime",
        adapterId: nil,
        provider: nil,
        retryable: false
      ))
  }

  private func agentRuntimeSource() throws -> String {
    try sourceFile("Chat/AgentRuntimeProcess.swift")
  }

  private func sourceFile(_ relativePath: String) throws -> String {
    let sourceURL = URL(fileURLWithPath: #filePath)
      .deletingLastPathComponent()
      .deletingLastPathComponent()
      .appendingPathComponent("Sources")
      .appendingPathComponent(relativePath)
    return try String(contentsOf: sourceURL, encoding: .utf8)
  }
}