@gleapai/kai-bridge 0.5.0 → 0.7.0

package/src/harnesses.mjs

@@ -19,9 +19,11 @@ import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync
 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';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_BIN = join(PKG, "node_modules", ".bin");
+const require = createRequire(import.meta.url);
 
 export const HARNESS_IDS = ["claude", "codex", "cursor"];
 
@@ -76,21 +78,30 @@ export function cursorDownloadUrl(version = CURSOR_AGENT_VERSION) {
 /** Bundled / installed binary for a harness, or null. */
 export function harnessBinary(harness, kaiHome = join(homedir(), ".kai")) {
   if (harness === "claude") {
-    const pkgDir = join(PKG, "node_modules", "@anthropic-ai");
     try {
-      const plat = readdirSync(pkgDir).find((d) => d.startsWith("claude-agent-sdk-") && d !== "claude-agent-sdk");
-      if (plat) {
-        const bin = join(pkgDir, plat, platform() === "win32" ? "claude.exe" : "claude");
-        if (existsSync(bin)) return bin;
-      }
+      // 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 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 {
       /* not installed */
     }
     return null;
   }
   if (harness === "codex") {
-    const bin = join(PKG_BIN, platform() === "win32" ? "codex.cmd" : "codex");
-    return existsSync(bin) ? bin : null;
+    try {
+      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 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');
+    } catch { return null; }
   }
   if (harness === "cursor") {
     const bin = join(CURSOR_CURRENT(kaiHome), "dist-package", platform() === "win32" ? "cursor-agent.exe" : "cursor-agent");
@@ -194,7 +205,7 @@ export function harnessLoginCommand(harness, configDir, kaiHome) {
     // Ambient login must land in the keychain (env untouched) so the
     // equally-untouched probe and turns find it; managed dirs are exported.
     const env = resolvePath(configDir) !== resolvePath(claudeDefault) ? { CLAUDE_CONFIG_DIR: configDir } : {};
-    return { cmd: bin, args: ["login"], env };
+    return { cmd: bin, args: ["auth", "login"], env };
   }
   if (harness === "codex") return { cmd: bin, args: ["login"], env: { CODEX_HOME: configDir } };
   return { cmd: bin, args: ["login"], env: {} };

package/src/hosted-auth.mjs

@@ -0,0 +1,42 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Only harness authentication failures invalidate a login. An application's
+// HTTP 401 during validation, a quota limit, or an outage must not sign it out.
+export function classifyHarnessFailure(message = '') {
+  if (/rate.?limit|429|usage limit|out of (extra )?usage/i.test(message)) return 'rate_limited';
+  if (/refresh_token_(reused|expired|invalidated)|not logged in|login (has )?expired|login required|authentication[_ ](?:error|required)|oauth.{0,30}(expired|invalid)|model provider rejected.{0,30}401/i.test(message)) return 'authentication_required';
+  if (/service unavailable|provider.{0,30}(unavailable|outage)|HTTP 50[234]|ECONNRESET|ETIMEDOUT/i.test(message)) return 'provider_unavailable';
+  return null;
+}
+
+const marker = (profile, kaiHome) => join(kaiHome, `auth-failure-${createHash('sha256').update(profile.id).digest('hex')}.json`);
+const fingerprint = profile => {
+  const hash = createHash('sha256');
+  for (const file of profile.harness === 'codex' ? ['auth.json'] : ['.credentials.json']) {
+    try { hash.update(readFileSync(join(profile.configDir, file))); } catch { hash.update('missing'); }
+  }
+  return hash.digest('hex');
+};
+
+export function markHostedLoginExpired(profile, kaiHome) {
+  mkdirSync(kaiHome, { recursive: true });
+  writeFileSync(marker(profile, kaiHome), JSON.stringify({ fingerprint: fingerprint(profile) }), { mode: 0o600 });
+}
+
+export function hostedLoginExpired(profile, kaiHome) {
+  try {
+    const previous = JSON.parse(readFileSync(marker(profile, kaiHome), 'utf8'));
+    if (previous.fingerprint === fingerprint(profile)) return true;
+    // Native login or a successful supervised refresh replaced the credential.
+    rmSync(marker(profile, kaiHome), { force: true });
+  } catch { /* No failed login recorded. */ }
+  return false;
+}
+
+export function hostedLoginRecovery(harness) {
+  return harness === 'codex'
+    ? 'Codex sign-in expired. Open maintenance SSH and run sudo /opt/kai-bridge/fly/login-codex.sh, then retry.'
+    : 'Claude Code sign-in expired. Open maintenance SSH and run sudo -iu kai claude auth login, then retry.';
+}

package/src/hosted-git-credential.mjs

@@ -0,0 +1,24 @@
+// Git's credential helper protocol. Credentials go directly to Git's pipe,
+// never into a remote URL, argv, stored config or a daemon log.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig, KAI_HOME } from './config.mjs';
+
+if (process.argv[2] === 'get') {
+  const input = await new Promise(resolve => { let text = ''; process.stdin.on('data', b => { text += b; }); process.stdin.on('end', () => resolve(text)); });
+  const fields = Object.fromEntries(String(input).split('\n').filter(Boolean).map(line => { const i = line.indexOf('='); return [line.slice(0, i), line.slice(i + 1)]; }));
+  const config = loadConfig();
+  const manifest = JSON.parse(readFileSync(join(KAI_HOME, 'hosted-repositories.json'), 'utf8'));
+  const remote = `${fields.protocol}://${fields.host}/${fields.path || ''}`;
+  const id = manifest[remote] || manifest[`${remote}.git`];
+  if (id && config.device?.token && fields.protocol === 'https') {
+    const response = await fetch(`${config.apiBase}/gleapcode/bridge/devices/me/hosted-repositories?repositoryId=${encodeURIComponent(id)}`, {
+      headers: { authorization: `Bearer ${config.device.token}` }, signal: AbortSignal.timeout(25_000) });
+    if (response.ok) {
+      const [repo] = await response.json();
+      if (repo?.remote === remote || repo?.remote === `${remote}.git`) {
+        if ([repo.username, repo.password].every(v => typeof v === 'string' && !/[\r\n]/.test(v))) process.stdout.write(`username=${repo.username}\npassword=${repo.password}\n\n`);
+      }
+    }
+  }
+}

package/src/hosted-git.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// Fly-only Git launcher. Azure uses bearer authentication, which old Git
+// credential helpers cannot express. Add freshly authorized headers to this
+// process's config environment; never persist them in .git/config or argv.
+import { readFileSync, existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { loadConfig, KAI_HOME } from './config.mjs';
+const args = process.argv.slice(2), env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+const manifestPath = join(KAI_HOME, 'hosted-repositories.json');
+try {
+  if (args.some(a => ['clone', 'fetch', 'push', 'pull', 'ls-remote', 'submodule'].includes(a)) && existsSync(manifestPath)) {
+    const config = loadConfig(), manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    let count = Number(env.GIT_CONFIG_COUNT || 0);
+    for (const [remote, id] of Object.entries(manifest)) {
+      const response = await fetch(`${config.apiBase}/gleapcode/bridge/devices/me/hosted-repositories?repositoryId=${encodeURIComponent(id)}`, {
+        headers: { authorization: `Bearer ${config.device.token}` }, signal: AbortSignal.timeout(25_000) });
+      // A revoked companion cannot break an unrelated repository's fetch.
+      // The exact remote still fails closed if its own credentials are absent.
+      if (!response.ok) continue;
+      const [repo] = await response.json();
+      if (repo?.remote !== remote || !repo.authHeader || /[\r\n]/.test(repo.authHeader)) continue;
+      env[`GIT_CONFIG_KEY_${count}`] = `http.${remote}.extraheader`;
+      env[`GIT_CONFIG_VALUE_${count}`] = repo.authHeader; count++;
+    }
+    env.GIT_CONFIG_COUNT = String(count);
+  }
+  const sharedOperation = args.some(a => ['clone', 'fetch', 'push', 'pull', 'worktree', 'branch', 'update-ref', 'submodule'].includes(a));
+  const lock = sharedOperation && !process.env.KAI_GIT_LOCKED;
+  if (lock) env.KAI_GIT_LOCKED = '1';
+  const child = spawn(lock ? '/usr/bin/flock' : '/usr/bin/git', lock ? ['--timeout', '180', '/data/git-operations.lock', '/usr/bin/git', ...args] : args, { env, stdio: 'inherit' });
+  child.on('error', () => process.exit(1)); child.on('exit', code => process.exit(code || 0));
+} catch (error) { process.stderr.write(`${error.message}\n`); process.exit(1); }

package/src/hosted-ports.mjs

@@ -0,0 +1,20 @@
+// Reserve before boot: two sessions can otherwise choose the same free port.
+export class HostedPortPool {
+  constructor() { this.owners = new Map(); this.tail = Promise.resolve(); }
+  reserve(owner, preferred, pinned, listening) {
+    const operation = this.tail.then(async () => {
+      const current = [...this.owners].find(([, who]) => who === owner);
+      if (current) return current[0];
+      const first = Number.isInteger(preferred) && preferred >= 1024 && preferred <= 65535 ? preferred : 43000;
+      for (let i = 0; i < (pinned ? 1 : 10000); i++) {
+        const port = 1024 + ((first - 1024 + i) % (65536 - 1024));
+        if (this.owners.has(port) || await listening(port)) continue;
+        this.owners.set(port, owner); return port;
+      }
+      throw new Error(pinned ? `Port ${first} is already reserved. Use a port variable in .gleap/dev.yaml to run concurrent previews.` : 'No preview ports are available. Stop an unused preview and retry.');
+    });
+    this.tail = operation.catch(() => {}); return operation;
+  }
+  releaseSession(sessionId) { for (const [port, owner] of this.owners) if (owner.startsWith(`${sessionId}/`)) this.owners.delete(port); }
+}
+export const hostedPorts = new HostedPortPool();

package/src/hosted-resources.mjs

@@ -0,0 +1,35 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+
+export function processTreeMemory(rows, root) {
+  const parsed = rows.trim().split('\n').map(line => line.trim().split(/\s+/).map(Number)).filter(p => p.length === 3 && p.every(Number.isFinite));
+  const owned = new Set([Number(root)]);
+  for (let changed = true; changed;) { changed = false; for (const [pid, parent] of parsed) if (owned.has(parent) && !owned.has(pid)) { owned.add(pid); changed = true; } }
+  return parsed.filter(([pid]) => owned.has(pid)).reduce((sum, [, , rss]) => sum + rss, 0) / 1024;
+}
+
+/** Bound a workload including subprocesses, reserving room for Bridge,
+ * Codex's shared auth process, a second session and preview services. Root SSH
+ * can change the VM; the provider-side time/access limits remain authoritative. */
+export function boundHostedProcess(child, { limitMb = 2048, onExceeded = () => {} } = {}) {
+  if (process.env.KAI_HOSTED !== '1' || !child.pid) return () => {};
+  let stopped = false, reading = false, killTimer;
+  const timer = setInterval(async () => {
+    if (stopped || reading) return;
+    reading = true;
+    try {
+      const { stdout } = await exec('ps', ['-eo', 'pid=,ppid=,rss='], { timeout: 2000, maxBuffer: 2 * 1024 * 1024 });
+      if (!stopped && processTreeMemory(stdout, child.pid) > limitMb) {
+        onExceeded(`This workload exceeded its ${limitMb} MB memory budget. Reduce build concurrency or stop another preview, then retry.`);
+        try { process.kill(-child.pid, 'SIGTERM'); } catch { child.kill('SIGTERM'); }
+        killTimer = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }, 5000);
+        stopped = true; clearInterval(timer);
+      }
+    } catch { /* Failed observation never claims that validation passed. */ }
+    finally { reading = false; }
+  }, 3000);
+  timer.unref?.();
+  const cleanup = () => { stopped = true; clearInterval(timer); };
+  child.once('close', cleanup); return cleanup;
+}

package/src/hosted-tunnel.mjs

@@ -0,0 +1,76 @@
+import WebSocket from 'ws';
+import http from 'node:http';
+import https from 'node:https';
+
+export class HostedTunnel {
+  constructor({ config, api, log = () => {} }) { this.config = config; this.api = api; this.log = log; this.services = new Map(); this.pending = new Map(); this.closed = false; }
+  connect() {
+    if (!process.env.KAI_TUNNEL_URL || this.closed) return;
+    this.socket = new WebSocket(process.env.KAI_TUNNEL_URL, { headers: { authorization: `Bearer ${this.config.device.token}` }, maxPayload: 12 * 1024 * 1024 });
+    this.socket.on('message', raw => { try { this.handle(JSON.parse(String(raw))); } catch { this.socket.close(1008); } });
+    this.socket.on('error', () => {});
+    this.socket.on('close', () => {
+      for (const request of this.pending.values()) { request.destroy?.(); request.close?.(); }
+      this.pending.clear(); if (!this.closed) this.timer = setTimeout(() => this.connect(), 3000);
+    });
+  }
+  send(message) {
+    if (this.socket?.bufferedAmount > 16 * 1024 * 1024) { this.socket.close(1013, 'Preview transport backpressure'); return; }
+    if (this.socket?.readyState === WebSocket.OPEN) this.socket.send(JSON.stringify(message));
+  }
+  async register(sessionId, name, port, protocol = 'http') {
+    const service = await this.api.request('POST', '/gleapcode/bridge/devices/me/preview-services', { sessionId, name, port, protocol });
+    this.services.set(service.key, { sessionId, name, port, protocol });
+    return service.url;
+  }
+  unregisterSession(sessionId) {
+    for (const [key, service] of this.services) if (service.sessionId === sessionId) {
+      this.services.delete(key);
+      for (const [id, pending] of this.pending) if (pending.serviceKey === key) { pending.destroy?.(); pending.close?.(); this.pending.delete(id); this.send({ type: 'end', id }); }
+    }
+  }
+  handle(message) {
+    const { id } = message;
+    if (message.type === 'cancel') { const pending = this.pending.get(id); pending?.destroy?.(); pending?.close?.(); this.pending.delete(id); return; }
+    if (message.type === 'ws-data') {
+      const socket = this.pending.get(id), data = Buffer.from(message.data || '', 'base64');
+      if (!socket) return;
+      if (socket.readyState === WebSocket.OPEN && socket.bufferedAmount < 4 * 1024 * 1024) socket.send(data, { binary: !!message.binary });
+      else if (socket.readyState === WebSocket.CONNECTING && (socket.earlyBytes || 0) + data.length < 1024 * 1024) { socket.earlyBytes = (socket.earlyBytes || 0) + data.length; socket.early.push({ data, binary: !!message.binary }); }
+      else { socket.close(1013); this.send({ type: 'error', id }); }
+      return;
+    }
+    const service = this.services.get(message.key);
+    // The relay may reach only services registered by THIS daemon. It cannot
+    // turn into an arbitrary loopback / private-network proxy.
+    if (!service || service.port !== message.port || service.protocol !== message.protocol || !String(message.path).startsWith('/')) { this.send({ type: 'error', id }); return; }
+    if (this.pending.size >= 64) { this.send({ type: 'error', id }); return; }
+    const headers = { ...message.headers };
+    if (message.type === 'http') {
+      const client = service.protocol === 'https' ? https : http;
+      const request = client.request({ hostname: '127.0.0.1', port: service.port, method: message.method,
+        path: message.path, headers, rejectUnauthorized: false, timeout: 60_000 }, response => {
+        this.send({ type: 'headers', id, status: response.statusCode, headers: response.headers });
+        response.on('data', data => this.send({ type: 'data', id, data: data.toString('base64') }));
+        response.on('end', () => { this.send({ type: 'end', id }); this.pending.delete(id); });
+      });
+      this.pending.set(id, request);
+      request.serviceKey = message.key;
+      request.on('timeout', () => request.destroy());
+      request.on('error', () => { this.send({ type: 'error', id }); this.pending.delete(id); });
+      request.end(Buffer.from(message.body || '', 'base64'));
+    } else if (message.type === 'ws') {
+      // The local client generates its own handshake headers.
+      const protocols = headers['sec-websocket-protocol']?.split(',').map(p => p.trim()).filter(Boolean);
+      for (const key of Object.keys(headers)) if (key.toLowerCase().startsWith('sec-websocket-')) delete headers[key];
+      const socket = new WebSocket(`${service.protocol === 'https' ? 'wss' : 'ws'}://127.0.0.1:${service.port}${message.path}`, protocols || [], { headers, rejectUnauthorized: false, maxPayload: 12 * 1024 * 1024 });
+      this.pending.set(id, socket);
+      socket.serviceKey = message.key; socket.early = []; socket.earlyBytes = 0;
+      socket.on('open', () => { for (const frame of socket.early) socket.send(frame.data, { binary: frame.binary }); socket.early = []; socket.earlyBytes = 0; });
+      socket.on('message', (data, binary) => this.send({ type: 'data', id, data: Buffer.from(data).toString('base64'), binary }));
+      socket.on('close', () => { this.pending.delete(id); this.send({ type: 'end', id }); });
+      socket.on('error', () => { this.pending.delete(id); this.send({ type: 'error', id }); });
+    }
+  }
+  close() { this.closed = true; clearTimeout(this.timer); this.socket?.close(); for (const p of this.pending.values()) { p.destroy?.(); p.close?.(); } }
+}

package/src/hosted.mjs

@@ -0,0 +1,86 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { freemem } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { defaultConfig, loadConfig, saveConfig, KAI_HOME, DEFAULT_API_BASE } from './config.mjs';
+
+export async function bootstrapHosted() {
+  if (process.env.KAI_HOSTED !== '1') return;
+  const config = loadConfig();
+  if (config.device?.token) return;
+  const response = await fetch(`${DEFAULT_API_BASE}/gleapcode/hosted-bootstrap`, { method: 'POST',
+    headers: { 'content-type': 'application/json' }, signal: AbortSignal.timeout(30_000),
+    body: JSON.stringify({ token: process.env.KAI_BOOTSTRAP_TOKEN, machineId: process.env.KAI_MACHINE_ID,
+      generation: Number(process.env.KAI_MACHINE_GENERATION) }) });
+  if (!response.ok) throw new Error(`Machine bootstrap failed (${response.status}). Use maintenance SSH to repair.`);
+  const data = await response.json();
+  saveConfig({ ...defaultConfig(), ...data, autoUpdate: false });
+  delete process.env.KAI_BOOTSTRAP_TOKEN;
+}
+
+export function hostedResources(daemon) {
+  return { availableMemoryMb: Math.floor(freemem() / 1024 / 1024),
+    activeWork: daemon.running.size + (daemon.hostedCloning ? 1 : 0) + daemon.logins.size + (daemon.hostedPreviewWork?.size || 0),
+    queuedWork: daemon.hostedQueued?.size || 0, repositories: daemon.hostedRepositorySetup };
+}
+
+function git(args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    let error = '';
+    child.stderr.on('data', b => { error = (error + b).slice(-2000); });
+    const timer = setTimeout(() => child.kill('SIGTERM'), 180_000);
+    child.once('error', e => { clearTimeout(timer); reject(e); });
+    child.once('exit', code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error(`Repository preparation failed (${code}): ${error}`)); });
+  });
+}
+
+export async function syncHostedRepositories(daemon) {
+  if (!daemon.config.hosted || daemon.hostedCloning || daemon.stopped) return;
+  daemon.hostedCloning = true;
+  const readyIds = [];
+  daemon.hostedRepositorySetup = { status: 'cloning', readyIds };
+  try {
+    const repos = await daemon.api.request('GET', '/gleapcode/bridge/devices/me/hosted-repositories');
+    const root = '/data/repos'; mkdirSync(root, { recursive: true });
+    const helperPath = join(dirname(fileURLToPath(import.meta.url)), 'hosted-git-credential.mjs');
+    const manifest = Object.fromEntries(repos.map(repo => [repo.remote, repo.id]));
+    writeFileSync(join(daemon.kaiHome, 'hosted-repositories.json'), JSON.stringify(manifest), { mode: 0o600 });
+    for (const repo of repos) {
+      const name = createHash('sha256').update(repo.key || repo.remote).digest('hex');
+      const target = join(root, name), staging = `${target}.cloning`;
+      if (existsSync(join(target, '.git'))) { readyIds.push(repo.id); continue; }
+      // Never erase a failed clone's directory or a user-created checkout.
+      if (existsSync(staging) || existsSync(target)) throw new Error(`Repository ${repo.fullName} needs attention at ${staging}. Existing files were preserved.`);
+      const helper = `!${JSON.stringify(process.execPath)} ${JSON.stringify(helperPath)}`;
+      await git(['-c', 'credential.helper=', '-c', `credential.helper=${helper}`, '-c', 'credential.useHttpPath=true', 'clone', '--', repo.remote, staging], root);
+      await git(['config', '--local', 'credential.helper', helper], staging);
+      await git(['config', '--local', 'credential.useHttpPath', 'true'], staging);
+      renameSync(staging, target);
+      readyIds.push(repo.id);
+    }
+    await daemon.scanRepos(); await daemon.hello();
+    daemon.hostedRepositorySetup = { status: 'ready', readyIds };
+  } catch (error) {
+    daemon.hostedRepositorySetup = { status: 'error', error: error.message, readyIds };
+    throw error;
+  } finally { daemon.hostedCloning = false; }
+}
+
+/** FIFO contents persist on the server; duplicate push/replay cannot run twice. */
+export async function awaitHostedAdmission(daemon, turn) {
+  if (!daemon.config.hosted) return true;
+  daemon.hostedQueued ??= new Set();
+  if (daemon.hostedQueued.has(turn.turnId) || daemon.running.has(turn.turnId)) return false;
+  daemon.hostedQueued.add(turn.turnId);
+  try {
+    while (!daemon.stopped && !daemon.hostedCancelled?.has(turn.turnId)) {
+      const admission = await daemon.api.request('POST', `/gleapcode/bridge/turns/${turn.turnId}/admit`, {});
+      if (admission.admitted) return true;
+      await new Promise(r => setTimeout(r, 2000));
+    }
+    return false;
+  } finally { daemon.hostedQueued.delete(turn.turnId); }
+}

