@gleapai/kai-bridge 0.7.0 → 0.9.1

package/src/harness-install.mjs

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+export const HARNESS_PACKAGES = { codex: '@openai/codex', claude: '@anthropic-ai/claude-agent-sdk' };
+const rootFor = (home, harness) => join(home, 'harnesses', harness);
+
+export function managedHarnessRoot(home, harness) {
+  try {
+    const { active } = JSON.parse(readFileSync(join(rootFor(home, harness), 'active.json'), 'utf8'));
+    if (!/^[a-f0-9-]{36}$/.test(active)) return null;
+    const root = join(rootFor(home, harness), 'releases', active);
+    return existsSync(join(root, 'package.json')) ? root : null;
+  } catch { return null; }
+}
+
+async function installPackage(destination, spec) {
+  const npmCli = [process.env.npm_execpath, join(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js'), join(dirname(process.execPath), '../lib/node_modules/npm/bin/npm-cli.js')]
+    .find(p => p?.endsWith('npm-cli.js') && existsSync(p));
+  if (!npmCli && process.platform === 'win32') throw new Error('npm is missing. Install Node.js with npm, then retry.');
+  const args = ['install', '--prefix', destination, '--ignore-scripts', '--save-exact', '--no-audit', '--no-fund', spec];
+  await exec(npmCli ? process.execPath : 'npm', npmCli ? [npmCli, ...args] : args, {
+    timeout: 5 * 60_000, maxBuffer: 2 * 1024 * 1024,
+  });
+}
+
+/** Download into an isolated release, verify it runs, then atomically select it.
+ * Existing sessions retain their old binaries; profiles and global CLIs are untouched. */
+export async function installManagedHarness({ harness, kaiHome, version = 'latest', resolveBinary, probeVersion, onLog = () => {}, install = installPackage }) {
+  const packageName = HARNESS_PACKAGES[harness];
+  if (!packageName || !/^(latest|\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?)$/.test(version)) throw new Error('Choose a valid coding agent version.');
+  const root = rootFor(kaiHome, harness);
+  mkdirSync(root, { recursive: true });
+  const lock = join(root, '.install-lock');
+  try { mkdirSync(lock); } catch {
+    let abandoned = false;
+    try {
+      const { pid } = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+      if (Number.isSafeInteger(pid) && pid > 0) {
+        try { process.kill(pid, 0); } catch (error) { abandoned = error.code === 'ESRCH'; }
+      }
+    } catch { abandoned = Date.now() - statSync(lock).mtimeMs > 10 * 60_000; }
+    if (!abandoned) throw new Error('An installation is already running for this agent. Try again when it finishes.');
+    rmSync(lock, { recursive: true, force: true });
+    try { mkdirSync(lock); } catch { throw new Error('Another agent installation started. Try again when it finishes.'); }
+  }
+  writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid }));
+  const release = randomUUID();
+  const destination = join(root, 'releases', release);
+  const temporary = join(root, `active-${release}.tmp`);
+  let activated = false;
+  try {
+    mkdirSync(destination, { recursive: true });
+    writeFileSync(join(destination, 'package.json'), JSON.stringify({ private: true }));
+    onLog(`Installing ${harness} ${version}…`);
+    await install(destination, `${packageName}@${version}`);
+    const binary = resolveBinary(destination);
+    const detected = binary && await probeVersion(binary);
+    if (!detected) throw new Error('The new coding agent did not start. Your previous version is still selected.');
+    writeFileSync(temporary, JSON.stringify({ active: release, version: detected }), { mode: 0o600 });
+    renameSync(temporary, join(root, 'active.json'));
+    activated = true;
+    onLog(`Ready: ${detected}`);
+    return { ok: true, version: detected, binary };
+  } finally {
+    rmSync(temporary, { force: true });
+    if (!activated) rmSync(destination, { recursive: true, force: true });
+    rmSync(lock, { recursive: true, force: true });
+  }
+}

package/src/harnesses.mjs

