@polderlabs/bizar 10.4.4 → 10.6.0

package/bizar-dash/src/server/routes/loops.mjs

@@ -0,0 +1,138 @@
+/**
+ * src/server/routes/loops.mjs
+ *
+ * G-autoloop Phase 5 — HTTP surface for the loop runtime.
+ *
+ * Endpoints (mounted under `/api/loops`):
+ *   GET    /api/loops                  — snapshot of all known loops
+ *   GET    /api/loops/:id              — single loop state
+ *   POST   /api/loops                  — create a new pending loop
+ *   PATCH  /api/loops/:id              — patch fields (intervalMs, maxIterations, etc.)
+ *   POST   /api/loops/:id/start        — flip status to 'running' (idempotent)
+ *   POST   /api/loops/:id/stop         — flip status to 'stopped' (idempotent)
+ *   DELETE /api/loops/:id              — delete the state file
+ *
+ * The actual scheduling (in-process setInterval) happens in
+ * `loop-runtime.mjs`. This router owns only the HTTP wiring — keeps
+ * the runtime pure + testable.
+ *
+ * Phase 5 deliberately stops short of dispatching real tasks here.
+ * That's wired in a follow-up so we can ship the loop infrastructure
+ * (CRUD + scheduler) and let a dedicated route pair it with the real
+ * `taskDelegator` + project-store integration.
+ */
+
+import { Router } from 'express';
+import {
+  createLoop,
+  readLoop,
+  patchLoop,
+  deleteLoop,
+  listLoops,
+  snapshotLoops,
+  startLoop,
+  stopLoop,
+} from '../loop-runtime.mjs';
+import { wrap } from './_shared.mjs';
+
+const VALID_PATCH_FIELDS = new Set([
+  'name',
+  'intervalMs',
+  'maxIterations',
+  'projectId',
+]);
+
+/**
+ * @param {Object} deps
+ * @param {Function} [deps.broadcast]
+ */
+export function createLoopsRouter({ broadcast = () => {} } = {}) {
+  const router = Router();
+
+  router.get('/loops', wrap(async (req, res) => {
+    const snap = snapshotLoops();
+    res.json({ loops: Object.values(snap), count: Object.keys(snap).length });
+  }));
+
+  router.get('/loops/:id', wrap(async (req, res) => {
+    const s = readLoop(req.params.id);
+    if (!s) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    res.json(s);
+  }));
+
+  router.post('/loops', wrap(async (req, res) => {
+    const body = req.body || {};
+    if (!body.projectId) {
+      res.status(400).json({ error: 'bad_request', message: 'projectId required' });
+      return;
+    }
+    const s = createLoop({
+      projectId: body.projectId,
+      name: body.name,
+      intervalMs: body.intervalMs,
+      maxIterations: body.maxIterations,
+    });
+    broadcast({ type: 'loops:change', loop: s });
+    res.status(201).json(s);
+  }));
+
+  router.patch('/loops/:id', wrap(async (req, res) => {
+    const patch = {};
+    for (const [k, v] of Object.entries(req.body || {})) {
+      if (VALID_PATCH_FIELDS.has(k)) patch[k] = v;
+    }
+    const next = patchLoop(req.params.id, patch);
+    if (!next) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'loops:change', loop: next });
+    res.json(next);
+  }));
+
+  // Start a loop. The runtime owns the timer; this just flips state.
+  // We re-use `startLoop` from the runtime so the in-process scheduler
+  // is the single source of truth. If the caller passed a `dry` flag,
+  // we only flip the state without engaging the timer — useful for
+  // the dashboard's "arm only" toggle.
+  router.post('/loops/:id/start', wrap(async (req, res) => {
+    const dry = req.body && req.body.dry === true;
+    let next;
+    try {
+      next = dry ? patchLoop(req.params.id, { status: 'running' }) : startLoop(req.params.id, {});
+    } catch (err) {
+      res.status(404).json({ error: 'not_found', message: err.message });
+      return;
+    }
+    if (!next) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'loops:change', loop: next });
+    res.json(next);
+  }));
+
+  router.post('/loops/:id/stop', wrap(async (req, res) => {
+    const next = stopLoop(req.params.id);
+    if (!next) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'loops:change', loop: next });
+    res.json(next);
+  }));
+
+  router.delete('/loops/:id', wrap(async (req, res) => {
+    // Stop the in-process timer first so it doesn't keep firing on a
+    // deleted state.json.
+    stopLoop(req.params.id);
+    deleteLoop(req.params.id);
+    broadcast({ type: 'loops:deleted', loopId: req.params.id });
+    res.status(204).end();
+  }));
+
+  return router;
+}

