ai-agentmanager 1.4.0 → 1.6.0

package/public/index.html

@@ -25,7 +25,7 @@
         <button id="assistant-btn" title="An always-on session that finds new work and starts agents for it">Assistant <span id="assistant-dot" class="assistant-dot" hidden></span></button>
         <button id="spend-btn" title="Results across agents (merge rate, time to PR, cost per merged PR), what they cost, and spending limits">Results <span id="spend-today" class="spend-today"></span></button>
         <button id="machine-btn" title="A terminal on this computer (your home folder), from any device you're signed in on">Terminal</button>
-        <button id="ask-btn" title="A general Claude session with no repo or folder">Ask Claude</button>
+        <button id="ask-btn" title="A general session with no repo or folder, on Claude Code or another engine you have (Codex, Muse Code, …)">Ask Agent</button>
         <button id="new-btn" class="primary">+ New agents</button>
         <div class="menu-wrap">
           <button id="menu-btn" class="menu-btn" type="button" aria-haspopup="menu" aria-expanded="false" title="Settings and preferences">
@@ -163,10 +163,17 @@
     <dialog id="new-dialog">
       <form id="new-form" method="dialog">
         <h2>New agents</h2>
+        <div class="row intent-split">
+          <span>What to do</span>
+          <label class="check" title="Each line starts its own agent: a list of tickets or small tasks"><input type="radio" name="split" value="lines" checked /> One agent per line</label>
+          <label class="check" title="The whole text goes to one agent: a long description, a spec, pasted notes"><input type="radio" name="split" value="one" /> One agent for all of it</label>
+          <span class="spacer"></span><span class="hint" id="intent-count"></span>
+        </div>
         <label>
-          Intents <span class="hint">one per line; each gets its own agent</span>
+          <span class="sr-only">Intents</span>
           <textarea name="intents" rows="6" required placeholder="Add a dark mode toggle that remembers the user's choice&#10;Make search results show up as you type&#10;Find out why the dashboard takes 5 seconds to load and speed it up&#10;Add a one-click CSV export to the reports page"></textarea>
         </label>
+        <div id="new-attach"></div>
         <div class="row">
           <label>
             Git repository URL
@@ -195,6 +202,7 @@
           <label id="engine-field" hidden>
             Engine
             <select name="engine"><option value="">Claude Code</option></select>
+            <span class="hint warn" id="engine-notice" hidden></span>
           </label>
         </div>
         <label>
@@ -300,16 +308,24 @@
 
     <dialog id="ask-dialog">
       <form id="ask-form" method="dialog">
-        <h2>Ask Claude</h2>
+        <h2>Ask an agent</h2>
         <p class="hint">A general session with no repo or folder. It is tracked and resumable like any other agent.</p>
         <label>
           Question <span class="hint">optional; you can also just type in the terminal</span>
           <textarea name="question" rows="4" placeholder="How do I tune GC for a JVM with a 32 GB heap?"></textarea>
         </label>
-        <label>
-          Name <span class="hint">optional</span>
-          <input name="name" placeholder="jvm-gc-questions" />
-        </label>
+        <div id="ask-attach"></div>
+        <div class="row">
+          <label>
+            Name <span class="hint">optional</span>
+            <input name="name" placeholder="jvm-gc-questions" />
+          </label>
+          <label id="ask-engine-field">
+            Engine
+            <select name="engine"><option value="">Claude Code</option></select>
+            <span class="hint warn" id="ask-engine-notice" hidden></span>
+          </label>
+        </div>
         <p id="ask-error" class="error" hidden></p>
         <div class="dialog-actions">
           <button type="button" id="ask-cancel" class="ghost">Cancel</button>
@@ -672,6 +688,11 @@
           <label class="check">Keep at most <input type="number" name="maxRunning" min="1" max="500" placeholder="no limit" class="num" /> agents open at once</label>
           <p class="hint">Above it, the agents idle longest are closed (they resume when you open them), so the machine stays responsive. Never closed: agents working, waiting for your answer, active in the last 5 minutes, marked Keep, or in a team that is still going. <span id="settings-running"></span></p>
         </fieldset>
+        <fieldset class="local-only" id="settings-service">
+          <legend>Start at login</legend>
+          <label class="check"><input type="checkbox" name="startAtLogin" /> Start AI Agent Manager when I log in</label>
+          <p class="hint">After a restart or a crash, the daemon comes back by itself and running agents resume; without it, it starts only when you run <code>agentmgr</code>. <span id="settings-service-state"></span></p>
+        </fieldset>
         <fieldset class="local-only">
           <legend>Updates</legend>
           <label class="check"><input type="checkbox" name="updateCheck" /> Check for a new release twice a day</label>

