mstro-app 0.4.52 → 0.5.1

package/server/services/plan/review-gate.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Review Gate — AI-powered quality gate for completed issues.
@@ -13,16 +12,19 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { join } from 'node:path';
 import { ResilientRunner } from '../../cli/headless/resilient-runner.js';
 import { loadAgentPrompt } from './agent-loader.js';
+import { getBoardReviewCriteria, resolveActiveBoardId } from './board-config.js';
 import { resolveIsCodeTask } from './issue-classification.js';
+import { appendCancellationNote, type WarnFn } from './issue-writer.js';
+import { resolveOutputPath } from './output-manager.js';
 import type { Issue, ReviewCheck, ReviewResult } from './types.js';
 
 /** Max review attempts per issue per sprint before giving up */
 export const MAX_REVIEW_ATTEMPTS = 3;
 
-/** Review runner stall timeouts (ms) */
+/** Review runner stall timeouts (ms) — hard cap is a backstop that only fires after stall signals flag the run */
 const REVIEW_STALL_WARNING_MS = 300_000;   // 5 min
 const REVIEW_STALL_KILL_MS = 600_000;      // 10 min
-const REVIEW_STALL_HARD_CAP_MS = 900_000;  // 15 min
+const REVIEW_STALL_HARD_CAP_MS = 2_700_000; // 45 min backstop
 
 export interface ReviewIssueOptions {
   workingDir: string;
@@ -244,3 +246,100 @@ function buildReviewPrompt(
   return `You are a reviewer. Review the work done for issue ${issue.id}: ${issue.title}.\n\n## Acceptance Criteria\n${criteriaStr}\n\nOutput EXACTLY one JSON object on its own line (no markdown fencing):\n{"passed": true, "checks": [{"name": "criteria_met", "passed": true, "details": "..."}]}`;
 }
 
+// ── Review pipeline orchestration ───────────────────────────
+
+/** Status messages emitted during the review pipeline. */
+export type ReviewProgressStatus = 'reviewing' | 'passed' | 'failed' | 'max_attempts';
+
+/** Callbacks for the executor to observe review pipeline events. */
+export interface ReviewPipelineCallbacks {
+  /** Update an issue's front-matter status on disk. */
+  setStatus: (issuePath: string, status: string) => Promise<void>;
+  onOutput: (issueId: string, text: string) => void;
+  onReviewProgress: (issueId: string, status: ReviewProgressStatus) => void;
+  onIssueAbandoned: (issueId: string, reason: string, attempts: number) => void;
+  onIssueCompleted: (issue: Issue) => void;
+  onIssueError: (issueId: string, error: string) => void;
+  warn: WarnFn;
+}
+
+/** Configuration for running the full review pipeline for a single issue. */
+export interface ReviewPipelineOptions {
+  issue: Issue;
+  pmDir: string;
+  workingDir: string;
+  executionDir: string | null;
+  boardDir: string | null;
+  boardId: string | null;
+  extraEnv?: Record<string, string>;
+}
+
+/**
+ * Full review pipeline for a completed issue: attempt-count guard, status
+ * transitions, AI review, persistence, and event emission through the
+ * caller's callbacks. Returns `true` when the review passes and the issue is
+ * marked `done`, `false` otherwise (reverted, cancelled, or errored).
+ */
+export async function runReviewPipeline(
+  options: ReviewPipelineOptions,
+  callbacks: ReviewPipelineCallbacks,
+): Promise<boolean> {
+  const { issue, pmDir, workingDir, executionDir, boardDir, boardId, extraEnv } = options;
+  const reviewDir = boardDir ?? pmDir;
+  const attempts = getReviewAttemptCount(reviewDir, issue);
+
+  if (attempts >= MAX_REVIEW_ATTEMPTS) {
+    await callbacks.setStatus(issue.path, 'cancelled');
+    await appendCancellationNote(
+      pmDir,
+      issue,
+      `Cancelled after ${MAX_REVIEW_ATTEMPTS} failed reviews — issue may need restructuring`,
+      callbacks.warn,
+    );
+    callbacks.onReviewProgress(issue.id, 'max_attempts');
+    callbacks.onIssueAbandoned(
+      issue.id,
+      `Review failed ${MAX_REVIEW_ATTEMPTS} times — cancelled to unblock dependents`,
+      attempts,
+    );
+    callbacks.onOutput(issue.id, 'Review: max attempts reached, cancelling issue to unblock dependents');
+    return false;
+  }
+
+  await callbacks.setStatus(issue.path, 'in_review');
+  callbacks.onReviewProgress(issue.id, 'reviewing');
+
+  const outputPath = resolveOutputPath(issue, workingDir, boardDir);
+  const effectiveBoardId = boardId ?? resolveActiveBoardId(pmDir);
+  const reviewCriteria = await getBoardReviewCriteria(pmDir, effectiveBoardId, callbacks.warn);
+
+  const result = await reviewIssue({
+    workingDir: executionDir || workingDir,
+    issue,
+    pmDir,
+    outputPath,
+    onOutput: (text) => callbacks.onOutput(issue.id, text),
+    logDir: boardDir ? join(boardDir, 'logs') : undefined,
+    reviewCriteria,
+    boardDir,
+    extraEnv,
+  });
+  persistReviewResult(reviewDir, issue, result);
+
+  if (result.passed) {
+    await callbacks.setStatus(issue.path, 'done');
+    callbacks.onReviewProgress(issue.id, 'passed');
+    callbacks.onIssueCompleted(issue);
+    return true;
+  }
+
+  await callbacks.setStatus(issue.path, 'todo');
+  appendReviewFeedback(pmDir, issue, result);
+  callbacks.onReviewProgress(issue.id, 'failed');
+  callbacks.onIssueError(
+    issue.id,
+    `Review failed: ${result.checks.filter(c => !c.passed).map(c => c.name).join(', ')}`,
+  );
+  return false;
+}
+

package/server/services/plan/state-reconciler.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * State Reconciler — Recomputes STATE.md from individual issue files.

package/server/services/plan/types.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Plan Types — Project Plan Spec (PPS) data structures

package/server/services/plan/watcher.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Plan Watcher — Watches .mstro/pm/ directory for changes and broadcasts updates.

package/server/services/platform-credentials.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Platform Credentials — Token management for device authentication.

package/server/services/platform-token-lifecycle.ts

@@ -0,0 +1,171 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Token Lifecycle — refresh, verify, and auth-expired signaling for the
+ * platform device token. Extracted from PlatformConnection so the relay
+ * lifecycle (sockets, reconnect, heartbeat) and the auth lifecycle (token
+ * refresh, verify, expired-signal) can be reasoned about apart. The token
+ * lifecycle has its own clock (24h periodic check), its own remote endpoints
+ * (/refresh, /verify), and its own failure modes (revocation vs. transient
+ * network error) — none of which need to be in PlatformConnection.
+ */
+
+import {
+  getCredentials,
+  shouldRefreshToken,
+  updateCredentials,
+} from './platform-credentials.js'
+
+const PERIODIC_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+export interface TokenLifecycleDeps {
+  /** Platform base URL — used to compose /api/auth/device/{refresh,verify} */
+  platformUrl: string
+  /** Send a message upstream over the live relay socket (no-op if closed). */
+  send: (message: unknown) => void
+  /** Read the current relay connection ID at the moment auth-expired fires. */
+  getConnectionId: () => string | null
+}
+
+export class TokenLifecycle {
+  private intervalHandle: ReturnType<typeof setInterval> | null = null
+
+  constructor(private readonly deps: TokenLifecycleDeps) {}
+
+  /**
+   * Refresh the device token if it's older than the refresh interval.
+   * Returns `true` if the token is (still) valid after this call, `false`
+   * if refresh was attempted and rejected with an auth error — in which
+   * case the caller should surface an auth-expired signal to the web
+   * rather than silently reusing a dead token.
+   */
+  async maybeRefresh(): Promise<boolean> {
+    const creds = getCredentials()
+    if (!creds) return false
+    if (!shouldRefreshToken(creds)) return true
+
+    try {
+      const response = await fetch(`${this.deps.platformUrl}/api/auth/device/refresh`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${creds.token}`,
+          'Content-Type': 'application/json'
+        }
+      })
+
+      if (response.ok) {
+        const data = await response.json() as { accessToken: string }
+        updateCredentials({
+          token: data.accessToken,
+          lastRefreshedAt: new Date().toISOString()
+        })
+        return true
+      }
+      if (response.status === 401 || response.status === 403) {
+        console.warn(`[Platform] Token refresh failed — auth is expired (${response.status}). Run \`mstro login --force\`.`)
+        this.notifyAuthExpired()
+        return false
+      }
+      console.warn(`[Platform] Token refresh failed with status ${response.status}, will retry later`)
+      return true
+    } catch (err) {
+      console.warn('[Platform] Token refresh error:', err)
+      return true
+    }
+  }
+
+  /**
+   * Verify the current token against the platform. A rejection (401/403)
+   * means the token is permanently invalid (revoked, signing-key rotation,
+   * account deleted); the caller should stop looping reconnects and tell
+   * the user to run `mstro login --force`.
+   *
+   * Returns `true` when the token is valid or the verification endpoint
+   * is unreachable (we prefer false negatives to false positives — a
+   * network blip shouldn't force a re-login).
+   */
+  async verify(): Promise<boolean> {
+    const creds = getCredentials()
+    if (!creds?.token) return false
+    try {
+      const response = await fetch(`${this.deps.platformUrl}/api/auth/device/verify`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${creds.token}` },
+      })
+      if (response.status === 401 || response.status === 403) {
+        console.warn(`[Platform] Token verify rejected (${response.status}) — auth is expired.`)
+        return false
+      }
+      return true
+    } catch {
+      // Network error: treat as "probably valid" so a flaky connection
+      // doesn't force users to re-login. The WebSocket open itself will
+      // catch a truly bad token via the 4001 path.
+      return true
+    }
+  }
+
+  /**
+   * Surface an auth-expired condition to any paired web clients.
+   *
+   * Two cooperating paths deliver this signal — either alone is enough,
+   * both together cover every timing edge:
+   *
+   *   1. **CLI-initiated (this method):** we detected a 401 from the
+   *      `/refresh` or `/verify` endpoint *while the relay socket is
+   *      still open*. The injected `send` pushes the message upstream so
+   *      the server relays it to paired webs before the CLI closes.
+   *      A no-op if the socket is already closed.
+   *
+   *   2. **Server-initiated:** when the platform closes a CLI socket
+   *      with 4001 or 4008, `handleAuthClose` in `clientHandlers.ts`
+   *      broadcasts the same `clientAuthExpired` to paired webs. This
+   *      covers cases where the CLI never had a chance to detect the
+   *      rejection itself (e.g. token revoked while the socket was idle,
+   *      server-side token rotation).
+   *
+   * IMPORTANT: never route this through PlatformConnection's
+   * `onRelayedMessage` callback — that callback feeds INCOMING web→CLI
+   * requests into the local handler, which would treat
+   * `clientAuthExpired` as an unknown inbound request.
+   */
+  notifyAuthExpired(): void {
+    this.deps.send({
+      type: 'clientAuthExpired',
+      data: {
+        connectionId: this.deps.getConnectionId(),
+        message: 'The CLI\'s device token is invalid — run `mstro login --force` on the machine.',
+      },
+    })
+  }
+
+  /**
+   * Best-effort token verification, fired in parallel with the socket
+   * open so a slow verify endpoint never delays reconnect.
+   *
+   * Only runs when the token is stale enough that we'd be about to
+   * refresh anyway — keeps the hot path free of an extra network call.
+   * A truly-revoked token that slips past this check still hits 4001
+   * on the WebSocket, which also triggers `notifyAuthExpired`.
+   */
+  maybeVerifyInParallel(): void {
+    const creds = getCredentials()
+    if (!creds || !shouldRefreshToken(creds)) return
+    this.verify().then((valid) => {
+      if (!valid) this.notifyAuthExpired()
+    }).catch(() => { /* network error — rely on 4001 close path */ })
+  }
+
+  startPeriodicCheck(): void {
+    this.intervalHandle = setInterval(() => {
+      this.maybeRefresh()
+    }, PERIODIC_CHECK_INTERVAL_MS)
+  }
+
+  stopPeriodicCheck(): void {
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle)
+      this.intervalHandle = null
+    }
+  }
+}

package/server/services/platform.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Platform Connection Service
@@ -14,12 +13,8 @@ import { arch, hostname, type } from 'node:os'
 import { basename } from 'node:path'
 import { AnalyticsEvents, trackEvent } from './analytics.js'
 import { getClientId } from './client-id.js'
-import {
-  CLI_VERSION,
-  getCredentials,
-  shouldRefreshToken,
-  updateCredentials,
-} from './platform-credentials.js'
+import { CLI_VERSION, getCredentials } from './platform-credentials.js'
+import { TokenLifecycle } from './platform-token-lifecycle.js'
 import { captureException } from './sentry.js'
 
 /**
@@ -50,6 +45,27 @@ if (typeof WebSocket !== 'undefined') {
 // PLATFORM_URL is set via --server / --dev flag in mstro.js
 const DEFAULT_PLATFORM_URL = process.env.PLATFORM_URL || 'https://api.mstro.app'
 
+/**
+ * Relay wire-format version this CLI speaks. Bumped by the server when the
+ * relay protocol changes incompatibly. Must match (or exceed) the server's
+ * `minProtocolVersion` in `server/src/relay/version-policy.ts` — when the
+ * server's floor moves above this value, the upgrade handshake returns 426
+ * and the CLI surfaces the upgrade message via `handleSocketClose`.
+ *
+ * This is a build-time constant, not user-configurable: a stale CLI must be
+ * told to upgrade rather than allowed to opt itself into compatibility.
+ */
+const PROTOCOL_VERSION = 1
+
+/**
+ * Long sentinel delay used after a 426 protocol-too-old close. The CLI
+ * auto-upgrades on the next `mstro` invocation, so a tight reconnect loop
+ * would just hammer the server with rejections that policy already decided
+ * to refuse. One hour is long enough to count as "stop", short enough that
+ * a forgotten foreground process eventually retries on its own.
+ */
+const PROTOCOL_UPGRADE_RECONNECT_DELAY_MS = 60 * 60 * 1000
+
 interface ConnectionCallbacks {
   onConnected?: (connectionId: string) => void
   onDisconnected?: () => void
@@ -73,11 +89,12 @@ export class PlatformConnection {
   private callbacks: ConnectionCallbacks
   private connectionId: string | null = null
   private isConnected = false
-  private tokenRefreshInterval: ReturnType<typeof setInterval> | null = null
   private heartbeatInterval: ReturnType<typeof setInterval> | null = null
   private missedPongs = 0
   private everConnected = false
+  private protocolUpgradeRequired = false
   private readonly startedAt: string
+  private readonly tokens: TokenLifecycle
 
   constructor(
     workingDirectory: string,
@@ -88,39 +105,11 @@ export class PlatformConnection {
     this.platformUrl = platformUrl || DEFAULT_PLATFORM_URL
     this.callbacks = callbacks
     this.startedAt = new Date().toISOString()
-  }
-
-  private async maybeRefreshToken(): Promise<void> {
-    const creds = getCredentials()
-    if (!creds || !shouldRefreshToken(creds)) return
-
-    try {
-      const response = await fetch(`${this.platformUrl}/api/auth/device/refresh`, {
-        method: 'POST',
-        headers: {
-          'Authorization': `Bearer ${creds.token}`,
-          'Content-Type': 'application/json'
-        }
-      })
-
-      if (response.ok) {
-        const data = await response.json() as { accessToken: string }
-        updateCredentials({
-          token: data.accessToken,
-          lastRefreshedAt: new Date().toISOString()
-        })
-      } else {
-        console.warn('[Platform] Token refresh failed, will retry later')
-      }
-    } catch (err) {
-      console.warn('[Platform] Token refresh error:', err)
-    }
-  }
-
-  private startTokenRefreshCheck(): void {
-    this.tokenRefreshInterval = setInterval(() => {
-      this.maybeRefreshToken()
-    }, 24 * 60 * 60 * 1000)
+    this.tokens = new TokenLifecycle({
+      platformUrl: this.platformUrl,
+      send: (msg) => this.send(msg),
+      getConnectionId: () => this.connectionId,
+    })
   }
 
   private startHeartbeat(): void {
@@ -153,48 +142,18 @@ export class PlatformConnection {
     }
   }
 
-  private stopTokenRefreshCheck(): void {
-    if (this.tokenRefreshInterval) {
-      clearInterval(this.tokenRefreshInterval)
-      this.tokenRefreshInterval = null
-    }
-  }
-
   connect(): void {
     this.isIntentionallyClosed = false
-    const name = basename(this.workingDirectory)
-    const machineHostname = hostname()
-    const clientId = getClientId()
-    const machineId = getMachineIdentifier()
-    const nodeVersion = process.version
-    const osType = type().toLowerCase()
-    const cpuArch = arch()
-
-    const credentials = getCredentials()
-    const authToken = credentials?.token
+    this.protocolUpgradeRequired = false
 
+    const authToken = getCredentials()?.token
     if (!authToken) {
       console.error('\n❌ Not logged in. Run `mstro login` first.\n')
       this.callbacks.onError?.('Not logged in - run `mstro login` first')
       return
     }
 
-    const params = new URLSearchParams({
-      name,
-      workingDirectory: this.workingDirectory,
-      machineHostname,
-      clientId,
-      machineId,
-      nodeVersion,
-      osType,
-      cpuArch,
-      cliVersion: CLI_VERSION,
-      capabilities: JSON.stringify({}),
-      startedAt: this.startedAt,
-    })
-
-    const wsUrl = `${this.platformUrl.replace(/^http/, 'ws')}/ws/client?${params}`
-
+    const wsUrl = this.buildConnectionUrl()
     try {
       this.ws = new WebSocketImpl(wsUrl)
     } catch (err) {
@@ -205,7 +164,31 @@ export class PlatformConnection {
       return
     }
 
-    const connectionTimeout = setTimeout(() => {
+    const connectionTimeout = this.startConnectionTimeout()
+    this.attachSocketHandlers(this.ws, authToken, connectionTimeout)
+    this.tokens.maybeVerifyInParallel()
+  }
+
+  private buildConnectionUrl(): string {
+    const params = new URLSearchParams({
+      name: basename(this.workingDirectory),
+      workingDirectory: this.workingDirectory,
+      machineHostname: hostname(),
+      clientId: getClientId(),
+      machineId: getMachineIdentifier(),
+      nodeVersion: process.version,
+      osType: type().toLowerCase(),
+      cpuArch: arch(),
+      cliVersion: CLI_VERSION,
+      capabilities: JSON.stringify({}),
+      startedAt: this.startedAt,
+      protocolVersion: String(PROTOCOL_VERSION),
+    })
+    return `${this.platformUrl.replace(/^http/, 'ws')}/ws/client?${params}`
+  }
+
+  private startConnectionTimeout(): ReturnType<typeof setTimeout> {
+    return setTimeout(() => {
       const state = this.ws?.readyState
       if (this.ws && (state === 0 || state === undefined)) {
         console.error('\n❌ Connection timeout. The platform may have rejected your credentials.')
@@ -214,53 +197,133 @@ export class PlatformConnection {
         this.callbacks.onError?.('Connection timeout - run `mstro login --force`')
       }
     }, 10000)
+  }
 
-    this.ws.onopen = () => {
+  private attachSocketHandlers(
+    ws: WebSocket,
+    authToken: string,
+    connectionTimeout: ReturnType<typeof setTimeout>,
+  ): void {
+    ws.onopen = () => {
       clearTimeout(connectionTimeout)
-      this.ws!.send(JSON.stringify({ type: 'auth', token: authToken }))
-      this.maybeRefreshToken()
-      this.startTokenRefreshCheck()
+      ws.send(JSON.stringify({ type: 'auth', token: authToken }))
+      this.tokens.maybeRefresh()
+      this.tokens.startPeriodicCheck()
       this.reconnectAttempts = 0
       trackEvent(AnalyticsEvents.PLATFORM_CONNECTED)
     }
 
-    this.ws.onmessage = (event) => {
+    ws.onmessage = (event) => {
       try {
-        const message = JSON.parse(event.data.toString())
-        this.handleMessage(message)
+        this.handleMessage(JSON.parse(event.data.toString()))
       } catch (err) {
         console.error('Failed to parse platform message:', err)
       }
     }
 
-    this.ws.onclose = (event) => {
+    ws.onclose = (event) => {
       clearTimeout(connectionTimeout)
-      this.stopHeartbeat()
-      this.isConnected = false
-
-      if (!this.isIntentionallyClosed) {
-        const isAuthFailure = event.code === 4001 ||
-          event.reason?.includes('Unauthorized') ||
-          (event.code === 1006 && !this.everConnected)
-
-        if (isAuthFailure) {
-          console.error('\n❌ Authentication failed. Your device token may be invalid or expired.')
-          console.error('   Run `mstro login --force` to re-authenticate.\n')
-          this.callbacks.onError?.('Authentication failed - run `mstro login --force`')
-          return
-        }
-
-        console.log('Disconnected, reconnecting...')
-        this.callbacks.onDisconnected?.()
-        trackEvent(AnalyticsEvents.PLATFORM_DISCONNECTED)
-        this.scheduleReconnect()
-      }
+      this.handleSocketClose(event)
     }
 
-    this.ws.onerror = () => {
+    ws.onerror = () => {
       clearTimeout(connectionTimeout)
       // onclose will be called after this
     }
+
+    // The Node `ws` library exposes the raw HTTP upgrade response as an
+    // `unexpected-response` event when the server returns a non-101 status
+    // (for us: 426 Upgrade Required from the protocol-version gate). The
+    // global WebSocket in Bun / Node 21+ doesn't expose this — for those
+    // runtimes we rely on the close-code path below. Both paths feed into
+    // `protocolUpgradeRequired`, so `handleSocketClose` can decide once.
+    const wsWithEmitter = ws as unknown as {
+      on?: (event: string, listener: (...args: unknown[]) => void) => void
+    }
+    if (typeof wsWithEmitter.on === 'function') {
+      wsWithEmitter.on('unexpected-response', (...args: unknown[]) => {
+        const response = args[1] as { statusCode?: number } | undefined
+        if (response?.statusCode === 426) {
+          this.protocolUpgradeRequired = true
+        }
+      })
+    }
+  }
+
+  private handleSocketClose(event: CloseEvent): void {
+    this.stopHeartbeat()
+    this.isConnected = false
+
+    if (this.isIntentionallyClosed) return
+
+    if (this.isProtocolTooOldClose(event)) {
+      this.handleProtocolUpgradeRequired()
+      return
+    }
+
+    const isAuthFailure = event.code === 4001 ||
+      event.reason?.includes('Unauthorized') ||
+      (event.code === 1006 && !this.everConnected)
+
+    if (isAuthFailure) {
+      console.error('\n❌ Authentication failed. Your device token may be invalid or expired.')
+      console.error('   Run `mstro login --force` to re-authenticate.\n')
+      this.tokens.notifyAuthExpired()
+      this.callbacks.onError?.('Authentication failed - run `mstro login --force`')
+      return
+    }
+
+    console.log('Disconnected, reconnecting...')
+    this.callbacks.onDisconnected?.()
+    trackEvent(AnalyticsEvents.PLATFORM_DISCONNECTED)
+    this.scheduleReconnect()
+  }
+
+  /**
+   * The relay can refuse a CLI for being too old in two shapes:
+   *
+   *   1. **HTTP 426 during upgrade** — the `ws` library surfaces this via
+   *      its `unexpected-response` event, which sets
+   *      `protocolUpgradeRequired` before `onclose` fires. This is the path
+   *      the current server takes (`checkProtocolVersionGate`).
+   *
+   *   2. **WS close 1002/1008 with `protocol-too-old` reason** — reserved
+   *      for a future server variant that completes the upgrade and then
+   *      closes (e.g. when the policy check moves into a post-handshake
+   *      stage). The reason string is part of the contract with the server.
+   *
+   * Anything else (1006 race after a successful run, 1001 going-away on
+   * deploy) must fall through to the regular reconnect path so transient
+   * failures keep healing on their own.
+   */
+  private isProtocolTooOldClose(event: CloseEvent): boolean {
+    if (this.protocolUpgradeRequired) return true
+    const code = event.code
+    if ((code === 1002 || code === 1008) && event.reason?.includes('protocol-too-old')) {
+      return true
+    }
+    return false
+  }
+
+  private handleProtocolUpgradeRequired(): void {
+    const message = 'Mstro CLI is out of date for this orchestra. Run `mstro` again to upgrade and reconnect.'
+    console.error(`\n❌ ${message}\n`)
+    this.callbacks.onError?.(message)
+    this.callbacks.onDisconnected?.()
+
+    // Don't exit the process — terminal sessions and other local state stay
+    // alive while the user re-runs `mstro`. Schedule a single, far-future
+    // reconnect as a sentinel so we silently retry exactly once if the
+    // process is somehow still around an hour later. The existing
+    // exponential-backoff path is bypassed deliberately: hammering a server
+    // that has already decided to refuse on policy is pointless.
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout)
+    }
+    this.reconnectTimeout = setTimeout(() => {
+      this.reconnectTimeout = null
+      this.connect()
+    }, PROTOCOL_UPGRADE_RECONNECT_DELAY_MS)
   }
 
   private handleMessage(message: Record<string, unknown>): void {
@@ -325,7 +388,7 @@ export class PlatformConnection {
   disconnect(): void {
     this.isIntentionallyClosed = true
     this.stopHeartbeat()
-    this.stopTokenRefreshCheck()
+    this.tokens.stopPeriodicCheck()
 
     if (this.reconnectTimeout) {
       clearTimeout(this.reconnectTimeout)