@@ -1,18 +1,4 @@
-// Harness registry: which coding agents this device can run, how to find
-// their binaries, install/update them, probe their login, and open a
-// login.
-//
-//   claude — Claude Code. BUNDLED: the ACP adapter ships the Agent SDK,
-//            which ships the CLI. Nothing to install; only a login.
-//   codex  — Codex CLI. BUNDLED by codex-acp. Only a login.
-//   cursor — Cursor Agent CLI. NOT bundled (no npm package); installed by
-//            the bridge from Cursor's release tarball into
-//            ~/.kai/harnesses/cursor/<version>/ and called by path — never
-//            via the vendor's ~/.local/bin/agent symlink (other vendors
-//            use that name too: Grok's CLI on at least one dev machine).
-//
-// "Installed" therefore means: claude/codex always; cursor when the
-// tarball is present. "Signed in" is per profile (see profiles.mjs).
+// Coding agents: bundled defaults, optional managed updates, and per-profile sign-in.
 
 import { execFileSync, spawn } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
@@ -20,6 +6,7 @@ import { arch, homedir, platform } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from 'node:module';
+import { managedHarnessRoot, installManagedHarness } from './harness-install.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_BIN = join(PKG, "node_modules", ".bin");
@@ -76,12 +63,12 @@ export function cursorDownloadUrl(version = CURSOR_AGENT_VERSION) {
 }
 
 /** Bundled / installed binary for a harness, or null. */
