chore(release): cut 0.1.13

ci: publish Android APK to GitHub releases
refactor: remove legacy agent update RPCs
2026-07-29 12:01:31 +00:00 · 2026-02-17 21:39:24 +07:00 · 2026-02-17 21:36:15 +07:00 · 2026-02-17 21:16:31 +07:00 · 2026-02-17 21:07:11 +07:00 · 2026-02-17 20:05:20 +07:00
28 changed files with 577 additions and 248 deletions
--- a/.github/workflows/android-apk-release.yml
+++ b/.github/workflows/android-apk-release.yml
@@ -0,0 +1,119 @@
+name: Android APK Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to build (e.g. v0.1.0)"
+        required: true
+        type: string
+
+concurrency:
+  group: android-apk-release-${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
+  cancel-in-progress: false
+
+env:
+  RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref_name }}
+
+jobs:
+  publish-android-apk:
+    permissions:
+      contents: write
+      packages: read
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+          registry-url: "https://npm.pkg.github.com"
+          scope: "@boudra"
+
+      - name: Install JS dependencies
+        run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Expo and EAS
+        uses: expo/expo-github-action@v8
+        with:
+          eas-version: latest
+          token: ${{ secrets.EXPO_TOKEN }}
+
+      - name: Build Android APK on EAS
+        id: eas_build
+        shell: bash
+        run: |
+          set -euo pipefail
+          cd packages/app
+
+          build_json="$(npx eas build --platform android --profile production-apk --non-interactive --wait --json)"
+          echo "$build_json" > "$RUNNER_TEMP/eas-build.json"
+
+          build_id="$(jq -r 'if type == "array" then .[0].id // empty else .id // empty end' "$RUNNER_TEMP/eas-build.json")"
+          if [ -z "$build_id" ]; then
+            echo "Failed to determine EAS build ID."
+            cat "$RUNNER_TEMP/eas-build.json"
+            exit 1
+          fi
+
+          echo "build_id=$build_id" >> "$GITHUB_OUTPUT"
+
+      - name: Resolve APK artifact URL
+        id: artifact
+        shell: bash
+        run: |
+          set -euo pipefail
+          cd packages/app
+
+          build_view_json="$(npx eas build:view '${{ steps.eas_build.outputs.build_id }}' --json)"
+          echo "$build_view_json" > "$RUNNER_TEMP/eas-build-view.json"
+
+          artifact_url="$(jq -r '.artifacts.buildUrl // .artifacts.applicationArchiveUrl // empty' "$RUNNER_TEMP/eas-build-view.json")"
+          if [ -z "$artifact_url" ]; then
+            echo "Failed to determine APK artifact URL."
+            cat "$RUNNER_TEMP/eas-build-view.json"
+            exit 1
+          fi
+
+          asset_name="paseo-${RELEASE_TAG}-android.apk"
+          asset_path="$RUNNER_TEMP/$asset_name"
+
+          curl --fail --location --output "$asset_path" "$artifact_url"
+
+          echo "asset_name=$asset_name" >> "$GITHUB_OUTPUT"
+          echo "asset_path=$asset_path" >> "$GITHUB_OUTPUT"
+
+      - name: Wait for GitHub release tag
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          for attempt in $(seq 1 90); do
+            if gh release view "$RELEASE_TAG" --repo "${{ github.repository }}" >/dev/null 2>&1; then
+              echo "Found release for tag $RELEASE_TAG"
+              exit 0
+            fi
+            echo "Release for $RELEASE_TAG is not available yet (attempt $attempt/90)."
+            sleep 20
+          done
+
+          echo "Timed out waiting for GitHub release tag $RELEASE_TAG."
+          exit 1
+
+      - name: Upload APK to GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload "$RELEASE_TAG" "${{ steps.artifact.outputs.asset_path }}" --clobber --repo "${{ github.repository }}"
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -139,6 +139,7 @@ npm run android:production
 ### Cloud build + submit (EAS Workflows)

 Tag pushes like `v0.1.0` trigger `packages/app/.eas/workflows/release-mobile.yml` on Expo servers.
+Tag pushes like `v0.1.0` also trigger `.github/workflows/android-apk-release.yml` on GitHub Actions to publish an APK asset on the matching GitHub Release.

 That workflow does:
 - Build iOS with the `production` profile
@@ -182,7 +183,7 @@ npm run release:patch
 npm run version:all:patch  # npm version across all workspaces (creates commit + local tag)
 npm run release:check
 npm run release:publish
