gitroots 0.5.0 → 0.6.0

package/src/session/agents.js

@@ -0,0 +1,416 @@
+// /agents · /machines · /watch · /attach
+// Sessions come from two places:
+//   - your machines, as the gitroots app reports them (approve / deny / message / stop go back through gitroots)
+//   - this computer: Claude Code and Codex session files (resume them here)
+import { spawn, spawnSync } from 'node:child_process';
+import { select, interactive, ask, confirm, enterFullscreen, leaveFullscreen, paintFrame, size, parseKeys, FRAMES } from '../ui/term.js';
+import { json } from '../ui/components.js';
+import { localSessions, refreshLocal, shortPath, ago as agoMs } from '../agents/local.js';
+import { c, h, line, pad, fit, width, next, load, ago, empty, cols, cmdText, statusMark } from './helpers.js';
+import { windowed } from './workspace.js';
+
+// ---------------------------------------------------------------- data
+
+function remoteRow(s) {
+  return {
+    key: `r:${s.id}`, source: 'remote', id: s.id, agentName: s.agent_name, title: s.title, where: s.machine || 'removed machine',
+    branch: [s.repo, s.branch].filter(Boolean).join(' · '), status: s.status, needs: s.needs_you, updated: ago(s.updated_at), raw: s,
+  };
+}
+
+function localRow(s) {
+  return {
+    key: `l:${s.id}`, source: 'local', id: s.id, agentName: s.agentName, title: s.title, where: shortPath(s.cwd),
+    branch: s.branch, status: s.status, needs: false, updated: agoMs(s.mtime), raw: s,
+  };
+}
+
+async function gather(ctx, { quiet = false } = {}) {
+  let remote = null;
+  let remoteError = null;
+  if (ctx.api.signedIn && ctx.api.orgId !== null && ctx.api.orgId !== undefined) {
+    try { remote = await ctx.api.agents({ signal: ctx.signal, timeout: 8000 }); } catch (e) { remoteError = e.message; }
+  } else remoteError = ctx.api.signedIn ? 'no workspace chosen' : 'not signed in';
+  const local = localSessions({ limit: 40 });
+  const rows = [
+    ...(remote?.sessions || []).filter((s) => s.active || Date.now() - Date.parse(s.updated_at || 0) < 864e5).map(remoteRow),
+    ...local.map(localRow),
+  ];
+  rows.sort((a, b) => (b.needs - a.needs) || (rank(a.status) - rank(b.status)));
+  if (!quiet && remoteError && ctx.api.signedIn) line(c.w(`◐ couldn't load sessions from gitroots: ${remoteError}`));
+  return { rows, remote, local, remoteError };
+}
+
+const rank = (s) => ({ waiting: 0, blocked: 1, live: 2, idle: 3 }[s] ?? 4);
+
+function rowText(r, sel, w = cols()) {
+  const tailFit = (t, n) => (t.length > n ? `…${t.slice(t.length - n + 1)}` : t);
+  const where = r.source === 'remote' ? `⇄ ${r.where}` : `⌂ ${tailFit(r.where, 28)}`;
+  const text = `${pad(statusMark(r.status), 14)}${pad(r.agentName, 13)}${fit(r.title, 36)}  ${c.m(fit(where, 30))}  ${c.m(fit(r.branch || '', Math.max(8, w - 111)))}${c.m(pad(r.updated, 9))}`;
+  return `${sel ? c.g('❯ ') : '  '}${sel ? c.b(text) : text}`;
+}
+
+// ---------------------------------------------------------------- /agents
+
+export async function agents(ctx) {
+  const d = await load(ctx, 'Looking for agent sessions…', () => gather(ctx, { quiet: true }));
+  if (ctx.json) { json({ remote: d.remote?.sessions || [], local: d.local.map(({ log, ...s }) => s) }); return 0; }
+  if (d.remoteError && ctx.api.signedIn) line(c.w(`◐ couldn't load sessions from gitroots: ${d.remoteError}`));
+  if (!ctx.api.signedIn) line(c.m(`○ showing this computer only · ${cmdText(ctx, 'login')} adds the sessions your gitroots app reports`));
+  if (!d.rows.length) { empty('no agent sessions in the last 14 days'); return 0; }
+  line(`  ${h(`${pad('STATE', 14)}${pad('AGENT', 13)}${pad('SESSION', 38)}${pad('WHERE', 32)}BRANCH`)}`);
+  if (!ctx.session || !interactive()) {
+    for (const r of d.rows.slice(0, 30)) line(rowText(r, false));
+    line();
+    next(ctx, 'watch');
+    return 0;
+  }
+  const res = await select({ count: d.rows.length, render: (i) => `${windowed(d.rows, i, 12, (r, sel) => rowText(r, sel))}\n${c.m('  ⇄ your machines, via the gitroots app   ⌂ this computer')}` });
+  if (res.action === 'cancel') return 0;
+  return sessionActions(ctx, d.rows[res.index]);
+}
+
+async function sessionActions(ctx, r) {
+  const s = r.raw;
+  line();
+  line(`${c.b(r.title)}  ${statusMark(r.status)}`);
+  line(`  ${c.s(pad('agent', 10))}${r.agentName} ${c.m(r.source === 'remote' ? `on ${r.where} · owner ${s.owner}` : `on this computer · ${r.where}`)}`);
+  if (r.branch) line(`  ${c.s(pad('branch', 10))}${r.branch}`);
+  if (r.source === 'remote' && s.ask && s.ask.what) {
+    line(`  ${c.w(pad('asks', 10))}${s.ask.what}${s.ask.cmd ? c.m(` · ${s.ask.cmd}`) : ''}`);
+    if (s.ask.rule) line(`  ${c.s(pad('rule', 10))}${s.ask.rule}`);
+  }
+  line();
+  const actions = [['view', 'Open live view']];
+  if (r.source === 'remote') {
+    if (s.can_decide) actions.push(['approve', 'Approve'], ['deny', 'Deny']);
+    if (s.can_send) actions.push(['send', 'Send a message']);
+    if (s.can_stop) actions.push(['stop', 'Stop']);
+  } else {
+    actions.push(['resume', `Resume here (${s.resume.cmd} ${s.resume.args.join(' ')})`], ['copy', 'Copy the resume command']);
+  }
+  actions.push(['back', 'Back']);
+  const pick = await select({ count: actions.length, render: (i) => actions.map(([, label], j) => `${j === i ? c.g('❯ ') : '  '}${j === i ? c.b(label) : label}`).join('\n') });
+  if (pick.action === 'cancel') return 0;
+  const act = actions[pick.index][0];
+  if (act === 'back') return 0;
+  if (act === 'view') return attachView(ctx, r);
+  if (act === 'resume') return resumeLocal(s);
+  if (act === 'copy') return copyResume(s);
+  return remoteAction(ctx, s, act);
+}
+
+async function remoteAction(ctx, s, act) {
+  let text = '';
+  if (act === 'send') { text = await ask('Message to the agent'); if (!text) { line(c.m('  nothing sent')); return 0; } }
+  if (act === 'stop' && !(await confirm(`Stop ${s.title}?`, { def: false }))) { line(c.m('  nothing changed')); return 0; }
+  const r = await load(ctx, 'Sending to gitroots…', () => ctx.api.agentAction(s.id, act, text, { signal: ctx.signal }));
+  const verb = { approve: 'Approved', deny: 'Denied', send: 'Message sent', stop: 'Stop requested' }[act];
+  line(`${act === 'deny' || act === 'stop' ? c.w('◐') : c.g('✓')} ${verb} ${c.m(`· ${r.note || 'the gitroots app on that machine picks it up on its next sync'}`)}`);
+  return 0;
+}
+
+function hasCommand(cmd) {
+  const r = spawnSync(process.platform === 'win32' ? 'where' : 'sh', process.platform === 'win32' ? [cmd] : ['-c', `command -v ${cmd}`], { stdio: 'ignore' });
+  return r.status === 0;
+}
+
+export async function resumeLocal(s) {
+  if (!hasCommand(s.resume.cmd)) { line(c.r(`✕ ${s.resume.cmd} isn't on your PATH · install ${s.agentName} first`)); return 1; }
+  line(c.m(`  ${shortPath(s.cwd)} $ ${s.resume.cmd} ${s.resume.args.join(' ')}`));
+  line(c.m(`  gitroots continues when ${s.agentName} exits`));
+  line();
+  const code = await new Promise((resolve) => {
+    const child = spawn(s.resume.cmd, s.resume.args, { cwd: s.cwd, stdio: 'inherit' });
+    child.on('error', (e) => { line(c.r(`✕ ${e.message}`)); resolve(1); });
+    child.on('exit', (n) => resolve(n ?? 0));
+  });
+  line();
+  line(c.m(`  back in gitroots · ${s.agentName} exited${code ? ` with ${code}` : ''}`));
+  return 0;
+}
+
+async function copyResume(s) {
+  const cmd = `cd ${JSON.stringify(s.cwd)} && ${s.resume.cmd} ${s.resume.args.join(' ')}`;
+  const { copyToClipboard } = await import('../ui/term.js');
+  const ok = await copyToClipboard(cmd);
+  line(ok ? `${c.g('✓')} Copied ${c.m(cmd)}` : `  ${cmd}`);
+  return 0;
+}
+
+// ---------------------------------------------------------------- /machines
+
+export async function machines(ctx) {
+  const d = await load(ctx, 'Loading machines…', () => ctx.api.agents({ signal: ctx.signal }));
+  if (ctx.json) { json(d.machines); return 0; }
+  if (!d.machines.length) { empty('no machines yet · add them in the gitroots app (Agents › Machines)'); return 0; }
+  for (const m of d.machines) {
+    const load_ = m.online ? c.m(`cpu ${m.cpu ?? '–'}% · mem ${m.mem ?? '–'}% · disk ${m.disk ?? '–'}%`) : c.m(`last seen ${ago(m.last_seen_at) || 'never'}`);
+    line(`  ${m.online ? c.g('● online ') : c.m('○ offline')}  ${c.b(pad(m.name, 22))}${pad(m.os || m.kind || '', 26)}${pad(m.agents.join(', '), 22)}${load_}`);
+  }
+  line();
+  next(ctx, 'watch');
+  return 0;
+}
+
+// ---------------------------------------------------------------- full screen: /watch and /attach
+
+function logLines(r, detail) {
+  if (r.source === 'local') {
+    return (r.raw.log || []).map((l) => (l.who === 'you' ? `${c.i(c.b(pad('you', 7)))}${l.text}` : l.who === 'tool' ? `${c.m(pad('tool', 7))}${c.s(l.text)}` : `${c.g(c.b(pad('agent', 7)))}${l.text}`));
+  }
+  const log = detail?.log || r.raw.log || r.raw.last_log || [];
+  return log.map((l) => `${c.s(l)}`);
+}
+
+function keyChip(k, label) { return `${c.bg('key')(c.b(` ${k} `))} ${c.s(label)}`; }
+
+export async function watch(ctx) {
+  if (!interactive()) return agents(ctx);
+  let rows = [];
+  let idx = 0;
+  let tick = 0;
+  let flash = null;
+  let busy = false;
+  let lastRemote = 0;
+  let remoteError = null;
+  let remote = null;
+  const details = {};
+  let lastDetail = 0;
+  const loadDetail = async () => {
+    const r = rows[idx];
+    if (!r || r.source !== 'remote' || Date.now() - lastDetail < 2500) return;
+    lastDetail = Date.now();
+    try { details[r.raw.id] = await ctx.api.agentSession(r.raw.id, { timeout: 8000 }); } catch { /* keep last */ }
+  };
+  const refresh = async (force) => {
+    if (busy) return;
+    busy = true;
+    try {
+      if (force || Date.now() - lastRemote > 3000) {
+        if (ctx.api.signedIn && ctx.api.orgId != null) {
+          try { remote = await ctx.api.agents({ timeout: 8000 }); remoteError = null; } catch (e) { remoteError = e.message; }
+        }
+        lastRemote = Date.now();
+      }
+      const keep = rows[idx]?.key;
+      const local = localSessions({ limit: 40 });
+      rows = [...(remote?.sessions || []).filter((s) => s.active).map(remoteRow), ...local.filter((s) => Date.now() - s.mtime < 3 * 864e5).map(localRow)];
+      rows.sort((a, b) => (b.needs - a.needs) || (rank(a.status) - rank(b.status)));
+      const k = rows.findIndex((r) => r.key === keep);
+      idx = k >= 0 ? k : Math.min(idx, Math.max(0, rows.length - 1));
+      await loadDetail();
+    } finally { busy = false; }
+  };
+  await refresh(true);
+  return new Promise((resolve) => {
+    let mode = null; // { type: 'send', text } | { type: 'confirm-stop' }
+    const draw = () => {
+      const { cols: W, rows: H } = size();
+      const spin = FRAMES[tick % FRAMES.length];
+      const n = (st) => rows.filter((r) => r.status === st).length;
+      const left = `  ${c.g(c.b('gitroots'))}  ${c.b('watch')}   ${c.s(`${n('live')} live · ${rows.filter((r) => r.needs).length} need you · ${n('idle')} idle`)}${remoteError ? `   ${c.w(`◐ gitroots: ${remoteError}`)}` : ''}`;
+      const right = `${c.m(`${new Date().toTimeString().slice(0, 8)} · live`)}  `;
+      const frame = [c.bg('bar')(fit(left, W - width(right)) + right), ''];
+      frame.push(`  ${h(`${pad('STATE', 14)}${pad('AGENT', 13)}${pad('SESSION', 38)}WHERE`)}`);
+      const listH = Math.max(3, Math.min(rows.length, Math.floor((H - 6) / 2)));
+      const start = Math.max(0, Math.min(idx - listH + 1, rows.length - listH));
+      for (let i = start; i < start + listH && i < rows.length; i++) frame.push(i === idx ? c.bg('sel')(fit(rowText(rows[i], true, W), W)) : rowText(rows[i], false, W));
+      if (!rows.length) frame.push(c.m('  no agent sessions · start Claude Code or Codex, or add machines in the gitroots app'));
+      frame.push('');
+      const r = rows[idx];
+      const boxH = H - frame.length - 3;
+      if (r && boxH > 2) {
+        frame.push(` ${c.b(r.title)} ${c.m(`· ${r.agentName} · ${r.where}${r.branch ? ` · ${r.branch}` : ''}`)}`);
+        let body = logLines(r, r.source === 'remote' ? details[r.raw.id] : null);
+        if (r.source === 'remote' && r.raw.ask?.what) body = [...body, '', `${c.w(c.b('◐ asks'))} ${r.raw.ask.what}${r.raw.ask.cmd ? c.m(` · ${r.raw.ask.cmd}`) : ''}`, r.raw.can_decide ? c.g('y approve · n deny') : c.m('waiting for the session owner')];
+        if (r.status === 'live') body.push(`${c.i(spin)} ${c.s('working')}`);
+        const inner = boxH - 2;
+        const view = body.slice(-inner);
+        while (view.length < inner) view.unshift('');
+        frame.push(` ${c.m(`╭${'─'.repeat(W - 4)}╮`)}`);
+        for (const l of view) frame.push(` ${c.m('│')} ${fit(l, W - 6)} ${c.m('│')}`);
+        frame.push(` ${c.m(`╰${'─'.repeat(W - 4)}╯`)}`);
+      }
+      while (frame.length < H - 1) frame.push('');
+      let bar;
+      if (mode?.type === 'send') bar = `  ${c.s('message:')} ${mode.text}${c.inv(' ')}   ${c.m('enter send · esc cancel')}`;
+      else if (mode?.type === 'stop') bar = `  ${c.w(`Stop "${fit(rows[idx]?.title || '', 40)}"?`)} ${c.m('(y/N)')}`;
+      else {
+        const cur = rows[idx];
+        const keys = [keyChip('↑↓', 'move'), keyChip('enter', 'open')];
+        if (cur?.source === 'remote') {
+          if (cur.raw.can_decide) keys.push(keyChip('y', 'approve'), keyChip('n', 'deny'));
+          if (cur.raw.can_send) keys.push(keyChip('m', 'message'));
+          if (cur.raw.can_stop) keys.push(keyChip('s', 'stop'));
+        } else if (cur) keys.push(keyChip('r', 'resume here'));
+        keys.push(keyChip('q', 'back'));
+        bar = `  ${keys.join('  ')}`;
+      }
+      if (flash && Date.now() < flash.until) bar = `${fit(bar, Math.max(0, W - width(flash.msg) - 4))}  ${flash.msg}  `;
+      frame.push(c.bg('bar')(fit(bar, W)));
+      paintFrame(frame.slice(0, H));
+    };
+    const say = (msg) => { flash = { msg, until: Date.now() + 4000 }; };
+    const act = async (r, action, text) => {
+      try {
+        const res = await ctx.api.agentAction(r.raw.id, action, text);
+        say(c.g(`✓ ${{ approve: 'approved', deny: 'denied', send: 'sent', stop: 'stop requested' }[action]} · ${res.note || 'queued'}`));
+      } catch (e) { say(c.r(`✕ ${e.message}`)); }
+      refresh(true).then(draw);
+    };
+    const finish = (after) => {
+      clearInterval(timer);
+      process.stdin.off('data', onData);
+      process.stdout.off('resize', draw);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      leaveFullscreen();
+      resolve(after ? after() : 0);
+      return true;
+    };
+    const onKey = (k) => {
+      const r = rows[idx];
+      if (mode?.type === 'send') {
+        if (k.name === 'escape') mode = null;
+        else if (k.name === 'enter') { const t = mode.text.trim(); mode = null; if (t && r) act(r, 'send', t); }
+        else if (k.name === 'backspace') mode.text = mode.text.slice(0, -1);
+        else if (k.ch) mode.text += k.ch;
+        return;
+      }
+      if (mode?.type === 'stop') { mode = null; if ((k.ch === 'y' || k.ch === 'Y') && r) act(r, 'stop'); return; }
+      switch (k.ch || k.name) {
+        case 'q': case 'escape': case 'ctrl-c': return finish();
+        case 'up': case 'k': if (rows.length) { idx = (idx - 1 + rows.length) % rows.length; lastDetail = 0; loadDetail().then(draw); } break;
+        case 'down': case 'j': if (rows.length) { idx = (idx + 1) % rows.length; lastDetail = 0; loadDetail().then(draw); } break;
+        case 'enter': case 'a': if (r) return finish(() => attachView(ctx, r).then(() => watch(ctx))); break;
+        case 'y': if (r?.source === 'remote' && r.raw.can_decide) act(r, 'approve'); break;
+        case 'n': if (r?.source === 'remote' && r.raw.can_decide) act(r, 'deny'); break;
+        case 'm': if (r?.source === 'remote' && r.raw.can_send) mode = { type: 'send', text: '' }; break;
+        case 's': if (r?.source === 'remote' && r.raw.can_stop) mode = { type: 'stop' }; break;
+        case 'r': if (r?.source === 'local') return finish(() => resumeLocal(r.raw)); break;
+        default: break;
+      }
+    };
+    const onData = (buf) => { for (const k of parseKeys(buf)) { const out = onKey(k); if (out !== undefined) return; } draw(); };
+    enterFullscreen();
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('data', onData);
+    process.stdout.on('resize', draw);
+    const timer = setInterval(() => { tick++; if (tick % 15 === 0) refresh().then(draw); else draw(); }, 100);
+    draw();
+  });
+}
+
+export async function attach(ctx, args) {
+  const d = await load(ctx, 'Looking for the session…', () => gather(ctx, { quiet: true }));
+  let r = null;
+  const id = args[0];
+  if (id) r = d.rows.find((x) => String(x.id) === id || String(x.id).startsWith(id) || x.key === id);
+  if (!r) {
+    if (!interactive() || !d.rows.length) throw new Error(d.rows.length ? `no session ${id}` : 'no agent sessions to attach to');
+    line(`${c.i(c.b('?'))} Which session?`);
+    const res = await select({ count: d.rows.length, render: (i) => windowed(d.rows, i, 12, (x, sel) => rowText(x, sel)) });
+    if (res.action === 'cancel') return 0;
+    r = d.rows[res.index];
+  }
+  return attachView(ctx, r);
+}
+
+export function attachView(ctx, r) {
+  if (!interactive()) { for (const l of logLines(r)) line(l); return Promise.resolve(0); }
+  return new Promise((resolve) => {
+    let detail = null;
+    let tick = 0;
+    let flash = null;
+    let mode = null;
+    let row = r;
+    const refresh = async () => {
+      try {
+        if (row.source === 'remote') { detail = await ctx.api.agentSession(row.raw.id, { timeout: 8000 }); row = { ...row, raw: { ...row.raw, ...detail }, status: detail.status }; }
+        else { const s = refreshLocal(row.raw); row = { ...row, raw: s, status: s.status, updated: agoMs(s.mtime) }; }
+      } catch (e) { flash = { msg: c.w(`◐ ${e.message}`), until: Date.now() + 4000 }; }
+    };
+    const draw = () => {
+      const { cols: W, rows: H } = size();
+      const s = row.raw;
+      const head = `  ${c.g(c.b('gitroots'))}   ${c.b(`attached · ${fit(row.title, 40)}`)}   ${c.s(`${row.agentName} · ${row.where}`)}   ${statusMark(row.status)}`;
+      const frame = [c.bg('attach')(fit(head, W)), ''];
+      let body = logLines(row, detail);
+      if (row.source === 'remote' && s.ask?.what && row.status === 'waiting') {
+        body = [...body, '', `${c.w(c.b('  ◐ Approval needed'))}  ${s.ask.what}`, s.ask.cmd ? `    ${c.s(s.ask.cmd)}` : '', s.ask.why ? `    ${c.m(s.ask.why)}` : '', s.can_decide ? `    ${c.g('y approve')}   ${c.r('n deny')}` : c.m('    waiting for the session owner')].filter((x) => x !== '');
+      }
+      if (detail?.pending?.length) body.push('', c.m(`  ${detail.pending.length} request${detail.pending.length > 1 ? 's' : ''} waiting for the gitroots app on ${row.where}: ${detail.pending.map((p) => p.kind).join(', ')}`));
+      if (row.status === 'live') body.push(`${c.i(FRAMES[tick % FRAMES.length])} ${c.s('working')}`);
+      const bodyH = H - 4;
+      const view = body.slice(-bodyH);
+      while (view.length < bodyH) view.push('');
+      for (const l of view) frame.push(` ${fit(l, W - 2)}`);
+      let bar;
+      if (mode?.type === 'send') bar = `  ${c.g('❯')} ${mode.text}${c.inv(' ')}   ${c.m('enter send · esc cancel')}`;
+      else if (mode?.type === 'stop') bar = `  ${c.w('Stop this session?')} ${c.m('(y/N)')}`;
+      else {
+        const keys = [];
+        if (row.source === 'remote') {
+          if (s.can_decide && row.status === 'waiting') keys.push(keyChip('y', 'approve'), keyChip('n', 'deny'));
+          if (s.can_send) keys.push(keyChip('m', 'message'));
+          if (s.can_stop) keys.push(keyChip('s', 'stop'));
+        } else keys.push(keyChip('r', `resume in ${s.resume.cmd}`));
+        keys.push(keyChip('q', 'back'));
+        bar = `  ${keys.join('  ')}`;
+      }
+      if (flash && Date.now() < flash.until) bar = `${fit(bar, Math.max(0, W - width(flash.msg) - 4))}  ${flash.msg}  `;
+      frame.push(c.bg('bar')(fit(bar, W)));
+      paintFrame(frame.slice(0, H));
+    };
+    const act = async (action, text) => {
+      try {
+        const res = await ctx.api.agentAction(row.raw.id, action, text);
+        flash = { msg: c.g(`✓ ${{ approve: 'approved', deny: 'denied', send: 'sent', stop: 'stop requested' }[action]} · ${res.note || 'queued'}`), until: Date.now() + 5000 };
+      } catch (e) { flash = { msg: c.r(`✕ ${e.message}`), until: Date.now() + 5000 }; }
+      await refresh();
+      draw();
+    };
+    const finish = (after) => {
+      clearInterval(timer);
+      process.stdin.off('data', onData);
+      process.stdout.off('resize', draw);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      leaveFullscreen();
+      resolve(after ? after() : 0);
+      return true;
+    };
+    const onKey = (k) => {
+      const s = row.raw;
+      if (mode?.type === 'send') {
+        if (k.name === 'escape') mode = null;
+        else if (k.name === 'enter') { const t = mode.text.trim(); mode = null; if (t) act('send', t); }
+        else if (k.name === 'backspace') mode.text = mode.text.slice(0, -1);
+        else if (k.ch) mode.text += k.ch;
+        return undefined;
+      }
+      if (mode?.type === 'stop') { mode = null; if (k.ch === 'y' || k.ch === 'Y') act('stop'); return undefined; }
+      switch (k.ch || k.name) {
+        case 'q': case 'escape': case 'ctrl-c': return finish();
+        case 'y': if (row.source === 'remote' && s.can_decide) act('approve'); break;
+        case 'n': if (row.source === 'remote' && s.can_decide) act('deny'); break;
+        case 'm': if (row.source === 'remote' && s.can_send) mode = { type: 'send', text: '' }; break;
+        case 's': if (row.source === 'remote' && s.can_stop) mode = { type: 'stop' }; break;
+        case 'r': if (row.source === 'local') return finish(() => resumeLocal(row.raw)); break;
+        default: break;
+      }
+      return undefined;
+    };
+    const onData = (buf) => { for (const k of parseKeys(buf)) { const out = onKey(k); if (out !== undefined) return; } draw(); };
+    enterFullscreen();
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('data', onData);
+    process.stdout.on('resize', draw);
+    const timer = setInterval(() => { tick++; if (tick % 20 === 0) refresh().then(draw); else draw(); }, 100);
+    refresh().then(draw);
+    draw();
+  });
+}

