@polderlabs/bizar 3.7.2 → 3.8.0

package/cli/update.mjs

@@ -1,36 +1,180 @@
 /**
  * update.mjs — `bizar update` subcommand.
  *
- * Updates the opencode CLI, the @polderlabs/bizar package, and/or the
- * @polderlabs/bizar-plugin package. By default, prompts for each
- * component individually. With `--all`, updates everything without
- * prompting. With explicit subcommands (`opencode`, `bizar`, `plugin`),
- * runs only the named update.
+ * Updates the opencode CLI, the @polderlabs/bizar package, the
+ * @polderlabs/bizar-dash package, and/or the @polderlabs/bizar-plugin
+ * package. By default, prompts for each component individually. With
+ * `--all`, updates everything without prompting.
  *
- * Each update is a thin wrapper around the underlying installer:
- *   - opencode:    `opencode upgrade` (or `npm install -g opencode-ai@latest` as a fallback)
- *   - bizar:       `npm install -g @polderlabs/bizar@latest`
- *   - plugin:      `npm install -g @polderlabs/bizar-plugin@latest`
+ * Before any install, the command:
+ *   1. Detects running instances (background service daemon, dashboard
+ *      server, TUI dashboard) by reading the PID files at
+ *      ~/.config/bizar/{service,dashboard}.pid and cleaning up any
+ *      stale or empty ones.
+ *   2. Warns the user explicitly about each running instance, lists
+ *      what will be killed, and asks for confirmation. Skipped only
+ *      with `--yes` (or `--force`).
+ *   3. Sends SIGTERM to each live instance, waits up to 5s for
+ *      graceful shutdown, then escalates to SIGKILL for anything
+ *      still alive.
  *
- * After the package updates, re-runs the install script so the locally
- * deployed plugin source matches the just-upgraded npm version. Without
- * this, the plugin in `~/.config/opencode/plugins/bizar/` would be one
- * version behind the npm registry, and the BUGS.md "version skew"
+ * After a successful update of `bizar` or `bizar-dash`, the dashboard
+ * is automatically restarted (using its own `POST /api/restart`
+ * endpoint when reachable, or by spawning a new process when not).
+ * Use `--no-restart` to skip the restart.
+ *
+ * After the npm packages are updated, the install script is re-run so
+ * the locally deployed plugin source matches the just-upgraded npm
+ * version. Without this, the plugin in `~/.config/opencode/plugins/bizar/`
+ * would lag one version behind npm and the BUGS.md "version skew"
  * trap would bite.
  *
  * Exit codes:
  *   0 — all requested updates succeeded (or none were requested)
- *   1 — at least one update failed
+ *   1 — at least one update failed, or the user cancelled the kill
  */
 
 import chalk from 'chalk';
