fix(handoff): resolve the Kiro editor tile through the IDE app bundle on darwin

Bare `kiro` is not a deterministic IDE entry point. Once the opt-in command router is installed (v1.26.0+), `kiro` routes to whatever the user set as their default, so `kiro set-default cli` made the editor tile open the terminal agent instead of the IDE.

Add `preferMacOpenBundle` to CatalogueEntry and set it on the kiro entry only: on darwin the app bundle resolves before the $PATH shim, so `open -a Kiro <dir>` reaches /Applications/Kiro.app through LaunchServices in every router state. `command: kiro` stays as the fallback, and resolution order for every other entry is unchanged.

Not fixed with `kiro ide <dir>`: with the router absent (the default install) `kiro` is a Code-OSS-style launcher that treats `ide` as a path, which opens a spurious `ide` entry alongside the project. Verified on macOS arm64 with Kiro IDE 1.0.230-insider and no router installed. On win32/linux the ambiguity remains — no deterministic IDE entry point exists there today.

Tests now assert the resolved launch arguments, not just platform applicability: bundle-first on darwin, shim fallback when the bundle is missing, `[dir]` only on win32/linux, an unflagged entry keeping shim-first, and a catalogue invariant that only kiro opts in. They mock the fs probe and stub process.platform so they execute on any CI platform instead of self-skipping.

Author: gmarchand

apps/daemon/src/routes/host-tools.ts

@@ -42,9 +42,16 @@ export interface CatalogueEntry {
   // macOS-only fallback: when the CLI shim is missing, look for an app
   // bundle by name and launch it via `open -a "<name>"`. Lets us list
   // Xcode / Qoder / Antigravity / Warp / IntelliJ without forcing users
-  // to also install their CLI shim.
+  // to also install their CLI shim. `preferMacOpenBundle` flips it from
+  // fallback to first choice.
   macOpenBundle?: string | readonly string[];
   macOpenArgs?: (bundleName: string, resolvedDir: string) => string[];
+  // On darwin, try `macOpenBundle` before the `$PATH` shim. For tools whose
+  // bare shim is not a deterministic entry point, the app bundle is: it goes
+  // through LaunchServices and lands on exactly one app. `command` stays as
+  // the fallback so the entry still reports available when the bundle is
+  // missing, and win32/linux resolution order is untouched.
+  preferMacOpenBundle?: boolean;
   platforms?: RealPlatform[];
   excludedPlatforms?: RealPlatform[];
 }