package/src/session/helpers.js

@@ -0,0 +1,71 @@
+// Shared bits for commands: loading spinners, hints, empty states, time.
+import { c, h, pad, fit, width } from '../ui/ansi.js';
+import { line, spinner, size } from '../ui/term.js';
+import { ApiError } from '../api.js';
+
+export { c, h, pad, fit, width, line };
+
+export function cols() { return Math.max(60, Math.min(size().cols, 160)); }
+
+// "/status" inside the session, "gitroots status" outside.
+export function cmdText(ctx, name, args = '') {
+  return ctx.session ? `/${name}${args ? ` ${args}` : ''}` : `gitroots ${name}${args ? ` ${args}` : ''}`;
+}
+
+export function next(ctx, name, args, alt) {
+  const tail = alt ? `   ${c.m('or')}  ${c.s(alt)}` : '';
+  line(`${c.g(`→ ${cmdText(ctx, name, args)}`)}${tail}`);
+}
+
+export function needSignIn(ctx) {
+  if (ctx.api.signedIn) return;
+  throw new ApiError(`not signed in · ${cmdText(ctx, 'login')} connects your gitroots account`, 401);
+}
+
+export function needWorkspace(ctx) {
+  needSignIn(ctx);
+  if (ctx.api.orgId === null || ctx.api.orgId === undefined) throw new ApiError(`no workspace chosen · ${cmdText(ctx, 'workspace')}`, 400);
+}
+
+/** Await work behind a one-line spinner. */
+export async function load(ctx, label, fn) {
+  if (ctx.json) return fn();
+  const sp = spinner((f) => `${c.i(f)} ${c.s(label)}`);
+  try { return await fn(); } finally { sp.stop(); }
+}
+
+export function ago(iso) {
+  if (!iso) return '';
+  const s = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+export function empty(text) { line(`  ${c.m(text)}`); }
+
+// A table that fits the terminal: the last column takes what's left.
+export function table(columns, rows) {
+  const total = cols() - 2;
+  const fixed = columns.slice(0, -1).reduce((n, col) => n + col.w, 0);
+  const lastW = Math.max(10, total - fixed);
+  line(`  ${h(columns.map((col, i) => (i === columns.length - 1 ? col.label : pad(col.label, col.w))).join(''))}`);
+  for (const r of rows) {
+    line(`  ${columns.map((col, i) => {
+      const v = col.fmt ? col.fmt(r) : String(r[col.key] ?? '');
+      return i === columns.length - 1 ? fit(v, lastW).trimEnd() : fit(v, col.w - 1) + ' ';
+    }).join('')}`);
+  }
+}
+
+export const STATUS_MARK = {
+  live: (w = 'live') => c.g(`● ${w}`),
+  waiting: (w = 'needs you') => c.w(`◐ ${w}`),
+  blocked: (w = 'blocked') => c.r(`✕ ${w}`),
+  idle: (w = 'idle') => c.s(`○ ${w}`),
+  done: (w = 'finished') => c.m(`✓ ${w}`),
+  stopped: (w = 'stopped') => c.m(`■ ${w}`),
+  failed: (w = 'failed') => c.r(`✕ ${w}`),
+};
+export function statusMark(s) { return (STATUS_MARK[s] || STATUS_MARK.idle)(); }

package/src/session/logo.js

@@ -0,0 +1,40 @@
+// The gitroots mark (4×4 green grid) drawn with block characters, so it shows in every terminal.
+import { state as colorState, c, width, fit } from '../ui/ansi.js';
+
+// Cell colors sampled from assets/logo.png, light lime (top left) to deep green (bottom right).
+const GRID = [
+  ['#B8DB4A', '#9CCF3A', '#5BB33A', '#22954E'],
+  ['#7DC035', '#63B535', '#258C35', '#0A743F'],
+  ['#1F8932', '#11713F', '#0A6435', '#0A4F33'],
+  ['#0A5835', '#0B4F27', '#0A3A27', '#0A3328'],
+];
+const FALLBACK = [[149, 112, 70, 29], [106, 70, 28, 23], [28, 23, 22, 22], [22, 22, 22, 22]];
+
+function cell(hex, r, col) {
+  if (!colorState.color) return '██';
+  const [R, G, B] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+  const code = colorState.truecolor ? `\x1b[38;2;${R};${G};${B}m` : `\x1b[38;5;${FALLBACK[r][col]}m`;
+  return `${code}██\x1b[39m`;
+}
+
+// Four rows, 11 columns: "██ ██ ██ ██"
+export function logoRows() {
+  return GRID.map((row, r) => row.map((hex, col) => cell(hex, r, col)).join(' '));
+}
+
+// Claude Code-style welcome box: logo on the left, lines of text on the right.
+export function welcomeBox(lines, cols) {
+  const inner = Math.max(40, Math.min(cols - 2, 100));
+  const logo = logoRows();
+  const rows = Math.max(logo.length, lines.length);
+  const out = [];
+  const b = (s) => c.g(s);
+  out.push(b(`╭${'─'.repeat(inner)}╮`));
+  for (let i = 0; i < rows; i++) {
+    const left = logo[i] || ' '.repeat(11);
+    const right = lines[i] || '';
+    out.push(`${b('│')} ${left}   ${fit(right, inner - 16)}${' '.repeat(Math.max(0, inner - 16 - width(fit(right, inner - 16))))} ${b('│')}`);
+  }
+  out.push(b(`╰${'─'.repeat(inner)}╯`));
+  return out;
+}

package/src/session/registry.js

@@ -0,0 +1,61 @@
+// Every command, used by the session's / picker and by one-shot `gitroots <command>`.
+import * as ws from './workspace.js';
+import * as ag from './agents.js';
+import * as acct from './account.js';
+import * as setup from './setup.js';
+
+export const COMMANDS = [
+  { name: 'status', group: 'Workspace', desc: 'What needs you, posture, agents', run: ws.status },
+  { name: 'approvals', group: 'Workspace', args: '[waiting|approved|declined]', desc: 'Review merge and access requests · approve or decline', run: ws.approvals },
+  { name: 'repos', group: 'Workspace', desc: 'Repositories in this workspace', run: ws.repos },
+  { name: 'repo', group: 'Workspace', args: '[name]', desc: 'One repository: branch rules, environments, people', run: ws.repo },
+  { name: 'pushes', group: 'Workspace', args: '[--blocked]', desc: 'Recent pushes and the ones that were blocked', run: ws.pushes },
+  { name: 'audit', group: 'Workspace', args: '[blocked|merges|access] [search]', desc: 'Who did what, when', run: ws.audit },
+  { name: 'activity', group: 'Workspace', desc: 'Team activity over the last 20 weeks', run: ws.activity },
+  { name: 'members', group: 'Workspace', desc: 'People in this workspace and their roles', run: ws.members },
+
+  { name: 'agents', group: 'Agents', desc: 'Agent sessions on your machines and this computer', run: ag.agents },
+  { name: 'watch', group: 'Agents', desc: 'Live dashboard of every agent session', run: ag.watch },
+  { name: 'attach', group: 'Agents', args: '[session]', desc: 'Open one session live · approve, message, stop, resume', run: ag.attach },
+  { name: 'machines', group: 'Agents', desc: 'Machines the gitroots app manages for you', run: ag.machines },
+
+  { name: 'hooks', group: 'This repository', args: '[install|uninstall]', desc: 'Push checks for this repository', run: setup.hooks },
+  { name: 'check', group: 'This repository', desc: 'Run the push checks on your local commits', run: setup.check },
+
+  { name: 'login', group: 'Account', desc: 'Sign in with your browser', run: acct.login },
+  { name: 'logout', group: 'Account', desc: 'Sign out on this computer', run: acct.logout },
+  { name: 'whoami', group: 'Account', aliases: ['account'], desc: 'Who you are signed in as', run: acct.whoami },
+  { name: 'workspace', group: 'Account', args: '[slug]', desc: 'Switch workspace', run: acct.workspace },
+
+  { name: 'doctor', group: 'gitroots', desc: 'Check the install, sign-in, git and hooks', run: setup.doctor },
+  { name: 'update', group: 'gitroots', desc: 'Update gitroots', run: async (ctx, args, flags) => (await import('../commands/update.js')).run('update', args, flags) },
+  { name: 'help', group: 'gitroots', desc: 'All commands and keys', run: null },
+  { name: 'clear', group: 'gitroots', session: true, desc: 'Clear the screen', run: null },
+  { name: 'exit', group: 'gitroots', session: true, aliases: ['quit'], desc: 'Leave gitroots', run: null },
+];
+
+export function find(name) {
+  const n = String(name || '').replace(/^\//, '').toLowerCase();
+  return COMMANDS.find((c) => c.name === n || (c.aliases || []).includes(n)) || null;
+}
+
+/** Commands for the / menu: prefix matches first, then names or descriptions containing the text. */
+export function match(query, { session = true } = {}) {
+  const q = query.toLowerCase();
+  const list = COMMANDS.filter((c) => session || !c.session);
+  if (!q) return list;
+  const starts = list.filter((c) => c.name.startsWith(q) || (c.aliases || []).some((a) => a.startsWith(q)));
+  const contains = list.filter((c) => !starts.includes(c) && (c.name.includes(q) || c.desc.toLowerCase().includes(q)));
+  return [...starts, ...contains];
+}
+
+export function suggest(word) {
+  const w = word.toLowerCase();
+  const dist = (a, b) => {
+    const m = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++) m[0][j] = j;
+    for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return m[a.length][b.length];
+  };
+  return COMMANDS.map((c) => [c, dist(w, c.name)]).filter(([, d]) => d <= 2).sort((a, b) => a[1] - b[1]).map(([c]) => c).slice(0, 3);
+}