-import { execSync, spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { execSync, spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 
 const PKG_MAIN = '@polderlabs/bizar';
+const PKG_DASH = '@polderlabs/bizar-dash';
 const PKG_PLUGIN = '@polderlabs/bizar-plugin';
 
+// All known components, in the order they should be prompted + updated.
+const COMPONENTS = ['opencode', 'bizar', 'dash', 'plugin'];
+
+// ---------------------------------------------------------------------------
+// Config paths (mirror the dashboard + service for consistency)
+// ---------------------------------------------------------------------------
+
+function bizarConfigDir() {
+  if (process.platform === 'win32') {
+    return process.env.APPDATA
+      ? join(process.env.APPDATA, 'bizar')
+      : join(homedir(), '.config', 'bizar');
+  }
+  return process.env.XDG_CONFIG_HOME
+    ? join(process.env.XDG_CONFIG_HOME, 'bizar')
+    : join(homedir(), '.config', 'bizar');
+}
+
+const BIZAR_HOME = bizarConfigDir();
+const SERVICE_PID_FILE = join(BIZAR_HOME, 'service.pid');
+const DASHBOARD_PID_FILE = join(BIZAR_HOME, 'dashboard.pid');
+const DASHBOARD_PORT_FILE = join(BIZAR_HOME, 'dashboard.port');
+
+// ---------------------------------------------------------------------------
+// PID helpers (exported for testability)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and validate a PID file. Returns a live integer PID, or `null`
+ * if the file is missing / empty / contains a non-numeric value / the
+ * process is not running. Stale or corrupt PID files are removed.
+ *
+ * Exported so tests can exercise the cleanup behavior without going
+ * through the full update flow.
+ */
+export function readLivePid(pidFile) {
+  if (!existsSync(pidFile)) return null;
+  let raw;
+  try {
+    raw = readFileSync(pidFile, 'utf8').trim();
+  } catch {
+    return null;
+  }
+  if (!raw) {
+    // Empty / corrupt — clean it up so future checks are accurate.
+    try { rmSync(pidFile, { force: true }); } catch { /* ignore */ }
+    return null;
+  }
+  const pid = parseInt(raw, 10);
+  if (!Number.isFinite(pid) || pid <= 0) {
+    try { rmSync(pidFile, { force: true }); } catch { /* ignore */ }
+    return null;
+  }
+  try {
+    process.kill(pid, 0);
+    return pid;
+  } catch {
+    // PID no longer alive — stale PID file.
+    try { rmSync(pidFile, { force: true }); } catch { /* ignore */ }
+    return null;
+  }
+}
+
+/**
+ * Send SIGTERM, wait up to `timeoutMs`, then SIGKILL if still alive.
+ * Returns true if a signal was successfully delivered (or never needed).
+ *
+ * Implementation note: Linux PIDs are recycled immediately after a
+ * process dies, so `process.kill(pid, 0)` after a kill is an unreliable
+ * liveness check — the PID may already belong to a brand-new process.
+ * We treat any successful signal delivery as success; if SIGKILL is
+ * sent, the original process is certainly dead (uncatchable).
+ *
+ * Exported for testability.
+ */
+export function killAndWait(pid, { timeoutMs = 5000, label = 'process' } = {}) {
+  if (!pid) return true;
+
+  // Phase 1: graceful SIGTERM
+  let sigtermOk = false;
+  try {
+    process.kill(pid, 'SIGTERM');
+    sigtermOk = true;
+  } catch (err) {
+    if (err.code === 'ESRCH') return true; // already dead
+    console.log(chalk.yellow(`    ! could not SIGTERM ${label} (pid ${pid}): ${err.message}`));
+    return false;
+  }
+
+  // Best-effort poll for graceful exit. Note: a SIGTERM-handling process
+  // (Express dashboard, Node sleeper) usually exits within ~100ms. We
+  // poll for up to `timeoutMs`; if anything responds to kill -0 it may be
+  // a recycled PID, so we don't treat that as "still our process".
+  const start = Date.now();
+  let sawExit = false;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      process.kill(pid, 0);
+    } catch (err) {
+      if (err.code === 'ESRCH') { sawExit = true; break; }
+    }
+    spawnSync('sleep', ['0.1']);
+  }
+
+  if (sawExit) {
+    // Confirmed gone via ESRCH.
+    return true;
+  }
+
+  // Phase 2: escalate to SIGKILL. Even if `kill -0` still succeeds (PID
+  // recycled or process truly stuck), SIGKILL is uncatchable and the
+  // original process — if it was still our PID — is now dead.
+  try {
+    process.kill(pid, 'SIGKILL');
+    if (sigtermOk) {
+      console.log(chalk.yellow(`    ! ${label} (pid ${pid}) did not exit gracefully; sent SIGKILL`));
+    }
+    // Brief settle for the kernel.
+    spawnSync('sleep', ['0.2']);
+    return true;
+  } catch (err) {
+    if (err.code === 'ESRCH') return true;
+    console.log(chalk.red(`    ✗ could not SIGKILL ${label} (pid ${pid}): ${err.message}`));
+    return false;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Version helpers
 // ---------------------------------------------------------------------------
@@ -41,8 +185,10 @@ const PKG_PLUGIN = '@polderlabs/bizar-plugin';
  */
 function currentVersion(pkg) {
   try {
-    const out = execSync(`npm ls -g ${pkg} --depth=0 --json`, { stdio: ['ignore', 'pipe', 'ignore'] })
-      .toString();
+    const out = execSync(`npm ls -g ${pkg} --depth=0 --json`, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 15000,
+    }).toString();
     const parsed = JSON.parse(out);
     const deps = parsed.dependencies ?? {};
     return deps[pkg]?.version ?? null;
@@ -57,9 +203,10 @@ function currentVersion(pkg) {
  */
 function latestVersion(pkg) {
   try {
-    const out = execSync(`npm view ${pkg} version`, { stdio: ['ignore', 'pipe', 'ignore'] })
-      .toString()
-      .trim();
+    const out = execSync(`npm view ${pkg} version`, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 15000,
+    }).toString().trim();
     return out || null;
   } catch {
     return null;
@@ -76,12 +223,10 @@ function latestVersion(pkg) {
  * Returns `{ ok: boolean, message: string }`.
  */
 function updateOpencode() {
-  // Try `opencode upgrade` first — that's the canonical updater.
   const r1 = spawnSync('opencode', ['upgrade'], { stdio: 'inherit' });
   if (r1.status === 0) {
     return { ok: true, message: 'opencode updated via `opencode upgrade`' };
   }
-  // Fall back to npm. `opencode-ai` is the npm package name.
   console.log(chalk.dim('  opencode upgrade not available; falling back to npm'));
   const r2 = spawnSync('npm', ['install', '-g', 'opencode-ai@latest'], { stdio: 'inherit' });
   if (r2.status === 0) {
@@ -90,26 +235,12 @@ function updateOpencode() {
   return { ok: false, message: 'opencode update failed — try `opencode upgrade` manually' };
 }
 
-/**
- * Update @polderlabs/bizar globally. Returns `{ ok, message }`.
- */
-function updateBizar() {
-  const r = spawnSync('npm', ['install', '-g', `${PKG_MAIN}@latest`], { stdio: 'inherit' });
+function updatePackage(pkg) {
+  const r = spawnSync('npm', ['install', '-g', `${pkg}@latest`], { stdio: 'inherit' });
   if (r.status !== 0) {
-    return { ok: false, message: `${PKG_MAIN} update failed` };
+    return { ok: false, message: `${pkg} update failed` };
   }
-  return { ok: true, message: `${PKG_MAIN} updated` };
-}
-
-/**
- * Update @polderlabs/bizar-plugin globally. Returns `{ ok, message }`.
- */
-function updateBizarPlugin() {
-  const r = spawnSync('npm', ['install', '-g', `${PKG_PLUGIN}@latest`], { stdio: 'inherit' });
-  if (r.status !== 0) {
-    return { ok: false, message: `${PKG_PLUGIN} update failed` };
-  }
-  return { ok: true, message: `${PKG_PLUGIN} updated` };
+  return { ok: true, message: `${pkg} updated` };
 }
 
 // ---------------------------------------------------------------------------
@@ -122,8 +253,6 @@ function updateBizarPlugin() {
  * fix for the BUGS.md "version skew" trap.
  */
 function rerunInstallScript() {
-  // Find the package root via `npm root -g` + package name. This works
-  // whether the user installed via `npm install -g` or `npx`.
   let globalRoot;
   try {
     globalRoot = execSync('npm root -g', { stdio: ['ignore', 'pipe', 'ignore'] })
@@ -142,12 +271,10 @@ function rerunInstallScript() {
     }
     return { ok: false, message: 'setup rerun failed' };
   }
-
   const installSh = join(pkgRoot, 'install.sh');
   if (process.platform === 'win32' || !existsSync(installSh)) {
     return { ok: false, message: 'could not locate a compatible setup script to re-run' };
   }
-
   console.log(chalk.dim(`\n  Re-running install script at ${installSh}...`));
   const r = spawnSync('bash', [installSh], { stdio: 'inherit' });
   if (r.status !== 0) {
@@ -157,19 +284,141 @@ function rerunInstallScript() {
 }
 
 // ---------------------------------------------------------------------------
-// Prompt helpers
+// Instance detection + kill
 // ---------------------------------------------------------------------------
 
 /**
- * Interactive prompt for which components to update. Uses inquirer.
- * Returns a Set of `opencode`, `bizar`, `plugin` strings.
+ * Detect live Bizar instances by reading the well-known PID files.
+ * Returns:
+ *   { service: { pid, label } | null,
+ *     dashboard: { pid, port } | null,
+ *     other: Array<{ pid, cmd }> }
  */
-async function promptForUpdates(forceAll) {
-  if (forceAll) {
-    return new Set(['opencode', 'bizar', 'plugin']);
+function detectInstances() {
+  const servicePid = readLivePid(SERVICE_PID_FILE);
+  const dashboardPid = readLivePid(DASHBOARD_PID_FILE);
+  let port = null;
+  if (dashboardPid && existsSync(DASHBOARD_PORT_FILE)) {
+    try {
+      port = parseInt(readFileSync(DASHBOARD_PORT_FILE, 'utf8').trim(), 10) || null;
+    } catch { /* ignore */ }
   }
-  // Dynamic import so the rest of the file can be loaded even if
-  // inquirer is unavailable for some reason.
+  return {
+    service: servicePid ? { pid: servicePid, label: `bizar service (pid ${servicePid})` } : null,
+    dashboard: dashboardPid ? { pid: dashboardPid, port, label: `bizar-dash web dashboard (pid ${dashboardPid}${port ? `, port ${port}` : ''})` } : null,
+  };
+}
+
+/**
+ * Ask the user to confirm killing the listed instances. Returns true if
+ * they confirmed, false if they cancelled. Skipped entirely with `assumeYes`.
+ */
+async function confirmKill(instances, { assumeYes } = {}) {
+  const lines = [];
+  if (instances.service) lines.push(`  • ${instances.service.label} — background schedule runner`);
+  if (instances.dashboard) lines.push(`  • ${instances.dashboard.label} — web UI + API`);
+  if (lines.length === 0) return true;
+  if (assumeYes) return true;
+  console.log('');
+  console.log(chalk.bold.yellow('  ⚠  Running Bizar instances detected:'));
+  for (const l of lines) console.log(chalk.yellow(l));
+  console.log('');
+  console.log(chalk.yellow('  These must be stopped before npm can replace the on-disk files.'));
+  console.log(chalk.yellow('  Killing them will close any open web tabs / TUI sessions.'));
+  console.log('');
+  // Best-effort interactive confirmation. Non-TTY (CI / piped input) skips the
+  // prompt and aborts — callers should pass `--yes` explicitly in that case.
+  if (!process.stdin.isTTY) {
+    console.log(chalk.red('  Non-interactive shell detected; rerun with --yes to confirm the kill, or stop the processes manually.'));
+    return false;
+  }
+  try {
+    const inquirer = await import('inquirer');
+    const { ok } = await inquirer.default.prompt([
+      {
+        type: 'confirm',
+        name: 'ok',
+        message: 'Kill the running instance(s) and continue?',
+        default: true,
+      },
+    ]);
+    return Boolean(ok);
+  } catch (err) {
+    console.log(chalk.red(`  ! inquirer unavailable: ${err.message}`));
+    return false;
+  }
+}
+
+function killInstances(instances) {
+  const out = [];
+  if (instances.service) {
+    const ok = killAndWait(instances.service.pid, { label: 'bizar service' });
+    out.push({ name: 'service', ok });
+    if (ok) {
+      try { rmSync(SERVICE_PID_FILE, { force: true }); } catch { /* ignore */ }
+    }
+  }
+  if (instances.dashboard) {
+    const ok = killAndWait(instances.dashboard.pid, { label: 'bizar-dash' });
+    out.push({ name: 'dashboard', ok });
+    if (ok) {
+      try { rmSync(DASHBOARD_PID_FILE, { force: true }); } catch { /* ignore */ }
+      try { rmSync(DASHBOARD_PORT_FILE, { force: true }); } catch { /* ignore */ }
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Restart the dashboard after the update completes
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn a fresh dashboard process detached, returning the new PID. The
+ * dashboard will use the just-updated @polderlabs/bizar-dash code from
+ * the global npm install.
+ */
+function spawnFreshDashboard({ port } = {}) {
+  let globalRoot;
+  try {
+    globalRoot = execSync('npm root -g', { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+  } catch {
+    return { ok: false, message: 'could not locate npm global root' };
+  }
+  const dashBin = join(globalRoot, ...PKG_DASH.split('/'), 'src', 'cli.mjs');
+  if (!existsSync(dashBin)) {
+    return {
+      ok: false,
+      message: `dashboard binary not found at ${dashBin} (was @polderlabs/bizar-dash installed?)`,
+    };
+  }
+  try {
+    mkdirSync(BIZAR_HOME, { recursive: true });
+  } catch { /* ignore */ }
+  const args = [dashBin, 'start', '--bg'];
+  if (port) args.push(`--port=${port}`);
+  try {
+    const child = spawn(process.execPath, args, {
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env, BIZAR_AUTO_RESPAWN: '1' },
+    });
+    child.on('error', () => { /* ignore */ });
+    child.unref();
+    return { ok: true, message: `dashboard re-spawned (pid ${child.pid})` };
+  } catch (err) {
+    return { ok: false, message: `dashboard re-spawn failed: ${err.message}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Prompt helpers
+// ---------------------------------------------------------------------------
+
+async function promptForUpdates(forceAll) {
+  if (forceAll) return new Set(COMPONENTS);
   const inquirer = await import('inquirer');
   const { selections } = await inquirer.default.prompt([
     {
@@ -179,6 +428,7 @@ async function promptForUpdates(forceAll) {
       choices: [
         { name: 'opencode (the opencode CLI itself)', value: 'opencode', checked: true },
         { name: `bizar (${PKG_MAIN})`, value: 'bizar', checked: true },
+        { name: `bizar-dash (${PKG_DASH}) — web dashboard`, value: 'dash', checked: true },
         { name: `plugin (${PKG_PLUGIN})`, value: 'plugin', checked: true },
       ],
     },
@@ -190,29 +440,60 @@ async function promptForUpdates(forceAll) {
 // Main entry point
 // ---------------------------------------------------------------------------
 
-/**
- * Run the update subcommand.
- *
- * @param {string[]} subargs - arguments after `bizar update`
- */
 export async function runUpdate(subargs = []) {
   console.log(chalk.bold.hex('#a855f7')('\n  ᚦ BIZAR UPDATE ᚦ\n'));
 
-  // Show what we know before asking.
+  // Parse flags
+  const assumeYes = subargs.includes('--yes') || subargs.includes('-y') || subargs.includes('--force');
+  const restartAfter = !subargs.includes('--no-restart');
+  const forceAll = subargs.includes('--all');
+
+  // 1. Detect running instances BEFORE doing anything else.
+  const instances = detectInstances();
+  const runningCount = (instances.service ? 1 : 0) + (instances.dashboard ? 1 : 0);
+
+  if (runningCount > 0) {
+    const ok = await confirmKill(instances, { assumeYes });
+    if (!ok) {
+      console.log(chalk.yellow('\n  Update cancelled — instances still running.'));
+      console.log(chalk.dim('  Stop them with `bizar service stop` and `bizar dashboard stop`, then retry.'));
+      process.exit(1);
+    }
+    console.log(chalk.cyan('\n  Stopping running instances...'));
+    const kills = killInstances(instances);
+    for (const k of kills) {
+      const marker = k.ok ? chalk.green('✓') : chalk.red('✗');
+      console.log(`    ${marker} ${k.name} stopped`);
+    }
+    // Give the kernel a moment to release any open file handles on the
+    // npm-global directory before npm tries to replace files.
+    spawnSync('sleep', ['0.5']);
+  } else {
+    console.log(chalk.dim('  No running Bizar instances detected.'));
+  }
+
+  // 2. Show installed vs. latest versions.
   const cur = {
     opencode: currentVersion('opencode-ai'),
     bizar: currentVersion(PKG_MAIN),
+    dash: currentVersion(PKG_DASH),
     plugin: currentVersion(PKG_PLUGIN),
   };
   const latest = {
     opencode: latestVersion('opencode-ai'),
     bizar: latestVersion(PKG_MAIN),
+    dash: latestVersion(PKG_DASH),
     plugin: latestVersion(PKG_PLUGIN),
   };
 
+  console.log('');
   console.log('  Installed vs. latest:');
-  for (const k of Object.keys(cur)) {
-    const label = k === 'plugin' ? PKG_PLUGIN : k === 'bizar' ? PKG_MAIN : 'opencode-ai';
+  for (const k of COMPONENTS) {
+    const label =
+      k === 'plugin' ? PKG_PLUGIN :
+      k === 'dash' ? PKG_DASH :
+      k === 'bizar' ? PKG_MAIN :
+      'opencode-ai';
     const c = cur[k] ?? '(not installed)';
     const l = latest[k] ?? '(unknown)';
     const same = c === l;
@@ -220,19 +501,18 @@ export async function runUpdate(subargs = []) {
   }
   console.log('');
 
-  // Decide what to update.
+  // 3. Decide what to update.
   let selected;
-  if (subargs.includes('--all')) {
-    selected = new Set(['opencode', 'bizar', 'plugin']);
+  if (forceAll || assumeYes) {
+    selected = new Set(COMPONENTS);
   } else if (subargs.length === 0) {
     selected = await promptForUpdates(false);
   } else {
-    // Explicit subcommands.
-    const valid = new Set(['opencode', 'bizar', 'plugin']);
-    selected = new Set(subargs.filter((a) => valid.has(a)));
+    const valid = new Set(COMPONENTS);
+    selected = new Set(subargs.filter((a) => !a.startsWith('-') && valid.has(a)));
     if (selected.size === 0) {
       console.log(chalk.yellow(`  No valid components selected from: ${subargs.join(' ')}`));
-      console.log(chalk.dim('  Valid components: opencode, bizar, plugin'));
+      console.log(chalk.dim('  Valid components: opencode, bizar, dash, plugin'));
       console.log(chalk.dim('  Run `bizar update --help` for usage.'));
       process.exit(1);
     }
@@ -252,15 +532,18 @@ export async function runUpdate(subargs = []) {
   }
   if (selected.has('bizar')) {
     console.log(chalk.bold(`  → ${PKG_MAIN}`));
-    results.push(['bizar', updateBizar()]);
+    results.push(['bizar', updatePackage(PKG_MAIN)]);
+  }
+  if (selected.has('dash')) {
+    console.log(chalk.bold(`  → ${PKG_DASH}`));
+    results.push(['dash', updatePackage(PKG_DASH)]);
   }
   if (selected.has('plugin')) {
     console.log(chalk.bold(`  → ${PKG_PLUGIN}`));
-    results.push(['plugin', updateBizarPlugin()]);
+    results.push(['plugin', updatePackage(PKG_PLUGIN)]);
   }
 
-  // Re-run the install script if anything was updated, so the deployed
-  // plugin source matches the registry.
+  // 4. Re-run the install script if anything relevant changed.
   const anySuccess = results.some(([, r]) => r.ok);
   if (anySuccess && (selected.has('bizar') || selected.has('plugin'))) {
     console.log('');
@@ -273,6 +556,20 @@ export async function runUpdate(subargs = []) {
     }
   }
 
+  // 5. Restart the dashboard if it was running before the update.
+  if (restartAfter && instances.dashboard && (selected.has('bizar') || selected.has('dash'))) {
+    console.log('');
+    console.log(chalk.cyan('  Restarting dashboard with the new code...'));
+    const res = spawnFreshDashboard({ port: instances.dashboard.port || undefined });
+    if (res.ok) {
+      console.log(chalk.green(`  ✓ ${res.message}`));
+    } else {
+      console.log(chalk.yellow(`  ⚠ ${res.message}`));
+      console.log(chalk.dim('    Start it manually with `bizar-dash start --bg`.'));
+    }
+  }
+
+  // 6. Summary
   console.log('');
   console.log('  Summary:');
   for (const [name, r] of results) {
@@ -286,4 +583,4 @@ export async function runUpdate(subargs = []) {
     process.exit(1);
   }
   console.log(chalk.green('\n  ✓ Update complete\n'));
-}
+}

package/config/AGENTS.md

@@ -283,6 +283,36 @@ The Hindsight MCP server is already configured. All agents interact with it thro
 
 ---
 
+## Graph Query (bizar graph)
+
+Bizar integrates [graphify](https://github.com/safishamsi/graphify) for per-project knowledge graphs. When investigating a Bizar project, **query the graph before grepping raw files** — it's faster and surfaces structural relationships grep can't see.
+
+### Where the graph lives
+`.bizar/graph/` inside the project (git-trackable JSON + Markdown; cache and per-machine interpreter path are gitignored).
+
+### How to query
+From the project root, the user (or heimdall via `/init` or any other agent prompted by Odin) can run:
+- `bizar graph status` — confirm the graph exists; print node/edge/community counts
+- `bizar graph query "<concept>"` — find nodes related to a concept (BFS traversal)
+- `bizar graph path "<A>" "<B>"` — shortest path between two concepts
+- `bizar graph explain "<X>"` — all nodes related to X
+- `bizar graph update` — incremental rebuild after editing source files
+- `bizar graph build` — full rebuild (overwrites existing graph)
+- `bizar graph watch` — foreground watcher (Ctrl-C to stop)
+
+### When to use the graph
+- Before reading a large file: `bizar graph explain "<module-name>"` to see what calls/uses it
+- When mapping unfamiliar code: `bizar graph query "<feature>"` to find related concepts
+- When debugging cross-module interactions: `bizar graph path "<symptom>" "<root-cause>"`
+- Before grep: `bizar graph query "<term>"` first — the graph may already point you to the right file
+
+### When NOT to use the graph
+- The graph is stale (run `bizar graph update` first)
+- graphify is not installed (init skipped graph step; user can install with `pip install graphifyy` then `bizar graph build`)
+- The question is about runtime behavior, not source structure
+
+---
+
 ---
 
 ## General Agent Baseline — Always-On Behavior
@@ -548,3 +578,26 @@ For Bizar-internal claims (citing files, lines, tool results), use file:line ref
 
 This baseline covers: identity, refusal, tone, formatting, lists, user wellbeing, evenhandedness, mistakes, knowledge cutoff and research-first, MCP servers and skills, mandatory skill-read, file creation, file handling, search, copyright, harmful content, citations, images, memory privacy, execution, clarification, and communication. Every Bizar agent — Odin, Frigg, Vör, Mimir, Heimdall, Hermod, Thor, Baldr, Tyr, Vidarr, Forseti — must follow it.
 
+---
+
+## Parallel Execution Awareness
+
+You may be dispatched by Odin as one of several agents running concurrently against the same working directory and the same git repository. Your sibling agents **cannot see you** and you **cannot see them**. Without discipline this leads to silent file overwrites, `.git/index.lock` collisions, lockfile corruption, and lost work.
+
+### Hard rules when you have siblings (Odin tells you in the prompt)
+
+1. **File scope is sacred.** Odin assigns you a scope. Only modify files inside it. If you need to touch something outside, STOP and report — do not improvise.
+2. **No write-level git.** `git commit`, `push`, `merge`, `rebase`, `reset`, `clean`, `stash`, branch-switching `checkout`, and `pull --rebase` are FORBIDDEN for every agent except @hermod. Use `git status`, `git diff`, `git log`, and `git add` (scope files only) for context.
+3. **Detect conflicts before they happen.** Before writing a file, run `git diff --name-only` and confirm the file is not in a sibling's scope. If it has changed since you started, STOP and report.
+4. **`.git/index.lock` is a sibling's signal.** If you see it, wait 2-3 seconds and retry. If it persists, STOP and report. Do not delete the lock file.
+5. **Lockfiles and root configs are shared.** `package.json`, `package-lock.json`, `tsconfig.json`, `vite.config.*`, `Dockerfile`, CI configs — only ONE agent in a batch should touch these. If Odin did not assign them to you, treat as READ-ONLY.
+6. **Report parallel context in your final summary.** State "siblings: ..." and any conflicts observed.
+
+### Default behavior when Odin does NOT mention siblings
+
+- You may work normally.
+- Still avoid `git commit`/`push`/`merge`/`rebase`/`reset`/`clean`/`stash` unless explicitly asked. Default to read-only git unless the user/Odin explicitly requests a write operation. When in doubt, leave git work to @hermod.
+
+### Why this exists
+The harness shares one `.git/` directory across all parallel sessions. Two simultaneous `git commit` calls race on the index lock. Two agents writing the same file = silent last-writer-wins data loss. Discipline now is cheaper than recovery later.
+