ai-agentmanager 1.5.0 → 1.7.0

package/public/menu.js

@@ -52,15 +52,21 @@ export function initMenu({ api, esc, toast, $ }) {
   // ------------------------------------------------------------ Settings dialog
   const dialog = $('#settings-dialog');
   const form = $('#settings-form');
+  let service = null; // the login service as the dialog opened
   $('#settings-btn').onclick = async () => {
     $('#settings-error').hidden = true;
     try {
       const c = await api('GET', '/cleanup');
       form.maxRunning.value = c.maxRunning ?? '';
       $('#settings-running').textContent = `Open now: ${c.running}.`;
+      service = null;
       if (!remote()) {
         const u = await api('GET', '/update').catch(() => null);
         form.updateCheck.checked = u?.check !== false;
+        service = await api('GET', '/service').catch(() => null);
+        $('#settings-service').hidden = !service?.supported;
+        form.startAtLogin.checked = Boolean(service?.installed);
+        $('#settings-service-state').textContent = service?.installed ? (service.loaded ? 'On: the login service is loaded.' : 'On; loads at the next login.') : 'Off now.';
       }
       dialog.showModal();
     } catch (err) {
@@ -79,6 +85,11 @@ export function initMenu({ api, esc, toast, $ }) {
     try {
       const c = await api('PUT', '/cleanup', { maxRunning: form.maxRunning.value.trim() || null });
       if (!remote()) await api('PUT', '/update', { check: form.updateCheck.checked }).catch(() => {});
+      // Only when it changed: installing touches launchd / systemd.
+      if (!remote() && service?.supported && form.startAtLogin.checked !== Boolean(service.installed)) {
+        const s = await api('PUT', '/service', { enabled: form.startAtLogin.checked });
+        toast(s.installed ? `Starts at login from now on${s.note ? `. ${s.note}` : ''}` : 'No longer starts at login', 6000);
+      }
       dialog.close();
       toast(c.maxRunning ? `At most ${c.maxRunning} agents open; the ones idle longest close above that` : 'No limit on open agents');
     } catch (err) {

package/public/review.js

@@ -1,5 +1,7 @@
 // Review screen: an agent's changes file by file, line comments sent back to the agent as one
 // message, and Commit / Push & open PR. Comments not sent yet are kept per agent in this browser.
+// With a walkthrough, each hunk shows its explanation and ◀ / ▶ step through them in reading order.
+import { cardHtml, explainButton, stepOf, walkthroughOf } from './walkthrough.js';
 
 /** Unified diff -> [{ path, status, binary, hunks: [{ head, lines: [{ t, old, new, text }] }] }] */
 export function parseDiff(text) {
@@ -56,7 +58,8 @@ const BIG = 600; // files with more changed lines start collapsed
 export function initReview({ api, esc, toast, agents, $ }) {
   const dlg = $('#review-dialog');
   const body = $('#review-body');
-  const st = { id: null, data: null, files: [], comments: [], collapsed: new Set(), editing: null, loading: false };
+  const st = { id: null, data: null, files: [], comments: [], collapsed: new Set(), editing: null, loading: false, step: null };
+  const walk = () => walkthroughOf(agents.get(st.id), st.data?.diffHash);
 
   const key = (id) => `agentmgr.review.${id}`;
   const loadDrafts = (id) => {
@@ -80,6 +83,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
     st.collapsed = new Set();
     st.editing = null;
     st.data = null;
+    st.step = null;
     $('#review-title').textContent = `Review: ${agents.get(id)?.name ?? ''}`;
     body.innerHTML = '<p class="hint">Loading changes…</p>';
     if (!dlg.open) dlg.showModal();
@@ -129,7 +133,10 @@ export function initReview({ api, esc, toast, agents, $ }) {
     if (collapsed) return `<div class="rv-file" id="rv-${encodeURIComponent(f.path)}">${head}</div>`;
     if (f.binary) return `<div class="rv-file" id="rv-${encodeURIComponent(f.path)}">${head}<p class="hint rv-pad">Binary file</p></div>`;
     const rows = [];
+    const w = walk();
     for (const h of f.hunks) {
+      const i = w.doc ? stepOf(w.doc, f.path, h.head) : -1;
+      if (i >= 0) rows.push(`<tr class="rv-explain ${st.step === i ? 'current' : ''}" id="rv-step-${i}"><td colspan="3">${cardHtml(w.doc.data.changes[i], i, w.doc.data.changes.length, esc)}</td></tr>`);
       rows.push(`<tr class="rv-hunk"><td colspan="3">${esc(h.head)}</td></tr>`);
       for (const l of h.lines) {
         const side = l.t === 'del' ? 'old' : 'new';
@@ -149,6 +156,48 @@ export function initReview({ api, esc, toast, agents, $ }) {
     return `<div class="rv-file" id="rv-${encodeURIComponent(f.path)}">${head}<table class="rv-table">${rows.join('')}</table></div>`;
   }
 
+  /** Explain changes, then ◀ n of N ▶ once there is a walkthrough. */
+  function walkNav() {
+    const w = walk();
+    const n = w.doc?.data.changes.length ?? 0;
+    const nav = n
+      ? `<span class="rv-walk"><button type="button" class="small ghost" data-rv-step="-1" title="Previous change ([)">◀</button><span class="hint">${st.step == null ? `${n} changes` : `${st.step + 1} of ${n}`}</span><button type="button" class="small ghost" data-rv-step="1" title="Next change (])">▶</button></span>`
+      : '';
+    return `${nav}${explainButton(w, 'data-rv-explain')}`;
+  }
+
+  function walkNote() {
+    const w = walk();
+    if (w.error && !w.pending) return `<p class="error rv-pad">Couldn't explain the changes: ${esc(w.error)}</p>`;
+    if (!w.doc) return '';
+    const notes = [esc(w.doc.data.summary)];
+    if (w.stale) notes.push('<b>The changes moved since this was written</b>; explanations for hunks that changed are missing. Explain again for the latest.');
+    if (w.doc.cut) notes.push('The diff was too long to explain all of it; the rest has no explanation.');
+    return `<p class="hint rv-walk-note">${notes.join(' ')}</p>`;
+  }
+
+  /** Explanations whose hunk is still in the diff (after more edits, some may be gone). */
+  const present = (w) => (w.doc?.data.changes ?? []).map((c, i) => (st.files.some((f) => f.path === c.file && f.hunks.some((h) => h.head === c.head)) ? i : -1)).filter((i) => i >= 0);
+
+  /** Step `dir` (+1 / -1) from the current explanation: open its file, mark it and scroll to it. */
+  function step(dir) {
+    const w = walk();
+    const ok = present(w);
+    if (!ok.length) return toast('These explanations no longer match the changes; Explain again');
+    const at = st.step == null ? -1 : ok.indexOf(st.step);
+    const next = at < 0 ? (dir > 0 ? ok[0] : ok.at(-1)) : ok[(at + dir + ok.length) % ok.length];
+    gotoStep(next);
+  }
+
+  function gotoStep(i) {
+    const w = walk();
+    st.step = i;
+    st.collapsed.delete(w.doc.data.changes[st.step].file);
+    keepInputs();
+    render();
+    body.querySelector(`#rv-step-${st.step}`)?.scrollIntoView({ block: 'center', behavior: 'smooth' });
+  }
+
   function render() {
     const d = st.data;
     if (!d) return;
@@ -168,8 +217,10 @@ export function initReview({ api, esc, toast, agents, $ }) {
         ${d.unpushed ? `<span class="tag">${d.unpushed} not pushed</span>` : ''}
         ${openPr ? `<a href="${esc(openPr.url)}" target="_blank" rel="noopener">PR #${esc(openPr.number ?? '')}</a>` : ''}
         <span class="spacer"></span>
+        ${d.files.length ? walkNav() : ''}
         <button type="button" class="small ghost" data-rv-reload>${st.loading ? 'Loading…' : 'Reload'}</button>
       </div>
+      ${walkNote()}
       ${d.busy ? '<p class="hint rv-warn">The agent is working, so the changes may still move. Reload when it is idle.</p>' : ''}
       ${d.truncated ? '<p class="hint rv-warn">The diff is large and was cut short; open a shell for the rest.</p>' : ''}
       <div class="rv-main">
@@ -235,6 +286,20 @@ export function initReview({ api, esc, toast, agents, $ }) {
   body.addEventListener('click', async (e) => {
     const t = e.target;
     if (t.closest('[data-rv-reload]')) return keepInputs(), reload();
+    const stepBtn = t.closest('[data-rv-step]');
+    if (stepBtn) return step(Number(stepBtn.dataset.rvStep));
+    if (t.closest('[data-rv-explain]')) {
+      keepInputs();
+      try {
+        // In the background: the agent's record says when it's done (agentChanged re-renders).
+        agents.set(st.id, await api('POST', `/agents/${st.id}/docs/walkthrough?background=1`));
+        st.step = null;
+        render();
+      } catch (err) {
+        toast(`Error: ${err.message}`, 5000);
+      }
+      return;
+    }
     const go = t.closest('[data-rv-goto]');
     if (go) {
       e.preventDefault();
@@ -339,6 +404,13 @@ export function initReview({ api, esc, toast, agents, $ }) {
     }
   });
 
+  // [ and ] step through the explained changes (not while typing).
+  dlg.addEventListener('keydown', (e) => {
+    if ((e.key !== '[' && e.key !== ']') || e.target.closest?.('textarea, input') || !walk().doc) return;
+    e.preventDefault();
+    step(e.key === ']' ? 1 : -1);
+  });
+
   body.addEventListener('keydown', (e) => {
     const form = e.target.closest?.('.rv-form');
     if (form && e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
@@ -364,5 +436,16 @@ export function initReview({ api, esc, toast, agents, $ }) {
     st.note = st.msg = st.prTitle = '';
   });
 
-  return { open, get openId() { return dlg.open ? st.id : null; } };
+  /** The agent changed (its walkthrough finished, say): redraw if it's the one under review. */
+  function agentChanged(a) {
+    if (!dlg.open || a.id !== st.id || !st.data) return;
+    const w = a.docs?.walkthrough;
+    const sig = `${w?.at}|${w?.pending}|${w?.error}`;
+    if (sig === st.walkSig) return;
+    st.walkSig = sig;
+    keepInputs();
+    render();
+  }
+
+  return { open, agentChanged, get openId() { return dlg.open ? st.id : null; } };
 }

package/public/setup.js

@@ -3,6 +3,7 @@
 
 const STEPS = [
   ['agent', 'Start your first agent', 'Give it a request and a repo or folder; it works in its own branch.', '#new-btn', 'New agents'],
+  ['service', 'Start at login', 'So AI Agent Manager and your agents come back by themselves after a restart.', '#settings-btn', 'Settings'],
   ['alerts', 'Get Slack alerts', 'Hear when an agent needs you, is stuck or finished.', '#alerts-btn', 'Alerts'],
   ['assistant', 'Let work come to you', 'The assistant, or triggers (a GitHub label, a webhook), start agents for new work.', '#assistant-btn', 'Assistant'],
   ['remote', 'Use it from your phone', 'Answer agents from anywhere on your network.', '#remote-btn', 'Remote access'],

package/public/side.js

@@ -0,0 +1,191 @@
+// The split view: the terminal (Claude, a shell or a browser tab) stays on the left, and the right
+// pane shows the same agent's Code, its Docs (Diagrams by default) or its Changes explained one by
+// one. On, the tab and the document are remembered in this browser.
+import { parseDiff } from '/review.js';
+import { cardHtml, explainButton, walkthroughOf } from '/walkthrough.js';
+
+const DOCS = [
+  ['diagrams', 'Diagrams'],
+  ['design', 'Design'],
+  ['flow', 'Flow'],
+  ['analysis', 'Analysis'],
+  ['proposal', 'Proposal'],
+  ['explain', 'Explain'],
+];
+const pref = {
+  get: (k, d) => {
+    try {
+      return localStorage.getItem(`agentmgr.side.${k}`) ?? d;
+    } catch {
+      return d;
+    }
+  },
+  set: (k, v) => {
+    try {
+      localStorage.setItem(`agentmgr.side.${k}`, v);
+    } catch {}
+  },
+};
+
+export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDiagrams, mainKind, setMain, refit }) {
+  const pane = $('#side-pane');
+  const body = $('#side-body');
+  const code = $('#code');
+  const codeHome = $('#term-main');
+  const st = { on: pref.get('on', '0') === '1', tab: pref.get('tab', 'docs'), doc: pref.get('doc', 'diagrams'), agentId: null, changes: null, sig: '', loading: false };
+
+  const docOf = (a, kind) => (kind === 'explain' ? a?.explanation : a?.docs?.[kind]);
+
+  function show() {
+    const on = st.on && Boolean(st.agentId);
+    pane.hidden = !on;
+    $('#split-pane').hidden = !on;
+    $('#term-split-btn').classList.toggle('on', on);
+    for (const t of pane.querySelectorAll('[data-side]')) t.classList.toggle('active', t.dataset.side === st.tab);
+    // Code lives in one place at a time: here when this tab shows it, else back in the main panel.
+    const want = on && st.tab === 'code' ? body : codeHome;
+    if (code.parentElement !== want) want === body ? body.replaceChildren(code) : codeHome.insertBefore(code, $('#browser'));
+    pane.classList.toggle('with-code', on && st.tab === 'code');
+    if (!on) return refit();
+    if (st.tab === 'code') codeUi.open(st.agentId);
+    else if (st.tab === 'docs') renderDocs(true);
+    else renderChanges(true);
+    refit();
+  }
+
+  // ------------------------------------------------------------ Docs
+  function renderDocs(force) {
+    const a = agents.get(st.agentId);
+    const d = docOf(a, st.doc);
+    const sig = `docs|${st.agentId}|${st.doc}|${d?.at}|${d?.pending}|${d?.error}`;
+    if (!force && sig === st.sig) return;
+    st.sig = sig;
+    const label = DOCS.find(([k]) => k === st.doc)?.[1] ?? st.doc;
+    const picker = `<select data-side-doc>${DOCS.map(([k, l]) => `<option value="${k}" ${k === st.doc ? 'selected' : ''}>${l}${docOf(a, k)?.markdown ? ' ✓' : ''}</option>`).join('')}</select>`;
+    const stale = d?.markdown && a?.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
+    const action = d?.pending
+      ? `<span class="hint">Writing…</span>`
+      : `<button type="button" class="small ${d?.markdown ? 'ghost' : 'primary'}" data-side-write>${d?.markdown ? 'Again' : st.doc === 'diagrams' ? 'Draw' : 'Write'}</button>`;
+    let content;
+    if (d?.pending && !d?.markdown) content = `<p class="hint">Writing the ${esc(label.toLowerCase())} from the agent's work so far…</p>`;
+    else if (d?.error && !d?.markdown) content = `<p class="error">Couldn't write it: ${esc(d.error)}</p>`;
+    else if (d?.markdown) content = `<div class="md ${st.doc === 'diagrams' ? 'diagrams-view' : ''}">${docHtml(d.markdown)}</div>`;
+    else content = `<p class="hint">No ${esc(label.toLowerCase())} for this agent yet.</p>`;
+    body.innerHTML = `<div class="side-tools">${picker}<span class="spacer"></span>${stale ? '<span class="hint">brief changed since</span>' : ''}${action}</div><div class="side-scroll">${content}</div>`;
+    renderDiagrams(body);
+  }
+
+  // ------------------------------------------------------------ Changes
+  async function loadChanges() {
+    st.loading = true;
+    try {
+      const data = await api('GET', `/agents/${st.agentId}/changes`);
+      st.changes = { id: st.agentId, diffHash: data.diffHash, files: parseDiff(data.diff) };
+    } catch (err) {
+      st.changes = { id: st.agentId, error: err.message };
+    }
+    st.loading = false;
+    renderChanges(true);
+  }
+
+  function hunkHtml(file, head) {
+    const h = st.changes?.files?.find((f) => f.path === file)?.hunks.find((x) => x.head === head);
+    if (!h) return '<p class="hint">This hunk has changed since; Explain again for the latest.</p>';
+    const lines = h.lines.slice(0, 40).map((l) => `<div class="sd-${l.t}">${l.t === 'add' ? '+' : l.t === 'del' ? '−' : ' '}${esc(l.text)}</div>`);
+    if (h.lines.length > 40) lines.push(`<div class="hint">… ${h.lines.length - 40} more lines (Review changes shows all)</div>`);
+    return `<div class="sd-hunk"><div class="sd-head">${esc(head)}</div>${lines.join('')}</div>`;
+  }
+
+  function renderChanges(force) {
+    if (!st.changes || st.changes.id !== st.agentId) {
+      body.innerHTML = '<p class="hint side-pad">Loading the changes…</p>';
+      if (!st.loading) loadChanges();
+      return;
+    }
+    const a = agents.get(st.agentId);
+    const w = walkthroughOf(a, st.changes.diffHash);
+    const sig = `changes|${st.agentId}|${a?.docs?.walkthrough?.at}|${w.pending}|${w.error}|${st.changes.diffHash}`;
+    if (!force && sig === st.sig) return;
+    st.sig = sig;
+    const tools = `<div class="side-tools">${explainButton(w, 'data-side-explain')}<span class="spacer"></span><button type="button" class="small ghost" data-side-reload title="Load the changes again">⟳</button></div>`;
+    let content;
+    if (st.changes.error) content = `<p class="error">${esc(st.changes.error)}</p>`;
+    else if (!st.changes.files.length) content = '<p class="hint">No changes yet.</p>';
+    else if (!w.doc) content = `${w.error && !w.pending ? `<p class="error">Couldn't explain them: ${esc(w.error)}</p>` : ''}<p class="hint">${st.changes.files.length} file${st.changes.files.length === 1 ? '' : 's'} changed. <b>Explain changes</b> goes through them one by one: what, why, the risk and what to check.</p>`;
+    else {
+      const list = w.doc.data.changes;
+      content = `<p class="hint">${esc(w.doc.data.summary)}${w.stale ? ' <b>The changes moved since this was written.</b>' : ''}</p>${list
+        .map((c, i) => `<section class="sd-step"><div class="sd-file"><code>${esc(c.file)}</code></div>${cardHtml(c, i, list.length, esc)}${hunkHtml(c.file, c.head)}</section>`)
+        .join('')}`;
+    }
+    body.innerHTML = `${tools}<div class="side-scroll">${content}</div>`;
+  }
+
+  // ------------------------------------------------------------ events
+  pane.addEventListener('click', async (e) => {
+    const tab = e.target.closest('[data-side]');
+    if (tab) return setTab(tab.dataset.side);
+    if (e.target.closest('#side-close')) return toggle(false);
+    if (e.target.closest('[data-side-reload]')) return loadChanges();
+    try {
+      if (e.target.closest('[data-side-explain]')) {
+        agents.set(st.agentId, await api('POST', `/agents/${st.agentId}/docs/walkthrough?background=1`));
+        return renderChanges(true);
+      }
+      if (e.target.closest('[data-side-write]')) {
+        const route = st.doc === 'explain' ? `/agents/${st.agentId}/explain?background=1` : `/agents/${st.agentId}/docs/${st.doc}?background=1`;
+        agents.set(st.agentId, await api('POST', route));
+        return renderDocs(true);
+      }
+    } catch (err) {
+      toast(`Error: ${err.message}`, 5000);
+    }
+  });
+  pane.addEventListener('change', (e) => {
+    if (!e.target.matches('[data-side-doc]')) return;
+    st.doc = e.target.value;
+    pref.set('doc', st.doc);
+    renderDocs(true);
+  });
+
+  function setTab(tab) {
+    st.tab = tab;
+    pref.set('tab', tab);
+    // Code can't be on both sides: the main panel goes back to the agent's session.
+    if (tab === 'code' && mainKind() === 'code') setMain('claude');
+    show();
+  }
+
+  function toggle(on = !st.on) {
+    st.on = on;
+    pref.set('on', on ? '1' : '0');
+    if (on && st.tab === 'code' && mainKind() === 'code') st.tab = 'docs';
+    show();
+  }
+
+  $('#term-split-btn').onclick = () => toggle();
+
+  return {
+    /** The terminal now shows this agent (or none): follow it. */
+    follow(id) {
+      if (id === st.agentId) return;
+      st.agentId = id ?? null;
+      st.changes = null;
+      st.sig = '';
+      show();
+    },
+    /** The main panel is about to show Code: move this pane off it. */
+    mainShowsCode() {
+      if (st.on && st.tab === 'code') {
+        st.tab = 'docs';
+        show();
+      }
+    },
+    showing: (tab) => st.on && Boolean(st.agentId) && st.tab === tab,
+    agentChanged(a) {
+      if (!st.on || a.id !== st.agentId) return;
+      if (st.tab === 'docs') renderDocs(false);
+      else if (st.tab === 'changes') renderChanges(false);
+    },
+  };
+}

package/public/style.css

@@ -829,3 +829,47 @@ input.inline { display: inline-block; width: 80px; padding: 1px 4px; }
 .sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
 .hint.warn { display: block; margin-top: 4px; color: var(--yellow); }
 .hint.warn[hidden] { display: none; }
+
+/* Attachments in New agents and Ask: a button, then a chip per file. */
+.attach-box { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; margin: -4px 0 10px; }
+.attach-chips { display: contents; }
+.attach-chip { display: inline-flex; align-items: center; gap: 6px; padding: 2px 4px 2px 8px; border: 1px solid var(--border); border-radius: 999px; background: var(--panel-2); font-size: 12px; max-width: 100%; }
+.attach-chip.fail { border-color: var(--red); }
+.attach-chip .link { padding: 0 4px; }
+form.dropping { outline: 2px dashed var(--accent, #6b8cff); outline-offset: 4px; }
+
+/* Walkthrough: an explanation card above each hunk; the current one is marked. */
+.wt-card { display: flex; flex-direction: column; gap: 3px; padding: 8px 10px; font: 13px/1.45 var(--sans, system-ui); white-space: normal; color: var(--text); }
+.wt-head { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.wt-n { font: 11px var(--mono, ui-monospace); color: var(--muted); }
+.wt-k { display: inline-block; min-width: 44px; font-size: 11px; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); }
+.rv-explain td { background: var(--panel); border-top: 1px solid var(--border); }
+.rv-explain.current td { box-shadow: inset 3px 0 0 var(--accent, #6b8cff); background: var(--panel-2); }
+.rv-walk { display: inline-flex; align-items: center; gap: 4px; }
+.rv-walk-note { margin: 4px 12px 8px; }
+
+/* Split view: the terminal (or a browser tab, or Code) on the left, a pane on the right. */
+.term-split { flex: 1; display: flex; min-height: 0; min-width: 0; }
+.term-main { flex: 1; display: flex; flex-direction: column; min-width: 0; min-height: 0; }
+.split-pane { flex: none; width: 0; }
+.split-pane::after { top: 0; bottom: 0; left: -4px; width: 8px; cursor: col-resize; }
+.split-pane[hidden], .side-pane[hidden] { display: none !important; }
+.side-pane { flex: none; width: var(--pane-w, 45%); display: flex; flex-direction: column; min-height: 0; border-left: 1px solid #30363d; background: var(--bg); color: var(--text); }
+.side-bar { display: flex; align-items: center; gap: 6px; padding: 4px 8px; background: #161a22; color: #c9d1d9; font-size: 12.5px; }
+.side-bar button { color: #c9d1d9; border-color: #30363d; }
+.side-body { flex: 1; display: flex; flex-direction: column; min-height: 0; }
+.side-pane .code { display: flex; flex: 1; }
+.side-tools { display: flex; align-items: center; gap: 8px; padding: 6px 10px; border-bottom: 1px solid var(--border); }
+.side-tools select { width: auto; }
+.side-scroll { flex: 1; overflow: auto; padding: 10px 12px; }
+.side-pad { padding: 10px 12px; }
+.side-scroll .diagrams-view .diagram, .side-scroll .diagram { display: flex; justify-content: center; overflow-x: auto; }
+.side-scroll .diagram svg { max-width: 100%; height: auto; }
+.sd-step { margin-bottom: 14px; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
+.sd-file { padding: 4px 10px; background: var(--panel-2); font-size: 12px; }
+.sd-hunk { font: 12px/1.45 var(--mono, ui-monospace, monospace); white-space: pre; overflow-x: auto; border-top: 1px solid var(--border); }
+.sd-hunk > div { padding: 0 10px; }
+.sd-head { color: var(--muted); background: var(--panel); }
+.sd-add { background: rgba(46, 160, 67, .15); }
+.sd-del { background: rgba(248, 81, 73, .15); }
+#term-split-btn.on { background: #262c38; }

package/public/walkthrough.js

@@ -0,0 +1,36 @@
+// An agent's changes explained one by one (the "walkthrough" document): shared by the review
+// screen, which shows each explanation above its hunk, and the Changes pane of the split view.
+
+const RISK = { high: 'fail', medium: '', low: 'open' };
+
+/** The walkthrough of an agent and whether it still matches the changes (diffHash from /changes). */
+export function walkthroughOf(agent, diffHash) {
+  const w = agent?.docs?.walkthrough;
+  return {
+    doc: w?.data ? w : null,
+    pending: Boolean(w?.pending),
+    error: w?.error ?? null,
+    stale: Boolean(w?.data && diffHash && w.diffHash !== diffHash),
+  };
+}
+
+/** Index of the explanation for a hunk (file + header), or -1. */
+export const stepOf = (doc, file, head) => doc?.data.changes.findIndex((c) => c.file === file && c.head === head) ?? -1;
+
+/** One explanation: title, risk, what / why / check. */
+export function cardHtml(c, i, total, esc) {
+  if (c.unexplained) return `<div class="wt-card"><div class="wt-head"><span class="wt-n">${i + 1}/${total}</span><span class="hint">Not explained (the model skipped it)</span></div></div>`;
+  return `<div class="wt-card">
+    <div class="wt-head"><span class="wt-n">${i + 1}/${total}</span><b>${esc(c.title)}</b><span class="tag ${RISK[c.risk] ?? ''}">${esc(c.risk)} risk</span></div>
+    ${c.what ? `<div><span class="wt-k">What</span> ${esc(c.what)}</div>` : ''}
+    ${c.why ? `<div><span class="wt-k">Why</span> ${esc(c.why)}</div>` : ''}
+    ${c.check ? `<div><span class="wt-k">Check</span> ${esc(c.check)}</div>` : ''}
+  </div>`;
+}
+
+/** The button that writes (or rewrites) the walkthrough, with its state. */
+export function explainButton(w, attrs = 'data-wt-explain') {
+  const label = w.pending ? 'Explaining…' : w.doc ? (w.stale ? 'Explain again (changed)' : 'Explain again') : '✨ Explain changes';
+  return `<button type="button" class="small ${w.doc && !w.stale ? 'ghost' : 'primary'}" ${attrs} ${w.pending ? 'disabled' : ''}
+    title="Explain each change one by one: what, why, the risk and what to check, in the order to read them (a separate one-off call; the agent isn't interrupted)">${label}</button>`;
+}

package/src/backlog.js

@@ -89,7 +89,7 @@ export class Backlog extends EventEmitter {
   // ------------------------------------------------------------ editing
 
   /** Queue one item per title. Options are what an agent would take (repo, dir, base, project, ...). */
-  add(titles, { repo, dir, base, project, worktree, permissionMode, model, plan, planReview, engine, priority = 2 } = {}) {
+  add(titles, { repo, dir, base, project, worktree, permissionMode, model, plan, planReview, engine, attachments, priority = 2 } = {}) {
     const list = titles.map((t) => String(t ?? '').trim()).filter(Boolean);
     if (!list.length) throw err(400, 'At least one item is required');
     const pr = parsePriority(priority);
@@ -120,6 +120,8 @@ export class Backlog extends EventEmitter {
         permissionMode: permissionMode || null,
         model: model || null,
         engine: engine || null,
+        // Staged uploads; each item's agent gets its own copies when it starts.
+        attachments: Array.isArray(attachments) && attachments.length ? attachments.slice(0, 20).map(String) : undefined,
         plan: Boolean(plan),
         planReview: planReview ?? null,
         priority: pr,
@@ -219,6 +221,7 @@ export class Backlog extends EventEmitter {
       permissionMode: it.permissionMode,
       model: it.model,
       engine: it.engine ?? undefined,
+      attachments: it.attachments,
       plan: it.plan,
       planReview: it.planReview ?? undefined,
       priority: it.priority,

package/src/brief.js

@@ -411,6 +411,81 @@ export function diagramsOnly(markdown) {
     .trim();
 }
 
+// ------------------------------------------------------------------ Change walkthrough
+
+/**
+ * The agent's changes explained one by one, for review: each hunk of its diff gets a title, what
+ * changed, why, a risk and what to check, in the order a reviewer should read them.
+ * `hunks`: [{ id, file, head, text }].
+ */
+export function walkthroughPrompt({ intent, status, digest, briefMarkdown, hunks }) {
+  return [
+    "You help a person review an AI coding agent's changes, one change at a time.",
+    'Below are its changes as numbered hunks (H1, H2, ...), with the request and its conversation for the reasons behind them.',
+    '',
+    'Reply with one JSON object only, no prose around it:',
+    '{"summary": "<two sentences: what the changes do overall>", "changes": [{"id": "H3", "title": "<under 10 words>", "what": "<what this hunk changes, concretely>", "why": "<why, from the request or conversation; \"Not stated\" if unknown>", "risk": "low|medium|high", "check": "<what the reviewer should verify here>"}]}',
+    '',
+    'Rules:',
+    '- One entry per hunk, every hunk exactly once. Order them the way a reviewer should read them: the core change first, then what depends on it, then tests, docs and small edits.',
+    '- Be specific: name the functions, values and behavior. Base it only on the hunks and the context; do not invent intent.',
+    '- risk is high for security, data loss, concurrency, money or public API changes; medium for behavior changes; low for refactors, tests, docs and formatting.',
+    '- Keep what, why and check to one or two sentences each.',
+    '',
+    ...contextBlock({ intent, status, digest, repo: '', briefMarkdown }),
+    '<hunks>',
+    ...hunks.map((h) => `<hunk id="${h.id}" file="${h.file}">\n${h.head}\n${h.text}\n</hunk>`),
+    '</hunks>',
+  ].join('\n');
+}
+
+/** The hunks a walkthrough explains, from a parsed diff: ids, and the text sent (capped). */
+export function walkthroughHunks(files, { maxLines = 80, maxChars = 60_000 } = {}) {
+  const out = [];
+  let used = 0;
+  for (const f of files) {
+    if (f.binary) continue;
+    for (const h of f.hunks) {
+      const lines = h.lines.map((l) => `${l.t === 'add' ? '+' : l.t === 'del' ? '-' : ' '}${l.text}`);
+      const text = lines.length > maxLines ? [...lines.slice(0, maxLines), `… (${lines.length - maxLines} more lines)`].join('\n') : lines.join('\n');
+      if (used + text.length > maxChars) return { hunks: out, cut: true };
+      used += text.length;
+      out.push({ id: `H${out.length + 1}`, file: f.path, head: h.head, text });
+    }
+  }
+  return { hunks: out, cut: false };
+}
+
+/** The model's reply mapped back to hunks (file + header), in its reading order; unknown ids dropped. */
+export function walkthroughFrom(reply, hunks) {
+  const byId = new Map(hunks.map((h) => [h.id, h]));
+  const seen = new Set();
+  const risk = (r) => (['low', 'medium', 'high'].includes(r) ? r : 'medium');
+  const changes = [];
+  for (const c of Array.isArray(reply?.changes) ? reply.changes : []) {
+    const h = byId.get(String(c?.id ?? '').trim());
+    if (!h || seen.has(h.id)) continue;
+    seen.add(h.id);
+    changes.push({ file: h.file, head: h.head, title: String(c.title ?? '').slice(0, 120), what: String(c.what ?? '').slice(0, 800), why: String(c.why ?? '').slice(0, 800), risk: risk(c.risk), check: String(c.check ?? '').slice(0, 600) });
+  }
+  // Hunks the model skipped still get a place (unexplained), so stepping through covers everything.
+  for (const h of hunks) if (!seen.has(h.id)) changes.push({ file: h.file, head: h.head, title: '', what: '', why: '', risk: 'low', check: '', unexplained: true });
+  return { summary: String(reply?.summary ?? '').slice(0, 600), changes };
+}
+
+/** Markdown version, for Copy / Download and the CLI. */
+export function walkthroughMarkdown({ summary, changes }, title = '') {
+  const out = [`# Changes explained${title ? `: ${title}` : ''}`, '', summary, ''];
+  changes.forEach((c, i) => {
+    out.push(`## ${i + 1}. ${c.title || '(not explained)'}`, '', `\`${c.file}\` · \`${c.head.replace(/^(@@[^@]*@@).*/, '$1')}\` · risk: ${c.risk}`, '');
+    if (c.what) out.push(`- **What:** ${c.what}`);
+    if (c.why) out.push(`- **Why:** ${c.why}`);
+    if (c.check) out.push(`- **Check:** ${c.check}`);
+    out.push('');
+  });
+  return out.join('\n').trim() + '\n';
+}
+
 // ------------------------------------------------------------------ Human vs AI
 
 export const contextBlock = ({ intent, status, digest, repo, briefMarkdown }) => [