-npm run release:push       # pushes HEAD and current version tag (triggers desktop + EAS mobile workflows)
+npm run release:push       # pushes HEAD and current version tag (triggers desktop + Android APK + EAS mobile workflows)
 ```

 Notes:
@@ -196,6 +197,7 @@ Notes:
 Release completion checklist:
 - `npm run release:patch` completes successfully.
 - GitHub `Desktop Release` workflow for the new `v*` tag is green.
+- GitHub `Android APK Release` workflow for the same tag is green.
 - EAS `release-mobile.yml` workflow for the same tag is green (Expo queues can take longer on the free plan).

 ## Orchestrator Mode
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
  "name": "paseo",
-  "version": "0.1.9",
+  "version": "0.1.13",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "paseo",
-      "version": "0.1.9",
+      "version": "0.1.13",
      "hasInstallScript": true,
      "license": "MIT",
      "workspaces": [
@@ -14714,7 +14714,9 @@
    },
    "node_modules/nan": {
      "version": "2.23.0",
-      "license": "MIT"
+      "dev": true,
+      "license": "MIT",
+      "optional": true
    },
    "node_modules/nanoid": {
      "version": "3.3.11",
@@ -14779,6 +14781,12 @@
      "version": "2.0.1",
      "license": "MIT"
    },
+    "node_modules/node-addon-api": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "license": "MIT"
+    },
    "node_modules/node-domexception": {
      "version": "1.0.0",
      "funding": [
@@ -14825,6 +14833,16 @@
      "version": "0.4.0",
      "license": "MIT"
    },
+    "node_modules/node-pty": {
+      "version": "1.2.0-beta.11",
+      "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.2.0-beta.11.tgz",
+      "integrity": "sha512-THcUyu1WwdgoIyUvgXOZ70EOMXzheGa0q3tbEb5kUIfKgcpBJ+AJ9Q1kq0bKtYmQzr77usXiTORZTLmAUQlnoQ==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "node-addon-api": "^7.1.0"
+      }
+    },
    "node_modules/node-releases": {
      "version": "2.0.26",
      "license": "MIT"
@@ -20344,7 +20362,7 @@
    },
    "packages/app": {
      "name": "@getpaseo/app",
-      "version": "0.1.9",
+      "version": "0.1.13",
      "dependencies": {
        "@boudra/expo-two-way-audio": "^0.1.3",
        "@dnd-kit/core": "^6.3.1",
@@ -20352,7 +20370,7 @@
        "@dnd-kit/utilities": "^3.2.2",
        "@expo/vector-icons": "^15.0.2",
        "@floating-ui/react-native": "^0.10.7",
-        "@getpaseo/server": "0.1.9",
+        "@getpaseo/server": "0.1.13",
        "@gorhom/bottom-sheet": "^5.2.6",
        "@gorhom/portal": "^1.0.14",
        "@lezer/common": "^1.5.0",
@@ -20456,11 +20474,11 @@
    },
    "packages/cli": {
      "name": "@getpaseo/cli",
-      "version": "0.1.9",
+      "version": "0.1.13",
      "dependencies": {
        "@clack/prompts": "^1.0.0",
-        "@getpaseo/relay": "0.1.9",
-        "@getpaseo/server": "0.1.9",
+        "@getpaseo/relay": "0.1.13",
+        "@getpaseo/server": "0.1.13",
        "chalk": "^5.3.0",
        "commander": "^12.0.0",
        "mime-types": "^2.1.35",
@@ -20510,14 +20528,14 @@
    },
    "packages/desktop": {
      "name": "@getpaseo/desktop",
-      "version": "0.1.9",
+      "version": "0.1.13",
      "devDependencies": {
        "@tauri-apps/cli": "^2.9.6"
      }
    },
    "packages/relay": {
      "name": "@getpaseo/relay",
-      "version": "0.1.9",
+      "version": "0.1.13",
      "dependencies": {
        "base64-js": "^1.5.1",
        "tweetnacl": "^1.0.3",
@@ -20533,12 +20551,12 @@
    },
    "packages/server": {
      "name": "@getpaseo/server",
-      "version": "0.1.9",
+      "version": "0.1.13",
      "dependencies": {
        "@ai-sdk/openai": "2.0.52",
        "@anthropic-ai/claude-agent-sdk": "^0.2.11",
        "@deepgram/sdk": "^3.4.0",
-        "@getpaseo/relay": "0.1.9",
+        "@getpaseo/relay": "0.1.13",
        "@lezer/common": "^1.5.0",
        "@lezer/css": "^1.3.0",
        "@lezer/highlight": "^1.2.3",
@@ -20558,7 +20576,7 @@
        "express-basic-auth": "^1.2.1",
        "lezer-elixir": "^1.1.2",
        "mnemonic-id": "^3.2.7",
-        "node-pty": "^1.0.0",
+        "node-pty": "1.2.0-beta.11",
        "onnxruntime-node": "^1.23.0",
        "openai": "^4.20.0",
        "pino": "^10.2.0",
@@ -20802,14 +20820,6 @@
        "node": ">= 0.6"
      }
    },
-    "packages/server/node_modules/node-pty": {
-      "version": "1.0.0",
-      "hasInstallScript": true,
-      "license": "MIT",
-      "dependencies": {
-        "nan": "^2.17.0"
-      }
-    },
    "packages/server/node_modules/qs": {
      "version": "6.14.0",
      "license": "BSD-3-Clause",
@@ -20890,7 +20900,7 @@
    },
    "packages/website": {
      "name": "@getpaseo/website",
-      "version": "0.1.9",
+      "version": "0.1.13",
      "dependencies": {
        "@cloudflare/vite-plugin": "^1.20.3",
        "@cloudflare/workers-types": "^4.20260114.0",
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "paseo",
-  "version": "0.1.9",
+  "version": "0.1.13",
  "private": true,
  "workspaces": [
    "packages/server",
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,7 +1,7 @@
 {
  "name": "@getpaseo/app",
  "main": "index.ts",
-  "version": "0.1.9",
+  "version": "0.1.13",
  "private": true,
  "scripts": {
    "start": "expo start",
@@ -30,7 +30,7 @@
    "@dnd-kit/utilities": "^3.2.2",
    "@expo/vector-icons": "^15.0.2",
    "@floating-ui/react-native": "^0.10.7",
-    "@getpaseo/server": "0.1.9",
+    "@getpaseo/server": "0.1.13",
    "@gorhom/bottom-sheet": "^5.2.6",
    "@gorhom/portal": "^1.0.14",
    "@lezer/common": "^1.5.0",
--- a/packages/app/src/components/explorer-sidebar.tsx
+++ b/packages/app/src/components/explorer-sidebar.tsx
@@ -240,8 +240,9 @@ export function ExplorerSidebar({ serverId, agentId, cwd, isGit }: ExplorerSideb
    width: resizeWidth.value,
  }));

-  // Mobile: full-screen overlay with gesture
-  const overlayPointerEvents = Platform.OS === "web" ? "auto" : "box-none";
+  // Mobile: full-screen overlay with gesture.
+  // On web, keep it interactive only while open so closed sidebars don't eat taps.
+  const overlayPointerEvents = Platform.OS === "web" ? (isOpen ? "auto" : "none") : "box-none";

  if (isMobile) {
    return (
--- a/packages/app/src/components/sliding-sidebar.tsx
+++ b/packages/app/src/components/sliding-sidebar.tsx
@@ -325,8 +325,9 @@ export function SlidingSidebar({ selectedAgentId }: SlidingSidebarProps) {


  // Render mobile sidebar
-  // On web, use "auto" instead of "box-none" because web's pointer-events: none blocks scroll
-  const overlayPointerEvents = Platform.OS === "web" ? "auto" : "box-none";
+  // On web, keep the overlay interactive only while the sidebar is open.
+  // This preserves swipe/scroll behavior without blocking taps when closed.
+  const overlayPointerEvents = Platform.OS === "web" ? (isOpen ? "auto" : "none") : "box-none";
  if (isMobile) {
    return (
      <View style={StyleSheet.absoluteFillObject} pointerEvents={overlayPointerEvents}>
--- a/packages/app/src/contexts/session-context.tsx
+++ b/packages/app/src/contexts/session-context.tsx
@@ -27,6 +27,7 @@ import { useDaemonConnections } from "./daemon-connections-context";
 import type { ActiveConnection } from "./daemon-connections-context";
 import {
  useSessionStore,
+  type Agent,
  type SessionState,
  type DaemonConnectionSnapshot,
 } from "@/stores/session-store";
@@ -850,14 +851,7 @@ export function SessionProvider({
  useEffect(() => {
    if (!connectionSnapshot.isConnected) {
      hasBootstrappedAgentUpdatesRef.current = false;
-      const subscriptionId = agentUpdatesSubscriptionIdRef.current;
-      if (subscriptionId && client) {
-        try {
-          client.unsubscribeAgentUpdates(subscriptionId);
-        } catch {
-          // no-op
-        }
-      }
+      pendingAgentUpdatesRef.current.clear();
      agentUpdatesSubscriptionIdRef.current = null;
      return;
    }
@@ -866,26 +860,84 @@ export function SessionProvider({
    }
    hasBootstrappedAgentUpdatesRef.current = true;

-    try {
-      if (!agentUpdatesSubscriptionIdRef.current) {
-        agentUpdatesSubscriptionIdRef.current = client.subscribeAgentUpdates({
-          subscriptionId: `app:${serverId}`,
-          filter: { labels: { ui: "true" } },
-        });
-      }
-    } catch (err) {
-      console.error("[Session] subscribeAgentUpdates failed", { serverId, err });
-    }
+    let cancelled = false;
+    const requestedSubscriptionId = `app:${serverId}`;

-    // Session bootstrap is now fully event-driven for agent lists.
-    setInitializingAgents(serverId, new Map());
-    setHasHydratedAgents(serverId, true);
-    updateConnectionStatus(serverId, {
-      status: "online",
-      lastOnlineAt: new Date().toISOString(),
-      agentListReady: true,
-    });
-  }, [connectionSnapshot.isConnected, client, serverId, setHasHydratedAgents, updateConnectionStatus]);
+    const bootstrapAgentDirectory = async () => {
+      try {
+        const payload = await client.fetchAgents({
+          filter: { labels: { ui: "true" } },
+          subscribe: { subscriptionId: requestedSubscriptionId },
+        });
+        if (cancelled) {
+          return;
+        }
+
+        agentUpdatesSubscriptionIdRef.current =
+          payload.subscriptionId ?? requestedSubscriptionId;
+
+        const nextAgents = new Map<string, Agent>();
+        const nextPendingPermissions = new Map<
+          string,
+          { key: string; agentId: string; request: AgentPermissionRequest }
+        >();
+        const nextStatuses = new Map<string, AgentLifecycleStatus>();
+
+        for (const entry of payload.entries) {
+          const agent = {
+            ...normalizeAgentSnapshot(entry.agent, serverId),
+            projectPlacement: entry.project,
+          };
+          nextAgents.set(agent.id, agent);
+          nextStatuses.set(agent.id, agent.status);
+
+          for (const request of agent.pendingPermissions) {
+            const key = derivePendingPermissionKey(agent.id, request);
+            nextPendingPermissions.set(key, { key, agentId: agent.id, request });
+          }
+        }
+
+        previousAgentStatusRef.current = nextStatuses;
+        pendingAgentUpdatesRef.current.clear();
+        setAgents(serverId, nextAgents);
+        for (const agent of nextAgents.values()) {
+          setAgentLastActivity(agent.id, agent.lastActivityAt);
+        }
+        setPendingPermissions(serverId, nextPendingPermissions);
+        setInitializingAgents(serverId, new Map());
+        setHasHydratedAgents(serverId, true);
+        updateConnectionStatus(serverId, {
+          status: "online",
+          lastOnlineAt: new Date().toISOString(),
+          agentListReady: true,
+        });
+      } catch (err) {
+        if (cancelled) {
+          return;
+        }
+        hasBootstrappedAgentUpdatesRef.current = false;
+        pendingAgentUpdatesRef.current.clear();
+        agentUpdatesSubscriptionIdRef.current = null;
+        console.error("[Session] fetchAgents bootstrap failed", { serverId, err });
+      }
+    };
+
+    void bootstrapAgentDirectory();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    connectionSnapshot.isConnected,
+    client,
+    serverId,
+    setAgentLastActivity,
+    setAgents,
+    setHasHydratedAgents,
+    setInitializingAgents,
+    setPendingPermissions,
+    updateConnectionStatus,
+  ]);

  // Daemon message handlers - directly update Zustand store
  useEffect(() => {
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@getpaseo/cli",
-  "version": "0.1.9",
+  "version": "0.1.13",
  "description": "Paseo CLI - control your AI coding agents from the command line",
  "type": "module",
  "files": [
@@ -22,8 +22,8 @@
  },
  "dependencies": {
    "@clack/prompts": "^1.0.0",
-    "@getpaseo/relay": "0.1.9",
-    "@getpaseo/server": "0.1.9",
+    "@getpaseo/relay": "0.1.13",
+    "@getpaseo/server": "0.1.13",
    "chalk": "^5.3.0",
    "commander": "^12.0.0",
    "mime-types": "^2.1.35",
--- a/packages/cli/src/utils/client.ts
+++ b/packages/cli/src/utils/client.ts
@@ -62,7 +62,6 @@ export async function connectToDaemon(options?: ConnectOptions): Promise<DaemonC
    if (timeoutHandle) {
      clearTimeout(timeoutHandle)
    }
-    client.subscribeAgentUpdates({ subscriptionId: `cli:${process.pid}` })
    return client
  } catch (err) {
    // Clear the timeout on error too
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@getpaseo/desktop",
-  "version": "0.1.9",
+  "version": "0.1.13",
  "private": true,
  "description": "Paseo desktop app (Tauri wrapper)",
  "scripts": {
--- a/packages/relay/package.json
+++ b/packages/relay/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@getpaseo/relay",
-  "version": "0.1.9",
+  "version": "0.1.13",
  "description": "Paseo relay for bridging daemon and client connections",
  "type": "module",
  "publishConfig": {
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@getpaseo/server",
-  "version": "0.1.9",
+  "version": "0.1.13",
  "description": "Paseo backend server",
  "type": "module",
  "publishConfig": {
@@ -9,6 +9,7 @@
  "types": "./dist/server/server/exports.d.ts",
  "files": [
    "dist/server",
+    "dist/src",
    "dist/scripts",
    "README.md",
    ".env.example",
@@ -52,10 +53,10 @@
    "test:e2e:mobile": "playwright test --project='Mobile Chrome'"
  },
  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.11",
-    "@getpaseo/relay": "0.1.9",
    "@ai-sdk/openai": "2.0.52",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.11",
    "@deepgram/sdk": "^3.4.0",
+    "@getpaseo/relay": "0.1.13",
    "@lezer/common": "^1.5.0",
    "@lezer/css": "^1.3.0",
    "@lezer/highlight": "^1.2.3",
@@ -75,7 +76,7 @@
    "express-basic-auth": "^1.2.1",
    "lezer-elixir": "^1.1.2",
    "mnemonic-id": "^3.2.7",
-    "node-pty": "^1.0.0",
+    "node-pty": "1.2.0-beta.11",
    "onnxruntime-node": "^1.23.0",
    "openai": "^4.20.0",
    "pino": "^10.2.0",
@@ -92,13 +93,13 @@
  },
  "devDependencies": {
    "@playwright/test": "^1.56.1",
-    "playwright": "^1.56.1",
    "@types/express": "^4.17.20",
    "@types/node": "^20.9.0",
    "@types/qrcode": "^1.5.6",
    "@types/uuid": "^9.0.7",
    "@types/ws": "^8.5.8",
    "@vitest/ui": "^3.2.4",
+    "playwright": "^1.56.1",
    "tsx": "^4.6.0",
    "typescript": "^5.2.2",
    "vitest": "^3.2.4"
--- a/packages/server/scripts/voice-main-daemon-e2e.ts
+++ b/packages/server/scripts/voice-main-daemon-e2e.ts
@@ -49,7 +49,9 @@ async function runVoiceRoundTrip(params: {
 }): Promise<RoundTripResult> {
  const client = new DaemonClient({ url: `${params.daemonUrl}/ws` });
  await client.connect();
-  client.subscribeAgentUpdates({ subscriptionId: `voice-e2e-${randomUUID()}` });
+  await client.fetchAgents({
+    subscribe: { subscriptionId: `voice-e2e-${randomUUID()}` },
+  });

  const mode = await client.setVoiceMode(true, params.voiceAgentId);
  if (!mode.accepted) {
--- a/packages/server/scripts/voice-roundtrip-debug.ts
+++ b/packages/server/scripts/voice-roundtrip-debug.ts
@@ -48,7 +48,7 @@ async function main(): Promise<void> {

  try {
    await client.connect();
-    client.subscribeAgentUpdates({ subscriptionId: "voice-debug" });
+    await client.fetchAgents({ subscribe: { subscriptionId: "voice-debug" } });

    const voiceCwd = mkdtempSync(path.join(tmpdir(), "voice-roundtrip-debug-"));
    const voiceAgent = await client.createAgent({
--- a/packages/server/src/client/daemon-client.test.ts
+++ b/packages/server/src/client/daemon-client.test.ts
@@ -535,6 +535,7 @@ describe("DaemonClient", () => {
        { key: "created_at", direction: "desc" },
      ],
      page: { limit: 25, cursor: "cursor-1" },
+      subscribe: { subscriptionId: "sub-1" },
    });

    expect(mock.sent).toHaveLength(1);
@@ -549,6 +550,7 @@ describe("DaemonClient", () => {
          direction: "asc" | "desc";
        }>;
        page?: { limit: number; cursor?: string };
+        subscribe?: { subscriptionId?: string };
      };
    };
    expect(request.message.type).toBe("fetch_agents_request");
@@ -557,6 +559,7 @@ describe("DaemonClient", () => {
      { key: "created_at", direction: "desc" },
    ]);
    expect(request.message.page).toEqual({ limit: 25, cursor: "cursor-1" });
+    expect(request.message.subscribe).toEqual({ subscriptionId: "sub-1" });

    mock.triggerMessage(
      JSON.stringify({
@@ -565,6 +568,7 @@ describe("DaemonClient", () => {
          type: "fetch_agents_response",
          payload: {
            requestId: request.message.requestId,
+            subscriptionId: "sub-1",
            entries: [],
            pageInfo: {
              nextCursor: null,
@@ -578,6 +582,7 @@ describe("DaemonClient", () => {

    await expect(promise).resolves.toEqual({
      requestId: request.message.requestId,
+      subscriptionId: "sub-1",
      entries: [],
      pageInfo: {
        nextCursor: null,
--- a/packages/server/src/client/daemon-client.ts
+++ b/packages/server/src/client/daemon-client.ts
@@ -350,10 +350,6 @@ export class DaemonClient {
  private connectReject: ((error: Error) => void) | null = null;
  private lastErrorValue: string | null = null;
  private connectionState: ConnectionState = { status: "idle" };
-  private agentUpdateSubscriptions = new Map<
-    string,
-    { labels?: Record<string, string>; agentId?: string } | undefined
-  >();
  private checkoutDiffSubscriptions = new Map<
    string,
    { cwd: string; compare: { mode: "uncommitted" | "base"; baseRef?: string } }
@@ -475,7 +471,6 @@ export class DaemonClient {
          this.lastErrorValue = null;
          this.reconnectAttempt = 0;
          this.updateConnectionState({ status: "connected" });
-          this.resubscribeAgentUpdates();
          this.resubscribeCheckoutDiffSubscriptions();
          this.resubscribeTerminalDirectorySubscriptions();
          this.flushPendingSendQueue();
@@ -997,6 +992,7 @@ export class DaemonClient {
      ...(options?.filter ? { filter: options.filter } : {}),
      ...(options?.sort ? { sort: options.sort } : {}),
      ...(options?.page ? { page: options.page } : {}),
+      ...(options?.subscribe ? { subscribe: options.subscribe } : {}),
    });
    return this.sendRequest({
      requestId: resolvedRequestId,
@@ -1043,44 +1039,6 @@ export class DaemonClient {
    return payload.agent;
  }

-  subscribeAgentUpdates(options?: {
-    subscriptionId?: string;
-    filter?: { labels?: Record<string, string>; agentId?: string };
-  }): string {
-    const subscriptionId = options?.subscriptionId ?? crypto.randomUUID();
-    this.agentUpdateSubscriptions.set(subscriptionId, options?.filter);
-    const message = SessionInboundMessageSchema.parse({
-      type: "subscribe_agent_updates",
-      subscriptionId,
-      ...(options?.filter ? { filter: options.filter } : {}),
-    });
-    this.sendSessionMessage(message);
-    return subscriptionId;
-  }
-
-  unsubscribeAgentUpdates(subscriptionId: string): void {
-    this.agentUpdateSubscriptions.delete(subscriptionId);
-    const message = SessionInboundMessageSchema.parse({
-      type: "unsubscribe_agent_updates",
-      subscriptionId,
-    });
-    this.sendSessionMessage(message);
-  }
-
-  private resubscribeAgentUpdates(): void {
-    if (this.agentUpdateSubscriptions.size === 0) {
-      return;
-    }
-    for (const [subscriptionId, filter] of this.agentUpdateSubscriptions) {
-      const message = SessionInboundMessageSchema.parse({
-        type: "subscribe_agent_updates",
-        subscriptionId,
-        ...(filter ? { filter } : {}),
-      });
-      this.sendSessionMessage(message);
-    }
-  }
-
  private resubscribeCheckoutDiffSubscriptions(): void {
    if (this.checkoutDiffSubscriptions.size === 0) {
      return;
--- a/packages/server/src/server/daemon-client.e2e.test.ts
+++ b/packages/server/src/server/daemon-client.e2e.test.ts
@@ -291,7 +291,9 @@ describe("daemon client E2E", () => {
    async () => {
      const cwd = tmpCwd();

-      ctx.client.subscribeAgentUpdates();
+      await ctx.client.fetchAgents({
+        subscribe: { subscriptionId: "daemon-client-lifecycle" },
+      });

      const agentUpdatePromise = waitForSignal(15000, (resolve) => {
        const unsubscribe = ctx.client.on("agent_update", (message) => {
--- a/packages/server/src/server/daemon-e2e/agent-operations.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/agent-operations.e2e.test.ts
@@ -143,7 +143,9 @@ describe("daemon E2E", () => {
      async () => {
        const cwd = tmpCwd();

-        ctx.client.subscribeAgentUpdates();
+        await ctx.client.fetchAgents({
+          subscribe: { subscriptionId: "agent-operations-cancel" },
+        });

        // Create Codex agent
        const agent = await ctx.client.createAgent({
@@ -217,7 +219,9 @@ describe("daemon E2E", () => {
      async () => {
        const cwd = tmpCwd();

-        ctx.client.subscribeAgentUpdates();
+        await ctx.client.fetchAgents({
+          subscribe: { subscriptionId: "agent-operations-mode" },
+        });

        // Create a Codex agent with default mode ("auto")
        const agent = await ctx.client.createAgent({
--- a/packages/server/src/server/daemon-e2e/live-preferences.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/live-preferences.e2e.test.ts
@@ -73,7 +73,7 @@ describe("daemon E2E", () => {
    unsubscribe = ctx.client.subscribeRawMessages((message) => {
      messages.push(message);
    });
-    ctx.client.subscribeAgentUpdates();
+    await ctx.client.fetchAgents({ subscribe: { subscriptionId: "live-preferences" } });
  });

  afterEach(async () => {
--- a/packages/server/src/server/daemon-e2e/send-while-running-stuck-claude.real.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/send-while-running-stuck-claude.real.e2e.test.ts
@@ -32,8 +32,8 @@ describe("daemon E2E (real claude) - send while running recovery", () => {
      try {
        await primary.connect();
        await secondary.connect();
-        primary.subscribeAgentUpdates({ subscriptionId: "primary" });
-        secondary.subscribeAgentUpdates({ subscriptionId: "secondary" });
+        await primary.fetchAgents({ subscribe: { subscriptionId: "primary" } });
+        await secondary.fetchAgents({ subscribe: { subscriptionId: "secondary" } });

        const agent = await primary.createAgent({
          cwd,
@@ -67,7 +67,9 @@ describe("daemon E2E (real claude) - send while running recovery", () => {
        const reconnected = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
        try {
          await reconnected.connect();
-          reconnected.subscribeAgentUpdates({ subscriptionId: "reconnected" });
+          await reconnected.fetchAgents({
+            subscribe: { subscriptionId: "reconnected" },
+          });

          reconnected.on("agent_update", (message) => {
            if (message.type !== "agent_update" || message.payload.kind !== "upsert") {
--- a/packages/server/src/server/daemon-e2e/send-while-running-stuck.real.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/send-while-running-stuck.real.e2e.test.ts
@@ -32,8 +32,8 @@ describe("daemon E2E (real codex) - send while running recovery", () => {
      try {
        await primary.connect();
        await secondary.connect();
-        primary.subscribeAgentUpdates({ subscriptionId: "primary" });
-        secondary.subscribeAgentUpdates({ subscriptionId: "secondary" });
+        await primary.fetchAgents({ subscribe: { subscriptionId: "primary" } });
+        await secondary.fetchAgents({ subscribe: { subscriptionId: "secondary" } });

        const agent = await primary.createAgent({
          cwd,
@@ -64,7 +64,9 @@ describe("daemon E2E (real codex) - send while running recovery", () => {
        const reconnected = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
        try {
          await reconnected.connect();
-          reconnected.subscribeAgentUpdates({ subscriptionId: "reconnected" });
+          await reconnected.fetchAgents({
+            subscribe: { subscriptionId: "reconnected" },
+          });

          reconnected.on("agent_update", (message) => {
            if (message.type !== "agent_update" || message.payload.kind !== "upsert") {
--- a/packages/server/src/server/session.ts
+++ b/packages/server/src/server/session.ts
@@ -293,6 +293,7 @@ type FetchAgentsRequestMessage = Extract<
  SessionInboundMessage,
  { type: "fetch_agents_request" }
 >;
+type FetchAgentsRequestFilter = NonNullable<FetchAgentsRequestMessage["filter"]>;
 type FetchAgentsRequestSort = NonNullable<FetchAgentsRequestMessage["sort"]>[number];
 type FetchAgentsResponsePayload = Extract<
  SessionOutboundMessage,
@@ -300,6 +301,17 @@ type FetchAgentsResponsePayload = Extract<
 >["payload"];
 type FetchAgentsResponseEntry = FetchAgentsResponsePayload["entries"][number];
 type FetchAgentsResponsePageInfo = FetchAgentsResponsePayload["pageInfo"];
+type AgentUpdatePayload = Extract<
+  SessionOutboundMessage,
+  { type: "agent_update" }
+>["payload"];
+type AgentUpdatesFilter = FetchAgentsRequestFilter;
+type AgentUpdatesSubscriptionState = {
+  subscriptionId: string;
+  filter?: AgentUpdatesFilter;
+  isBootstrapping: boolean;
+  pendingUpdatesByAgentId: Map<string, AgentUpdatePayload>;
+};
 type FetchAgentsCursor = {
  sort: FetchAgentsRequestSort[];
  values: Record<string, string | number | null>;
@@ -551,12 +563,7 @@ export class Session {
  private readonly pushTokenStore: PushTokenStore;
  private readonly providerRegistry: ReturnType<typeof buildProviderRegistry>;
  private unsubscribeAgentEvents: (() => void) | null = null;
-  private agentUpdatesSubscription:
-    | {
-        subscriptionId: string;
-        filter?: { labels?: Record<string, string>; agentId?: string };
-      }
-    | null = null;
+  private agentUpdatesSubscription: AgentUpdatesSubscriptionState | null = null;
  private clientActivity: {
    deviceType: "web" | "mobile";
    focusedAgentId: string | null;
@@ -1081,19 +1088,105 @@ export class Session {
    }
  }

-  private matchesAgentFilter(
-    agent: AgentSnapshotPayload,
-    filter?: { labels?: Record<string, string>; agentId?: string }
-  ): boolean {
-    if (filter?.agentId && agent.id !== filter.agentId) {
+  private matchesAgentFilter(options: {
+    agent: AgentSnapshotPayload;
+    project: ProjectPlacementPayload;
+    filter?: AgentUpdatesFilter;
+  }): boolean {
+    const { agent, project, filter } = options;
+
+    if (filter?.labels) {
+      const matchesLabels = Object.entries(filter.labels).every(
+        ([key, value]) => agent.labels[key] === value
+      );
+      if (!matchesLabels) {
+        return false;
+      }
+    }
+
+    const includeArchived = filter?.includeArchived ?? false;
+    if (!includeArchived && agent.archivedAt) {
      return false;
    }
-    if (!filter?.labels) {
-      return true;
+
+    if (filter?.statuses && filter.statuses.length > 0) {
+      const statuses = new Set(filter.statuses);
+      if (!statuses.has(agent.status)) {
+        return false;
+      }
+    }
+
+    if (typeof filter?.requiresAttention === "boolean") {
+      const requiresAttention = agent.requiresAttention ?? false;
+      if (requiresAttention !== filter.requiresAttention) {
+        return false;
+      }
+    }
+
+    if (filter?.projectKeys && filter.projectKeys.length > 0) {
+      const projectKeys = new Set(
+        filter.projectKeys.filter((item) => item.trim().length > 0)
+      );
+      if (projectKeys.size > 0 && !projectKeys.has(project.projectKey)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  private getAgentUpdateTargetId(update: AgentUpdatePayload): string {
+    return update.kind === "remove" ? update.agentId : update.agent.id;
+  }
+
+  private bufferOrEmitAgentUpdate(
+    subscription: AgentUpdatesSubscriptionState,
+    payload: AgentUpdatePayload
+  ): void {
+    if (subscription.isBootstrapping) {
+      subscription.pendingUpdatesByAgentId.set(
+        this.getAgentUpdateTargetId(payload),
+        payload
+      );
+      return;
+    }
+
+    this.emit({
+      type: "agent_update",
+      payload,
+    });
+  }
+
+  private flushBootstrappedAgentUpdates(options?: {
+    snapshotUpdatedAtByAgentId?: Map<string, number>;
+  }): void {
+    const subscription = this.agentUpdatesSubscription;
+    if (!subscription || !subscription.isBootstrapping) {
+      return;
+    }
+
+    subscription.isBootstrapping = false;
+    const pending = Array.from(subscription.pendingUpdatesByAgentId.values());
+    subscription.pendingUpdatesByAgentId.clear();
+
+    for (const payload of pending) {
+      if (payload.kind === "upsert") {
+        const snapshotUpdatedAt = options?.snapshotUpdatedAtByAgentId?.get(
+          payload.agent.id
+        );
+        if (typeof snapshotUpdatedAt === "number") {
+          const updateUpdatedAt = Date.parse(payload.agent.updatedAt);
+          if (!Number.isNaN(updateUpdatedAt) && updateUpdatedAt <= snapshotUpdatedAt) {
+            continue;
+          }
+        }
+      }
+
+      this.emit({
+        type: "agent_update",
+        payload,
+      });
    }
-    return Object.entries(filter.labels).every(
-      ([key, value]) => agent.labels[key] === value
-    );
  }

  private buildFallbackProjectCheckout(cwd: string): ProjectCheckoutLitePayload {
@@ -1159,51 +1252,31 @@ export class Session {
      }

      const payload = await this.buildAgentPayload(agent);
-      const matches = this.matchesAgentFilter(payload, subscription.filter);
+      const project = await this.buildProjectPlacement(payload.cwd);
+      const matches = this.matchesAgentFilter({
+        agent: payload,
+        project,
+        filter: subscription.filter,
+      });

      if (matches) {
-        const project = await this.buildProjectPlacement(payload.cwd);
-        this.emit({
-          type: "agent_update",
-          payload: { kind: "upsert", agent: payload, project },
+        this.bufferOrEmitAgentUpdate(subscription, {
+          kind: "upsert",
+          agent: payload,
+          project,
        });
        return;
      }

-      this.emit({
-        type: "agent_update",
-        payload: { kind: "remove", agentId: payload.id },
+      this.bufferOrEmitAgentUpdate(subscription, {
+        kind: "remove",
+        agentId: payload.id,
      });
    } catch (error) {
      this.sessionLogger.error({ err: error }, "Failed to emit agent update");
    }
  }

-  private async emitCurrentAgentUpdatesForSubscription(): Promise<void> {
-    const subscription = this.agentUpdatesSubscription;
-    if (!subscription) {
-      return;
-    }
-
-    try {
-      const agents = await this.listAgentPayloads({
-        labels: subscription.filter?.labels,
-      });
-      for (const agent of agents) {
-        const project = await this.buildProjectPlacement(agent.cwd);
-        this.emit({
-          type: "agent_update",
-          payload: { kind: "upsert", agent, project },
-        });
-      }
-    } catch (error) {
-      this.sessionLogger.error(
-        { err: error },
-        "Failed to emit current agent updates for subscription bootstrap"
-      );
-    }
-  }
-
  /**
   * Main entry point for processing session messages
   */
@@ -1230,22 +1303,6 @@ export class Session {
          await this.handleFetchAgent(msg.agentId, msg.requestId);
          break;

-        case "subscribe_agent_updates":
-          this.agentUpdatesSubscription = {
-            subscriptionId: msg.subscriptionId,
-            filter: msg.filter,
-          };
-          await this.emitCurrentAgentUpdatesForSubscription();
-          break;
-
-        case "unsubscribe_agent_updates":
-          if (
-            this.agentUpdatesSubscription?.subscriptionId === msg.subscriptionId
-          ) {
-            this.agentUpdatesSubscription = null;
-          }
-          break;
-
        case "delete_agent_request":
          await this.handleDeleteAgentRequest(msg.agentId, msg.requestId);
          break;
@@ -1702,9 +1759,9 @@ export class Session {
    });

    if (this.agentUpdatesSubscription) {
-      this.emit({
-        type: "agent_update",
-        payload: { kind: "remove", agentId },
+      this.bufferOrEmitAgentUpdate(this.agentUpdatesSubscription, {
+        kind: "remove",
+        agentId,
      });
    }
  }
@@ -5097,28 +5154,11 @@ export class Session {
  }> {
    const filter = request.filter;
    const sort = this.normalizeFetchAgentsSort(request.sort);
-    const includeArchived = filter?.includeArchived ?? false;

-    let agents = await this.listAgentPayloads({
+    const agents = await this.listAgentPayloads({
      labels: filter?.labels,
    });

-    if (!includeArchived) {
-      agents = agents.filter((agent) => !agent.archivedAt);
-    }
-
-    if (filter?.statuses && filter.statuses.length > 0) {
-      const statuses = new Set(filter.statuses);
-      agents = agents.filter((agent) => statuses.has(agent.status));
-    }
-
-    if (typeof filter?.requiresAttention === "boolean") {
-      agents = agents.filter(
-        (agent) =>
-          (agent.requiresAttention ?? false) === filter.requiresAttention
-      );
-    }
-
    const placementByCwd = new Map<string, Promise<ProjectPlacementPayload>>();
    const getPlacement = (cwd: string): Promise<ProjectPlacementPayload> => {
      const existing = placementByCwd.get(cwd);
@@ -5136,11 +5176,13 @@ export class Session {
        project: await getPlacement(agent.cwd),
      }))
    );
-
-    if (filter?.projectKeys && filter.projectKeys.length > 0) {
-      const projectKeys = new Set(filter.projectKeys.filter((item) => item.trim().length > 0));
-      entries = entries.filter((entry) => projectKeys.has(entry.project.projectKey));
-    }
+    entries = entries.filter((entry) =>
+      this.matchesAgentFilter({
+        agent: entry.agent,
+        project: entry.project,
+        filter,
+      })
+    );

    entries.sort((left, right) =>
      this.compareFetchAgentsEntries(left, right, sort)
@@ -5178,16 +5220,55 @@ export class Session {
  private async handleFetchAgents(
    request: Extract<SessionInboundMessage, { type: "fetch_agents_request" }>
  ): Promise<void> {
+    const requestedSubscriptionId = request.subscribe?.subscriptionId?.trim();
+    const subscriptionId =
+      request.subscribe
+        ? requestedSubscriptionId && requestedSubscriptionId.length > 0
+          ? requestedSubscriptionId
+          : uuidv4()
+        : null;
+
    try {
+      if (subscriptionId) {
+        this.agentUpdatesSubscription = {
+          subscriptionId,
+          filter: request.filter,
+          isBootstrapping: true,
+          pendingUpdatesByAgentId: new Map(),
+        };
+      }
+
      const payload = await this.listFetchAgentsEntries(request);
+      const snapshotUpdatedAtByAgentId = new Map<string, number>();
+      for (const entry of payload.entries) {
+        const parsedUpdatedAt = Date.parse(entry.agent.updatedAt);
+        if (!Number.isNaN(parsedUpdatedAt)) {
+          snapshotUpdatedAtByAgentId.set(entry.agent.id, parsedUpdatedAt);
+        }
+      }
+
      this.emit({
        type: "fetch_agents_response",
        payload: {
          requestId: request.requestId,
+          ...(subscriptionId ? { subscriptionId } : {}),
          ...payload,
        },
      });
+
+      if (
+        subscriptionId &&
+        this.agentUpdatesSubscription?.subscriptionId === subscriptionId
+      ) {
+        this.flushBootstrappedAgentUpdates({ snapshotUpdatedAtByAgentId });
+      }
    } catch (error) {
+      if (
+        subscriptionId &&
+        this.agentUpdatesSubscription?.subscriptionId === subscriptionId
+      ) {
+        this.agentUpdatesSubscription = null;
+      }
      const code =
        error instanceof SessionRequestError ? error.code : "fetch_agents_failed";
      const message =
--- a/packages/server/src/server/test-utils/daemon-test-context.ts
+++ b/packages/server/src/server/test-utils/daemon-test-context.ts
@@ -43,7 +43,7 @@ export async function createDaemonTestContext(
    url: `ws://127.0.0.1:${daemon.port}/ws`,
  });
  await client.connect();
