@gleapai/kai-bridge 0.9.0 → 0.9.1

package/README.md

@@ -8,6 +8,7 @@ npm i -g @gleapai/kai-bridge   # one install, so the background service has a st
 kai-bridge login             # pair this machine with your Gleap account
 kai-bridge 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)
 ```
 
 (`npx @gleapai/kai-bridge login` works for a quick look, but `install` needs the

package/bin/kai-bridge.mjs

@@ -7,6 +7,7 @@
 //   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>
@@ -28,6 +29,7 @@ import { defaultRoots, groupByRepo, scanRoots, toDeviceRepoReport } from "../src
 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";
+import { collectProcessList, formatProcessList } from "../src/ps.mjs";
 
 const BIN = fileURLToPath(import.meta.url);
 const argv = process.argv.slice(2);
@@ -68,6 +70,12 @@ async function status() {
   for (const r of toDeviceRepoReport(groups)) out(`  ${r.key.padEnd(48)} ${r.primaryPath}${r.checkouts > 1 ? ` (+${r.checkouts - 1})` : ""} ${r.dirtyCount ? `· ${r.dirtyCount} dirty` : ""}`);
 }
 
+/** Sessions running on this machine — read from the daemon's state files, so it works while the daemon is busy or down. */
+function ps() {
+  const list = collectProcessList();
+  out(flags.json ? JSON.stringify(list, null, 2) : formatProcessList(list));
+}
+
 async function profile() {
   const config = loadConfig();
   const sub = positional[0];
@@ -231,6 +239,9 @@ try {
     case "status":
       await status();
       break;
+    case "ps":
+      ps();
+      break;
     case "profile":
       await profile();
       break;
@@ -280,7 +291,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 | update
+  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>

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@gleapai/kai-bridge",
-      "version": "0.9.0",
+      "version": "0.9.1",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Kai Code Bridge runs Kai Code on your computer or server with your own coding subscriptions, local previews, and photo or video verification.",
   "type": "module",
   "license": "MIT",

package/src/api.mjs

@@ -210,6 +210,14 @@ export class BridgeApi {
   pendingTurns() {
     return this.request("GET", "/gleapcode/bridge/devices/me/pending");
   }
+  /**
+   * Provider git credentials for one connected repository — asked for only
+   * after this machine's own credentials were rejected (see git-auth.mjs).
+   */
+  gitCredentials(repoKey) {
+    return this.request("POST", "/gleapcode/bridge/devices/me/git-credentials", { repoKey });
+  }
+
   commandAck(commandId, payload) {
     return this.request("POST", `/gleapcode/bridge/commands/${encodeURIComponent(commandId)}/ack`, payload);
   }

package/src/daemon.mjs

@@ -54,6 +54,7 @@ import {
   rewriteStorageState,
   storageStateIsEmpty,
 } from "./preview-login.mjs";
+import { GIT_AUTH_TTL_MS, gitAuthEnv, isGitAuthError } from "./git-auth.mjs";
 import { describeHarnesses, installHarness, probeHarnessAuth } from "./harnesses.mjs";
 import { probeHarnessModels } from "./models.mjs";
 import { decideRestart, decideUpdate, fetchLatestVersion, installVersion, installedVersion, installedVersionOrNull, isNewer } from "./selfupdate.mjs";
@@ -158,6 +159,8 @@ export class BridgeDaemon {
     this.kaiHome = kaiHome;
     this.log = log;
     this.api = new BridgeApi({ apiBase: config.apiBase, token: config.device?.token });
+    /** repoKey → { authHeader, at }: Server-issued git credentials (see git-auth.mjs). */
+    this.gitAuth = new Map();
     this.realtimeFactory = realtimeFactory;
     this.running = new Map(); // turnId → { ctrl: AbortController, control?: (obj) => boolean }
     this.services = new Map(); // sessionId → ServiceRunner (lives across turns)
@@ -547,9 +550,11 @@ export class BridgeDaemon {
     }
   }
 
+  /** Merges: the runner pid and the verify artifacts dir arrive after the turn's session meta. */
   rememberInflight(turnId, meta = {}) {
-    const rest = this.readInflight().filter((e) => e.turnId !== turnId);
-    this.writeInflight([...rest, { turnId, ...meta }]);
+    const all = this.readInflight();
+    const existing = all.find((e) => e.turnId === turnId);
+    this.writeInflight([...all.filter((e) => e.turnId !== turnId), { ...existing, turnId, ...meta }]);
   }
 
   forgetInflight(turnId) {
@@ -611,11 +616,34 @@ export class BridgeDaemon {
     }
   }
 
-  /** ServiceRunner hook: every dev-server pid is persisted while it lives. */
-  trackServicePid(sessionId, name, pid, op) {
+  /**
+   * ServiceRunner hook: every dev-server pid is persisted while it lives —
+   * with its port and the session's title/link, so `kai-bridge ps` can
+   * show a preview-only session without a turn to borrow the meta from.
+   */
+  trackServicePid(sessionId, name, pid, op, { port = null } = {}) {
     if (!Number.isInteger(pid)) return;
     const rest = this.readPreviewPids().filter((e) => e.pid !== pid);
-    this.writePreviewPids(op === "add" ? [...rest, { pid, name, sessionId, startedAt: new Date().toISOString() }] : rest);
+    const session = this.sessionMeta?.get(sessionId) ?? {};
+    this.writePreviewPids(op === "add" ? [...rest, { pid, name, sessionId, port, ...session, startedAt: new Date().toISOString() }] : rest);
+  }
+
+  /**
+   * Title, dashboard link and repo keys of a session this machine works
+   * on — copied into the inflight / preview-pid entries (ps.mjs reads
+   * them back). Remembered from turn starts and preview starts alike.
+   */
+  rememberSession(sessionId, { title = null, sessionUrl = null, repos = [] } = {}) {
+    if (typeof sessionId !== "string") return {};
+    this.sessionMeta ??= new Map();
+    const prev = this.sessionMeta.get(sessionId) ?? {};
+    const meta = {
+      title: typeof title === "string" && title ? title : prev.title ?? null,
+      sessionUrl: typeof sessionUrl === "string" && sessionUrl ? sessionUrl : prev.sessionUrl ?? null,
+      repos: Array.isArray(repos) && repos.length ? repos.map((r) => (typeof r === "string" ? r : r?.key)).filter((k) => typeof k === "string") : prev.repos ?? [],
+    };
+    this.sessionMeta.set(sessionId, meta);
+    return meta;
   }
 
   /**
@@ -856,7 +884,8 @@ export class BridgeDaemon {
    * truncation. `companionRemotes` (Server-resolved `{ key: remote }`) is
    * how non-github companions get cloned; `note` survives onto error writes.
    */
-  async previewStart({ sessionId, title, repos, companionRemotes = null }) {
+  async previewStart({ sessionId, title, repos, sessionUrl = null, companionRemotes = null }) {
+    this.rememberSession(sessionId, { title, sessionUrl, repos });
     let lastNote = null;
     const skipped = [];
     // Every report is also RETURNED: the verify turn boots the preview
@@ -1220,7 +1249,7 @@ export class BridgeDaemon {
         ...(this.describeListener ? { describeListener: this.describeListener } : {}),
         ...(this.previewSettleMs != null ? { settleMs: this.previewSettleMs } : {}),
         onServiceExit: (info) => this.onServiceDied(sessionId, info),
-        onProcess: (name, pid, op) => this.trackServicePid(sessionId, name, pid, op),
+        onProcess: (name, pid, op, info) => this.trackServicePid(sessionId, name, pid, op, info),
       });
       this.services.set(sessionId, runner);
     }
@@ -1228,21 +1257,23 @@ export class BridgeDaemon {
   }
 
   /** Map the Server's repo bindings onto local checkouts; throw a readable error when one is missing. */
-  bindRepos(turn) {
+  async bindRepos(turn) {
     const bound = [];
     for (const r of turn.repos || []) {
       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";
-      const ws = materializeBinding({
+      const ws = await this.withGitAuth(r.key, (gitEnv) => materializeBinding({
         kaiHome: this.kaiHome,
         repo: { name: group.name, primaryPath: group.primary.path, defaultBranch: group.primary.defaultBranch },
         binding: { mode, base: r.base, carryUncommitted: r.carryUncommitted },
         sessionId: turn.sessionId,
         title: turn.title,
-      });
+        gitEnv,
+      }));
       bound.push({ key: r.key, ...ws });
       if (ws.deps) this.log("info", "deps.seed", { repo: r.key, ...ws.deps });
+      if (ws.fetch && (ws.fetch.stale || ws.fetch.attempts > 1)) this.log("warn", "workspace.fetch.contended", { repo: r.key, ...ws.fetch });
       // Remember the choice per repo (the UI asks once, then sticks).
       this.config.repoModes = { ...(this.config.repoModes || {}), [r.key]: mode };
     }
@@ -1310,11 +1341,13 @@ export class BridgeDaemon {
     // turn — see prepareVerifyTurn / finishVerification.
     const isVerify = turn.agent === "kai-verifier";
     let verify = null;
-    this.rememberInflight(turnId, { sessionId: turn.sessionId, agent: turn.agent ?? null });
+    // Everything `kai-bridge ps` shows for this turn; the runner pid follows at spawn.
+    const session = this.rememberSession(turn.sessionId, { title: turn.title, sessionUrl: turn.sessionUrl, repos: turn.repos });
+    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 {
       const profile = resolveProfiles(this.config, this.kaiHome).find((p) => p.id === turn.profileId) ?? { id: "gleap-key", kind: "gleap-key", harness: turn.harness };
-      const bound = this.bindRepos(turn);
+      const bound = await this.bindRepos(turn);
       // 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.
@@ -1342,7 +1375,7 @@ export class BridgeDaemon {
         }
         previewNote = verify.note;
         // The evidence dir is where a restart mid-run finds partial footage.
-        this.rememberInflight(turnId, { sessionId: turn.sessionId, agent: turn.agent, artifactsDir: verify.artifactsDir });
+        this.rememberInflight(turnId, { artifactsDir: verify.artifactsDir });
         mcpServers = [
           ...(turn.mcpServers || []),
           previewMcpServer(RUNNER_DIR, {
@@ -1377,6 +1410,7 @@ export class BridgeDaemon {
         signal: ctrl.signal,
         onSpawn: (handle) => {
           entry.control = handle.control;
+          if (Number.isInteger(handle.pid)) this.rememberInflight(turnId, { pid: handle.pid });
         },
         onEvent: (ev) => {
           if (verify) {
@@ -1401,7 +1435,7 @@ export class BridgeDaemon {
       // Plan and verify turns are read-only: worktrees are restored, local
       // checkouts only reported, nothing is ever committed or pushed.
       const readOnlyTurn = !!turn.planMode || isVerify;
-      const changes = [...bound, ...this.adoptSessionWorktrees(turn, bound)].map((b) => {
+      const changes = await Promise.all([...bound, ...this.adoptSessionWorktrees(turn, bound)].map(async (b) => {
         ensureCommitExcludes(b.cwd, { allowDevConfig: !!turn.allowDevConfig });
         // A read-only turn must leave the worktree as it found it — see
         // discardChanges. Local checkouts are the user's; only report.
@@ -1423,12 +1457,20 @@ export class BridgeDaemon {
         // Build turns in worktree mode publish the session branch so the
         // Server can open the PR; read-only turns and local mode never push.
         const shouldPush = completed && b.mode === "worktree" && !readOnlyTurn && diff.files.length > 0;
+        const pushOnce = (gitEnv) => {
+          const out = commitAndPush(b.cwd, {
+            branch: b.branch,
+            allowDevConfig: !!turn.allowDevConfig,
+            message: `${turn.title || "Kai Code changes"}\n\nSession ${turn.sessionId} · run on ${this.config.device?.name || "a paired device"}`,
+            gitEnv,
+          });
+          // commitAndPush reports instead of throwing; surface an auth
+          // rejection so withGitAuth can retry the push (the commit exists).
+          if (!out.pushed && !gitEnv && isGitAuthError(out.error)) throw Object.assign(new Error(out.error), { push: out });
+          return out;
+        };
         const push = shouldPush
-          ? commitAndPush(b.cwd, {
-              branch: b.branch,
-              allowDevConfig: !!turn.allowDevConfig,
-              message: `${turn.title || "Kai Code changes"}\n\nSession ${turn.sessionId} · run on ${this.config.device?.name || "a paired device"}`,
-            })
+          ? await this.withGitAuth(b.key, pushOnce).catch((err) => err.push ?? { committed: false, pushed: false, branch: b.branch, error: err.message })
           : isVerify
             ? false
             : null;
@@ -1438,7 +1480,7 @@ export class BridgeDaemon {
         // Server can write a real pull request description.
         const described = push?.pushed ? describeBranchChanges(b.cwd, b.base) : null;
         return { key: b.key, mode: b.mode, branch: b.branch, base: b.base, cwd: b.cwd, adopted: b.adopted || undefined, ...diff, push, ...(described ? described : {}) };
-      });
+      }));
       // The read-only 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).
@@ -1462,9 +1504,11 @@ export class BridgeDaemon {
         profileId: profile.id,
       };
     } catch (err) {
-      this.log("error", "turn.failed", { turnId, error: err.message });
+      this.log("error", "turn.failed", { turnId, error: err.message, ...(err.code ? { code: err.code, repo: err.repo } : {}) });
       await batcher.flush().catch(() => {});
-      outcome = outcome ?? { status: "failed", error: err.message };
+      // A WorkspaceError names why the checkout could not be prepared;
+      // the Server turns `failure.code` into a one-click retry.
+      outcome = outcome ?? { status: "failed", error: err.message, ...(err.code ? { failure: { code: err.code, repo: err.repo ?? null } } : {}) };
     } finally {
       // One report, retried until it lands — a dropped result is what
       // leaves a session spinning forever in the dashboard.
@@ -1670,7 +1714,7 @@ export class BridgeDaemon {
     this.previewStatusListeners.set(sessionId, heartbeat.note);
     let preview;
     try {
-      preview = await this.previewStart({ sessionId, title: turn.title, repos: turn.repos, companionRemotes: turn.companionRemotes ?? null });
+      preview = await this.previewStart({ sessionId, title: turn.title, repos: turn.repos, sessionUrl: turn.sessionUrl ?? null, companionRemotes: turn.companionRemotes ?? null });
     } finally {
       this.previewStatusListeners?.delete(sessionId);
       heartbeat.stop();
@@ -2390,6 +2434,43 @@ export class BridgeDaemon {
     return { note: notes.join(""), hasLivePreview: previews.length > 0 };
   }
 
+  /**
+   * Run a git network op with this machine's own credentials; when those are
+   * rejected, retry ONCE with the Server-issued credentials for `repoKey`
+   * (connected repos only — anything else rethrows the original error).
+   */
+  async withGitAuth(repoKey, run) {
+    try {
+      return await run(null);
+    } catch (err) {
+      if (!repoKey || !isGitAuthError(err)) throw err;
+      let authHeader;
+      try {
+        authHeader = await this.gitAuthHeader(repoKey);
+      } catch (credErr) {
+        this.log("warn", "git.auth.unavailable", { repo: repoKey, error: credErr.message });
+        throw err;
+      }
+      this.log("info", "git.auth.fallback", { repo: repoKey });
+      try {
+        return await run(gitAuthEnv(authHeader));
+      } catch (retryErr) {
+        // Stale or revoked: never reuse it for the next attempt.
+        if (isGitAuthError(retryErr)) this.gitAuth.delete(repoKey);
+        throw retryErr;
+      }
+    }
+  }
+
+  async gitAuthHeader(repoKey) {
+    const cached = this.gitAuth.get(repoKey);
+    if (cached && Date.now() - cached.at < GIT_AUTH_TTL_MS) return cached.authHeader;
+    const { authHeader } = await this.api.gitCredentials(repoKey);
+    if (!authHeader) throw new Error("The Server returned no git credentials.");
+    this.gitAuth.set(repoKey, { authHeader, at: Date.now() });
+    return authHeader;
+  }
+
   /**
    * Clone `remote` into the preferred root as `name`. Hardened for
    * unattended runs: no credential prompts (`GIT_TERMINAL_PROMPT=0`,
@@ -2401,7 +2482,7 @@ export class BridgeDaemon {
   async cloneRepo({ commandId, remote, name, repoKey, timeoutMs = CLONE_TIMEOUT_MS }) {
     const root = preferredCloneRoot(this.repoGroups, (this.config.roots || [])[0] ?? defaultRoots()[0]);
     try {
-      const target = await cloneRepository({ remote, name, root, repoKey, timeoutMs });
+      const target = await this.withGitAuth(repoKey, (gitEnv) => cloneRepository({ remote, name, root, repoKey, timeoutMs, gitEnv }));
       await this.scanRepos();
       // Ack only after the Server has the new inventory: recovery checks
       // readiness before automatically retrying the blocked session.

package/src/executor.mjs

@@ -151,6 +151,8 @@ export function runTurn({ turn, profile, workDir, onEvent, onLog = () => {}, onS
     const child = spawn(process.execPath, [RUNNER, ...args], { cwd: workDir, env, stdio: ["pipe", "pipe", "pipe"] });
     child.stdin.on("error", () => {});
     onSpawn?.({
+      /** The runner's pid — the daemon records it for `kai-bridge ps`. */
+      pid: child.pid,
       /** Write one control line; false when the runner is already gone. */
       control(obj) {
         if (child.exitCode !== null || child.killed || !child.stdin.writable) return false;

package/src/git-auth.mjs

@@ -0,0 +1,38 @@
+// Git credentials of last resort.
+//
+// Every git network op runs with the machine's own credentials first: that
+// keeps the user's identity, their SSH keys and their org SSO exactly as
+// they are. A device that was never signed in to GitHub (a fresh Mac, a
+// shared box, a CI-ish machine) has none, and a clone, the prep fetch or
+// the end-of-turn push then dies with "Authentication failed".
+//
+// For those — and ONLY those — the Server hands out the same short-lived
+// provider credentials Kai Code Cloud clones with, for one repository, on
+// demand. The header is passed through the environment for that single git
+// command: it never reaches `.git/config`, the remote URL, or `ps` output.
+
+const AUTH_FAILURE = /authentication failed|invalid username or (?:token|password)|could not read (?:username|password)|terminal prompts disabled|permission denied \(publickey\)|remote: (?:invalid|write access|permission)|403 forbidden|repository not found|please ask the owner|support for password authentication was removed/i;
+
+export const isGitAuthError = (err) =>
+  // `cause`: workspace.mjs wraps a failed fetch in a WorkspaceError.
+  AUTH_FAILURE.test([err?.stderr, err?.message, err?.cause?.stderr, err?.cause?.message, typeof err === "string" ? err : ""]
+    .map((part) => String(part ?? "")).join(" "));
+
+/**
+ * `git -c http.extraheader=…` without the command line: GIT_CONFIG_COUNT
+ * config pairs are read by git itself, so the token stays out of argv.
+ */
+export function gitAuthEnv(authHeader) {
+  if (!authHeader) return null;
+  return {
+    GIT_CONFIG_COUNT: "1",
+    GIT_CONFIG_KEY_0: "http.extraheader",
+    GIT_CONFIG_VALUE_0: String(authHeader),
+    // The header authenticates; never let a helper prompt on top of it.
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_ASKPASS: "echo",
+  };
+}
+
+/** Keep a repo's credentials only while they are certainly still valid. */
+export const GIT_AUTH_TTL_MS = 30 * 60_000;

package/src/preview.mjs

@@ -414,7 +414,7 @@ export class ServiceRunner {
    * `describeListener(port)` (ports.mjs by default) decides adoption;
    * `onServiceExit({ name, code, repoRoot, repoKey, logPath, error, errorCode, detail })`
    * fires when a service that had become ready dies on its own;
-   * `onProcess(name, pid, "add" | "remove")` lets the daemon persist pids.
+   * `onProcess(name, pid, "add" | "remove", { port })` lets the daemon persist pids.
    */
   constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {}, preferredPort = null, describeListener = null, settleMs = DEFAULT_SETTLE_MS, onServiceExit = () => {}, onProcess = () => {}, home = homedir() } = {}) {
     if (settleMs === DEFAULT_SETTLE_MS) settleMs = defaultSettleMs();
@@ -629,7 +629,7 @@ export class ServiceRunner {
       ).catch(() => {});
     });
     this.processes.set(name, child);
-    this.onProcess(name, child.pid, "add");
+    this.onProcess(name, child.pid, "add", { port });
     this.onStatus(`Starting ${name} (${cmd}) on :${port}`);
     // Bail as soon as the process dies (command not found, crash on
     // boot) instead of polling a dead port for the full timeout.

package/src/ps.mjs

@@ -0,0 +1,152 @@
+// `kai-bridge ps` — what this machine is running right now, grouped by
+// Kai Code session. Read-only: it never talks to the daemon, it reads
+// the files the daemon keeps for crash recovery (daemon.mjs):
+//
+//   ~/.kai/daemon.lock               pid of the running daemon
+//   ~/.kai/state/inflight.json       turns in progress (+ runner pid, session meta)
+//   ~/.kai/state/preview-pids.json   dev-server processes (+ port, session meta)
+//
+// Liveness is `kill -0`. Dead pids are LABELLED, never cleaned up — the
+// daemon owns those files (reportInterruptedTurns / adoptPreviewPids).
+// `collectProcessList` is the one source of truth for the text view,
+// `--json`, and any host UI (a menu-bar widget) that wants the same list.
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { KAI_HOME } from "./config.mjs";
+import { installedVersionOrNull } from "./selfupdate.mjs";
+
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the process exists but belongs to someone else — still alive.
+    return err?.code === "EPERM";
+  }
+}
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function readDaemon(kaiHome, isAlive, version) {
+  const lock = join(kaiHome, "daemon.lock");
+  let pid = null;
+  let startedAt = null;
+  try {
+    pid = Number(readFileSync(lock, "utf8").trim()) || null;
+    // The lock is written once, when the daemon starts (acquireLock).
+    startedAt = statSync(lock).mtime.toISOString();
+  } catch {
+    /* no lock — no daemon */
+  }
+  const running = pid != null && isAlive(pid);
+  return { running, pid, version, startedAt: running ? startedAt : null };
+}
+
+/** Pre-0.5.0 inflight files held bare turn ids. */
+function normaliseInflight(raw) {
+  return (Array.isArray(raw) ? raw : []).map((e) => (typeof e === "string" ? { turnId: e } : e)).filter((e) => e && typeof e.turnId === "string");
+}
+
+/**
+ * `{ daemon: { running, pid, version, startedAt }, sessions: [{ sessionId,
+ * title, sessionUrl, repos, turns: [...], services: [...] }] }`.
+ * Turn state: running | exited (runner pid gone, daemon still up) |
+ * interrupted (daemon down). Service state: running | dead.
+ */
+export function collectProcessList({ kaiHome = KAI_HOME, isAlive = pidAlive, version = installedVersionOrNull() } = {}) {
+  const daemon = readDaemon(kaiHome, isAlive, version);
+  const inflight = normaliseInflight(readJson(join(kaiHome, "state", "inflight.json"), []));
+  const previewPids = readJson(join(kaiHome, "state", "preview-pids.json"), []);
+  const services = (Array.isArray(previewPids) ? previewPids : []).filter((e) => e && Number.isInteger(e.pid));
+
+  const sessions = new Map(); // sessionId (or null) → session block, in first-seen order
+  const sessionFor = (entry) => {
+    const id = typeof entry.sessionId === "string" ? entry.sessionId : null;
+    let s = sessions.get(id);
+    if (!s) {
+      s = { sessionId: id, title: null, sessionUrl: null, repos: [], turns: [], services: [] };
+      sessions.set(id, s);
+    }
+    // Every entry denormalises the session meta; the first one that has it wins.
+    if (!s.title && typeof entry.title === "string") s.title = entry.title;
+    if (!s.sessionUrl && typeof entry.sessionUrl === "string") s.sessionUrl = entry.sessionUrl;
+    if (!s.repos.length && Array.isArray(entry.repos)) s.repos = entry.repos.filter((r) => typeof r === "string");
+    return s;
+  };
+
+  for (const e of inflight) {
+    const pid = Number.isInteger(e.pid) ? e.pid : null;
+    const state = !daemon.running ? "interrupted" : pid != null && !isAlive(pid) ? "exited" : "running";
+    sessionFor(e).turns.push({ turnId: e.turnId, agent: e.agent ?? null, harness: e.harness ?? null, profileId: e.profileId ?? null, pid, startedAt: e.startedAt ?? null, state });
+  }
+  for (const e of services) {
+    sessionFor(e).services.push({ name: e.name ?? null, pid: e.pid, port: Number.isInteger(e.port) ? e.port : null, startedAt: e.startedAt ?? null, state: isAlive(e.pid) ? "running" : "dead" });
+  }
+  return { daemon, sessions: [...sessions.values()] };
+}
+
+// ── text view ───────────────────────────────────────────────────────
+
+/** "2h 13m", "3m 12s", "45s" — how long since `iso`. */
+export function formatAge(iso, now = Date.now()) {
+  const ms = iso ? now - Date.parse(iso) : NaN;
+  if (!Number.isFinite(ms) || ms < 0) return "?";
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  return `${Math.floor(h / 24)}d ${h % 24}h`;
+}
+
+/** Minutes-and-up version for long-lived dev servers ("14m", "2h 13m"). */
+function formatUptime(iso, now) {
+  const age = formatAge(iso, now);
+  return age.endsWith("s") && !age.includes("m") ? age : age.replace(/ \d+s$/, "");
+}
+
+function turnLine(t, now) {
+  const who = [t.agent ?? "turn", t.harness && t.profileId ? `${t.harness}/${t.profileId}` : t.harness ?? ""].filter(Boolean);
+  const state =
+    t.state === "running" ? `running ${formatAge(t.startedAt, now)}` : t.state === "exited" ? "exited — runner gone, daemon still winding it down" : "interrupted — daemon is down";
+  return `  turn   ${t.turnId.padEnd(26)} ${who[0].padEnd(16)} ${(who[1] ?? "").padEnd(16)} ${(t.pid != null ? `pid ${t.pid}` : "").padEnd(10)} ${state}`;
+}
+
+function serviceLine(s, now) {
+  const state = s.state === "running" ? `up ${formatUptime(s.startedAt, now)}` : "dead — stale entry";
+  return `  dev    ${(s.name ?? "?").padEnd(26)} ${"".padEnd(16)} ${"".padEnd(16)} ${`pid ${s.pid}`.padEnd(10)} ${(s.port != null ? `:${s.port}` : "").padEnd(7)} ${state}`;
+}
+
+export function formatProcessList(list, { now = Date.now() } = {}) {
+  const lines = [];
+  const d = list.daemon;
+  lines.push(
+    d.running
+      ? `daemon:   running · pid ${d.pid}${d.version ? ` · v${d.version}` : ""} · up ${formatUptime(d.startedAt, now)}`
+      : `daemon:   not running${d.pid ? ` (stale lock, pid ${d.pid})` : ""} — run \`kai-bridge start\` or \`kai-bridge install\``,
+  );
+  if (!list.sessions.length) {
+    lines.push("", "nothing running on this machine");
+    return lines.join("\n");
+  }
+  for (const s of list.sessions) {
+    lines.push("");
+    const head = [`session ${s.sessionId ?? "(unknown)"}`, s.title ? `"${s.title}"` : "(untitled)"];
+    if (s.repos.length) head.push(s.repos.join(", "));
+    lines.push(head.join("  "));
+    if (s.sessionUrl) lines.push(`  ${s.sessionUrl}`);
+    for (const t of s.turns) lines.push(turnLine(t, now));
+    for (const sv of s.services) lines.push(serviceLine(sv, now));
+  }
+  return lines.join("\n");
+}

