ai-agentmanager 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.5.0 (2026-10-31)
+
+- **Muse Code engine:** Meta's Muse Code CLI (`muse`) as a fourth engine: `--engine muse` or **Muse Code** in the Engine picker. Session adoption, resume (messages typed once idle), conversation and usage, trust and approval questions in the inbox, a clean stop, and Explain. The picker warns when Muse is in contributor mode. Stuck detection from commands and edits isn't there yet for Muse.
+- **Terminals:** reloading the page no longer types the terminal's answers to old color and cursor queries into the program (seen with Muse Code), in agents' terminals and the Terminal. The agent's terminal tab is named after its engine (Codex, Antigravity, Muse Code).
+- **One agent or one per line:** New agents asks whether each line starts its own agent (a list of tickets) or the whole text goes to one agent (a long description, kept as written). The button shows how many agents it will create, and the choice is remembered.
+- **Diagrams:** a **Diagrams** button beside the documents draws the problem and its solution for a quick grasp, diagrams only: the problem, architecture (changes highlighted), design, data flow with animated arrows, the key interaction and the plan. Drawn from the analysis, design, flow, proposal and plan already written, plus the agent's work and the repo layout. Also `agentmgr doc <agent> diagrams`.
+- **Home page:** shows what you can do (agents, teams and races, Inbox, Code, shells and the browser, Terminal, review and Land, Backlog and the assistant, Results, your phone, several machines), each with a button to it, and stays after Getting started is done or hidden. It scrolls when it doesn't fit.
+- **Restart from the app's own terminal:** `agentmgr restart` or `agentmgr update` typed in an agent's shell or the Terminal no longer dies halfway (daemon stopped, never started) when the restart closes that terminal; it finishes, and the terminal can be reopened.
+- **Remote typing:** over remote access, typing or a paste whose request fails (a network blip) is retried in order instead of dropped, and you're told if it still can't get through.
+
 ## 1.4.0 (2026-10-31)
 
 - **Move an agent to another machine:** **Move to…** on the hub (or `agentmgr fleet move <machine>/<agent> --to <machine>`) continues an agent elsewhere with its conversation, branch and uncommitted work. The work goes through the repo's remote on a temporary handoff branch; the conversation goes through the hub in pieces (not stored). Both machines must allow the new `move` permission. A failed move puts everything back; the copy left behind is marked moved and can't be resumed.

package/README.md

