From bbe84d40494ac8540e9457faf67b4bc66cc33dcb Mon Sep 17 00:00:00 2001
From: DevMando <codefilez@gmail.com>
Date: Wed, 9 Sep 2026 20:55:14 -0700
Subject: [PATCH 1/2] Show agent shell commands in a read-only terminal tab
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The agent's commands were invisible while they ran: a long build was a
single truncated status line for its whole duration, then a wall of finished
output.

Give each agent a read-only tab in the terminal panel, fed by the engine's
new command output sink. Deliberately NOT a shared pseudo-terminal: the
agent keeps running commands through captured pipes, which is what keeps
stdout and stderr separate, keeps the output free of escape sequences, and
leaves a real exit code to report. Routing the agent through a PTY to make
it visible would trade all three away for cursor control the model has no
use for, plus a second writer racing the user for one stdin. This is a
fan-out of lines that already existed, so it costs the agent nothing.

AgentCommandLog buffers per agent from launch, because the terminal panel is
built lazily — without it, an agent that built before the panel was ever
opened would show an empty tab, which is the case the feature exists for. It
holds more than the model's 5000-character copy, so the tail of a long build
stays visible. Trimming lands on a line boundary: cutting mid-escape would
leave half an SGR code to colour everything after it.

AgentCommandFormat renders the lifecycle and strips control characters from
command output, so a tool that emits VT when it isn't talking to a terminal
can't clear the log someone is reading.

Tabs never steal focus — an agent building while you type in a shell must
not yank the panel away — so the title accents instead. Closing a tab clears
that agent's buffer, so it isn't replayed on the next command.
---
 CHANGELOG.md                                  |  10 ++
 MandoCode                                     |   2 +-
 .../AgentCommandOutputTests.cs                | 160 ++++++++++++++++++
 .../MandoCode.Desktop.Tests.csproj            |   4 +-
 .../Assets/web/terminal/terminal.js           |  37 ++--
 .../Controls/TerminalPanel.xaml.cs            | 117 +++++++++++--
 src/MandoCode.Desktop/MainWindow.Tabs.cs      |   6 +-
 src/MandoCode.Desktop/MainWindow.Terminal.cs  |  55 +++++-
 .../Services/AgentCommandFormat.cs            |  71 ++++++++
 .../Services/AgentCommandLog.cs               |  87 ++++++++++
 .../Services/AgentSession.cs                  |  10 +-
 11 files changed, 533 insertions(+), 26 deletions(-)
 create mode 100644 src/MandoCode.Desktop.Tests/AgentCommandOutputTests.cs
 create mode 100644 src/MandoCode.Desktop/Services/AgentCommandFormat.cs
 create mode 100644 src/MandoCode.Desktop/Services/AgentCommandLog.cs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1790c2b..3b63e1f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,16 @@ for every approved plan. Desktop's version follows the engine generation, so it
 0.15.0.
 
 ### Added
+- **Watch the agent's shell commands run.** The terminal panel gains a read-only tab per agent
+  showing every command that agent runs — the command and the folder it runs in, its output line by
+  line as it arrives, and whether it finished, failed, or was killed for taking too long. A long
+  build is no longer ninety seconds of silence. The tab is deliberately read-only: the agent's
+  commands still run through captured pipes rather than a terminal, so nothing about what the model
+  receives, how commands are timed out, or how they report their exit code changes. The view keeps
+  more scrollback than the model is given, so the tail of a long build is visible even though the
+  model's copy is truncated. Output is recorded from launch, so opening the panel after a build
+  still shows it. A tab never steals focus while you are working in a shell — its title accents
+  instead — and closing one discards that agent's recorded output.
 - **PDFs open in the preview pane.** Selecting a PDF in the Explorer shows it in the browser's own
   viewer — scroll, zoom, search, print — instead of only offering to open it in another
   application. This is for reading: a PDF's text and structure are not reachable through the page
diff --git a/MandoCode b/MandoCode
index fe8eb6d..f4e0556 160000
--- a/MandoCode
+++ b/MandoCode
@@ -1 +1 @@
-Subproject commit fe8eb6d897c8c8ffd0652e91ea6f7973d9f7f8b6
+Subproject commit f4e055692d6de39c29b7a80dc17d3c6e4503c559
diff --git a/src/MandoCode.Desktop.Tests/AgentCommandOutputTests.cs b/src/MandoCode.Desktop.Tests/AgentCommandOutputTests.cs
new file mode 100644
index 0000000..392cff8
--- /dev/null
+++ b/src/MandoCode.Desktop.Tests/AgentCommandOutputTests.cs
@@ -0,0 +1,160 @@
+using System.Text.RegularExpressions;
+using MandoCode.Desktop.Services;
+using Xunit;
+
+namespace MandoCode.Desktop.Tests;
+
+/// <summary>
+/// The agent output tab is a read-only mirror of what the agent runs. These cover the two host-side
+/// pieces that decide what actually reaches xterm: how a command's lifecycle is rendered, and how
+/// the buffer that survives until someone opens the panel is kept.
+/// </summary>
+public class AgentCommandOutputTests
+{
+    // \u001b, not \x1b: C# hex escapes are variable-length and greedily eat any hex
+    // digit that follows, so "\x1b" next to one silently becomes a different character.
+    private const char Esc = '\u001b';
+
+    /// <summary>Complete SGR colour sequences, removed so what remains can be checked for damage.</summary>
+    private static string StripSgr(string s) => Regex.Replace(s, @"\u001b\[[0-9;]*m", "");
+
+    // ---- Formatting -------------------------------------------------------------
+
+    [Fact]
+    public void HeaderShowsTheCommandAndWhereItRuns()
+    {
+        // The folder matters: an agent runs in ITS project root, which is not necessarily the one
+        // the user is looking at, and two agents share this panel.
+        var header = AgentCommandFormat.Header("dotnet build", @"C:\src\project");
+
+        Assert.Contains("dotnet build", StripSgr(header));
+        Assert.Contains(@"C:\src\project", StripSgr(header));
+    }
+
+    [Fact]
+    public void StderrIsDistinguishableFromStdout()
+    {
+        var stdout = AgentCommandFormat.Line("all good", isError: false);
+        var stderr = AgentCommandFormat.Line("all good", isError: true);
+
+        Assert.NotEqual(stdout, stderr);
+        Assert.Equal("all good\r\n", stdout);           // no decoration on the common case
+        Assert.Equal("all good", StripSgr(stderr).TrimEnd('\r', '\n'));
+    }
+
+    [Fact]
+    public void SuccessFailureAndKillReadDifferently()
+    {
+        // A non-zero exit means the command ran and disagreed with you; a kill means it never got
+        // to finish. Someone watching has to be able to tell those apart at a glance.
+        var ok = StripSgr(AgentCommandFormat.Footer(0, null));
+        var failed = StripSgr(AgentCommandFormat.Footer(1, null));
+        var killed = StripSgr(AgentCommandFormat.Footer(null, "idle 30s with no output"));
+
+        Assert.Contains("exit 0", ok);
+        Assert.Contains("exit 1", failed);
+        Assert.Contains("killed", killed);
+        Assert.Contains("idle 30s with no output", killed);
+        Assert.NotEqual(ok, failed);
+    }
+
+    [Fact]
+    public void CommandOutputCannotDriveTheDisplay()
+    {
+        // A tool that emits VT even when it is not talking to a terminal could otherwise clear the
+        // screen or move the cursor, wiping the log someone is reading. The escape is defanged,
+        // and the visible text is kept.
+        var line = AgentCommandFormat.Line("\u001b[2Jwiped\u001b[Hagain", isError: false);
+
+        Assert.DoesNotContain(Esc, (IEnumerable<char>)line);
+        Assert.Contains("wiped", line);
+        Assert.Contains("again", line);
+    }
+
+    [Fact]
+    public void OneLineOfOutputStaysOneLine()
+    {
+        // Embedded newlines would let a single line forge the header/footer structure around it,
+        // and would desynchronise the display from the line count the model was given.
+        var line = AgentCommandFormat.Line("first\nsecond\rthird", isError: false);
+
+        Assert.Equal("firstsecondthird\r\n", line);
+    }
+
+    [Fact]
+    public void TabsSurviveBecauseTheyAreAlignment()
+    {
+        Assert.Equal("a\tb\r\n", AgentCommandFormat.Line("a\tb", isError: false));
+    }
+
+    // ---- Buffering --------------------------------------------------------------
+
+    [Fact]
+    public void RecordsForAViewThatIsNotOpenYet()
+    {
+        // The whole reason the log buffers: the terminal panel is built lazily, so an agent that
+        // builds before the user opens it must still have something to show.
+        var log = new AgentCommandLog();
+
+        log.CommandStarted("git status", @"C:\src");
+        log.CommandOutput("nothing to commit", isError: false);
+        log.CommandFinished(0, null);
+
+        var snapshot = StripSgr(log.Snapshot());
+        Assert.Contains("git status", snapshot);
+        Assert.Contains("nothing to commit", snapshot);
+        Assert.Contains("exit 0", snapshot);
+    }
+
+    [Fact]
+    public void LiveSubscribersSeeExactlyWhatIsBuffered()
+    {
+        var log = new AgentCommandLog();
+        var live = "";
+        log.Appended += text => live += text;
+
+        log.CommandStarted("ls", @"C:\src");
+        log.CommandOutput("file.txt", isError: false);
+        log.CommandFinished(0, null);
+
+        Assert.Equal(log.Snapshot(), live);
+    }
+
+    [Fact]
+    public void ClearDropsWhatTheUserDismissed()
+    {
+        var log = new AgentCommandLog();
+        log.CommandOutput("old news", isError: false);
+
+        log.Clear();
+
+        Assert.Equal("", log.Snapshot());
+    }
+
+    [Fact]
+    public void BufferStaysBoundedAndKeepsTheNewestOutput()
+    {
+        var log = new AgentCommandLog();
+        for (int i = 0; i < 4000; i++)
+            log.CommandOutput($"line {i} " + new string('x', 100), isError: false);
+
+        var snapshot = log.Snapshot();
+        Assert.True(snapshot.Length <= AgentCommandLog.MaxBufferedChars,
+            $"buffer grew to {snapshot.Length}");
+        Assert.Contains("line 3999", snapshot);
+        Assert.DoesNotContain("line 0 ", snapshot);
+    }
+
+    [Fact]
+    public void TrimmingNeverLeavesHalfAnEscapeSequence()
+    {
+        // Cutting at an exact character count would routinely land mid-sequence, and half an SGR
+        // code replayed into xterm colours everything after it until something else resets. The
+        // buffer is trimmed to a line boundary to avoid that.
+        var log = new AgentCommandLog();
+        for (int i = 0; i < 4000; i++)
+            log.CommandOutput($"error {i} " + new string('e', 100), isError: true);   // every line coloured
+
+        Assert.DoesNotContain(Esc, (IEnumerable<char>)StripSgr(log.Snapshot()));
+    }
+}
diff --git a/src/MandoCode.Desktop.Tests/MandoCode.Desktop.Tests.csproj b/src/MandoCode.Desktop.Tests/MandoCode.Desktop.Tests.csproj
index ac3d4c8..965e803 100644
--- a/src/MandoCode.Desktop.Tests/MandoCode.Desktop.Tests.csproj
+++ b/src/MandoCode.Desktop.Tests/MandoCode.Desktop.Tests.csproj
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
@@ -58,6 +58,8 @@
     <Compile Include="..\MandoCode.Desktop\Services\TranscriptJournal.cs" Link="src\TranscriptJournal.cs" />
     <Compile Include="..\MandoCode.Desktop\Services\ModelNoticeReplay.cs" Link="src\ModelNoticeReplay.cs" />
     <Compile Include="..\MandoCode.Desktop\Services\StableCollection.cs" Link="src\StableCollection.cs" />