package/src/repository-setup.mjs

@@ -27,7 +27,7 @@ export function locateRepository(rawPath, repoKey) {
   return target;
 }
 
-export function cloneRepository({ remote, name, root, repoKey, timeoutMs = 180_000 }, spawnGit = spawn) {
+export function cloneRepository({ remote, name, root, repoKey, timeoutMs = 180_000, gitEnv = null }, spawnGit = spawn) {
   if (typeof remote !== 'string' || !(/^(https?|ssh):\/\/\S+$/i.test(remote) || /^[\w.-]+@[\w.-]+:\S+$/.test(remote))) {
     return Promise.reject(new Error('This repository has an unsupported clone URL.'));
   }
@@ -53,7 +53,7 @@ export function cloneRepository({ remote, name, root, repoKey, timeoutMs = 180_0
           stdio: ['ignore', 'ignore', 'pipe'],
           detached: process.platform !== 'win32',
           env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'echo', SSH_ASKPASS: 'echo',
-            GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || 'ssh -o BatchMode=yes' },
+            GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || 'ssh -o BatchMode=yes', ...(gitEnv || {}) },
         });
         let stderr = '';
         let timedOut = false;

package/src/workspace.mjs

@@ -22,6 +22,89 @@ function git(cwd, args, opts = {}) {
   return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...opts }).trim();
 }
 
