npm - @serkanalgur/opencode-nexus - Versions diffs - 2.7.0 → 2.8.0 - Mend

@serkanalgur/opencode-nexus 2.7.0 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/index.js CHANGED Viewed

@@ -8478,6 +8478,9 @@ var DEFAULT_CONFIG = {
     enabled: true,
     port: 4747,
     host: "127.0.0.1"
+  },
+  notifications: {
+    enabled: true
   }
 };
@@ -8487,10 +8490,12 @@ class NexusConfigManager {
   storageConfig = null;
   loadInfo = null;
   dashboardBase;
-  constructor(dashboardBase) {
+  notificationsBase;
+  constructor(dashboardBase, notificationsBase) {
     this.projectConfig = null;
     this.globalConfig = null;
     this.dashboardBase = { ...DEFAULT_CONFIG.dashboard, ...dashboardBase };
+    this.notificationsBase = { ...DEFAULT_CONFIG.notifications, ...notificationsBase };
   }
   loadConfigs(basePath) {
     if (this.loadInfo === null)
@@ -8557,6 +8562,9 @@ class NexusConfigManager {
         enabled: this.storageConfig?.dashboard?.enabled ?? this.projectConfig?.dashboard?.enabled ?? this.globalConfig?.dashboard?.enabled ?? this.dashboardBase.enabled,
         port: this.storageConfig?.dashboard?.port ?? this.projectConfig?.dashboard?.port ?? this.globalConfig?.dashboard?.port ?? this.dashboardBase.port,
         host: this.storageConfig?.dashboard?.host ?? this.projectConfig?.dashboard?.host ?? this.globalConfig?.dashboard?.host ?? this.dashboardBase.host
+      },
+      notifications: {
+        enabled: this.storageConfig?.notifications?.enabled ?? this.projectConfig?.notifications?.enabled ?? this.globalConfig?.notifications?.enabled ?? this.notificationsBase.enabled
       }
     };
   }
@@ -8678,6 +8686,7 @@ class NexusConfigManager {
     result.budget = { ...current.budget };
     result.selfHealing = { ...current.selfHealing };
     result.dashboard = { ...current.dashboard };
+    result.notifications = { ...current.notifications };
     return result;
   }
   resetToDefaults() {
@@ -10819,7 +10828,12 @@ var dashboard_default = `<!DOCTYPE html>
       + ' (' + fmtElapsed(age) + ' ago)';
     $lastRefresh.textContent = text;
     $lastRefresh.className = 'last-refresh' + (age > STALE_AFTER_MS ? ' stale' : '');
-    $lastRefresh.title = 'Snapshot received at ' + fmtTime(new Date(lastStateReceivedAt).toISOString())
+    // The server's own stamp, verbatim, alongside the received-at time. The two
+    // are different claims — one is when the snapshot was made, the other when
+    // this page heard about it — and a \`title\` is where a raw timestamp belongs:
+    // the visible line stays readable while the exact value stays checkable.
+    $lastRefresh.title = 'state.lastUpdated ' + (lastStateUpdated || 'not reported')
+      + '; received at ' + fmtTime(new Date(lastStateReceivedAt).toISOString())
       + '. ' + (ws && ws.readyState === WebSocket.OPEN
           ? 'Auto-refresh asks the server every ' + (AUTO_REFRESH_INTERVAL / 1000) + 's.'
           : 'Not connected: this may be the last state the server sent.');
@@ -11023,6 +11037,24 @@ var dashboard_default = `<!DOCTYPE html>
     return String(err);
   }
+  /**
+   * A frame's own type, for an error message about that frame.
+   *
+   * Deliberately TOTAL: it is called from the render-failure path, where the
+   * page has already thrown once, so it must not be the thing that throws
+   * second. \`msg\` may be a non-object — a bare number, a string, \`null\` — so
+   * every step is narrowed through the same \`asObject\`/\`text\` gates the rest of
+   * the page uses rather than assumed. Mirrors \`handleMessage\`'s own
+   * \`msg.type || msg.event\` so the two cannot disagree about a frame's name.
+   */
+  function frameType(msg) {
+    var obj = asObject(msg);
+    if (obj === null) return 'untyped';
+    var type = text(obj.type);
+    if (type === null) type = text(obj.event);
+    return type === null ? 'untyped' : type;
+  }
   // ── Connection ──
   function setConnState(state) {
     $connBadge.className = 'connection-badge ' + state;
@@ -11068,11 +11100,34 @@ var dashboard_default = `<!DOCTYPE html>
       }
     };
+    // Parse and render are TWO failures with TWO owners, so they are caught
+    // separately and reported separately.
+    //
+    // A single \`try\` around both meant a \`TypeError\` thrown by this page's own
+    // renderer was reported as "Non-JSON frame from server" — which points a
+    // reader at the server for a bug that is entirely in this file, and does so
+    // with a message that is simply false about a frame that parsed perfectly
+    // well. That misdiagnosis is what sent the investigation the wrong way when
+    // \`renderState\` started throwing on every push.
+    //
+    // The render failure names the frame's own type, so a log line says which
+    // message could not be drawn, and it is logged as an error rather than as
+    // server-side information. The parse failure stays an \`info\` line: an
+    // unparseable frame IS news about the server.
     ws.onmessage = function(evt) {
+      var msg;
       try {
-        handleMessage(JSON.parse(evt.data));
+        msg = JSON.parse(evt.data);
       } catch (e) {
         addLog('info', '📩', 'Non-JSON frame from server: ' + errorText(e));
+        return;
+      }
+      try {
+        handleMessage(msg);
+      } catch (e) {
+        addLog('error', '⚠️', 'Page failed to render a ' + frameType(msg)
+          + ' frame (this is a bug in the page, not a bad frame from the server): '
+          + errorText(e));
       }
     };
@@ -11148,8 +11203,8 @@ var dashboard_default = `<!DOCTYPE html>
         break;
       case 'task:failed':
-        addLog('error', '❌', 'Task failed: ' + taskLabel(data) + ' — ' + errorOf(data));
-        addLogStream('error', 'FAIL', 'Task failed: ' + taskLabel(data) + ' — ' + errorOf(data));
+        addLog('error', '❌', 'Task failed: ' + taskFailedText(data));
+        addLogStream('error', 'FAIL', 'Task failed: ' + taskFailedText(data));
         break;
       case 'cost:delta':
@@ -11232,6 +11287,32 @@ var dashboard_default = `<!DOCTYPE html>
     return e === null ? 'no error message reported' : e;
   }
+  /**
+   * A \`task:failed\` line: which task, why, and how long it took.
+   *
+   * \`duration\` was on the event and unread. It is the one field that separates
+   * the two failures a reader has to tell apart — a task that failed
+   * immediately and one that ran for minutes and then failed are the same line
+   * of text without it, and only the second is a hang worth chasing. The
+   * spawn-failure emit site reports \`duration: 0\` and omits the agent, model and
+   * session entirely rather than fabricating them, so a zero here is a real
+   * "the spawn itself failed", not a missing reading; it is printed as such
+   * rather than as a dash that would read as unreported.
+   *
+   * The rest of the payload — \`role\`, \`agentId\`, \`model\`, \`sessionID\` — is
+   * deliberately not read here. It is all in the throttled state push within a
+   * second and rendered on the Tasks and Agents sections, so a log line
+   * repeating it would be a second, staler copy of the same numbers. The line's
+   * job is to name the task and the cause, which is what you act on.
+   */
+  function taskFailedText(d) {
+    var ms = num(d.duration);
+    return taskLabel(d) + ' — ' + errorOf(d)
+      + (ms === null ? '' : ms === 0
+          ? ' (failed before any work — the spawn itself did not complete)'
+          : ' (after ' + fmtMs(ms) + ')');
+  }
   function escalationText(d) {
     return taskLabel(d) + ' on agent ' + (text(d.agentId) || 'unreported') + ' — ' + errorOf(d)
       + ' (retries and model fallback are exhausted; notifying)';
@@ -11264,15 +11345,33 @@ var dashboard_default = `<!DOCTYPE html>
   }
   /**
-   * \`config:reloaded\` carries \`NexusConfigLoadInfo\`, so the useful part is which
-   * files were consulted, whether a session override is layered on top of them,
-   * and how many times this has loaded.
+   * \`config:reloaded\` carries \`NexusConfigLoadInfo\`. The useful part is not the
+   * timestamps.
+   *
+   * The line already said how many times this has loaded, when, and which files
+   * were consulted — and none of those answer the question a reader actually
+   * has, which is WHY it reloaded. A reload you did not cause is exactly the one
+   * worth explaining: \`initial\` is the process starting up, \`event\` is the
+   * filesystem watch firing, \`poll\` is the interval check noticing the same
+   * files changed. Without the trigger, a line appearing that nobody asked for
+   * reads as the orchestrator having changed its own mind.
+   *
+   * So the trigger leads, and the count of resolved models comes with it: after
+   * a reload the next question is always "did it pick up my change?", and a
+   * number of roles is the one thing that can be compared against the Models
+   * panel without reading the whole map back out of the config viewer.
    */
   function configReloadText(d) {
     var parts = [];
+    var trigger = text(d.trigger);
+    parts.push('trigger ' + (trigger === null ? 'unreported' : trigger));
     var count = num(d.loadCount);
     parts.push(count === null ? 'load count unreported' : 'load #' + fmtInt(count));
-    parts.push('loaded ' + fmtDateTime(d.loadedAt));
+    // The raw ISO, not a locale-formatted time. Every other line on this page
+    // carries raw server values, and a log line whose one timestamp is the only
+    // one a reader has to interpret by eye is the one they cannot grep.
+    var loadedAt = text(d.loadedAt);
+    parts.push('loaded ' + (loadedAt === null ? 'unreported' : loadedAt));
     if (typeof d.sessionOverride === 'boolean') {
       parts.push(d.sessionOverride ? 'session override layered on top of disk' : 'no session override');
     }
@@ -11280,6 +11379,15 @@ var dashboard_default = `<!DOCTYPE html>
     if (project !== null) parts.push('project ' + configFileText(project));
     var global = asObject(d.global);
     if (global !== null) parts.push('global ' + configFileText(global));
+    // The map itself is shown by the config viewer and the Models panel, so what
+    // the log line carries is its SIZE — the checkable figure — rather than a
+    // truncated copy of it.
+    var models = asObject(d.models);
+    if (models !== null) {
+      var roles = Object.keys(models);
+      parts.push(roles.length + ' role' + (roles.length === 1 ? '' : 's') + ' resolved'
+        + (roles.length === 0 ? ' (empty map)' : ''));
+    }
     return parts.join(' · ');
   }
@@ -11303,27 +11411,129 @@ var dashboard_default = `<!DOCTYPE html>
     return 'success';
   }
+  /**
+   * Which table priced this line, and which tier of it was selected.
+   *
+   * \`settledTier\` is on every \`cost:delta\`, and the page read none of it: each
+   * line showed an amount with nothing at all about where the amount came from.
+   * That matters because \`settledTier.pricing\` is a \`PricingSource\` —
+   * \`model-costs\` (a published price list for this model), \`fallback-table\` (a
+   * generic table, because this model is not in the list) or \`unknown-model\`.
+   *
+   * It is worth being precise about what this is and is not, because the page
+   * already has a measured/estimated distinction and it is easy to conflate the
+   * two. \`settledTier.pricing\` is about where the PRICE came from, not where
+   * the TOKEN COUNTS came from. The orchestrator reads the counts off a real
+   * session for this event, so the usage here is measured; what varies is
+   * whether the number was multiplied by this model's real price or by a
+   * stand-in. So the honest label is "priced by", never "estimated" — calling a
+   * fallback-priced figure "estimated" would be a different and wrong claim,
+   * and a \`$0.42\` off a generic table wearing a real price's clothes is exactly
+   * the confusion the Accounting panel and the unbilled bound exist to prevent
+   * on the other half of the page.
+   *
+   * \`threshold\` is the prompt size at which the tier table switches, and
+   * \`promptSizeAtSettlement\` is the size that selected the tier. Both are
+   * printed so a reader can see WHICH tier the amount was priced at rather than
+   * trusting that it was a sensible one. A null \`threshold\` is a real value and
+   * not a missing one: it is the base tier, which has no threshold to switch
+   * at, so it is named rather than reported as unreported.
+   *
+   * When \`settledTier\` itself is absent the line says so. The field is on the
+   * event, so its absence is a fact about this line, and omitting the clause
+   * would let a reader assume every line carries a price source when some do
+   * not.
+   */
+  function settledTierText(d) {
+    var tier = asObject(d.settledTier);
+    if (tier === null) return ' · price source NOT reported';
+    var threshold = num(tier.threshold);
+    var size = num(tier.promptSizeAtSettlement);
+    return ' · priced by ' + pricingSourceText(text(tier.pricing))
+      + ' at ' + (threshold === null ? 'the base tier' : 'the ' + fmtInt(threshold) + '-token tier')
+      + ' (' + (size === null ? 'prompt size at settlement unreported'
+        : fmtInt(size) + ' prompt tokens at settlement') + ')';
+  }
+  /**
+   * Plain words for a \`PricingSource\`.
+   *
+   * The server's own token is kept inside the string for every branch, so a
+   * source this build has never heard of is reported as unrecognised AND quoted
+   * rather than being quietly described as something it is not. That is the
+   * same rule the rest of the page follows for a value it does not recognise.
+   */
+  function pricingSourceText(source) {
+    if (source === 'model-costs') return "the model's published price list (" + source + ')';
+    if (source === 'fallback-table') {
+      return 'a FALLBACK price table, because this model is not in it (' + source + ')';
+    }
+    if (source === 'unknown-model') return 'an UNKNOWN-MODEL fallback price (' + source + ')';
+    return 'an unrecognised price source (' + (source === null ? 'unreported' : source) + ')';
+  }
   function costDeltaText(d) {
     var session = text(d.sessionID);
     var reason = text(d.reason);
     var delta = num(d.deltaCost);
+    var agent = text(d.agentId);
+    var model = text(d.model);
+    var tokens = num(d.deltaTokens);
+    // \`nodeId\` is deliberately NOT read: every emit site sets it to the same
+    // value as \`taskId\` (\`nodeId: ledger.taskId\`), so it is an alias rather
+    // than a second fact, and printing both would put two ids for one task on
+    // the line whenever they ever disagreed.
     var head = 'Session ' + (session === null ? 'unreported' : session)
-      + ' (' + taskLabel(d) + ')';
+      + (agent === null ? ' (agent unreported)' : ' on ' + agent)
+      + ' · ' + taskLabel(d)
+      + ' · ' + (model === null ? 'model unreported' : model);
+    // A dollar amount with no token count says nothing about magnitude — $0.25
+    // over three tokens and $0.25 over three million are the same string. The
+    // count is on the event and it is the only thing on this line that says how
+    // big the increment was.
+    var amount = ' · ' + (tokens === null ? 'token delta unreported' : fmtInt(tokens) + ' tok');
+    // A settlement can also have MOVED money after the fact. \`recordsAdjusted\`
+    // names which of the per-agent, per-task, history and performance records
+    // the increment was written into. That is worth saying on this page
+    // specifically, because the agent cost bars and the Spend card are built
+    // from exactly those records — so a line that rewrote them is the reason a
+    // total can move without a bill appearing, and saying nothing about it
+    // leaves the reader to conclude the numbers were wrong.
+    var corrections = '';
+    var adjusted = asObject(d.recordsAdjusted);
+    if (adjusted !== null) {
+      var moved = ['history', 'performance', 'node', 'agent'].filter(function(k) {
+        return adjusted[k] === true;
+      });
+      corrections = moved.length === 0
+        ? ' · no records adjusted'
+        : ' · corrected the ' + moved.join(', ') + ' record' + (moved.length === 1 ? '' : 's');
+    }
+    // A settlement that threw still bills. The line has to say the charge was
+    // made and the bookkeeping failed, because a dollar figure printed with no
+    // mention of the error beside it reads as a clean one.
+    var fault = text(d.error);
+    if (fault !== null) corrections += ' · SETTLEMENT ERROR: ' + fault;
     if (reason === 'abandoned') {
       var uncollected = asObject(d.uncollected);
       var lower = uncollected === null ? null : num(uncollected.observedUncollected);
       return head + ' ABANDONED — stopped collecting while still running; at least '
-        + fmt$(lower) + ' unbilled (lower bound)';
+        + fmt$(lower) + ' unbilled (lower bound)' + amount + corrections + settledTierText(d);
     }
     if (reason === 'shutdown') {
-      return head + ' charged at teardown, settlement unverified: ' + fmt$(delta);
+      return head + ' charged at teardown, settlement unverified: ' + fmt$(delta)
+        + amount + corrections + settledTierText(d);
     }
     if (reason === 'session-idle') {
       return head + ' went idle; settled ' + fmt$(delta) + ' (session total '
-        + fmt$(d.sessionTotalCost) + ')';
+        + fmt$(d.sessionTotalCost) + ')' + amount + corrections + settledTierText(d);
     }
     return head + ' ' + (reason === null ? 'reason unreported' : reason) + ': '
-      + fmt$(delta) + ' (session total ' + fmt$(d.sessionTotalCost) + ')';
+      + fmt$(delta) + ' (session total ' + fmt$(d.sessionTotalCost) + ')'
+      + amount + corrections + settledTierText(d);
   }
   // ── Render State ──
@@ -11339,6 +11549,28 @@ var dashboard_default = `<!DOCTYPE html>
     var totalSpent = num(state.totalSpent);
     var budgetRemaining = num(state.budgetRemaining);
+    // Every DERIVED list is declared here, with the other derived values, and
+    // not beside the line that consumes it. \`var\` hoists the declaration but not
+    // the assignment, so a derived list written just below its first use is
+    // \`undefined\` at the moment it is read — which is a \`TypeError\` on the first
+    // property access, thrown on every state push and every auto-refresh tick,
+    // and therefore a page that renders nothing at all rather than a wrong
+    // number. That is exactly how the \`liveAgents\` count below used to be
+    // written, and it is invisible to a grep: nothing type-checks this file, so
+    // \`test/dashboard-page-execution.test.ts\` runs the page instead of reading it.
+    var liveAgents = agents.filter(function(a) { return asObject(a) !== null; });
+    var activeCount = liveAgents.filter(function(a) { return a.status === 'working'; }).length;
+    var liveTasks = tasks.filter(function(t) { return asObject(t) !== null; });
+    var runningTasks = liveTasks.filter(function(t) {
+      return t.status === 'running' || t.status === 'queued';
+    }).length;
+    var completedTasks = liveTasks.filter(function(t) { return t.status === 'completed'; }).length;
+    var failedTasks = liveTasks.filter(function(t) { return t.status === 'failed'; }).length;
+    // Same derivation the Sessions section uses for its header and its orphan
+    // banner, so the overview card and the section cannot print two different
+    // answers to "how many sessions, and is any of them leaking".
+    var sessionTally = sessionCensus(sessions);
     renderLifecycle(state);
     // ── Overview Stats ──
@@ -11347,8 +11579,6 @@ var dashboard_default = `<!DOCTYPE html>
     // so a total that included entries the page cannot render would contradict
     // the caveat printed directly beneath it.
     $statAgents.textContent = String(liveAgents.length);
-    var liveAgents = agents.filter(function(a) { return asObject(a) !== null; });
-    var activeCount = liveAgents.filter(function(a) { return a.status === 'working'; }).length;
     // Both figures from \`liveAgents\`, not one from \`agents\`: the count beside
     // the total has to be arithmetic the reader can do in their head, and
     // \`agents.length - activeCount\` mixing the two lists made the sub-line
@@ -11364,16 +11594,31 @@ var dashboard_default = `<!DOCTYPE html>
     $statAgentsSub.textContent = activeCount + ' working · '
       + (liveAgents.length - activeCount) + ' not working (live agents only)';
-    var liveTasks = tasks.filter(function(t) { return asObject(t) !== null; });
-    var runningTasks = liveTasks.filter(function(t) {
-      return t.status === 'running' || t.status === 'queued';
-    }).length;
-    var completedTasks = liveTasks.filter(function(t) { return t.status === 'completed'; }).length;
-    var failedTasks = liveTasks.filter(function(t) { return t.status === 'failed'; }).length;
     $statTasks.textContent = String(tasks.length);
     $statTasksSub.textContent = runningTasks + ' running/queued · ' + completedTasks + ' done'
       + (failedTasks > 0 ? ' · ' + failedTasks + ' failed' : '');
+    // The Sessions card. It sat at \`—\` with "No sessions reported" printed
+    // beneath it for the whole life of the card, while the Sessions SECTION
+    // further down the same page rendered the same list perfectly well —
+    // \`$statSessions\` and \`$statSessionsSub\` were resolved by \`getElementById\`
+    // at load and never assigned by any render path.
+    //
+    // The reason it shipped is worth recording, because it is the same reason
+    // the \`liveAgents\` use-before-declaration shipped: a grep cannot tell "reads
+    // the field somewhere" from "fills this element". The static contract test's
+    // required-field list contains \`sessions\`, the page does read
+    // \`state.sessions\` (in \`renderSessions\`), so every source-level assertion
+    // passed over a card that never received a value. The assertion that was
+    // missing is a rendered-output one, and it now lives in
+    // \`dashboard-page-execution.test.ts\`: the card is checked for the VALUE the
+    // section shows, not for the absence of an exception.
+    //
+    // The headline is the raw array length — the same figure the section header
+    // prints — so the two can never disagree about how many sessions exist.
+    $statSessions.textContent = String(sessionTally.total);
+    $statSessionsSub.textContent = sessionsSub(sessionTally);
     $statSpent.textContent = fmt$(totalSpent);
     $statSpentSub.textContent = maxTotalCost === null
       ? 'Budget ceiling not reported'
@@ -11471,6 +11716,94 @@ var dashboard_default = `<!DOCTYPE html>
     return s.owned !== true || s.agentId === null;
   }
