claude-simple 0.2.24 → 0.2.26

package/src/app.js

@@ -13,7 +13,7 @@ import zlib from 'zlib';
 import { fileURLToPath } from 'url';
 import { runClaude } from './agents/claude.js';
 import { runCodex } from './agents/codex.js';
-import { runGrok } from './agents/grok.js';
+import { runGrok, getGrokQueueState, cancelGrokQueue } from './agents/grok.js';
 import { runGemini } from './agents/gemini.js';
 import { runCursor } from './agents/cursor.js';
 import {
@@ -33,8 +33,21 @@ import { discoverAllAgentModels } from './agents/models.js';
 import { createTextBatcher } from './agents/stream-batch.js';
 import { normalizeCommand, mapAgentEmit } from './runtime/protocol.js';
 import { createOutbox } from './runtime/outbox.js';
+import { createExternalSessionMirror } from './runtime/external-session-sync.js';
 import { resolveApproval, cancelApprovalsForSession } from './runtime/approvals.js';
 import { createMcpHttpHandler, createMcpService } from './mcp.js';
+import { createCollab, roleAtLeast, proxyToLocalPort, machineId as localMachineId } from './collab.js';
+import {
+  CLAUDE_ENV_KEYS,
+  loadAgentEnvDoc,
+  saveAgentEnvDoc,
+  patchEnv,
+  redactEnv,
+  applyAgentEnvToProcess,
+  pickAllowedEnv,
+  normalizeProfileName,
+  envForProfile,
+} from './agent-env.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.join(__dirname, '..');
 
@@ -129,15 +142,16 @@ let sessionMetaCache = null;
 
 /** Normalize project entry: old { notes } was the goal line. */
 function normalizeProjectEntry(entry) {
-  if (!entry || typeof entry !== 'object') return { goal: '', notes: '', updatedAt: 0 };
+  if (!entry || typeof entry !== 'object') return { goal: '', notes: '', hidden: false, updatedAt: 0 };
   const hasGoalKey = Object.prototype.hasOwnProperty.call(entry, 'goal');
   if (!hasGoalKey && entry.notes != null) {
     // legacy: single notes field = Project Goal
-    return { goal: String(entry.notes || ''), notes: '', updatedAt: entry.updatedAt || 0 };
+    return { goal: String(entry.notes || ''), notes: '', hidden: Boolean(entry.hidden), updatedAt: entry.updatedAt || 0 };
   }
   return {
     goal: String(entry.goal || ''),
     notes: String(entry.notes || ''),
+    hidden: Boolean(entry.hidden),
     updatedAt: entry.updatedAt || 0,
   };
 }
@@ -191,18 +205,27 @@ async function findUser(username) {
   return store.users.find(u => u.username === username) || null;
 }
 
-async function createUser(username, passwordHash) {
+async function createUser(username, passwordHash, role = null) {
   const store = await loadCreds();
-  const user = { id: Date.now(), username, passwordHash };
+  if (!role) role = store.users.length === 0 ? 'owner' : 'editor';
+  const user = { id: Date.now(), username, passwordHash, role };
   store.users.push(user);
   await saveCreds(store);
   return user;
 }
 
+function userRole(user) {
+  return user?.role || 'owner';
+}
+
 function jwtSecret() { return credStore?.jwtSecret; }
 
 function makeToken(user) {
-  return jwt.sign({ userId: user.id, username: user.username }, jwtSecret(), { expiresIn: '7d' });
+  return jwt.sign(
+    { userId: user.id, username: user.username, role: userRole(user) },
+    jwtSecret(),
+    { expiresIn: '7d' },
+  );
 }
 
 function makeMcpToken(user, expiresInSeconds) {
@@ -238,6 +261,7 @@ function authMiddleware(req, res, next) {
     req.user = {
       userId: 0,
       username: req.headers['x-hub-user'] || 'hub',
+      role: req.headers['x-hub-role'] || 'editor',
       viaHub: true,
     };
     return next();
@@ -395,13 +419,20 @@ async function dispatchAgent(agent, command, options, send) {
   } else if (a === 'cursor') {
     await runCursor(command, options, send, { ...ctx, cliPath: CURSOR_AGENT_PATH, cursorHome: CURSOR_HOME });
   } else {
-    await runClaude(command, options, send, { ...ctx, cliPath: CLAUDE_CLI_PATH });
+    const wss = await getWorkspaces();
+    const ws = wss.find(w => options.configDir && w.configDir === options.configDir)
+      || wss.find(w => options.workspaceName && w.name === options.workspaceName);
+    await runClaude(command, {
+      ...options,
+      configDir: options.configDir || ws?.configDir,
+      workspaceName: options.workspaceName || ws?.name,
+    }, send, { ...ctx, cliPath: CLAUDE_CLI_PATH });
   }
 }
 
-function abortSession(sessionId) {
+function abortSession(sessionId, { preserveQueue = false } = {}) {
   if (!sessionId) return false;
-  let ok = false;
+  let ok = !preserveQueue && cancelGrokQueue(sessionId) > 0;
   cancelApprovalsForSession(sessionId);
   // Grok/Codex may register under temp key + real sessionId — abort every match.
   for (const [key, s] of activeSessions) {
@@ -475,6 +506,50 @@ function compactHistoryMessages(messages) {
 // ─── App factory ──────────────────────────────────────────────────────────────
 export function createApp() {
   const app = express();
+  const COLLAB_FILE = process.env.COLLAB_FILE || path.join(rootDir, '.collab.json');
+  const collab = createCollab({ filePath: COLLAB_FILE });
+  const allowRemoteProxy = process.env.PORT_PROXY_ALLOW_REMOTE === '1';
+  // External CLIs (Codex, Grok, Claude, …) write native session records while
+  // running.  Mirror only sessions a browser is looking at; this is strictly
+  // read-only and does not turn the UI into the owner of that agent process.
+  const externalSessionMirror = createExternalSessionMirror({
+    readSession: readSessionBundle,
+    emit: (sessionId, event) => broadcastChat(sessionId, event),
+    // fs.watch below wakes the mirror immediately on native JSONL writes.
+    // This slower timer is only a safety net for missed/coalesced events.
+    intervalMs: 3_000,
+  });
+
+  function liveRole(req) {
+    return req.user?.role || 'viewer';
+  }
+  function sessionResourceKey(sessionId, agent) {
+    return `session:${localMachineId()}:${agent || 'claude'}:${sessionId}`;
+  }
+  async function enforceSessionLock(req, res, sessionId, agent) {
+    if (!sessionId) return true;
+    const key = req.headers['x-lock-key'] || sessionResourceKey(sessionId, agent);
+    const r = await collab.requireLock({
+      key,
+      lockToken: req.headers['x-lock-token'],
+      writer: req.user.username,
+      writerRole: liveRole(req),
+    });
+    if (r.code !== 200) {
+      res.status(r.code).json({ error: r.error, lock: r.lock });
+      return false;
+    }
+    if (r.lock?.token) res.setHeader('X-Lock-Token', r.lock.token);
+    return true;
+  }
+  function requireRole(need) {
+    return (req, res, next) => {
+      if (!roleAtLeast(liveRole(req), need)) {
+        return res.status(403).json({ error: 'forbidden' });
+      }
+      next();
+    };
+  }
 
   // Gzip JSON/text API responses when client accepts it (mobile / direct browser).
   // Skip for hub-proxied edge traffic: Node fetch auto-decompresses gzip while
@@ -532,7 +607,7 @@ export function createApp() {
     })().catch(e => res.status(500).json({ error: e.message }));
   });
 
-  app.post('/api/projects/:id/file', authMiddleware, (req, res) => {
+  app.post('/api/projects/:id/file', authMiddleware, requireRole('editor'), (req, res) => {
     (async () => {
       const projectPath = resolveProjectRoot(req);
       const rel = req.query.path;
@@ -636,7 +711,31 @@ export function createApp() {
         return res.status(400).json({ error: 'Username ≥3 chars, password ≥6 chars' });
       const hash = await bcrypt.hash(password, 12);
       const user = await createUser(username, hash);
-      res.json({ token: makeToken(user), user: { id: user.id, username: user.username } });
+      res.json({
+        token: makeToken(user),
+        user: { id: user.id, username: user.username, role: userRole(user) },
+      });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  app.post('/api/auth/password', authMiddleware, async (req, res) => {
+    try {
+      const current = req.body?.current;
+      const next = req.body?.next;
+      if (!current || !next) return res.status(400).json({ error: 'current and next required' });
+      if (String(next).length < 6) return res.status(400).json({ error: 'password ≥6 chars' });
+      const user = await findUser(req.user.username);
+      if (!user) return res.status(404).json({ error: 'not found' });
+      const ok = await bcrypt.compare(current, user.passwordHash);
+      if (!ok) return res.status(403).json({ error: 'current password incorrect' });
+      user.passwordHash = await bcrypt.hash(next, 12);
+      const store = await loadCreds();
+      const idx = store.users.findIndex(u => u.username === user.username);
+      if (idx >= 0) store.users[idx] = user;
+      await saveCreds(store);
+      res.json({ ok: true });
     } catch (e) {
       res.status(500).json({ error: e.message });
     }
@@ -650,12 +749,245 @@ export function createApp() {
       if (!user) return res.status(401).json({ error: 'Invalid credentials' });
       const ok = await bcrypt.compare(password, user.passwordHash);
       if (!ok) return res.status(401).json({ error: 'Invalid credentials' });
-      res.json({ token: makeToken(user), user: { id: user.id, username: user.username } });
+      res.json({
+        token: makeToken(user),
+        user: { id: user.id, username: user.username, role: userRole(user) },
+      });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  app.get('/api/agent-env', authMiddleware, async (req, res) => {
+    const doc = await loadAgentEnvDoc();
+    const name = normalizeProfileName(req.query.name);
+    const names = Object.keys(doc.profiles);
+    const env = name ? envForProfile(doc, name) : doc.env;
+    res.json({
+      keys: CLAUDE_ENV_KEYS,
+      name: name || '',
+      names,
+      env: redactEnv(env),
+      defaultEnv: redactEnv(doc.env),
+      profiles: Object.fromEntries(names.map(n => [n, redactEnv(doc.profiles[n])])),
+      process: redactEnv(pickAllowedEnv(process.env)),
+    });
+  });
+
+  app.put('/api/agent-env', authMiddleware, requireRole('editor'), async (req, res) => {
+    try {
+      const doc = await loadAgentEnvDoc();
+      const name = normalizeProfileName(req.body?.name || req.query.name);
+      const patch = req.body?.env || req.body;
+      if (name) {
+        doc.profiles[name] = patchEnv(doc.profiles[name] || {}, patch);
+        if (!Object.keys(doc.profiles[name]).length) delete doc.profiles[name];
+      } else {
+        doc.env = patchEnv(doc.env, patch);
+      }
+      await saveAgentEnvDoc(doc);
+      await applyAgentEnvToProcess(process.env);
+      const env = name ? envForProfile(doc, name) : doc.env;
+      res.json({
+        name: name || '',
+        names: Object.keys(doc.profiles),
+        env: redactEnv(env),
+      });
     } catch (e) {
       res.status(500).json({ error: e.message });
     }
   });
 
+  app.get('/api/collab/me', authMiddleware, (req, res) => {
+    res.json({
+      username: req.user.username,
+      role: liveRole(req),
+      userId: req.user.userId ?? req.user.id,
+    });
+  });
+
+  app.get('/api/collab/sync', authMiddleware, async (req, res) => {
+    const role = liveRole(req);
+    res.json({
+      serverTime: Date.now(),
+      locks: await collab.listLocks(),
+      routes: await collab.listRoutes(req.user.username, role),
+      machines: [{ id: localMachineId(), online: true }],
+      me: { username: req.user.username, role },
+    });
+  });
+
+  app.get('/api/collab/locks', authMiddleware, async (_req, res) => {
+    res.json(await collab.listLocks());
+  });
+
+  app.post('/api/collab/locks', authMiddleware, requireRole('editor'), async (req, res) => {
+    const r = await collab.acquire({
+      key: req.body.key,
+      kind: req.body.kind,
+      holder: req.user.username,
+      holderRole: liveRole(req),
+      lockToken: req.body.token,
+      ttlMs: (req.body.ttlSec || 60) * 1000,
+      exclusive: req.body.exclusive !== false,
+    });
+    if (r.code !== 200) return res.status(r.code).json({ error: r.error, lock: r.lock });
+    res.json(r.lock);
+  });
+
+  async function handleLockAction(req, res, key, action, token, ttlSec) {
+    key = decodeURIComponent(key || '');
+    if (action === 'heartbeat') {
+      const r = await collab.heartbeat({
+        key, holder: req.user.username, lockToken: token,
+        ttlMs: (ttlSec || 60) * 1000,
+      });
+      if (r.code !== 200) return res.status(r.code).json({ error: r.error });
+      return res.json(r.lock);
+    }
+    if (action === 'release') {
+      const r = await collab.release({
+        key, holder: req.user.username, lockToken: token, force: false,
+      });
+      if (r.code !== 200) return res.status(r.code).json({ error: r.error });
+      return res.json({ ok: true });
+    }
+    if (action === 'break') {
+      if (!roleAtLeast(liveRole(req), 'admin')) return res.status(403).json({ error: 'forbidden' });
+      await collab.release({ key, force: true });
+      return res.json({ ok: true });
+    }
+    res.status(400).json({ error: 'unknown action' });
+  }
+
+  app.post('/api/collab/lock-action', authMiddleware, async (req, res) => {
+    await handleLockAction(req, res, req.body?.key, req.body?.action, req.body?.token, req.body?.ttlSec);
+  });
+
+  app.post('/api/collab/locks/:key/:action', authMiddleware, async (req, res) => {
+    await handleLockAction(req, res, req.params.key, req.params.action, req.body?.token, req.body?.ttlSec);
+  });
+
+  app.get('/api/collab/routes', authMiddleware, async (req, res) => {
+    res.json(await collab.listRoutes(req.user.username, liveRole(req)));
+  });
+
+  app.post('/api/collab/routes', authMiddleware, requireRole('editor'), async (req, res) => {
+    const r = await collab.putRoute(req.user.username, liveRole(req), {
+      ...req.body,
+      machineId: req.body.machineId || localMachineId(),
+    });
+    if (r.code !== 200) return res.status(r.code).json({ error: r.error });
+    res.json(r.route);
+  });
+
+  app.get('/api/collab/routes/:slug', authMiddleware, async (req, res) => {
+    const rt = await collab.getRoute(req.params.slug);
+    if (!rt) return res.status(404).json({ error: 'not found' });
+    res.json(rt);
+  });
+
+  app.delete('/api/collab/routes/:slug', authMiddleware, requireRole('editor'), async (req, res) => {
+    const r = await collab.deleteRoute(req.user.username, liveRole(req), req.params.slug);
+    if (r.code !== 200) return res.status(r.code).json({ error: r.error });
+    res.json({ ok: true });
+  });
+
+  app.get('/api/collab/users', authMiddleware, requireRole('admin'), async (_req, res) => {
+    const store = await loadCreds();
+    res.json(store.users.map(u => ({
+      id: u.id, username: u.username, role: userRole(u), disabled: !!u.disabled,
+    })));
+  });
+
+  app.post('/api/collab/users', authMiddleware, requireRole('admin'), async (req, res) => {
+    try {
+      const { username, password, role } = req.body || {};
+      if (!username || !password) return res.status(400).json({ error: 'Username and password required' });
+      if (await findUser(username)) return res.status(409).json({ error: 'user exists' });
+      const actor = liveRole(req);
+      let nextRole = role || 'editor';
+      if (nextRole === 'owner' && actor !== 'owner') return res.status(403).json({ error: 'only owner can create owner' });
+      if (nextRole === 'admin' && actor !== 'owner') return res.status(403).json({ error: 'only owner can create admin' });
+      const hash = await bcrypt.hash(password, 12);
+      const user = await createUser(username, hash, nextRole);
+      res.json({ id: user.id, username: user.username, role: userRole(user) });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  app.patch('/api/collab/users/:username', authMiddleware, requireRole('admin'), async (req, res) => {
+    try {
+      const user = await findUser(req.params.username);
+      if (!user) return res.status(404).json({ error: 'not found' });
+      const actor = liveRole(req);
+      if (userRole(user) === 'owner' && actor !== 'owner') return res.status(403).json({ error: 'cannot modify owner' });
+      const store = await loadCreds();
+      const idx = store.users.findIndex(u => u.username === user.username);
+      if (req.body?.password) {
+        if (String(req.body.password).length < 6) return res.status(400).json({ error: 'password ≥6 chars' });
+        user.passwordHash = await bcrypt.hash(req.body.password, 12);
+      }
+      if (req.body?.role) {
+        if (req.body.role === 'owner' && actor !== 'owner') return res.status(403).json({ error: 'cannot promote to owner' });
+        user.role = req.body.role;
+      }
+      if (typeof req.body?.disabled === 'boolean') user.disabled = req.body.disabled;
+      if (idx >= 0) store.users[idx] = user;
+      await saveCreds(store);
+      res.json({ ok: true, username: user.username, role: userRole(user) });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  app.all('/api/port-proxy', authMiddleware, requireRole('editor'), async (req, res) => {
+    try {
+      const host = req.query.host || '127.0.0.1';
+      const port = req.query.port;
+      let reqPath = req.query.path || '/';
+      if (req.query.q) reqPath += (reqPath.includes('?') ? '&' : '?') + req.query.q;
+      const chunks = [];
+      if (req.readable && !req.readableEnded && req.method !== 'GET' && req.method !== 'HEAD') {
+        await new Promise((resolve, reject) => {
+          req.on('data', c => chunks.push(c));
+          req.on('end', resolve);
+          req.on('error', reject);
+        });
+      }
+      const out = await proxyToLocalPort({
+        host, port, reqPath, method: req.method,
+        headers: req.headers, body: Buffer.concat(chunks), allowRemote: allowRemoteProxy,
+      });
+      for (const [k, v] of Object.entries(out.headers || {})) {
+        if (k.toLowerCase() === 'content-length' || k.toLowerCase() === 'transfer-encoding') continue;
+        res.setHeader(k, v);
+      }
+      res.status(out.status).end(out.body);
+    } catch (e) {
+      res.status(e.status || 502).json({ error: e.message });
+    }
+  });
+
+  app.all('/r/:slug/*', authMiddleware, async (req, res) => {
+    try {
+      const rt = await collab.getRoute(req.params.slug);
+      if (!rt || !rt.enabled) return res.status(404).json({ error: 'route not found' });
+      const suffix = '/' + (req.params[0] || '');
+      const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?') + 1) : '';
+      let reqPath = suffix || '/';
+      if (q) reqPath += (reqPath.includes('?') ? '&' : '?') + q;
+      const out = await proxyToLocalPort({
+        host: rt.targetHost, port: rt.targetPort, reqPath, method: req.method,
+        headers: req.headers, body: null, allowRemote: allowRemoteProxy,
+      });
+      res.status(out.status).end(out.body);
+    } catch (e) {
+      res.status(e.status || 502).json({ error: e.message });
+    }
+  });
+
   app.get('/api/projects/:id/files', authMiddleware, async (req, res) => {
     try {
       const projectPath = resolveProjectRoot(req);
@@ -863,7 +1195,7 @@ export function createApp() {
 
   app.post('/api/projects/notes', authMiddleware, async (req, res) => {
     try {
-      const { root, goal, notes } = req.body || {};
+      const { root, goal, notes, hidden } = req.body || {};
       if (!root) return res.status(400).json({ error: 'root required' });
       const resolved = path.resolve(expandPath(root));
       const db = await loadProjectNotes();
@@ -872,6 +1204,7 @@ export function createApp() {
       const next = {
         goal: goal !== undefined ? String(goal || '') : prev.goal,
         notes: notes !== undefined ? String(notes || '') : prev.notes,
+        hidden: hidden !== undefined ? Boolean(hidden) : prev.hidden,
         updatedAt: Date.now(),
       };
       db[resolved] = next;
@@ -904,11 +1237,22 @@ export function createApp() {
 
   app.put('/api/sessions/meta', authMiddleware, async (req, res) => {
     try {
-      const { sessionId, agent, favorite, notes, title, hidden } = req.body || {};
+      const { sessionId, agent, favorite, notes, title, hidden, branch } = req.body || {};
       if (!sessionId) return res.status(400).json({ error: 'sessionId required' });
       const key = sessionMetaKey(agent || 'claude', sessionId);
       const db = await loadSessionMeta();
-      const prev = db[key] || { favorite: false, notes: '', title: '', hidden: false, updatedAt: 0 };
+      const prev = db[key] || { favorite: false, notes: '', title: '', hidden: false, branch: null, updatedAt: 0 };
+      const nextBranch = branch === undefined
+        ? (prev.branch || null)
+        : (branch && typeof branch === 'object' && typeof branch.parentSessionId === 'string'
+          ? {
+            parentSessionId: branch.parentSessionId,
+            parentAgent: String(branch.parentAgent || agent || 'claude'),
+            parentMachineId: branch.parentMachineId ? String(branch.parentMachineId) : null,
+            forkMessageIndex: Number.isInteger(branch.forkMessageIndex) ? branch.forkMessageIndex : null,
+            forkedAt: Number.isFinite(Number(branch.forkedAt)) ? Number(branch.forkedAt) : Date.now(),
+          }
+          : null);
       const next = {
         favorite: favorite !== undefined ? Boolean(favorite) : Boolean(prev.favorite),
         notes: notes !== undefined ? String(notes || '') : String(prev.notes || ''),
@@ -917,10 +1261,11 @@ export function createApp() {
           ? String(title || '').trim().slice(0, 200)
           : String(prev.title || '').trim(),
         hidden: hidden !== undefined ? Boolean(hidden) : Boolean(prev.hidden),
+        branch: nextBranch,
         updatedAt: Date.now(),
       };
       // Drop empty entries to keep file small
-      if (!next.favorite && !next.notes && !next.title && !next.hidden) {
+      if (!next.favorite && !next.notes && !next.title && !next.hidden && !next.branch) {
         delete db[key];
       } else {
         db[key] = next;
@@ -929,7 +1274,7 @@ export function createApp() {
       res.json({
         success: true,
         key,
-        ...(db[key] || { favorite: false, notes: '', title: '', hidden: false, updatedAt: Date.now() }),
+        ...(db[key] || { favorite: false, notes: '', title: '', hidden: false, branch: null, updatedAt: Date.now() }),
       });
     } catch (e) { res.status(500).json({ error: e.message }); }
   });
@@ -1075,7 +1420,10 @@ export function createApp() {
         compact,
       };
       res.setHeader('X-Session-Agent', payload.agent);
-      res.setHeader('Cache-Control', 'private, max-age=30');
+      // A session can be appended while a turn is streaming. Returning a
+      // cached transcript here lets a client paint an old snapshot after a
+      // newer WS update, so session history must always be read fresh.
+      res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
       res.json(payload);
     } catch (e) {
       res.status(500).json({ error: e.message });
@@ -1120,6 +1468,62 @@ export function createApp() {
     }
   });
 
+  // Fork a session at a completed assistant message. Native transcript cloning
+  // lets the target agent continue with the same context while branch topology
+  // itself is saved by the UI as session metadata (Hub-safe as well).
+  app.post('/api/sessions/:sessionId/fork', authMiddleware, async (req, res) => {
+    try {
+      const { sessionId } = req.params;
+      const { sourceAgent, upTo, assistantText } = req.body || {};
+      if (!/^[0-9a-f-]{36}$/i.test(sessionId)) return res.status(400).json({ error: 'Invalid session id' });
+      const detectedSourceAgent = String(sourceAgent || '').toLowerCase();
+      if (!ENABLED_AGENTS.includes(detectedSourceAgent)) {
+        return res.status(400).json({ error: 'A valid sourceAgent is required' });
+      }
+      if (!await enforceSessionLock(req, res, sessionId, detectedSourceAgent)) return;
+      const opts = {
+        claudeConfigDirs: CLAUDE_CONFIG_DIRS,
+        codexHome: CODEX_HOME,
+        grokHome: GROK_HOME,
+        geminiHome: GEMINI_HOME,
+        cursorHome: CURSOR_HOME,
+      };
+      // A streamed assistant message may reach the screen a moment before the
+      // CLI finishes its journal write. Retry briefly, then match the exact
+      // output text; history index is preferred for already-loaded messages.
+      let bundle = null;
+      for (let attempt = 0; attempt < 3; attempt++) {
+        bundle = await loadSessionMessages(sessionId, detectedSourceAgent, opts);
+        const messages = bundle?.messages || [];
+        if (Number.isInteger(upTo) && upTo >= 0 && upTo < messages.length) break;
+        if (typeof assistantText === 'string' && assistantText.trim()
+          && messages.some(m => m?.role === 'assistant' && m?.content === assistantText)) break;
+        if (attempt < 2) await new Promise(resolve => setTimeout(resolve, 180));
+      }
+      const messages = bundle?.messages || [];
+      if (!messages.length) return res.status(404).json({ error: 'Source session history is not ready yet' });
+      let forkIndex = Number.isInteger(upTo) && upTo >= 0 && upTo < messages.length ? upTo : -1;
+      if (forkIndex < 0 && typeof assistantText === 'string' && assistantText.trim()) {
+        for (let i = messages.length - 1; i >= 0; i--) {
+          if (messages[i]?.role === 'assistant' && messages[i]?.content === assistantText) { forkIndex = i; break; }
+        }
+      }
+      if (forkIndex < 0 || messages[forkIndex]?.role !== 'assistant') {
+        return res.status(409).json({ error: 'The selected assistant message is not persisted yet. Please try again in a moment.' });
+      }
+      const { targetSessionId } = await convertSession(
+        sessionId,
+        detectedSourceAgent,
+        detectedSourceAgent,
+        opts,
+        { upTo: forkIndex + 1 },
+      );
+      res.json({ success: true, targetSessionId, targetAgent: detectedSourceAgent, forkMessageIndex: forkIndex });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
   app.get('/api/sessions/:sessionId/memory', authMiddleware, async (req, res) => {
     try {
       const { sessionId } = req.params;
@@ -1476,6 +1880,40 @@ export function createApp() {
   const wssChat  = new WebSocketServer(wssOpts);
   const wssShell = new WebSocketServer(wssOpts);
 
+  // macOS supports recursive fs.watch; the non-recursive fallback still gives
+  // us the periodic mirror safety net on platforms/filesystems that do not.
+  // Watch only agent-owned record directories, never Terminal PTYs.
+  const externalWatchers = [];
+  let externalRefreshTimer = null;
+  const requestExternalRefresh = () => {
+    if (externalRefreshTimer) return;
+    externalRefreshTimer = setTimeout(() => {
+      externalRefreshTimer = null;
+      externalSessionMirror.refresh().catch(() => {});
+      // A CLI can create a brand-new native session without any browser being
+      // subscribed yet. Let open UIs refresh their sidebar catalog as well.
+      for (const client of chatClients) sendJson(client.ws, { type: 'external-sessions-changed' });
+    }, 80);
+  };
+  for (const dir of [
+    path.join(CODEX_HOME, 'sessions'),
+    path.join(GROK_HOME, 'sessions'),
+    ...CLAUDE_CONFIG_DIRS.map(d => path.join(d, 'projects')),
+    GEMINI_HOME,
+    CURSOR_HOME,
+  ]) {
+    try {
+      externalWatchers.push(fsSync.watch(dir, { recursive: true }, requestExternalRefresh));
+    } catch {
+      try { externalWatchers.push(fsSync.watch(dir, requestExternalRefresh)); } catch { /* directory may not exist yet */ }
+    }
+  }
+  server.once('close', () => {
+    if (externalRefreshTimer) clearTimeout(externalRefreshTimer);
+    for (const watcher of externalWatchers) watcher.close();
+    externalSessionMirror.close();
+  });
+
   server.on('upgrade', (req, socket, head) => {
     const pathname = new URL(req.url, 'http://localhost').pathname;
     if (pathname === '/ws/chat') {
@@ -1503,7 +1941,15 @@ export function createApp() {
       return;
     }
 
-    const client = { ws, sessionId: url.searchParams.get('sessionId') || null };
+    const client = {
+      ws,
+      sessionId: url.searchParams.get('sessionId') || null,
+      agent: url.searchParams.get('agent') || null,
+      username: decoded.username || null,
+      role: decoded.role || (decoded.viaHub ? 'editor' : 'editor'),
+      viaHub: !!decoded.viaHub,
+      externalMirrorKey: null,
+    };
     chatClients.add(client);
 
     // Broadcast to every chat socket on the same session (mobile reconnect / multi-tab).
@@ -1546,11 +1992,33 @@ export function createApp() {
 
       if (cmd.cmd === 'session.subscribe') {
         client.sessionId = cmd.sessionId || client.sessionId || null;
+        client.agent = cmd.agent || client.agent || null;
         wireSend({
           type: 'run-status',
           sessionId: client.sessionId,
           running: isSessionBusy(client.sessionId),
         });
+        // UI-managed active runs already stream their events directly. For
+        // everything else, tail the native persisted transcript so an agent
+        // launched in an ordinary terminal appears live in this UI.
+        if (!isSessionBusy(client.sessionId)) {
+          externalSessionMirror.subscribe(client, {
+            sessionId: client.sessionId,
+            agent: client.agent,
+          });
+        } else {
+          externalSessionMirror.unsubscribe(client);
+        }
+        const queued = getGrokQueueState(client.sessionId);
+        if (queued.running || queued.items.length) {
+          wireSend({
+            type: 'grok-queue-status',
+            agent: 'grok',
+            sessionId: client.sessionId,
+            running: queued.running,
+            items: queued.items,
+          });
+        }
         outbox.flush();
         return;
       }
@@ -1570,8 +2038,9 @@ export function createApp() {
 
       if (cmd.cmd === 'turn.interrupt') {
         const sid = cmd.sessionId;
-        const ok = abortSession(sid);
+        const ok = abortSession(sid, { preserveQueue: cmd.preserveQueue === true });
         wireSend({ type: 'abort-result', success: ok, sessionId: sid });
+        wireSend({ type: 'grok-queue-status', agent: 'grok', sessionId: sid, running: false, items: [] });
         outbox.flush();
         return;
       }
@@ -1582,6 +2051,24 @@ export function createApp() {
         if (cmd.sessionId) options.sessionId = cmd.sessionId;
         if (cmd.cwd) options.cwd = cmd.cwd;
         if (options.sessionId) client.sessionId = options.sessionId;
+        // Hub already enforced the lease (X-Hub-User). Standalone checks here.
+        if (!client.viaHub && options.sessionId && client.username) {
+          const lockTok = cmd.lockToken || options.lockToken || msg.lockToken;
+          const r = await collab.requireLock({
+            key: sessionResourceKey(options.sessionId, agent),
+            lockToken: lockTok,
+            writer: client.username,
+            writerRole: client.role || 'editor',
+          });
+          if (r.code !== 200) {
+            wireSend({
+              type: 'error', code: r.code, message: r.error || 'locked',
+              lock: r.lock, sessionId: options.sessionId,
+            });
+            outbox.flush();
+            return;
+          }
+        }
         // A socket may subscribe to another session while this agent is still
         // streaming. Keep this run's delivery target in its own closure rather
         // than consulting mutable client.sessionId in the shared socket outbox.
@@ -1614,11 +2101,9 @@ export function createApp() {
         } finally {
           // `complete` is a UI-facing agent event and is not a reliable
           // scheduling boundary (an adapter may emit it early or more than
-          // once). The hub advances its Grok FIFO only after dispatchAgent has
-          // actually returned from the ACP request.
-          if (agent === 'grok') {
-            runOutbox.send({ type: 'hub-turn-finished', agent, sessionId: runSessionId });
-          }
+          // once). Clients may only advance a local FIFO after the adapter has
+          // actually returned and released the session, for every agent.
+          runOutbox.send({ type: 'hub-turn-finished', agent, sessionId: runSessionId });
           runOutbox.flush();
         }
         return;
@@ -1666,6 +2151,7 @@ export function createApp() {
 
     ws.on('close', () => {
       chatClients.delete(client);
+      externalSessionMirror.unsubscribe(client);
       clearInterval(heartbeat);
       outbox.flush();
       shellOut?.flush();
@@ -1788,6 +2274,7 @@ else:
 export async function init() {
   await loadCreds();
   await bootstrapEnvUser();
+  await applyAgentEnvToProcess(process.env);
   await syncConfigDirs();
   console.log(`[agents] enabled: ${ENABLED_AGENTS.join(', ')}`);
   console.log(`[agents] claude=${CLAUDE_CLI_PATH}  codex=${CODEX_CLI_PATH}  grok=${GROK_CLI_PATH}  gemini=${GEMINI_CLI_PATH}`);