+/** Network ops only: `gitEnv` is the git-auth.mjs fallback, applied to that one command. */
+const withGitEnv = (gitEnv, opts = {}) => (gitEnv ? { ...opts, env: { ...process.env, ...gitEnv } } : opts);
+
+/**
+ * A workspace could not be prepared for a reason that has nothing to do
+ * with the task — the Server surfaces `code` as a one-click retry instead
+ * of a dead session. `repo` names the checkout for the log line.
+ */
+export class WorkspaceError extends Error {
+  constructor(message, { code, repo, cause } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = "WorkspaceError";
+    this.code = code;
+    this.repo = repo;
+  }
+}
+
+/**
+ * Git refused to update a ref because ANOTHER git process was writing the
+ * same repo at that moment: the bridge fetches `origin/<base>` in the
+ * user's primary checkout, and IDE auto-fetch / a second session /
+ * the user's own `git pull` race it there. The loser sees one of:
+ *
+ *   cannot lock ref 'refs/remotes/origin/master': is at <new> but expected <old>
+ *   Unable to create '…/refs/remotes/origin/master.lock': File exists.
+ *   Another git process seems to be running in this repository
+ *
+ * None of them mean anything is wrong — the ref is simply being moved by
+ * someone else — so the fetch is retried, and if it keeps losing the
+ * ref the competitor just wrote is used as the base (2026-09-16: a
+ * session on ticket #147312 died 54 s in on exactly this, before the
+ * agent ever ran).
+ */
+export function isRefLockContention(message) {
+  const text = String(message || "");
+  return (
+    /cannot lock ref/i.test(text) ||
+    /\.lock['"]?: File exists/i.test(text) ||
+    /Another git process seems to be running/i.test(text)
+  );
+}
+
+const sleepSync = (ms) => {
+  if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
+/**
+ * `git fetch origin <base>` in `primaryPath`, tolerant of ref-lock
+ * contention. Returns `{ attempts, stale }` — `stale: true` means every
+ * attempt lost the race and the existing `origin/<base>` (which the
+ * competitor just updated) is used instead. Any other fetch failure, or
+ * contention with no usable `origin/<base>`, throws a WorkspaceError
+ * whose `code` the Server turns into a retry offer.
+ */
+export function fetchBase(primaryPath, base, { exec = git, attempts = 4, backoffMs = 400, sleep = sleepSync, repo = primaryPath, gitEnv = null } = {}) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      exec(primaryPath, ["fetch", "origin", base, "--quiet"], withGitEnv(gitEnv));
+      return { attempts: attempt, stale: false };
+    } catch (err) {
+      const text = `${err?.stderr || ""}\n${err?.message || ""}`;
+      if (!isRefLockContention(text)) {
+        throw new WorkspaceError(err?.message || String(err), { code: "workspace_fetch_failed", repo, cause: err });
+      }
+      lastError = err;
+      if (attempt < attempts) sleep(backoffMs * attempt);
+    }
+  }
+  // Every attempt lost: whoever kept winning has already moved
+  // origin/<base> forward, so it is at least as fresh as our fetch
+  // would have made it.
+  try {
+    exec(primaryPath, ["rev-parse", "--verify", "--quiet", `origin/${base}^{commit}`]);
+    return { attempts, stale: true };
+  } catch {
+    throw new WorkspaceError(
+      `Git in ${repo} was busy (another fetch was running) and origin/${base} is not available yet — retry the task.`,
+      { code: "workspace_transient", repo, cause: lastError },
+    );
+  }
+}
+
 export function sessionSlug(sessionId, title) {
   const t = String(title || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32);
   const id = String(sessionId || "").slice(-8);
@@ -67,7 +150,7 @@ export function copyPrimaryEnvFiles(primaryPath, cwd) {
  * Materialise one repo binding. Returns `{ cwd, mode, branch, base }`.
  * `repo` = `{ name, primaryPath, defaultBranch }`, `binding` = `{ mode, base?, carryUncommitted? }`.
  */
-export function materializeBinding({ kaiHome, repo, binding, sessionId, title, branchPrefix = "kai" }) {
+export function materializeBinding({ kaiHome, repo, binding, sessionId, title, branchPrefix = "kai", fetch = fetchBase, gitEnv = null }) {
   const mode = binding?.mode === "local" ? "local" : "worktree";
   if (mode === "local") {
     const branch = git(repo.primaryPath, ["rev-parse", "--abbrev-ref", "HEAD"]);
@@ -82,7 +165,7 @@ export function materializeBinding({ kaiHome, repo, binding, sessionId, title, b
     return { cwd: dir, mode, branch, base, resumed: true };
   }
   mkdirSync(dirname(dir), { recursive: true });
-  git(repo.primaryPath, ["fetch", "origin", base, "--quiet"]);
+  const fetched = fetch(repo.primaryPath, base, { repo: repo.name, gitEnv });
   git(repo.primaryPath, ["worktree", "add", "-b", branch, dir, `origin/${base}`]);
   // A fresh worktree has no node_modules; clone the primary checkout's
   // when the lockfiles match so the agent's tests and the preview boot
@@ -110,7 +193,7 @@ export function materializeBinding({ kaiHome, repo, binding, sessionId, title, b
       }
     }
   }
-  return { cwd: dir, mode, branch, base, resumed: false, deps };
+  return { cwd: dir, mode, branch, base, resumed: false, deps, fetch: fetched };
 }
 
 /** The branch checked out at `cwd` (null when it is not a git checkout). */
@@ -267,7 +350,7 @@ export function ensureCommitExcludes(cwd, { allowDevConfig = false } = {}) {
   }
 }
 
-export function commitAndPush(cwd, { branch, message, allowEmpty = false, allowDevConfig = false } = {}) {
+export function commitAndPush(cwd, { branch, message, allowEmpty = false, allowDevConfig = false, gitEnv = null } = {}) {
   const out = { committed: false, pushed: false, branch, commitSha: null, remote: null, error: null };
   try {
     ensureCommitExcludes(cwd, { allowDevConfig });
@@ -279,7 +362,7 @@ export function commitAndPush(cwd, { branch, message, allowEmpty = false, allowD
     }
     out.commitSha = git(cwd, ["rev-parse", "HEAD"]);
     out.remote = git(cwd, ["remote", "get-url", "origin"]);
-    git(cwd, ["push", "-u", "origin", `HEAD:${branch}`], { timeout: 120_000 });
+    git(cwd, ["push", "-u", "origin", `HEAD:${branch}`], withGitEnv(gitEnv, { timeout: 120_000 }));
     out.pushed = true;
   } catch (err) {
     out.error = String(err?.stderr || err?.message || err).trim().slice(0, 500);