+  /**
+   * The session figures, derived ONCE per render and read by two surfaces.
+   *
+   * \`$statSessions\` (the overview card) and \`renderOrphanBanner\` (the section
+   * alarm) answer the same question — is any session spending with nobody
+   * watching it? — and they are printed on the same page. If each counted its
+   * own, a future edit to one would put "0 unowned" on the card above "3
+   * running with no owning agent" in the banner, and both halves would still
+   * look correct on their own. So they share a derivation.
+   *
+   * \`total\` is the RAW array length, deliberately, because that is exactly what
+   * the Sessions section header prints. The card and the section must not be
+   * able to disagree about how many sessions exist, and the entries that are
+   * not objects are therefore counted as \`unreported\` rather than quietly
+   * dropped from a partition — see \`sessionsSub\`.
+   */
+  function sessionCensus(sessions) {
+    var all = asArray(sessions);
+    var running = 0;
+    var abandoned = 0;
+    var unowned = 0;
+    var unownedRunning = 0;
+    var unownedRunningIds = [];
+    var live = 0;
+    for (var i = 0; i < all.length; i++) {
+      var s = asObject(all[i]);
+      if (s === null) continue;
+      live++;
+      if (s.state === 'running') running++;
+      if (s.state === 'abandoned') abandoned++;
+      if (sessionIsOrphan(s)) {
+        unowned++;
+        // The one combination the whole view exists for: still generating, and
+        // the agent that owned it has been deleted, so its spend is collected
+        // by nobody. Counted apart from \`unowned\` because "unowned" alone
+        // reads as a bookkeeping state and this is a leak.
+        if (s.state === 'running') {
+          unownedRunning++;
+          unownedRunningIds.push(text(s.id) || 'unreported');
+        }
+      }
+    }
+    return {
+      total: all.length,
+      live: live,
+      unreported: all.length - live,
+      running: running,
+      abandoned: abandoned,
+      unowned: unowned,
+      unownedRunning: unownedRunning,
+      unownedRunningIds: unownedRunningIds
+    };
+  }
+  /**
+   * The overview card's sub-line for Sessions.
+   *
+   * Two constraints, and the second is the one that is easy to get wrong:
+   *
+   *   1. Every clause must be arithmetic the reader can check against the
+   *      headline above it. \`running\` and \`abandoned\` are disjoint slices of
+   *      the live sessions, and the entries that are not objects are stated
+   *      rather than dropped, so the figure above is always reachable from the
+   *      clauses beneath it. The \`unowned\` count is the ONE overlapping clause
+   *      and says so in its own wording, because an abandoned session is also
+   *      unowned.
+   *   2. It must not imply a healthy fleet. \`owned: false\` on a RUNNING session
+   *      is not a session that finished — it is a session still generating with
+   *      the agent that owned it deleted. Rolling those into a bare "running"
+   *      total is exactly what would make a leaking fleet read as healthy, so
+   *      the still-running unowned count is a clause of its own and is placed
+   *      after the terminal-state counts rather than buried in a suffix.
+   */
+  function sessionsSub(census) {
+    if (census.total === 0) return 'No sessions reported';
+    var parts = [census.running + ' running', census.abandoned + ' abandoned'];
+    if (census.unowned > 0) {
+      parts.push(census.unowned + ' with no owning agent'
+        + (census.unownedRunning > 0
+            ? ' (' + census.unownedRunning + ' still running)'
+            : ' (all finished)'));
+    }
+    if (census.unreported > 0) {
+      parts.push(census.unreported + ' unreported');
+    }
+    return parts.join(' · ');
+  }
   function sessionPassesFilter(s) {
     if (s === null || s === undefined) return false;
     if (sessionFilter === 'all') return true;
@@ -11494,8 +11827,9 @@ var dashboard_default = `<!DOCTYPE html>
   function renderSessions(sessions) {
     sessions = asArray(sessions);
-    $sessionCount.textContent = String(sessions.length);
-    renderOrphanBanner(sessions);
+    var census = sessionCensus(sessions);
+    $sessionCount.textContent = String(census.total);
+    renderOrphanBanner(census);
     if (sessions.length === 0) {
       $sessionsContainer.innerHTML = '<div class="empty-message">'
@@ -11519,7 +11853,8 @@ var dashboard_default = `<!DOCTYPE html>
     var html = '<table class="session-table"><thead><tr>'
       + '<th>Session</th><th>Owner</th><th>Task</th><th>Role</th><th>Model</th>'
-      + '<th>State</th><th class="num">Last read tokens</th><th class="num">Unbilled (≥)</th>'
+      + '<th>State</th><th class="num">Age</th><th class="num">Last read tokens</th>'
+      + '<th class="num">Unbilled (≥)</th>'
       + '</tr></thead><tbody>';
     for (var i = 0; i < shown.length; i++) {
       html += sessionRow(asObject(shown[i]));
@@ -11568,6 +11903,7 @@ var dashboard_default = `<!DOCTYPE html>
       + '<td class="mono">' + escHtml(text(s.model) || '—') + '</td>'
       + '<td><span class="session-state ' + escHtml(text(s.state) || 'unknown') + '">'
         + escHtml(text(s.state) || 'unreported') + '</span></td>'
+      + sessionAgeCell(s)
       + '<td class="num" title="The last token count actually observed for this session. Not a live reading.">'
         + (unread ? '—' : fmtInt(tokens)) + '</td>'
       + '<td class="num" title="Lower bound on what this session spent unbilled. A lower bound, not a total; excluded from Spend.">'
@@ -11575,38 +11911,82 @@ var dashboard_default = `<!DOCTYPE html>
       + '</tr>';
   }
+  /**
+   * How long a session has existed, as its own cell.
+   *
+   * \`SessionStateView.spawnedAt\` is documented as "from the owning agent. null
+   * for an orphan" — and an unowned session is exactly the row this view exists
+   * for. So the cell reads \`—\` on precisely the sessions a user most needs
+   * dated. That is worth SHOWING rather than omitting: an undated leak is
+   * visible, and the banner above the table says why it is undated, so the
+   * absence cannot pass for "started a moment ago". Omitting the column would
+   * have left that gap invisible, which is how it survived in the first place.
+   *
+   * The agent grid already prints its own \`spawnedAt\`, so leaving this one out
+   * also made the two sections of the same page inconsistent about the same
+   * field of the same object.
+   *
+   * The cell shows ELAPSED time rather than a wall clock because what makes a
+   * session's age matter is how long it has outlived its agent — a five-minute
+   * leak and a five-hour one are different incidents, and only the elapsed
+   * figure answers that. The raw ISO is on the \`title\`, which is where an
+   * unambiguous value belongs and which is also what the execution test reads,
+   * since an elapsed duration is not a stable string to assert on.
+   */
+  function sessionAgeCell(s) {
+    var iso = text(s.spawnedAt);
+    if (iso === null) {
+      return '<td class="num" title="SessionStateView.spawnedAt was not reported for this session.'
+        + ' It comes from the owning agent, so it is null for an unowned session.">—</td>';
+    }
+    var at = new Date(iso);
+    if (isNaN(at.getTime())) {
+      return '<td class="num" title="SessionStateView.spawnedAt is not a readable timestamp: '
+        + escHtml(iso) + '">—</td>';
+    }
+    // A snapshot whose clock runs ahead of this one must not produce a negative
+    // age, which would read as a session from the future.
+    var age = Date.now() - at.getTime();
+    if (age < 0) age = 0;
+    return '<td class="num" title="state.sessions[].spawnedAt ' + escHtml(iso) + '">'
+      + escHtml(fmtElapsed(age)) + '</td>';
+  }
   /**
    * The section-level alarm. It fires on the specific combination that is the
    * point of the whole view: a session that is still running, has no owning
    * agent, and is therefore spending into nothing.
+   *
+   * Takes the shared \`sessionCensus\` rather than the raw list, so this banner
+   * and the overview card are counting from one derivation and cannot drift
+   * apart.
    */
-  function renderOrphanBanner(sessions) {
-    var leaking = [];
-    var abandoned = 0;
-    for (var i = 0; i < sessions.length; i++) {
-      var s = asObject(sessions[i]);
-      if (s === null) continue;
-      if (s.state === 'abandoned') abandoned++;
-      if (sessionIsOrphan(s) && s.state === 'running') leaking.push(s);
-    }
+  function renderOrphanBanner(census) {
+    var leaking = census.unownedRunning;
+    var abandoned = census.abandoned;
-    if (leaking.length === 0 && abandoned === 0) {
+    if (leaking === 0 && abandoned === 0) {
       $orphanBanner.innerHTML = '';
       return;
     }
     var parts = [];
-    if (leaking.length > 0) {
-      var ids = leaking.map(function(s) { return text(s.id) || 'unreported'; });
+    if (leaking > 0) {
       parts.push(
         '<div class="orphan-banner">'
         + '<span class="icon">🔓</span><div>'
-        + '<div class="title">' + leaking.length + ' running session' + (leaking.length === 1 ? '' : 's')
+        + '<div class="title">' + leaking + ' running session' + (leaking === 1 ? '' : 's')
         + ' with no owning agent</div>'
         + '<div class="body">These sessions are still generating after the agent that owned '
         + 'them was terminated. Whatever they spend is not being collected, and the server '
-        + 'keeps them in view so you can terminate them.</div>'
-        + '<div class="detail">Session ids: <span class="mono">' + escHtml(ids.join(', ')) + '</span></div>'
+        + 'keeps them in view so you can terminate them. '
+        + '<strong>The Age column reads &mdash; for these rows:</strong> a session with no owning '
+        + 'agent has no owning agent to carry a spawn time, so <code>SessionStateView.spawnedAt</code> '
+        + 'is null for exactly the sessions whose age you most want. How long these have been '
+        + 'leaking is not on this snapshot.'
+        + '</div>'
+        + '<div class="detail">Session ids: <span class="mono">'
+        + escHtml(census.unownedRunningIds.join(', ')) + '</span></div>'
         + '</div></div>');
     }
     if (abandoned > 0) {
@@ -11665,7 +12045,8 @@ var dashboard_default = `<!DOCTYPE html>
       html += '<div class="agent-meta" title="Resolved model">📦 ' + escHtml(text(a.model) || 'model unreported') + '</div>';
       html += '<div class="agent-meta"><span>🔗</span><span class="mono">'
         + (sessionId === null ? 'no session id reported' : escHtml(sessionId)) + '</span></div>';
-      html += '<div class="agent-meta" title="state.agents[].spawnedAt">🕑 spawned '
+      html += '<div class="agent-meta" title="state.agents[].spawnedAt '
+        + escHtml(text(a.spawnedAt) || 'not reported') + '">🕑 spawned '
         + escHtml(fmtDateTime(a.spawnedAt)) + '</div>';
       html += '<div class="agent-metrics">';
@@ -12556,6 +12937,7 @@ function stateMessage(orchestrator) {
 class DashboardModule {
   server = null;
+  address = null;
   orchestrator;
   constructor(orchestrator) {
     this.orchestrator = orchestrator;
@@ -12624,9 +13006,11 @@ class DashboardModule {
           }
         }
       });
+      this.address = { host, port, url: `http://${host}:${port}` };
       console.log(`[nexus] Dashboard server running at http://${host}:${port}`);
     } catch (err) {
       this.server = null;
+      this.address = null;
       const detail = errorMessage(err);
       console.error(`[nexus] Failed to start dashboard on ${host}:${port}: ${detail}`);
       throw new Error(`Dashboard failed to start on port ${port}: ${detail}`);
@@ -12637,6 +13021,10 @@ class DashboardModule {
       this.server.stop();
       this.server = null;
     }
+    this.address = null;
+  }
+  getAddress() {
+    return this.server ? this.address : null;
   }
   getClientCount() {
     return this.orchestrator.broadcaster?.getClientCount() ?? 0;
@@ -12645,6 +13033,51 @@ class DashboardModule {
     return this.server !== null;
   }
 }
+function parseDashboardTarget(input, fallback) {
+  const parts = (input ?? "").trim().split(/\s+/).filter(Boolean);
+  let port = fallback.port;
+  let host = fallback.host;
+  if (parts.length > 0) {
+    const parsed = Number(parts[0]);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      return { error: `"${parts[0]}" is not a port number. Give a port between 1 and 65535.` };
+    }
+    port = parsed;
+  }
+  if (parts.length > 1) {
+    host = parts[1];
+  }
+  return { target: { port, host } };
+}
+function startDashboardServer(orchestrator, port, host) {
+  const running = orchestrator.dashboard?.getAddress() ?? null;
+  if (running) {
+    return { kind: "already-running", ...running };
+  }
+  try {
+    orchestrator.startDashboard(port, host);
+  } catch (error) {
+    return { kind: "refused", detail: error instanceof Error ? error.message : String(error) };
+  }
+  const address = orchestrator.dashboard?.getAddress() ?? null;
+  if (!address) {
+    return { kind: "refused", detail: "the dashboard reported a start but is not serving any address" };
+  }
+  return { kind: "started", ...address };
+}
+function describeDashboardStart(outcome) {
+  if (outcome.kind === "refused") {
+    return `Dashboard NOT started: ${outcome.detail}
+` + `No server is listening and no browser was opened. ` + `If the port is in use, either stop whatever holds it or pass a different \`port\`. ` + `Call again once the port is free — the dashboard does not retry on its own.`;
+  }
+  if (outcome.kind === "already-running") {
+    return `A dashboard is already running at ${outcome.url} — nothing was started a second time.
+` + `That server keeps serving until it is stopped, so open that exact URL to use it. ` + `Call \`nexus.dashboard.stop\` first if you want it on a different port.`;
+  }
+  return `Dashboard started at ${outcome.url}
+` + `Open that exact URL in a browser. The page connects to the same host and port for its live ` + `state over WebSocket (ws://${outcome.host}:${outcome.port}/ws/events), so it works only while this ` + `server runs. The TUI's \`/nexus-dashboard\` command opens the browser once this tool has succeeded.
+` + `Call \`nexus.dashboard.stop\` to shut it down.`;
+}
 // src/dag.ts
 function detectCycles(nodes) {
@@ -13058,62 +13491,205 @@ class MessageRouter {
 // src/notifications.ts
 import { spawn } from "node:child_process";
+var MACOS_SCRIPT_WITH_SOUND = [
+  "on run argv",
+  'display notification (item 2 of argv) with title (item 1 of argv) sound name "Glass"',
+  "end run"
+].join(`
+`);
+var MACOS_SCRIPT_SILENT = [
+  "on run argv",
+  "display notification (item 2 of argv) with title (item 1 of argv)",
+  "end run"
+].join(`
+`);
+var WINDOWS_SCRIPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null",
+  "$template = [Windows.UI.Notifications.ToastTemplateType]::ToastText02",
+  "$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent($template)",
+  "$texts = $xml.GetElementsByTagName('text')",
+  "$texts.Item(0).AppendChild($xml.CreateTextNode($env:NEXUS_NOTIFY_TITLE)) | Out-Null",
+  "$texts.Item(1).AppendChild($xml.CreateTextNode($env:NEXUS_NOTIFY_BODY)) | Out-Null",
+  "$toast = New-Object Windows.UI.Notifications.ToastNotification $xml",
+  "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Nexus').Show($toast)"
+].join(`
+`);
+var WINDOWS_NOTIFY_ENV = {
+  title: "NEXUS_NOTIFY_TITLE",
+  body: "NEXUS_NOTIFY_BODY"
+};
+var NOTIFY_TIMEOUT_MS = 3000;
+function macScriptFor(options) {
+  return options.silent || options.sound === false ? MACOS_SCRIPT_SILENT : MACOS_SCRIPT_WITH_SOUND;
+}
+function buildMacOSInvocation(options) {
+  return {
+    command: "osascript",
+    args: ["-e", macScriptFor(options), "--", options.title, options.body]
+  };
+}
+function buildLinuxInvocation(options) {
+  return {
+    command: "notify-send",
+    args: [options.title, options.body]
+  };
+}
+function buildWindowsInvocation(options) {
+  return {
+    command: "powershell",
+    args: ["-NoProfile", "-NonInteractive", "-Command", WINDOWS_SCRIPT],
+    env: {
+      ...process.env,
+      [WINDOWS_NOTIFY_ENV.title]: options.title,
+      [WINDOWS_NOTIFY_ENV.body]: options.body
+    }
+  };
+}
+function buildInvocation(platform, options) {
+  switch (platform) {
+    case "darwin":
+      return buildMacOSInvocation(options);
+    case "linux":
+      return buildLinuxInvocation(options);
+    case "win32":
+      return buildWindowsInvocation(options);
+    default:
+      return null;
+  }
+}
+var boundSetTimeout = globalThis.setTimeout;
+var boundClearTimeout = globalThis.clearTimeout;
+var SYSTEM_TIMERS = {
+  setTimeout: (handler, ms) => boundSetTimeout(handler, ms),
+  clearTimeout: (handle) => boundClearTimeout(handle)
+};
+function runProcess(proc, label, timeoutMs = NOTIFY_TIMEOUT_MS, timers = SYSTEM_TIMERS) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let stderr = "";
+    const finish = (outcome) => {
+      if (settled)
+        return;
+      settled = true;
+      timers.clearTimeout(timer);
+      resolve(outcome);
+    };
+    const timer = timers.setTimeout(() => {
+      if (!proc.killed) {
+        try {
+          proc.kill();
+        } catch {}
+      }
+      finish({ ok: false, reason: `${label} timed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+    proc.stderr?.on("data", (chunk) => {
+      if (stderr.length < 500)
+        stderr += String(chunk);
+    });
+    proc.on("error", (error) => {
+      finish({ ok: false, reason: `${label} could not start: ${error.message}` });
+    });
+    proc.on("close", (code) => {
+      if (code === 0) {
+        finish({ ok: true, reason: null });
+        return;
+      }
+      const detail = stderr.trim();
+      finish({
+        ok: false,
+        reason: `${label} exited with code ${code}${detail ? `: ${detail}` : ""}`
+      });
+    });
+  });
+}
 class NotificationManager {
   enabled;
   platform;
-  constructor(enabled = true) {
+  spawnImpl;
+  timeoutMs;
+  timers;
+  sent = 0;
+  failed = 0;
+  suppressed = 0;
+  lastError = null;
+  lastErrorAt = null;
+  constructor(enabled = true, options = {}) {
     this.enabled = enabled;
     this.platform = process.platform;
+    this.spawnImpl = options.spawnImpl ?? spawn;
+    this.timeoutMs = options.timeoutMs ?? NOTIFY_TIMEOUT_MS;
+    this.timers = options.timers ?? SYSTEM_TIMERS;
   }
   async notify(options) {
-    if (!this.enabled)
+    if (!this.enabled) {
+      this.suppressed += 1;
       return false;
-    try {
-      if (this.platform === "darwin") {
-        return await this.notifyMacOS(options);
-      } else if (this.platform === "linux") {
-        return await this.notifyLinux(options);
-      } else if (this.platform === "win32") {
-        return await this.notifyWindows(options);
-      }
-    } catch {}
+    }
+    const outcome = await this.attempt(options);
+    if (outcome.ok) {
+      this.sent += 1;
+      return true;
+    }
+    this.failed += 1;
+    this.lastError = outcome.reason;
+    this.lastErrorAt = new Date().toISOString();
+    console.error(`[nexus] notification failed: ${outcome.reason}`);
     return false;
   }
-  async notifyMacOS(options) {
-    const soundFlag = options.silent ? "" : options.sound !== false ? 'sound name "Glass"' : "";
-    const script = `display notification "${options.body}" with title "${options.title}" ${soundFlag}`;
-    return new Promise((resolve) => {
-      const proc = spawn("osascript", ["-e", script]);
-      proc.on("close", (code) => resolve(code === 0));
-      proc.on("error", () => resolve(false));
-      setTimeout(() => {
-        proc.kill();
-        resolve(false);
-      }, 3000);
-    });
+  async test() {
+    if (this.platform !== "darwin" && this.platform !== "linux" && this.platform !== "win32") {
+      return {
+        delivered: false,
+        reason: `no notifier for platform "${this.platform}"`,
+        enabled: this.enabled,
+        platform: this.platform,
+        stats: this.getStats()
+      };
+    }
+    const probe = {
+      title: "Nexus: notifications on",
+      body: "If you can read this, OS notifications are working.",
+      sound: true
+    };
+    const outcome = await this.attempt(probe);
+    return {
+      delivered: outcome.ok,
+      reason: outcome.reason,
+      enabled: this.enabled,
+      platform: this.platform,
+      stats: this.getStats()
+    };
   }
-  async notifyLinux(options) {
-    return new Promise((resolve) => {
-      const proc = spawn("notify-send", [options.title, options.body]);
-      proc.on("close", (code) => resolve(code === 0));
-      proc.on("error", () => resolve(false));
-      setTimeout(() => {
-        proc.kill();
-        resolve(false);
-      }, 3000);
-    });
+  async attempt(options) {
+    const invocation = buildInvocation(this.platform, options);
+    if (invocation === null) {
+      return { ok: false, reason: `no notifier for platform "${this.platform}"` };
+    }
+    let proc;
+    try {
+      proc = this.spawnImpl(invocation.command, [...invocation.args], {
+        env: invocation.env ? { ...invocation.env } : process.env
+      });
+    } catch (error) {
+      return {
+        ok: false,
+        reason: `${invocation.command} could not start: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+    return runProcess(proc, invocation.command, this.timeoutMs, this.timers);
   }
-  async notifyWindows(options) {
-    return new Promise((resolve) => {
-      const proc = spawn("powershell", ["-Command", `New-BurntToastNotification -Text '${options.title}','${options.body}'`]);
-      proc.on("close", (code) => resolve(code === 0));
-      proc.on("error", () => resolve(false));
-      setTimeout(() => {
-        proc.kill();
-        resolve(false);
-      }, 3000);
-    });
+  getStats() {
+    return {
+      sent: this.sent,
+      failed: this.failed,
+      suppressed: this.suppressed,
+      lastError: this.lastError,
+      lastErrorAt: this.lastErrorAt,
+      enabled: this.enabled,
+      platform: this.platform
+    };
   }
   setEnabled(enabled) {
     this.enabled = enabled;
@@ -14013,12 +14589,19 @@ class NexusOrchestrator {
     return this._healthMonitor;
   }
   notifications = null;
+  sendNotification(options) {
+    if (!this.notifications)
+      return;
+    this.notifications.notify(options).catch((error) => {
+      console.error(`[nexus] notification rejected: ${error instanceof Error ? error.message : String(error)}`);
+    });
+  }
   modelCosts = new Map;
   lastDegradedSpawn = null;
   constructor(config, messageStoreConfig, memoryStoreConfig) {
     this.config = this.mergeConfig(config);
     this.budget = this.config.budget;
-    this.configManager = new NexusConfigManager(this.config.dashboard);
+    this.configManager = new NexusConfigManager(this.config.dashboard, this.config.notifications);
     this.moduleRegistry = new ModuleRegistry;
     this.messageStore = new MessageStore(messageStoreConfig);
     this.memoryStore = new PersistentMemoryStore(memoryStoreConfig);
@@ -14047,7 +14630,7 @@ class NexusOrchestrator {
     this._healthMonitor = new HealthMonitor({
       checkInterval: this.config.agents.healthCheckInterval
     });
-    this.notifications = new NotificationManager(true);
+    this.notifications = new NotificationManager(this.configManager.getConfig().notifications.enabled);
     const moduleCtx = {
       orchestrator: this,
       config: this.config,
@@ -14293,6 +14876,9 @@ class NexusOrchestrator {
         port: 4747,
         host: "127.0.0.1"
       },
+      notifications: {
+        enabled: true
+      },
       security: {
         sastEnabled: true,
         secretsScanning: true,
@@ -14317,6 +14903,7 @@ class NexusOrchestrator {
       communication: { ...defaults.communication, ...partial?.communication },
       memory: { ...defaults.memory, ...partial?.memory },
       dashboard: { ...defaults.dashboard, ...partial?.dashboard },
+      notifications: { ...defaults.notifications, ...partial?.notifications },
       security: { ...defaults.security, ...partial?.security },
       learning: { ...defaults.learning, ...partial?.learning },
       ...partial?.cost ? { cost: { ...defaultCost, ...partial.cost } } : {}
@@ -14620,9 +15207,7 @@ Please continue from where the previous agent left off.`;
         startedAt: new Date(startTime),
         completedAt: new Date
       });
-      if (this.notifications?.isEnabled()) {
-        this.notifications.notify({ title: "Nexus: Task Complete", body: `${node.task.name} completed successfully` });
-      }
+      this.sendNotification({ title: "Nexus: Task Complete", body: `${node.task.name} completed successfully` });
       const priorPattern = this.learning.findSolutions(`task ${node.id} failed`);
       if (priorPattern.length > 0) {
         this.learning.recordSuccess(priorPattern[0].entry.id);
@@ -14703,9 +15288,7 @@ Please continue from where the previous agent left off.`;
           timeout
         });
       }
-      if (this.notifications?.isEnabled()) {
-        this.notifications.notify({ title: "Nexus: Task Failed", body: `${node.task.name} failed: ${errorMessage}`, sound: true });
-      }
+      this.sendNotification({ title: "Nexus: Task Failed", body: `${node.task.name} failed: ${errorMessage}`, sound: true });
       if (this.config.selfHealing.enabled) {
         await this.handleFailure(agent, node, new Error(errorMessage));
       }
@@ -15003,9 +15586,7 @@ Please continue from where the previous agent left off.`;
     }
     if (policy.alertOnFailure) {
       this.emit("agent:escalation", { agentId: agent.id, taskId: node.id, error: error.message });
-      if (this.notifications?.isEnabled()) {
-        this.notifications.notify({ title: "Nexus: Task Failed", body: `${node.task.name} failed: ${error.message}`, sound: true });
-      }
+      this.sendNotification({ title: "Nexus: Task Failed", body: `${node.task.name} failed: ${error.message}`, sound: true });
     }
     node.status = "failed";
     node.result = {
@@ -15425,16 +16006,20 @@ Please continue from where the previous agent left off.`;
   checkBudget() {
     const remaining = this.budget.maxTotalCost - this.totalSpent;
     const remainingPercent = remaining / this.budget.maxTotalCost;
-    if (remainingPercent <= this.config.budget.alertThreshold) {
-      this.emit("budget:alert", { remaining, remainingPercent });
-      if (this.notifications?.isEnabled()) {
-        this.notifications.notify({ title: "Nexus: Budget Alert", body: `Budget low: $${remaining.toFixed(2)} remaining (${(remainingPercent * 100).toFixed(1)}%)`, sound: true });
-      }
-    }
     if (this.budget.hardLimit && remaining <= 0 && !this.budgetExceeded) {
       this.budgetExceeded = true;
       this.emit("budget:exceeded", { totalSpent: this.totalSpent });
+      this.sendNotification({
+        title: "Nexus: Budget Limit Reached",
+        body: `Hard limit hit at $${this.totalSpent.toFixed(2)}. Execution paused.`,
+        sound: true
+      });
       this.pause();
+      return;
+    }
+    if (!this.budgetExceeded && remainingPercent <= this.config.budget.alertThreshold) {
+      this.emit("budget:alert", { remaining, remainingPercent });
+      this.sendNotification({ title: "Nexus: Budget Alert", body: `Budget low: $${remaining.toFixed(2)} remaining (${(remainingPercent * 100).toFixed(1)}%)`, sound: true });
     }
   }
   publish(topic, message) {
@@ -15489,8 +16074,9 @@ Please continue from where the previous agent left off.`;
       models: this.configManager.getResolvedModels()
     };
     const spend = this.spendSplit();
+    const notifications = this.notifications?.getStats() ?? null;
     if (detailed)
-      return JSON.stringify({ ...state, ...spend, budgetExceeded: this.budgetExceeded, config }, null, 2);
+      return JSON.stringify({ ...state, ...spend, budgetExceeded: this.budgetExceeded, config, notifications }, null, 2);
     return JSON.stringify({
       running: state.running,
       paused: state.paused,
@@ -15500,6 +16086,7 @@ Please continue from where the previous agent left off.`;
       totalCost: state.totalSpent,
       ...spend,
       budgetRemaining: state.budgetRemaining,
+      notifications,
       config
     }, null, 2);
   }
@@ -15675,11 +16262,29 @@ Please continue from where the previous agent left off.`;
         this.resume();
         return "Orchestrator resumed";
       case "dashboard":
-        return JSON.stringify(this.getState(), null, 2);
+        return this.handleDashboardCommand(parts.slice(2).join(" "));
       default:
-        return "Unknown command. Available: status, agents, costs, pause, resume, dashboard";
+        return "Unknown command. Available: status, agents, costs, pause, resume, dashboard [port] [host], dashboard stop, dashboard state";
     }
   }
+  handleDashboardCommand(argument) {
+    const sub = argument.trim().split(/\s+/).filter(Boolean)[0]?.toLowerCase();
+    if (sub === "state") {
+      return JSON.stringify(this.getState(), null, 2);
+    }
+    if (sub === "stop") {
+      const wasRunning = this.dashboard?.isRunning() ?? false;
+      this.stopDashboard();
+      return wasRunning ? "Dashboard stopped. The orchestrator, its agents and its sessions were not affected." : "No dashboard was running, so nothing was stopped. The orchestrator, its agents and its " + "sessions were not affected.";
+    }
+    const fallback = this.configManager.getConfig().dashboard;
+    const parsed = parseDashboardTarget(argument, { port: fallback.port, host: fallback.host });
+    if ("error" in parsed) {
+      return `Dashboard NOT started: ${parsed.error}
+No server was started and no browser was opened.`;
+    }
+    return describeDashboardStart(startDashboardServer(this, parsed.target.port, parsed.target.host));
+  }
 }
 // src/templates.ts
@@ -16101,20 +16706,19 @@ function watchConfigFiles(ctx, orchestrator, debounceMs = CONFIG_RELOAD_DEBOUNCE
 }
 var DASHBOARD_START_DESCRIPTION = "Start the Nexus web dashboard: an HTTP + WebSocket server that serves the dashboard page and the " + "orchestrator's live state, agents, tasks, sessions, costs and config. It is NOT started for you — " + "nothing in nexus listens until this tool is called, and it serves nothing but the dashboard. " + "The port must be FREE: the bind fails if another process holds it, and this tool reports that " + "failure rather than replacing the other listener. Host defaults to 127.0.0.1 and port to 4747, " + "or to the `dashboard` block in nexus.jsonc. If that block sets `enabled: false` the start is " + "refused and the refusal names the config key. On success the URL is printed — give the user that " + "exact URL; it is the only address the page is served on.";
 var DASHBOARD_STOP_DESCRIPTION = "Stop the Nexus web dashboard started by `dashboard.start`, closing its HTTP and WebSocket " + "connections. Takes no arguments. A no-op if no dashboard is running — it says so rather than " + "reporting a stop that did not happen. Note that this only stops the dashboard server: the " + "orchestrator, its agents and its sessions are unaffected and keep running.";
+var NOTIFICATIONS_TEST_DESCRIPTION = "Send a test OS notification and report whether the OS notifier accepted it, with the reason if it did not. " + "Use this to verify notification setup when the user reports never seeing notifications: it " + "distinguishes notifications being switched off in config, this platform having no notifier, and " + "the notifier itself rejecting the notification. Reports the notifier's own result, never a canned " + "success. Note that `delivered: true` means the OS took the notification, not that a human will see " + "it: a muted app, Focus/Dnd, or missing notification permission all still exit 0.";
+async function runNotificationsTest(orchestrator) {
+  if (!orchestrator.notifications) {
+    return JSON.stringify({
+      delivered: false,
+      reason: "notification manager is not initialised yet",
+      stats: null
+    }, null, 2);
+  }
+  return JSON.stringify(await orchestrator.notifications.test(), null, 2);
+}
 function runDashboardStart(orchestrator, port, host) {
-  try {
-    orchestrator.startDashboard(port, host);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    return `Dashboard NOT started: ${detail}
-` + `No server is listening and no browser was opened. ` + `If the port is in use, either stop whatever holds it or pass a different \`port\`. ` + `Call this tool again once the port is free — the dashboard does not retry on its own.`;
-  }
-  const dashboardConfig = orchestrator.configManager.getConfig().dashboard;
-  const boundHost = host || dashboardConfig.host;
-  const boundPort = port || dashboardConfig.port;
-  return `Dashboard started at http://${boundHost}:${boundPort}
-` + `Open that exact URL in a browser. The page connects to the same host and port for its live ` + `state over WebSocket (ws://${boundHost}:${boundPort}/ws/events), so it works only while this ` + `server runs. The TUI's \`/nexus-web\` command opens the browser once this tool has succeeded.
-` + `Call \`nexus.dashboard.stop\` to shut it down.`;
+  return describeDashboardStart(startDashboardServer(orchestrator, port, host));
 }
 function runDashboardStop(orchestrator) {
   const wasRunning = orchestrator.dashboard?.isRunning() ?? false;
@@ -16707,6 +17311,19 @@ You are a technical writer who creates documentation that developers actually wa
           return { content: orchestrator.getCostReport() };
         }
       });
+      editor.add({
+        name: "notifications.test",
+        description: NOTIFICATIONS_TEST_DESCRIPTION,
+        input: {
+          type: "object",
+          properties: {},
+          additionalProperties: false
+        },
+        options: { codemode: true },
+        execute: async () => {
+          return { content: await runNotificationsTest(orchestrator) };
+        }
+      });
       editor.add({
         name: "dashboard",
         description: "Get full orchestrator state for dashboard display",
@@ -17787,10 +18404,25 @@ ${lines.join(`
       });
     });
     await ctx.session.hook("prompt", (event) => {
-      if (event.prompt.text.startsWith("/nexus")) {
-        const result = orchestrator.handleCommand(event.prompt.text);
-        event.metadata = { ...event.metadata, nexusResult: result };
+      if (!event.prompt.text.startsWith("/nexus"))
+        return;
+      let result;
+      try {
+        result = orchestrator.handleCommand(event.prompt.text);
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        result = `The \`${event.prompt.text.trim()}\` command failed: ${detail}
+Nothing was changed.`;
       }
+      event.metadata = { ...event.metadata, nexusResult: result };
+      event.prompt.text = [
+        `The user ran \`${event.prompt.text.trim()}\`. The Nexus plugin already handled it and the `,
+        `result is below. Do not run the command again and do not try to start, stop or open `,
+        `anything yourself — report the result above in one or two sentences.`,
+        "",
+        result
+      ].join(`
+`);
     });
     const stopConfigWatch = watchConfigFiles(ctx, orchestrator);
     return () => {
@@ -17815,6 +18447,7 @@ export {
   MessageRouter,
   MessageStore,
   ModuleRegistry,
+  NOTIFICATIONS_TEST_DESCRIPTION,
   NexusConfigManager,
   NexusOrchestrator,
   PRESETS,
@@ -17833,5 +18466,6 @@ export {
   listTemplates,
   runDashboardStart,
   runDashboardStop,
+  runNotificationsTest,
   watchConfigFiles
 };