+    <Compile Include="..\MandoCode.Desktop\Services\AgentCommandFormat.cs" Link="src\AgentCommandFormat.cs" />
+    <Compile Include="..\MandoCode.Desktop\Services\AgentCommandLog.cs" Link="src\AgentCommandLog.cs" />
     <Compile Include="..\MandoCode.Desktop\Services\ConversationLog.cs" Link="src\ConversationLog.cs" />
     <!-- History's full-text matching + snippet extraction. Pure (text in, match out); the file reads
          and caching live in ConversationTextCache, which is NOT compiled here because it touches
diff --git a/src/MandoCode.Desktop/Assets/web/terminal/terminal.js b/src/MandoCode.Desktop/Assets/web/terminal/terminal.js
index 2d8c8a2..e5c0845 100644
--- a/src/MandoCode.Desktop/Assets/web/terminal/terminal.js
+++ b/src/MandoCode.Desktop/Assets/web/terminal/terminal.js
@@ -16,6 +16,13 @@
     try { window.chrome.webview.postMessage(JSON.stringify(obj)); } catch (e) { }
   }
 
+  // A blinking-less, invisible cursor: xterm still tracks a cursor position in a read-only
+  // buffer, and showing it would promise a text entry point that does not exist.
+  function readOnlyTheme(t) {
+    const base = makeTheme(t);
+    return Object.assign({}, base, { cursor: "transparent", cursorAccent: base.background });
+  }
+
   function makeTheme(t) {
     return t || {
       background: "#0b0b12",
@@ -31,7 +38,9 @@
     };
   }
 
-  function create(id, cols, rows, theme) {
+  // readOnly backs the agent-output tab: same renderer, but nothing is sent back to C# and no
+  // cursor is drawn, because there is no process on the other end for a keystroke to reach.
+  function create(id, cols, rows, theme, readOnly) {
     if (terms[id]) return;
 
     const el = document.createElement("div");
@@ -47,20 +56,24 @@
       fontFamily: "Cascadia Mono, Consolas, 'Courier New', monospace",
       fontSize: 13,
       lineHeight: 1.1,
-      theme: makeTheme(theme),
+      theme: readOnly ? readOnlyTheme(theme) : makeTheme(theme),
       scrollback: 5000,
-      allowProposedApi: true
+      allowProposedApi: true,
+      disableStdin: !!readOnly
     });
 
     const fit = new FitAddonNS.FitAddon();
     term.loadAddon(fit);
     term.open(el);
 
-    // Keystrokes / pasted text -> C# -> shell stdin.
-    term.onData(d => post({ type: "data", id: id, data: d }));
-    term.onBinary(d => post({ type: "data", id: id, data: d }));
+    // Keystrokes / pasted text -> C# -> shell stdin. Never wired for a read-only terminal, so
+    // input is dropped here rather than travelling to C# to be ignored there.
+    if (!readOnly) {
+      term.onData(d => post({ type: "data", id: id, data: d }));
+      term.onBinary(d => post({ type: "data", id: id, data: d }));
+    }
 