package/src/preview.mjs

@@ -1,3 +1,5 @@
+import { hostedPorts } from './hosted-ports.mjs';
+import { boundHostedProcess } from './hosted-resources.mjs';
 // Preview tier A — run the app's real dev servers next to the session.
 //
 // Each repo may commit a `.gleap/dev.yaml`:
@@ -304,8 +306,11 @@ export function lanAddress() {
 }
 
 /** `${port:api}` → assigned port of service `api`. */
-export function substitutePorts(value, ports) {
-  return String(value).replace(/\$\{port:([\w-]+)\}/g, (_, name) => String(ports[name] ?? ""));
+export function substitutePorts(value, ports, urls = {}) {
+  return String(value).replace(/\$\{port:([\w-]+)\}/g, (_, name) => String(ports[name] ?? "")).replace(/\$\{url:([\w-]+)\}/g, (_, name) => {
+    if (!urls[name]) throw new Error(`Service URL is not available for ${name}.`);
+    return urls[name];
+  });
 }
 
 /** GET `url` accepting self-signed certificates (dev https); resolves `{ status, contentType }` or null. */
@@ -384,6 +389,7 @@ 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
@@ -393,7 +399,9 @@ 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.
-  return spawn(cmd, { cwd, env, shell: true, stdio: ["ignore", fd, fd], detached: process.platform !== "win32" && detached, windowsHide: true });
+  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;
 }
 
 /**
@@ -411,10 +419,12 @@ export class ServiceRunner {
    * fires when a service that had become ready dies on its own;
    * `onProcess(name, pid, "add" | "remove")` lets the daemon persist pids.
    */