package/public/machine.js

@@ -8,6 +8,7 @@ const MACHINE = '__machine__';
 export function initMachine({ api, esc, toast, $, Terminal, FitAddon }) {
   const dialog = $('#machine-dialog');
   let xterm = null;
+  let replaying = false; // writing the backlog (see onData)
   let fit = null;
   let conn = null;
   let current = null;
@@ -19,7 +20,8 @@ export function initMachine({ api, esc, toast, $, Terminal, FitAddon }) {
     fit = new FitAddon();
     xterm.loadAddon(fit);
     xterm.open($('#machine-term'));
-    xterm.onData((d) => conn?.send({ t: 'i', d }));
+    // Answers xterm gives to queries in the replayed backlog are stale; don't send them as typing.
+    xterm.onData((d) => !replaying && conn?.send({ t: 'i', d }));
     xterm.onResize(({ cols, rows }) => conn?.send({ t: 'r', cols, rows }));
     new ResizeObserver(() => dialog.open && fit.fit()).observe($('#machine-term'));
   }
@@ -45,12 +47,16 @@ export function initMachine({ api, esc, toast, $, Terminal, FitAddon }) {
           xterm.focus();
         },
         onMessage: (msg) => {
-          if (msg.t === 'hello' && msg.backlog) xterm.write(msg.backlog);
+          if (msg.t === 'hello' && msg.backlog) {
+            replaying = true;
+            xterm.write(msg.backlog, () => (replaying = false));
+          }
           else if (msg.t === 'o') xterm.write(msg.d);
           else if (msg.t === 'exit') xterm.write('\r\n\x1b[2m[terminal ended; reopen it with + Terminal]\x1b[0m\r\n');
           else if (msg.t === 'error') xterm.write(`\r\n\x1b[31m${msg.error}\x1b[0m\r\n`);
         },
         onClose: ({ reason }) => reason && xterm.write(`\r\n\x1b[2m[${reason}]\x1b[0m\r\n`),
+        onInputLost: () => xterm.write('\r\n\x1b[33m[some typing did not reach the computer (connection lost); check before going on]\x1b[0m\r\n'),
       },
     );
     xterm.focus();

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/setup.js

@@ -1,14 +1,30 @@
-// Getting started: shown where an agent's details go while none is selected, until every step
-// is done or it is hidden. Steps open the dialog that does them.
+// The home page, where an agent's details go while none is selected: Getting started until every
+// step is done or it is hidden (steps open the dialog that does them), then what the app can do.
 
 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'],
   ['budget', 'Set a budget', 'An alert at 80% of an agent budget, and a daily limit.', '#spend-btn', 'Results'],
 ];
 
+// What the app can do, each with where to find it: a button to click, a sidebar tab, or a link.
+const FEATURES = [
+  ['Agents side by side', 'Each works on its own branch in its own folder; the list shows which need you.', { btn: '#new-btn', label: 'New agents' }],
+  ['Teams and races', 'A team (analyst, critics, implementer, tester, reviewer) solves one problem; a race tries variants and you keep the best.', { btn: '#new-btn', label: 'New agents' }],
+  ['Inbox', 'Every question, permission prompt, stuck agent and overlap between agents, in one place.', { tab: 'inbox', label: 'Inbox' }],
+  ['Code', "Every agent has a Code tab: its files in the editor from VS Code, with search and a diff against where it started. Or open the folder in VS Code or Cursor."],
+  ['Shells and browser', "+ Shell opens a terminal in an agent's folder; + Browser shows a page as this computer sees it (a dev server on localhost), from your phone too."],
+  ['Terminal', 'A shell on this computer in your home folder, from any device you are signed in on.', { btn: '#machine-btn', label: 'Terminal' }],
+  ['Review and land', "Review an agent's changes and send comments back; Land shows each pull request and what it needs to merge.", { tab: 'land', label: 'Land' }],
+  ['Backlog and assistant', 'Queue work to start as agents finish; the assistant and triggers (a GitHub label, a webhook) bring in new work.', { tab: 'backlog', label: 'Backlog' }],
+  ['Results', 'Merge rate, time to PR and cost per merged PR, with budgets and a daily limit.', { btn: '#spend-btn', label: 'Results' }],
+  ['From your phone', 'Answer agents, review and use the terminals from anywhere on your network.', { btn: '#remote-btn', label: 'Remote access' }],
+  ['Several machines', 'Link your computers to a hub to see every agent in one place, and move an agent to another machine to carry on there.', { href: 'https://github.com/jdmunta/ai-agentmanager-core/blob/main/docs/distributed.md', label: 'How it works' }],
+];
+
 export function initSetup({ api, esc, $ }) {
   const el = $('#placeholder');
   const plain = el.innerHTML;
@@ -21,30 +37,41 @@ export function initSetup({ api, esc, $ }) {
     }
   };
 
