@gleapai/kai-bridge 0.2.5 → 0.2.7

package/bin/kai-bridge.mjs

@@ -27,6 +27,7 @@ import { HARNESSES, createManagedProfile, describeProfiles, findBinary, loginCom
 import { defaultRoots, groupByRepo, scanRoots, toDeviceRepoReport } from "../src/repos.mjs";
 import { install, isInstalled, uninstall, isEphemeralBinPath } from "../src/service.mjs";
 import { HARNESS_INFO, describeHarnesses, installHarness } from "../src/harnesses.mjs";
+import { fetchLatestVersion, installVersion, installedVersion, isNewer } from "../src/selfupdate.mjs";
 
 const BIN = fileURLToPath(import.meta.url);
 const argv = process.argv.slice(2);
@@ -244,6 +245,28 @@ try {
     case "doctor":
       await doctor();
       break;
+    case "update": {
+      // Manual update: ignores autoUpdate and a previous failed attempt.
+      const current = installedVersion();
+      const latest = await fetchLatestVersion();
+      if (!isNewer(latest, current)) {
+        out(`kai-bridge ${current} is up to date.`);
+        break;
+      }
+      out(`Updating kai-bridge ${current} → ${latest}…`);
+      const res = await installVersion(latest);
+      if (!res.ok) fail(`Update failed: ${res.error}\n\nTry: npm i -g @gleapai/kai-bridge@${latest}`);
+      const cfg = loadConfig();
+      cfg.selfUpdate = { lastAttempt: { version: latest, ok: true, at: new Date().toISOString(), error: null } };
+      saveConfig(cfg);
+      if (isInstalled()) {
+        install({ binPath: BIN, logDir: join(KAI_HOME, "logs") });
+        out(`Installed ${latest} and restarted the background service.`);
+      } else {
+        out(`Installed ${latest}. Restart \`kai-bridge start\` to run it.`);
+      }
+      break;
+    }
     default: {
       // A bare `kai-bridge` in a terminal IS the setup — first run pairs,
       // later runs open with keep / reconnect / log out, so it doubles as
@@ -256,7 +279,7 @@ try {
       out(`kai-bridge — run Gleap Kai Code on this machine
 
   setup                            guided onboarding (pair · service · sign-ins)
-  login | logout | install | uninstall | start | status | doctor
+  login | logout | install | uninstall | start | status | doctor | update
   harness list|install <id>|login <id>
   profile list|add <id> --harness claude|codex|cursor|login <id>|remove <id>
   repo scan|roots [add|remove <dir>]|primary <repoKey> <path>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Run Gleap Kai Code sessions on your own machine with your own Claude Code / Codex login — and preview your real dev servers from the dashboard or the phone.",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/claude-agent-acp": "0.73.0",
-    "@agentclientprotocol/codex-acp": "1.8.0",
+    "@agentclientprotocol/codex-acp": "1.10.0",
     "@agentclientprotocol/sdk": "1.4.0",
     "@playwright/mcp": "^0.0.79",
     "@sockudo/client": "^2.0.0",

package/runner/acp-runner.mjs

@@ -39,8 +39,9 @@ import {
   startHeartbeat,
   traceLog,
 } from "./lib/contract.mjs";
-import { deriveEngineSlug, getHarness, isNativeAnthropic, pickSessionMode, resolveHarnessId } from "./lib/acp/harnesses.mjs";
+import { deriveEngineSlug, getHarness, isNativeAnthropic, pickSessionConfigOptions, pickSessionMode, resolveHarnessId } from "./lib/acp/harnesses.mjs";
 import { createAcpMapper, permissionPolicy } from "./lib/acp/mapper.mjs";
+import { describeProviderError, extractProviderError } from "./lib/acp/providerError.mjs";
 import { aggregateUsageRows, lastRootContextSnapshot } from "./lib/acp/transcripts.mjs";
 import { needsWireProxy, startWireProxy } from "./lib/wire-proxy.mjs";
 
@@ -145,6 +146,17 @@ const GATEWAY_PLAN_GUARD =
   `If you asked questions via the ${ASK_USER_TOOL_REF}, ` +
   "do NOT also finalise the plan in the same turn — wait for " +
   "the answers first.";
+// Harnesses without an enforced read-only plan mode (codex-acp's
+// "read-only" is a workspace-write sandbox that merely asks before
+// touching files OUTSIDE the workspace — found live 2026-09-06 when
+// Codex implemented the whole ticket during its plan turn). The prompt
+// has to carry the rule, and the bridge discards plan-turn edits.
+const READ_ONLY_PLAN_NOTE =
+  "PLAN MODE IS READ-ONLY. Do not create, edit or delete files and do " +
+  "not run commands that change the workspace (no installs, no " +
+  "formatters, no git writes) — nothing enforces this for you, and every " +
+  "change made during a plan turn is discarded before the build starts. " +
+  "Read, search and reason; then end your turn with the plan.";
 // Tool allow-lists (Claude permission rules). Plan mode and artifact
 // writers (kai-asker / researcher / documentarian: `.kai/` outputs only,
 // never repo edits) run under the CLI's own gating with these rules;
@@ -244,6 +256,7 @@ function buildAppendSystemPrompt() {
   }
   if (NEEDS_ASK_USER_MCP && !IS_ARTIFACT_WRITER) sections.push(GATEWAY_QUESTION_NOTE);
   if (IS_PLAN_MODE) sections.push(NEEDS_ASK_USER_MCP ? GATEWAY_PLAN_GUARD : PLAN_QUESTION_GUARD);
+  if (IS_PLAN_MODE && HARNESS_ID !== "claude") sections.push(READ_ONLY_PLAN_NOTE);
   if (!IS_PLAN_MODE) sections.push(GIT_HANDOFF_PROMPT);
   // After the safety guards (their leading position is load-bearing for
   // cursor's prompt-prefix mode) but before project instructions.
@@ -573,6 +586,15 @@ async function main() {
       traceLog("session.mode.failed", { modeId: desiredMode, error: String(err?.message ?? err) });
     }
   }
+  // Codex's native plan collaboration mode (see pickSessionConfigOptions).
+  for (const option of pickSessionConfigOptions(HARNESS_ID, ctx, sessionResponse.configOptions)) {
+    try {
+      await conn.setSessionConfigOption({ sessionId: acpSessionId, ...option });
+      traceLog("session.config", option);
+    } catch (err) {
+      traceLog("session.config.failed", { ...option, error: String(err?.message ?? err) });
+    }
+  }
 
   // Artifact writers must leave the repo untouched: snapshot before,
   // revert anything outside `.kai/` after (belt-and-braces under the
@@ -658,6 +680,15 @@ async function main() {
   if (stopReason === "refusal") {
     emit({ type: "error", message: "The model declined to continue (refusal)." });
   }
+  // A backend rejection codex-acp forwarded as text is a failed turn,
+  // not an answer — and never a plan (see providerError.mjs).
+  const providerError = cancelRequested ? null : extractProviderError(finished.lastText);
+  if (providerError) {
+    traceLog("provider.error", providerError);
+    emitSync({ type: "error", message: describeProviderError(providerError) });
+    emitSync(tracker.buildResultEvent({ sessionId: acpSessionId }));
+    process.exit(1);
+  }
   const resultMessage = IS_PLAN_MODE && !finished.planEmitted && !finished.questionAsked ? finished.lastText : "";
   if (IS_PLAN_MODE && resultMessage) emit({ type: "plan", message: resultMessage });
   emitSync(tracker.buildResultEvent({ message: resultMessage, sessionId: acpSessionId }));

package/runner/lib/acp/harnesses.mjs

@@ -48,6 +48,24 @@ export function resolveHarnessId(explicit, model) {
  * advertises (`session/new` → `modes.availableModes`); null when the
  * agent advertises no modes (then `session/set_mode` is skipped).
  */
+/**
+ * Session config options to set right after the mode. Codex has a NATIVE
+ * plan collaboration mode ("Plan before making changes") that codex-acp
+ * exposes as the `collaboration_mode` select option — the only real
+ * read-only plan mode Codex has: its ACP "read-only" mode is a
+ * workspace-write sandbox, and the prompt alone did not stop it from
+ * editing during a plan turn (2026-09-06). Empty when the agent does not
+ * advertise the option (older codex-acp, other harnesses).
+ */
+export function pickSessionConfigOptions(harnessId, ctx, configOptions) {
+  if (harnessId !== "codex" || !ctx?.isPlanMode) return [];
+  const option = (Array.isArray(configOptions) ? configOptions : []).find((o) => o?.id === "collaboration_mode");
+  if (!option) return [];
+  const values = (Array.isArray(option.options) ? option.options : []).map((o) => String(o?.value ?? o));
+  if (!values.includes("plan")) return [];
+  return option.currentValue === "plan" ? [] : [{ configId: "collaboration_mode", value: "plan" }];
+}
+
 export function pickSessionMode(preferred, available) {
   const ids = new Set((Array.isArray(available) ? available : []).map((m) => String(m?.id ?? m)));
   if (ids.size === 0) return preferred[0] ?? null;
@@ -102,6 +120,12 @@ export function buildCodexConfigToml(mcpServers) {
     "show_raw_agent_reasoning = true",
     "[features]",
     "collaboration_modes = true",
+    // The user's ChatGPT connectors ("apps") stay out of Kai sessions:
+    // a bridge turn runs under the teammate's own ChatGPT login, and
+    // with apps on, Codex reached the Gleap connector of that account —
+    // tools the session's MCP config had disabled (draft_reply_to_composer
+    // landed in the composer through it; found live 2026-09-06).
+    "apps = false",
   ];
   for (const server of mcpServers || []) {
     if (!server || typeof server !== "object") continue;

package/runner/lib/acp/mapper.mjs

@@ -66,6 +66,21 @@ export function toolNameFromUpdate(update) {
   return "Tool";
 }
 
+/**
+ * codex-acp's post-plan permission request ("Implement this plan?", kind
+ * switch_mode, `_meta.codex.kind: "plan_review"`, the plan in
+ * `rawInput.plan`) → the plan markdown; null for every other request.
+ */
+export function planReviewText(params) {
+  const toolCall = params?.toolCall ?? {};
+  const isPlanReview =
+    params?._meta?.codex?.kind === "plan_review" ||
+    (toolCall.kind === "switch_mode" && /implement this plan/i.test(String(toolCall.title ?? "")));
+  if (!isPlanReview) return null;
+  const plan = toolCall.rawInput?.plan;
+  return typeof plan === "string" ? plan.trim() : "";
+}
+
 /** Normalise adapter-specific raw inputs into the shapes summarizeTool knows. */
 export function normalizeToolInput(name, update) {
   const raw = update?.rawInput;
@@ -507,9 +522,26 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
       const toolCall = params?.toolCall ?? {};
       const name = toolNameFromUpdate(toolCall);
       const input = toolCall.rawInput ?? null;
-      if (handleTurnEndingTool(name, input)) return null;
       const options = Array.isArray(params?.options) ? params.options : [];
       const pick = (kind) => options.find((o) => o?.kind === kind)?.optionId;
+      // Codex's native plan mode ends with "Implement this plan?" — and
+      // codex-acp asks the CLIENT: a "yes" switches to default mode and
+      // runs the implementation inside the same prompt. We auto-allowed
+      // it like any unknown permission, so Codex implemented during plan
+      // turns (2026-09-06). Gleap owns that question (the dashboard's plan
+      // card): capture the plan, end the turn, answer no.
+      const planReview = isPlanMode ? planReviewText(params) : null;
+      if (planReview !== null) {
+        if (!planEmitted) {
+          planEmitted = true;
+          flushThought();
+          flushText();
+          emit({ type: "plan", message: planReview || lastText });
+        }
+        onTurnShouldEnd?.("plan");
+        return pick("reject_once") ?? pick("reject_always") ?? "__reject__";
+      }
+      if (handleTurnEndingTool(name, input)) return null;
       if (!allowTool(name, input)) {
         emit({
           type: "tool_status",

package/runner/lib/acp/providerError.mjs

@@ -0,0 +1,83 @@
+// A backend rejection the ACP adapter forwarded as prose.
+//
+// codex-acp streams a non-retryable app-server error (an HTTP 4xx from
+// the Responses API: unknown model, bad request, model gated behind a
+// newer CLI) as a plain agent text chunk — `${message}\n\n`, where
+// `message` is the raw JSON envelope — and then ends the turn normally.
+// Without this the runner took that text for the agent's answer; in
+// plan mode it BECAME the plan and the dashboard asked "Implement this
+// plan?" over `{"type":"error","status":400,…}` (found live 2026-09-06:
+// gpt-6-astra on a bundled Codex CLI too old for it).
+
+/**
+ * The provider error hidden in the agent's final text, or `null` when
+ * the text is a real answer. Only the LAST paragraph decides: the CLI's
+ * own "Warning: …" lines ride ahead of the envelope, while an error the
+ * agent quoted and then worked past is still an answer.
+ */
+export function extractProviderError(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  const paragraphs = text.trim().split(/\n\s*\n/);
+  const candidate = paragraphs[paragraphs.length - 1].trim();
+  if (!candidate.startsWith("{") || !candidate.endsWith("}")) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch {
+    return null; // prose that happens to sit in braces
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.type !== "error")
+    return null;
+  const inner =
+    parsed.error && typeof parsed.error === "object" ? parsed.error : parsed;
+  const message =
+    typeof inner.message === "string" && inner.message.trim()
+      ? inner.message.trim()
+      : candidate;
+  const status = Number.isInteger(parsed.status)
+    ? parsed.status
+    : Number.isInteger(inner.status)
+      ? inner.status
+      : null;
+  const code =
+    inner !== parsed && typeof inner.type === "string"
+      ? inner.type
+      : typeof inner.code === "string"
+        ? inner.code
+        : null;
+  return { message, status, code };
+}
+
+/**
+ * What the teammate can DO about it. The provider's own text is written
+ * for people running the CLI by hand ("upgrade the latest app or CLI") —
+ * on a paired machine the CLI is bundled with Kai Bridge, so the fix is
+ * the bridge, not Codex. Null when there is no known remedy.
+ */
+export function adviseProviderError(error) {
+  const text = `${error.message} ${error.code ?? ""}`;
+  if (/newer version of codex|upgrade .*(app|cli)/i.test(text)) {
+    return (
+      "This model needs a newer Codex than the one bundled with Kai Bridge on this machine. " +
+      "Kai Bridge updates itself when idle (0.2.6 and later) — give it a few minutes and retry, " +
+      "or run `npm i -g @gleapai/kai-bridge@latest` there. Or pick a model from this machine's list."
+    );
+  }
+  if (error.status === 401 || /unauthori[sz]ed|not logged in|login required|invalid.*(token|api key)/i.test(text)) {
+    return "The Codex login on this machine has expired — run `kai-bridge login` there, then retry.";
+  }
+  if (error.status === 404 || /model.*(not found|does not exist|unknown|unsupported)|unknown model/i.test(text)) {
+    return "This machine's Codex does not know that model — pick one from this machine's list.";
+  }
+  if (error.status === 429 || /rate limit|too many requests|usage limit/i.test(text)) {
+    return "The ChatGPT account on this machine is rate-limited — wait for the window to reset or run in Gleap Cloud.";
+  }
+  return null;
+}
+
+/** One line for the dashboard's failed-turn row: what happened, then what to do. */
+export function describeProviderError(error) {
+  const where = error.status ? ` (HTTP ${error.status})` : "";
+  const advice = adviseProviderError(error);
+  return `The model provider rejected the request${where}: ${error.message}${advice ? ` ${advice}` : ""}`;
+}

package/src/daemon.mjs

@@ -20,10 +20,11 @@ import { KAI_HOME, defaultConfig, loadConfig, saveConfig } from "./config.mjs";
 import { runTurn } from "./executor.mjs";
 import { createManagedProfile, describeProfiles, managedConfigDir, ambientConfigDir, openLoginTerminal, probeUsageLimits } from "./profiles.mjs";
 import { defaultRoots, groupByRepo, preferredCloneRoot, scanRoots, toDeviceRepoReport } from "./repos.mjs";
-import { collectChanges, commitAndPush, copyPrimaryEnvFiles, currentBranch, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
+import { discardChanges, collectChanges, commitAndPush, copyPrimaryEnvFiles, currentBranch, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
 import { ServiceRunner, detectDevConfig, previewMcpServer, readDevConfig } from "./preview.mjs";
 import { describeHarnesses, installHarness, probeHarnessAuth } from "./harnesses.mjs";
 import { probeHarnessModels } from "./models.mjs";
+import { decideUpdate, fetchLatestVersion, installVersion, installedVersion, isNewer } from "./selfupdate.mjs";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -38,7 +39,14 @@ const USAGE_REFRESH_MS = 10 * 60_000;
 const MODELS_REFRESH_MS = 6 * 60 * 60_000;
 /** Harnesses that can tell us which models they offer (Cursor has no such surface). */
 const MODEL_PROBE_HARNESSES = ["claude", "codex"];
-const VERSION = "0.1.0";
+// Read from package.json: the hard-coded "0.1.0" this used to be is what
+// every device reported as its bridge version, so nobody could tell who
+// was behind.
+const VERSION = installedVersion();
+const SELF_UPDATE_CHECK_MS = 6 * 60 * 60_000;
+// EX_TEMPFAIL: a failure exit on purpose — launchd (SuccessfulExit:false)
+// and systemd (Restart=on-failure) restart the service on the new code.
+const RESTART_EXIT_CODE = 75;
 
 export function createLogger(kaiHome = KAI_HOME) {
   mkdirSync(join(kaiHome, "logs"), { recursive: true });
@@ -109,6 +117,9 @@ export class BridgeDaemon {
     this.usageByProfile = new Map(); // profileId → plan-usage snapshot (claude only)
     this.modelsByHarness = new Map(); // harnessId → models the signed-in login offers (see refreshHarnessModels)
     this.stopped = false;
+    this.updateAvailable = null; // newer registry version, when one exists
+    this.updateError = null; // why the last self-update did not apply
+    this.updating = false; // npm is replacing our files — refuse new turns
   }
 
   async scanRepos() {
@@ -131,6 +142,9 @@ export class BridgeDaemon {
       repos,
       roots: [...defaultRoots(), ...(this.config.roots || [])],
       repoModes: this.config.repoModes || {},
+      updateAvailable: this.updateAvailable || null,
+      updateError: this.updateError || null,
+      autoUpdate: this.config.autoUpdate !== false,
     });
   }
 
@@ -169,6 +183,10 @@ export class BridgeDaemon {
         await new Promise((r) => setTimeout(r, delay));
       }
     }
+    // Update BEFORE picking up work: a machine that wakes up applies the
+    // new version first, so its next turn runs on current code. Applying
+    // restarts the process (this call never returns in that case).
+    await this.checkForUpdate();
     this.connectRealtime();
     // REF'd on purpose: this timer is what keeps the process alive. With
     // it unref'd, a realtime socket that gave up for good left no handle
@@ -190,7 +208,82 @@ export class BridgeDaemon {
     void this.refreshHarnessModels();
     this.modelsTimer = setInterval(() => void this.refreshHarnessModels(), MODELS_REFRESH_MS);
     this.modelsTimer.unref?.();
-    this.log("info", "started", { device: this.config.device.id });
+    this.updateTimer = setInterval(() => void this.checkForUpdate(), SELF_UPDATE_CHECK_MS);
+    this.updateTimer.unref?.();
+    this.log("info", "started", { device: this.config.device.id, version: VERSION });
+  }
+
+  // ── self-update ────────────────────────────────────────────────────
+  /**
+   * Compare with the registry and, when idle, install the newer version
+   * and restart. A busy daemon retries once the turn ends; a version that
+   * failed to install is not retried (the dashboard shows the hint and
+   * `kai-bridge update` forces it). Never throws.
+   */
+  async checkForUpdate() {
+    if (this.stopped || this.updating) return;
+    // Tests and embedded hosts (the Desktop app ships its own copy).
+    if (process.env.KAI_BRIDGE_NO_SELF_UPDATE === "1") return;
+    let latest;
+    try {
+      latest = await fetchLatestVersion();
+    } catch (err) {
+      this.log("warn", "update.check.failed", { error: err?.message });
+      return;
+    }
+    this.updateAvailable = isNewer(latest, VERSION) ? latest : null;
+    const decision = decideUpdate({
+      current: VERSION,
+      latest,
+      running: this.running.size,
+      autoUpdate: this.config.autoUpdate !== false,
+      lastAttempt: this.config.selfUpdate?.lastAttempt ?? null,
+    });
+    if (decision.action === "skip") {
+      if (decision.reason === "busy") this.updatePending = latest;
+      return;
+    }
+    if (decision.action === "notify") {
+      this.updateError = decision.reason === "disabled" ? null : this.config.selfUpdate?.lastAttempt?.error || "previous install failed";
+      this.log("info", "update.available", { latest, reason: decision.reason });
+      await this.hello().catch(() => undefined);
+      return;
+    }
+    await this.applyUpdate(latest);
+  }
+
+  async applyUpdate(version) {
+    this.updating = true;
+    this.updatePending = null;
+    this.log("info", "update.installing", { from: VERSION, to: version });
+    const res = await installVersion(version);
+    this.config.selfUpdate = { lastAttempt: { version, ok: res.ok, at: new Date().toISOString(), error: res.error || null } };
+    try {
+      saveConfig(this.config, this.kaiHome);
+    } catch {
+      /* best-effort */
+    }
+    if (!res.ok) {
+      this.updating = false;
+      this.updateError = res.error;
+      this.log("error", "update.failed", { version, error: res.error });
+      await this.hello().catch(() => undefined);
+      return;
+    }
+    this.log("info", "update.installed", { version, restarting: true });
+    this.restartForUpdate();
+  }
+
+  /** Hand the machine to the new version: the service restarts us. */
+  restartForUpdate() {
+    this.stop();
+    if (platform() === "win32") {
+      // Task Scheduler only starts at logon — respawn ourselves instead.
+      const child = spawn(process.execPath, [process.argv[1], "start"], { detached: true, stdio: "ignore", windowsHide: true });
+      child.unref();
+      process.exit(0);
+    }
+    process.exit(RESTART_EXIT_CODE);
   }
 
   /** Install/version state per harness, plus the models it reported (when probed). */
@@ -277,6 +370,7 @@ export class BridgeDaemon {
     clearInterval(this.heartbeat);
     clearInterval(this.usageTimer);
     clearInterval(this.modelsTimer);
+    clearInterval(this.updateTimer);
     if (this.realtimeRetry) clearTimeout(this.realtimeRetry);
     for (const ctrl of this.running.values()) ctrl.abort();
     for (const runner of this.services.values()) runner.stopAll();
@@ -481,6 +575,15 @@ export class BridgeDaemon {
     this.log("info", "command", { name, turnId: data?.turnId, commandId: data?.commandId });
     switch (name) {
       case "bridge.turn.start":
+        if (this.updating) {
+          // Our files are being replaced under us — a turn started now
+          // would run half old, half new code. Seconds later the restarted
+          // daemon picks queued turns up again.
+          await this.api
+            .turnResult(data.turnId, { status: "failed", error: "This machine is updating kai-bridge — send the turn again in a minute." })
+            .catch((err) => this.log("warn", "update.turn.refused.failed", { turnId: data.turnId, error: err?.message }));
+          return;
+        }
         return this.startTurn(data);
       case "bridge.turn.cancel":
         this.running.get(data.turnId)?.abort();
@@ -822,6 +925,21 @@ export class BridgeDaemon {
       const completed = !ctrl.signal.aborted && res.code === 0 && !res.rateLimited;
       const changes = [...bound, ...this.adoptSessionWorktrees(turn, bound)].map((b) => {
         ensureCommitExcludes(b.cwd, { allowDevConfig: !!turn.allowDevConfig });
+        // A plan turn must leave the worktree as it found it — see
+        // discardChanges. Local checkouts are the user's; only report.
+        if (turn.planMode) {
+          const leaked = b.mode === "worktree" ? discardChanges(b.cwd).discarded : collectChanges(b.cwd).files;
+          if (leaked.length > 0) {
+            this.log("warn", "plan.changes", { turnId, repo: b.key, mode: b.mode, files: leaked.length, discarded: b.mode === "worktree" });
+            batcher.push({
+              type: "text",
+              message:
+                b.mode === "worktree"
+                  ? `Plan mode is read-only — ${leaked.length} file change${leaked.length === 1 ? "" : "s"} made during planning ${leaked.length === 1 ? "was" : "were"} discarded; the build starts from the plan.`
+                  : `Plan mode is read-only, but ${leaked.length} file change${leaked.length === 1 ? "" : "s"} landed in your local checkout of ${b.key} — review them before building.`,
+            });
+          }
+        }
         const diff = collectChanges(b.cwd);
         // Build turns in worktree mode publish the session branch so the
         // Server can open the PR; plan turns and local mode never push.
@@ -837,6 +955,10 @@ export class BridgeDaemon {
         // work that stayed on this machine (files but no push).
         return { key: b.key, mode: b.mode, branch: b.branch, base: b.base, cwd: b.cwd, adopted: b.adopted || undefined, ...diff, push };
       });
+      // The plan-mode notices above were queued AFTER the post-turn
+      // flush; land them before the result closes the turn (the Server
+      // answers 410 for events on an ended turn).
+      await batcher.flush();
       // Built OUTSIDE the report call: if posting the result throws, the
       // catch below must not turn a finished turn into a failed one. The
       // work is already committed and pushed at this point.
@@ -868,6 +990,7 @@ export class BridgeDaemon {
       this.forgetInflight(turnId);
       releaseAwake();
       this.running.delete(turnId);
+      if (this.updatePending && this.running.size === 0) void this.checkForUpdate();
     }
   }
 
@@ -892,7 +1015,9 @@ export class BridgeDaemon {
         notes.push(
           `\n\nNo .gleap/dev.yaml found in ${b.key}. If you figure out how this project's dev server runs, ` +
             `write .gleap/dev.yaml (services: { <name>: { cwd, run, port, health } }, preview: <name>) ` +
-            `so Gleap can run live previews for this repo in future sessions.`,
+            `so Gleap can run live previews for this repo in future sessions. This is optional housekeeping ` +
+            `for Gleap, not part of the task: it is committed separately, so never count it as work the user asked for ` +
+            `or mention it in your summary.`,
         );
       }
       if (!committed || !live) continue;

package/src/models.mjs

@@ -11,18 +11,23 @@
 //            (subscription tier, `availableModels` allowlist, gateway
 //            settings all applied by the CLI itself). Spawns the CLI
 //            (~2s), so never on hello's path — see the daemon's refresh.
-//   codex  — `<CODEX_HOME>/models_cache.json`, the model catalogue the
-//            Codex CLI fetches for the signed-in ChatGPT account. No
-//            spawn, plain file read.
+//   codex  — `codex debug models` from the BUNDLED CLI: the catalogue the
+//            backend serves for THIS client version under the signed-in
+//            ChatGPT account (spawns the CLI, ~1-2s). The profile's
+//            models_cache.json is only the fallback — another Codex (the
+//            ChatGPT app, a newer global CLI) writes it and lists models
+//            the bundled CLI cannot run yet.
 //   cursor — no catalogue surface; the dashboard keeps its static list.
 //
 // Ids are namespaced exactly like the Server's registry (`anthropic/…`,
 // `openai/…`) so the harness derivation, the BYO gate and the runner's
 // engine-slug derivation all keep working unchanged.
 
-import { existsSync, readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { promisify } from "node:util";
 import { harnessBinary } from "./harnesses.mjs";
 import { ambientConfigDir } from "./profiles.mjs";
 
@@ -168,7 +173,56 @@ export async function probeClaudeModels(configDir, kaiHome = process.env.KAI_HOM
   }
 }
 
-export function probeCodexModels(configDir) {
+const execFileAsync = promisify(execFile);
+
+/**
+ * Where the Codex catalogue probe runs. `codex debug models` needs a
+ * login, and CODEX_HOME must never be the user's real ~/.codex (the CLI
+ * writes its own cache + config there) — so a scratch home under
+ * ~/.kai/state seeded with a COPY of the profile's auth.json, the same
+ * rule the executor applies for turns.
+ */
+export function codexProbeHome(configDir, kaiHome) {
+  const home = join(kaiHome, "state", "models-probe", "codex");
+  mkdirSync(home, { recursive: true });
+  const auth = join(configDir, "auth.json");
+  if (existsSync(auth)) copyFileSync(auth, join(home, "auth.json"));
+  return home;
+}
+
+/**
+ * The bundled CLI's OWN catalogue: `codex debug models` renders the
+ * list the backend serves for THIS client version. The profile's
+ * models_cache.json is written by whichever Codex the user runs (the
+ * ChatGPT app, a newer global CLI) and can list models the bundled CLI
+ * cannot run yet — found live 2026-09-06: the picker offered
+ * gpt-6-astra, the turn died with "requires a newer version of Codex".
+ * `null` = the CLI could not answer (missing, signed out, timeout).
+ */
+export async function codexModelsFromCli(configDir, kaiHome, { timeoutMs = 30_000, exec = execFileAsync } = {}) {
+  const bin = harnessBinary("codex", kaiHome);
+  if (!bin) return null;
+  const env = { ...process.env, CODEX_HOME: codexProbeHome(configDir, kaiHome) };
+  delete env.OPENAI_API_KEY;
+  const { stdout } = await exec(bin, ["debug", "models"], { env, cwd: kaiHome, timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024 });
+  const parsed = JSON.parse(String(stdout));
+  const rows = codexModelsFromCache(parsed);
+  return rows.length ? rows : null;
+}
+
+/**
+ * Codex models under a login: the bundled CLI's own answer first, the
+ * profile's cache file only when the CLI cannot answer — never a list
+ * the CLI would then reject.
+ */
+export async function probeCodexModels(configDir, kaiHome = process.env.KAI_HOME || join(HOME, ".kai"), opts = {}) {
+  let fromCli = null;
+  try {
+    fromCli = await codexModelsFromCli(configDir, kaiHome, opts);
+  } catch {
+    fromCli = null;
+  }
+  if (fromCli) return fromCli;
   const cache = readCodexModelsCache(configDir);
   return cache ? codexModelsFromCache(cache) : null;
 }
@@ -181,6 +235,6 @@ export function probeCodexModels(configDir) {
  */
 export async function probeHarnessModels(harness, configDir, kaiHome, opts) {
   if (harness === "claude") return probeClaudeModels(configDir, kaiHome, opts);
-  if (harness === "codex") return probeCodexModels(configDir);
+  if (harness === "codex") return probeCodexModels(configDir, kaiHome, opts);
   return null;
 }

package/src/selfupdate.mjs

@@ -0,0 +1,105 @@
+// Self-update: the daemon checks npm for a newer @gleapai/kai-bridge and,
+// when idle, installs it into the same global prefix the login service
+// already points at, then exits so launchd/systemd restart it on the new
+// code (Windows: it re-spawns itself). Paired machines used to stay on
+// whatever version each teammate last typed `npm i -g` for.
+
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_NAME = "@gleapai/kai-bridge";
+export const REGISTRY_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The version of THIS install (re-read after an install to verify it). */
+export function installedVersion(root = PACKAGE_ROOT) {
+  return JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+}
+
+function parseVersion(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(String(v || "").trim());
+  if (!m) return null;
+  return { parts: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] || null };
+}
+
+/** semver-ish: -1 / 0 / 1; a prerelease ranks below its release; unparsable = equal. */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i += 1) {
+    if (pa.parts[i] !== pb.parts[i]) return pa.parts[i] > pb.parts[i] ? 1 : -1;
+  }
+  if (!!pa.pre !== !!pb.pre) return pa.pre ? -1 : 1;
+  return 0;
+}
+
+export function isNewer(latest, current) {
+  return compareVersions(latest, current) > 0;
+}
+
+/** The registry's `latest` dist-tag. Plain HTTPS — no npm needed to look. */
+export async function fetchLatestVersion({ fetchImpl = globalThis.fetch, timeoutMs = 8_000, url = REGISTRY_LATEST_URL } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal, headers: { accept: "application/json" } });
+    if (!res.ok) throw new Error(`registry ${res.status}`);
+    const body = await res.json();
+    if (!body?.version) throw new Error("registry response has no version");
+    return String(body.version);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * What to do about `latest`, given the daemon's state:
+ *   skip   — nothing to do now (up to date, or a turn is running: retry later)
+ *   notify — a newer version exists but we must not install it (auto-update
+ *            off, or this exact version already failed to install once)
+ *   update — install it now
+ */
+export function decideUpdate({ current, latest, running = 0, autoUpdate = true, lastAttempt = null }) {
+  if (!latest || !isNewer(latest, current)) return { action: "skip", reason: "up_to_date" };
+  if (autoUpdate === false) return { action: "notify", reason: "disabled" };
+  if (lastAttempt && lastAttempt.version === latest && lastAttempt.ok === false) return { action: "notify", reason: "failed_before" };
+  if (running > 0) return { action: "skip", reason: "busy" };
+  return { action: "update", reason: "newer" };
+}
+
+/** The npm that belongs to the node running us — same global prefix as the install. */
+export function npmBinary(execPath = process.execPath, os = platform()) {
+  const candidate = join(dirname(execPath), os === "win32" ? "npm.cmd" : "npm");
+  return existsSync(candidate) ? candidate : os === "win32" ? "npm.cmd" : "npm";
+}
+
+/**
+ * `npm install -g <pkg>@<version>` into the current prefix, then re-read the
+ * package.json at this install's path to prove the files were replaced.
+ * Async on purpose: the daemon's heartbeat keeps running while npm works.
+ */
+export function installVersion(version, { npm = npmBinary(), timeoutMs = 5 * 60_000, root = PACKAGE_ROOT, exec = execFile } = {}) {
+  return new Promise((resolve) => {
+    exec(
+      npm,
+      ["install", "-g", `${PACKAGE_NAME}@${version}`, "--no-fund", "--no-audit", "--loglevel=error"],
+      { timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, shell: platform() === "win32" },
+      (err, stdout, stderr) => {
+        const output = `${stdout || ""}${stderr || ""}`.trim().slice(-2000);
+        if (err) return resolve({ ok: false, version, error: `${err.message}${output ? `\n${output}` : ""}`.slice(0, 1500) });
+        let installed = null;
+        try {
+          installed = installedVersion(root);
+        } catch (readErr) {
+          return resolve({ ok: false, version, error: `installed, but could not read ${root}/package.json: ${readErr.message}` });
+        }
+        if (installed !== version) return resolve({ ok: false, version, error: `npm finished but ${root} still reports ${installed}` });
+        resolve({ ok: true, version });
+      },
+    );
+  });
+}

package/src/workspace.mjs

@@ -118,7 +118,12 @@ export function currentBranch(cwd) {
 
 /** Diff of what the turn changed (for the dashboard's file-changes panel). */
 export function collectChanges(cwd) {
-  const status = git(cwd, ["status", "--porcelain"]);
+  // NOT via git(): its trailing .trim() also strips the LEADING space of
+  // the first porcelain line, so a first entry that is a tracked
+  // modification (" M path") lost its space and every field shifted one
+  // char left — the file list reported to the Server read "EADME.md"
+  // (found 2026-09-06). Read raw; porcelain columns are fixed-width.
+  const status = execFileSync("git", ["status", "--porcelain"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
   const files = status
     .split("\n")
     .filter(Boolean)
@@ -127,6 +132,25 @@ export function collectChanges(cwd) {
   return { files, diff };
 }
 
+/**
+ * Throw away everything a turn left uncommitted — tracked edits and new
+ * files alike (ignored files stay: node_modules, .env copies). Plan
+ * turns are read-only by contract, but not every harness enforces it:
+ * codex-acp's "read-only" mode is a workspace-write sandbox that only
+ * asks before touching files OUTSIDE the workspace, and Codex went on to
+ * implement a whole ticket during its plan turn (2026-09-06). Whatever a
+ * plan turn changed is discarded here so the build turn starts from the
+ * base, exactly as the plan promised. Worktree mode only — a `local`
+ * binding is the user's own checkout and is never reset.
+ */
+export function discardChanges(cwd) {
+  const before = collectChanges(cwd).files;
+  if (before.length === 0) return { discarded: [] };
+  git(cwd, ["checkout", "--", "."]);
+  git(cwd, ["clean", "-fd"]);
+  return { discarded: before };
+}
+
 /** Drop a session's worktrees (after merge/close). */
 export function removeWorktree({ kaiHome, repo, sessionId, title }) {
   const dir = worktreePath(kaiHome, repo.name, sessionSlug(sessionId, title));