@polderlabs/bizar 4.3.0 → 4.4.1

package/bizar-dash/src/web/views/BackgroundAgents.tsx

@@ -21,6 +21,7 @@ import { useModal } from '../components/Modal';
 import { useToast } from '../components/Toast';
 import { BgStatusBadge } from '../components/BgStatusBadge';
 import { openKillConfirmDialog } from '../components/KillConfirmDialog';
+import { TmuxAttachCard } from '../components/background/TmuxAttachCard';
 import { api } from '../lib/api';
 import { Ws } from '../lib/ws';
 import { cn, formatTime, truncate } from '../lib/utils';
@@ -283,6 +284,8 @@ function BackgroundAgentCard({
           <Trash2 size={14} /> Kill
         </Button>
       </div>
+
+      <TmuxAttachCard instance={inst} />
     </Card>
   );
 }

package/bizar-dash/src/web/views/Chat.tsx

@@ -1,13 +1,22 @@
-// src/views/Chat.tsx — Gemini-inspired dark chat orchestrator.
-// Composer state (agent, model, text, attachments) is local.
-// useChat handles messages, sessions, send, polling.
+// src/views/Chat.tsx — Gemini-inspired dark chat orchestrator (v3.22).
+//
+// v3.22 — redesigned layout: 3-column grid (rail / thread / info).
+// The legacy `.chat-shell / .chat-body / .chat-sessions / .chat-main /
+// .chat-info` wrapper classes are still available for MobileChat (which
+// uses its own view); this file uses the new `.chat-page` grid.
+//
+// The `chat-thread` section is a vertical grid (head / scroll / composer).
+// The scrollable message list lives inside the legacy `ChatThread`
+// component (still wrapped in its own `.chat-thread` div with className
+// `legacy` to opt into the original styles — see chat.css).
 
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { ChatTopBar } from '../components/chat/ChatTopBar';
-import { SessionList } from '../components/chat/SessionList';
+import { ChatRail } from '../components/chat/ChatRail';
 import { ChatThread } from '../components/chat/ChatThread';
-import { FloatingComposer } from '../components/chat/FloatingComposer';
-import { InfoPanel } from '../components/chat/InfoPanel';
+import { ChatComposer } from '../components/chat/ChatComposer';
+import { ChatInfoPanel } from '../components/chat/ChatInfoPanel';
+import { JumpToLatest } from '../components/chat/JumpToLatest';
 import { useChat } from '../components/chat/useChat';
 import { useSlashCommands } from '../components/chat/useSlashCommands';
 import { useToast } from '../components/Toast';