-export function harnessBinary(harness, kaiHome = join(homedir(), ".kai")) {
+function packageBinary(harness, packageRequire) {
   if (harness === "claude") {
     try {
       // Resolve from the SDK exactly as the ACP adapter does, including nested
       // npm installs and the correct libc. Directory order is not a platform check.
-      const sdkRequire = createRequire(require.resolve('@anthropic-ai/claude-agent-sdk'));
+      const sdkRequire = createRequire(packageRequire.resolve('@anthropic-ai/claude-agent-sdk'));
       const libc = platform() === 'linux' && !process.report.getReport().header.glibcVersionRuntime ? '-musl' : '';
       return sdkRequire.resolve(`@anthropic-ai/claude-agent-sdk-${platform()}-${arch()}${libc}/claude${platform() === 'win32' ? '.exe' : ''}`);
     } catch {
@@ -94,15 +81,25 @@ export function harnessBinary(harness, kaiHome = join(homedir(), ".kai")) {
       if (platform() === 'win32') {
         // execFile/ACP cannot execute a JS entrypoint or .cmd shim directly on
         // Windows. Resolve the same pinned package's native executable there.
-        const codexRequire = createRequire(require.resolve('@openai/codex/package.json'));
+        const codexRequire = createRequire(packageRequire.resolve('@openai/codex/package.json'));
         const root = dirname(codexRequire.resolve(`@openai/codex-win32-${arch()}/package.json`));
         const triple = `${arch() === 'arm64' ? 'aarch64' : 'x86_64'}-pc-windows-msvc`;
         const binary = join(root, 'vendor', triple, 'bin', 'codex.exe');
         return existsSync(binary) ? binary : null;
       }
-      return require.resolve('@openai/codex/bin/codex.js');
+      return packageRequire.resolve('@openai/codex/bin/codex.js');
     } catch { return null; }
   }
+  return null;
+}
+
+export function harnessBinary(harness, kaiHome = process.env.KAI_HOME || join(homedir(), ".kai")) {
+  const managed = managedHarnessRoot(kaiHome, harness);
+  if (managed) {
+    const binary = packageBinary(harness, createRequire(join(managed, "package.json")));
+    if (binary && existsSync(binary)) return binary;
+  }
+  if (harness === "claude" || harness === "codex") return packageBinary(harness, require);
   if (harness === "cursor") {
     const bin = join(CURSOR_CURRENT(kaiHome), "dist-package", platform() === "win32" ? "cursor-agent.exe" : "cursor-agent");
     return existsSync(bin) ? bin : null;
@@ -146,18 +143,22 @@ export function describeHarnesses(kaiHome) {
 }
 
 /**
- * Install (or update) a harness. Bundled ones are no-ops. Cursor:
+ * Install (or update) a coding agent. Cursor:
  * download the release tarball for this platform into
  * ~/.kai/harnesses/cursor/<version>/ and point `current` at it.
  * `onLog(line)` receives progress; resolves `{ ok, version, binary }`.
  */
-export async function installHarness(harness, { kaiHome, onLog = () => {}, version = CURSOR_AGENT_VERSION } = {}) {
+export async function installHarness(harness, { kaiHome = process.env.KAI_HOME || join(homedir(), ".kai"), onLog = () => {}, version, update = false } = {}) {
   if (!HARNESS_IDS.includes(harness)) throw new Error(`unknown harness ${harness}`);
   if (HARNESS_INFO[harness].bundled) {
     const bin = harnessBinary(harness, kaiHome);
-    onLog(`${HARNESS_INFO[harness].label} is bundled with the bridge (${bin ? versionOf(bin) : "missing — run npm install"})`);
-    return { ok: !!bin, version: bin ? versionOf(bin) : null, binary: bin };
+    const currentVersion = bin ? versionOf(bin) : null;
+    if (!update && !version && currentVersion) return { ok: true, version: currentVersion, binary: bin };
+    return installManagedHarness({ harness, kaiHome, version: version || 'latest', onLog,
+      resolveBinary: root => packageBinary(harness, createRequire(join(root, 'package.json'))), probeVersion: versionOf });
   }
+  version ||= CURSOR_AGENT_VERSION;
+  if (!/^[0-9][a-zA-Z0-9.-]*$/.test(version)) throw new Error("Invalid Cursor version.");
   const root = CURSOR_ROOT(kaiHome);
   const target = join(root, version);
   const tmp = join(root, `.tmp-${version}-${process.pid}`);
@@ -197,7 +198,11 @@ export async function installHarness(harness, { kaiHome, onLog = () => {}, versi
 }
 
 /** Interactive login command for a harness under a profile's config dir. */
-export function harnessLoginCommand(harness, configDir, kaiHome) {
+export function isHeadless(env = process.env, os = platform()) {
+  return !!(env.SSH_CONNECTION || env.SSH_TTY || (os === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY));
+}
+
+export function harnessLoginCommand(harness, configDir, kaiHome, { deviceAuth = isHeadless() } = {}) {
   const bin = harnessBinary(harness, kaiHome);
   if (!bin) return null;
   if (harness === "claude") {
@@ -207,7 +212,7 @@ export function harnessLoginCommand(harness, configDir, kaiHome) {
     const env = resolvePath(configDir) !== resolvePath(claudeDefault) ? { CLAUDE_CONFIG_DIR: configDir } : {};
     return { cmd: bin, args: ["auth", "login"], env };
   }
-  if (harness === "codex") return { cmd: bin, args: ["login"], env: { CODEX_HOME: configDir } };
+  if (harness === "codex") return { cmd: bin, args: ["login", ...(deviceAuth ? ["--device-auth"] : [])], env: { CODEX_HOME: configDir } };
   return { cmd: bin, args: ["login"], env: {} };
 }
 

package/src/{hosted-ports.mjs → preview-ports.mjs}

@@ -1,5 +1,5 @@
 // Reserve before boot: two sessions can otherwise choose the same free port.
-export class HostedPortPool {
+export class PreviewPortPool {
   constructor() { this.owners = new Map(); this.tail = Promise.resolve(); }
   reserve(owner, preferred, pinned, listening) {
     const operation = this.tail.then(async () => {
@@ -17,4 +17,4 @@ export class HostedPortPool {
   }
   releaseSession(sessionId) { for (const [port, owner] of this.owners) if (owner.startsWith(`${sessionId}/`)) this.owners.delete(port); }
 }
-export const hostedPorts = new HostedPortPool();
+export const previewPorts = new PreviewPortPool();

package/src/preview.mjs

@@ -1,5 +1,4 @@
-import { hostedPorts } from './hosted-ports.mjs';
-import { boundHostedProcess } from './hosted-resources.mjs';
+import { previewPorts } from './preview-ports.mjs';
 // Preview tier A — run the app's real dev servers next to the session.
 //
 // Each repo may commit a `.gleap/dev.yaml`:
@@ -389,7 +388,6 @@ function lockfileHash(cwd) {
 
 /** Runs `cmd` through the user's login shell (darwin) or the platform shell, capturing output into `fd`. */
 function spawnShell(cmd, { cwd, env, fd, detached = false }) {
-  if (process.env.KAI_HOSTED === '1') { env = { ...env, NODE_OPTIONS: '--max-old-space-size=1024' }; detached = true; }
   if (process.platform !== "win32") cmd = withDaemonNode(cmd);
   if (process.platform === "darwin") {
     // Under launchd the daemon's PATH is frozen at install time
@@ -400,7 +398,6 @@ function spawnShell(cmd, { cwd, env, fd, detached = false }) {
   // Windows has no process groups to kill and `detached` would open a
   // console window — taskkill /T does the tree.
   const child = spawn(cmd, { cwd, env, shell: true, stdio: ["ignore", fd, fd], detached: process.platform !== "win32" && detached, windowsHide: true });
-  boundHostedProcess(child, { limitMb: 1536 });
   return child;
 }
 
@@ -417,14 +414,13 @@ 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(), registerPublicService = null } = {}) {
+  constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {}, preferredPort = null, describeListener = null, settleMs = DEFAULT_SETTLE_MS, onServiceExit = () => {}, onProcess = () => {}, home = homedir() } = {}) {
     if (settleMs === DEFAULT_SETTLE_MS) settleMs = defaultSettleMs();
     this.kaiHome = kaiHome;
     this.sessionId = sessionId;
-    this.registerPublicService = registerPublicService;
-    this.publicUrls = {};
+    this.serviceUrls = {};
     this.log = log;
     this.onStatus = onStatus;
     this.preferredPort = typeof preferredPort === "function" ? preferredPort : null;
@@ -479,13 +475,10 @@ export class ServiceRunner {
       }
       if (this.ports[svc.name]) continue;
       const declared = svc.port;
-      if (process.env.KAI_HOSTED === '1') {
-        const pinned = !!declared && (mode === 'local' || new RegExp(`(^|[^0-9])${declared}([^0-9]|$)`).test(`${svc.run} ${Object.values(svc.env).join(' ')}`));
-        this.ports[svc.name] = await hostedPorts.reserve(`${this.sessionId}/${repoRoot}/${svc.name}`, declared || await this.preferredPort?.({ repoKey, service: svc.name }), pinned, isPortListening);
-        continue;
-      }
+      const owner = `${this.sessionId}/${repoRoot}/${svc.name}`;
+      const pinned = !!declared && (mode === 'local' || new RegExp(`(^|[^0-9])${declared}([^0-9]|$)`).test(`${svc.run} ${Object.values(svc.env).join(' ')}`));
       if (declared && !(await isPortListening(declared))) {
-        this.ports[svc.name] = declared;
+        this.ports[svc.name] = await previewPorts.reserve(owner, declared, pinned, isPortListening);
         continue;
       }
       if (declared) {
@@ -513,10 +506,11 @@ export class ServiceRunner {
           });
         }
       }
-      this.ports[svc.name] = (declared ? await findFreePortNear(declared) : await this.stablePort(repoKey, svc.name)) ?? (await getFreePort());
+      const preferred = (declared ? await findFreePortNear(declared) : await this.stablePort(repoKey, svc.name)) ?? (await getFreePort());
+      this.ports[svc.name] = await previewPorts.reserve(owner, preferred, false, isPortListening);
     }
     for (const svc of services) {
-      this.publicUrls[svc.name] = this.registerPublicService ? await this.registerPublicService(svc.name, this.ports[svc.name], svc.protocol) : `${svc.protocol || 'http'}://localhost:${this.ports[svc.name]}`;
+      this.serviceUrls[svc.name] = `${svc.protocol || 'http'}://localhost:${this.ports[svc.name]}`;
     }
     this.registered.set(repoRoot, services);
     this.previewNames ??= new Map();
@@ -594,7 +588,7 @@ export class ServiceRunner {
     const env = {
       ...process.env,
       PORT: String(port),
-      ...Object.fromEntries(Object.entries(svc.env).map(([k, v]) => [k, substitutePorts(v, this.ports, this.publicUrls)])),
+      ...Object.fromEntries(Object.entries(svc.env).map(([k, v]) => [k, substitutePorts(v, this.ports, this.serviceUrls)])),
       KAI_SESSION_ID: String(this.sessionId),
       BROWSER: "none",
     };
@@ -603,7 +597,7 @@ export class ServiceRunner {
     // straight into `command not found` was the #1 preview failure. The
     // install is authoritative: when it fails, the dev command never runs.
     await this.ensureDeps(cwd, { env, fd, logPath, service: name, repoKey });
-    const cmd = stripOpenFlag(substitutePorts(svc.run, this.ports, this.publicUrls));
+    const cmd = stripOpenFlag(substitutePorts(svc.run, this.ports, this.serviceUrls));
     const child = spawnShell(cmd, { cwd, env, fd, detached: true });
     m.ready = false;
     child.on("exit", (code) => {
@@ -635,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.
@@ -865,7 +859,7 @@ export class ServiceRunner {
   }
 
   stopAll() {
-    if (process.env.KAI_HOSTED === '1') hostedPorts.releaseSession(this.sessionId);
+    previewPorts.releaseSession(this.sessionId);
     for (const [name, child] of this.processes) {
       this.stopping.add(name);
       if (process.platform === "win32") {

package/src/profiles.mjs

@@ -13,7 +13,7 @@
 
 import { execFileSync, spawn } from "node:child_process";
 import { cpSync, existsSync, mkdirSync } from "node:fs";
-import { HARNESS_IDS as REGISTRY_IDS, harnessBinary, harnessLoginCommand, probeHarnessAuth } from "./harnesses.mjs";
+import { HARNESS_IDS as REGISTRY_IDS, harnessBinary, harnessLoginCommand, isHeadless, probeHarnessAuth } from "./harnesses.mjs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -112,8 +112,8 @@ export function createManagedProfile(harness, profileId, kaiHome) {
 }
 
 /** Interactive login for a profile (opens the harness's own flow). */
-export function loginCommand(harness, configDir, kaiHome = process.env.KAI_HOME || join(HOME, ".kai")) {
-  const c = harnessLoginCommand(harness, configDir, kaiHome);
+export function loginCommand(harness, configDir, kaiHome = process.env.KAI_HOME || join(HOME, ".kai"), options) {
+  const c = harnessLoginCommand(harness, configDir, kaiHome, options);
   if (!c) return null;
   return { cmd: c.cmd, args: c.args, env: { ...process.env, ...c.env } };
 }
@@ -124,8 +124,9 @@ export function loginCommand(harness, configDir, kaiHome = process.env.KAI_HOME
  * DEVICE running the login under the profile's config dir. Returns the
  * spawned process or null when no terminal could be opened.
  */
-export function openLoginTerminal(harness, configDir) {
-  const c = loginCommand(harness, configDir);
+export function openLoginTerminal(harness, configDir, kaiHome) {
+  if (isHeadless()) return null;
+  const c = loginCommand(harness, configDir, kaiHome);
   if (!c) return null;
   // Ambient claude must log in with the env untouched so credentials land
   // in the keychain, where the (equally untouched) probe and turns look.

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/service.mjs

@@ -70,7 +70,7 @@ export function displayEnv(env = process.env) {
 export function renderSystemdUnit({ program, args, env = {} }) {
   const q = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
   return `[Unit]
-Description=Gleap Kai Bridge
+Description=Kai Code Bridge
 Wants=network-online.target
 After=network-online.target
 

package/src/setup.mjs

@@ -165,7 +165,7 @@ const rowLine = (h) => {
 export async function runSetup({ binPath, prompter = makePrompter() } = {}) {
   const config = loadConfig();
   out("");
-  out("── Kai Bridge ────────────────────────────────────────────────");
+  out("── Kai Code Bridge ────────────────────────────────────────────────");
   out("Run Kai Code sessions on this machine — with your own Claude /");
   out("Codex / Cursor login, against your local checkouts.");
   out("");