madarx 2.16.3 → 2.17.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to Madarx OS. Newest first.
 
 ## Unreleased
 
+## [2.17.0] - 2026-06-05
+
+### Added
+
+- **Persistent top toolbar.** A macOS-style toolbar mounted in the root layout (`AppChrome`) now stays on every non-chromeless page across navigation — showing the current section, a global "agents running" indicator (live via the SSE bus), and a search trigger. The dashboard's canvas controls (Approve & Run, Hermes, Runtime, Reset layout) are portaled into this single bar so "spaces" no longer shows two toolbars. The Hermes control appears only when a Hermes-engine agent exists.
+- **Durable manual agent runs.** Clicking **Run** now enqueues a durable `heartbeat_tasks` row (leased, stale-recovered) and kicks one worker pass for low latency, instead of a fire-and-forget promise — so a manual run survives a server recompile/restart. `max_attempts:1` avoids retry-storming deterministic config errors.
+- **Visible manual-run failures.** A failed manual run now persists a FAILED `runs` row + `agent.run.failed` audit carrying the error code and remediation, so engine/tool misconfigurations (e.g. a tool-needing agent on the Hermes/Ollama engine) surface in the agent's activity feed instead of failing silently to the console.
+- **Live agent activity feed + run-state hydration.** The agent detail activity feed subscribes to the SSE bus and surfaces run start/complete/failure without a reload; the Run button hydrates its state from a new `GET /api/agents/[id]/active-run` so it reflects an in-flight run after navigating away and back.
+
+### Fixed
+
+- **claude-code missing from the main chat model picker despite being "available".** `/api/models` (the main-agent picker) now uses the same robust CLI detector as `/settings/engines` — absolute-path candidates plus the `MADARX_CLAUDE_BIN` / `MADARX_CODEX_BIN` override — instead of a login-shell-only `command -v`. A CLI installed outside the server's inherited PATH (common on desktop/GUI-launched servers) now appears in the picker wherever the engines page reports it available; pin it explicitly with `MADARX_CLAUDE_BIN=/abs/path/to/claude`.
+- **Artifact canvas top alignment.** Removed the leftover top inset so the artifact window aligns flush with the chat panel and sidebar.
+
 ## [2.16.3] - 2026-06-05
 
 ### Added

package/app/agents/[id]/agent-activity-feed.tsx