-  function render() {
-    if (!data || hidden()) {
-      el.innerHTML = plain;
-      return;
-    }
+  // A feature's button, unless what it opens isn't available here (local-only, on a phone).
+  function action(f) {
+    if (f.href) return `<a href="${f.href}" target="_blank" rel="noopener">${f.label} ↗</a>`;
+    if (f.btn && document.body.classList.contains('remote') && document.querySelector(f.btn)?.classList.contains('local-only')) return '';
+    if (f.btn) return `<button class="small ghost" data-setup-open="${f.btn}">${f.label}</button>`;
+    if (f.tab) return `<button class="small ghost" data-setup-tab="${f.tab}">${f.label}</button>`;
+    return '';
+  }
+
+  function steps() {
+    if (!data || hidden()) return '';
     const done = STEPS.filter(([k]) => data.steps[k]).length;
-    if (done === STEPS.length && !data.checks.length) {
-      el.innerHTML = plain;
-      return;
-    }
-    el.innerHTML = `<div class="setup">
-      <div class="setup-head"><h3>Getting started</h3><span class="hint">${done} of ${STEPS.length} done</span><span class="spacer"></span><button class="link" data-setup-hide>Hide</button></div>
+    if (done === STEPS.length && !data.checks.length) return '';
+    return `<div class="setup-head"><h3>Getting started</h3><span class="hint">${done} of ${STEPS.length} done</span><span class="spacer"></span><button class="link" data-setup-hide>Hide</button></div>
       ${data.checks.length ? `<div class="setup-checks">${data.checks.map((c) => `<div class="setup-check ${c.status}"><b>${esc(c.name)}</b>: ${esc(c.detail)}${c.fix ? `<div class="hint">${esc(c.fix)}</div>` : ''}</div>`).join('')}</div>` : ''}
       <ol class="setup-steps">${STEPS.map(([k, title, why, btn, label]) => `<li class="${data.steps[k] ? 'done' : ''}">
         <span class="setup-mark">${data.steps[k] ? '✓' : ''}</span>
         <div><b>${title}</b><div class="hint">${why}</div></div>
-        ${data.steps[k] ? '' : `<button class="small" data-setup-open="${btn}">${label}</button>`}</li>`).join('')}</ol>
+        ${data.steps[k] ? '' : `<button class="small" data-setup-open="${btn}">${label}</button>`}</li>`).join('')}</ol>`;
+  }
+
+  function render() {
+    el.innerHTML = `<div class="setup">
       <p class="hint">${plain}</p>
+      ${steps()}
+      <h3 class="setup-features-head">What you can do</h3>
+      <ul class="setup-features">${FEATURES.map(([title, why, f = {}]) => `<li><div><b>${title}</b><div class="hint">${why}</div></div>${action(f)}</li>`).join('')}</ul>
     </div>`;
   }
 
   el.addEventListener('click', (e) => {
     const open = e.target.closest('[data-setup-open]');
     if (open) return document.querySelector(open.dataset.setupOpen)?.click();
+    const tab = e.target.closest('[data-setup-tab]');
+    if (tab) return document.querySelector(`.side-tab[data-tab="${tab.dataset.setupTab}"]`)?.click();
     if (e.target.closest('[data-setup-hide]')) {
       try {
         localStorage.setItem('agentmgr.setupHidden', '1');

package/public/style.css

@@ -207,7 +207,7 @@ body.term-max .layout { grid-template-columns: 1fr; }
 
 /* ---------- detail */
 .detail { display: flex; flex-direction: column; min-height: 0; min-width: 0; }
-.placeholder { margin: auto; color: var(--muted); padding: 24px; text-align: center; }
+.placeholder { margin: auto; color: var(--muted); padding: 24px; text-align: center; max-height: 100%; overflow-y: auto; box-sizing: border-box; min-height: 0; width: 100%; }
 #detail-body { padding: 16px 20px; overflow-y: auto; flex: 0 1 auto; max-height: 100%; }
 .detail.with-term #detail-body { max-height: var(--brief-h, 42%); border-bottom: 1px solid var(--border); }
 .detail.with-term.brief-sized #detail-body { height: var(--brief-h); flex: none; }
@@ -735,7 +735,7 @@ input.inline { display: inline-block; width: 80px; padding: 1px 4px; }
 .pb-form { border: 1px solid var(--border); border-radius: 8px; padding: 12px; margin-top: 10px; }
 .memory-text { width: 100%; font: 12px/1.5 var(--mono); }
 #memory-dialog { width: min(760px, calc(100vw - 32px)); }
-.setup { max-width: 640px; margin: 24px auto; text-align: left; color: var(--text); }
+.setup { max-width: 820px; margin: 24px auto; text-align: left; color: var(--text); }
 .setup-head { display: flex; gap: 10px; align-items: baseline; }
 .setup-head h3 { margin: 0; font-size: 16px; }
 .setup-steps { list-style: none; padding: 0; margin: 10px 0; display: flex; flex-direction: column; gap: 6px; }
@@ -743,6 +743,11 @@ input.inline { display: inline-block; width: 80px; padding: 1px 4px; }
 .setup-steps li.done { opacity: .6; }
 .setup-mark { color: var(--green); font-weight: 700; }
 .setup-check { padding: 6px 10px; border-radius: 6px; margin: 6px 0; border-left: 3px solid var(--yellow); background: var(--panel-2); font-size: 13px; }
+.setup > .hint:first-child { text-align: center; margin: 0 0 16px; }
+.setup-features-head { margin: 22px 0 8px; font-size: 16px; }
+.setup-features { list-style: none; padding: 0; margin: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 8px; }
+.setup-features li { display: flex; flex-direction: column; justify-content: space-between; gap: 8px; padding: 10px 12px; border: 1px solid var(--border); border-radius: 8px; background: var(--panel); }
+.setup-features li > :last-child:not(div) { align-self: flex-start; }
 .setup-check.fail { border-left-color: var(--red); }
 
 /* ---------------------------------------------------------------- menu and settings */
@@ -809,3 +814,26 @@ input.inline { display: inline-block; width: 80px; padding: 1px 4px; }
 .machine-dialog[open] { display: flex; flex-direction: column; }
 .machine-dialog .terminal { flex: 1; min-height: 0; }
 .machine-dialog #machine-title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: #8b93a7; margin-left: 8px; }
+
+/* Diagrams: big pictures, one under another, for a quick grasp. */
+#doc-body.diagrams-view h2 { margin: 26px 0 8px; padding-top: 14px; border-top: 1px solid var(--border); }
+#doc-body.diagrams-view h2:first-of-type { border-top: 0; padding-top: 0; }
+#doc-body.diagrams-view .diagram { display: flex; justify-content: center; padding: 12px; border: 1px solid var(--border); border-radius: 8px; background: var(--panel); overflow-x: auto; }
+#doc-body.diagrams-view .diagram svg { max-width: 100%; height: auto; }
+@media (prefers-reduced-motion: reduce) { .diagram svg * { animation: none !important; } }
+
+.row.intent-split { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 16px; margin-bottom: 4px; }
+.intent-split > span:first-child { font-weight: 600; }
+.intent-split .check { margin: 0; }
+.intent-split[hidden] { display: none; }
+.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; }

package/public/transport.js

@@ -14,7 +14,8 @@ export const post = (url, body) =>
 
 /**
  * Open the event stream (`{ events: true }`) or a terminal (`{ agentId, kind }`).
- * Handlers: onOpen(), onMessage(msg), onClose({ code, reason }) when it ends for good.
+ * Handlers: onOpen(), onMessage(msg), onClose({ code, reason }) when it ends for good, and
+ * onInputLost(text) when typing could not be delivered (remote only).
  * Returns { send(msg), close() } where msg is { t: 'i', d } (input) or { t: 'r', cols, rows } (resize).
  */
 export function openStream({ events = false, agentId, kind = 'claude' }, h) {
@@ -43,16 +44,31 @@ export function openStream({ events = false, agentId, kind = 'claude' }, h) {
     }
   };
 
-  // Keystrokes: coalesced and sent strictly in order, one request at a time.
+  // Keystrokes: coalesced and sent strictly in order, one request at a time. A request that fails
+  // (a network blip, a phone waking up) is retried, not dropped: losing a line of a paste would run
+  // the rest without it.
   let queue = '';
   let inflight = false;
+  const deliver = async (d) => {
+    for (let attempt = 0; attempt < 6 && !closed; attempt++) {
+      try {
+        const res = await post(`/api/agents/${agentId}/term/input`, { d, kind });
+        // A refusal (signed out, terminal gone) won't change on a retry.
+        if (res.ok || (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429)) return res.ok;
+      } catch {
+        // Offline for a moment; try again.
+      }
+      await new Promise((r) => setTimeout(r, 250 * 2 ** attempt));
+    }
+    return false;
+  };
   const pump = async () => {
     if (inflight || !queue) return;
     inflight = true;
     const d = queue;
     queue = '';
     try {
-      await post(`/api/agents/${agentId}/term/input`, { d, kind });
+      if (!(await deliver(d)) && !closed) h.onInputLost?.(d);
     } finally {
       inflight = false;
       if (queue) pump();

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

@@ -342,6 +342,150 @@ export function docPrompt(kind, { intent, status, digest, repo, briefMarkdown, a
   ].join('\n');
 }
 
+// ------------------------------------------------------------------ Diagrams
+
+const DIAGRAM_SET = [
+  ['The problem', 'a flowchart of the situation today and where it goes wrong (the root cause, from the analysis)'],
+  ['Architecture', 'a flowchart of the components and how they connect, grouped with subgraphs; mark the components this work adds or changes with class "changed"'],
+  ['Design', 'a classDiagram (or erDiagram for data) of the key modules, types or records and their relationships'],
+  ['Data flow', 'a flowchart LR of how data moves through the system, with the main path animated'],
+  ['Key interaction', 'a sequenceDiagram (with autonumber) of the most important exchange between components, services or the user'],
+  ['Plan', 'a flowchart of the delivery steps or a stateDiagram-v2 of the main lifecycle, whichever the work is about'],
+];
+
+/**
+ * Diagrams only: the problem and its solution drawn for a quick grasp, from the documents
+ * already written for this work (analysis, design, flow, plan) and the agent's live context.
+ */
+export function diagramsPrompt({ intent, status, digest, repo, briefMarkdown, documents, repoMap }) {
+  return [
+    "Draw diagrams that let a person grasp an AI coding agent's work at a glance: the problem and how it is being solved.",
+    'Diagrams only. No paragraphs, bullets, captions, notes or explanations outside the diagrams.',
+    '',
+    'Output Markdown in exactly this shape: a level-1 title "# Diagrams: <short name of the work>", then for each diagram a',
+    'level-2 heading with its name followed by one ```mermaid code block. Nothing else.',
+    '',
+    'The diagrams, in this order (leave one out only when the context has nothing for it):',
+    ...DIAGRAM_SET.map(([name, what], i) => `${i + 1}. "${name}": ${what}.`),
+    '',
+    'Rules:',
+    '- Valid Mermaid syntax. At most about 15 nodes per diagram; labels of five words or fewer; quote labels with punctuation, e.g. A["Parse (JSON)"]. No HTML in labels.',
+    '- Animate the main path in every flowchart: give its edges ids and animate them, e.g.',
+    '    A e1@--> B',
+    '    B e2@-->|"saves"| C',
+    '    e1@{ animate: true }',
+    '    e2@{ animate: true }',
+    '- In the architecture diagram, style what this work adds or changes: `classDef changed stroke-width:3px,stroke:#22c55e` then `class X,Y changed`.',
+    '- Use the real names of files, modules, services and data from the context. Prefer what the documents below say; do not invent components.',
+    '- Output only the Markdown.',
+    '',
+    contextBlock({ intent, status, digest, repo, briefMarkdown }).join('\n'),
+    '<documents_already_written>',
+    documents || '(none yet: draw from the context above)',
+    '</documents_already_written>',
+    '<repository_layout>',
+    repoMap || '(no repository)',
+    '</repository_layout>',
+  ].join('\n');
+}
+
+/** Keep only the title, the diagram headings and the Mermaid blocks of a reply. */
+export function diagramsOnly(markdown) {
+  const out = [];
+  let block = null;
+  for (const line of String(markdown ?? '').split('\n')) {
+    if (block) {
+      if (/^\s*```\s*$/.test(line)) {
+        if (block.length) out.push('```mermaid', ...block, '```', '');
+        block = null;
+      } else block.push(line);
+    } else if (/^\s*```\s*mermaid\s*$/i.test(line)) block = [];
+    else if (/^#{1,2} \S/.test(line)) out.push(line, '');
+  }
+  if (!out.some((l) => l === '```mermaid')) throw new Error('The reply had no diagrams');
+  // A heading left with no diagram under it says nothing.
+  return out
+    .filter((l, i) => !/^## /.test(l) || out.slice(i + 1).find((x) => x !== '') === '```mermaid')
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .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 }) => [