-  client.subscribeAgentUpdates({ subscriptionId: "test" });
+  await client.fetchAgents({ subscribe: { subscriptionId: "test" } });

  return {
    daemon,
--- a/packages/server/src/shared/messages.ts
+++ b/packages/server/src/shared/messages.ts
@@ -405,26 +405,12 @@ export const AudioPlayedMessageSchema = z.object({
  id: z.string(),
 });

-export const RequestAgentListMessageSchema = z.object({
-  type: z.literal("request_agent_list"),
-  requestId: z.string(),
-  filter: z.object({
-    labels: z.record(z.string()).optional(),
-  }).optional(),
-});
-
-export const SubscribeAgentUpdatesMessageSchema = z.object({
-  type: z.literal("subscribe_agent_updates"),
-  subscriptionId: z.string(),
-  filter: z.object({
-    labels: z.record(z.string()).optional(),
-    agentId: z.string().optional(),
-  }).optional(),
-});
-
-export const UnsubscribeAgentUpdatesMessageSchema = z.object({
-  type: z.literal("unsubscribe_agent_updates"),
-  subscriptionId: z.string(),
+const AgentDirectoryFilterSchema = z.object({
+  labels: z.record(z.string()).optional(),
+  projectKeys: z.array(z.string()).optional(),
+  statuses: z.array(AgentStatusSchema).optional(),
+  includeArchived: z.boolean().optional(),
+  requiresAttention: z.boolean().optional(),
 });

 export const DeleteAgentRequestMessageSchema = z.object({
@@ -472,15 +458,7 @@ export const SendAgentMessageSchema = z.object({
 export const FetchAgentsRequestMessageSchema = z.object({
  type: z.literal("fetch_agents_request"),
  requestId: z.string(),
-  filter: z
-    .object({
-      labels: z.record(z.string()).optional(),
-      projectKeys: z.array(z.string()).optional(),
-      statuses: z.array(AgentStatusSchema).optional(),
-      includeArchived: z.boolean().optional(),
-      requiresAttention: z.boolean().optional(),
-    })
-    .optional(),
+  filter: AgentDirectoryFilterSchema.optional(),
  sort: z
    .array(
      z.object({
@@ -495,6 +473,11 @@ export const FetchAgentsRequestMessageSchema = z.object({
      cursor: z.string().min(1).optional(),
    })
    .optional(),
+  subscribe: z
+    .object({
+      subscriptionId: z.string().optional(),
+    })
+    .optional(),
 });

 export const FetchAgentRequestMessageSchema = z.object({
@@ -1045,8 +1028,6 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
  AudioPlayedMessageSchema,
  FetchAgentsRequestMessageSchema,
  FetchAgentRequestMessageSchema,
-  SubscribeAgentUpdatesMessageSchema,
-  UnsubscribeAgentUpdatesMessageSchema,
  DeleteAgentRequestMessageSchema,
  ArchiveAgentRequestMessageSchema,
  UpdateAgentRequestMessageSchema,
@@ -1443,6 +1424,7 @@ export const FetchAgentsResponseMessageSchema = z.object({
  type: z.literal("fetch_agents_response"),
  payload: z.object({
    requestId: z.string(),
+    subscriptionId: z.string().nullable().optional(),
    entries: z.array(
      z.object({
        agent: AgentSnapshotPayloadSchema,
--- a/packages/server/src/terminal/terminal.test.ts
+++ b/packages/server/src/terminal/terminal.test.ts
@@ -1,5 +1,12 @@
 import { describe, it, expect, afterEach } from "vitest";
-import { createTerminal, type TerminalSession } from "./terminal.js";
+import {
+  createTerminal,
+  ensureNodePtySpawnHelperExecutableForCurrentPlatform,
+  type TerminalSession,
+} from "./terminal.js";
+import { chmodSync, mkdtempSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";

 // Extract text from a single row
 function getRowText(state: ReturnType<TerminalSession["getState"]>, rowIndex: number): string {
@@ -40,12 +47,19 @@ async function waitForLines(

 describe("Terminal", () => {
  const sessions: TerminalSession[] = [];
+  const temporaryDirs: string[] = [];

  afterEach(async () => {
    for (const session of sessions) {
      session.kill();
    }
    sessions.length = 0;
+    while (temporaryDirs.length > 0) {
+      const dir = temporaryDirs.pop();
+      if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    }
  });

  function trackSession(session: TerminalSession): TerminalSession {
@@ -54,6 +68,24 @@ describe("Terminal", () => {
  }

  describe("createTerminal", () => {
+    it("ensures darwin prebuild spawn-helper is executable", () => {
+      const packageRoot = mkdtempSync(join(tmpdir(), "terminal-node-pty-helper-"));
+      temporaryDirs.push(packageRoot);
+      const prebuildDir = join(packageRoot, "prebuilds", `darwin-${process.arch}`);
+      mkdirSync(prebuildDir, { recursive: true });
+      const helperPath = join(prebuildDir, "spawn-helper");
+      writeFileSync(helperPath, "#!/bin/sh\necho helper\n");
+      chmodSync(helperPath, 0o644);
+
+      ensureNodePtySpawnHelperExecutableForCurrentPlatform({
+        packageRoot,
+        platform: "darwin",
+        force: true,
+      });
+
+      expect(statSync(helperPath).mode & 0o111).toBe(0o111);
+    });
+
    it("creates a terminal session with an id, name, and cwd", async () => {
      const session = trackSession(
        await createTerminal({
--- a/packages/server/src/terminal/terminal.ts
+++ b/packages/server/src/terminal/terminal.ts
@@ -1,8 +1,13 @@
 import * as pty from "node-pty";
 import xterm, { type Terminal as TerminalType } from "@xterm/headless";
 import { randomUUID } from "crypto";
+import { chmodSync, existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";

 const { Terminal } = xterm;
+const require = createRequire(import.meta.url);
+let nodePtySpawnHelperChecked = false;

 export interface Cell {
  char: string;
@@ -83,6 +88,73 @@ export interface CreateTerminalOptions {
  name?: string;
 }

+type EnsureNodePtySpawnHelperExecutableOptions = {
+  packageRoot?: string;
+  platform?: NodeJS.Platform;
+  arch?: string;
+  force?: boolean;
+};
+
+function resolveNodePtyPackageRoot(): string | null {
+  try {
+    const packageJsonPath = require.resolve("node-pty/package.json");
+    return dirname(packageJsonPath);
+  } catch {
+    return null;
+  }
+}
+
+function ensureExecutableBit(path: string): void {
+  if (!existsSync(path)) {
+    return;
+  }
+  const stat = statSync(path);
+  if (!stat.isFile()) {
+    return;
+  }
+  // node-pty 1.1.0 shipped darwin prebuild spawn-helper without execute bit.
+  if ((stat.mode & 0o111) === 0o111) {
+    return;
+  }
+  chmodSync(path, stat.mode | 0o111);
+}
+
+export function ensureNodePtySpawnHelperExecutableForCurrentPlatform(
+  options: EnsureNodePtySpawnHelperExecutableOptions = {}
+): void {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "darwin") {
+    return;
+  }
+  if (nodePtySpawnHelperChecked && !options.force) {
+    return;
+  }
+
+  const packageRoot = options.packageRoot ?? resolveNodePtyPackageRoot();
+  if (!packageRoot) {
+    return;
+  }
+  const arch = options.arch ?? process.arch;
+
+  const candidates = [
+    join(packageRoot, "build", "Release", "spawn-helper"),
+    join(packageRoot, "build", "Debug", "spawn-helper"),
+    join(packageRoot, "prebuilds", `darwin-${arch}`, "spawn-helper"),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      ensureExecutableBit(candidate);
+    } catch {
+      // best-effort hardening only
+    }
+  }
+
+  if (!options.force) {
+    nodePtySpawnHelperChecked = true;
+  }
+}
+
 function extractCell(terminal: TerminalType, row: number, col: number): Cell {
  const buffer = terminal.buffer.active;
  const line = buffer.getLine(row);
@@ -212,6 +284,8 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
    allowProposedApi: true,
  });

+  ensureNodePtySpawnHelperExecutableForCurrentPlatform();
+
  // Create PTY
  const ptyProcess = pty.spawn(shell, [], {
    name: "xterm-256color",
--- a/packages/website/package.json
+++ b/packages/website/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@getpaseo/website",
-  "version": "0.1.9",
+  "version": "0.1.13",
  "private": true,
  "type": "module",
  "scripts": {
Author	SHA1	Message	Date
Mohamed Boudra	a5842482b0	chore(release): cut 0.1.13	2026-02-17 21:39:24 +07:00
Mohamed Boudra	9b9535aa78	ci: publish Android APK to GitHub releases	2026-02-17 21:36:15 +07:00
Mohamed Boudra	515cb0a777	refactor: remove legacy agent update RPCs	2026-02-17 21:16:31 +07:00
Mohamed Boudra	0dc944df3a	fix(server): pin node-pty beta with macOS spawn-helper fix	2026-02-17 21:07:11 +07:00
Mohamed Boudra	16ea92aec5	fix(app): stop mobile web sidebars from intercepting taps when closed	2026-02-17 20:05:20 +07:00
Mohamed Boudra	93ec537095	chore(release): cut 0.1.12	2026-02-17 17:17:21 +07:00
Mohamed Boudra	9255212043	fix(server): self-heal node-pty spawn-helper execute bit	2026-02-17 17:16:47 +07:00
Mohamed Boudra	a03da6774a	chore(release): cut 0.1.11	2026-02-17 16:22:01 +07:00
Mohamed Boudra	7c5bbc8048	chore(release): cut 0.1.10	2026-02-17 16:19:52 +07:00
Mohamed Boudra	76e6ad89d2	fix(server): publish daemon-runner sherpa runtime module	2026-02-17 16:19:38 +07:00