@@ -1,7 +1,8 @@
 'use client';
 
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { Search, Play, ShieldCheck } from 'lucide-react';
+import { subscribeAgentEvents } from '../agent-events-bus.js';
 import { formatRelativeTime, humanizeRunStatus } from './format-helpers';
 
 type ActivityItem = {
@@ -30,24 +31,59 @@ function statusLabel(item: ActivityItem): string {
   return humanizeRunStatus(item.status);
 }
 
-export function AgentActivityFeed({ items }: { items: ActivityItem[] }) {
+export function AgentActivityFeed({ agentId, items }: { agentId: string; items: ActivityItem[] }) {
   const [query, setQuery] = useState('');
+  // Live runs for THIS agent, layered above the server-rendered snapshot. The
+  // server feed is a static render (no revalidate on run), so a manual run —
+  // especially a FAILED one — would otherwise be invisible until a reload. We
+  // surface start/complete/failed from the SSE bus immediately. Keyed by run_id
+  // (or 'manual' for fire-and-forget runs) so complete updates the same row.
+  const [liveItems, setLiveItems] = useState<ActivityItem[]>([]);
+
+  useEffect(() => {
+    return subscribeAgentEvents((event: any) => {
+      if (event.agent_id !== agentId) return;
+      const key = `live-${event.run_id || 'manual'}`;
+      if (event.type === 'agent_run_start') {
+        setLiveItems((cur) => {
+          const rest = cur.filter((i) => i.id !== key);
+          return [
+            { id: key, kind: 'execution', status: 'running', title: `${event.agent_name || 'Agent'} run`, at: new Date().toISOString() },
+            ...rest,
+          ];
+        });
+      } else if (event.type === 'agent_run_complete') {
+        const status = event.isError ? (event.status || 'failed') : (event.status || 'complete');
+        setLiveItems((cur) => {
+          const existing = cur.find((i) => i.id === key);
+          const title = event.error ? `${event.agent_name || 'Agent'} run — ${String(event.error).slice(0, 120)}` : (existing?.title || `${event.agent_name || 'Agent'} run`);
+          const updated: ActivityItem = { id: key, kind: 'execution', status, title, at: existing?.at || new Date().toISOString() };
+          const rest = cur.filter((i) => i.id !== key);
+          return [updated, ...rest];
+        });
+      }
+    });
+  }, [agentId]);
+
+  // Merge live over server items; dedupe is unnecessary — live items use a
+  // `live-` id and reset on remount, while server items use `run-`/`approval-`.
+  const merged = useMemo(() => [...liveItems, ...items], [liveItems, items]);
 
   const filtered = useMemo(() => {
     const q = query.trim().toLowerCase();
-    if (!q) return items;
-    return items.filter((item) =>
+    if (!q) return merged;
+    return merged.filter((item) =>
       item.title.toLowerCase().includes(q)
       || item.status.toLowerCase().includes(q)
       || item.kind.includes(q)
     );
-  }, [items, query]);
+  }, [merged, query]);
 
   return (
     <section className="ad-activity">
       <div className="ad-activity-head">
         <span className="ad-activity-title">Recent activity</span>
-        {items.length ? (
+        {merged.length ? (
           <label className="ad-activity-search">
             <Search size={13} aria-hidden />
             <input
@@ -83,7 +119,7 @@ export function AgentActivityFeed({ items }: { items: ActivityItem[] }) {
             );
           })}
         </ul>
-      ) : items.length ? (
+      ) : merged.length ? (
         <div className="ad-feed-empty">No activity matches “{query}”.</div>
       ) : (
         <div className="ad-feed-empty">

package/app/agents/[id]/agent-detail-simple.tsx

@@ -111,7 +111,7 @@ export function AgentDetailSimple({
         updateDefaultSpaceAction={updateDefaultSpaceAction}
       />
 
-      <AgentActivityFeed items={activity} />
+      <AgentActivityFeed agentId={agent.id} items={activity} />
     </section>
   );
 }

package/app/agents/agent-run-button.jsx

@@ -6,6 +6,19 @@ export default function AgentRunButton({ agentId }) {
   const [running, setRunning] = useState(false);
   const [submitting, setSubmitting] = useState(false);
 
+  // Hydrate from server truth on mount. The SSE `agent_run_start` event fires
+  // once at run start; if the user navigated away and back, that event was
+  // missed and this freshly-mounted button would wrongly show "Run" while a run
+  // is still live. Ask the server whether a run is currently active.
+  useEffect(() => {
+    let cancelled = false;
+    fetch(`/api/agents/${encodeURIComponent(agentId)}/active-run`)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data) => { if (!cancelled && data?.active) setRunning(true); })
+      .catch(() => { /* best-effort; SSE still drives live flips */ });
+    return () => { cancelled = true; };
+  }, [agentId]);
+
   useEffect(() => {
     return subscribeAgentEvents((event) => {
       if (event.agent_id !== agentId) return;

package/app/api/agents/[id]/active-run/route.js

@@ -0,0 +1,23 @@
+import { isRunActive } from '@/lib/active-runs.js';
+import { listAgentRuns } from '@/lib/delegation.js';
+import { isActiveRunStatus } from '@/lib/delegation-contracts.js';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+// Source of truth for "is this agent running right now?" so the Run button can
+// hydrate the correct state after the user navigates away and back. Combines:
+//   - the in-process manual-run registry (fire-and-forget runs have no DB row)
+//   - any delegated/task agent_runs row in an active status (queued/running/...)
+export async function GET(_req, { params }) {
+  const { id } = await params;
+  let taskActive = false;
+  try {
+    taskActive = listAgentRuns({ agent_id: id, limit: 20 })
+      .some(run => isActiveRunStatus(run.status));
+  } catch {
+    taskActive = false;
+  }
+  const active = isRunActive(id) || taskActive;
+  return Response.json({ active, agent_id: id });
+}

package/app/api/agents/[id]/run/route.js

@@ -1,21 +1,40 @@
 import { getAgent } from '@/lib/runtime.js';
-import { runAgentTick } from '@/lib/agent-runner.js';
+import { createHeartbeatTask } from '@/lib/heartbeat-queue.js';
+import { runHeartbeatWorkerOnce } from '@/lib/heartbeat-worker.js';
 
 export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 
-// Fire-and-forget manual run. The dashboard SSE stream (`agent_run_start` /
-// `agent_run_complete`) drives the UI, so this route returns immediately and
-// lets the run finish in the background — otherwise the request would block
-// for the full duration of the tick and the button would lock up.
+// Manual run = durable + low-latency (hybrid).
+//
+// Previously this was a fire-and-forget `runAgentTick().catch()` promise: it
+// survived browser navigation (server-side) but NOT a dev recompile / server
+// restart, and it was untracked. Now we ENQUEUE a heartbeat_tasks row (durable —
+// leased, retried-once, stale-recovered by the worker) and immediately KICK one
+// worker pass so it still starts in ~milliseconds. If this process dies mid-run,
+// the lease expires and the in-process/standalone heartbeat worker re-claims it.
+//
+// max_attempts:1 — a manual click is one intent; a deterministic config error
+// (e.g. engine_cannot_run_tools) must not retry-storm into duplicate failed runs.
 export async function POST(_req, { params }) {
   const { id } = await params;
   const agent = getAgent(id);
   if (!agent) return Response.json({ ok: false, error: 'agent not found' }, { status: 404 });
 
-  runAgentTick(id, { triggered_by: 'manual' }).catch(err => {
-    console.warn(`[agents/${id}/run] tick failed:`, err?.message || err);
+  const task = createHeartbeatTask({
+    agent_id: id,
+    type: 'agent_tick',
+    priority: 10, // ahead of background ticks so the click feels instant
+    max_attempts: 1,
+    payload: { type: 'agent_tick', agent_id: id, triggered_by: 'manual', reason: 'manual-run' },
   });
 
-  return Response.json({ ok: true, agent_id: id, status: 'queued' });
+  // Low-latency kick. Best-effort: the durable queue is the safety net, so a
+  // failed kick (or none, e.g. management mode) just means the worker picks it
+  // up on its next interval.
+  runHeartbeatWorkerOnce().catch(err => {
+    console.warn(`[agents/${id}/run] worker kick failed:`, err?.message || err);
+  });
+
+  return Response.json({ ok: true, agent_id: id, task_id: task.id, status: 'queued' });
 }

package/app/components/app-chrome.jsx

@@ -3,6 +3,7 @@
 import { useMemo } from 'react';
 import { usePathname } from 'next/navigation';
 import SmartSearch from './smart-search';
+import AppTopbar from './app-topbar';
 
 const CHROMELESS_PREFIXES = ['/login', '/share'];
 
@@ -22,6 +23,7 @@ export default function AppChrome({ children, sidebar }) {
   return (
     <>
       <div className="app-shell">
+        <AppTopbar />
         <div className="app-rail">{sidebarNode}</div>
         <div className="app-content">{children}</div>
       </div>

package/app/components/app-topbar.jsx

@@ -0,0 +1,100 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import { usePathname } from 'next/navigation';
+import { Search, Command } from 'lucide-react';
+import { subscribeAgentEvents } from '../agents/agent-events-bus.js';
+
+// Pathname prefix → human section label. Longest-prefix wins via order: list
+// more specific paths before their parents.
+const SECTIONS = [
+  ['/agents', 'Agents'],
+  ['/tasks', 'Tasks'],
+  ['/approvals', 'Approvals'],
+  ['/marketplace', 'Marketplace'],
+  ['/tools', 'Tools'],
+  ['/schedules', 'Schedules'],
+  ['/reports', 'Reports'],
+  ['/activity', 'Activity'],
+  ['/runtime', 'Runtime'],
+  ['/workflows', 'Workflows'],
+  ['/brand', 'Brand'],
+  ['/team', 'Team'],
+  ['/whatsapp', 'WhatsApp'],
+  ['/settings', 'Settings'],
+  ['/help', 'Help'],
+];
+
+function sectionFor(pathname) {
+  if (!pathname || pathname === '/') return 'Overview';
+  const hit = SECTIONS.find(([prefix]) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+  return hit ? hit[1] : 'madarX';
+}
+
+export default function AppTopbar() {
+  const pathname = usePathname();
+  const section = useMemo(() => sectionFor(pathname), [pathname]);
+
+  // Global "is anything running" indicator. Tracks the set of agent ids with a
+  // live run via the shared SSE bus — the same source the Run buttons use.
+  const [runningIds, setRunningIds] = useState(() => new Set());
+
+  useEffect(() => {
+    return subscribeAgentEvents((event) => {
+      if (!event?.agent_id) return;
+      if (event.type === 'agent_run_start') {
+        setRunningIds((cur) => {
+          const next = new Set(cur);
+          next.add(event.agent_id);
+          return next;
+        });
+      } else if (event.type === 'agent_run_complete') {
+        setRunningIds((cur) => {
+          if (!cur.has(event.agent_id)) return cur;
+          const next = new Set(cur);
+          next.delete(event.agent_id);
+          return next;
+        });
+      }
+    });
+  }, []);
+
+  const runningCount = runningIds.size;
+
+  function openSearch() {
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent('madarx:open-search'));
+    }
+  }
+
+  return (
+    <header className="app-topbar" role="banner">
+      <div className="app-topbar-left">
+        <span className="app-topbar-brand">madar<b>X</b></span>
+        <span className="app-topbar-sep" aria-hidden />
+        <span className="app-topbar-section">{section}</span>
+      </div>
+
+      <div className="app-topbar-right">
+        {/* Page-scoped action slot. The dashboard ("spaces") portals its canvas
+            controls (Approve & Run, Hermes, Runtime, Reset layout) in here so
+            there is ONE toolbar instead of two. Empty on every other page. */}
+        <div id="app-topbar-slot" className="app-topbar-slot" />
+
+        <span
+          className={`app-topbar-activity ${runningCount ? 'is-running' : ''}`}
+          title={runningCount ? `${runningCount} agent${runningCount === 1 ? '' : 's'} running` : 'No agents running'}
+        >
+          <span className="app-topbar-dot" aria-hidden />
+          {runningCount ? `${runningCount} running` : 'Idle'}
+        </span>
+
+        <button type="button" className="app-topbar-search" onClick={openSearch} aria-label="Open search (Command K)">
+          <Search size={13} aria-hidden />
+          <span>Search</span>
+          <kbd><Command size={10} aria-hidden />K</kbd>
+        </button>
+      </div>
+    </header>
+  );
+}

package/app/components/dashboard/canvas-section.jsx

@@ -1,5 +1,6 @@
 "use client";
-import { memo, useState } from 'react';
+import { memo, useEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { useDashboard } from './dashboard-context';
 import ArtifactDock from './artifact-dock';
 import ArtifactBoard from './artifact-board';
@@ -14,6 +15,7 @@ function CanvasSection() {
     runtimeActions,
     mainAgent,
     approvalRun,
+    counts,
     artifacts,
     visibleArtifacts,
     dockedArtifacts,
@@ -52,60 +54,78 @@ function CanvasSection() {
 
   const [moveMenu, setMoveMenu] = useState(null); // { artifactId, x, y } | null
 
+  // Portal the canvas controls into the persistent top toolbar so the dashboard
+  // ("spaces") shows ONE toolbar, not two. The slot lives in AppTopbar (root
+  // layout); resolve it after mount. Handlers keep working because the buttons
+  // stay in this component's React tree — only their DOM position moves.
+  const [toolbarSlot, setToolbarSlot] = useState(null);
+  useEffect(() => {
+    setToolbarSlot(document.getElementById('app-topbar-slot'));
+  }, []);
+
+  // Hermes control is shown only when the user actually has a Hermes-engine
+  // agent — otherwise the runtime indicator is noise.
+  const hasHermesAgent = (counts?.agents || []).some(a => (a.engine || '') === 'hermes');
+
+  const toolbarActions = (
+    <div className="app-topbar-actions">
+      {approvalRun && (
+        <button
+          className="admin-button"
+          onClick={() => approveClaudeRun(approvalRun.id)}
+          disabled={approvalBusyId === approvalRun.id}
+          style={{ height: 28, padding: '0 12px', fontSize: 12 }}
+        >
+          {approvalBusyId === approvalRun.id ? 'Running Claude...' : 'Approve & Run'}
+        </button>
+      )}
+      {hasHermesAgent && (
+        <div className="hermes-wrap">
+          <span
+            className={'tb-icon-btn' + (activeHermesJobs.length > 0 ? ' on' : '')}
+            role="status"
+            aria-label={activeHermesJobs.length > 0 ? `Hermes ${activeHermesJobs.length} running` : 'Hermes idle'}
+          >
+            <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/>
+            </svg>
+            {activeHermesJobs.length > 0 && <span>{activeHermesJobs.length}</span>}
+          </span>
+          <div className="hermes-tooltip" role="tooltip">
+            <b>Hermes</b>
+            <small>{activeHermesJobs.length > 0 ? `${activeHermesJobs.length} running` : 'idle'}</small>
+            {activeHermesJobs.length > 0 && (
+              <ul>
+                {activeHermesJobs.map(j => (
+                  <li key={j.id}>{j.title || (j.prompt ? j.prompt.slice(0, 60) : 'Untitled job')}</li>
+                ))}
+              </ul>
+            )}
+          </div>
+        </div>
+      )}
+      <RuntimePopover />
+      {artifacts.length > 0 && (
+        <button
+          className="tb-icon-btn"
+          onClick={resetArtifactLayout}
+          title={layoutMode === 'manual' ? 'Reset to auto layout' : 'Auto layout active'}
+          aria-label={layoutMode === 'manual' ? 'Reset to auto layout' : 'Auto layout active'}
+        >
+          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <rect x="3" y="3" width="7" height="7"/>
+            <rect x="14" y="3" width="7" height="7"/>
+            <rect x="14" y="14" width="7" height="7"/>
+            <rect x="3" y="14" width="7" height="7"/>
+          </svg>
+        </button>
+      )}
+    </div>
+  );
+
   return (
 <section className={'canvas fresh-canvas' + (isSpaceSwitching ? ' is-space-switching' : '')}>
-  <div className="toolbar fresh-toolbar">
-    <span className="tb-wordmark" aria-label="madarX OS">madar<b>X</b><i>OS</i></span>
-    {approvalRun && (
-      <button
-        onClick={() => approveClaudeRun(approvalRun.id)}
-        disabled={approvalBusyId === approvalRun.id}
-        style={{border:0,borderRadius:999,padding:'7px 10px',background:'#111318',color:'#fff',fontSize:12,fontWeight:700,cursor:approvalBusyId ? 'wait' : 'pointer'}}
-      >
-        {approvalBusyId === approvalRun.id ? 'Running Claude...' : 'Approve & Run'}
-      </button>
-    )}
-    <div className="hermes-wrap">
-      <span
-        className={'tb-icon-btn' + (activeHermesJobs.length > 0 ? ' on' : '')}
-        role="status"
-        aria-label={activeHermesJobs.length > 0 ? `Hermes ${activeHermesJobs.length} running` : 'Hermes idle'}
-      >
-        <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-          <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/>
-        </svg>
-        {activeHermesJobs.length > 0 && <span>{activeHermesJobs.length}</span>}
-      </span>
-      <div className="hermes-tooltip" role="tooltip">
-        <b>Hermes</b>
-        <small>{activeHermesJobs.length > 0 ? `${activeHermesJobs.length} running` : 'idle'}</small>
-        {activeHermesJobs.length > 0 && (
-          <ul>
-            {activeHermesJobs.map(j => (
-              <li key={j.id}>{j.title || (j.prompt ? j.prompt.slice(0, 60) : 'Untitled job')}</li>
-            ))}
-          </ul>
-        )}
-      </div>
-    </div>
-    <RuntimePopover />
-    {artifacts.length > 0 && (
-      <button
-        className="tb-icon-btn"
-        style={{ marginLeft: 'auto' }}
-        onClick={resetArtifactLayout}
-        title={layoutMode === 'manual' ? 'Reset to auto layout' : 'Auto layout active'}
-        aria-label={layoutMode === 'manual' ? 'Reset to auto layout' : 'Auto layout active'}
-      >
-        <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-          <rect x="3" y="3" width="7" height="7"/>
-          <rect x="14" y="3" width="7" height="7"/>
-          <rect x="14" y="14" width="7" height="7"/>
-          <rect x="3" y="14" width="7" height="7"/>
-        </svg>
-      </button>
-    )}
-  </div>
+  {toolbarSlot ? createPortal(toolbarActions, toolbarSlot) : null}
 
   {(() => {
     const visible = visibleArtifacts;

package/app/components/smart-search.jsx

@@ -232,6 +232,17 @@ export default function SmartSearch() {
     return () => window.removeEventListener('madarx:open-setting', onOpenSetting);
   }, [openSetting]);
 
+  // Let chrome surfaces (the persistent top toolbar) open the palette without
+  // synthesizing a keydown. Mirrors the ⌘K toggle.
+  useEffect(() => {
+    function onOpenSearch(event) {
+      const q = event?.detail?.query;
+      openWithQuery(typeof q === 'string' ? q : '');
+    }
+    window.addEventListener('madarx:open-search', onOpenSearch);
+    return () => window.removeEventListener('madarx:open-search', onOpenSearch);
+  }, []);
+
   useEffect(() => {
     function onKeyDown(event) {
       const key = (event.key || '').toLowerCase();

package/app/globals.css

@@ -137,7 +137,7 @@
 .runtime-approval button.secondary{border:1px solid rgba(17,19,24,.12);background:#fff;color:#111318;}
 .runtime-approval button:disabled{opacity:.45;cursor:not-allowed;}
 .runtime-empty{border:1px dashed rgba(17,19,24,.14);border-radius:12px;padding:14px;text-align:center;font-size:12px;color:#68707b;background:#fafbfc;}
-.fresh-workspace{position:absolute;inset:56px 14px 70px;display:grid;grid-template-columns:minmax(0,1.1fr) minmax(260px,.55fr);gap:14px;align-items:stretch;}
+.fresh-workspace{position:absolute;inset:0 14px 70px;display:grid;grid-template-columns:minmax(0,1.1fr) minmax(260px,.55fr);gap:14px;align-items:stretch;}
 .fresh-hero,.fresh-status{border:1px solid rgba(255,255,255,.80);background:rgba(255,255,255,.72);backdrop-filter:blur(18px);box-shadow:0 22px 64px rgba(37,36,34,.15);border-radius:28px;}
 .fresh-hero{padding:44px;display:flex;flex-direction:column;justify-content:center;min-height:0;}
 .fresh-hero small{letter-spacing:.18em;text-transform:uppercase;color:#8a6d35;font-weight:800;font-size:11px;}
@@ -150,7 +150,7 @@
 .fresh-status div{border:1px solid rgba(20,22,26,.07);background:linear-gradient(180deg,#fff,rgba(247,247,245,.88));border-radius:20px;padding:18px;}
 .fresh-status b{display:block;font-size:48px;letter-spacing:-.06em;}
 .fresh-status span{display:block;text-transform:uppercase;letter-spacing:.14em;color:#6c747f;font-size:11px;font-weight:800;}
-@media(max-width:980px){.fresh-workspace{position:relative;inset:auto;margin:64px 12px 12px;grid-template-columns:1fr}.fresh-hero{padding:28px}.fresh-status{grid-template-columns:repeat(2,1fr)}}
+@media(max-width:980px){.fresh-workspace{position:relative;inset:auto;margin:12px;grid-template-columns:1fr}.fresh-hero{padding:28px}.fresh-status{grid-template-columns:repeat(2,1fr)}}
 
 .fresh-workspace{grid-template-columns:1fr;}
 .fresh-hero.full-width{max-width:none;}
@@ -366,7 +366,7 @@ body:has(.artifact-fs[data-phase="open"]){overflow:hidden;}
 .dock-item-menu-divider{height:1px;background:rgba(17,19,24,.08);margin:4px 4px;}
 
 /* === Building card — shown while agent creates the first artifact === */
-.building-card-wrap{position:absolute;inset:64px 14px 14px;animation:building-enter .38s cubic-bezier(.32,.72,0,1) both;}
+.building-card-wrap{position:absolute;inset:0 14px 14px;animation:building-enter .38s cubic-bezier(.32,.72,0,1) both;}
 @keyframes building-enter{from{opacity:0;transform:translateY(16px) scale(.982)}to{opacity:1;transform:translateY(0) scale(1)}}
 .building-card{width:100%;height:100%;border-radius:22px;background:rgba(255,255,255,.92);border:1px solid rgba(255,255,255,.88);box-shadow:0 22px 64px rgba(32,34,38,.20);overflow:hidden;display:flex;flex-direction:column;position:relative;}
 .building-card::before{content:'';position:absolute;inset:0;background:linear-gradient(108deg,transparent 34%,rgba(255,255,255,.52) 50%,transparent 66%);animation:card-sweep 2.6s ease-in-out infinite;pointer-events:none;z-index:10;}
@@ -427,7 +427,7 @@ body:has(.artifact-fs[data-phase="open"]){overflow:hidden;}
 .artifact-kind-badge.markdown{background:#f0fdf4;color:#166534;}
 
 /* Canvas board — free-positioning surface for artifact windows (macOS-style) */
-.canvas-board{position:absolute;inset:56px 0 70px;overflow:auto;overscroll-behavior:contain;z-index:1;transition:opacity .22s cubic-bezier(.32,.72,0,1),transform .22s cubic-bezier(.32,.72,0,1),filter .22s ease;}
+.canvas-board{position:absolute;inset:0 0 70px;overflow:auto;overscroll-behavior:contain;z-index:1;transition:opacity .22s cubic-bezier(.32,.72,0,1),transform .22s cubic-bezier(.32,.72,0,1),filter .22s ease;}
 .canvas-board--docked{padding-bottom:0;}
 
 /* Space switching — outgoing fade-and-lift; incoming relies on artifact-enter keyframes */
@@ -3564,6 +3564,7 @@ a.admin-record-link{display:block;text-decoration:none;color:inherit;transition:
 .app-shell {
   display: grid;
   grid-template-columns: 64px 1fr;
+  grid-template-rows: auto 1fr; /* row 1: persistent top toolbar (spans), row 2: rail + content */
   gap: 10px;
   padding: 10px;
   height: 100vh;
@@ -3571,6 +3572,108 @@ a.admin-record-link{display:block;text-decoration:none;color:inherit;transition:
   background: #f4f3f0;
   overflow: hidden;
 }
+/* Persistent macOS-style top toolbar. Lives in the root layout via AppChrome so
+   it stays mounted on every non-chromeless page. */
+.app-topbar {
+  grid-column: 1 / -1;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 38px;
+  padding: 0 14px;
+  border-radius: 13px;
+  background: var(--glass, rgba(255,255,255,.78));
+  border: 1px solid rgba(255,255,255,.8);
+  box-shadow: 0 8px 24px rgba(17,19,24,.08), inset 0 1px 0 rgba(255,255,255,.6);
+  backdrop-filter: saturate(160%) blur(14px);
+  -webkit-backdrop-filter: saturate(160%) blur(14px);
+  font-size: 12px;
+  color: #4a5059;
+  user-select: none;
+}
+.app-topbar-left { display: flex; align-items: center; gap: 11px; min-width: 0; }
+.app-topbar-brand {
+  font-family: var(--font-mono-brand, 'IBM Plex Mono', monospace);
+  font-weight: 500;
+  font-size: 13px;
+  letter-spacing: -.02em;
+  color: #111318;
+}
+.app-topbar-brand b { color: var(--accent-500); font-weight: 500; }
+.app-topbar-sep { width: 1px; height: 16px; background: var(--line, rgba(20,22,26,.12)); }
+.app-topbar-section {
+  font-weight: 700;
+  letter-spacing: -.01em;
+  color: #1c1f25;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.app-topbar-right { display: flex; align-items: center; gap: 10px; }
+/* Page-scoped action slot (dashboard portals its canvas controls here). */
+.app-topbar-slot { display: flex; align-items: center; }
+.app-topbar-slot:empty { display: none; }
+.app-topbar-actions { display: flex; align-items: center; gap: 8px; }
+.app-topbar-actions::after {
+  content: '';
+  width: 1px;
+  height: 18px;
+  background: var(--line, rgba(20,22,26,.12));
+  margin: 0 2px;
+}
+.app-topbar-activity {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  font-weight: 600;
+  color: #69707a;
+  padding: 3px 9px;
+  border-radius: 999px;
+  background: rgba(17,19,24,.04);
+}
+.app-topbar-dot { width: 7px; height: 7px; border-radius: 50%; background: #c2c7cd; flex: 0 0 auto; }
+.app-topbar-activity.is-running { color: var(--accent-700, #7c2b19); background: var(--accent-50, #fdf2ef); }
+.app-topbar-activity.is-running .app-topbar-dot {
+  background: var(--accent-500, #c2452a);
+  box-shadow: 0 0 0 3px rgba(194,69,42,.18);
+  animation: topbarPulse 1.4s ease-in-out infinite;
+}
+@keyframes topbarPulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: .4; }
+}
+.app-topbar-search {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  height: 26px;
+  padding: 0 9px;
+  border: 1px solid var(--line, rgba(20,22,26,.12));
+  border-radius: 9px;
+  background: #fff;
+  color: #515760;
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: border-color .14s ease, box-shadow .14s ease;
+}
+.app-topbar-search:hover { border-color: rgba(20,22,26,.24); box-shadow: 0 2px 8px rgba(17,19,24,.08); }
+.app-topbar-search kbd {
+  display: inline-flex;
+  align-items: center;
+  gap: 1px;
+  font-family: var(--font-mono-brand, ui-monospace, monospace);
+  font-size: 10px;
+  color: #8a9099;
+  background: rgba(17,19,24,.05);
+  border-radius: 5px;
+  padding: 2px 4px;
+}
+@media (max-width: 980px) {
+  .app-topbar-brand, .app-topbar-sep { display: none; }
+  .app-topbar-search span { display: none; }
+}
 .app-rail {
   min-width: 0;
   height: 100%;