package/bizar-dash/src/server/task-splitter.mjs

@@ -0,0 +1,241 @@
+/**
+ * src/server/task-splitter.mjs
+ *
+ * v10.6.0 — G-autoloop Phase 3. Task ordering + auto-splitting.
+ *
+ * The "best order" problem the user cares about has three pieces:
+ *
+ *   1. Order.    Which ready task should the loop pick next? Already
+ *                solved in `loop-runtime.mjs:pickReadyTasks` (priority
+ *                then age, dependencies gated on `done` status).
+ *
+ *   2. Size.     How big is each task? Operators want to know
+ *                "`tsk_abc` is L-sized" before they let the loop loose
+ *                on it. Size is a heuristic over title/description
+ *                length, presence of linked goal/KR, and historical
+ *                completion times.
+ *
+ *   3. Split.    Tasks tagged `size ∈ { L, XL }` get routed to the
+ *                `task-decomposer` agent, which returns 2-N smaller
+ *                tasks. The new tasks link back via `parentTaskId`
+ *                so progress aggregates up. The parent stays open
+ *                until all children are `done`.
+ *
+ * This module implements pure functions for (2) and (3). Splitting
+ * itself delegates to a caller-supplied `decompose` function so we
+ * don't bake an LLM call into the harness — that's the agent's job
+ * (per our architecture boundary: skills/MCP define agent behaviour,
+ * not the dash server).
+ */
+
+const SIZE_ORDER = ['S', 'M', 'L', 'XL'];
+
+/**
+ * Estimate a task's size bucket from its title, description, linked
+ * goals, and history. Heuristic, no LLM. Buckets: S, M, L, XL.
+ *
+ * Signals:
+ *   - title word count        : +0.2 per word over 6
+ *   - description char count  : +0.001 per char over 200
+ *   - linked goal/KR          : +1 size point each
+ *   - avg historical duration : +1 if > 2h, +2 if > 6h
+ *
+ * @param {Object} task
+ * @param {string} task.title
+ * @param {string} [task.description]
+ * @param {Object} [task.metadata]      may carry goalId/krId
+ * @param {Array}  [history]            prior tasks from this assignee;
+ *                                      we use title-length buckets and
+ *                                      avg `timeSpent` minutes as a
+ *                                      proxy for difficulty.
+ * @returns {'S'|'M'|'L'|'XL'}
+ */
+export function estimateSize(task, history = []) {
+  if (!task || typeof task !== 'object') return 'M';
+  const title = String(task.title || '');
+  const desc = String(task.description || '');
+  const meta = task.metadata || {};
+
+  let score = 0;
+  // Title length signal — every word over 6 adds 0.2 to the score.
+  const words = title.trim().split(/\s+/).filter(Boolean);
+  if (words.length > 6) score += (words.length - 6) * 0.2;
+
+  // Description length signal — chars over 200 add 0.001 each.
+  if (desc.length > 200) score += (desc.length - 200) * 0.001;
+
+  // Linked goal / KR — both count.
+  if (meta.goalId) score += 1;
+  if (meta.krId) score += 1;
+
+  // Historical signal — if prior similar-sized tasks took > 2h, push up.
+  const historicalMinutes = avgHistoricalMinutes(task, history);
+  if (historicalMinutes > 360) score += 2;      // > 6h
+  else if (historicalMinutes > 120) score += 1; // > 2h
+
+  return scoreToBucket(score);
+}
+
+function scoreToBucket(score) {
+  if (score < 0.5) return 'S';
+  if (score < 1.5) return 'M';
+  if (score < 3.0) return 'L';
+  return 'XL';
+}
+
+/**
+ * Average minutes spent on historical tasks that share at least 2
+ * title-words with the candidate. We treat very short histories
+ * (< 2 items) as unreliable and return 0.
+ *
+ * @param {Object} task
+ * @param {Array}  history
+ * @returns {number}
+ */
+export function avgHistoricalMinutes(task, history) {
+  if (!task || !Array.isArray(history) || history.length < 2) return 0;
+  const titleWords = new Set(
+    String(task.title || '').toLowerCase().split(/\s+/).filter((w) => w.length > 3),
+  );
+  if (titleWords.size === 0) return 0;
+  const similar = history.filter((h) => {
+    if (!h || !h.title) return false;
+    const hw = new Set(String(h.title).toLowerCase().split(/\s+/).filter((w) => w.length > 3));
+    let overlap = 0;
+    for (const w of titleWords) if (hw.has(w)) overlap++;
+    return overlap >= 2;
+  });
+  if (similar.length === 0) return 0;
+  let total = 0;
+  let count = 0;
+  for (const h of similar) {
+    const mins = Number(h.timeSpent) || 0;
+    if (mins > 0) {
+      total += mins;
+      count++;
+    }
+  }
+  return count > 0 ? total / count : 0;
+}
+
+/**
+ * Decide whether a task should be split. Threshold: `size ∈ { L, XL }`
+ * OR explicit `metadata.autoSplit === true`.
+ *
+ * @param {Object} task
+ * @param {Array}  [history]
+ * @returns {boolean}
+ */
+export function shouldSplit(task, history = []) {
+  if (!task) return false;
+  if (task.metadata && task.metadata.autoSplit === true) return true;
+  if (task.metadata && task.metadata.autoSplit === false) return false;
+  const size = estimateSize(task, history);
+  return size === 'L' || size === 'XL';
+}
+
+/**
+ * Plan a split. Returns the **call shape** the caller dispatches to a
+ * `task-decomposer` agent (LLM-step), plus the metadata that should
+ * be patched back onto the parent. The agent must return:
+ *
+ *   [{ title, description?, size?, priority? }, ...]      // 2..N tasks
+ *
+ * @param {Object} parent
+ * @returns {Object} plan
+ *   - kind: 'task-decompose'
+ *   - parentTaskId
+ *   - prompt: natural-language instruction for the agent
+ *   - constraints: { min: 2, max: 5 } — the agent may not exceed this
+ */
+export function planSplit(parent) {
+  if (!parent || !parent.id) throw new TypeError('planSplit: task id required');
+  const p = parent;
+  return {
+    kind: 'task-decompose',
+    parentTaskId: p.id,
+    prompt: [
+      `Break the following task into 2-5 smaller, independently-completable subtasks.`,
+      `Each subtask should be completable in under 30 minutes by a single subagent.`,
+      ``,
+      `Title: ${p.title || '(no title)'}`,
+      `Description: ${p.description || '(no description)'}`,
+      p.assignee ? `Original assignee: ${p.assignee}` : null,
+      p.metadata && p.metadata.goalId ? `Linked goal: ${p.metadata.goalId}` : null,
+    ].filter(Boolean).join('\n'),
+    constraints: { min: 2, max: 5 },
+  };
+}
+
+/**
+ * Validate a `task-decompose` response. Returns an array of task
+ * seeds (without ids — those are minted by the task store on create).
+ *
+ * @param {Array}  candidates
+ * @param {Object} [opts]
+ * @param {number} [opts.min=2]
+ * @param {number} [opts.max=5]
+ * @returns {Array} cleaned seeds, ready to be passed to `tasksStore.create`
+ */
+export function acceptSplit(candidates, { min = 2, max = 5 } = {}) {
+  if (!Array.isArray(candidates)) return [];
+  const out = [];
+  for (const c of candidates) {
+    if (!c || typeof c !== 'object') continue;
+    if (!c.title || typeof c.title !== 'string') continue;
+    out.push({
+      title: String(c.title).slice(0, 200),
+      description: c.description ? String(c.description).slice(0, 4000) : '',
+      priority: Number.isFinite(c.priority) ? c.priority : 5,
+      tags: Array.isArray(c.tags) ? c.tags.filter((t) => typeof t === 'string') : ['autosplit'],
+    });
+    if (out.length >= max) break;
+  }
+  if (out.length < min) return [];
+  return out;
+}
+
+/**
+ * Roll up child task progress into the parent's `metadata.progress`
+ * (0..1) and auto-complete the parent when all children are `done`.
+ *
+ * Pure function — the caller is responsible for writing back to the
+ * task store. Returns `{ ratio, allDone }`. If `parent` has no
+ * children array, returns `{ ratio: 0, allDone: false }`.
+ *
+ * @param {Object} parent
+ * @returns {Object}
+ */
+export function rollupProgress(parent) {
+  if (!parent) return { ratio: 0, allDone: false };
+  const children = Array.isArray(parent.subtasks) ? parent.subtasks : [];
+  if (children.length === 0) return { ratio: 0, allDone: false };
+  let done = 0;
+  for (const c of children) {
+    if (c && c.status === 'done') done++;
+  }
+  const ratio = done / children.length;
+  return { ratio, allDone: done === children.length };
+}
+
+/**
+ * Suggest a goal-aware priority bump. If a task links to a goal whose
+ * status is `at-risk` or `blocked`, bump its priority by 1; if `done`,
+ * drop the task to backlog. Pure helper; caller decides what to do
+ * with the result.
+ *
+ * @param {Object} task
+ * @param {Object} [goal]   parsed goal object (from progress-parser)
+ * @returns {{ priority: number, action: 'bump'|'drop'|'none' }}
+ */
+export function goalAwarePriority(task, goal) {
+  if (!task || !goal) return { priority: Number.isFinite(task && task.priority) ? task.priority : 5, action: 'none' };
+  const base = Number.isFinite(task.priority) ? task.priority : 5;
+  if (goal.status === 'at-risk') return { priority: Math.max(1, base - 1), action: 'bump' };
+  if (goal.status === 'blocked') return { priority: base, action: 'none' };
+  if (goal.status === 'done') return { priority: 9, action: 'drop' };
+  return { priority: base, action: 'none' };
+}
+
+/** Exported for tests + UI. */
+export const __sizeBuckets = SIZE_ORDER;