@@ -58,7 +65,19 @@ export const CATALOGUE: ReadonlyArray<CatalogueEntry> = [
   { id: 'cursor', label: 'Cursor', icon: 'sparkles', command: 'cursor', macOpenBundle: 'Cursor' },
   { id: 'vscode', label: 'VS Code', icon: 'file-code', command: 'code', macOpenBundle: 'Visual Studio Code' },
   { id: 'windsurf', label: 'Windsurf', icon: 'sparkles', command: 'windsurf', macOpenBundle: 'Windsurf' },
-  { id: 'kiro', label: 'Kiro', icon: 'sparkles', command: 'kiro', macOpenBundle: 'Kiro' },
+  // Bare `kiro` is not a deterministic IDE entry point. Once the opt-in
+  // command router is installed (v1.26.0+, `kiro-cli integrations install
+  // kiro-command-router`) `kiro` routes to whatever the user set as their
+  // default, so `kiro set-default cli` makes this tile open the terminal
+  // agent instead of the IDE — see "Kiro Command Router" in
+  // https://kiro.dev/docs/cli/reference/cli-commands/. On darwin we sidestep
+  // the router by resolving /Applications/Kiro.app first: `open -a Kiro`
+  // reaches the IDE through LaunchServices in every router state. `kiro ide
+  // <dir>` is not a fix — with the router absent, `kiro` is a Code-OSS-style
+  // launcher that treats `ide` as a path and adds a spurious `ide` entry. On
+  // win32/linux the ambiguity stays unaddressed: no deterministic IDE entry
+  // point exists there today.
+  { id: 'kiro', label: 'Kiro', icon: 'sparkles', command: 'kiro', macOpenBundle: 'Kiro', preferMacOpenBundle: true },
   { id: 'zed', label: 'Zed', icon: 'edit', command: 'zed', macOpenBundle: 'Zed' },
   { id: 'qoder', label: 'Qoder', icon: 'sparkles', command: 'qoder', macOpenBundle: ['Qoder', 'QoderWork'] },
   { id: 'antigravity', label: 'Antigravity', icon: 'orbit', command: 'antigravity', macOpenBundle: ['Antigravity', 'Google Antigravity'] },
@@ -162,35 +181,47 @@ async function probeMacBundle(name: string | readonly string[]): Promise<{ name:
   return null;
 }
 
-async function resolveEntry(entry: CatalogueEntry): Promise<{
+interface ResolvedEntry {
   available: boolean;
   resolvedPath?: string;
   launch?: { command: string; argsForDir: (resolvedDir: string) => string[] };
-}> {
-  if (entry.command) {
-    const resolved = await probeCommandOnPath(entry.command);
-    if (resolved) {
-      return {
-        available: true,
-        resolvedPath: resolved,
-        launch: { command: resolved, argsForDir: entry.commandArgs ?? ((resolvedDir) => [resolvedDir]) },
-      };
-    }
-  }
-  if (entry.macOpenBundle && process.platform === 'darwin') {
-    const bundle = await probeMacBundle(entry.macOpenBundle);
-    if (bundle) {
-      return {
-        available: true,
-        resolvedPath: bundle.path,
-        launch: {
-          command: await resolveMacOpenCommand(),
-          argsForDir: entry.macOpenArgs
-            ? ((resolvedDir) => entry.macOpenArgs?.(bundle.name, resolvedDir) ?? ['-a', bundle.name, resolvedDir])
-            : ((resolvedDir) => ['-a', bundle.name, resolvedDir]),
-        },
-      };
-    }
+}
+
+async function resolveViaPathShim(entry: CatalogueEntry): Promise<ResolvedEntry | null> {
+  if (!entry.command) return null;
+  const resolved = await probeCommandOnPath(entry.command);
+  if (!resolved) return null;
+  return {
+    available: true,
+    resolvedPath: resolved,
+    launch: { command: resolved, argsForDir: entry.commandArgs ?? ((resolvedDir) => [resolvedDir]) },
+  };
+}
+
+async function resolveViaMacBundle(entry: CatalogueEntry): Promise<ResolvedEntry | null> {
+  if (!entry.macOpenBundle || process.platform !== 'darwin') return null;
+  const bundle = await probeMacBundle(entry.macOpenBundle);
+  if (!bundle) return null;
+  return {
+    available: true,
+    resolvedPath: bundle.path,
+    launch: {
+      command: await resolveMacOpenCommand(),
+      argsForDir: entry.macOpenArgs
+        ? ((resolvedDir) => entry.macOpenArgs?.(bundle.name, resolvedDir) ?? ['-a', bundle.name, resolvedDir])
+        : ((resolvedDir) => ['-a', bundle.name, resolvedDir]),
+    },
+  };
+}
+
+async function resolveEntry(entry: CatalogueEntry): Promise<ResolvedEntry> {
+  const order =
+    entry.preferMacOpenBundle === true && process.platform === 'darwin'
+      ? [resolveViaMacBundle, resolveViaPathShim]
+      : [resolveViaPathShim, resolveViaMacBundle];
+  for (const resolve of order) {
+    const resolved = await resolve(entry);
+    if (resolved) return resolved;
   }
   return { available: false };
 }

apps/daemon/tests/host-tools-routes.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import {
   CATALOGUE,
@@ -8,6 +8,24 @@ import {
 } from '../src/routes/host-tools.js';
 import type { CatalogueEntry, Platform } from '../src/routes/host-tools.js';
 
+// Probe boundary. `installed` stays null by default so the cases that want the
+// real filesystem (the darwin Finder/Terminal plans below) keep hitting it;
+// the resolution-order cases set an allowlist instead, which lets them assert
+// resolved launch arguments on any CI platform rather than self-skipping.
+const probe = vi.hoisted(() => ({ installed: null as string[] | null }));
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs/promises')>();
+  return {
+    ...actual,
+    access: async (target: Parameters<typeof actual.access>[0], mode?: number) => {
+      if (probe.installed === null) return actual.access(target, mode);
+      if (probe.installed.includes(String(target))) return undefined;
+      throw Object.assign(new Error(`ENOENT: ${String(target)}`), { code: 'ENOENT' });
+    },
+  };
+});
+
 describe('host tools open-in launch plans', () => {
   it('uses the absolute macOS open command to reveal project folders in Finder', async () => {
     if (process.platform !== 'darwin') return;
@@ -30,6 +48,90 @@ describe('host tools open-in launch plans', () => {
   });
 });
 
+// Resolution-order coverage for the launch *arguments*, not just platform
+// applicability. `kiro` carries preferMacOpenBundle so darwin resolves
+// /Applications/Kiro.app ahead of the `$PATH` shim — bare `kiro` routes to the
+// user's default once the Kiro command router is installed, and `kiro ide
+// <dir>` is not a usable substitute (it adds a spurious `ide` entry when the
+// router is absent). These cases pin both halves so neither can regress.
+describe('host tools resolution order — preferMacOpenBundle', () => {
+  const DIR = '/tmp/open-design-project';
+  const ORIGINAL_PLATFORM = process.platform;
+
+  function stubPlatform(platform: NodeJS.Platform, installed: string[]) {
+    Object.defineProperty(process, 'platform', { value: platform, configurable: true });
+    // Single-entry PATH so probeCommandOnPath resolves to a known absolute path.
+    vi.stubEnv('PATH', '/fake/bin');
+    probe.installed = installed;
+  }
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', { value: ORIGINAL_PLATFORM, configurable: true });
+    vi.unstubAllEnvs();
+    probe.installed = null;
+  });
+
+  it('darwin: kiro launches the app bundle through open even when the $PATH shim exists', async () => {
+    stubPlatform('darwin', ['/fake/bin/kiro', '/Applications/Kiro.app', '/usr/bin/open']);
+
+    const plan = await resolveHostToolLaunchPlan('kiro', DIR);
+
+    expect(plan.available).toBe(true);
+    expect(plan.resolvedPath).toBe('/Applications/Kiro.app');
+    expect(plan.command).toBe('/usr/bin/open');
+    expect(plan.args).toEqual(['-a', 'Kiro', DIR]);
+    expect(plan.args).not.toContain('ide');
+  });
+
+  it('darwin: kiro still falls back to the $PATH shim when the app bundle is missing', async () => {
+    stubPlatform('darwin', ['/fake/bin/kiro', '/usr/bin/open']);
+
+    const plan = await resolveHostToolLaunchPlan('kiro', DIR);
+
+    expect(plan.available).toBe(true);
+    expect(plan.command).toBe('/fake/bin/kiro');
+    expect(plan.args).toEqual([DIR]);
+  });
+
+  it('win32: kiro falls back to the $PATH shim with the dir as its only argument', async () => {
+    stubPlatform('win32', ['/fake/bin/kiro.exe']);
+
+    const plan = await resolveHostToolLaunchPlan('kiro', DIR);
+
+    expect(plan.available).toBe(true);
+    expect(plan.command).toBe('/fake/bin/kiro.exe');
+    expect(plan.args).toEqual([DIR]);
+    expect(plan.args).not.toContain('ide');
+  });
+
+  it('linux: kiro falls back to the $PATH shim with the dir as its only argument', async () => {
+    stubPlatform('linux', ['/fake/bin/kiro']);
+
+    const plan = await resolveHostToolLaunchPlan('kiro', DIR);
+
+    expect(plan.available).toBe(true);
+    expect(plan.command).toBe('/fake/bin/kiro');
+    expect(plan.args).toEqual([DIR]);
+    expect(plan.args).not.toContain('ide');
+  });
+
+  it('darwin: an unflagged entry still prefers the $PATH shim over its app bundle', async () => {
+    stubPlatform('darwin', ['/fake/bin/cursor', '/Applications/Cursor.app', '/usr/bin/open']);
+
+    const plan = await resolveHostToolLaunchPlan('cursor', DIR);
+
+    expect(plan.available).toBe(true);
+    expect(plan.resolvedPath).toBe('/fake/bin/cursor');
+    expect(plan.command).toBe('/fake/bin/cursor');
+    expect(plan.args).toEqual([DIR]);
+  });
+
+  it('only kiro opts into bundle-first resolution', () => {
+    const flagged = CATALOGUE.filter((e: CatalogueEntry) => e.preferMacOpenBundle === true);
+    expect(flagged.map((e: CatalogueEntry) => e.id)).toEqual(['kiro']);
+  });
+});
+
 describe('platform gate — Warp is darwin-only, cross-platform tools stay available everywhere', () => {
   it('CATALOGUE includes a warp entry', () => {
     const warp = CATALOGUE.find((e: CatalogueEntry) => e.id === 'warp');