@polderlabs/bizar 5.5.0 → 5.5.2

package/bizar-dash/src/server/headroom.mjs

@@ -48,7 +48,9 @@ const DEFAULT_HEADROOM_HOST = '127.0.0.1';
 function runCmd(cmd, args, opts = {}) {
   return new Promise((resolve) => {
     const { timeout = 30000, cwd = HOME, env = process.env } = opts;
-    const child = spawn(cmd, args, { cwd, env, shell: true });
+    // shell:false avoids DEP0190 deprecation warning and is safe because
+    // args are already a proper array (not interpolated into a command string).
+    const child = spawn(cmd, args, { cwd, env, shell: false });
     let stdout = '';
     let stderr = '';
     const timer = setTimeout(() => {

package/bizar-dash/src/server/memory-lightrag.mjs

@@ -365,7 +365,9 @@ export function findLightragBinary() {
 }
 
 export async function isInstalled() {
-  return findLightragBinary() !== null;
+  const found = findLightragBinary() !== null;
+  if (found) _lightragNotInstalled = false;
+  return found;
 }
 
 function httpGet(url, timeoutMs) {
@@ -421,12 +423,31 @@ function httpPost(url, body, timeoutMs) {
   });
 }
 
+/**
+ * v5.x — Flag set when LightRAG is confirmed not installed or explicitly
+ * disabled. When true, isRunning() returns false immediately without
+ * making any network request, preventing ECONNREFUSED log spam from a
+ * binary that will never be present.
+ *
+ * Reset by findLightragBinary() succeeding (e.g. after user installs
+ * the binary without restarting the dashboard).
+ */
+let _lightragNotInstalled = false;
+
 export async function isRunning(config) {
+  // Fast path: skip network check if we already know LightRAG is absent.
+  // This suppresses the ECONNREFUSED log spam that otherwise occurs on every
+  // poll when the binary is not on PATH.
+  if (_lightragNotInstalled) return false;
   try {
     const res = await httpGet(`http://${config.host}:${config.port}/health`, 3000);
     return res.status === 200;
   } catch (err) {
-    console.warn('[lightrag] swallowed in isRunning.healthCheck:', err?.message || err);
+    // Rate-limit: only log once per 60s to avoid flooding the console
+    // when LightRAG health-check fails repeatedly.
+    if (_rateLimit('isRunning.healthCheck', 60_000)) {
+      console.warn('[lightrag] isRunning healthCheck failed:', err?.message || err);
+    }
     return false;
   }
 }
@@ -484,6 +505,7 @@ export async function startServer(config, { logger } = {}) {
   }
 
   if (!findLightragBinary()) {
+    _lightragNotInstalled = true;
     return {
       ok: false,
       error:
@@ -682,6 +704,7 @@ export async function lightragStartupHook(projectRoot, opts = {}) {
 
   // 3. Check lightrag.enabled flag.
   if (config.enabled === false) {
+    _lightragNotInstalled = true;
     log('startup hook: lightrag disabled in .bizar/memory.json, skipping');
     return { ok: true, started: false, reason: 'disabled' };
   }
@@ -689,6 +712,7 @@ export async function lightragStartupHook(projectRoot, opts = {}) {
   // 4. Check env-var override.
   const envAuto = process.env.BIZAR_LIGHTRAG_AUTOSTART;
   if (typeof envAuto === 'string' && /^(0|false|no|off)$/i.test(envAuto.trim())) {
+    _lightragNotInstalled = true;
     log(`startup hook: BIZAR_LIGHTRAG_AUTOSTART=${envAuto}, skipping`);
     return { ok: true, started: false, reason: 'env-disabled' };
   }

package/bizar-dash/src/server/memory-store.mjs

@@ -207,8 +207,14 @@ export function saveConfig(projectRoot, config) {
 /**
  * Resolve the effective vault root, namespaces, and related paths based on mode.
  *
+ * v6.x — `vaultRoot` is now always the GENERAL vault root (e.g. `~/.bizar_memory`).
+ * A new `projectVaultRoot` field carries the project-specific subdirectory for
+ * note storage in managed/linked mode (`~/.bizar_memory/projects/<projectId>`).
+ * This distinction lets the UI display the general root while the store still
+ * writes notes to the correct project subdirectory.
+ *
  * @param {string} projectRoot
- * @returns {{ mode: string, projectId: string, vaultRoot: string, repoPath: string | null, configDir: string, gitRemote: string | null, branch: string, lightragDir: string, namespaces: object }}
+ * @returns {{ mode: string, projectId: string, vaultRoot: string, projectVaultRoot: string, repoPath: string | null, configDir: string, gitRemote: string | null, branch: string, lightragDir: string, namespaces: object }}
  */
 export function resolveVault(projectRoot) {
   const { config } = loadConfig(projectRoot);
@@ -219,16 +225,19 @@ export function resolveVault(projectRoot) {
   const gitRemote = mr.remote || config.gitRemote || null;
 
   let vaultRoot;
+  let projectVaultRoot;
   let repoPath;
   if (mode === 'local-only') {
     vaultRoot = join(projectRoot, '.obsidian');
+    projectVaultRoot = vaultRoot;
     repoPath = null;
   } else {
     // managed or linked — path may be absolute, ~-relative, or a sibling of projectRoot
     const rawPath = mr.path || config.repoName || join(projectRoot, '.bizar', 'memory');
     const expanded = rawPath.startsWith('~') ? join(HOME, rawPath.slice(1)) : rawPath;
     repoPath = expanded;
-    vaultRoot = join(expanded, 'projects', projectId);
+    vaultRoot = expanded; // v6.x — general root, e.g. ~/.bizar_memory
+    projectVaultRoot = join(expanded, 'projects', projectId); // project-specific subdirectory
   }
 
   const configDir = join(projectRoot, '.bizar');
@@ -239,29 +248,28 @@ export function resolveVault(projectRoot) {
     user: `users/${process.env.USER || process.env.USERNAME || 'local'}`,
   };
 
-  return { mode, projectId, vaultRoot, repoPath, configDir, gitRemote, branch, lightragDir, namespaces };
+  return { mode, projectId, vaultRoot, projectVaultRoot, repoPath, configDir, gitRemote, branch, lightragDir, namespaces };
 }
 
 /**
  * Resolve the absolute path of a namespace root.
  *
- * For `project`, returns vaultRoot (the existing default). For `global` and
- * `user`, returns `<vaultRoot>/<namespaces.global|user>` in both modes —
- * `writeNote('global/bizar/foo.md', …)` already places files there in both
- * local-only and managed mode, so this matches the on-disk layout that
- * existing callers rely on.
+ * For `project`, returns projectVaultRoot (the directory where project notes
+ * are stored: `<vaultRoot>/projects/<projectId>` in managed mode, or
+ * `<projectRoot>/.obsidian` in local-only mode). For `global` and `user`,
+ * returns `<vaultRoot>/<namespaces.X>` — these namespaces live at the vault
+ * root level, not inside the project subdirectory.
  *
- * (Note: an earlier draft distinguished local-only vs managed, putting
- * global under `<repoPath>/global/bizar` in managed mode. That diverged from
- * where writeNote actually creates the file, which is always under
- * vaultRoot. This implementation matches the on-disk reality.)
+ * Routing: writeNote/readNote/deleteNote use this to determine where files
+ * live. Project relPaths go to projectVaultRoot; global/ and users/ relPaths
+ * go to vaultRoot-based paths.
  *
- * @param {{ mode: string, vaultRoot: string, namespaces: object }} vaultInfo
+ * @param {{ mode: string, vaultRoot: string, projectVaultRoot: string, namespaces: object }} vaultInfo
  * @param {'project'|'global'|'user'} namespace
  * @returns {string|null} absolute path, or null if the namespace is unknown
  */
 export function resolveNamespaceRoot(vaultInfo, namespace) {
-  if (namespace === 'project') return vaultInfo.vaultRoot;
+  if (namespace === 'project') return vaultInfo.projectVaultRoot;
   const ns = vaultInfo.namespaces?.[namespace];
   if (!ns) return null;
   return join(vaultInfo.vaultRoot, ns);
@@ -381,8 +389,8 @@ export function initVault(projectRoot) {
  * @returns {Array<{ relPath: string, mtime: number, size: number, frontmatter: Record<string, unknown>, body: string, schemaValid: boolean }>}
  */
 export function listNotes(projectRoot, opts = {}) {
-  const { vaultRoot } = resolveVault(projectRoot);
-  const root = opts.root || vaultRoot;
+  const { projectVaultRoot } = resolveVault(projectRoot);
+  const root = opts.root || projectVaultRoot;
   if (!existsSync(root)) return [];
 
   const namespace = opts.namespace || '';
@@ -425,8 +433,16 @@ export function listNotes(projectRoot, opts = {}) {
  * @returns {{ relPath: string, frontmatter: Record<string, unknown>, body: string, raw: string, mtime: number, size: number, schemaValid: boolean } | null}
  */
 export function readNote(projectRoot, relPath, opts = {}) {
-  const vaultInfo = resolveVault(projectRoot);
-  const root = opts.root || vaultInfo.vaultRoot;
+  const { vaultRoot, projectVaultRoot } = resolveVault(projectRoot);
+  // When opts.root is explicitly provided, use it. Otherwise route based on
+  // namespace so reads find notes where writeNote placed them.
+  let root;
+  if (opts.root) {
+    root = opts.root;
+  } else {
+    const isProjectNamespace = !relPath.startsWith('global/') && !relPath.startsWith('users/');
+    root = isProjectNamespace ? projectVaultRoot : vaultRoot;
+  }
   const filePath = resolveSafe(root, relPath);
   if (!filePath || !existsSync(filePath)) return null;
   try {
@@ -450,7 +466,7 @@ export function readNote(projectRoot, relPath, opts = {}) {
  * @throws {Error} if schema validation fails or HIGH-severity secret found
  */
 export function writeNote(projectRoot, relPath, { frontmatter, body }) {
-  const { vaultRoot } = resolveVault(projectRoot);
+  const { vaultRoot, projectVaultRoot } = resolveVault(projectRoot);
 
   // Validate frontmatter
   const { valid, errors, warnings } = validateNote(frontmatter, body);
@@ -473,13 +489,20 @@ export function writeNote(projectRoot, relPath, { frontmatter, body }) {
     throw err;
   }
 
+  // Determine the effective vault root based on namespace.
+  // Project notes (relPaths that don't start with global/ or users/) go under
+  // projectVaultRoot. Global and user notes go under vaultRoot.
+  // This matches the layout resolveNamespaceRoot returns for each namespace.
+  const isProjectNamespace = !relPath.startsWith('global/') && !relPath.startsWith('users/');
+  const noteVaultRoot = isProjectNamespace ? projectVaultRoot : vaultRoot;
+
   // Build file content
-  const filePath = resolveSafe(vaultRoot, relPath);
+  const filePath = resolveSafe(noteVaultRoot, relPath);
   if (!filePath) {
     throw new Error(`Invalid note path: ${relPath}`);
   }
 
-  // Lazily create the project namespace directory (F7 — not created at initVault)
+  // Lazily create the namespace directory (not created at initVault)
   const nsDir = dirname(filePath);
   if (!existsSync(nsDir)) {
     mkdirSync(nsDir, { recursive: true });
@@ -538,8 +561,16 @@ export function writeNote(projectRoot, relPath, { frontmatter, body }) {
  * @returns {boolean}
  */
 export function deleteNote(projectRoot, relPath, opts = {}) {
-  const vaultInfo = resolveVault(projectRoot);
-  const root = opts.root || vaultInfo.vaultRoot;
+  const { vaultRoot, projectVaultRoot } = resolveVault(projectRoot);
+  // When opts.root is explicitly provided, use it. Otherwise route based on
+  // namespace so deletes find notes where writeNote placed them.
+  let root;
+  if (opts.root) {
+    root = opts.root;
+  } else {
+    const isProjectNamespace = !relPath.startsWith('global/') && !relPath.startsWith('users/');
+    root = isProjectNamespace ? projectVaultRoot : vaultRoot;
+  }
   const filePath = resolveSafe(root, relPath);
   if (!filePath || !existsSync(filePath)) return false;
   unlinkSync(filePath);
@@ -560,8 +591,23 @@ export function searchVault(projectRoot, query, { limit = 25 } = {}) {
   const tokens = q.split(/\s+/).filter((t) => t.length >= 2);
   if (tokens.length === 0) return [];
 
+  const { vaultRoot, projectVaultRoot } = resolveVault(projectRoot);
+
+  // Collect notes from all namespaces by walking vaultRoot (which contains
+  // projects/<id>/, global/, and users/ as siblings). This finds project,
+  // global, and user notes in a single scan. relPaths returned are vaultRoot-
+  // relative (e.g. "projects/<id>/decisions/foo.md" or "global/bizar/foo.md").
+  // For project notes, strip the "projects/<id>/" prefix so the relPath matches
+  // what writeNote uses (projectVaultRoot-relative).
+  const projectPrefix = join('projects', projectVaultRoot.split('/').pop());
+  const allNotes = listNotes(projectRoot, { root: vaultRoot });
+
   const results = [];
-  for (const note of listNotes(projectRoot)) {
+  for (const note of allNotes) {
+    let relPath = note.relPath;
+    if (relPath.startsWith(projectPrefix)) {
+      relPath = relPath.slice(projectPrefix.length + 1);
+    }
     const lower = (note.body + ' ' + JSON.stringify(note.frontmatter)).toLowerCase();
     let score = 0;
     for (const t of tokens) {
@@ -572,7 +618,7 @@ export function searchVault(projectRoot, query, { limit = 25 } = {}) {
     const start = Math.max(0, idx - 60);
     const end = Math.min(lower.length, idx + 160);
     const snippet = (start > 0 ? '…' : '') + lower.slice(start, end).replace(/\s+/g, ' ').trim();
-    results.push({ relPath: note.relPath, snippet, score, mtime: note.mtime });
+    results.push({ relPath, snippet, score, mtime: note.mtime });
   }
 
   return results.sort((a, b) => b.score - a.score).slice(0, limit);
@@ -707,8 +753,8 @@ export function vaultStats(projectRoot) {
     };
   }
 
-  const { vaultRoot, mode, branch } = resolveVault(projectRoot);
-  if (!vaultRoot || !existsSync(vaultRoot)) {
+  const { vaultRoot, projectVaultRoot, mode, branch } = resolveVault(projectRoot);
+  if (!projectVaultRoot || !existsSync(projectVaultRoot)) {
     return {
       exists: true,
       vaultRoot: vaultRoot || '',
@@ -737,7 +783,7 @@ export function vaultStats(projectRoot) {
     try {
       const { isGitInstalled, status: gitStatus } = memoryGit;
       if (isGitInstalled()) {
-        const gs = gitStatus(vaultRoot);
+        const gs = gitStatus(projectVaultRoot);
         gitClean = gs.clean;
         gitBranch = gs.branch;
       }

package/bizar-dash/src/server/opencode-sdk.mjs

@@ -9,6 +9,8 @@
  * is kept as a backwards-compatible alias).
  *
  * v0.1.0 — initial implementation
+ * v5.5.1 — added `getOpencodeSdkOrThrow()` and `subscribeToSession()`
+ *           for the SDK-based bg spawner (see bg-spawner.mjs).
  */
 
 import { readServeInfo, pingOpencodeServe as _pingOpencodeServe } from "./serve-info.mjs";
@@ -18,7 +20,10 @@ let _sdkInfo = null;
 
 /**
  * Lazily create and cache an opencode SDK instance from the active
- * serve-info. Returns `null` when no serve-info is available.
+ * serve-info. Returns `null` when no serve-info is available OR when
+ * the SDK package is not installed (e.g. in a fresh checkout that
+ * hasn't run `npm install` yet — the dashboard's serve-info read
+ * succeeds but the dynamic import fails).
  *
  * @returns {Promise<import('@polderlabs/bizar-sdk').OpencodeSdk | null>}
  */
@@ -31,7 +36,19 @@ export async function getOpencodeSdk() {
     return _sdk;
   }
 
-  const { createOpencodeSdk } = await import("@polderlabs/bizar-sdk/opencode");
+  let createOpencodeSdk;
+  try {
+    const mod = await import("@polderlabs/bizar-sdk/opencode");
+    createOpencodeSdk = mod.createOpencodeSdk;
+    if (typeof createOpencodeSdk !== "function") createOpencodeSdk = null;
+  } catch {
+    // SDK package not installed / not built. Return null so the caller
+    // can degrade gracefully. The bg-spawner converts this into an
+    // `opencode_serve_unavailable` error.
+    return null;
+  }
+  if (!createOpencodeSdk) return null;
+
   const sdk = await createOpencodeSdk({
     baseUrl: info.baseUrl,
     password: info.password,
@@ -43,6 +60,49 @@ export async function getOpencodeSdk() {
   return sdk;
 }
 
+/**
+ * v5.5.1 — Same as {@link getOpencodeSdk} but throws when no SDK is
+ * available. Use this from code paths that REQUIRE the opencode serve
+ * (e.g. the SDK-based bg spawner) — callers want a clear error rather
+ * than a silent `null` they have to remember to check.
+ *
+ * @returns {Promise<import('@polderlabs/bizar-sdk').OpencodeSdk>}
+ */
+export async function getOpencodeSdkOrThrow() {
+  const sdk = await getOpencodeSdk();
+  if (!sdk) {
+    throw new Error(
+      "opencode_serve_unavailable: no serve-info file found. " +
+        "The opencode serve child is not running. Start it via `bizar serve` " +
+        "or run an opencode session so the plugin can write serve-info.",
+    );
+  }
+  return sdk;
+}
+
+/**
+ * v5.5.1 — Subscribe to opencode SSE events for a single session. Thin
+ * wrapper over `sdk.events.subscribe({ sessionID })` that closes the
+ * subscription cleanly when the returned async iterable is broken.
+ *
+ * Returns `{ stream, close }` — `stream` is an `AsyncIterable` of
+ * `OpencodeEventEnvelope` objects; `close()` aborts the underlying SSE
+ * connection.
+ *
+ * @param {string} sessionId
+ * @returns {Promise<AsyncIterable<unknown> & { close: () => void } | null>}
+ */
+export async function subscribeToSession(sessionId) {
+  const sdk = await getOpencodeSdk();
+  if (!sdk || !sessionId) return null;
+  try {
+    const sub = await sdk.events.subscribe({ sessionID: sessionId });
+    return sub;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Ping the opencode serve child using the SDK's health endpoint.
  * Falls back to TCP-connect ping if the SDK health check fails.
@@ -69,4 +129,4 @@ export async function pingOpencodeSdk(info) {
  * Backwards-compatible alias for `pingOpencodeSdk`.
  * @deprecated Use `pingOpencodeSdk` instead.
  */
-export const pingOpencodeServe = pingOpencodeSdk;
+export const pingOpencodeServe = pingOpencodeSdk;

package/bizar-dash/src/server/plugins/registry.mjs

@@ -44,7 +44,7 @@ import * as logger from '../logger.mjs';
  * deployments, point this at an internal CDN or S3 bucket.
  */
 const DEFAULT_REGISTRY_URL =
-  'https://raw.githubusercontent.com/DrB0rk/bizar-plugins/main/registry.json';
+  'https://raw.githubusercontent.com/DrB0rk/bizar-mods/main/registry.json';
 
 /**
  * Fallback registry URLs tried in order when the primary URL fails.

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

@@ -2,6 +2,7 @@
  * src/server/routes/activity.mjs
  *
  * /api/activity                            — full activity log (newest first)
+ * /api/activity/stream                     — SSE stream of activity events
  * /api/activity/hidden                     — list of hidden event keys (for overview hide)
  * /api/activity/hide                      — POST { keys: [...] }  add to hidden
  * /api/activity/hide                      — DELETE                  clear all hidden
@@ -106,5 +107,89 @@ export function createActivityRouter({ state } = {}) {
     res.json(data);
   }));
 
+  // GET /activity/stream — SSE stream of activity events.
+  //
+  // The Overview tab (Overview.tsx) opens this SSE connection to get live
+  // activity updates without polling. Two event types are sent:
+  //   event: snapshot\ndata: { events: ActivityItem[], generatedAt: string }\n\n
+  //   event: activity\ndata: ActivityItem\n\n
+  //
+  // The SSE lifetime is unbounded; the client auto-reconnects on drop.
+  // We send a 25s heartbeat to keep the connection alive through proxies.
+  router.get('/activity/stream', (req, res) => {
+    res.status(200);
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no');
+    if (typeof res.flushHeaders === 'function') res.flushHeaders();
+
+    let closed = false;
+
+    // Send current snapshot immediately.
+    try {
+      const overview = state?.getOverview?.();
+      const events = Array.isArray(overview?.recentActivity)
+        ? overview.recentActivity.slice(0, 50)
+        : [];
+      res.write(`event: snapshot\ndata: ${JSON.stringify({ events, generatedAt: overview?.generatedAt || new Date().toISOString() })}\n\n`);
+    } catch {
+      res.write(`event: snapshot\ndata: ${JSON.stringify({ events: [], generatedAt: new Date().toISOString() })}\n\n`);
+    }
+
+    // Poll for new activity every 5 seconds.
+    // Reads recentActivity from state and emits only genuinely new entries
+    // (identified by ts, which is set at write time).
+    let knownLastTs = null;
+    const pollInterval = setInterval(() => {
+      if (closed || res.writableEnded || res.destroyed) {
+        clearInterval(pollInterval);
+        return;
+      }
+      try {
+        const overview = state?.getOverview?.();
+        const events = Array.isArray(overview?.recentActivity)
+          ? overview.recentActivity
+          : [];
+        if (events.length === 0) return;
+
+        const newestTs = events[0].ts;
+        // Only emit if there's a genuinely newer event (newer timestamp than
+        // what we last sent, or a new entry with the same timestamp but
+        // different content).
+        if (knownLastTs === null || newestTs !== knownLastTs) {
+          const newEvents = knownLastTs === null
+            ? events
+            : events.filter((e) => e.ts !== knownLastTs);
+          for (const entry of newEvents) {
+            res.write(`event: activity\ndata: ${JSON.stringify(entry)}\n\n`);
+          }
+          knownLastTs = newestTs;
+        }
+      } catch {
+        /* ignore poll errors */
+      }
+    }, 5_000);
+
+    // Heartbeat to keep the connection alive through reverse proxies.
+    const heartbeat = setInterval(() => {
+      if (closed || res.writableEnded || res.destroyed) {
+        clearInterval(heartbeat);
+        return;
+      }
+      try {
+        res.write(': keepalive\n\n');
+      } catch {
+        clearInterval(heartbeat);
+      }
+    }, 25_000);
+
+    req.on('close', () => {
+      closed = true;
+      clearInterval(pollInterval);
+      clearInterval(heartbeat);
+    });
+  });
+
   return router;
 }

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

@@ -2,20 +2,26 @@
  * src/server/routes/background.mjs
  *
  * /api/background                          — list
- * /api/background (POST)                   — spawn from UI (v5.x)
+ * /api/background (POST)                   — spawn from UI (v5.x; v5.5.1 SDK-backed)
  * /api/background/:id                      — single instance
  * /api/background/:id/output               — tail captured output
  * /api/background/:id/tool-calls (GET)     — tool call history (v5.x)
  * /api/background/:id/tmux                 — tmux attach metadata
  * /api/background/:id/message (POST)       — send a follow-up message
- * /api/background/:id/pause (POST)         — pause subprocess (v5.x)
- * /api/background/:id/resume (POST)        — resume subprocess (v5.x)
- * /api/background/:id/steer (POST)         — kill+respawn with new prompt (v5.x)
+ * /api/background/:id/pause (POST)         — pause (v5.x SIGSTOP / v5.5.1 output pause)
+ * /api/background/:id/resume (POST)        — resume (v5.x SIGCONT / v5.5.1 drain)
+ * /api/background/:id/steer (POST)         — TRUE mid-flight prompt (v5.5.1)
  * /api/background/:id/retry (POST)         — manual unstick (v3.11.0)
  * /api/background/:id (DELETE)             — kill
  *
  * Backed by the opencode-plugin's bg instance store. Imports the
  * store lazily so this module loads even when the plugin is offline.
+ *
+ * v5.5.1: the spawner is now SDK-based (see ../bg-spawner.mjs).
+ * `POST /api/background/:id/steer` performs a true mid-flight prompt
+ * (no kill+respawn); the response shape stays backwards compatible with
+ * the v5.5.0 contract except `newInstanceId` is `null` (same instance
+ * is reused) and a new `mode: "true_midflight"` field is added.
  */
 import { Router } from 'express';
 import { wrap } from './_shared.mjs';
@@ -146,7 +152,16 @@ export function createBackgroundRouter({ broadcast }) {
     res.json({ ok: true, status: 'running' });
   }));
 
-  // v5.x — Steer (kill+restart with appended prompt). Body: { message }.
+  // v5.5.1 — Steer is now TRUE mid-flight: the dashboard calls
+  // sdk.sessions.prompt() on the live opencode session. No kill+respawn.
+  // The response shape is the same `{ ok, newInstanceId?, processId? }` —
+  // `newInstanceId` is omitted (the same instance is reused); the
+  // `mode` field tells the dashboard this was a true mid-flight steer.
+  //
+  // Backwards compat: clients that read `newInstanceId` from the response
+  // see `null` in v5.5.1 (the field is dropped, not set to the same id —
+  // explicitly set to `null` so a test can tell the new behavior apart
+  // from the old kill+respawn path).
   router.post('/background/:id/steer', wrap(async (req, res) => {
     const message = String((req.body && req.body.message) || '').trim();
     if (!message) {
@@ -162,16 +177,19 @@ export function createBackgroundRouter({ broadcast }) {
     broadcast({
       type: 'background:change',
       id: req.params.id,
-      status: 'steered',
-      newInstanceId: result.newInstanceId,
+      status: 'running',
+      action: 'steer',
+      steerCount: result.steerCount,
     });
-    broadcast({
-      type: 'background:change',
-      id: result.newInstanceId,
-      status: 'pending',
-      parentInstanceId: req.params.id,
+    res.json({
+      ok: true,
+      mode: result.mode || 'true_midflight',
+      // Same instance — explicitly null so dashboards/tests can detect
+      // the new behavior (the v5.5.0 contract returned a new id here).
+      newInstanceId: null,
+      instanceId: req.params.id,
+      steerCount: result.steerCount,
     });
-    res.json({ ok: true, status: 'steered', newInstanceId: result.newInstanceId, processId: result.processId });
   }));
 
   // v3.5.5 — Tmux session metadata. The UI uses this to render an