sensorium-mcp 3.1.2 → 3.1.3-board.10

package/Install-Sensorium.ps1

@@ -9,7 +9,8 @@
 
     The release channel follows the SAME switch as the MCP server: the tag in
     MCPStartCommand ("npx -y sensorium-mcp@<tag>"). @latest -> supervisor-latest
-    (stable, built from main); @refactor -> supervisor-refactor (built from the
+    (stable, built from main); @board -> supervisor-board (built from
+    feature/agent-task-board); @refactor -> supervisor-refactor (built from the
     refactor branch). One edit to install.config.json flips both node + supervisor.
 
     All configuration is read from ~/.remote-copilot-mcp/install.config.json.
@@ -41,11 +42,25 @@ $ConfigFile = Join-Path $DataDir "install.config.json"
 $StartupDir = [Environment]::GetFolderPath("Startup")
 $StartupLauncher = Join-Path $StartupDir "SensoriumSupervisor.cmd"
 
+# Isolated MCP runtime: a PRIVATE npm cache + a repo-independent cwd for the MCP,
+# both living under $DataDir (never a dev checkout). This severs the shared-cache /
+# shared-cwd coupling that lets a worker's `npm ci`/build in a dev repo interfere
+# with (and kill) the live MCP — WITHOUT pinning the version, so `npx ...@latest`
+# still auto-updates the MCP on each restart. npx also stages its packages in
+# <cache>/_npx, so a private npm cache isolates npx resolution too.
+$McpRuntimeRoot = Join-Path $DataDir "mcp-runtime"
+$McpRuntimeCache = Join-Path $McpRuntimeRoot "npm-cache"
+
 # ── Config File ──────────────────────────────────────────────────────────────
 $Defaults = @{
     SecureVaultProfile = "SENSORIUM"
     UpdateMode         = "production"
     MCPStartCommand    = "npx -y sensorium-mcp@latest"
+    # Opt-in runtime isolation. When "true", the MCP keeps its `npx ...@latest`
+    # start command (so auto-update still works) but is given its OWN npm cache
+    # ($McpRuntimeCache) and a repo-independent cwd ($McpRuntimeRoot), decoupled
+    # from any dev checkout's shared npm cache / cwd. "false" = legacy behaviour.
+    IsolateMcpRuntime  = "false"
 }
 
 function Load-Config {
@@ -78,14 +93,16 @@ $Config = Load-Config
 $SecureVaultProfile = $Config["SecureVaultProfile"]
 $UpdateMode = $Config["UpdateMode"]
 $EffectiveMCPStartCommand = $Config["MCPStartCommand"]
+$IsolateMcpRuntime = $Config["IsolateMcpRuntime"] -eq "true"
 
 # Resolve the supervisor release channel from the same tag the node server
-# follows: the "@<tag>" in MCPStartCommand. Only @refactor uses the branch
-# build; everything else (incl. @latest, a bare version pin, or no tag) stays
+# follows: the "@<tag>" in MCPStartCommand. Only @board (supervisor-board, built
+# from feature/agent-task-board) and @refactor (supervisor-refactor) use branch
+# builds; everything else (incl. @latest, a bare version pin, or no tag) stays
 # on the stable supervisor-latest release. This keeps the stable rollback path
 # intact — pointing the config back at @latest restores the main supervisor.
 $mcpTag = if ($EffectiveMCPStartCommand -match 'sensorium-mcp@([A-Za-z0-9._-]+)') { $Matches[1] } else { "latest" }
-$ReleaseTag = if ($mcpTag -eq "refactor") { "supervisor-refactor" } else { "supervisor-latest" }
+$ReleaseTag = if ($mcpTag -eq "board") { "supervisor-board" } elseif ($mcpTag -eq "refactor") { "supervisor-refactor" } else { "supervisor-latest" }
 Write-Host "Supervisor channel: $ReleaseTag (from MCP tag '$mcpTag')" -ForegroundColor Cyan
 
 # Validate config values
@@ -102,8 +119,27 @@ Save-Config $Config
 function Stop-SupervisorProcess {
     $procs = Get-Process -Name "sensorium-supervisor" -ErrorAction SilentlyContinue
     if ($procs) {
+        # Keep the original PID set. A name-only lookup after stopping can confuse a
+        # newly launched process with the instance we were asked to stop.
+        $targetPids = @($procs | Select-Object -ExpandProperty Id)
         Write-Host "Stopping background sensorium-supervisor process(es)..."
-        $procs | Stop-Process -Force
+        $procs | Stop-Process -Force -ErrorAction Stop
+
+        # Stop-Process returns once a signal has been sent, not once all image/file
+        # handles are released. Do not attempt an in-place replacement until every
+        # PID we targeted is gone; a continuing process makes the update unsafe.
+        $deadline = (Get-Date).AddSeconds(10)
+        do {
+            $remainingPids = @($targetPids | Where-Object {
+                Get-Process -Id $_ -ErrorAction SilentlyContinue
+            })
+            if ($remainingPids.Count -eq 0) { break }
+            Start-Sleep -Milliseconds 250
+        } while ((Get-Date) -lt $deadline)
+
+        if ($remainingPids.Count -gt 0) {
+            throw "Refusing to update: sensorium-supervisor PID(s) $($remainingPids -join ', ') did not stop within 10 seconds."
+        }
         Write-Host "Process(es) stopped." -ForegroundColor Yellow
     }
 }
@@ -212,7 +248,45 @@ function Save-BinaryMetadata {
         InstalledAt    = (Get-Date).ToString("o")
     }
 
-    $metadata | ConvertTo-Json | Set-Content -LiteralPath $MetadataPath -Encoding ASCII
+    # Do not write metadata in place: a failure halfway through a write would make a
+    # good binary look stale on the next run. The temp name is unique so concurrent
+    # or previously interrupted installs cannot collide with it.
+    $metadataTempPath = "$MetadataPath.tmp.$PID.$([guid]::NewGuid().ToString('N'))"
+    try {
+        $metadata | ConvertTo-Json | Set-Content -LiteralPath $metadataTempPath -Encoding ASCII
+        Move-FileWithRetry -Source $metadataTempPath -Destination $MetadataPath -Operation "update release metadata"
+    }
+    finally {
+        if (Test-Path -LiteralPath $metadataTempPath) {
+            Remove-Item -LiteralPath $metadataTempPath -Force -ErrorAction SilentlyContinue
+        }
+    }
+}
+
+function Move-FileWithRetry {
+    param(
+        [string]$Source,
+        [string]$Destination,
+        [string]$Operation = "replace file",
+        [int]$MaxAttempts = 20,
+        [int]$RetryDelayMs = 1500
+    )
+
+    for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
+        try {
+            Move-Item -LiteralPath $Source -Destination $Destination -Force -ErrorAction Stop
+            return
+        }
+        catch {
+            if ($attempt -eq $MaxAttempts) {
+                throw "Failed to $Operation at $Destination after $MaxAttempts attempts (~$([math]::Round($MaxAttempts * $RetryDelayMs / 1000))s). Original error: $_"
+            }
+            if ($attempt % 4 -eq 0) {
+                Write-Host "  ... waiting to $Operation (attempt $attempt/$MaxAttempts)..." -ForegroundColor Yellow
+            }
+            Start-Sleep -Milliseconds $RetryDelayMs
+        }
+    }
 }
 
 function Get-BinaryAsset {
@@ -229,7 +303,13 @@ function Get-BinaryAsset {
     $headers = Get-GithubAuthHeaders -Accept "application/octet-stream"
     Write-Host "Downloading $($AssetInfo.AssetName) ..."
 
-    $tmpFile = "$Destination.tmp"
+    $operationId = "$PID.$([guid]::NewGuid().ToString('N'))"
+    $tmpFile = "$Destination.tmp.$operationId"
+    $backupPath = "$Destination.bak.$operationId"
+    $metadataBackupPath = "$MetadataPath.bak.$operationId"
+    $hadBinary = Test-Path -LiteralPath $Destination
+    $hadMetadata = Test-Path -LiteralPath $MetadataPath
+    $swapped = $false
     try {
         Invoke-WebRequest -Uri $downloadUrl -Headers $headers -OutFile $tmpFile -UseBasicParsing -ErrorAction Stop
     }
@@ -241,15 +321,74 @@ function Get-BinaryAsset {
         throw "Download failed: $_"
     }
 
-    # Atomic replace
-    if (Test-Path $Destination) {
-        $backupPath = "$Destination.bak"
-        Copy-Item $Destination $backupPath -Force
+    try {
+        # Preserve both halves of the installed state. If anything after the
+        # executable swap fails (notably metadata persistence), restore the pair.
+        if ($hadBinary) { Copy-Item -LiteralPath $Destination -Destination $backupPath -Force -ErrorAction Stop }
+        if ($hadMetadata) { Copy-Item -LiteralPath $MetadataPath -Destination $metadataBackupPath -Force -ErrorAction Stop }
+
+        # The old exe can still be locked for a while after Stop-Process — AV/EDR
+        # may retain its image-section handle during a post-exit scan.
+        Move-FileWithRetry -Source $tmpFile -Destination $Destination -Operation "replace supervisor binary"
+        $swapped = $true
+
+        try {
+            Unblock-File -Path $Destination -ErrorAction Stop
+        }
+        catch {
+            Write-Host "[WARN] Could not unblock ${Destination}: $($_.Exception.Message)" -ForegroundColor Yellow
+        }
+
+        Save-BinaryMetadata -MetadataPath $MetadataPath -AssetInfo $AssetInfo
+        Write-Host "Binary placed at: $Destination" -ForegroundColor Green
+    }
+    catch {
+        $updateError = $_
+        if ($swapped) {
+            Write-Host "[WARN] Update failed after binary replacement; restoring the previous binary and metadata..." -ForegroundColor Yellow
+            $restoreErrors = @()
+            try {
+                if ($hadBinary) {
+                    $restoreFile = "$Destination.restore.$operationId"
+                    Copy-Item -LiteralPath $backupPath -Destination $restoreFile -Force -ErrorAction Stop
+                    Move-FileWithRetry -Source $restoreFile -Destination $Destination -Operation "restore previous supervisor binary"
+                }
+                elseif (Test-Path -LiteralPath $Destination) {
+                    Remove-Item -LiteralPath $Destination -Force -ErrorAction Stop
+                }
+            }
+            catch { $restoreErrors += "binary: $($_.Exception.Message)" }
+
+            try {
+                if ($hadMetadata) {
+                    # Stage the backup under a unique name, then use the same
+                    # retrying replacement path as the binary. Copy-Item directly
+                    # to $MetadataPath could leave metadata restoration vulnerable
+                    # to a locked destination and bypass the retry policy.
+                    $metadataRestoreFile = "$MetadataPath.restore.$operationId"
+                    Copy-Item -LiteralPath $metadataBackupPath -Destination $metadataRestoreFile -Force -ErrorAction Stop
+                    Move-FileWithRetry -Source $metadataRestoreFile -Destination $MetadataPath -Operation "restore previous release metadata"
+                }
+                elseif (Test-Path -LiteralPath $MetadataPath) {
+                    Remove-Item -LiteralPath $MetadataPath -Force -ErrorAction Stop
+                }
+            }
+            catch { $restoreErrors += "metadata: $($_.Exception.Message)" }
+
+            if ($restoreErrors.Count -gt 0) {
+                throw "Update failed and recovery was incomplete ($($restoreErrors -join '; ')). Original error: $($updateError.Exception.Message)"
+            }
+            throw "Update failed after replacement; the previous binary and metadata were restored. Original error: $($updateError.Exception.Message)"
+        }
+        throw
+    }
+    finally {
+        foreach ($path in @($tmpFile, $backupPath, $metadataBackupPath, "$Destination.restore.$operationId", "$MetadataPath.restore.$operationId")) {
+            if (Test-Path -LiteralPath $path) {
+                Remove-Item -LiteralPath $path -Force -ErrorAction SilentlyContinue
+            }
+        }
     }
-    Move-Item $tmpFile $Destination -Force
-    Unblock-File -Path $Destination -ErrorAction SilentlyContinue
-    Save-BinaryMetadata -MetadataPath $MetadataPath -AssetInfo $AssetInfo
-    Write-Host "Binary placed at: $Destination" -ForegroundColor Green
 }
 
 function Install-StartupLauncher {
@@ -306,10 +445,44 @@ function Test-SecureVaultAvailable {
     catch { return $false }
 }
 
+function Initialize-IsolatedMcpRuntime {
+    <#
+      Prepares the PRIVATE MCP runtime area: a dedicated npm cache and a
+      repo-independent cwd, both under $McpRuntimeRoot. It does NOT install or pin
+      any package — the MCP keeps its `npx ...@latest` start command so auto-update
+      still works; isolation comes purely from the private cache + cwd handed to the
+      supervisor (and thus to npx) via Start-Supervisor. Idempotent; only creates dirs.
+    #>
+    Write-Host "Isolated MCP runtime enabled — preparing private cache + cwd..." -ForegroundColor Cyan
+    Write-Host "  Runtime cwd : $McpRuntimeRoot"
+    Write-Host "  npm cache   : $McpRuntimeCache (npx stages under $McpRuntimeCache\_npx)"
+
+    try {
+        New-Item -ItemType Directory -Path $McpRuntimeRoot -Force | Out-Null
+        New-Item -ItemType Directory -Path $McpRuntimeCache -Force | Out-Null
+    }
+    catch {
+        Write-Host "[WARN] Could not create isolated runtime dirs: $($_.Exception.Message) — keeping legacy behaviour." -ForegroundColor Yellow
+        return $false
+    }
+    return $true
+}
+
 function Start-Supervisor {
     $env:SUPERVISOR_UPDATE_MODE = $UpdateMode
     $env:MCP_START_COMMAND = $EffectiveMCPStartCommand
 
+    # In isolated mode, hand the supervisor a private npm cache and a repo-independent
+    # cwd. The supervisor inherits its whole environment and passes it to the MCP, so
+    # NPM_CONFIG_CACHE reaches the `npx ...@latest` child automatically (isolating both
+    # the npm cache and npx's <cache>\_npx staging); MCP_WORKING_DIR is consumed by the
+    # supervisor to set the MCP's spawn cwd. The `@latest` command is unchanged, so
+    # auto-update keeps working — only WHERE npx resolves/caches changes.
+    if ($IsolateMcpRuntime) {
+        $env:NPM_CONFIG_CACHE = $McpRuntimeCache
+        $env:MCP_WORKING_DIR = $McpRuntimeRoot
+    }
+
     $useSecureVault = (-not [string]::IsNullOrWhiteSpace($SecureVaultProfile)) -and (Test-SecureVaultAvailable)
 
     if ($useSecureVault) {
@@ -390,7 +563,7 @@ function Sync-ReleaseBinary {
     Write-Host "Fetching release via SecureVault (profile: $SecureVaultProfile)..."
     securevault run pwsh -NoProfile -File "`"$PSCommandPath`"" -SyncReleaseOnly --profile $SecureVaultProfile
     if ($LASTEXITCODE -ne 0) {
-        throw "SecureVault-driven release sync failed (exit $LASTEXITCODE). Ensure profile '$SecureVaultProfile' maps a GitHub PAT to env var SENSORIUM_GH_TOKEN."
+        throw "SecureVault-driven release sync failed (exit $LASTEXITCODE). See the error above for the actual cause (e.g. a locked binary, network failure, or a missing GitHub PAT for profile '$SecureVaultProfile' -> `$env:SENSORIUM_GH_TOKEN)."
     }
 }
 
@@ -402,35 +575,76 @@ if ($SyncReleaseOnly) {
 }
 
 # ── Main ─────────────────────────────────────────────────────────────────────
-$alreadyExists = Test-Path $Binary
+# Serialize only full installer invocations for this Windows user. The
+# SecureVault child above deliberately returns before this point, so it can do
+# the authenticated release sync without waiting on (and deadlocking with) its
+# parent installer process.
+$currentUserSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$installMutexName = "Local\SensoriumSupervisor.Install.$($currentUserSid -replace '[^A-Za-z0-9_.-]', '_')"
+$installMutex = [System.Threading.Mutex]::new($false, $installMutexName)
+$mutexHeld = $false
+
+try {
+    try {
+        $mutexHeld = $installMutex.WaitOne([TimeSpan]::FromMinutes(5))
+    }
+    catch [System.Threading.AbandonedMutexException] {
+        # The prior installer died without releasing the mutex; Windows has given
+        # us ownership, so continue while making that state visible to the user.
+        $mutexHeld = $true
+        Write-Host "[WARN] Recovered an abandoned installer mutex; continuing." -ForegroundColor Yellow
+    }
 
-Write-Host ""
-if ($alreadyExists) {
-    Write-Host "=== Sensorium Supervisor UPDATE ===" -ForegroundColor Cyan
-}
-else {
-    Write-Host "=== Sensorium Supervisor INSTALL ===" -ForegroundColor Cyan
-}
-Write-Host "SecureVault profile: $(if ([string]::IsNullOrWhiteSpace($SecureVaultProfile)) { '<disabled>' } else { $SecureVaultProfile })"
-Write-Host "Watcher mode: $UpdateMode"
-Write-Host "MCP start command: $EffectiveMCPStartCommand"
-Write-Host "Binary     : $Binary"
-Write-Host ""
-
-# Step 1 — stop existing instance
-if ($alreadyExists) {
-    Stop-SupervisorProcess
-}
+    if (-not $mutexHeld) {
+        throw "Another Sensorium install/update is still running for this user. Timed out waiting for it to finish."
+    }
 
-# Step 2 — ensure bin dir exists
-New-Item -ItemType Directory -Path $BinDir -Force | Out-Null
+    $alreadyExists = Test-Path $Binary
 
-# Step 3 — fetch release metadata and download only when needed
-Sync-ReleaseBinary
+    Write-Host ""
+    if ($alreadyExists) {
+        Write-Host "=== Sensorium Supervisor UPDATE ===" -ForegroundColor Cyan
+    }
+    else {
+        Write-Host "=== Sensorium Supervisor INSTALL ===" -ForegroundColor Cyan
+    }
+    Write-Host "SecureVault profile: $(if ([string]::IsNullOrWhiteSpace($SecureVaultProfile)) { '<disabled>' } else { $SecureVaultProfile })"
+    Write-Host "Watcher mode: $UpdateMode"
+    Write-Host "MCP start command: $EffectiveMCPStartCommand"
+    Write-Host "MCP runtime isolation: $(if ($IsolateMcpRuntime) { 'ENABLED' } else { 'disabled (legacy npx)' })"
+    Write-Host "Binary     : $Binary"
+    Write-Host ""
+
+    # Step 1 — stop existing instance
+    if ($alreadyExists) {
+        Stop-SupervisorProcess
+    }
+
+    # Step 2 — ensure bin dir exists
+    New-Item -ItemType Directory -Path $BinDir -Force | Out-Null
+
+    # Step 3 — fetch release metadata and download only when needed
+    Sync-ReleaseBinary
+
+    # Step 3b — prepare the isolated MCP runtime area (opt-in): a private npm cache +
+    # repo-independent cwd. The `npx ...@latest` command is unchanged (auto-update
+    # preserved). On any failure this disables the isolation env in Start-Supervisor,
+    # so the install degrades safely to legacy behaviour.
+    if ($IsolateMcpRuntime) {
+        if (-not (Initialize-IsolatedMcpRuntime)) {
+            $IsolateMcpRuntime = $false
+            Write-Host "[WARN] Isolation disabled for this run — using the shared npm cache / inherited cwd." -ForegroundColor Yellow
+        }
+    }
 
-# Step 4 — install launcher and start
-Install-StartupLauncher
-Start-Supervisor
+    # Step 4 — install launcher and start
+    Install-StartupLauncher
+    Start-Supervisor
 
-# Step 5 — verify
-Show-Status
+    # Step 5 — verify
+    Show-Status
+}
+finally {
+    if ($mutexHeld) { $installMutex.ReleaseMutex() }
+    if ($installMutex) { $installMutex.Dispose() }
+}

package/README.md

@@ -5,6 +5,8 @@
 
 MCP server with multi-layer memory, voice analysis, multi-thread orchestration, and Telegram bridge for AI assistants.
 
+Internal TypeScript conventions: [coding guidelines](docs/coding-guidelines.md).
+
 ## Why?
 
 AI assistants forget everything between sessions. Every restart is a blank slate — no memory of your preferences, past decisions, or ongoing projects. Voice messages arrive as opaque audio blobs. And there's no way to talk to your agent when it's running headless in CI or on a remote machine.

package/dist/board/api/api.js

@@ -0,0 +1,84 @@
+/**
+ * Data-adapter switch.  ❌ FROZEN SEAM — the ONLY seam is data.
+ *
+ * MODE decides the implementation ONCE, lazily:
+ *   - preview    → mock/api.mock.js is DYNAMICALLY imported (so not a single mock
+ *                  byte is loaded in production).
+ *   - production → api/client.js (real fetch).
+ *
+ * Every method returns a Promise and forwards to the resolved adapter, so callers
+ * (state/ composables) never know or care which one is live.
+ *
+ * @typedef {import('./contract.js').BoardApi} BoardApi
+ */
+
+import { MODE } from "../config.js";
+
+let implPromise = null;
+
+/** @returns {Promise<BoardApi>} */
+function load() {
+  if (!implPromise) {
+    implPromise = (
+      MODE === "preview"
+        ? import("../mock/api.mock.js").then((m) => m.mockApi)
+        : import("./client.js").then((m) => m.client)
+    ).then(assertAdapterComplete);
+  }
+  return implPromise;
+}
+
+const METHODS = [
+  "listCards",
+  "getCard",
+  "createCard",
+  "previewBriefing",
+  "updateCard",
+  "deleteCard",
+  "stopCard",
+  "addComment",
+  "postDecision",
+  "listLaneGroups",
+  "getProfiles",
+  "saveProfile",
+  "threadRunning",
+  "threadLogs",
+  // Card-builder "How" schema + presets.
+  "getPolicySchema",
+  "getPresets",
+  "createLaneGroup",
+  "updateLaneGroup",
+  "deleteLaneGroup",
+  // Working-directory picker: one filesystem level per call (lazy browse).
+  "listDir",
+];
+
+/**
+ * Fail LOUD if the resolved adapter is missing any METHODS entry. A method listed
+ * in the contract/registry but never implemented in the active adapter used to
+ * surface as a late "undefined is not a function" at call time — exactly how
+ * lane-group CRUD and previewBriefing broke in production
+ * while preview worked. Asserting completeness once, at load, turns that silent
+ * drift into an immediate, named error.
+ *
+ * @param {Partial<BoardApi>} impl
+ * @returns {BoardApi}
+ */
+function assertAdapterComplete(impl) {
+  const missing = METHODS.filter((name) => typeof impl?.[name] !== "function");
+  if (missing.length) {
+    throw new Error(
+      `Board API adapter is missing method(s): ${missing.join(", ")}. ` +
+        `Every METHODS entry must be implemented by the active adapter (api/client.js or mock/api.mock.js).`,
+    );
+  }
+  return /** @type {BoardApi} */ (impl);
+}
+
+/** @type {BoardApi} */
+const api = /** @type {any} */ ({});
+for (const name of METHODS) {
+  api[name] = (...args) => load().then((impl) => impl[name](...args));
+}
+
+export { api, assertAdapterComplete };

package/dist/board/api/api.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { assertAdapterComplete } from "./api.js";
+import { client } from "./client.js";
+import type { BoardApi } from "./contract.js";
+
+test("the adapter completeness guard passes for the production client", () => {
+  // Arrange
+  const impl = client;
+
+  // Act & Assert — every contract/registry method is now implemented in client.js.
+  assert.doesNotThrow(() => assertAdapterComplete(impl));
+});
+
+test("the adapter completeness guard throws naming a method missing from the adapter", () => {
+  // Arrange — a client with one contract method dropped (the exact drift that
+  // shipped lane CRUD as a late `undefined is not a function`).
+  const incomplete: Partial<BoardApi> = { ...client };
+  delete incomplete.createLaneGroup;
+
+  // Act & Assert
+  assert.throws(() => assertAdapterComplete(incomplete), /createLaneGroup/);
+});

package/dist/board/api/client.js

@@ -0,0 +1,113 @@
+/**
+ * Production data adapter.  ❌ FROZEN SEAM.
+ *
+ * Real `fetch` to the board API. Root-relative `/api/...` paths (never a host or
+ * port) so the app works unchanged behind the Dev Tunnel. This is the ONLY module
+ * that talks to the network.
+ *
+ * @typedef {import('./contract.js').BoardApi}   BoardApi
+ * @typedef {import('./contract.js').BoardCard}  BoardCard
+ */
+
+import { API_BASE } from "../config.js";
+
+/**
+ * @param {string} method
+ * @param {string} path
+ * @param {unknown} [body]
+ */
+async function req(method, path, body) {
+  const headers = {};
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+
+  const res = await fetch(`${API_BASE}${path}`, {
+    method,
+    headers,
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+
+  const text = await res.text();
+  let data = null;
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = { error: text };
+    }
+  }
+  if (!res.ok) {
+    const msg = (data && data.error) || `${res.status} ${res.statusText}`;
+    const err = new Error(msg);
+    err.status = res.status;
+    throw err;
+  }
+  return data;
+}
+
+/** @type {BoardApi} */
+export const client = {
+  listCards({ includeArchived = false } = {}) {
+    const p = new URLSearchParams();
+    if (includeArchived) p.set("includeArchived", "1");
+    const qs = p.toString();
+    return req("GET", `/api/board/cards${qs ? `?${qs}` : ""}`);
+  },
+  getCard(id) {
+    return req("GET", `/api/board/cards/${id}`);
+  },
+  createCard(card) {
+    return req("POST", "/api/board/cards", card).then((d) => d.card);
+  },
+  previewBriefing(draft) {
+    return req("POST", "/api/board/cards/preview", draft).then((d) => d.briefing);
+  },
+  updateCard(id, patch) {
+    return req("PATCH", `/api/board/cards/${id}`, patch).then((d) => d.card);
+  },
+  deleteCard(id) {
+    return req("DELETE", `/api/board/cards/${id}`).then(() => undefined);
+  },
+  stopCard(id) {
+    return req("POST", `/api/board/cards/${id}/stop`, {}).then((d) => d.card);
+  },
+  addComment(id, content) {
+    return req("POST", `/api/board/cards/${id}/comments`, { content }).then((d) => d.comment);
+  },
+  postDecision(id, answer) {
+    return req("POST", `/api/board/cards/${id}/decision`, { answer }).then((d) => d.card);
+  },
+  listLaneGroups() {
+    return req("GET", "/api/board/lane-groups").then((d) => d.laneGroups);
+  },
+  createLaneGroup(name) {
+    return req("POST", "/api/board/lane-groups", { name }).then((d) => d.laneGroup);
+  },
+  updateLaneGroup(id, patch) {
+    return req("PATCH", `/api/board/lane-groups/${id}`, patch).then((d) => d.laneGroup);
+  },
+  deleteLaneGroup(id) {
+    return req("DELETE", `/api/board/lane-groups/${id}`).then(() => undefined);
+  },
+  getProfiles() {
+    return req("GET", "/api/board/profiles").then((d) => d.profiles);
+  },
+  saveProfile(input) {
+    return req("POST", "/api/board/profiles", input).then((d) => d.profile);
+  },
+  threadRunning(threadId) {
+    return req("GET", `/api/threads/${threadId}/running`).then((d) => !!d.running);
+  },
+  threadLogs(threadId, { view = "assistant", offset = 0, limit = 4000 } = {}) {
+    const params = new URLSearchParams({ view, offset: String(offset), limit: String(limit) });
+    return req("GET", `/api/threads/${threadId}/logs?${params}`);
+  },
+  getPolicySchema() {
+    return req("GET", "/api/board/policy").then((d) => d.schema);
+  },
+  getPresets() {
+    return req("GET", "/api/board/policy").then((d) => d.presets);
+  },
+  listDir(path) {
+    return req("GET", `/api/board/dir-listing?path=${encodeURIComponent(path || "")}`);
+  },
+};

package/dist/board/components/BottomNav.js

@@ -0,0 +1,32 @@
+/**
+ * Bottom navigation — ✅ EDITABLE. Pure: `active` in, `navigate` out.
+ * Thumb-reach primary nav (board / new / settings).
+ */
+
+export default {
+  name: "BottomNav",
+  props: { active: { type: String, default: "board" } },
+  emits: ["navigate"],
+  setup(props, { emit }) {
+    const items = [
+      { name: "board", to: "/board", label: "Board", icon: "▦" },
+      { name: "settings", to: "/settings", label: "Settings", icon: "⚙" },
+    ];
+    return { items, emit };
+  },
+  template: `
+    <nav class="bottom-nav">
+      <button
+        v-for="it in items"
+        :key="it.name"
+        type="button"
+        class="bottom-nav__item"
+        :class="{ 'is-active': active === it.name }"
+        @click="emit('navigate', it.to)"
+      >
+        <span class="bottom-nav__icon" aria-hidden="true">{{ it.icon }}</span>
+        <span class="bottom-nav__label">{{ it.label }}</span>
+      </button>
+    </nav>
+  `,
+};