-    terms[id] = { term: term, fit: fit, el: el };
+    terms[id] = { term: term, fit: fit, el: el, readOnly: !!readOnly };
   }
 
   function write(id, b64) {
@@ -89,7 +102,8 @@
 
   function focus(id) {
     const t = terms[id];
-    if (t) setTimeout(() => { try { t.term.focus(); } catch (e) { } }, 0);
+    if (!t || t.readOnly) return;   // nothing to type into; leave the caret where the user put it
+    setTimeout(() => { try { t.term.focus(); } catch (e) { } }, 0);
   }
 
   function dispose(id) {
@@ -117,7 +131,10 @@
   }
 
   function setTheme(theme) {
-    for (const k in terms) terms[k].term.options.theme = makeTheme(theme);
+    for (const k in terms) {
+      terms[k].term.options.theme =
+        terms[k].readOnly ? readOnlyTheme(theme) : makeTheme(theme);
+    }
   }
 
   // C# -> JS (host.PostWebMessageAsJson -> parsed object on e.data).
@@ -125,7 +142,7 @@
     const m = e.data;
     if (!m || !m.type) return;
     switch (m.type) {
-      case "create": create(m.id, m.cols, m.rows, m.theme); break;
+      case "create": create(m.id, m.cols, m.rows, m.theme, m.readOnly); break;
       case "write": write(m.id, m.data); break;
       case "show": show(m.id); break;
       case "fit": fit(m.id); break;
diff --git a/src/MandoCode.Desktop/Controls/TerminalPanel.xaml.cs b/src/MandoCode.Desktop/Controls/TerminalPanel.xaml.cs
index 3951c67..7ce2a8d 100644
--- a/src/MandoCode.Desktop/Controls/TerminalPanel.xaml.cs
+++ b/src/MandoCode.Desktop/Controls/TerminalPanel.xaml.cs
@@ -1,4 +1,4 @@
-using System.IO;
+using System.IO;
 using System.Text.Json;
 using MandoCode.Desktop.Services;
 using Microsoft.UI.Xaml;
@@ -19,11 +19,20 @@ public sealed partial class TerminalPanel : UserControl
     private sealed class TerminalTab
     {
         public required string Id { get; init; }
-        public required ShellSpec Shell { get; init; }
-        public required TerminalSession Session { get; init; }
+
+        // Both null for the agent-output tab: it has no shell and no process behind it. That is
+        // what makes it read-only — there is nothing for a keystroke to be written to.
+        public ShellSpec? Shell { get; init; }
+        public TerminalSession? Session { get; init; }
         public required Border Header { get; init; }
         public required TextBlock Title { get; init; }
 
+        /// <summary>The agent this tab mirrors, for an output tab; null for a real shell.</summary>
+        public string? AgentKey { get; init; }
+
+        /// <summary>New output arrived while this tab was not the visible one.</summary>
+        public bool Unread;
+
         // Output coalescing: the read thread appends here; a single UI-thread flush
         // drains it, so a burst of small reads becomes one write across the WebView bridge.
         public readonly List<byte[]> Pending = new();
@@ -46,6 +55,19 @@ private sealed class TerminalTab
     /// <summary>Raised when the user toggles maximize/restore (host owns the row height).</summary>
     public event EventHandler? MaximizeRequested;
 
+    /// <summary>
+    /// Raised once the xterm host is live and tabs can be created. The host waits for this before
+    /// replaying agent scrollback, so nothing has to be buffered twice — <see cref="AgentCommandLog"/>
+    /// already holds it until someone can display it.
+    /// </summary>
+    public event EventHandler? Ready;
+
+    /// <summary>Raised with an agent key when the user closes that agent's output tab.</summary>
+    public event EventHandler<string>? AgentOutputClosed;
+
+    /// <summary>True once the xterm host has reported in and <see cref="WriteAgentOutput"/> works.</summary>
+    public bool IsReady => _webReady;
+
     /// <summary>Updates the maximize button's glyph/tooltip to reflect the current state.</summary>
     public void SetMaximized(bool maximized)
     {
@@ -193,11 +215,66 @@ private void MaybeShowCliHint(string id)
         });
     }
 
-    private (Border header, TextBlock title) BuildTabHeader(string id, ShellSpec shell)
+    // ---- Agent output tabs (read-only) -----------------------------------------
+
+    /// <summary>
+    /// Writes an agent's shell-command output into that agent's own read-only tab, creating the tab
+    /// on first use. The text is already terminal-formatted by <see cref="AgentCommandFormat"/>.
+    ///
+    /// <para>Creating a tab never switches to it. An agent running a build while you are typing in
+    /// a shell must not steal the panel out from under you — the tab title accents instead, and you
+    /// look when you want to.</para>
+    ///
+    /// <para>Must be called on the UI thread, and only once <see cref="IsReady"/> is true; output
+    /// arriving earlier stays in the agent's <see cref="AgentCommandLog"/> until the host replays
+    /// it.</para>
+    /// </summary>
+    public void WriteAgentOutput(string agentKey, string tabTitle, string text)
+    {
+        if (!_webReady || string.IsNullOrEmpty(text)) return;
+
+        var tab = EnsureAgentTab(agentKey, tabTitle);
+        if (tab == null) return;
+
+        Post(new { type = "write", id = tab.Id, data = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(text)) });
+
+        if (_activeId != tab.Id)
+        {
+            tab.Unread = true;
+            ApplyTabStyle(tab, active: false);
+        }
+    }
+
+    /// <summary>Renames an agent's output tab in place, so a renamed agent stays recognizable.</summary>
+    public void RenameAgentOutput(string agentKey, string tabTitle)
+    {
+        var tab = _tabs.Values.FirstOrDefault(t => t.AgentKey == agentKey);
+        if (tab != null) tab.Title.Text = tabTitle;
+    }
+
+    private TerminalTab? EnsureAgentTab(string agentKey, string tabTitle)
+    {
+        var existing = _tabs.Values.FirstOrDefault(t => t.AgentKey == agentKey);
+        if (existing != null) return existing;
+
+        string id = "a" + (++_tabCounter);
+        var (header, title) = BuildTabHeader(id, shell: null, outputTitle: tabTitle);
+        var tab = new TerminalTab { Id = id, Header = header, Title = title, AgentKey = agentKey };
+        _tabs[id] = tab;
+        TabStrip.Children.Add(header);
+
+        // readOnly tells xterm not to accept or forward input at all; there is no process behind
+        // this tab for a keystroke to reach.
+        Post(new { type = "create", id, cols = 80, rows = 24, readOnly = true });
+        ApplyTabStyle(tab, active: false);
+        return tab;
+    }
+
+    private (Border header, TextBlock title) BuildTabHeader(string id, ShellSpec? shell, string? outputTitle = null)
     {
         var title = new TextBlock
         {
-            Text = shell.DisplayName,
+            Text = outputTitle ?? shell?.DisplayName ?? "Shell",
             FontSize = 12,
             VerticalAlignment = VerticalAlignment.Center,
         };
@@ -218,7 +295,9 @@ private void MaybeShowCliHint(string id)
             Spacing = 6,
             VerticalAlignment = VerticalAlignment.Center,
         };
-        content.Children.Add(new FontIcon { Glyph = "", FontSize = 11, VerticalAlignment = VerticalAlignment.Center, Opacity = 0.7 });
+        // A distinct glyph for the read-only output tab, so it is not mistaken for a
+        // shell you can type in before the cursor ever gets there.
+        content.Children.Add(new FontIcon { Glyph = outputTitle != null ? "\uE9D9" : "\uE756", FontSize = 11, VerticalAlignment = VerticalAlignment.Center, Opacity = 0.7 });
         content.Children.Add(title);
         content.Children.Add(closeButton);
 
