@gleapai/kai-bridge 0.10.2 → 0.12.0

package/README.md

@@ -6,7 +6,7 @@ Claude Code / Codex login, and local dev-server previews.
 ```bash
 npm i -g @gleapai/kai-bridge   # one install, so the background service has a stable path
 kai-bridge login             # pair this machine with your Gleap account
-kai-bridge install           # run at login (launchd / systemd / Task Scheduler)
+kai-bridge service install   # run at login (launchd / systemd / Task Scheduler)
 kai-bridge status
 kai-bridge ps                # sessions running on this machine, with dashboard links (--json for tooling)
 ```
@@ -44,23 +44,38 @@ kai-bridge run --task "Explain the auth flow in this repo" --cwd ~/code/my-app
 `npm run sync-runner` copies the ACP runner from a sibling `gleap_code_analyzer` checkout;
 `npm test` runs the unit suite (uses real `git`).
 
+### Trying CLI changes locally
+
+```bash
+npm run cli -- status          # any kai-bridge command, run from this checkout
+npm run cli -- login --name "dev laptop"
+npm run cli -- start           # foreground daemon; Ctrl-C stops it
+npm run test:cli               # fast CLI regression suite (test/cli.test.mjs)
+```
+
+`npm run cli` (scripts/dev-cli.mjs) uses `<repo>/.kai-dev` as `KAI_HOME` and turns
+self-update off, so it never touches `~/.kai` or the background service running the
+released version. Export `KAI_API_BASE` / `KAI_APP_BASE` to point it at a local server.
+Don't `npm link` the package: the login service runs the global install by absolute
+path, and a link would swap that for this checkout.
+
 
 ### Computers and your own servers
 
 Kai Code offers **Kai Code Cloud** (Gleap's managed execution, using AI credits) or **Kai Code Bridge** (your coding agents on your computer or a server you manage, using your own AI subscriptions).
 
-Run `npm i -g @gleapai/kai-bridge && kai-bridge` in a local terminal or over SSH. The guided setup pairs the device, installs its background service and helps sign in to coding agents. Node.js 20+ and Git are required. On a Linux server, keep the user service running after logout using your system's service configuration; `kai-bridge doctor` reports service status.
+Run `npm i -g @gleapai/kai-bridge && kai-bridge` in a local terminal or over SSH. The guided setup pairs the device, installs its background service and helps sign in to coding agents. Node.js 20+ and Git are required. On a Linux server, keep the user service running after logout using your system's service configuration; `kai-bridge service status` and `kai-bridge service logs --follow` show what it is doing.
 
 Codex and Claude Code ship with Kai Code Bridge. Missing agents can be installed or repaired, and existing agents can be updated independently:
 
 ```sh
 kai-bridge harness install codex
 kai-bridge harness update codex
-kai-bridge harness login codex --device-auth
+kai-bridge profile login codex --device-auth
 
 kai-bridge harness install claude
 kai-bridge harness update claude
-kai-bridge harness login claude
+kai-bridge profile login claude
 ```
 
 Updates install into `~/.kai/harnesses`, verify the new executable, then select it for subsequent sessions. A failed download or startup leaves the previous version selected. Existing versions are retained for running sessions; your global CLI installations and agent logins are not overwritten. `--version <version>` selects a specific package version (for Claude, the Claude Agent SDK package version).

package/bin/kai-bridge.mjs

@@ -1,23 +1,10 @@
 #!/usr/bin/env node
 // kai-bridge — run Gleap Kai Code on this machine.
-//
-//   kai-bridge setup                 guided onboarding: pair · background service · harness sign-ins
-//                                    (a bare `kai-bridge` on an unpaired machine runs it too)
-//   kai-bridge login | logout        pair this device with your Gleap account / disconnect it
-//   kai-bridge install | uninstall   run at login (launchd / systemd / Task Scheduler)
-//   kai-bridge start                 run in the foreground (what the service runs)
-//   kai-bridge status                device, service, profiles, repos
-//   kai-bridge ps [--json]           what runs right now: daemon, turns, dev servers — with dashboard links
-//   kai-bridge harness list|install <id>|update <id>|login <id> [--device-auth]      Claude Code + Codex are bundled; Cursor is downloaded
-//   kai-bridge profile list|add <id> --harness claude|codex|cursor [--label …]|login <id>|remove <id>
-//   kai-bridge repo scan|roots [add <dir>|remove <dir>]|primary <repoKey> <path>
-//   kai-bridge run --task "…" [--model …] [--profile …] [--cwd …]   (local turn, no server)
-//   kai-bridge doctor
+// The command reference lives in src/help.mjs (`kai-bridge help`).
 
 import { spawn } from "node:child_process";
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { platform } from "node:os";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { KAI_HOME, loadConfig, saveConfig } from "../src/config.mjs";
@@ -26,13 +13,38 @@ import { BridgeDaemon, createLogger, resolveProfiles } from "../src/daemon.mjs";
 import { runTurn } from "../src/executor.mjs";
 import { HARNESSES, createManagedProfile, describeProfiles, findBinary, loginCommand } from "../src/profiles.mjs";
 import { defaultRoots, groupByRepo, scanRoots, toDeviceRepoReport } from "../src/repos.mjs";
-import { install, isInstalled, uninstall, isEphemeralBinPath } from "../src/service.mjs";
+import { install, isInstalled, uninstall, isEphemeralBinPath, servicePaths } from "../src/service.mjs";
+import { followFile, tailFile } from "../src/logs.mjs";
 import { HARNESS_INFO, describeHarnesses, installHarness } from "../src/harnesses.mjs";
 import { fetchLatestVersion, installVersion, installedVersion, isNewer } from "../src/selfupdate.mjs";
-import { collectProcessList, formatProcessList } from "../src/ps.mjs";
+import { collectProcessList, formatAge, formatProcessList } from "../src/ps.mjs";
+import { renderCommandHelp, renderHelp, suggestCommand } from "../src/help.mjs";
+import { palette } from "../src/tui.mjs";
 
 const BIN = fileURLToPath(import.meta.url);
+// `npm i -g` only warns on an old Node; the first run would die with a
+// SyntaxError instead. Say what is needed.
+{
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 20) {
+    process.stderr.write(`error: kai-bridge needs Node.js 20 or newer (this is ${process.versions.node}). Install a current Node from https://nodejs.org and run it again.\n`);
+    process.exit(1);
+  }
+}
+// `kai-bridge help | head` closes our stdout early: end quietly, not with a stack.
+process.stdout.on("error", (err) => {
+  if (err?.code === "EPIPE") process.exit(0);
+  throw err;
+});
 const argv = process.argv.slice(2);