-  constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {}, preferredPort = null, describeListener = null, settleMs = DEFAULT_SETTLE_MS, onServiceExit = () => {}, onProcess = () => {}, home = homedir() } = {}) {
+  constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {}, preferredPort = null, describeListener = null, settleMs = DEFAULT_SETTLE_MS, onServiceExit = () => {}, onProcess = () => {}, home = homedir(), registerPublicService = null } = {}) {
     if (settleMs === DEFAULT_SETTLE_MS) settleMs = defaultSettleMs();
     this.kaiHome = kaiHome;
     this.sessionId = sessionId;
+    this.registerPublicService = registerPublicService;
+    this.publicUrls = {};
     this.log = log;
     this.onStatus = onStatus;
     this.preferredPort = typeof preferredPort === "function" ? preferredPort : null;
@@ -469,6 +479,11 @@ 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;
+      }
       if (declared && !(await isPortListening(declared))) {
         this.ports[svc.name] = declared;
         continue;
@@ -500,6 +515,9 @@ export class ServiceRunner {
       }
       this.ports[svc.name] = (declared ? await findFreePortNear(declared) : await this.stablePort(repoKey, svc.name)) ?? (await getFreePort());
     }
+    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.registered.set(repoRoot, services);
     this.previewNames ??= new Map();
     this.previewNames.set(repoRoot, previewName);