@@ -236,8 +315,9 @@ private void MaybeShowCliHint(string id)
 
     private void SwitchTo(string id)
     {
-        if (!_tabs.ContainsKey(id)) return;
+        if (!_tabs.TryGetValue(id, out var target)) return;
         _activeId = id;
+        target.Unread = false;
         Post(new { type = "show", id });
 
         foreach (var t in _tabs.Values)
@@ -250,17 +330,28 @@ private void ApplyTabStyle(TerminalTab tab, bool active)
             ? (Brush)Application.Current.Resources["MandoBackgroundBrush"]
             : new SolidColorBrush(Microsoft.UI.Colors.Transparent);
         tab.Title.Opacity = active ? 1.0 : 0.65;
+        // An agent can produce output while you are looking at a different tab. Accenting the
+        // title is the only cue that anything happened — the panel deliberately never switches
+        // tabs on its own, which would yank you out of a shell mid-command.
+        tab.Title.Foreground = tab.Unread && !active
+            ? (Brush)Application.Current.Resources["MandoAccentBrush"]
+            : (Brush)Application.Current.Resources["MandoTextBrush"];
     }
 
     private void CloseTab(string id)
     {
         if (!_tabs.TryGetValue(id, out var tab)) return;
 
-        try { tab.Session.Dispose(); } catch { }
+        try { tab.Session?.Dispose(); } catch { }
         Post(new { type = "dispose", id });
         TabStrip.Children.Remove(tab.Header);
         _tabs.Remove(id);
 
+        // Closing an output tab is a dismissal, not a pause: tell the host so it clears that
+        // agent's scrollback. Otherwise the next command would reopen the tab and replay
+        // everything the user just closed.
+        if (tab.AgentKey != null) AgentOutputClosed?.Invoke(this, tab.AgentKey);
+
         if (_activeId == id) _activeId = null;
 
         if (_tabs.Count == 0)
@@ -335,11 +426,15 @@ private void OnWebMessage(object? sender, Microsoft.Web.WebView2.Core.CoreWebVie
                 case "ready":
                     _webReady = true;
                     if (_tabs.Count == 0) AddTab(ShellCatalog.Default());
+                    Ready?.Invoke(this, EventArgs.Empty);
                     break;
 
                 case "data":
+                    // Null session = the agent-output tab. xterm is told not to send input for it,
+                    // so this is belt-and-braces: a keystroke that arrives anyway is dropped rather
+                    // than being written into some other tab's shell.
                     if (TryGetTab(root, out var t) && t != null)
-                        t.Session.Write(root.GetProperty("data").GetString() ?? "");
+                        t.Session?.Write(root.GetProperty("data").GetString() ?? "");
                     break;
 
                 case "resize":
@@ -347,7 +442,7 @@ private void OnWebMessage(object? sender, Microsoft.Web.WebView2.Core.CoreWebVie
                     {
                         short cols = (short)root.GetProperty("cols").GetInt32();
                         short rows = (short)root.GetProperty("rows").GetInt32();
-                        rt.Session.Resize(cols, rows);
+                        rt.Session?.Resize(cols, rows);
                     }
                     break;
             }
@@ -412,7 +507,7 @@ public void ShutDown()
     {
         foreach (var tab in _tabs.Values)
         {
-            try { tab.Session.Dispose(); } catch { }
+            try { tab.Session?.Dispose(); } catch { }
         }
         _tabs.Clear();
     }
diff --git a/src/MandoCode.Desktop/MainWindow.Tabs.cs b/src/MandoCode.Desktop/MainWindow.Tabs.cs
index 38309f8..9b63d89 100644
--- a/src/MandoCode.Desktop/MainWindow.Tabs.cs
+++ b/src/MandoCode.Desktop/MainWindow.Tabs.cs
@@ -1,4 +1,4 @@
-using System.Collections.ObjectModel;
+using System.Collections.ObjectModel;
 using System.Diagnostics;
 using System.Text.Json;
 using MandoCode.Models;
@@ -106,6 +106,10 @@ private ChatTabEntry CreateChatTab(string? projectRoot = null, string? title = n
         TabStrip.Children.Add(header);
         WireHeader(entry);
 
+        // A new agent gets its output tab too, but only if the terminal is already up. Otherwise
+        // its log records quietly and AttachAllAgentOutputs picks it up when the panel opens.
+        AttachAgentOutput(session);
+
         SelectTab(entry);
         if (SnapshotsPanelOpen) PopulateSnapshots();   // an agent exists now → re-enable Import
         if (NotesPanelOpen) PopulateNotes();           // a new note would now be filed under this folder
diff --git a/src/MandoCode.Desktop/MainWindow.Terminal.cs b/src/MandoCode.Desktop/MainWindow.Terminal.cs
index 48812aa..59cf75f 100644
--- a/src/MandoCode.Desktop/MainWindow.Terminal.cs
+++ b/src/MandoCode.Desktop/MainWindow.Terminal.cs
@@ -1,4 +1,4 @@
-using System.Collections.ObjectModel;
+using System.Collections.ObjectModel;
 using System.Diagnostics;
 using System.Text.Json;
 using MandoCode.Models;
@@ -52,9 +52,62 @@ private Controls.TerminalPanel EnsureTerminal()
         _terminal.WorkingDirectoryProvider = () => ActiveChat?.Session.ProjectRoot.ProjectRoot;
         _terminal.CloseRequested += (_, _) => CloseTerminalPanel();
         _terminal.MaximizeRequested += (_, _) => ToggleMaximizeTerminal();
+
+        // Agent output tabs can only be built once the xterm host is live. Until then every
+        // agent's AgentCommandLog is holding its own scrollback, so nothing is lost by waiting.
+        _terminal.Ready += (_, _) => AttachAllAgentOutputs();
+        _terminal.AgentOutputClosed += (_, key) => FindSessionByKey(key)?.CommandLog.Clear();
+        if (_terminal.IsReady) AttachAllAgentOutputs();
         return _terminal;
     }
 
+    // ============================================================
+    // Agent command output (read-only terminal tabs)
+    // ============================================================
+
+    /// <summary>Agents already piped into the terminal panel, so a second call can't double-subscribe
+    /// and echo every line twice.</summary>
+    private readonly HashSet<string> _agentOutputAttached = new();
+
+    /// <summary>
+    /// The panel is shared by every agent, so each one's output needs a stable key to own a tab
+    /// with. PersistKey is that key: it already survives restarts and renames.
+    /// </summary>
+    private static string AgentOutputKey(AgentSession session) => session.PersistKey;
+
+    private AgentSession? FindSessionByKey(string key) =>
+        _tabs.FirstOrDefault(t => AgentOutputKey(t.View.Session) == key)?.View.Session;
+
+    private void AttachAllAgentOutputs()
+    {
+        foreach (var tab in _tabs) AttachAgentOutput(tab.View.Session);
+    }
+
+    /// <summary>
+    /// Pipes one agent's command log into the terminal panel: replays what it has already recorded,
+    /// then follows it live. Safe to call repeatedly — only the first call for an agent subscribes.
+    /// No-op until the panel exists and its xterm host is up; <see cref="AttachAllAgentOutputs"/>
+    /// runs then and catches up whatever was missed.
+    /// </summary>
+    private void AttachAgentOutput(AgentSession session)
+    {
+        var panel = _terminal;
+        if (panel == null || !panel.IsReady) return;
+
+        var key = AgentOutputKey(session);
+        if (!_agentOutputAttached.Add(key)) return;
+
+        var title = session.Title;
+        var backlog = session.CommandLog.Snapshot();
+        if (!string.IsNullOrEmpty(backlog)) panel.WriteAgentOutput(key, title, backlog);
+
+        // Raised on the command's own reader threads — hop to the UI thread before touching the
+        // WebView. The log keeps its copy either way, so a dropped enqueue costs a live update,
+        // never the scrollback.
+        session.CommandLog.Appended += text =>
+            DispatcherQueue.TryEnqueue(() => _terminal?.WriteAgentOutput(key, session.Title, text));
+    }
+
     private void NavTerminal_Click(object sender, RoutedEventArgs e) => ToggleTerminal();
 
     private void ToggleTerminal()
diff --git a/src/MandoCode.Desktop/Services/AgentCommandFormat.cs b/src/MandoCode.Desktop/Services/AgentCommandFormat.cs
new file mode 100644
index 0000000..eb2305b
--- /dev/null
+++ b/src/MandoCode.Desktop/Services/AgentCommandFormat.cs
@@ -0,0 +1,71 @@
+namespace MandoCode.Desktop.Services;
+
+/// <summary>
+/// Renders an agent shell command's lifecycle as terminal text — a prompt-style header, the
+/// command's own lines, and a closing status. Kept separate from <see cref="AgentCommandLog"/>
+/// and free of any UI type so the exact bytes that reach xterm can be asserted in tests.
+///
+/// <para>Colors are set with SGR escapes rather than the app's theme brushes because this text is
+/// written into an xterm buffer, which knows nothing about XAML resources. The 256-color codes
+/// chosen here match the terminal theme in <c>terminal.js</c>.</para>
+/// </summary>
+public static class AgentCommandFormat
+{
+    private const string Dim = "\x1b[38;5;244m";
+    private const string Gold = "\x1b[38;5;214m";
+    private const string Red = "\x1b[38;5;203m";
+    private const string Green = "\x1b[38;5;114m";
+    private const string Reset = "\x1b[0m";
+
+    /// <summary>
+    /// The line announcing a command, styled like a shell prompt so the log reads the way a
+    /// terminal session does. The working directory is shown because an agent's commands run in
+    /// its own project root, which is not necessarily the folder the user is looking at.
+    /// </summary>
+    public static string Header(string command, string workingDirectory) =>
+        $"\r\n{Dim}{Sanitize(workingDirectory)}{Reset}\r\n{Gold}${Reset} {Sanitize(command)}\r\n";
+
+    /// <summary>
+    /// One line of command output. stderr is colored rather than prefixed: the model's copy uses an
+    /// "[err]" prefix because it reads plain text, but a person watching a terminal reads color
+    /// faster and the prefix would just eat width.
+    /// </summary>
+    public static string Line(string line, bool isError) =>
+        isError ? $"{Red}{Sanitize(line)}{Reset}\r\n" : $"{Sanitize(line)}\r\n";
+
+    /// <summary>
+    /// How the command ended. A non-zero exit and a kill are shown differently on purpose — one
+    /// means the command ran and disagreed with you, the other means it never got to finish.
+    /// </summary>
+    public static string Footer(int? exitCode, string? killReason)
+    {
+        if (killReason != null)
+            return $"{Gold}■ killed: {Sanitize(killReason)}{Reset}\r\n";
+        if (exitCode == 0)
+            return $"{Green}✓ exit 0{Reset}\r\n";
+        return $"{Red}✗ exit {exitCode}{Reset}\r\n";
+    }
+
+    /// <summary>
+    /// Strips control characters that would let a command's output drive the display rather than
+    /// appear in it — a stray "clear screen" or cursor-home from a tool that emits VT even when it
+    /// is not talking to a terminal would otherwise wipe the log someone is reading. Tabs are kept
+    /// (they are alignment, and every compiler emits them); ESC is neutered so no sequence can
+    /// start. Note this is display hygiene, not a security boundary: the same text has already
+    /// gone to the model verbatim.
+    /// </summary>
+    private static string Sanitize(string text)
+    {
+        if (string.IsNullOrEmpty(text)) return "";
+        Span<char> buffer = text.Length <= 512 ? stackalloc char[text.Length] : new char[text.Length];
+        int n = 0;
+        foreach (var c in text)
+        {
+            if (c == '\t') { buffer[n++] = c; continue; }
+            if (c == '\x1b') { buffer[n++] = '^'; continue; }
+            if (char.IsControl(c)) continue;   // CR/LF included: this renders exactly one line
+            buffer[n++] = c;
+        }
+        return new string(buffer[..n]);
+    }
+}
diff --git a/src/MandoCode.Desktop/Services/AgentCommandLog.cs b/src/MandoCode.Desktop/Services/AgentCommandLog.cs
new file mode 100644
index 0000000..de2c5b7
--- /dev/null
+++ b/src/MandoCode.Desktop/Services/AgentCommandLog.cs
@@ -0,0 +1,87 @@
+using System.Text;
+using MandoCode.Services;
+
+namespace MandoCode.Desktop.Services;
+
+/// <summary>
+/// One agent's shell-command activity, kept as terminal-ready text so the terminal panel can show
+/// it live. Attached to that agent's <see cref="MandoCode.Services.AIService"/> as an
+/// <see cref="ICommandOutputSink"/>; the engine calls into it as commands run.
+///
+/// <para>Why this buffers rather than only forwarding: the terminal panel is built lazily, on first
+/// open. Without a buffer, an agent that ran a build before the user opened the panel would show an
+/// empty tab — precisely the case the feature exists for. Whoever attaches replays
+/// <see cref="Snapshot"/> first, then follows <see cref="Appended"/>.</para>
+///
+/// <para><b>Threading:</b> the engine raises output on the command's reader threads, so every
+/// member here is under one lock and <see cref="Appended"/> fires on whatever thread produced the
+/// output. Subscribers marshal to the UI thread themselves.</para>
+/// </summary>
+public sealed class AgentCommandLog : ICommandOutputSink
+{
+    /// <summary>
+    /// Retained scrollback, in characters. Generous because it holds full build output that the
+    /// model's own copy truncates, and bounded because a watch loop or a chatty test run would
+    /// otherwise grow it without limit for as long as the agent lives.
+    /// </summary>
+    public const int MaxBufferedChars = 256 * 1024;
+
+    private readonly object _lock = new();
+    private readonly StringBuilder _buffer = new();
+
+    /// <summary>Fresh terminal text, already formatted. Raised on arbitrary threads.</summary>
+    public event Action<string>? Appended;
+
+    public void CommandStarted(string command, string workingDirectory) =>
+        Append(AgentCommandFormat.Header(command, workingDirectory));
+
+    public void CommandOutput(string line, bool isError) =>
+        Append(AgentCommandFormat.Line(line, isError));
+
+    public void CommandFinished(int? exitCode, string? killReason) =>
+        Append(AgentCommandFormat.Footer(exitCode, killReason));
+
+    /// <summary>Everything retained so far — replayed into a view that attaches late.</summary>
+    public string Snapshot()
+    {
+        lock (_lock) { return _buffer.ToString(); }
+    }
+
+    /// <summary>Drops the retained scrollback. Used when the user closes the agent's output tab,
+    /// so reopening it later starts clean rather than replaying what they dismissed.</summary>
+    public void Clear()
+    {
+        lock (_lock) { _buffer.Clear(); }
+    }
+
+    private void Append(string text)
+    {
+        lock (_lock)
+        {
+            _buffer.Append(text);
+            if (_buffer.Length > MaxBufferedChars) TrimOldest();
+        }
+        Appended?.Invoke(text);
+    }
+
+    /// <summary>
+    /// Discards from the front, then advances to just past the next newline. Cutting at the exact
+    /// character count would routinely land mid-escape-sequence, and half an SGR code replayed into
+    /// xterm colors everything after it until something else resets — so the buffer is trimmed to a
+    /// line boundary even though that drops a little more than strictly necessary.
+    /// </summary>
+    private void TrimOldest()
+    {
+        var excess = _buffer.Length - MaxBufferedChars;
+        for (int i = excess; i < _buffer.Length; i++)
+        {
+            if (_buffer[i] == '\n')
+            {
+                _buffer.Remove(0, i + 1);
+                return;
+            }
+        }
+        // One line longer than the whole budget: no boundary to keep, so start over.
+        _buffer.Clear();
+    }
+}
diff --git a/src/MandoCode.Desktop/Services/AgentSession.cs b/src/MandoCode.Desktop/Services/AgentSession.cs
index 07e8e48..ff47cc2 100644
--- a/src/MandoCode.Desktop/Services/AgentSession.cs
+++ b/src/MandoCode.Desktop/Services/AgentSession.cs
@@ -65,6 +65,10 @@ public string Title
     public TokenTrackingService Tokens { get; }
     public PlanHandoff PlanHandoff { get; }
     public SkillLoader Skills { get; }
+
+    /// <summary>This agent's shell-command activity, as terminal-ready text. Always recording, so
+    /// the terminal panel can show work that ran before the user opened it.</summary>
+    public AgentCommandLog CommandLog { get; }
     public McpApprovalGate McpGate { get; }
     public AIService Ai { get; }
     public TaskPlannerService Planner { get; }
@@ -117,7 +121,11 @@ public AgentSession(
         Skills = new SkillLoader(Config, ProjectRoot);
         McpGate = new McpApprovalGate(Config);
 
-        Ai = new AIService(ProjectRoot, Config, Tokens, PlanHandoff, Skills, mcpManager, McpGate, spinner);
+        // Attached once, here: the engine hands the sink to the filesystem plugin on every agent
+        // rebuild, so it survives model switches, settings changes, and folder changes without the
+        // host re-attaching anything.
+        CommandLog = new AgentCommandLog();
+        Ai = new AIService(ProjectRoot, Config, Tokens, PlanHandoff, Skills, mcpManager, McpGate, spinner, CommandLog);
         PreviewTools = new DesktopPreviewTools(ProjectRoot) { RequireTabId = true, ImageSink = new AgentImageSink(new AiServiceAdapter(Ai)) };
         Ai.SetHostTools([
             Microsoft.Extensions.AI.AIFunctionFactory.Create(PreviewTools.ListBrowserFrames, new Microsoft.Extensions.AI.AIFunctionFactoryOptions { Name = "list_browser_frames" }),

From 90050f18562ca273b6520583a29fa6b2f8f17118 Mon Sep 17 00:00:00 2001
From: DevMando <codefilez@gmail.com>
Date: Wed, 9 Sep 2026 21:42:24 -0700
Subject: [PATCH 2/2] Advertise agent output on the rail, and open the panel on
 it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The output tab was undiscoverable. It lives inside a panel that is closed by
default, so the only way to learn it exists was to open the terminal for an
unrelated reason and notice a tab you didn't create.

Badge the rail's terminal button when an agent has produced output the user
hasn't seen. The rail is always visible, so the cue arrives where they are
already looking, at the moment it becomes true. It is driven by command
activity rather than by panel state on purpose: the panel isn't built until
first opened, and the first command a user's agent runs is precisely the one
that has to advertise a tab they don't know about.

The dot pulses only while a command is in flight and goes still once it
finishes, so motion means 'work is happening now' and a still dot means
'output is waiting' — two facts one badge was otherwise conflating. Unhurried
on purpose: a fast blink reads as an alarm, and this is an invitation. The
storyboard is stopped rather than hidden when idle, and FlatMotion themes get
the still dot in both states rather than a pulse they've opted out of.

Track in-flight commands with a counter, not a flag: a plan step can have one
command running while another closes out, and a flag would stop the pulse
with work still going. Clamped at zero so an unbalanced finish can't wedge
the rail pulsing forever.

Also fixes the landing tab. The panel creates a starter shell when it opens
and agent tabs are attached after that, so following the badge dropped the
user on an empty prompt with the tab they came for hidden behind it. Opening
with unread output now brings that tab to the front. Gated on unread rather
than on a tab existing, so reaching for Ctrl+` to get a shell still gets one.
Wired into both the first open and every reopen, since Ready fires once.
---
 CHANGELOG.md                                  |  6 +-
 .../AgentCommandOutputTests.cs                | 60 +++++++++++++++++
 .../Controls/TerminalPanel.xaml.cs            | 27 ++++++++
 .../MainWindow.Navigation.cs                  | 31 ++++++++-
 src/MandoCode.Desktop/MainWindow.Tabs.cs      |  1 +
 src/MandoCode.Desktop/MainWindow.Terminal.cs  | 64 ++++++++++++++++++-
 src/MandoCode.Desktop/MainWindow.xaml         | 41 +++++++++++-
 .../Services/AgentCommandLog.cs               | 32 +++++++++-
 8 files changed, 253 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3b63e1f..8b75459 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,7 +25,11 @@ for every approved plan. Desktop's version follows the engine generation, so it
   more scrollback than the model is given, so the tail of a long build is visible even though the
   model's copy is truncated. Output is recorded from launch, so opening the panel after a build
   still shows it. A tab never steals focus while you are working in a shell — its title accents
-  instead — and closing one discards that agent's recorded output.
+  instead — and closing one discards that agent's recorded output. The terminal button on the rail
+  carries a dot when an agent has produced output you have not seen, so the tab is discoverable
+  without opening the panel to find it: the dot pulses while a command is actually running and goes
+  still once it finishes, and following it opens the panel directly on that agent's output rather
+  than on an empty shell. Themes that switch off motion get the still dot in both cases.
 - **PDFs open in the preview pane.** Selecting a PDF in the Explorer shows it in the browser's own
   viewer — scroll, zoom, search, print — instead of only offering to open it in another
   application. This is for reading: a PDF's text and structure are not reachable through the page
diff --git a/src/MandoCode.Desktop.Tests/AgentCommandOutputTests.cs b/src/MandoCode.Desktop.Tests/AgentCommandOutputTests.cs
index 392cff8..96f299a 100644
--- a/src/MandoCode.Desktop.Tests/AgentCommandOutputTests.cs
+++ b/src/MandoCode.Desktop.Tests/AgentCommandOutputTests.cs
@@ -120,6 +120,66 @@ public void LiveSubscribersSeeExactlyWhatIsBuffered()
         Assert.Equal(log.Snapshot(), live);
     }
 
+    // ---- Running state (drives the rail's pulse) --------------------------------
+
+    [Fact]
+    public void RunningIsTrueOnlyBetweenStartAndFinish()
+    {
+        var log = new AgentCommandLog();
+        Assert.False(log.IsRunning);
+
+        log.CommandStarted("dotnet build", @"C:\src");
+        Assert.True(log.IsRunning);
+
+        log.CommandFinished(0, null);
+        Assert.False(log.IsRunning);
+    }
+
+    [Fact]
+    public void OverlappingCommandsStayRunningUntilTheLastOneEnds()
+    {
+        // Counted, not a flag: a plan step can have one command in flight while another closes out,
+        // and a flag would report idle — stopping the pulse — while work was still going.
+        var log = new AgentCommandLog();
+
+        log.CommandStarted("first", @"C:\src");
+        log.CommandStarted("second", @"C:\src");
+        log.CommandFinished(0, null);
+
+        Assert.True(log.IsRunning);
+        log.CommandFinished(0, null);
+        Assert.False(log.IsRunning);
+    }
+
+    [Fact]
+    public void RunningChangedFiresOnlyOnRealTransitions()
+    {
+        var log = new AgentCommandLog();
+        var seen = new List<bool>();
+        log.RunningChanged += running => seen.Add(running);
+
+        log.CommandStarted("first", @"C:\src");
+        log.CommandStarted("second", @"C:\src");
+        log.CommandFinished(0, null);
+        log.CommandFinished(0, null);
+
+        Assert.Equal(new[] { true, false }, seen);
+    }
+
+    [Fact]
+    public void AnUnbalancedFinishCannotLeaveTheRailPulsingForever()
+    {
+        // The sink contract pairs every finish with a start, but the rail animates off this state,
+        // so a stray call must not drive the counter negative and wedge it "running".
+        var log = new AgentCommandLog();
+
+        log.CommandFinished(0, null);
+        log.CommandStarted("later", @"C:\src");
+        log.CommandFinished(0, null);
+
+        Assert.False(log.IsRunning);
+    }
+
     [Fact]
     public void ClearDropsWhatTheUserDismissed()
     {
diff --git a/src/MandoCode.Desktop/Controls/TerminalPanel.xaml.cs b/src/MandoCode.Desktop/Controls/TerminalPanel.xaml.cs
index 7ce2a8d..9e50117 100644
--- a/src/MandoCode.Desktop/Controls/TerminalPanel.xaml.cs
+++ b/src/MandoCode.Desktop/Controls/TerminalPanel.xaml.cs
@@ -68,6 +68,17 @@ private sealed class TerminalTab
     /// <summary>True once the xterm host has reported in and <see cref="WriteAgentOutput"/> works.</summary>
     public bool IsReady => _webReady;
 
+    /// <summary>Raised when the visible tab changes, so the host can drop an unread cue.</summary>
+    public event EventHandler? ActiveTabChanged;
+
+    /// <summary>
+    /// True when the visible tab is an agent's output rather than a shell. The distinction matters
+    /// for the rail's unread badge: having the panel open on a shell tab is not the same as having
+    /// read what an agent printed.
+    /// </summary>
+    public bool ActiveTabIsAgentOutput =>
+        _activeId != null && _tabs.TryGetValue(_activeId, out var active) && active.AgentKey != null;
+
     /// <summary>Updates the maximize button's glyph/tooltip to reflect the current state.</summary>
     public void SetMaximized(bool maximized)
     {
@@ -245,6 +256,20 @@ public void WriteAgentOutput(string agentKey, string tabTitle, string text)
         }
     }
 
+    /// <summary>
+    /// Brings an agent output tab to the front, if one exists. Called when the panel is opened with
+    /// output waiting: the panel always creates a starter shell on first open, so without this the
+    /// user follows the rail badge, lands on an empty prompt, and has to hunt for the tab they came
+    /// for. Returns false when there is no output tab to show, leaving the shell in front.
+    /// </summary>
+    public bool FocusAgentOutput()
+    {
+        var tab = _tabs.Values.FirstOrDefault(t => t.AgentKey != null);
+        if (tab == null) return false;
+        SwitchTo(tab.Id);
+        return true;
+    }
+
     /// <summary>Renames an agent's output tab in place, so a renamed agent stays recognizable.</summary>
     public void RenameAgentOutput(string agentKey, string tabTitle)
     {
@@ -322,6 +347,8 @@ private void SwitchTo(string id)
 
         foreach (var t in _tabs.Values)
             ApplyTabStyle(t, active: t.Id == id);
+
+        ActiveTabChanged?.Invoke(this, EventArgs.Empty);
     }
 
     private void ApplyTabStyle(TerminalTab tab, bool active)
diff --git a/src/MandoCode.Desktop/MainWindow.Navigation.cs b/src/MandoCode.Desktop/MainWindow.Navigation.cs
index 0540c0e..028d335 100644
--- a/src/MandoCode.Desktop/MainWindow.Navigation.cs
+++ b/src/MandoCode.Desktop/MainWindow.Navigation.cs
@@ -1,4 +1,4 @@
-using System.Collections.ObjectModel;
+using System.Collections.ObjectModel;
 using System.Diagnostics;
 using System.Text.Json;
 using MandoCode.Models;
@@ -147,6 +147,35 @@ private void RefreshNavIcons()
         NavNotesIcon.Foreground = NotesPanelOpen ? accent : normal;
         NavTerminalIcon.Foreground = _terminalOpen ? accent : normal;
 
+        // Unread agent output is cleared the moment the user is actually looking at an agent's
+        // tab — not merely when the panel is open, since it may well be open on a shell.
+        if (_terminalOpen && (_terminal?.ActiveTabIsAgentOutput ?? false)) _agentOutputUnread = false;
+        var showBadge = _agentOutputUnread;
+        NavTerminalBadge.Visibility = showBadge ? Visibility.Visible : Visibility.Collapsed;
+
+        // Motion means "a command is running right now"; a still dot means "output is waiting".
+        // FlatMotion themes opt out of animation entirely, so they get the still dot in both cases
+        // rather than a pulse the theme has said it doesn't want.
+        var pulse = showBadge && AnyAgentCommandRunning && !ThemeManager.Current.FlatMotion;
+        if (pulse)
+        {
+            if (!_navTerminalBadgePulsing) { _navTerminalBadgePulsing = true; NavTerminalBadgePulse.Begin(); }
+        }
+        else if (_navTerminalBadgePulsing)
+        {
+            // Stopped, not just hidden: an animation left running behind a collapsed element keeps
+            // the compositor busy for no visible benefit.
+            _navTerminalBadgePulsing = false;
+            NavTerminalBadgePulse.Stop();
+            NavTerminalBadge.Opacity = 1.0;
+        }
+
+        ToolTipService.SetToolTip(NavTerminal, showBadge
+            ? (AnyAgentCommandRunning
+                ? "Terminal — agent is running a command (Ctrl+`)"
+                : "Terminal — agent output waiting (Ctrl+`)")
+            : "Terminal — open a shell, or watch agent commands (Ctrl+`)");
+
         // MCP acts on the selected agent, so it needs one open. Settings no longer does — it edits
         // the defaults for FUTURE agents, which is exactly the thing you might want to set up before
         // opening any. (An agent's own settings are behind its gear icon instead.)
diff --git a/src/MandoCode.Desktop/MainWindow.Tabs.cs b/src/MandoCode.Desktop/MainWindow.Tabs.cs
index 9b63d89..3984a4f 100644
--- a/src/MandoCode.Desktop/MainWindow.Tabs.cs
+++ b/src/MandoCode.Desktop/MainWindow.Tabs.cs
@@ -109,6 +109,7 @@ private ChatTabEntry CreateChatTab(string? projectRoot = null, string? title = n
         // A new agent gets its output tab too, but only if the terminal is already up. Otherwise
         // its log records quietly and AttachAllAgentOutputs picks it up when the panel opens.
         AttachAgentOutput(session);
+        WatchAgentOutputForBadge(session);
 
         SelectTab(entry);
         if (SnapshotsPanelOpen) PopulateSnapshots();   // an agent exists now → re-enable Import
diff --git a/src/MandoCode.Desktop/MainWindow.Terminal.cs b/src/MandoCode.Desktop/MainWindow.Terminal.cs
index 59cf75f..b326a3a 100644
--- a/src/MandoCode.Desktop/MainWindow.Terminal.cs
+++ b/src/MandoCode.Desktop/MainWindow.Terminal.cs
@@ -55,8 +55,16 @@ private Controls.TerminalPanel EnsureTerminal()
 
         // Agent output tabs can only be built once the xterm host is live. Until then every
         // agent's AgentCommandLog is holding its own scrollback, so nothing is lost by waiting.
-        _terminal.Ready += (_, _) => AttachAllAgentOutputs();
+        _terminal.Ready += (_, _) =>
+        {
+            AttachAllAgentOutputs();
+            // Agent tabs only exist after the line above, and the panel has already put a starter
+            // shell in front by now — so the choice of landing tab has to be made here, once
+            // there's something to choose between.
+            ShowAgentOutputIfWaiting();
+        };
         _terminal.AgentOutputClosed += (_, key) => FindSessionByKey(key)?.CommandLog.Clear();
+        _terminal.ActiveTabChanged += (_, _) => RefreshNavIcons();   // may clear the unread badge
         if (_terminal.IsReady) AttachAllAgentOutputs();
         return _terminal;
     }
@@ -69,6 +77,45 @@ private Controls.TerminalPanel EnsureTerminal()
     /// and echo every line twice.</summary>
     private readonly HashSet<string> _agentOutputAttached = new();
 
+    /// <summary>Agents whose badge subscription is live. Separate from <see cref="_agentOutputAttached"/>
+    /// on purpose: that one waits for the terminal panel, and this one must NOT — the badge exists
+    /// to advertise a panel the user has not opened.</summary>
+    private readonly HashSet<string> _agentOutputWatched = new();
+
+    /// <summary>An agent has printed something the user has not looked at yet.</summary>
+    private bool _agentOutputUnread;
+
+    /// <summary>Whether the badge's pulse storyboard is currently running.</summary>
+    private bool _navTerminalBadgePulsing;
+
+    /// <summary>True while ANY open agent has a shell command in flight — the rail is one badge for
+    /// every agent, so it pulses if any of them is working.</summary>
+    private bool AnyAgentCommandRunning => _tabs.Any(t => t.View.Session.CommandLog.IsRunning);
+
+    /// <summary>
+    /// Lights the rail's terminal badge whenever an agent runs a command the user isn't watching.
+    /// Subscribes on agent creation regardless of whether the terminal has ever been opened, which
+    /// is the whole point — the first command a user's agent runs is the one that has to advertise
+    /// the tab they don't know about.
+    /// </summary>
+    private void WatchAgentOutputForBadge(AgentSession session)
+    {
+        if (!_agentOutputWatched.Add(AgentOutputKey(session))) return;
+
+        session.CommandLog.Appended += _ => DispatcherQueue.TryEnqueue(() =>
+        {
+            // Already watching this agent's tab? Then it isn't unread — it's just being read.
+            if (_terminalOpen && (_terminal?.ActiveTabIsAgentOutput ?? false)) return;
+            if (_agentOutputUnread) return;   // already lit; skip the rail refresh
+            _agentOutputUnread = true;
+            RefreshNavIcons();
+        });
+
+        // Start and stop are what drive the pulse, and they bracket the output rather than riding
+        // along with it — a command can run for a minute without printing a line.
+        session.CommandLog.RunningChanged += _ => DispatcherQueue.TryEnqueue(RefreshNavIcons);
+    }
+
     /// <summary>
     /// The panel is shared by every agent, so each one's output needs a stable key to own a tab
     /// with. PersistKey is that key: it already survives restarts and renames.
@@ -83,6 +130,19 @@ private void AttachAllAgentOutputs()
         foreach (var tab in _tabs) AttachAgentOutput(tab.View.Session);
     }
 
+    /// <summary>
+    /// Lands the newly-opened panel on an agent's output when that is what the user came to see.
+    /// Gated on unread output rather than merely on a tab existing, so someone reaching for Ctrl+`
+    /// to get a shell still gets one — the redirect only happens when the rail was advertising
+    /// something. Not focus-stealing: the panel was just opened by hand, and choosing which tab it
+    /// opens on is not the same as switching tabs out from under someone mid-command.
+    /// </summary>
+    private void ShowAgentOutputIfWaiting()
+    {
+        if (!_agentOutputUnread) return;
+        if (_terminal?.FocusAgentOutput() == true) RefreshNavIcons();   // now read: clears the badge
+    }
+
     /// <summary>
     /// Pipes one agent's command log into the terminal panel: replays what it has already recorded,
     /// then follows it live. Safe to call repeatedly — only the first call for an agent subscribes.
@@ -121,6 +181,8 @@ private void OpenTerminalPanel()
         var term = EnsureTerminal();
         if (_terminalOpen) { term.FocusActive(); return; }
         _terminalOpen = true;
+        // Ready fires once, on the very first open. Every reopen after that comes through here.
+        ShowAgentOutputIfWaiting();
         RefreshNavIcons();
 
         term.Visibility = Visibility.Visible;
diff --git a/src/MandoCode.Desktop/MainWindow.xaml b/src/MandoCode.Desktop/MainWindow.xaml
index 3793073..585b88a 100644
--- a/src/MandoCode.Desktop/MainWindow.xaml
+++ b/src/MandoCode.Desktop/MainWindow.xaml
@@ -209,10 +209,45 @@
         <StackPanel Grid.Row="1" Padding="4,8" Spacing="6">
             <Border Background="{StaticResource MandoBorderBrush}" Height="1"
                     HorizontalAlignment="Stretch" Margin="8,2" Opacity="0.6"/>
+            <!-- The badge is the ONLY way the agent-output tab is discoverable: the panel it lives
+                 in is closed by default, so without a cue on the always-visible rail nobody learns
+                 the tab exists. Driven by command activity rather than by panel state, because the
+                 panel isn't even built until first opened — and the very first command a user runs
+                 is exactly the one that most needs to advertise itself. Cleared in RefreshNavIcons
+                 once they're actually looking at an agent's tab. -->
             <Button x:Name="NavTerminal" Click="NavTerminal_Click" Padding="10,8" Background="Transparent"
-                    BorderThickness="0" HorizontalAlignment="Stretch"
-                    ToolTipService.ToolTip="Terminal — open a shell (Ctrl+`)">
-                <FontIcon x:Name="NavTerminalIcon" Glyph="&#xE756;" FontSize="16"/>
+                    BorderThickness="0" HorizontalAlignment="Stretch">
+                <Grid>
+                    <Grid.Resources>
+                        <!-- Runs ONLY while a command is actually in flight, and is stopped the
+                             moment it isn't — a permanently animating rail is exactly the kind of
+                             perpetual repaint the transcript and terminal both avoid. Deliberately
+                             unhurried: a fast blink reads as an error demanding attention, and this
+                             is an invitation, not an alarm. Opacity plus a slight swell so it
+                             registers in peripheral vision without pulling the eye off the chat. -->
+                        <Storyboard x:Name="NavTerminalBadgePulse" RepeatBehavior="Forever" AutoReverse="True">
+                            <DoubleAnimation Storyboard.TargetName="NavTerminalBadge" Storyboard.TargetProperty="Opacity"
+                                             From="1.0" To="0.35" Duration="0:0:0.85" EnableDependentAnimation="True"/>
+                            <DoubleAnimation Storyboard.TargetName="NavTerminalBadgeScale" Storyboard.TargetProperty="ScaleX"
+                                             From="1.0" To="1.35" Duration="0:0:0.85" EnableDependentAnimation="True"/>
+                            <DoubleAnimation Storyboard.TargetName="NavTerminalBadgeScale" Storyboard.TargetProperty="ScaleY"
+                                             From="1.0" To="1.35" Duration="0:0:0.85" EnableDependentAnimation="True"/>
+                        </Storyboard>
+                    </Grid.Resources>
+                    <FontIcon x:Name="NavTerminalIcon" Glyph="&#xE756;" FontSize="16"/>
+                    <!-- Sits over the glyph's top-right corner. The ring is the rail's own
+                         background, so the dot stays legible against the glyph's strokes. -->
+                    <Ellipse x:Name="NavTerminalBadge" Visibility="Collapsed"
+                             Width="8" Height="8" Margin="0,-4,-6,0"
+                             HorizontalAlignment="Right" VerticalAlignment="Top"
+                             RenderTransformOrigin="0.5,0.5"
+                             Fill="{StaticResource MandoAccentBrush}"
+                             Stroke="{StaticResource MandoBackgroundBrush}" StrokeThickness="1.5">
+                        <Ellipse.RenderTransform>
+                            <ScaleTransform x:Name="NavTerminalBadgeScale"/>
+                        </Ellipse.RenderTransform>
+                    </Ellipse>
+                </Grid>
             </Button>
         </StackPanel>
         </Grid>
diff --git a/src/MandoCode.Desktop/Services/AgentCommandLog.cs b/src/MandoCode.Desktop/Services/AgentCommandLog.cs
index de2c5b7..71d5e1b 100644
--- a/src/MandoCode.Desktop/Services/AgentCommandLog.cs
+++ b/src/MandoCode.Desktop/Services/AgentCommandLog.cs
@@ -1,4 +1,4 @@
-using System.Text;
+using System.Text;
 using MandoCode.Services;
 
 namespace MandoCode.Desktop.Services;
@@ -29,17 +29,43 @@ public sealed class AgentCommandLog : ICommandOutputSink
     private readonly object _lock = new();
     private readonly StringBuilder _buffer = new();
 
+    private int _running;
+
     /// <summary>Fresh terminal text, already formatted. Raised on arbitrary threads.</summary>
     public event Action<string>? Appended;
 
-    public void CommandStarted(string command, string workingDirectory) =>
+    /// <summary>Raised when <see cref="IsRunning"/> flips. Raised on arbitrary threads.</summary>
+    public event Action<bool>? RunningChanged;
+
+    /// <summary>
+    /// True while at least one command is in flight. Lets the rail distinguish "work is happening
+    /// right now" from "output is sitting here unread" — the same badge means both, and only the
+    /// first deserves motion.
+    /// </summary>
+    public bool IsRunning => Volatile.Read(ref _running) > 0;
+
+    public void CommandStarted(string command, string workingDirectory)
+    {
+        // Counted rather than a bool: a plan step can have a command in flight while another is
+        // still closing out, and a bool would report idle the moment the first one finished.
+        if (Interlocked.Increment(ref _running) == 1) RunningChanged?.Invoke(true);
         Append(AgentCommandFormat.Header(command, workingDirectory));
+    }
 
     public void CommandOutput(string line, bool isError) =>
         Append(AgentCommandFormat.Line(line, isError));
 
-    public void CommandFinished(int? exitCode, string? killReason) =>
+    public void CommandFinished(int? exitCode, string? killReason)
+    {
         Append(AgentCommandFormat.Footer(exitCode, killReason));
+        // Clamped: a sink is only ever finished once per start, but an unbalanced call must not
+        // drive the counter negative and leave the rail pulsing forever.
+        if (Interlocked.Decrement(ref _running) <= 0)
+        {
+            Interlocked.Exchange(ref _running, 0);
+            RunningChanged?.Invoke(false);
+        }
+    }
 
     /// <summary>Everything retained so far — replayed into a view that attaches late.</summary>
     public string Snapshot()