@@ -6,7 +6,7 @@ Run one background [Claude Code](https://claude.com/claude-code) agent per inten
 
 ![The conflict radar: two agents changed the same lines of README.md; the AI judge rates it a collision and suggests which lands first](docs/images/conflict-radar.jpg)
 
-- **Intents in, agents out.** Give one intent or a list (one per line). Each becomes its own `claude` process.
+- **Intents in, agents out.** Give a list, one per line (say, a ticket each), and each becomes its own `claude` process. Or pick **One agent for all of it** and a long description goes to a single agent as written.
 - **Repo or folder.** Give a git URL (cloned once, then each agent gets its own worktree and branch) or a local folder.
   - **Fast clones.** URLs are cloned as partial clones (`--filter=blob:none`): history now, file contents only for what's checked out.
   - **Progress.** Clone and checkout progress shows in the UI and `agentmgr ls`.
@@ -83,13 +83,13 @@ Runs on macOS and Linux; on Windows, use WSL2. Requires Node 20+, `git`, and the
 
 ```sh
 npm install -g ai-agentmanager          # the latest release
-npm install -g ai-agentmanager@1.4.0    # or a specific one
+npm install -g ai-agentmanager@1.5.0    # or a specific one
 ```
 
 Or from the repository, at a release tag:
 
 ```sh
-git clone --branch v1.4.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
+git clone --branch v1.5.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
 cd ai-agentmanager-core
 npm install
 npm link            # optional: puts `agentmgr` on your PATH
@@ -109,7 +109,7 @@ npm link
 | Installed with | Update |
 | --- | --- |
 | npm | `npm install -g ai-agentmanager@latest` |
-| A clone at a release tag | `git fetch --tags && git checkout v1.4.0 && npm install` (the tag you want) |
+| A clone at a release tag | `git fetch --tags && git checkout v1.5.0 && npm install` (the tag you want) |
 | A clone of `main` | `git pull && npm install` |
 
 **Check your setup.** `agentmgr doctor` checks Node.js, Claude Code and its sign-in, git, `gh`, the data folder, the daemon's port and Chrome, and says how to fix anything missing.
@@ -327,6 +327,7 @@ The Brief panel's **Share for review** buttons, or `agentmgr doc <agent> <kind>`
 | **Flow** | Summary, end-to-end flowchart with a step-by-step walk-through, key interactions as a sequence diagram, failure and edge cases |
 | **Proposal** | Summary, problem, recommendation, scope, plan, effort and dependencies, risks, decisions needed |
 | **Human vs AI** | Your top 5 decisions, each with why it needs you, the stakes, options and what the work suggests, plus a box for your answer. Up to 5 questions the AI answers, each with its confidence, evidence and how to check it. A second model's verdict on each. |
+| **Diagrams** | Diagrams only, for a quick grasp: the problem, the architecture (with what changes highlighted), the design, the data flow (animated) and the key interaction, plus the plan. Drawn from the documents already written and the agent's work. Optional: **Write all** leaves it out. |
 
 **Human vs AI.** This review takes two separate read-only calls.
 1. **The split.** The agent's engine splits the open questions. *For you to decide* covers judgment calls such as intent, priorities, risk appetite and trade-offs. *Answered by AI* covers reasoning and evaluation: correctness, edge cases, test coverage and what's left.
@@ -723,12 +724,14 @@ Or use **Remote access** in the header of the UI on this computer.
 - **Firewall.** If the macOS firewall is off, the port is open to your whole network while remote access is on. Turn it off when you don't need it.
 - **Streaming.** The phone UI streams with Server-Sent Events plus plain HTTPS requests. iOS Safari doesn't apply an accepted self-signed certificate to WebSockets.
 
-## Engines: Claude Code, Codex and Antigravity
+## Engines: Claude Code, Codex, Antigravity and Muse Code
 
 Agents run Claude Code by default. With OpenAI's Codex CLI installed (`npm i -g @openai/codex`, signed in), an agent can run Codex instead: `agentmgr add --engine codex …`, or the **Engine** picker in New agent (shown once a second engine is installed). Everything else works the same way: worktrees, the brief and questions, the inbox (Codex's approval menus included), token usage, stuck detection, PR tracking, Explain, the backlog and the hub. Codex records no cost, and planning while a repo clones and forks are Claude-only for now. Set `"engine": "codex"` in config.json to make it the default; `engines.codex.bin` points at another binary. On the hub, each machine reports the engines it has (`engine:codex`), so shared backlog work can ask for one. See [docs/engines.md](docs/engines.md).
 
 Google's **Antigravity CLI** (`agy`, signed in with your Google account) works the same way: `--engine antigravity`. It replaced Gemini CLI for personal Google accounts in June 2026. AI Agent Manager adopts the conversation agy starts, resumes it with `--conversation`, reads token usage, commands and file writes from its transcript, shows its permission menus (commands, file changes, access outside the folder) in the inbox, pre-trusts agent folders in agy's settings, and runs Explain in agy's print mode. agy asks before writing the brief too, unless the agent runs in `acceptEdits` mode. `engines.antigravity.bin` points at another binary.
 
+Meta's **Muse Code** (`muse`, installed with `curl -fsSL https://dev.meta.ai/install.sh | bash` and signed in with `muse login`) works the same way: `--engine muse`. AI Agent Manager adopts the session Muse starts, resumes it with `muse resume` (a message for a resumed session is typed once Muse is idle), trusts the agent's folder for each run with `--trust-workspace` instead of saving it, reads the conversation and token usage from Muse's session log, shows its trust and approval questions in the inbox, stops it cleanly with SIGTERM, and runs Explain with `muse exec` in the read-only profile. Commands and edits aren't read from its log yet, so stuck detection has less to go on for Muse agents. When Muse runs in contributor mode (an account without a plan), the engine picker says so: Meta may use your code and conversations to improve its products. `engines.muse.bin` points at another binary, and `engines.muse.args` adds arguments to every run.
+
 ## Several machines: the hub
 
 With agents on more than one Mac, a **hub** shows all of them in one place: every machine's agents and one inbox of what needs you. Where a machine allows it, you can also act from the hub: answer, message, start and stop agents, start new ones, and open live terminals. Each Mac keeps running its own daemon. It connects out to the hub, so no ports need opening on it, and the hub's requests travel back over that same connection.

package/docs/engines.md

@@ -1,6 +1,6 @@
 # Design: several agent engines (Claude Code, Codex CLI, Gemini CLI)
 
-Status: phase 1, Codex and Antigravity built. Gemini CLI dropped: since June 18, 2026 it no longer serves personal Google accounts, and Antigravity CLI (`agy`, `src/engines/antigravity.js`, checked against 1.4.3, fixtures in `test/fixtures/antigravity/`) replaced it. 0.4 (branch `v0.4-engines`) · 2026-10-18. Targets the current releases of each CLI, checked in phase 1.
+Status: phase 1, Codex, Antigravity and Muse Code built. Gemini CLI dropped: since June 18, 2026 it no longer serves personal Google accounts, and Antigravity CLI (`agy`, `src/engines/antigravity.js`, checked against 1.4.3, fixtures in `test/fixtures/antigravity/`) replaced it. 0.4 (branch `v0.4-engines`) · 2026-10-18. Targets the current releases of each CLI, checked in phase 1.
 
 AI Agent Manager runs every agent with Claude Code. If Anthropic has an outage, a rate limit hits, or prices change, every agent stops at once. Running agents on other engines as well makes the fleet resilient across providers, and lets each task use the engine that suits it.
 
@@ -167,6 +167,7 @@ The e2e suite uses a fake Claude (`test/fake-claude.js`). Each engine gets its o
 | 1. Adapter seam ✅ | `src/engines/claude.js` with today's behaviour behind the interface; `engine` on agents; real CLIs checked and recorded as fixtures |
 | 2. Antigravity CLI ✅ | Replaces Gemini CLI. `src/engines/antigravity.js`: launch with instructions in the first message, adoption of the conversation agy picks (`cache/last_conversations.json`), resume with `--conversation`, usage, commands and writes from `brain/<id>/.system_generated/logs/transcript_full.jsonl`, command / file / access menus, trust in `settings.json` `trustedWorkspaces`, Explain in print mode (`--mode plan`, prompt attached to `--print=`). Non-Claude engines get a shorter conventions note: a smaller model turned the Claude-specific one into a search of the whole disk. |
 | 3. Codex CLI ✅ | `src/engines/codex.js`: launch and resume, session adoption, brief folder (`--add-dir`), usage, stuck detection, prompts, trust, Explain through `codex exec`; engine pickers in the CLI, the page and the hub; machines report `engine:*` labels for the shared backlog. Not yet: planning while cloning and forks. Built before Gemini, which waits on a sign-in. |
+| 3b. Muse Code ✅ (partly) | `src/engines/muse.js`, checked against Muse Code 1.4.14 (fixtures in `test/fixtures/muse/`). Launch with instructions in the first message; adoption of the session Muse picks (`$XDG_DATA_HOME/muse/sessions/YYYY/MM/DD/<id>/session.jsonl`, folder from the `runtime.session.metadata` record's `workspace_root`); `muse resume <id>`, which takes no message, so a message for a resumed session is typed once it is idle (`supports.resumePrompt: false`); `--trust-workspace` on each launch instead of saving trust; Plan → `:read-only` profile, Auto → `:auto-review`, Bypass → `--yolo`; prompts, replies and usage from the run events; stopped with SIGTERM (`stopSignal`), since a hangup leaves no clean end in its log; Explain through `muse exec` in the read-only profile (options after `exec`: `oneShotExtra`). A notice in the engine picker when Muse runs in contributor mode (Meta may use the content). Not yet, because real model calls weren't available while building it: commands and edits from the log (no stuck detection from them), and the approval menus are matched from the wording in the binary rather than a recorded screen. |
 | 4. Fail over | Engine health, preference lists in both backlogs, engines reported to the hub, **Continue on…** handoff |
 
 ## Open questions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agentmanager",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Run background coding agents (Claude Code, Codex) per intent, and keep track of them from a web UI, your phone or the CLI",
   "keywords": [
     "claude",

package/public/app.js

@@ -245,7 +245,9 @@ const INSIGHT_ICONS = { why: '🎯', what: '📦', how: '🛠', now: '📍' };
 
 // ------------------------------------------------------------------ stakeholder documents
 
-const DOCS = { analysis: 'Analysis', design: 'Design', flow: 'Flow', proposal: 'Proposal', humanai: 'Human vs AI' };
+const DOCS = { analysis: 'Analysis', design: 'Design', flow: 'Flow', proposal: 'Proposal', humanai: 'Human vs AI', diagrams: 'Diagrams' };
+// Optional extras that "Write all" leaves out.
+const DOC_EXTRAS = new Set(['diagrams']);
 const DOC_TITLES = { ...DOCS, plan: 'Implementation plan' };
 /** What the document dialog shows: a stakeholder document, or the agent's plan under review. */
 const docOf = (a, kind) => (kind === 'plan' ? a?.planReview && { markdown: a.planReview.markdown, at: a.planReview.updatedAt } : a?.docs?.[kind]);
@@ -308,7 +310,7 @@ function docHtml(markdown) {
 }
 
 function docButtons(a) {
-  const missing = Object.keys(DOCS).filter((k) => !a.docs?.[k]?.markdown && !a.docs?.[k]?.pending);
+  const missing = Object.keys(DOCS).filter((k) => !DOC_EXTRAS.has(k) && !a.docs?.[k]?.markdown && !a.docs?.[k]?.pending);
   const all = missing.length
     ? `<button class="small ghost" data-doc-all title="Write ${missing.map((k) => DOCS[k]).join(', ')} in the background; you'll be told when each is ready">Write all in background</button>`
     : '';
@@ -317,7 +319,7 @@ function docButtons(a) {
       const d = a.docs?.[k];
       const stale = d?.markdown && a.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
       return `<button class="small doc-btn ${d?.markdown ? 'has' : ''}" data-doc="${k}" ${d?.pending ? 'disabled' : ''}
-        title="${d?.markdown ? `Open the ${label.toLowerCase()} document${stale ? ' (the brief changed since)' : ''}` : `Write a ${label.toLowerCase()} document for stakeholders`}">${d?.pending ? `${label}…` : label}${d?.markdown ? (stale ? ' •' : ' ✓') : ''}</button>`;
+        title="${k === 'diagrams' ? (d?.markdown ? `Open the diagrams${stale ? ' (the brief changed since)' : ''}` : 'Draw the problem and its solution for a quick grasp: architecture, design, data flow (animated) and the key interaction, diagrams only. Built from the documents already written and the agent\'s work') : d?.markdown ? `Open the ${label.toLowerCase()} document${stale ? ' (the brief changed since)' : ''}` : `Write a ${label.toLowerCase()} document for stakeholders`}">${d?.pending ? `${label}…` : label}${d?.markdown ? (stale ? ' •' : ' ✓') : ''}</button>`;
     })
     .join('')}</span>`;
 }
@@ -332,8 +334,9 @@ function renderDocDialog() {
   const plan = docView.kind === 'plan';
   $('#doc-title').textContent = `${label} · ${a?.name ?? ''}`;
   const body = $('#doc-body');
+  body.classList.toggle('diagrams-view', docView.kind === 'diagrams');
   if (d?.pending) {
-    body.innerHTML = `<p class="hint">${docView.kind === 'humanai' ? 'Splitting the open questions and answering the AI ones, then asking a second model to check…' : `Writing the ${label.toLowerCase()} document from the agent's work so far…`}</p>`;
+    body.innerHTML = `<p class="hint">${docView.kind === 'humanai' ? 'Splitting the open questions and answering the AI ones, then asking a second model to check…' : docView.kind === 'diagrams' ? "Drawing the diagrams from the documents and the agent's work so far…" : `Writing the ${label.toLowerCase()} document from the agent's work so far…`}</p>`;
     body.dataset.rendered = '';
   } else if (d?.error) body.innerHTML = `<p class="error">Couldn't write it: ${esc(d.error)}</p>`;
   else if (plan && !d?.markdown) body.innerHTML = '<p class="hint">The agent is investigating and hasn\'t written its plan yet. You\'ll see it here (and in the inbox) when it has.</p>';
@@ -345,8 +348,8 @@ function renderDocDialog() {
     }
   }
   const stale = !plan && d?.markdown && a.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
-  const by = d?.writer ? ` by ${d.writer}${d.critique ? `, checked by ${d.critique.label}` : ''}` : '';
-  $('#doc-meta').textContent = d?.markdown ? `${plan ? `Plan · ${PLAN_LABEL[a.planReview.status]} · updated` : 'Written'} ${ago(d.at)}${by}${stale ? ' · the brief has changed since; Regenerate for the latest' : ''}` : '';
+  const by = d?.writer ? ` by ${d.writer}${d.critique ? `, checked by ${d.critique.label}` : ''}${d.from ? ` from ${d.from.length ? d.from.join(', ') : "the agent's work"}` : ''}` : '';
+  $('#doc-meta').textContent = d?.markdown ? `${plan ? `Plan · ${PLAN_LABEL[a.planReview.status]} · updated` : docView.kind === 'diagrams' ? 'Drawn' : 'Written'} ${ago(d.at)}${by}${stale ? ' · the brief has changed since; Regenerate for the latest' : ''}` : '';
   for (const id of ['doc-copy', 'doc-download', 'doc-print']) $(`#${id}`).disabled = !d?.markdown;
   $('#doc-print').hidden = plan;
   $('#doc-regen').hidden = plan;
@@ -1784,6 +1787,9 @@ const term = {
     this.xterm.loadAddon(this.fit);
     this.xterm.open($('#terminal'));
     this.xterm.onData((d) => {
+      // Replaying the backlog makes xterm answer the color and cursor queries in it again; those
+      // answers are stale, and the program would get them as typing.
+      if (this.replaying) return;
       lastTyped = Date.now();
       this.send({ t: 'i', d });
     });
@@ -1842,6 +1848,7 @@ const term = {
           this.conn = null;
           if (ev.code === 1008) toast(`Terminal unavailable: ${ev.reason}`, 5000);
         },
+        onInputLost: () => this.conn === conn && toast('Some typing did not reach the computer (connection lost); check the terminal before going on', 8000),
       },
     );
     this.conn = conn;
@@ -1852,7 +1859,8 @@ const term = {
       if (msg.t === 'hello') {
         // Also sent again after a reconnect: start from a clean screen and replay.
         this.xterm.reset();
-        this.xterm.write(msg.backlog);
+        this.replaying = true;
+        this.xterm.write(msg.backlog, () => (this.replaying = false));
         if (!matchMedia('(pointer: coarse)').matches) this.xterm.focus();
       } else if (msg.t === 'error') {
         toast(`Terminal unavailable: ${msg.error}`, 5000);
@@ -1888,6 +1896,8 @@ const term = {
   renderTabs() {
     renderSignIn();
     const a = this.agentId && agents.get(this.agentId);
+    // The agent's own session tab is named after its engine (Codex, Muse Code, …).
+    $('.term-tab[data-kind="claude"]').textContent = ENGINE_LABEL[a?.engine] ?? 'Claude';
     const nums = new Set(a?.runtime.shells ?? []);
     if (isShell(this.kind)) nums.add(shellNum(this.kind));
     $('#shell-tabs').innerHTML = [...nums]
@@ -3147,6 +3157,7 @@ function openNewDialog(mode = 'now') {
   renderProjectOptions();
   $('#new-error').hidden = true;
   dialog.querySelector(`input[name="when"][value="${mode}"]`).checked = true;
+  restoreIntentSplit();
   syncWhen();
   dialog.showModal();
   dialog.querySelector('textarea').focus();
@@ -3156,7 +3167,55 @@ function syncWhen() {
   dialog.querySelector('.now-only').hidden = when !== 'now';
   dialog.querySelector('.race-only').hidden = when !== 'race';
   dialog.querySelector('.team-only').hidden = when !== 'team';
-  dialog.querySelector('button[type=submit]').textContent = { backlog: 'Add to backlog', race: 'Start race', team: 'Start team' }[when] ?? 'Create agents';
+  // A race or a team always works on the whole text.
+  dialog.querySelector('.intent-split').hidden = when === 'race' || when === 'team';
+  syncIntentPlaceholder();
+  syncIntentCount();
+}
+
+/** The form's intents: one per line, or the whole text as one (kept as written, blank lines and all). */
+function formIntents(form) {
+  const text = form.intents.value;
+  const whole = form.split.value === 'one' || ['race', 'team'].includes(form.when.value);
+  if (whole) return text.trim() ? [text.trim()] : [];
+  return text
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function syncIntentCount() {
+  const form = $('#new-form');
+  const when = form.when.value;
+  const n = formIntents(form).length;
+  const split = !['race', 'team'].includes(when);
+  $('#intent-count').textContent = split && n ? (when === 'backlog' ? `${n} item${n > 1 ? 's' : ''}` : `${n} agent${n > 1 ? 's' : ''}`) : '';
+  const submit = dialog.querySelector('button[type=submit]');
+  submit.textContent = { backlog: n > 1 ? `Add ${n} to backlog` : 'Add to backlog', race: 'Start race', team: 'Start team' }[when] ?? (n > 1 ? `Create ${n} agents` : 'Create agent');
+}
+$('#new-form').intents.addEventListener('input', syncIntentCount);
+for (const r of dialog.querySelectorAll('input[name="split"]')) {
+  r.addEventListener('change', () => {
+    try {
+      localStorage.setItem('agentmgr.intentSplit', r.value);
+    } catch {}
+    syncIntentPlaceholder();
+    syncIntentCount();
+  });
+}
+const LINES_PLACEHOLDER = $('#new-form').intents.placeholder;
+const WHOLE_PLACEHOLDER = 'Describe the work in as much detail as you like: the problem, what done looks like, constraints, links. It all goes to one agent.';
+/** The remembered choice (a form reset forgets it), and a placeholder to match. */
+function restoreIntentSplit() {
+  const form = $('#new-form');
+  try {
+    form.split.value = localStorage.getItem('agentmgr.intentSplit') === 'one' ? 'one' : 'lines';
+  } catch {}
+  syncIntentPlaceholder();
+}
+function syncIntentPlaceholder() {
+  const form = $('#new-form');
+  form.intents.placeholder = form.split.value === 'one' || ['race', 'team'].includes(form.when.value) ? WHOLE_PLACEHOLDER : LINES_PLACEHOLDER;
 }
 for (const r of dialog.querySelectorAll('input[name="when"]')) r.addEventListener('change', syncWhen);
 $('#new-btn').onclick = () => openNewDialog('now');
@@ -3164,10 +3223,7 @@ $('#new-cancel').onclick = () => dialog.close();
 $('#new-form').addEventListener('submit', async (e) => {
   e.preventDefault();
   const f = new FormData(e.target);
-  const intents = String(f.get('intents'))
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
+  const intents = formIntents(e.target);
   if (f.get('when') === 'team') {
     // "analyst=opus reviewer=opus"
     const models = Object.fromEntries(
@@ -3951,13 +4007,22 @@ $('#login-form').addEventListener('submit', async (e) => {
 });
 
 // Engines this machine can run; the New agent form offers a choice once there's more than Claude.
-const ENGINE_LABEL = { claude: 'Claude', codex: 'Codex', antigravity: 'Antigravity' };
+const ENGINE_LABEL = { claude: 'Claude', codex: 'Codex', antigravity: 'Antigravity', muse: 'Muse Code' };
 async function loadEngines() {
   try {
     const list = (await api('GET', '/engines')).filter((e) => e.installed && e.id !== 'claude');
     const sel = document.querySelector('#engine-field select');
     for (const e of list) sel.append(Object.assign(document.createElement('option'), { value: e.id, textContent: e.label }));
     $('#engine-field').hidden = !list.length;
+    // Something to know before choosing an engine (Muse Code in contributor mode, say).
+    const notices = Object.fromEntries(list.filter((e) => e.notice).map((e) => [e.id, e.notice]));
+    const show = () => {
+      const n = $('#engine-notice');
+      n.textContent = notices[sel.value] ?? '';
+      n.hidden = !notices[sel.value];
+    };
+    sel.addEventListener('change', show);
+    show();
   } catch {}
 }
 

package/public/hub/hub.js

@@ -42,7 +42,7 @@ function toast(msg, bad = false) {
   toast.timer = setTimeout(() => (t.hidden = true), bad ? 6000 : 2500);
 }
 
-const ENGINE_LABEL = { claude: 'Claude Code', codex: 'Codex', antigravity: 'Antigravity' };
+const ENGINE_LABEL = { claude: 'Claude Code', codex: 'Codex', antigravity: 'Antigravity', muse: 'Muse Code' };
 /** Engines a machine reports installed (its engine:* labels). */
 const enginesOf = (runner) => (runner?.labels ?? []).filter((l) => l.startsWith('engine:')).map((l) => l.slice(7));
 /** Fill an engine picker; hidden while Claude Code is the only choice. */

package/public/index.html

@@ -163,8 +163,14 @@
     <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 class="row">
@@ -195,6 +201,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>

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

@@ -1,5 +1,5 @@
-// 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'],
@@ -9,6 +9,21 @@ const STEPS = [
   ['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 +36,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,18 @@ 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; }

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

@@ -342,6 +342,75 @@ 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();
+}
+
 // ------------------------------------------------------------------ Human vs AI
 
 export const contextBlock = ({ intent, status, digest, repo, briefMarkdown }) => [

package/src/cli.js

@@ -404,9 +404,9 @@ export async function main(argv) {
 
   program
     .command('doc')
-    .description('Write a stakeholder document from the agent work: analysis, design, flow, proposal or humanai (Human vs AI)')
+    .description('Write a stakeholder document from the agent work: analysis, design, flow, proposal, humanai (Human vs AI) or diagrams (diagrams only)')
     .argument('<agent>')
-    .argument('<kind>', 'analysis, design, flow, proposal, humanai, or all (background)')
+    .argument('<kind>', 'analysis, design, flow, proposal, humanai, diagrams, or all (background; diagrams not included)')
     .option('-o, --output <file>', 'also save the Markdown to this file')
     .option('--cached', 'print the last version instead of writing a new one')
     .option('-b, --background', 'start writing and return at once (kind "all" writes all five)')
@@ -2020,10 +2020,21 @@ export async function main(argv) {
       console.log(`${green('✓')} saved ${r.agents} agents (${r.running} running), scrollback for ${r.scrollback}, at ${r.at}`);
     });
 
+  // The daemon's own terminals (agent shells, Open Terminal, the agents themselves) close when it
+  // stops, and the hangup would end a restart typed there halfway: daemon stopped, never started.
+  // So a restart from one ignores the hangup and its closed output, and finishes without it.
+  const outliveTerminal = () => {
+    if (!process.env.AGENTMGR_TERMINAL) return;
+    console.log(dim('This terminal belongs to the daemon and closes while it restarts; the restart carries on. Reopen the terminal afterwards.'));
+    process.on('SIGHUP', () => {});
+    for (const out of [process.stdout, process.stderr]) out.on('error', () => {});
+  };
+
   program
     .command('restart')
     .description('Flush, stop the daemon, and start it again; running agents resume their sessions')
     .action(async () => {
+      outliveTerminal();
       const svc = await import('./service.js');
       const before = await health();
       if (before && !before.closing) {
@@ -2075,6 +2086,7 @@ export async function main(argv) {
       const r = await up.installUpdate({ log: (m) => console.log(dim(m)) });
       console.log(`${green('✓')} installed ${r.to} (was ${r.from})`);
       if (!(await health())) return console.log(dim('The daemon is not running; it starts on the new version next time'));
+      outliveTerminal();
       // The new version's own restart, not the copy of it loaded in this process.
       const { spawnSync } = await import('node:child_process');
       const res = spawnSync(process.execPath, [process.argv[1], 'restart'], { stdio: 'inherit' });

package/src/engines/index.js

@@ -5,8 +5,9 @@ import path from 'node:path';
 import antigravity from './antigravity.js';
 import claude from './claude.js';
 import codex from './codex.js';
+import muse from './muse.js';
 
-export const ENGINES = { claude, codex, antigravity };
+export const ENGINES = { claude, codex, antigravity, muse };
 export const DEFAULT_ENGINE = 'claude';
 
 /** Adds an engine from a plugin. Built-in engines can't be replaced. */
@@ -33,7 +34,14 @@ export function notInstalled(engine, config) {
 
 /** Every engine, with whether it can run here, for pickers and the hub. */
 export function listEngines(config) {
-  return Object.values(ENGINES).map((e) => ({ id: e.id, label: e.label, installed: installed(e, config), permissionModes: e.permissionModes, supports: e.supports }));
+  return Object.values(ENGINES).map((e) => {
+    const ok = installed(e, config);
+    let notice = null;
+    try {
+      notice = ok ? (e.notice?.(config) ?? null) : null;
+    } catch {}
+    return { id: e.id, label: e.label, installed: ok, permissionModes: e.permissionModes, supports: e.supports, notice };
+  });
 }
 
 /** The engine for an agent (or an engine id). */

package/src/engines/muse.js

@@ -0,0 +1,303 @@
+// Meta's Muse Code CLI (`muse`) as an agent engine (checked against Muse Code 1.4.14; fixtures in
+// test/fixtures/muse). Differences from Claude Code that shape this adapter:
+//   - Muse picks its own session IDs; the manager adopts the one it creates. Sessions live in
+//     $XDG_DATA_HOME/muse/sessions/YYYY/MM/DD/<id>/session.jsonl, and the runtime.session.metadata
+//     record near the top holds the folder it ran in (workspace_root).
+//   - `muse resume <id>` takes no message, so a message for a resumed session is typed once it
+//     is idle (supports.resumePrompt: false).
+//   - No flag for extra instructions: they go in the first message of a new session.
+//   - The log is Muse's own event log; this reads only the run events (prompt, reply, usage).
+//     Tool calls aren't read yet, so stuck detection has no commands or edits for Muse agents.
+//   - Approval questions ("Would you like to run the following command?") are matched from the
+//     wording in the binary; the trust question was seen on a real screen.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { extractRefs } from '../tracker.js';
+
+// MUSE_DATA_HOME is AI Agent Manager's own override (tests); Muse itself uses the XDG folder.
+const dataHome = () => process.env.MUSE_DATA_HOME || path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'), 'muse');
+const sessionsDir = () => path.join(dataHome(), 'sessions');
+const configHome = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'muse');
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const real = (p) => {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+};
+const ANSI = /\x1b(\[[0-9;?<>=]*[ -\/]*[@-~]|\][^\x07\x1b]*(\x07|\x1b\\)|[()][0-9A-B]|[=>78c])/g;
+const readdir = (d) => {
+  try {
+    return fs.readdirSync(d);
+  } catch {
+    return [];
+  }
+};
+
+/** Day folders from `sinceMs` to today (sessions are filed by their start date). */
+function dayDirs(sinceMs) {
+  const out = [];
+  const d = new Date(Math.min(sinceMs, Date.now()));
+  d.setHours(0, 0, 0, 0);
+  for (let i = 0; i < 400 && d.getTime() <= Date.now(); i++, d.setDate(d.getDate() + 1)) {
+    out.push(path.join(sessionsDir(), String(d.getFullYear()), String(d.getMonth() + 1).padStart(2, '0'), String(d.getDate()).padStart(2, '0')));
+  }
+  return out;
+}
+
+/** The folder a session ran in: workspace_root in its runtime.session.metadata record (one of the first lines). */
+function sessionCwd(file) {
+  try {
+    const fd = fs.openSync(file, 'r');
+    try {
+      const buf = Buffer.alloc(256 * 1024);
+      const n = fs.readSync(fd, buf, 0, buf.length, 0);
+      for (const line of buf.subarray(0, n).toString('utf8').split('\n')) {
+        if (!line.includes('"runtime.session.metadata"')) continue;
+        const m = /"(?:workspace_root|cwd)"\s*:\s*("(?:[^"\\]|\\.)*")/.exec(line);
+        return m ? JSON.parse(m[1]) : null;
+      }
+      return null;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
+const found = new Map(); // session id -> file
+function findSession(sessionId) {
+  if (!UUID.test(String(sessionId))) return null;
+  const hit = found.get(sessionId);
+  if (hit && fs.existsSync(hit)) return hit;
+  // Newest days first; a session resumed today is still filed under the day it started.
+  for (const y of readdir(sessionsDir()).filter((n) => /^\d{4}$/.test(n)).sort().reverse()) {
+    for (const m of readdir(path.join(sessionsDir(), y)).sort().reverse()) {
+      for (const d of readdir(path.join(sessionsDir(), y, m)).sort().reverse()) {
+        const file = path.join(sessionsDir(), y, m, d, sessionId, 'session.jsonl');
+        if (fs.existsSync(file)) {
+          found.set(sessionId, file);
+          return file;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/** Read the complete lines added since the cursor's offset. */
+function newRecords(file, cursor) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+  } catch {
+    return null;
+  }
+  try {
+    const { size, mtime } = fs.fstatSync(fd);
+    cursor.lastActivity = mtime.toISOString();
+    if (size < cursor.offset) cursor.offset = 0;
+    if (size === cursor.offset) return [];
+    const buf = Buffer.alloc(size - cursor.offset);
+    fs.readSync(fd, buf, 0, buf.length, cursor.offset);
+    const lastNl = buf.lastIndexOf(0x0a);
+    if (lastNl < 0) return [];
+    const start = cursor.offset;
+    cursor.offset += lastNl + 1;
+    const out = [];
+    let at = start;
+    for (const line of buf.subarray(0, lastNl).toString('utf8').split('\n')) {
+      const here = at;
+      at += Buffer.byteLength(line) + 1;
+      // Only the run events matter here; skip the rest without parsing it.
+      if (!line.includes('"runtime.session"') || !line.includes('"kind":"run"')) continue;
+      try {
+        out.push({ rec: JSON.parse(line), at: here });
+      } catch {}
+    }
+    return out;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** A run event: { kind, ...fields } for the person's message, the reply, usage and the end of a turn. */
+const runEvent = (rec) => (rec.payload_type === 'runtime.session' && rec.payload?.kind === 'run' ? rec.payload.event ?? null : null);
+const atOf = (rec) => (rec.recorded_at ? Math.floor(rec.recorded_at / 1000) : Date.now());
+
+/**
+ * Permission modes in Muse terms: a built-in permission profile, or no approval and no sandbox.
+ * Muse's own default is the Auto-review profile (a model reviews what isn't plainly safe).
+ */
+const MODES = {
+  default: [],
+  acceptEdits: [],
+  plan: ['--permission-profile', ':read-only'],
+  auto: ['--permission-profile', ':auto-review'],
+  bypassPermissions: ['--yolo'],
+};
+
+/** The model Muse is set to use (its settings file), or null. */
+function configuredModel() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(configHome(), 'settings.json'), 'utf8')).model ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export default {
+  id: 'muse',
+  label: 'Muse Code',
+  supports: { chooseSessionId: false, cost: false, planHandoff: false, fork: false, oneShot: true, resumePrompt: false },
+  permissionModes: Object.keys(MODES),
+  // Muse reads the first of these it finds, walking up to the repo root.
+  rulesFiles: ['AGENTS.md', 'CLAUDE.md'],
+  install: 'Install Muse Code (curl -fsSL https://dev.meta.ai/install.sh | bash) and run `muse login`',
+
+  // On a hangup Muse records no clean end and warns on the next resume; SIGTERM ends it cleanly.
+  stopSignal: 'SIGTERM',
+
+  bin: (config) => config.engines?.muse?.bin ?? 'muse',
+  extraArgs: (config) => [...(config.engines?.muse?.args ?? [])],
+
+  /** Something the person should know before choosing Muse, or null. */
+  notice() {
+    const model = configuredModel();
+    return /contributor/i.test(model ?? '') ? `Contributor mode (${model}): Meta may use your code and conversations to improve its products.` : null;
+  },
+
+  /**
+   * Full arguments for a launch. The folder is trusted for the run (nothing is saved), so the
+   * trust question doesn't stop a new agent. Resume takes no message; it is typed when idle.
+   */
+  launchArgs({ extra = [], permissionMode, model, instructions, sessionId, resume, prompt }) {
+    const opts = [...extra, '--trust-workspace', ...(MODES[permissionMode] ?? MODES.default)];
+    if (model) opts.push('--model', model);
+    if (resume) return ['resume', sessionId, ...opts];
+    const first = [instructions, prompt && (instructions ? `Your task:\n${prompt}` : prompt)].filter(Boolean).join('\n\n---\n\n');
+    // "--" so a message starting with "-" isn't read as a flag.
+    return [...opts, ...(first ? ['--', first] : [])];
+  },
+
+  sessionFile: (cwd, sessionId) => findSession(sessionId) ?? path.join(sessionsDir(), `missing-${sessionId}`, 'session.jsonl'),
+  hasSession: (cwd, sessionId) => Boolean(findSession(sessionId)),
+  subagentFiles: () => [],
+
+  /** Sessions Muse started in this folder since a time; the manager adopts a new one. */
+  recentSessions(cwd, sinceMs) {
+    const want = real(cwd);
+    const out = [];
+    for (const dir of dayDirs(sinceMs)) {
+      for (const id of readdir(dir)) {
+        if (!UUID.test(id)) continue;
+        const file = path.join(dir, id, 'session.jsonl');
+        let st;
+        try {
+          st = fs.statSync(file);
+        } catch {
+          continue;
+        }
+        if (st.mtimeMs < sinceMs) continue;
+        const where = sessionCwd(file);
+        if (!where || real(where) !== want) continue;
+        found.set(id, file);
+        out.push({ sessionId: id, file, mtimeMs: st.mtimeMs, birthtimeMs: st.birthtimeMs });
+      }
+    }
+    return out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  },
+
+  /** Usage (one entry per model call), PR and bug links from the person's messages and the replies. */
+  scan(file, cursor, bugPatterns = []) {
+    const result = { prs: [], bugs: [], title: null, lastPrompt: null, cost: null, lastActivity: null };
+    cursor.usage ??= new Map();
+    cursor.offset ??= 0;
+    const recs = newRecords(file, cursor);
+    result.lastActivity = cursor.lastActivity ?? null;
+    if (!recs) return result;
+    for (const { rec, at } of recs) {
+      const e = runEvent(rec);
+      if (!e) continue;
+      if (e.kind === 'model_completed' && e.usage) {
+        const u = e.usage;
+        const cached = u.cached_tokens ?? 0;
+        // Cached tokens are counted inside input_tokens, as with OpenAI's API.
+        cursor.usage.set(`r${at}`, { input: Math.max(0, (u.input_tokens ?? 0) - cached), output: (u.output_tokens ?? 0) + (u.reasoning_tokens ?? 0), cacheCreation: 0, cacheRead: cached });
+      } else if (e.kind === 'started' || e.kind === 'assistant_message_committed') {
+        const text = String(e.prompt ?? e.text ?? '');
+        if (e.kind === 'started' && text) result.lastPrompt = text.slice(0, 500);
+        const refs = extractRefs(text, bugPatterns);
+        result.prs.push(...refs.prs);
+        result.bugs.push(...refs.bugs);
+      }
+    }
+    return result;
+  },
+
+  /** Commands and edits for stuck detection: not read from Muse's log yet. */
+  activity(file, state) {
+    state.events ??= [];
+    return state;
+  },
+
+  /** A readable digest of the conversation, for Explain and documents. */
+  digest(file, { maxChars = 24_000 } = {}) {
+    const events = [];
+    for (const { rec } of newRecords(file, { offset: 0 }) ?? []) {
+      const e = runEvent(rec);
+      if (e?.kind === 'started' && e.prompt) events.push(`[user] ${String(e.prompt).slice(0, 1200)}`);
+      else if (e?.kind === 'assistant_message_committed' && e.text) events.push(`[agent] ${String(e.text).slice(0, 1800)}`);
+    }
+    const head = events.find((e) => e.startsWith('[user]'));
+    const tail = [];
+    let used = head?.length ?? 0;
+    for (let i = events.length - 1; i >= 0 && events[i] !== head; i--) {
+      if (used + events[i].length > maxChars) {
+        tail.unshift('… (earlier events omitted) …');
+        break;
+      }
+      tail.unshift(events[i]);
+      used += events[i].length + 1;
+    }
+    return { digest: [head, ...tail].filter(Boolean).join('\n'), events: events.length, edited: [] };
+  },
+
+  copySession: () => false,
+
+  attention: [
+    [/Doyoutrustthisworkspace\?/i, 'Folder trust prompt'],
+    [/Wouldyouliketo(run|allow)/i, 'Permission prompt'],
+  ],
+
+  /** Muse's menus: "Do you trust this workspace? … ⟩ 1  Trust and continue  2  Quit  Use Up/Down…". */
+  promptChoices(screen) {
+    const text = String(screen ?? '')
+      .replace(/\x1b\[(\d*)C/g, ' ')
+      .replace(ANSI, ' ')
+      .replace(/\s+/g, ' ');
+    const at = Math.max(text.lastIndexOf('Would you like'), text.lastIndexOf('Do you trust this workspace'));
+    if (at < 0) return { question: '', choices: [] };
+    const tail = text.slice(at);
+    const question = (/^(.*?\?)/.exec(tail)?.[1] ?? '').slice(0, 200);
+    const choices = new Map();
+    for (const m of tail.matchAll(/(?:⟩\s*)?\b(\d)\.?\s+(.+?)(?=\s+(?:⟩\s*)?\d\.?\s+[A-Z]|\s+Use Up\/Down|\s+Esc |$)/g)) {
+      if (!choices.has(m[1])) choices.set(m[1], m[2].trim().slice(0, 100));
+    }
+    return { question, choices: [...choices.entries()].sort(([a], [b]) => a - b).map(([key, label]) => ({ key, label })) };
+  },
+
+  /** Nothing to save: each launch passes --trust-workspace (trust for that run only). */
+  trust: () => false,
+
+  /** One-shot in the read-only profile (no writes or side-effecting commands), no web tools, not logged; the prompt is the last argument. */
+  oneShotArgs: (config, { model, prompt = '', extra = [] } = {}) => ['exec', ...extra, '--no-session-log', '--permission-profile', ':read-only', '--disable-web-tools', ...(model ? ['--model', model] : []), '--', prompt],
+  oneShotStdin: false,
+  // `muse exec` takes options only after the subcommand, configured extra arguments included.
+  oneShotExtra: true,
+
+  stripEnv: [],
+};

package/src/manager.js

@@ -8,6 +8,8 @@ import { expandHome, paths } from './config.js';
 import { DEFAULT_ENGINE, ENGINES, engineOf, installed, notInstalled } from './engines/index.js';
 import {
   DOC_KINDS,
+  diagramsOnly,
+  diagramsPrompt,
   briefDir,
   briefPath,
   briefPrompt,
@@ -33,11 +35,24 @@ const SUMMARIES = {
   insights: { field: 'insights', prompt: insightsPrompt },
   ...Object.fromEntries(Object.keys(DOC_KINDS).map((k) => [k, { doc: k, prompt: (ctx) => docPrompt(k, ctx) }])),
   humanai: { doc: 'humanai', run: 'runHumanAi' },
+  diagrams: { doc: 'diagrams', run: 'runDiagrams' },
 };
 /** Read / write where a summary of `kind` is kept on the agent record. */
 const getSummary = (agent, kind) => (SUMMARIES[kind].doc ? agent.docs?.[kind] : agent[SUMMARIES[kind].field]);
 const summaryPatch = (agent, kind, value) =>
   SUMMARIES[kind].doc ? { docs: { ...agent.docs, [kind]: value } } : { [SUMMARIES[kind].field]: value };
+
+/** The folders of a repo with how many files each holds, two levels deep: a map for drawing it. */
+async function repoLayout(dir) {
+  const files = (await git.run('git', ['ls-files'], { cwd: dir, timeout: 20_000 })).split('\n').filter(Boolean);
+  const counts = new Map();
+  for (const f of files) {
+    const parts = f.split('/');
+    const key = parts.length > 2 ? `${parts[0]}/${parts[1]}/` : parts.length === 2 ? `${parts[0]}/` : f;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts].slice(0, 150).map(([k, n]) => (k.endsWith('/') ? `${k} (${n} files)` : k)).join('\n');
+}
 import { spawn } from 'node:child_process';
 import * as git from './git.js';
 import { conflictMessage, findConflicts, related, repoKey, summarize as summarizeConflicts } from './conflicts.js';
@@ -847,15 +862,15 @@ export class AgentManager extends EventEmitter {
         resume = true;
       }
     }
-    const args = engine.launchArgs({
-      ...this.launchOptions(agent),
-      sessionId: sid,
-      resume,
-      name: agent.name,
-      // A team member's first message is its first step, not just the problem.
-      prompt: resume ? (handoff ? handoffMessage(agent) : null) : (agent.kickoff ?? agent.intent),
-    });
+    // A team member's first message is its first step, not just the problem.
+    const prompt = resume ? (handoff ? handoffMessage(agent) : null) : (agent.kickoff ?? agent.intent);
+    const args = engine.launchArgs({ ...this.launchOptions(agent), sessionId: sid, resume, name: agent.name, prompt });
     const proc = this.spawnAgent(agent, agent.workdir, args);
+    // Engines whose resume takes no message get it typed once the session is idle.
+    if (resume && prompt && engine.supports.resumePrompt === false) {
+      if (!this.outbox.has(agent.id)) this.outbox.set(agent.id, []);
+      this.outbox.get(agent.id).unshift({ text: prompt, source: 'system', at: now() });
+    }
 
     const session = agent.sessions.find((s) => s.id === sid);
     if (session) {
@@ -1102,7 +1117,8 @@ export class AgentManager extends EventEmitter {
         done.dispose();
         resolve(this.view(this.store.get(agent.id) ?? agent));
       });
-      rt.pty.kill('SIGHUP');
+      // A hangup, as when a terminal closes, unless the engine shuts down cleanly on another signal.
+      rt.pty.kill(engineOf(agent).stopSignal ?? 'SIGHUP');
       rt.killTimer = setTimeout(() => rt.pty?.kill('SIGKILL'), timeoutMs);
     });
   }
@@ -1168,7 +1184,7 @@ export class AgentManager extends EventEmitter {
   }
 
   childEnv(agent) {
-    const env = { ...process.env, ...(agent ? { AGENTMGR_AGENT_ID: agent.id } : {}), TERM: 'xterm-256color', COLORTERM: 'truecolor' };
+    const env = { ...process.env, ...(agent ? { AGENTMGR_AGENT_ID: agent.id } : {}), TERM: 'xterm-256color', COLORTERM: 'truecolor', AGENTMGR_TERMINAL: '1' };
     for (const key of STRIP_ENV) delete env[key];
     return env;
   }
@@ -1926,8 +1942,10 @@ export class AgentManager extends EventEmitter {
 
   /** One tool-less, read-only call to an engine; resolves to its text output. */
   oneShot(agent, text, { engine, model, timeoutMs = 300_000 }) {
-    // Some engines take the prompt as an argument instead of on stdin.
-    const args = [...engine.extraArgs(this.config), ...engine.oneShotArgs(this.config, { model, prompt: text })];
+    // Some engines take the prompt as an argument instead of on stdin, and some need their extra
+    // arguments after a subcommand (oneShotExtra: they place them).
+    const extra = engine.extraArgs(this.config);
+    const args = engine.oneShotExtra ? engine.oneShotArgs(this.config, { model, prompt: text, extra }) : [...extra, ...engine.oneShotArgs(this.config, { model, prompt: text })];
     return new Promise((resolve, reject) => {
       const child = spawn(engine.bin(this.config), args, { cwd: paths.home, env: this.childEnv(agent), stdio: ['pipe', 'pipe', 'pipe'] });
       let out = '';
@@ -1945,6 +1963,37 @@ export class AgentManager extends EventEmitter {
     });
   }
 
+  /** Diagrams only: the problem and its solution drawn from the documents already written and the live context. */
+  async runDiagrams(agent, ctx) {
+    const cur0 = this.store.get(agent.id) ?? agent;
+    const written = [
+      ...['analysis', 'design', 'flow', 'proposal'].map((k) => [DOC_KINDS[k].title, cur0.docs?.[k]?.markdown]),
+      ['Implementation plan', cur0.planReview?.markdown],
+      ['Explanation', cur0.explanation?.markdown],
+    ].filter(([, md]) => md);
+    const documents = written.map(([title, md]) => `<document title="${title}">\n${md.slice(0, 12_000)}\n</document>`).join('\n');
+    const repoMap = agent.workdir ? await repoLayout(agent.workdir).catch(() => '') : '';
+    const writer = this.writerFor(agent);
+    const markdown = diagramsOnly(await this.oneShot(agent, diagramsPrompt({ ...ctx, documents, repoMap }), writer));
+    const cur = this.store.get(agent.id);
+    if (!cur) return null;
+    const from = written.map(([title]) => title);
+    return this.view(
+      this.patch(
+        agent.id,
+        summaryPatch(cur, 'diagrams', {
+          markdown,
+          from,
+          writer: `${writer.engine.label}${writer.model ? ` (${writer.model})` : ''}`,
+          at: now(),
+          briefUpdatedAt: cur.brief?.updatedAt ?? null,
+          pending: false,
+          error: null,
+        }),
+      ),
+    );
+  }
+
   /** Human vs AI: the writer splits and answers the open questions, then another model double-checks it. */
   async runHumanAi(agent, ctx) {
     const writer = this.writerFor(agent);