package/bizar-dash/src/web/v8/shell/Sidebar.tsx

@@ -1,8 +1,44 @@
-import { useState, type ReactNode } from 'react';
+import { useState, type CSSProperties, type ReactNode } from 'react';
 import { Box } from '../ui/primitives/Box.js';
 import { Stack } from '../ui/primitives/Stack.js';
 import { Separator } from '../ui/primitives/Separator.js';
 import { ScrollArea } from '../ui/primitives/ScrollArea.js';
+
+const sidebarSectionHeaderStyle: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 'var(--space-2)',
+};
+
+const sidebarSectionLabelStyle: CSSProperties = {
+  fontSize: 'var(--fs-12)',
+  fontWeight: 600,
+  color: 'var(--fg-subtle)',
+  letterSpacing: 'var(--tracking-wide)',
+  textTransform: 'uppercase',
+  flex: 1,
+  padding: 'var(--space-1) var(--space-3)',
+};
+
+const sidebarSectionToggleStyle: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  width: 20,
+  height: 20,
+  background: 'transparent',
+  border: 0,
+  color: 'var(--fg-subtle)',
+  cursor: 'pointer',
+  padding: 0,
+};
+
+const sidebarSectionChevronStyle = (open: boolean): CSSProperties => ({
+  display: 'inline-block',
+  transition: 'transform var(--motion-fast) var(--ease-out)',
+  transform: open ? 'rotate(90deg)' : 'rotate(0deg)',
+  fontSize: 10,
+});
 import {
   Activity,
   Bell,
@@ -362,18 +398,8 @@ function SidebarSectionView({
   return (
     <Stack gap={1} data-sidebar-section={section.id}>
       {!collapsed && (
-        <div role="presentation" style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-2)' }}>
-          <span
-            style={{
-              fontSize: 'var(--fs-12)',
-              fontWeight: 600,
-              color: 'var(--fg-subtle)',
-              letterSpacing: 'var(--tracking-wide)',
-              textTransform: 'uppercase',
-              flex: 1,
-              padding: 'var(--space-1) var(--space-3)',
-            }}
-          >
+        <div role="presentation" style={sidebarSectionHeaderStyle}>
+          <span style={sidebarSectionLabelStyle}>
             {section.label}
           </span>
           <button
@@ -383,28 +409,12 @@ function SidebarSectionView({
             aria-controls={`sidebar-section-${section.id}`}
             data-section-toggle={section.id}
             data-testid={`sidebar-section-toggle-${section.id}`}
-            style={{
-              display: 'inline-flex',
-              alignItems: 'center',
-              justifyContent: 'center',
-              width: 20,
-              height: 20,
-              background: 'transparent',
-              border: 0,
-              color: 'var(--fg-subtle)',
-              cursor: 'pointer',
-              padding: 0,
-            }}
+            style={sidebarSectionToggleStyle}
           >
             <span
               aria-hidden="true"
               data-testid={`sidebar-section-chevron-${section.id}`}
-              style={{
-                display: 'inline-block',
-                transition: 'transform var(--motion-fast) var(--ease-out)',
-                transform: sectionOpen ? 'rotate(90deg)' : 'rotate(0deg)',
-                fontSize: 10,
-              }}
+              style={sidebarSectionChevronStyle(sectionOpen)}
             >
               ▸
             </span>

package/bizar-dash/src/web/v8/shell/Topbar.tsx

@@ -1,4 +1,4 @@
-import { useState, type ReactNode } from 'react';
+import { useState, type CSSProperties, type ReactNode } from 'react';
 import { ChevronDown, Search } from 'lucide-react';
 import { Box } from '../ui/primitives/Box.js';
 import { Inline } from '../ui/primitives/Inline.js';
@@ -11,6 +11,60 @@ import { useConnectionState } from '../data/useWebSocket.js';
 import { NotificationsPopover } from '../ui/feedback/NotificationsPopover.js';
 import { fetchJson, FetchError } from '../data/fetcher.js';
 
+const popoverLabelStyle: CSSProperties = {
+  fontSize: 'var(--fs-12)',
+  color: 'var(--fg-muted)',
+  marginBottom: 8,
+};
+
+const popoverEmptyStyle: CSSProperties = {
+  fontSize: 'var(--fs-12)',
+  color: 'var(--fg-muted)',
+};
+
+const popoverListStyle: CSSProperties = {
+  listStyle: 'none',
+  margin: 0,
+  padding: 0,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2,
+};
+
+const popoverItemStyle = (isActive: boolean, busy: boolean): CSSProperties => ({
+  display: 'flex',
+  width: '100%',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
+  padding: '6px 8px',
+  background: isActive ? 'var(--surface-2)' : 'transparent',
+  border: 0,
+  borderRadius: 'var(--radius-sm)',
+  color: 'var(--fg)',
+  cursor: busy ? 'wait' : 'pointer',
+  fontSize: 'var(--fs-13)',
+  textAlign: 'left',
+});
+
+const popoverItemLabelStyle: CSSProperties = {
+  minWidth: 0,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+};
+
+const popoverItemMarkerStyle = (active: boolean): CSSProperties => ({
+  fontSize: 'var(--fs-11)',
+  color: active ? 'var(--accent)' : 'var(--fg-muted)',
+});
+
+const popoverErrorStyle: CSSProperties = {
+  marginTop: 8,
+  fontSize: 'var(--fs-12)',
+  color: 'var(--danger)',
+};
+
 /**
  * Topbar — the 56px horizontal bar at the top of the v8 shell.
  *
@@ -141,13 +195,13 @@ function BrandPlaceholder(): JSX.Element {
           </button>
         </PopoverTrigger>
         <PopoverContent align="start" sideOffset={6}>
-          <Box style={{ fontSize: 'var(--fs-12)', color: 'var(--fg-muted)', marginBottom: 8 }}>
+          <Box style={popoverLabelStyle}>
             Switch project
           </Box>
           {list.length === 0 ? (
-            <Box style={{ fontSize: 'var(--fs-12)', color: 'var(--fg-muted)' }}>No projects registered</Box>
+            <Box style={popoverEmptyStyle}>No projects registered</Box>
           ) : (
-            <ul role="menu" style={{ listStyle: 'none', margin: 0, padding: 0, display: 'flex', flexDirection: 'column', gap: 2 }}>
+            <ul role="menu" style={popoverListStyle}>
               {list.map((p) => {
                 const isActive = p.id === activeId;
                 return (
@@ -159,27 +213,13 @@ function BrandPlaceholder(): JSX.Element {
                       onClick={() => { void activate(p.id); }}
                       data-testid={`topbar-project-option-${p.id}`}
                       aria-current={isActive ? 'true' : undefined}
-                      style={{
-                        display: 'flex',
-                        width: '100%',
-                        alignItems: 'center',
-                        justifyContent: 'space-between',
-                        gap: 8,
-                        padding: '6px 8px',
-                        background: isActive ? 'var(--surface-2)' : 'transparent',
-                        border: 0,
-                        borderRadius: 'var(--radius-sm)',
-                        color: 'var(--fg)',
-                        cursor: busy !== null ? 'wait' : 'pointer',
-                        fontSize: 'var(--fs-13)',
-                        textAlign: 'left',
-                      }}
+                      style={popoverItemStyle(isActive, busy !== null)}
                     >
-                      <span style={{ minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                      <span style={popoverItemLabelStyle}>
                         {p.name || p.id}
                       </span>
-                      {isActive && <span style={{ fontSize: 'var(--fs-11)', color: 'var(--accent)' }}>●</span>}
-                      {!isActive && busy === p.id && <span style={{ fontSize: 'var(--fs-11)', color: 'var(--fg-muted)' }}>…</span>}
+                      {isActive && <span style={popoverItemMarkerStyle(true)}>●</span>}
+                      {!isActive && busy === p.id && <span style={popoverItemMarkerStyle(false)}>…</span>}
                     </button>
                   </li>
                 );
@@ -187,7 +227,7 @@ function BrandPlaceholder(): JSX.Element {
             </ul>
           )}
           {error !== null && (
-            <Box role="alert" data-testid="topbar-project-error" style={{ marginTop: 8, fontSize: 'var(--fs-12)', color: 'var(--danger)' }}>
+            <Box role="alert" data-testid="topbar-project-error" style={popoverErrorStyle}>
               {error}
             </Box>
           )}

package/bizar-dash/src/web/v8/ui/feedback/NotificationsPopover.tsx

@@ -10,6 +10,7 @@
  */
 
 import { useEffect, useRef, useState } from 'react';
+import { useFocusTrap } from './useFocusTrap.js';
 import { Bell, Check } from 'lucide-react';
 import { Box } from '../primitives/Box.js';
 import { Inline } from '../primitives/Inline.js';
@@ -109,6 +110,8 @@ export function NotificationsPopover(): JSX.Element {
   };
 
   const unread = items.length;
+
+  useFocusTrap(ref, open);
   return (
     <Box style={{ position: 'relative' }} ref={ref}>
       <button

package/bizar-dash/src/web/v8/ui/feedback/useFocusTrap.ts

@@ -0,0 +1,58 @@
+/**
+ * useFocusTrap — traps Tab/Shift+Tab focus inside a container.
+ *
+ * Used by popover/dialog primitives that don't use @radix-ui/react-dialog.
+ * Radix Dialog components get this for free; this hook covers the few
+ * custom role="dialog" surfaces that remain.
+ *
+ * ponytail: edge-case (disabled elements, inert) — upgrade to focus-trap npm pkg when needed.
+ */
+
+import { useEffect, useRef } from 'react';
+
+const FOCUSABLE = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  'details > summary',
+].join(',');
+
+export function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, active: boolean): void {
+  const previousFocus = useRef<Element | null>(null);
+
+  useEffect(() => {
+    if (!active || !containerRef.current) return;
+
+    // Restore focus on unmount.
+    previousFocus.current = document.activeElement;
+    const container = containerRef.current;
+
+    // Focus first focusable child on mount.
+    const first = container.querySelector<HTMLElement>(FOCUSABLE);
+    first?.focus();
+
+    const onKeyDown = (e: KeyboardEvent): void => {
+      if (e.key !== 'Tab') return;
+      const focusable = Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE));
+      if (focusable.length === 0) { e.preventDefault(); return; }
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+
+      if (e.shiftKey) {
+        if (document.activeElement === first) { e.preventDefault(); last.focus(); }
+      } else {
+        if (document.activeElement === last) { e.preventDefault(); first.focus(); }
+      }
+    };
+
+    container.addEventListener('keydown', onKeyDown);
+    return () => {
+      container.removeEventListener('keydown', onKeyDown);
+      if (previousFocus.current instanceof HTMLElement) previousFocus.current.focus();
+    };
+  }, [active, containerRef]);
+}

package/bizar-dash/src/web/v8/ui/navigation/CommandPalette.tsx

@@ -49,6 +49,7 @@ export function CommandPalette(props: CommandPaletteProps) {
       className={cx('v8-command', className)}
       label="Command palette"
       shouldFilter
+      loop
     >
       <div
         style={{