@@ -576,7 +594,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)])),
+      ...Object.fromEntries(Object.entries(svc.env).map(([k, v]) => [k, substitutePorts(v, this.ports, this.publicUrls)])),
       KAI_SESSION_ID: String(this.sessionId),
       BROWSER: "none",
     };
@@ -585,10 +603,12 @@ 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));
+    const cmd = stripOpenFlag(substitutePorts(svc.run, this.ports, this.publicUrls));
     const child = spawnShell(cmd, { cwd, env, fd, detached: true });
     m.ready = false;
     child.on("exit", (code) => {
+      // An old shell can exit after a replacement has been admitted.
+      if (this.processes.get(name) !== child) return;
       this.processes.delete(name);
       this.onProcess(name, child.pid, "remove");
       this.log("info", "service.exit", { name, code });
@@ -804,7 +824,11 @@ export class ServiceRunner {
     const child = this.processes.get(name);
     if (!child) return;
     this.stopping.add(name);
-    const gone = new Promise((r) => child.once("exit", r));
+    const port = this.ports[name];
+    let timer;
+    const gone = child.exitCode !== null || child.signalCode !== null
+      ? Promise.resolve()
+      : new Promise((r) => child.once("exit", r));
     if (process.platform === "win32") {
       spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => {});
     } else {
@@ -819,17 +843,29 @@ export class ServiceRunner {
       }
     }
     this.log("info", "service.stop", { name });
-    await Promise.race([gone, new Promise((r) => setTimeout(r, timeoutMs))]);
-    if (this.processes.has(name)) {
+    await Promise.race([gone, new Promise((r) => { timer = setTimeout(r, timeoutMs); })]);
+    clearTimeout(timer);
+    // On Linux the shell may exit before its children close the listener.
+    // Starting the replacement now can mistake that old listener for readiness
+    // and then crash with EADDRINUSE. Wait for the owned service's port too.
+    const deadline = Date.now() + timeoutMs;
+    while (port && await isPortListening(port) && Date.now() < deadline) {
+      await new Promise(r => setTimeout(r, 50));
+    }
+    if (this.processes.get(name) === child || (port && await isPortListening(port))) {
       try {
         process.platform === "win32" ? child.kill() : process.kill(-child.pid, "SIGKILL");
       } catch {
         /* gone */
       }
     }
+    const forceDeadline = Date.now() + 1000;
+    while (port && await isPortListening(port) && Date.now() < forceDeadline) await new Promise(r => setTimeout(r, 50));
+    if (port && await isPortListening(port)) throw new PreviewError(`${name} did not release port ${port}; retry after checking the service.`, { code: 'port_busy', service: name });
   }
 
   stopAll() {
+    if (process.env.KAI_HOSTED === '1') hostedPorts.releaseSession(this.sessionId);
     for (const [name, child] of this.processes) {
       this.stopping.add(name);
       if (process.platform === "win32") {

package/src/profiles.mjs

@@ -138,12 +138,15 @@ export function openLoginTerminal(harness, configDir) {
       : harness === "codex"
         ? `CODEX_HOME=${shellQuote(configDir)} `
         : "NO_OPEN_BROWSER=0 ";
-  const line = `${envPrefix}${shellQuote(c.cmd)} login`;
+  const line = `${harness === 'claude' && process.platform !== 'win32' ? 'DISABLE_AUTOUPDATER=1 ' : ''}${envPrefix}${[c.cmd, ...c.args].map(shellQuote).join(' ')}`;
   if (process.platform === "darwin") {
     return spawn("osascript", ["-e", `tell application "Terminal" to activate`, "-e", `tell application "Terminal" to do script ${JSON.stringify(line)}`], { stdio: "ignore", detached: true });
   }
   if (process.platform === "win32") {
-    return spawn("cmd", ["/c", "start", "cmd", "/k", line.replace(/^([A-Z_]+)=('[^']*') /, "set $1=$2 && ")], { stdio: "ignore", detached: true, shell: true });
+    // cmd uses double quotes, and profile variables belong in the child env;
+    // POSIX KEY='value' prefixes are not valid Windows commands.
+    const windowsLine = [c.cmd, ...c.args].map(value => `"${String(value).replace(/"/g, '""')}"`).join(' ');
+    return spawn("cmd", ["/c", "start", '""', "cmd", "/k", windowsLine], { env: { ...c.env, ...(harness === 'claude' ? { DISABLE_AUTOUPDATER: '1' } : {}) }, stdio: "ignore", detached: true, shell: true });
   }
   for (const term of ["x-terminal-emulator", "gnome-terminal", "konsole", "xterm"]) {
     if (findBinary(term)) {

package/src/repository-setup.mjs

@@ -0,0 +1,96 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join, resolve, dirname, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { inspectCheckout, normalizeRemote } from './repos.mjs';
+
+const locks = new Map();
+export function withRepositoryLock(target, action) {
+  const key = resolve(target);
+  const prior = locks.get(key) || Promise.resolve();
+  const work = prior.catch(() => {}).then(action);
+  const tail = work.catch(() => {});
+  locks.set(key, tail);
+  void tail.then(() => { if (locks.get(key) === tail) locks.delete(key); });
+  return work;
+}
+
+export function locateRepository(rawPath, repoKey) {
+  const expanded = String(rawPath || '').trim().replace(/^~(?=$|\/)/, homedir());
+  if (!isAbsolute(expanded)) throw new Error('Enter an absolute folder path on this device.');
+  const target = resolve(expanded);
+  if (!existsSync(target)) throw new Error(`${target} does not exist on this machine.`);
+  // Validate BEFORE recording an override or adding a scan root.
+  if (repoKey && inspectCheckout(target)?.key !== repoKey) {
+    throw new Error(`${target} is not a checkout of ${repoKey}. Choose the folder for that repository.`);
+  }
+  return target;
+}
+
+export function cloneRepository({ remote, name, root, repoKey, timeoutMs = 180_000 }, 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.'));
+  }
+  if (!root || !existsSync(root)) return Promise.reject(new Error('No workspace folder is available. Add a scan folder in device settings.'));
+  if (typeof name !== 'string' || !name || name === '.' || name === '..' || name.startsWith('-') || /[/\\\x00-\x1f]/.test(name)) {
+    return Promise.reject(new Error('Invalid repository folder name.'));
+  }
+  const target = resolve(root, name);
+  if (dirname(target) !== resolve(root)) return Promise.reject(new Error('Invalid repository folder name.'));
+  const expectedKey = repoKey || normalizeRemote(remote)?.key;
+  if (!expectedKey || normalizeRemote(remote)?.key !== expectedKey) return Promise.reject(new Error('The clone URL belongs to a different repository.'));
+  return withRepositoryLock(target, async () => {
+    if (existsSync(target)) {
+      // Another session may have just cloned the same repo. Reuse only an
+      // exact identity match; never touch or remove an existing folder.
+      if (inspectCheckout(target)?.key === expectedKey) return target;
+      throw Object.assign(new Error(`${target} already exists. Use Locate existing to choose the correct checkout.`), { target });
+    }
+    mkdirSync(target); // exclusive reservation; cleanup only what we created
+    try {
+      await new Promise((accept, reject) => {
+        const child = spawnGit('git', ['clone', '--', remote, target], {
+          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' },
+        });
+        let stderr = '';
+        let timedOut = false;
+        let killTimer;
+        const signalGit = (signal) => {
+          try {
+            // SSH/helpers must exit too before the directory can be cleaned.
+            if (child.pid && process.platform !== 'win32') process.kill(-child.pid, signal);
+            else child.kill(signal);
+          } catch { /* already exited */ }
+        };
+        child.stderr.on('data', (chunk) => { stderr = `${stderr}${chunk}`.slice(-4000); });
+        const timer = setTimeout(() => {
+          timedOut = true;
+          signalGit('SIGTERM');
+          killTimer = setTimeout(() => signalGit('SIGKILL'), 2000);
+        }, timeoutMs);
+        const finish = (err) => {
+          clearTimeout(timer);
+          clearTimeout(killTimer);
+          if (err) reject(err); else accept();
+        };
+        child.on('error', finish);
+        // Wait for exit before deleting the partial clone/releasing the lock.
+        child.on('close', (code) => {
+          const detail = stderr.trim().split('\n').filter(Boolean).slice(-2).join(' · ')
+            .replace(/(https?:\/\/)[^\s/@]+(?::[^\s/@]*)?@/gi, '$1');
+          finish(timedOut ? new Error('Cloning timed out. Check the network and try again.') : code === 0 ? null
+            : new Error(`Could not clone the repository${detail ? `: ${detail}` : '.'}`));
+        });
+      });
+      if (inspectCheckout(target)?.key !== expectedKey) throw new Error('The cloned repository does not match the requested repository.');
+      return target;
+    } catch (err) {
+      rmSync(target, { recursive: true, force: true });
+      err.target = target;
+      throw err;
+    }
+  });
+}