+// `--version`/`-v` and `--help`/`-h` are flags people type before or after the
+// command; normalise them into the `version` and `help` commands.
+if (argv.includes("--version") || argv.includes("-v") || argv[0] === "version") {
+  process.stdout.write(`${installedVersion()}\n`);
+  process.exit(0);
+}
+if (argv[0] === "--help" || argv[0] === "-h") argv[0] = "help";
+else if (argv.includes("--help") || argv.includes("-h")) argv.splice(0, argv.length, "help", argv[0]);
 const cmd = argv[0];
 const flags = {};
 const positional = [];
@@ -52,14 +64,18 @@ const fail = (s) => {
 async function login() {
   const config = loadConfig();
   await pairDevice({ config, name: flags.name, print: out });
-  out(`Next: \`kai-bridge install\` keeps it running at login. \`kai-bridge start\` runs it right now.`);
+  out(`Next: \`kai-bridge service install\` keeps it running at login (\`kai-bridge start\` runs it right now), then \`kai-bridge profile login claude\` (or codex/cursor) to sign in your coding agent. \`kai-bridge\` does all of this in one go.`);
 }
 
 async function status() {
   const config = loadConfig();
+  out(`node:     ${process.version} (${process.execPath})`);
+  out(`git:      ${findBinary("git") ?? "not found"}`);
+  out(`claude:   ${findBinary("claude") ?? "not on PATH (bundled copy is used)"}`);
+  out(`codex:    ${findBinary("codex") ?? "not on PATH (bundled copy is used)"}`);
   out(`home:     ${KAI_HOME}`);
   out(`device:   ${config.device ? `${config.device.name} (${config.device.id})` : "not paired — run `kai-bridge login`"}`);
-  out(`service:  ${isInstalled() ? "installed" : "not installed — run `kai-bridge install`"}`);
+  out(`service:  ${isInstalled() ? "installed" : "not installed — run `kai-bridge service install`"}`);
   out("harnesses:");
   for (const h of describeHarnesses(KAI_HOME)) out(`  ${h.id.padEnd(8)} ${h.installed ? `installed ${h.version ?? ""}` : "not installed — kai-bridge harness install " + h.id}${h.bundled ? " (bundled)" : ""}`);
   const profiles = await describeProfiles(resolveProfiles(config));
@@ -95,8 +111,10 @@ async function profile() {
     return;
   }
   if (sub === "login") {
-    const p = resolveProfiles(config).find((x) => x.id === positional[1]);
-    if (!p) fail("unknown profile");
+    // A harness name means the machine's own login for it.
+    const wanted = HARNESS_INFO[positional[1]] ? `${positional[1]}-ambient` : positional[1];
+    const p = resolveProfiles(config).find((x) => x.id === wanted);
+    if (!p) fail(`unknown profile ${positional[1] ?? ""} — \`kai-bridge profile list\` shows them; \`profile login claude|codex|cursor\` signs in the machine's own agent.`);
     await installHarness(p.harness, { kaiHome: KAI_HOME, onLog: out });
     const c = loginCommand(p.harness, p.configDir, KAI_HOME, flags["device-auth"] ? { deviceAuth: true } : undefined);
     if (!c) fail(`${p.harness} is not installed`);
@@ -110,7 +128,7 @@ async function profile() {
     out("removed (the login dir is kept under ~/.kai/accounts)");
     return;
   }
-  fail("usage: profile list|add|login|remove");
+  fail("usage: profile list | login <id> [--device-auth] | add <id> --harness <claude|codex|cursor> [--label …] | remove <id>");
 }
 
 async function harness() {
@@ -120,25 +138,22 @@ async function harness() {
     return;
   }
   const id = positional[1];
-  if (!HARNESS_INFO[id]) fail("usage: harness list|install <id>|update <id>|login <id> (claude|codex|cursor)");
+  if (!HARNESS_INFO[id]) fail("usage: harness list | install <id> | update <id>   (claude|codex|cursor — sign in with `profile login <id>`)");
   if (sub === "install" || sub === "update") {
     const res = await installHarness(id, { kaiHome: KAI_HOME, onLog: out, update: sub === "update", version: typeof flags.version === "string" ? flags.version : undefined });
     if (!res.ok) fail(`${id} is not usable`);
     out(`${HARNESS_INFO[id].label} ${res.version} → ${res.binary}`);
     return;
   }
-  if (sub === "login") {
-    positional[1] = `${id}-ambient`;
-    positional[0] = "login";
-    return profile();
-  }
-  fail("usage: harness list|install <id>|update <id>|login <id> [--device-auth]");
+  if (sub === "login") return profile(); // old spelling of `profile login <id>`
+  fail("usage: harness list | install <id> | update <id>");
 }
 
 async function repo() {
   const config = loadConfig();
-  const sub = positional[0] || "scan";
+  const sub = positional[0] || "roots";
   if (sub === "scan") {
+    // Undocumented: `status` shows the same list.
     const groups = groupByRepo(scanRoots([...defaultRoots(), ...(config.roots || [])]), config.primaryOverrides);
     for (const r of toDeviceRepoReport(groups)) out(`${r.key}\t${r.primaryPath}\t${r.branch}`);
     return;
@@ -160,7 +175,7 @@ async function repo() {
     out("ok");
     return;
   }
-  fail("usage: repo scan|roots [add|remove <dir>]|primary <repoKey> <path>");
+  fail("usage: repo roots [add <dir> | remove <dir>] | primary <repoKey> <path>   (`kai-bridge status` lists the checkouts)");
 }
 
 async function runLocal() {
@@ -187,13 +202,54 @@ async function runLocal() {
   process.exit(res.code ?? 0);
 }
 
-async function doctor() {
-  out(`node:    ${process.version}`);
-  out(`claude:  ${findBinary("claude") ?? "not found (npm i -g @anthropic-ai/claude-code)"}`);
-  out(`codex:   ${findBinary("codex") ?? "not found (npm i -g @openai/codex)"}`);
-  out(`git:     ${findBinary("git") ?? "not found"}`);
-  out(`home:    ${KAI_HOME}`);
-  await status();
+/** `kai-bridge service …` — the login service and its logs. */
+async function service() {
+  const sub = positional[0] || "status";
+  if (sub === "install") {
+    if (isEphemeralBinPath(BIN)) {
+      fail(
+        "Running from npx, so there's no stable path to install from.\n" +
+          "Install it once, then this works:\n\n" +
+          "  npm i -g @gleapai/kai-bridge\n  kai-bridge service install\n",
+      );
+    }
+    const res = install({ binPath: BIN, logDir: join(KAI_HOME, "logs") });
+    out(`Installed (${res.kind}): ${res.path}. It runs at login and restarts if it crashes.`);
+    return;
+  }
+  if (sub === "uninstall") {
+    out(uninstall() ? "Removed." : "Nothing to remove.");
+    return;
+  }
+  if (sub === "restart") {
+    if (!isInstalled()) fail("The background service is not installed — run `kai-bridge service install`.");
+    const res = install({ binPath: BIN, logDir: join(KAI_HOME, "logs") });
+    out(`Restarted (${res.kind}).`);
+    return;
+  }
+  if (sub === "status") {
+    const paths = servicePaths();
+    const unit = platform() === "darwin" ? paths.launchdPlist : platform() === "linux" ? paths.systemdUnit : "Task Scheduler: GleapKaiBridge";
+    const d = collectProcessList().daemon;
+    out(`service:  ${isInstalled() ? `installed · ${unit}` : "not installed — run `kai-bridge service install`"}`);
+    out(`daemon:   ${d.running ? `running · pid ${d.pid} · up ${formatAge(d.startedAt)} · v${d.version}` : `not running${d.pid ? ` (stale lock, pid ${d.pid})` : ""}`}`);
+    out(`logs:     ${join(KAI_HOME, "logs", "bridge.log")}`);
+    return;
+  }
+  if (sub === "logs") {
+    const file = join(KAI_HOME, "logs", flags.service ? "service.err.log" : "bridge.log");
+    const n = Number(flags.lines) || 50;
+    const last = tailFile(file, n);
+    if (last) out(last);
+    else if (!flags.follow) out(`(no log yet at ${file})`);
+    if (flags.follow) {
+      const ctrl = new AbortController();
+      process.on("SIGINT", () => ctrl.abort());
+      await followFile(file, { signal: ctrl.signal });
+    }
+    return;
+  }
+  fail("usage: service install | uninstall | restart | status | logs [--lines <n>] [--follow] [--service]");
 }
 
 try {
@@ -207,20 +263,14 @@ try {
     case "logout":
       await logout();
       break;
-    case "install": {
-      if (isEphemeralBinPath(BIN)) {
-        fail(
-          "Running from npx, so there's no stable path to install from.\n" +
-            "Install it once, then this works:\n\n" +
-            "  npm i -g @gleapai/kai-bridge\n  kai-bridge install\n",
-        );
-      }
-      const res = install({ binPath: BIN, logDir: join(KAI_HOME, "logs") });
-      out(`Installed (${res.kind}): ${res.path}. It runs at login and restarts if it crashes.`);
+    case "service":
+      await service();
       break;
-    }
+    case "install":
     case "uninstall":
-      out(uninstall() ? "Removed." : "Nothing to remove.");
+      // Old spellings, kept working.
+      positional.unshift(cmd);
+      await service();
       break;
     case "start": {
       process.env.KAI_BRIDGE_FOREGROUND = process.stdout.isTTY ? "1" : "0";
@@ -255,7 +305,7 @@ try {
       await runLocal();
       break;
     case "doctor":
-      await doctor();
+      await status();
       break;
     case "update": {
       // Manual update: ignores autoUpdate and a previous failed attempt.
@@ -288,14 +338,20 @@ try {
         await runSetup({ binPath: BIN });
         break;
       }
-      out(`kai-bridge — run Gleap Kai Code on this machine
-
-  setup                            guided onboarding (pair · service · sign-ins)
-  login | logout | install | uninstall | start | status | ps | doctor | update
-  harness list|install <id>|update <id>|login <id> [--device-auth]
-  profile list|add <id> --harness claude|codex|cursor|login <id>|remove <id>
-  repo scan|roots [add|remove <dir>]|primary <repoKey> <path>
-  run --task "…" [--model …] [--profile …] [--cwd …]`);
+      if (cmd === "help" || !cmd) {
+        const topic = positional[0];
+        if (topic) {
+          const lines = renderCommandHelp(topic, { paint: palette() });
+          if (!lines) fail(`unknown command: ${topic}${suggestCommand(topic) ? ` (did you mean \`${suggestCommand(topic)}\`?)` : ""}\nRun \`kai-bridge help\` to list the commands.`);
+          for (const l of lines) out(l);
+        } else {
+          for (const l of renderHelp({ paint: palette(), version: installedVersion() })) out(l);
+        }
+        break;
+      }
+      // Not a command at all. A close match is almost always a typo.
+      const near = suggestCommand(cmd);
+      fail(`unknown command: ${cmd}${near ? ` (did you mean \`${near}\`?)` : ""}\nRun \`kai-bridge help\` to list the commands.`);
     }
   }
 } catch (err) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@gleapai/kai-bridge",
-      "version": "0.10.2",
+      "version": "0.12.0",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
@@ -134,9 +134,6 @@
       "cpu": [
         "arm64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -150,9 +147,6 @@
       "cpu": [
         "arm64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -166,9 +160,6 @@
       "cpu": [
         "x64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -182,9 +173,6 @@
       "cpu": [
         "x64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "Kai Code Bridge runs Kai Code on your computer or server with your own coding subscriptions and local previews.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,9 @@
     "postinstall": "node scripts/postinstall.mjs",
     "runtime:check": "node scripts/runtime-smoke.mjs",
     "prepack": "node scripts/prepare-release.mjs",
-    "postpack": "node scripts/prepare-release.mjs --clean"
+    "postpack": "node scripts/prepare-release.mjs --clean",
+    "cli": "node scripts/dev-cli.mjs",
+    "test:cli": "node --test test/cli.test.mjs"
   },
   "dependencies": {
     "@agentclientprotocol/claude-agent-acp": "0.81.1",

package/src/api.mjs

@@ -4,6 +4,7 @@
 //   POST   /gleapcode/bridge/pair/poll             → { status, device?, token? } (pollToken)
 //   PUT    /gleapcode/bridge/devices/me/hello      { name, platform, version, profiles, repos, roots }
 //   POST   /gleapcode/bridge/devices/me/heartbeat  { running: [turnIds] }
+//   POST   /gleapcode/bridge/turns/:id/ack         { via }   → 410 when the turn already ended
 //   POST   /gleapcode/bridge/turns/:id/events      { events: [contract lines] }
 //   POST   /gleapcode/bridge/turns/:id/result      { result, changes, status }
 //   POST   /gleapcode/bridge/devices/me/public-hosts { sessionId, services } → { domain, hosts, tunnel, displaced }
@@ -96,6 +97,15 @@ export class BridgeApi {
   heartbeat(payload) {
     return this.request("POST", "/gleapcode/bridge/devices/me/heartbeat", payload);
   }
+  /**
+   * "This machine has the turn" — sent for every delivery of a
+   * `bridge.turn.start` (push, the Server's re-send, the pending poll); the
+   * Server stops re-sending once one lands. Short timeout: the turn does not
+   * wait on a slow Server. 410 = the turn ended before it got here.
+   */
+  turnAck(turnId, payload) {
+    return this.request("POST", `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/ack`, payload, { timeoutMs: 5_000 });
+  }
   turnEvents(turnId, events) {
     return this.request("POST", `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/events`, { events });
   }

package/src/config.mjs

@@ -31,6 +31,7 @@ export function defaultConfig() {
     appBase: DEFAULT_APP_BASE,
     realtime: DEFAULT_REALTIME,
     device: null, // { id, name, token, organisationId, userId }
+    machineId: null, // stable per-install id; re-pairing keeps the same device row
     roots: [], // extra scan roots
     profiles: [
       { id: "claude-ambient", harness: "claude", kind: "ambient", label: "Claude (this machine)" },

package/src/daemon.mjs

@@ -5,7 +5,9 @@ import { cloneRepository, locateRepository } from './repository-setup.mjs';
 //
 // Commands arrive on `private-bridge-<deviceId>` (Sockudo / Pusher
 // protocol, the same channel family the dashboard uses):
-//   bridge.turn.start   { commandId, turnId, sessionId, profileId, repos:[{key, mode, base, carryUncommitted}], ...AgentRunOpts }
+//   bridge.turn.start   { turnId, sessionId, profileId, repos:[{key, mode, base, carryUncommitted}], resend?, ...AgentRunOpts }
+//                        — acknowledged with POST /turns/:id/ack; the Server re-sends an
+//                        unacknowledged start (`resend: n`), so a turn id seen before is ignored
 //   bridge.turn.cancel  { turnId }
 //   bridge.turn.steer   { turnId, steer: { id, text } }   — inject into the running turn;
 //                        answered with a {type:"steer", id, outcome} turn event
@@ -57,6 +59,8 @@ const REALTIME_RETRY_MS = 15_000;
 const HEARTBEAT_MS = 30_000;
 /** Safety net under the realtime channel: ask the server for work it thinks we run (see pullPendingWork). */
 const PENDING_POLL_MS = 60_000;
+/** Turn ids remembered after they ran, so a late duplicate delivery never runs twice (see startTurn). */
+const HANDLED_TURNS_MAX = 200;
 const USAGE_REFRESH_MS = 10 * 60_000;
 // Harness model catalogues change on releases, not by the minute.
 const MODELS_REFRESH_MS = 6 * 60 * 60_000;
@@ -563,6 +567,42 @@ export class BridgeDaemon {
     this.writeInflight(this.readInflight().filter((e) => e.turnId !== turnId));
   }
 
+  get handledTurnsPath() {
+    return join(this.kaiHome, "state", "handled-turns.json");
+  }
+
+  /**
+   * Turn ids this machine already ran (newest last, capped). Kept on disk:
+   * a turn whose result was lost is still "running" on the Server, and the
+   * pending poll after a restart must not run it a second time.
+   */
+  handledTurns() {
+    if (!this.handled) {
+      let ids = [];
+      try {
+        const raw = JSON.parse(readFileSync(this.handledTurnsPath, "utf8"));
+        if (Array.isArray(raw)) ids = raw.filter((id) => typeof id === "string");
+      } catch {
+        /* none yet */
+      }
+      this.handled = new Set(ids.slice(-HANDLED_TURNS_MAX));
+    }
+    return this.handled;
+  }
+
+  rememberHandledTurn(turnId) {
+    const handled = this.handledTurns();
+    handled.delete(turnId);
+    handled.add(turnId);
+    while (handled.size > HANDLED_TURNS_MAX) handled.delete(handled.values().next().value);
+    try {
+      mkdirSync(join(this.kaiHome, "state"), { recursive: true });
+      writeFileSync(this.handledTurnsPath, JSON.stringify([...handled]));
+    } catch {
+      /* best effort */
+    }
+  }
+
   /** Turns this machine was running when it was killed — report them dead. */
   async reportInterruptedTurns() {
     const entries = this.readInflight();
@@ -571,6 +611,8 @@ export class BridgeDaemon {
     for (const entry of entries) {
       const { turnId } = entry;
       this.log("warn", "turn.interrupted", { turnId, agent: entry.agent });
+      // Reported failed below; a re-send or a poll must not start it over.
+      this.rememberHandledTurn(turnId);
       await this.api
         .turnResult(turnId, {
           status: "failed",
@@ -867,8 +909,11 @@ export class BridgeDaemon {
       }
       for (const turn of pending?.turns || []) {
         if (this.running.has(turn.turnId) || cancelled.has(String(turn.turnId))) continue;
+        // Ran here already and its result never landed: the Server's reaper
+        // settles it — running the work again is never the fix.
+        if (this.handledTurns().has(turn.turnId)) continue;
         this.log("info", "turn.recovered", { turnId: turn.turnId, via });
-        void this.startTurn(turn).catch((err) => this.log("error", "turn.recover.failed", { error: err.message }));
+        void this.startTurn(turn, { via }).catch((err) => this.log("error", "turn.recover.failed", { error: err.message }));
       }
     } catch (err) {
       // Older server without the endpoint, or the server is restarting: the
@@ -931,7 +976,7 @@ export class BridgeDaemon {
             .catch((err) => this.log("warn", "update.turn.refused.failed", { turnId: data.turnId, error: err?.message }));
           return;
         }
-        return this.startTurn(data);
+        return this.startTurn(data, { via: data?.resend ? "resend" : "push" });
       case "bridge.turn.cancel":
         this.running.get(data.turnId)?.ctrl.abort();
         return;
@@ -1665,9 +1710,10 @@ export class BridgeDaemon {
   }
 
   /** Map the Server's repo bindings onto local checkouts; throw a readable error when one is missing. */
-  async bindRepos(turn) {
+  async bindRepos(turn, { onPrepare, signal } = {}) {
     const bound = [];
     for (const r of turn.repos || []) {
+      if (signal?.aborted) break; // stopped mid-prep: the caller reports the cancel
       const group = this.repoGroups.find((g) => g.key === r.key);
       if (!group) throw new Error(`Repository ${r.key} is not checked out on this device.`);
       const mode = r.mode || this.config.repoModes?.[r.key] || "worktree";
@@ -1678,6 +1724,7 @@ export class BridgeDaemon {
         sessionId: turn.sessionId,
         title: turn.title,
         gitEnv,
+        onPrepare,
       }));
       bound.push({ key: r.key, ...ws });
       if (ws.deps) this.log("info", "deps.seed", { repo: r.key, ...ws.deps });
@@ -1736,11 +1783,25 @@ export class BridgeDaemon {
     return adopted;
   }
 
-  async startTurn(turn) {
+  /**
+   * `via` = how the turn reached us: push, resend (the Server re-sent an
+   * unacknowledged start), poll or reconnect (pullPendingWork).
+   */
+  async startTurn(turn, { via = "push" } = {}) {
     const { turnId } = turn;
-    if (this.running.has(turnId)) return;
+    // One turn, several deliveries by design: the Server re-sends a start
+    // until it is acknowledged, and the poll / reconnect pull replays what
+    // the Server still expects. Only the first delivery runs. Every one is
+    // acknowledged — a duplicate usually means the first ack was missed.
+    if (this.running.has(turnId) || this.handledTurns().has(turnId)) {
+      this.log("info", "turn.duplicate", { turnId, via, running: this.running.has(turnId) });
+      await this.ackTurn(turnId, via);
+      return;
+    }
     const ctrl = new AbortController();
     const entry = { ctrl, control: null, sessionId: turn.sessionId };
+    // Claimed before the first await, so a second delivery arriving while
+    // the ack is in flight is the duplicate above.
     this.running.set(turnId, entry);
     const releaseAwake = keepAwake();
     let outcome = null;
@@ -1749,8 +1810,39 @@ export class BridgeDaemon {
     this.rememberInflight(turnId, { sessionId: turn.sessionId, agent: turn.agent ?? null, harness: turn.harness ?? null, profileId: turn.profileId ?? null, startedAt: new Date().toISOString(), ...session });
     const batcher = createEventBatcher({ api: this.api, turnId, onError: (err) => this.log("warn", "events.post.failed", { error: err.message }) });
     try {
+      // Receipt first: the Server stops re-sending the start.
+      if ((await this.ackTurn(turnId, via)) === "ended") {
+        // Stopped or reaped before it reached this machine — nobody is
+        // waiting for it, and its result would be refused anyway.
+        this.log("info", "turn.ended_before_start", { turnId, via });
+        return;
+      }
       const profile = resolveProfiles(this.config, this.kaiHome).find((p) => p.id === turn.profileId) ?? { id: "gleap-key", kind: "gleap-key", harness: turn.harness };
-      const bound = await this.bindRepos(turn);
+      // Prep no longer blocks the daemon, so a Stop (or session close) can
+      // land before the runner exists — and runTurn's abort listener would
+      // never hear a signal that fired before it was added. Never start the
+      // agent for a turn that was stopped on the way.
+      const stoppedBeforeRun = () => {
+        if (!ctrl.signal.aborted) return false;
+        this.log("info", "turn.cancelled_before_run", { turnId });
+        outcome = { status: "cancelled", changes: [], profileId: profile.id };
+        return true;
+      };
+      if (stoppedBeforeRun()) return;
+      // A fresh worktree costs a fetch, a checkout and a node_modules clone
+      // — up to minutes for a big repo — while the dashboard already calls
+      // the session running. Say what is happening before it starts (once
+      // per turn; resumed worktrees and local checkouts skip it).
+      let preparing = null;
+      const onPrepare = () => {
+        preparing ??= (async () => {
+          batcher.push({ type: "tool_status", message: `Preparing workspace on ${this.config.device?.name || "this machine"}…` });
+          await batcher.flush();
+        })();
+        return preparing;
+      };
+      const bound = await this.bindRepos(turn, { onPrepare, signal: ctrl.signal });
+      if (stoppedBeforeRun()) return;
       // Multi-repo: the runner's cwd is the first repo; the others are
       // reachable as siblings under the same worktree root or by their
       // local paths — the prompt lists them.
@@ -1764,6 +1856,7 @@ export class BridgeDaemon {
       const live = await this.describeLivePreview(turn, bound, batcher);
       const previewNote = live.note;
       const mcpServers = live.hasLivePreview ? [...(turn.mcpServers || []), previewMcpServer(RUNNER_DIR)] : turn.mcpServers;
+      if (stoppedBeforeRun()) return;
       const res = await runTurn({
         turn: { ...turn, task: `${turn.task}${repoNote}${previewNote}`, mcpServers },
         profile,
@@ -1861,12 +1954,30 @@ export class BridgeDaemon {
           .catch((err) => this.log("error", "result.lost", { turnId, error: err.message }));
       }
       this.forgetInflight(turnId);
+      this.rememberHandledTurn(turnId);
       releaseAwake();
       this.running.delete(turnId);
       if ((this.updatePending || this.restartPending) && this.running.size === 0) void this.checkForUpdate();
     }
   }
 
+  /**
+   * Tell the Server this machine has the turn. Resolves "acked", "ended"
+   * (410: the turn is over — it must not run), or "unknown" (an older Server
+   * without the route, a network hiccup): the turn then runs as it always
+   * did. Never throws.
+   */
+  async ackTurn(turnId, via) {
+    try {
+      await this.api.turnAck(turnId, { via });
+      return "acked";
+    } catch (err) {
+      if (err?.status === 410) return "ended";
+      this.log(err?.status === 404 ? "debug" : "warn", "turn.ack.failed", { turnId, via, error: err?.message });
+      return "unknown";
+    }
+  }
+
   // ── preview browser ────────────────────────────────────────────────
   /** Overridable seam (tests, embedded hosts): a browser the warm-up and the Playwright MCP can launch. */
   ensurePreviewBrowser() {