@@ -28,7 +37,6 @@ export function Chat({ snapshot, settings, setActiveTab, initialTaskId, onClearT
   const toast = useToast();
   const modal = useModal();
 
-  // ── Delegate to useChat: messages, sessions, send, polling ──────────────
   const chat = useChat(snapshot, settings, initialTaskId ?? '');
 
   // ── Composer state (local) ───────────────────────────────────────────────
@@ -39,12 +47,13 @@ export function Chat({ snapshot, settings, setActiveTab, initialTaskId, onClearT
   const [creating, setCreating] = useState(false);
 
   const fileInputRef = useRef<HTMLInputElement>(null);
-  const inputRef = useRef<HTMLTextAreaElement>(null);
 
   // ── Slash commands ───────────────────────────────────────────────────────
   const { allCommands, suggestions, setQuery } = useSlashCommands(snapshot);
 
-  useEffect(() => { setQuery(text); }, [text, setQuery]);
+  useEffect(() => {
+    setQuery(text);
+  }, [text, setQuery]);
 
   // ── File attach ──────────────────────────────────────────────────────────
   const onAttach = () => fileInputRef.current?.click();
@@ -68,6 +77,7 @@ export function Chat({ snapshot, settings, setActiveTab, initialTaskId, onClearT
     setText('');
     setQuery('');
     chat.onSend(msg, agent, model, attachments);
+    chat.jumpToLatest();
   };
 
   // ── Create session ───────────────────────────────────────────────────────
@@ -96,7 +106,9 @@ export function Chat({ snapshot, settings, setActiveTab, initialTaskId, onClearT
       children: <p style={{ margin: 0 }}>This action cannot be undone.</p>,
       footer: (
         <div style={{ display: 'flex', gap: 8, justifyContent: 'flex-end' }}>
-          <Button variant="secondary" size="sm" onClick={() => modal.close()}>Cancel</Button>
+          <Button variant="secondary" size="sm" onClick={() => modal.close()}>
+            Cancel
+          </Button>
           <Button
             variant="danger"
             size="sm"
@@ -112,7 +124,42 @@ export function Chat({ snapshot, settings, setActiveTab, initialTaskId, onClearT
     });
   };
 
-  // ── Pin / copy are handled directly via chat.* ──────────────────────────
+  // ── Derived: sessions with display state overlaid ────────────────────────
+  const displaySessions = useMemo(
+    () => chat.sessions.map((s) => chat.getSessionDisplay(s)),
+    [chat.sessions, chat.getSessionDisplay],
+  );
+  const displayOpencodeSessions = useMemo(
+    () => chat.opencodeSessions.map((s) => chat.getSessionDisplay(s)),
+    [chat.opencodeSessions, chat.getSessionDisplay],
+  );
+
+  // ── Current session for the thread head subtitle ────────────────────────
+  const activeSessionDisplay = useMemo(() => {
+    const id = chat.activeSource === 'opencode'
+      ? chat.activeOpencodeSessionId ?? ''
+      : chat.sessionId;
+    if (!id) return null;
+    return (
+      displaySessions.find((s) => s.id === id) ??
+      displayOpencodeSessions.find((s) => s.id === id) ??
+      null
+    );
+  }, [
+    chat.activeSource,
+    chat.activeOpencodeSessionId,
+    chat.sessionId,
+    displaySessions,
+    displayOpencodeSessions,
+  ]);
+
+  const threadSubtitle = (() => {
+    const base = `${agent || 'Odin'} · ${snapshot.activeProject?.name ?? 'no project'}`;
+    const state = activeSessionDisplay?.state ?? 'idle';
+    if (state === 'streaming') return `Replying · ${base}`;
+    if (state === 'awaiting') return `Your turn · ${base}`;
+    return `${base} · idle`;
+  })();
 
   return (
     <div className="chat-shell">
@@ -125,35 +172,71 @@ export function Chat({ snapshot, settings, setActiveTab, initialTaskId, onClearT
         onToggleInfo={() => {}}
         onOpenOverview={() => setActiveTab?.('overview')}
       />
-      <div className="chat-body">
-        <aside className="chat-sessions">
-          <SessionList
-            sessions={chat.sessions}
-            opencodeSessions={chat.opencodeSessions}
-            activeSessionId={chat.sessionId}
-            activeOpencodeSessionId={chat.activeOpencodeSessionId}
-            activeProject={snapshot.activeProject}
-            onCreateSession={handleCreateSession}
-            onSelectSession={chat.selectBizarSession}
-            onSelectOpencodeSession={(s) => chat.loadOpencodeSession(s.id)}
-            creating={creating}
-          />
-        </aside>
-
-        <main className="chat-main">
-          <ChatThread
-            messages={chat.activeSource === 'opencode' ? chat.opencodeMessages : chat.bizarMessages}
-            loading={chat.loading}
-            activeProject={snapshot.activeProject}
-            sessionId={chat.activeSource === 'opencode' ? (chat.activeOpencodeSessionId ?? chat.sessionId) : chat.sessionId}
-            pinned={chat.pinned}
-            onPickSuggestion={(t) => setText(t)}
-            onCopy={(m) => chat.copyMessage(m as Parameters<typeof chat.copyMessage>[0])}
-            onDelete={handleDelete}
-            onTogglePin={chat.togglePin}
-            onRegenerate={chat.onRegenerate}
-          />
-          <FloatingComposer
+      <div className="chat-page">
+        {/* ── rail ──────────────────────────────────────────────────────── */}
+        <ChatRail
+          sessions={displaySessions}
+          opencodeSessions={displayOpencodeSessions}
+          activeSessionId={chat.sessionId}
+          activeOpencodeSessionId={chat.activeOpencodeSessionId}
+          activeProject={snapshot.activeProject}
+          creating={creating}
+          onCreateSession={handleCreateSession}
+          onSelectSession={chat.selectBizarSession}
+          onSelectOpencodeSession={(s) => chat.loadOpencodeSession(s.id)}
+          onRenameSession={(id, title) => chat.renameSession(id, title)}
+          onDeleteSession={(id) => chat.deleteSession(id)}
+        />
+
+        {/* ── thread ───────────────────────────────────────────────────── */}
+        <section className="chat-thread-section">
+          <div className="chat-thread-head">
+            <div>
+              <div className="chat-thread-title">
+                {activeSessionDisplay?.title ?? chat.sessionId ?? 'New chat'}
+              </div>
+              <div
+                className={`chat-thread-sub chat-muted state-${activeSessionDisplay?.state ?? 'idle'}`}
+              >
+                <span className="chat-thread-dot" />
+                {threadSubtitle}
+              </div>
+            </div>
+            <div className="chat-thread-actions">
+              <button className="btn btn-ghost" title="Rename" type="button">
+                <span className="mono">rename</span>
+              </button>
+            </div>
+          </div>
+
+          <div className="chat-thread-scroll" ref={chat.listRef} onScroll={chat.handleScroll}>
+            <ChatThread
+              messages={chat.activeSource === 'opencode' ? chat.opencodeMessages : chat.bizarMessages}
+              loading={chat.loading}
+              activeProject={snapshot.activeProject}
+              sessionId={
+                chat.activeSource === 'opencode'
+                  ? (chat.activeOpencodeSessionId ?? chat.sessionId)
+                  : chat.sessionId
+              }
+              pinned={chat.pinned}
+              onPickSuggestion={(t) => setText(t)}
+              onCopy={(m) => chat.copyMessage(m as Parameters<typeof chat.copyMessage>[0])}
+              onDelete={handleDelete}
+              onTogglePin={chat.togglePin}
+              onRegenerate={chat.onRegenerate}
+            />
+          </div>
+
+          {!chat.stickToBottom && (
+            <JumpToLatest
+              streaming={activeSessionDisplay?.state === 'streaming'}
+              newMessageCount={chat.newMessageCount}
+              onClick={chat.jumpToLatest}
+            />
+          )}
+
+          <ChatComposer
             agent={agent}
             setAgent={setAgent}
             model={model}
@@ -168,24 +251,31 @@ export function Chat({ snapshot, settings, setActiveTab, initialTaskId, onClearT
             onPickSuggestion={(cmd) => setText(`${cmd.split(' ')[0]} `)}
             agents={snapshot.agents || []}
             onAttach={onAttach}
-            sessionsOpen={true}
-            infoOpen={true}
           />
-          <input ref={fileInputRef} type="file" multiple style={{ display: 'none' }} onChange={onFiles} />
-        </main>
-
-        <aside className="chat-info">
-          <InfoPanel
-            sessionId={chat.activeSource === 'opencode' ? (chat.activeOpencodeSessionId ?? chat.sessionId) : chat.sessionId}
-            messages={chat.activeSource === 'opencode' ? chat.opencodeMessages : chat.bizarMessages}
-            pinned={chat.pinned}
-            agent={agent}
-            model={model}
-            agents={snapshot.agents || []}
-            mcps={snapshot.mcps || []}
-            allCommands={allCommands}
+          <input
+            ref={fileInputRef}
+            type="file"
+            multiple
+            style={{ display: 'none' }}
+            onChange={onFiles}
           />
-        </aside>
+        </section>
+
+        {/* ── info panel ──────────────────────────────────────────────── */}
+        <ChatInfoPanel
+          sessionId={
+            chat.activeSource === 'opencode'
+              ? (chat.activeOpencodeSessionId ?? chat.sessionId)
+              : chat.sessionId
+          }
+          messages={chat.activeSource === 'opencode' ? chat.opencodeMessages : chat.bizarMessages}
+          pinned={chat.pinned}
+          agent={agent}
+          model={model}
+          agents={snapshot.agents || []}
+          mcps={snapshot.mcps || []}
+          allCommands={allCommands}
+        />
       </div>
     </div>
   );

package/bizar-dash/src/web/views/Tasks.tsx

@@ -30,6 +30,7 @@ import {
   RefreshCw,
   Send,
   FileText,
+  Inbox,
 } from 'lucide-react';
 import { Button } from '../components/Button';
 import { Card, CardTitle } from '../components/Card';
@@ -45,6 +46,7 @@ import { api, enhancePrompt } from '../lib/api';
 import { cn, formatRelative, priorityColors, autoTitleFromContent } from '../lib/utils';
 import type { Agent, Settings, Snapshot, Task } from '../lib/types';
 import { openArtifactViewer } from '../components/ArtifactViewer';
+import { BacklogPanel } from '../components/tasks/BacklogPanel';
 
 type Props = {
   snapshot: Snapshot;
@@ -319,6 +321,10 @@ export function Tasks({ snapshot, refreshSnapshot, setActiveTab }: Props) {
     openArtifactViewer(modal, artifactId);
   };
 
+  // v3.22 — Backlog panel visibility.
+  const [showBacklog, setShowBacklog] = useState(false);
+  const backlogCount = (snapshot.tasks || []).filter((t) => t.status === 'backlog').length;
+
   return (
     <div className="view view-tasks">
       <header className="view-header">
@@ -447,9 +453,25 @@ export function Tasks({ snapshot, refreshSnapshot, setActiveTab }: Props) {
           >
             <Plus size={14} /> Add
           </Button>
+          {backlogCount > 0 && (
+            <Button
+              variant={showBacklog ? 'accent' : 'ghost'}
+              size="sm"
+              onClick={() => setShowBacklog((v) => !v)}
+              title={showBacklog ? 'Hide backlog' : 'Show backlog'}
+            >
+              <Inbox size={14} />
+              Backlog
+              <span className="badge">{backlogCount}</span>
+            </Button>
+          )}
         </div>
       </div>
 
+      {showBacklog && backlogCount > 0 && (
+        <BacklogPanel agents={snapshot.agents || []} onRefresh={refreshSnapshot} />
+      )}
+
       {selected.size > 0 && (
         <div className="task-bulk-bar">
           <span className="text-sm">
@@ -900,7 +922,7 @@ function formatDuration(seconds: number): string {
   return `${m}m`;
 }
 
-function openTaskModal(
+export function openTaskModal(
   modal: ReturnType<typeof useModal>,
   toast: ReturnType<typeof useToast>,
   task: Task | null,

package/cli/bg.mjs

@@ -15,10 +15,11 @@
  *   kill <id>          Kill a running agent
  *   logs <id>          Tail the agent's log file
  *
- * The "view" subcommand is the headline feature: it gives the user
- * one terminal window with all running agents visible at once via
- * tmux splits. This is the antidote to "is the agent doing
- * anything?" — you can SEE them all working in parallel.
+ * The "view" subcommand (v3.22) is the headline feature: it creates a
+ * tmux control session (`bizar-bg-view`) with one pane per running
+ * agent (each pane attached to the agent's own tmux session, tiled).
+ * This is the antidote to "is the agent doing anything?" — you can
+ * SEE them all working in parallel.
  */
 import { execFileSync, spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
@@ -245,59 +246,112 @@ async function runKill(instanceId) {
 // --- view ----------------------------------------------------------------
 
 /**
- * Build a tmux "control session" that splits into N panes, each
- * showing the log of one running agent. The session name is fixed
- * (`bgr_view`) so subsequent `bizar bg view` calls reuse it.
+ * View subcommand (v3.22):
+ *   - Detects tmux. If missing, prints per-instance `bizar bg logs <id>`
+ *     fallback instructions and exits 0.
+ *   - Creates a fresh tmux control session `bizar-bg-view` with one pane
+ *     per running instance, each pane running `tmux attach -t <session>`.
+ *   - Caps at 16 panes (beyond that, tmux tiled layout degrades).
+ *   - Zero running instances → prints "no running agents" and exits 0.
  */
-function buildTmuxControlSession() {
+
+async function runView() {
   const all = readAllBgInstances();
-  const tmux = listBgrTmuxSessions();
+  const tmuxSessions = listBgrTmuxSessions();
   const running = all.filter(
+    (e) => e.data.status === 'running' || e.data.status === 'pending',
+  );
+
+  // Zero running agents — not an error.
+  if (running.length === 0) {
+    console.log(chalk.dim('\n  No running background agents.\n'));
+    return 0;
+  }
+
+  // Tmux presence check. If missing, print fallback instructions and exit 0
+  // (not an error — the operator can still use per-instance logs).
+  if (!which('tmux')) {
+    console.log(chalk.yellow('\n  ⚠ tmux is not installed on this host.\n'));
+    console.log(chalk.dim('  You can inspect individual agents via:\n'));
+    for (const r of running) {
+      console.log(chalk.cyan(`    bizar bg logs ${r.data.instanceId}`));
+    }
+    console.log();
+    return 0;
+  }
+
+  // Filter to instances that actually have a live tmux session.
+  const active = running.filter(
     (e) =>
-      (e.data.status === 'running' || e.data.status === 'pending') &&
       e.data.sessionId &&
-      tmux.includes(tmuxSessionForSessionId(e.data.sessionId)),
+      tmuxSessions.includes(tmuxSessionForSessionId(e.data.sessionId)),
   );
 
-  if (running.length === 0) {
-    return { ok: false, reason: 'no-running-agents' };
+  if (active.length === 0) {
+    console.log(chalk.dim('\n  No agents with active tmux sessions found.\n'));
+    console.log(chalk.dim('  State files exist but no tmux sessions are running.\n'));
+    console.log(chalk.dim('  Run `bizar bg list` to inspect state.\n'));
+    return 0;
   }
 
-  // 1. Create a fresh control session (or replace the existing one).
+  // Cap at 16 panes — beyond that, tiled layout is unusable.
+  const capped = active.slice(0, 16);
+  const overflow = active.length - capped.length;
+
+  // Kill any stale bizar-bg-view session, then create a fresh one.
   try {
-    execFileSync('tmux', ['kill-session', '-t', 'bgr_view'], { stdio: 'pipe' });
+    execFileSync('tmux', ['kill-session', '-t', 'bizar-bg-view'], { stdio: 'pipe' });
   } catch {
-    // didn't exist
+    /* didn't exist */
   }
   execFileSync('tmux', [
-    'new-session', '-d', '-s', 'bgr_view',
+    'new-session', '-d', '-s', 'bizar-bg-view',
     '-x', '220', '-y', '50',
   ], { stdio: 'pipe' });
 
-  // 2. For each running agent after the first, split the pane
-  //    and attach a tail in the new pane.
-  for (let i = 1; i < running.length; i++) {
-    const splitCmd = i % 2 === 1 ? 'split-window -h -t bgr_view' : 'split-window -v -t bgr_view';
-    execFileSync('tmux', splitCmd.split(' '), { stdio: 'pipe' });
-  }
-  // Apply tiled layout for a clean grid.
-  execFileSync('tmux', ['select-layout', '-t', 'bgr_view', 'tiled'], { stdio: 'pipe' });
-
-  // 3. Send a label + tail command to each pane.
-  for (let i = 0; i < running.length; i++) {
-    const r = running[i];
-    const tmuxName = tmuxSessionForSessionId(r.data.sessionId);
-    const logPath = r.data.logPath || join(homedir(), '.cache', 'bizar', 'logs', `${r.data.sessionId}.log`);
-    const header = `echo "═══ ${r.data.agent} │ ${r.data.instanceId} │ ${tmuxName} ═══"; tail -n 200 -F "${logPath}"`;
-    // Use send-keys so the echo+tail are sent in sequence, then Enter
-    // to run them. Target the pane by index in the bgr_view session.
+  // Pane 0 → first instance
+  const firstSession = tmuxSessionForSessionId(capped[0].data.sessionId);
+  execFileSync('tmux', [
+    'send-keys', '-t', 'bizar-bg-view:0.0',
+    `tmux attach -t ${firstSession}`, 'Enter',
+  ], { stdio: 'pipe' });
+
+  // Split for remaining instances (2..N)
+  for (let i = 1; i < capped.length; i++) {
+    execFileSync('tmux', ['split-window', '-v', '-t', 'bizar-bg-view'], { stdio: 'pipe' });
+    const sessionName = tmuxSessionForSessionId(capped[i].data.sessionId);
     execFileSync('tmux', [
-      'send-keys', '-t', `bgr_view:0.${i}`,
-      header, 'Enter',
+      'send-keys', '-t', `bizar-bg-view:0.${i}`,
+      `tmux attach -t ${sessionName}`, 'Enter',
     ], { stdio: 'pipe' });
   }
 
-  return { ok: true, count: running.length, session: 'bgr_view' };
+  // Tiled layout for a clean grid.
+  execFileSync('tmux', ['select-layout', '-t', 'bizar-bg-view', 'tiled'], { stdio: 'pipe' });
+
+  console.log(chalk.green(`\n  ✓ Built tmux view session with ${capped.length} pane(s)\n`));
+
+  if (overflow > 0) {
+    console.log(chalk.yellow(`  ⚠ ${overflow} more agent(s) not shown (16-pane cap):\n`));
+    for (const r of active.slice(16)) {
+      const sn = tmuxSessionForSessionId(r.data.sessionId);
+      console.log(chalk.dim(`    bizar bg logs ${r.data.instanceId}  —  tmux attach -t ${sn}`));
+    }
+    console.log();
+  }
+
+  // Open an OS terminal window attached to the control session.
+  const open = openTerminalAttached('bizar-bg-view');
+  if (open.ok) {
+    console.log(chalk.green(`  ✓ Opened ${open.terminal} attached to "bizar-bg-view"\n`));
+    console.log(chalk.dim('  Tip: `tmux attach -t bizar-bg-view` from any terminal.\n'));
+  } else {
+    console.log(chalk.yellow(`  ⚠ Could not open terminal: ${open.error}\n`));
+    console.log(chalk.dim('  Run in a terminal you can see:\n'));
+    console.log(chalk.cyan(`    tmux attach -t bizar-bg-view\n`));
+  }
+
+  return 0;
 }
 
 /**
@@ -362,39 +416,7 @@ function openTerminalAttached(tmuxSession) {
   return { ok: false, error: `unsupported platform: ${platform}` };
 }
 
-async function runView() {
-  if (!which('tmux')) {
-    console.log(chalk.red('\n  ✗ tmux is not installed. Install it and retry.'));
-    console.log(chalk.dim('    macOS:  brew install tmux'));
-    console.log(chalk.dim('    Linux:  apt-get install tmux  (or your distro equivalent)'));
-    console.log(chalk.dim('    Windows: choco install tmux\n'));
-    return 1;
-  }
-
-  const build = buildTmuxControlSession();
-  if (!build.ok) {
-    if (build.reason === 'no-running-agents') {
-      console.log(chalk.dim('\n  No running background agents to view.\n'));
-      console.log(chalk.dim('  Spawn one with `bizar_spawn_background` (Odin) or via the dashboard,\n'));
-      console.log(chalk.dim('  then re-run this command.\n'));
-      return 1;
-    }
-    console.log(chalk.red(`\n  ✗ Failed to build control session: ${build.error || build.reason}\n`));
-    return 1;
-  }
 
-  console.log(chalk.green(`\n  ✓ Built tmux control session with ${build.count} pane(s)\n`));
-  const open = openTerminalAttached(build.session);
-  if (open.ok) {
-    console.log(chalk.green(`  ✓ Opened ${open.terminal} attached to tmux session "${build.session}"\n`));
-    console.log(chalk.dim(`  Tip: \`tmux attach -t ${build.session}\` from any terminal.\n`));
-  } else {
-    console.log(chalk.yellow(`  ⚠ Could not open a terminal window: ${open.error}\n`));
-    console.log(chalk.dim('  Run one of the following in a terminal you can see:\n'));
-    console.log(chalk.cyan(`    tmux attach -t ${build.session}\n`));
-  }
-  return 0;
-}
 
 // --- Help ----------------------------------------------------------------
 
@@ -416,8 +438,9 @@ function showHelp() {
     and a log file (default ~/.cache/bizar/logs/<sessionId>.log).
 
     The \`view\` subcommand is the headline feature: it creates a new
-    tmux session (\`bgr_view\`) with one pane per running agent, then
-    opens a new OS terminal window attached to it. You can see all
+    tmux session (\`bizar-bg-view\`) with one pane per running agent,
+    each pane attached to the agent's own tmux session (tiled layout),
+    then opens a new OS terminal window attached to it. You can see all
     your agents working in parallel at a glance.
   `);
 }

package/cli/bin.mjs

@@ -291,17 +291,27 @@ function showServiceHelp() {
   bizar service — Manage the background service daemon
 
   Usage:
-    bizar service start        Start the service in background
-    bizar service stop         Stop the running service
-    bizar service status       Show whether the service is running
-    bizar service logs         Tail the service log
-    bizar service follow       Follow the service log until Ctrl-C
+    bizar service start            Start the service in background
+    bizar service stop             Stop the running service
+    bizar service status           Show whether the service is running
+    bizar service logs             Tail the service log
+    bizar service follow           Follow the service log until Ctrl-C
+    bizar service install          Register with systemd / launchd / scheduled task
+    bizar service install --force  Re-install even when the unit matches
+    bizar service uninstall        Remove the OS-level autostart
+    bizar service uninstall --force  Force-uninstall even when nothing is registered
 
   Description:
     The service watches per-project schedules (cron / interval / once)
     and runs them at the right time. It logs to
     ${bizarConfigDir}/service.log and writes its PID to
     ${bizarConfigDir}/service.pid.
+
+    install registers the daemon under the OS init system — systemd user
+    unit on Linux, launchd LaunchAgent on macOS, scheduled task
+    ("BizarDashboardService", ONSTART, HIGHEST) on Windows. After
+    install, a normal user does not need to run \`bizar service start\`
+    for the dashboard background process — the OS does it at login.
   `);
 }
 
@@ -613,9 +623,11 @@ async function runTestGate() {
 }
 
 /**
- * Service commands — start / stop / status / logs.
+ * Service commands — start / stop / status / logs / install / uninstall.
  *
- * Implementation lives in cli/service.mjs (created below).
+ * Implementation lives in cli/service.mjs. The install / uninstall
+ * branches delegate to cli/service-controller.mjs for OS-level
+ * registration (systemd / launchd / schtasks).
  */
 async function runServiceCommand(sub) {
   const { runService } = await import('./service.mjs');
@@ -820,7 +832,23 @@ async function runDash(dashArgs) {
 
   switch (sub) {
     case 'start':
-      await dashModule.start(subOpts);
+      // v4.4.0 — When `--bg` is passed, spawn the dashboard as a
+      // detached child process via the dash module's startInBackground
+      // helper, then return. Without this, runDash calls startDashboard
+      // in-process; once the bin's main() resolves, the bin process
+      // exits and takes the dashboard's HTTP server with it. The
+      // downstream effect is "(intermediate value)(intermediate value)
+      // (intermediate value) is not a function or its return value is
+      // not iterable" — a pre-existing crash signature in this codepath.
+      if (subOpts.bg) {
+        // Spawn the dashboard as a detached child process. The child's
+        // argv is `node cli.mjs start --bg` so the dash module's own
+        // CLI dispatch hits the background branch and runs
+        // startDashboard in the child, not the parent.
+        await dashModule.startInBackground(['start', ...(subOpts.subArgs || [])]);
+      } else {
+        await dashModule.start(subOpts);
+      }
       break;
     case 'stop':
       await dashModule.stop(subOpts);