@yemi33/minions 0.1.2142 → 0.1.2144

package/bin/cli-api-client.js

@@ -21,8 +21,42 @@
 const http = require('http');
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
-const DEFAULT_BASE_URL = process.env.MINIONS_DASHBOARD_URL || 'http://localhost:7331';
+/**
+ * Resolve the dashboard base URL on EVERY call so commands invoked while the
+ * dashboard auto-fallback bound to a non-default port (W-mq5nwl9l) still
+ * reach it. Precedence:
+ *   1. MINIONS_DASHBOARD_URL env var (full URL — wins absolutely)
+ *   2. engine/dashboard-port.json runtime file (the live dashboard's actual port)
+ *   3. http://localhost:7331 (legacy default)
+ *
+ * Inlined here (rather than going through engine/shared.js) so the CLI client
+ * stays runtime-loadable even if shared.js fails to load mid-upgrade.
+ */
+function _readRuntimePort() {
+  try {
+    const home = process.env.MINIONS_HOME || path.join(os.homedir(), '.minions');
+    const raw = fs.readFileSync(path.join(home, 'engine', 'dashboard-port.json'), 'utf8');
+    const data = JSON.parse(raw);
+    const port = Number(data && data.port);
+    if (Number.isInteger(port) && port > 0 && port <= 65535) return port;
+  } catch {}
+  return null;
+}
+
+function getDefaultBaseUrl() {
+  if (process.env.MINIONS_DASHBOARD_URL) return process.env.MINIONS_DASHBOARD_URL;
+  const port = _readRuntimePort();
+  if (port) return `http://localhost:${port}`;
+  return 'http://localhost:7331';
+}
+
+// Backwards-compat: an evaluated-at-import snapshot for callers that just want
+// "the value at the time the module loaded". Live consumers should call
+// getDefaultBaseUrl() (default-parameter evaluation inside apiCall does that
+// for them transparently).
+const DEFAULT_BASE_URL = getDefaultBaseUrl();
 
 // ── HTTP core ───────────────────────────────────────────────────────────────
 
@@ -60,7 +94,8 @@ function _normalizeApiPath(input) {
   return s;
 }
 
-function apiCall(method, urlPath, bodyJson, { baseUrl = DEFAULT_BASE_URL, timeoutMs = 30000 } = {}) {
+function apiCall(method, urlPath, bodyJson, { baseUrl, timeoutMs = 30000 } = {}) {
+  if (!baseUrl) baseUrl = getDefaultBaseUrl();
   return new Promise((resolve, reject) => {
     const normalized = _normalizeApiPath(urlPath);
     let u;
@@ -165,9 +200,10 @@ function _formatPlanOneLine(p) {
 // ── Generic passthrough: `minions api <METHOD> <PATH> [...]` ────────────────
 
 async function cliApi(argv) {
+  const baseUrlDefault = getDefaultBaseUrl();
   const help = `Usage: minions api <METHOD> <PATH> [--body JSON | --body-file FILE] [--base-url URL] [--quiet]
 
-Direct HTTP passthrough to the dashboard API at ${DEFAULT_BASE_URL}.
+Direct HTTP passthrough to the dashboard API at ${baseUrlDefault}.
 
 Examples:
   minions api GET  /api/status
@@ -187,7 +223,7 @@ Exit codes: 0 = 2xx, 1 = 4xx/5xx, 2 = connection failure / bad usage`;
     lineOut(help);
     return 2;
   }
-  const baseUrl = takeFlag(argv, '--base-url') || DEFAULT_BASE_URL;
+  const baseUrl = takeFlag(argv, '--base-url') || baseUrlDefault;
   const bodyInline = takeFlag(argv, '--body');
   const bodyFile = takeFlag(argv, '--body-file');
   const quiet = hasFlag(argv, '--quiet');
@@ -711,6 +747,7 @@ module.exports = {
   isHandled,
   dispatch,
   DEFAULT_BASE_URL,
+  getDefaultBaseUrl,
   // Per-command handlers exposed for unit tests that want to drive them
   // directly without going through process.argv.
   _handlers: { cliApi, cliWi, cliPlans, cliSchedule, cliWatch, cliFeature, cliSettings },

package/bin/minions.js

@@ -64,7 +64,43 @@ const PKG_ROOT = path.resolve(__dirname, '..');
 const shared = require(path.join(PKG_ROOT, 'engine', 'shared'));
 const { openUrlInBrowser } = shared;
 const { waitForRestartHealth, formatRestartHealthError } = require(path.join(PKG_ROOT, 'engine', 'restart-health'));
-const DASH_PORT = 7331;
+
+/**
+ * Resolve the dashboard port for any CLI command. Precedence (W-mq5nwl9l):
+ *   1. Runtime file (engine/dashboard-port.json) — what the live dashboard
+ *      ACTUALLY bound to. Wins over the chain so status/dash/restart-health
+ *      probes the right port even after an EADDRINUSE auto-fallback.
+ *   2. Explicit `--port N` CLI flag if present in `argv`.
+ *   3. env MINIONS_DASHBOARD_PORT.
+ *   4. config.json#engine.dashboardPort.
+ *   5. shared.DEFAULT_DASHBOARD_PORT (7331).
+ *
+ * Returns `{port, source, fromRuntimeFile}` so log lines can stay accurate.
+ * `fromRuntimeFile=true` means a dashboard wrote it; falsy means we computed
+ * the desired port from the chain (used when SPAWNING a fresh dashboard).
+ */
+function resolveDashboardPort(argv) {
+  // Read MINIONS_HOME lazily via env so this helper works at CLI-init time
+  // (before the const below is bound) — the const is resolved later.
+  const home = process.env.MINIONS_HOME || (typeof MINIONS_HOME !== 'undefined' ? MINIONS_HOME : null);
+  const rt = home ? shared.readDashboardPortFile(home) : shared.readDashboardPortFile();
+  if (rt && rt.port) return { port: rt.port, source: 'runtime-file', fromRuntimeFile: true };
+  let explicit = null;
+  if (Array.isArray(argv)) {
+    const i = argv.indexOf('--port');
+    if (i >= 0 && argv[i + 1]) explicit = argv[i + 1];
+  }
+  let cfg = null;
+  try {
+    if (home) cfg = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8'));
+  } catch { /* config may not exist yet */ }
+  const chain = shared.resolveDashboardPort({
+    explicit,
+    env: process.env.MINIONS_DASHBOARD_PORT,
+    config: cfg && cfg.engine && cfg.engine.dashboardPort,
+  });
+  return { port: chain.port, source: chain.source, fromRuntimeFile: false };
+}
 
 /** Returns PIDs (as strings) of processes LISTENING on `port`. Empty on no match
  *  or when the platform tool (netstat/findstr/lsof) is unavailable. */
@@ -276,12 +312,17 @@ function _sqliteSpawnFlags() {
 /** Spawn a detached dashboard with self-open suppressed — the CLI decides
  *  when to open a browser based on whether a real tab reconnects post-health.
  *  stdout/stderr land in engine/dashboard-stdio.log so silent startup crashes
- *  leave a postmortem instead of vanishing. */
-function spawnDashboard() {
+ *  leave a postmortem instead of vanishing. The optional `requestedPort` is
+ *  forwarded as argv[2] so the dashboard's own port resolver agrees with the
+ *  CLI's intent (EADDRINUSE retries still apply inside the dashboard if a
+ *  race opens between the CLI's port-free check and the actual bind). */
+function spawnDashboard(requestedPort) {
   const env = { ...process.env, MINIONS_NO_AUTO_OPEN: '1' };
   const out = _openStdioLog('dashboard-stdio.log');
   const err = _openStdioLog('dashboard-stdio.log');
-  const proc = spawn(process.execPath, [..._sqliteSpawnFlags(), path.join(MINIONS_HOME, 'dashboard.js')], {
+  const args = [..._sqliteSpawnFlags(), path.join(MINIONS_HOME, 'dashboard.js')];
+  if (requestedPort) args.push(String(requestedPort));
+  const proc = spawn(process.execPath, args, {
     cwd: MINIONS_HOME, stdio: ['ignore', out, err], detached: true, windowsHide: true, env
   });
   proc.unref();
@@ -324,17 +365,30 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
   });
   engineProc.unref();
   console.log(`\n  Engine started (PID: ${engineProc.pid})`);
-  const dashProc = spawnDashboard();
+  // The CLI has already killed any stale dashboard + port-released; the
+  // resolved chain port is what the new dashboard will TRY first. Forward
+  // it via argv so the dashboard's own resolver agrees. EADDRINUSE auto-
+  // fallback inside dashboard.js will pick a different port if a race opens.
+  const requested = resolveDashboardPort(rest);
+  const dashProc = spawnDashboard(requested.port);
   console.log(`  Dashboard started (PID: ${dashProc.pid})`);
-  console.log(`  Dashboard: http://localhost:${DASH_PORT}`);
+  console.log(`  Dashboard: http://localhost:${requested.port}`);
   const supProc = spawnSupervisor();
   console.log(`  Supervisor started (PID: ${supProc.pid})`);
   console.log('  Verifying restart health...');
   void (async () => {
+    // Poll the runtime port file so we use the ACTUAL bound port (which may
+    // differ from `requested.port` after EADDRINUSE retry). If the dashboard
+    // never writes it, fall back to the requested port — restart-health then
+    // surfaces a clear failure rather than the CLI silently mis-probing.
+    const actualPort = await _waitForDashboardPortFile(MINIONS_HOME, 12000) || requested.port;
+    if (actualPort !== requested.port) {
+      console.log(`  Dashboard bound to alternate port ${actualPort} (requested ${requested.port} was busy)`);
+    }
     const result = await waitForRestartHealth({
       minionsHome: MINIONS_HOME,
       dashboardPid: dashProc.pid,
-      dashboardPort: DASH_PORT,
+      dashboardPort: actualPort,
     });
     if (!result.ok) {
       console.error(formatRestartHealthError(result));
@@ -346,7 +400,7 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
       !(await _waitForBrowserReconnect(MINIONS_HOME, { afterMs: restartStartMs, timeoutMs: 5000 }));
     if (shouldOpen) {
       console.log(`  Opening dashboard in browser...`);
-      _openInBrowser(`http://localhost:${DASH_PORT}`);
+      _openInBrowser(`http://localhost:${actualPort}`);
     }
     console.log('');
   })().catch(err => {
@@ -356,6 +410,36 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
   });
 }
 
+/** Poll engine/dashboard-port.json until it appears (dashboard wrote it on
+ *  listen) or the timeout elapses. Returns the bound port or null on
+ *  timeout. Stale files left behind by a crashed dashboard are tolerated —
+ *  if the file pre-dates the current spawn we still pick it up; the
+ *  subsequent isPortListening probe in waitForRestartHealth will catch a
+ *  truly dead dashboard. */
+async function _waitForDashboardPortFile(home, timeoutMs = 12000, pollMs = 150) {
+  const start = Date.now();
+  const startedAt = start;
+  while (Date.now() - start < timeoutMs) {
+    const rt = shared.readDashboardPortFile(home);
+    if (rt && rt.port) {
+      // Prefer entries written AFTER we started polling. If the file is
+      // older (stale from a previous instance) it'll get rewritten by the
+      // new dashboard within the polling window — keep polling until then.
+      if (rt.boundAt) {
+        const ts = Date.parse(rt.boundAt);
+        if (Number.isFinite(ts) && ts >= startedAt - 1000) return rt.port;
+      } else {
+        return rt.port;
+      }
+    }
+    await new Promise(r => setTimeout(r, pollMs));
+  }
+  // Final read — even a stale entry is better than nothing if we timed out
+  // (the chain fallback in the caller covers a fully-missing file).
+  const rtFinal = shared.readDashboardPortFile(home);
+  return rtFinal && rtFinal.port ? rtFinal.port : null;
+}
+
 /** Clear the stop-intent flag so the supervisor resumes guarding the engine
  *  and dashboard. Called at the top of every start/restart path.
  *  Delegates to engine/shared.js when available so engine.js, dashboard.js,
@@ -653,7 +737,8 @@ function init() {
   if (isUpgrade && skipStart) return;
 
   // Auto-start on fresh install; direct force-upgrade restarts automatically.
-  const dashWasUp = isPortListening(DASH_PORT);
+  const upgradeRequested = resolveDashboardPort([]);
+  const dashWasUp = isPortListening(upgradeRequested.port);
   const restartStartMs = Date.now();
   if (isUpgrade) {
     // Pre-write stop-intent so the supervisor doesn't race-respawn the
@@ -663,7 +748,10 @@ function init() {
     try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME, timeout: 10000, windowsHide: true }); } catch {}
     // Free the dashboard port too — without this the new dashboard EADDRINUSE-dies
     // silently and the user keeps running stale code from the old dashboard process.
-    killByPort(DASH_PORT);
+    killByPort(upgradeRequested.port);
+    // Wipe the runtime port file so the new dashboard's freshly-written
+    // beacon is the source of truth (avoids polling-back a stale entry).
+    shared.clearDashboardPortFile(MINIONS_HOME);
     // Clear AFTER kill so the old dashboard can't repopulate during shutdown.
     _clearDashboardBrowserState(MINIONS_HOME);
   }
@@ -679,19 +767,20 @@ function init() {
   engineProc.unref();
   console.log(`  Engine started (PID: ${engineProc.pid})`);
 
-  const dashProc = spawnDashboard();
+  const dashProc = spawnDashboard(upgradeRequested.port);
   console.log(`  Dashboard started (PID: ${dashProc.pid})`);
-  console.log(`  Dashboard: http://localhost:${DASH_PORT}`);
+  console.log(`  Dashboard: http://localhost:${upgradeRequested.port}`);
 
   const supProc = spawnSupervisor();
   console.log(`  Supervisor started (PID: ${supProc.pid})`);
 
   void (async () => {
+    const actualPort = await _waitForDashboardPortFile(MINIONS_HOME, 8000) || upgradeRequested.port;
     const shouldOpen = forceOpen || !dashWasUp ||
       !(await _waitForBrowserReconnect(MINIONS_HOME, { afterMs: restartStartMs, timeoutMs: 5000 }));
     if (shouldOpen) {
       console.log(`  Opening dashboard in browser...`);
-      _openInBrowser(`http://localhost:${DASH_PORT}`);
+      _openInBrowser(`http://localhost:${actualPort}`);
     }
   })().catch(err => {
     console.log(`  Could not open dashboard: ${err.message}`);
@@ -1010,12 +1099,16 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   if (enginePid) {
     try { process.kill(enginePid, 0); engineAlive = true; } catch { /* dead */ }
   }
-  const dashUp = isPortListening(DASH_PORT);
+  // Probe the runtime port file first (already-bound dashboard) then fall
+  // back to the chain. Source distinguishes 'runtime-file' vs default for
+  // the partial-state error message.
+  const startResolved = resolveDashboardPort(rest);
+  const dashUp = isPortListening(startResolved.port);
   if (engineAlive && dashUp) {
-    console.log(`\n  Minions is already running (engine PID ${enginePid}; dashboard http://localhost:${DASH_PORT}).`);
+    console.log(`\n  Minions is already running (engine PID ${enginePid}; dashboard http://localhost:${startResolved.port}).`);
     if (forceOpen) {
       console.log(`  Opening dashboard in browser...`);
-      _openInBrowser(`http://localhost:${DASH_PORT}`);
+      _openInBrowser(`http://localhost:${startResolved.port}`);
     } else {
       console.log(`  Run \`minions dash\` to open the dashboard, or \`minions start --open\` to force a new browser tab.\n`);
     }
@@ -1033,7 +1126,11 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   // `--cli` / `--model` flags forward to `engine.js start` so the runtime
   // fleet flips before the daemon spawns (P-6b3f9c2e AC: works on restart).
   ensureInstalled();
-  const dashWasUp = isPortListening(DASH_PORT);
+  // For restart we want the port the CURRENT dashboard is bound to (so we
+  // kill it on its actual port) — runtime file wins for the kill step. The
+  // chain falls in as fallback if no file exists yet (cold start).
+  const restartResolved = resolveDashboardPort(rest);
+  const dashWasUp = isPortListening(restartResolved.port);
   const restartStartMs = Date.now();
   // Pre-write stop-intent so the supervisor doesn't race-respawn the
   // engine/dashboard we're about to kill. Killed before the engine/dashboard
@@ -1048,7 +1145,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   // Force-kill the recorded engine PID (NOT the tree — agent children must
   // survive so the new engine can re-attach them via PID files).
   killPidOnly(oldEnginePid);
-  killByPort(DASH_PORT);
+  killByPort(restartResolved.port);
   killMinionsProcesses(['engine.js', 'dashboard.js', 'supervisor.js']);
   // Confirm the OS finished the asynchronous termination before we spawn new
   // processes. Without this, `taskkill /F` returns immediately while the
@@ -1064,14 +1161,17 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
       process.exit(1);
     }
   }
-  const portFree = waitForPortRelease(DASH_PORT, 10000);
+  const portFree = waitForPortRelease(restartResolved.port, 10000);
   if (!portFree.ok) {
-    console.error(`\n  ERROR: Port ${DASH_PORT} still in use after 10s — killing failed.`);
+    console.error(`\n  ERROR: Port ${restartResolved.port} still in use after 10s — killing failed.`);
     console.error(`  Bound by PID(s): ${portFree.stillBound.join(', ')}`);
     console.error(`  Manually free the port: taskkill /F /PID ${portFree.stillBound.join(' /PID ')}`);
     console.error(`  Then retry: minions restart`);
     process.exit(1);
   }
+  // Wipe the runtime port file so a stale entry from the old dashboard
+  // can't fool the post-spawn poll into reading the old port.
+  shared.clearDashboardPortFile(MINIONS_HOME);
   // Clear stale beacons AFTER the kill so the old dashboard's last writes
   // can't repopulate the file in the gap between clear and shutdown.
   _clearDashboardBrowserState(MINIONS_HOME);
@@ -1108,8 +1208,9 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
 
   // 1. Kill all processes
   try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME }); } catch {}
-  killByPort(DASH_PORT);
+  killByPort(resolveDashboardPort([]).port);
   killMinionsProcesses(['engine.js', 'dashboard.js', 'spawn-agent.js']);
+  shared.clearDashboardPortFile(MINIONS_HOME);
   console.log('  Killed all processes');
 
   // 2. Delete runtime state
@@ -1199,7 +1300,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   writeStopIntent('minions uninstall');
   killSupervisor();
   try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME, timeout: 10000 }); } catch {}
-  killByPort(DASH_PORT);
+  killByPort(resolveDashboardPort([]).port);
   killMinionsProcesses(['engine.js', 'dashboard.js', 'spawn-agent.js', 'supervisor.js']);
   console.log('  Killed all processes');
 
@@ -1239,7 +1340,11 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   doctor(MINIONS_HOME).then(ok => process.exit(ok ? 0 : 1));
 } else if (cmd === 'dash' || cmd === 'dashboard') {
   ensureInstalled();
-  // If dashboard is already running, just open the browser
+  // If dashboard is already running, just open the browser. The runtime
+  // port file wins over the resolution chain when the dashboard is up so
+  // the probe targets the actually-bound port (which may differ from the
+  // default after an EADDRINUSE auto-fallback).
+  const dashResolved = resolveDashboardPort(rest);
   const net = require('net');
   const sock = new net.Socket();
   let handled = false;
@@ -1248,7 +1353,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     sock.destroy();
     if (handled) return;
     handled = true;
-    const url = `http://localhost:${DASH_PORT}`;
+    const url = `http://localhost:${dashResolved.port}`;
     console.log(`\n  Dashboard already running: ${url}\n`);
     openUrlInBrowser(url);
   });
@@ -1264,7 +1369,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     handled = true;
     delegate('dashboard.js', rest);
   });
-  sock.connect(DASH_PORT, '127.0.0.1');
+  sock.connect(dashResolved.port, '127.0.0.1');
 } else if (engineCmds.has(cmd)) {
   delegate('engine.js', [cmd, ...rest]);
 } else if (require('./cli-api-client').isHandled(cmd)) {

package/dashboard/js/refresh.js

@@ -137,7 +137,7 @@ const RENDER_VERSIONS = {
   projects: 1,
   notes: 1,
   prd: 1,
-  prs: 2,
+  prs: 3,
   archivedPrds: 1,
   engine: 4,
   version: 1,

package/dashboard/js/render-prs.js

@@ -153,10 +153,11 @@ function prRow(pr) {
         ? '<span class="pr-agent" title="' + escapeHtml(pr.reviewedBy.join(', ')) + '">' + escapeHtml(pr.reviewedBy.join(', ')) + '</span>'
         : '<span style="color:var(--muted);font-size:var(--text-base)">—</span>';
   const createdLabel = (pr.created || '—').slice(0, 16).replace('T', ' ');
-  // Per-row auto-observe toggle (W-mpmwxkzm0009ba0b). _contextOnly === true
-  // means the engine polls status/comments but does NOT dispatch review/fix
-  // agents against this PR. Default (undefined / false) = observed.
-  var observe = pr._contextOnly !== true;
+  // Per-row auto-observe toggle (W-mpmwxkzm0009ba0b; canonicalized in
+  // W-mq5s5ttx000j7ab8-c). pr.contextOnly === true means the engine polls
+  // status/comments but does NOT dispatch review/fix agents against this
+  // PR. Default (undefined / false) = observed.
+  var observe = pr.contextOnly !== true;
   var observeClass = observe ? 'pr-observe-on' : 'pr-observe-off';
   var observeLabel = observe ? 'observed' : 'context';
   var observeTitle = observe
@@ -396,9 +397,10 @@ async function unlinkPr(id) {
 }
 
 // Per-row auto-observe toggle (W-mpmwxkzm0009ba0b; toggle-switch UX in
-// W-mpof8qam000h62fb). Optimistic UI: flip the switch immediately, only
-// revert on API error. The engine consumes `_contextOnly` to gate review/fix
-// dispatch (engine/shared.js isAutoManagedPrRecord + discoverFromPrs).
+// W-mpof8qam000h62fb; canonicalized in W-mq5s5ttx000j7ab8-c). Optimistic
+// UI: flip the switch immediately, only revert on API error. The engine
+// consumes canonical `contextOnly` to gate review/fix dispatch (engine/
+// shared.js isAutoManagedPrRecord + discoverFromPrs).
 //
 // `btn` is the <input type=checkbox> inside .pr-observe-switch. Data-attrs
 // live on the input so this handler keeps reading them directly; visual

package/dashboard.js

@@ -77,9 +77,26 @@ const TITLE_SUFFIX = IS_DEV_MODE ? ' [DEV]' : '';
   }
 })();
 
-const PORT = parseInt(process.env.PORT || process.argv[2]) || 7331;
 let CONFIG = queries.getConfig();
 let PROJECTS = _getProjects(CONFIG);
+// PORT resolution chain (W-mq5nwl9l): explicit CLI arg (argv[2]) > env
+// MINIONS_DASHBOARD_PORT / PORT > config.engine.dashboardPort > default 7331.
+// REQUESTED_PORT is the user/operator intent; BOUND_PORT may differ after an
+// EADDRINUSE retry. Test-mode badge logic stays anchored to REQUESTED_PORT so
+// an accidental port collision (7331 already in use) does NOT cause the live
+// dashboard to wear the "TEST" badge. `PORT` is kept as an alias for the
+// bound port — every existing site that read PORT (banner, dashboardPort
+// substitution for CC, etc.) now sees the actually-bound value.
+const REQUESTED_PORT = (() => {
+  const argv = parseInt(process.argv[2], 10);
+  if (Number.isInteger(argv) && argv > 0 && argv <= 65535) return argv;
+  const envP = parseInt(process.env.MINIONS_DASHBOARD_PORT || process.env.PORT || '', 10);
+  if (Number.isInteger(envP) && envP > 0 && envP <= 65535) return envP;
+  const cfgP = parseInt(CONFIG && CONFIG.engine && CONFIG.engine.dashboardPort, 10);
+  if (Number.isInteger(cfgP) && cfgP > 0 && cfgP <= 65535) return cfgP;
+  return shared.DEFAULT_DASHBOARD_PORT;
+})();
+let PORT = REQUESTED_PORT;
 const CONFIG_PATH = path.join(MINIONS_DIR, 'config.json');
 const PINNED_PATH = path.join(MINIONS_DIR, 'pinned.md');
 const PINNED_DEFAULT_CONTENT = '# Pinned Context\n\nCritical notes visible to all agents.';
@@ -822,7 +839,7 @@ function collectArchivedWorkItems(minionsDir = MINIONS_DIR, projects = PROJECTS)
   }
   return archived;
 }
-function linkPullRequestForTracking({ url, title, project: projectName, autoObserve, context, workItemId }, config = CONFIG, options = {}) {
+function linkPullRequestForTracking({ url, title, project: projectName, contextOnly, autoObserve, context, workItemId }, config = CONFIG, options = {}) {
   if (!url) {
     const err = new Error('url required');
     err.statusCode = 400;
@@ -838,6 +855,12 @@ function linkPullRequestForTracking({ url, title, project: projectName, autoObse
   const linkedWorkItemId = getWorkItemIdFromPrLinkContext(context, workItemId);
   const contextText = typeof context === 'string' ? context : (context == null ? '' : JSON.stringify(context));
   const metadata = normalizePrMetadata(options.metadata);
+  // W-mq5s5ttx000j7ab8-c: canonical `contextOnly` field with `autoObserve`
+  // deprecated alias. Explicit canonical wins; otherwise fall back to the
+  // alias (autoObserve:true → contextOnly:false); otherwise default false.
+  const resolvedContextOnly = typeof contextOnly === 'boolean'
+    ? contextOnly
+    : (autoObserve === undefined ? false : !autoObserve);
   const result = shared.upsertPullRequestRecord(prPath, {
     id: prId,
     prNumber: parseInt(prNum, 10) || null,
@@ -850,9 +873,7 @@ function linkPullRequestForTracking({ url, title, project: projectName, autoObse
     created: new Date().toISOString(),
     url,
     prdItems: linkedWorkItemId ? [linkedWorkItemId] : [],
-    _manual: true,
-    _contextOnly: !autoObserve,
-    _autoObserve: !!autoObserve,
+    contextOnly: resolvedContextOnly,
     _context: contextText,
     _projectResolution: projectResolution,
   }, {
@@ -863,9 +884,11 @@ function linkPullRequestForTracking({ url, title, project: projectName, autoObse
 }
 
 // W-mpmwxkzm0009ba0b — Per-row auto-observe toggle backing helper for
-// POST /api/pull-requests/observe. Flips `_contextOnly` / `_autoObserve` on
-// an existing tracked PR record under a lock (per CLAUDE.md mutate convention).
+// POST /api/pull-requests/observe. Flips canonical `contextOnly` on an
+// existing tracked PR record under a lock (per CLAUDE.md mutate convention).
 // Body shape: { host: 'github'|'ado', slug, number, observe: boolean }.
+// The public `observe` body param is preserved for backward compatibility
+// (W-mq5s5ttx000j7ab8-c); internally it maps to `contextOnly = !observe`.
 // Returns the updated record + the PR path that was touched. Throws an
 // Error with `statusCode` for the route handler to map to an HTTP status.
 function updatePullRequestObserveFlag({ host, slug, number, observe } = {}, config = CONFIG, minionsDir = MINIONS_DIR) {
@@ -907,9 +930,8 @@ function updatePullRequestObserveFlag({ host, slug, number, observe } = {}, conf
     shared.mutatePullRequests(prPath, (prs) => {
       const pr = prs.find(p => p && p.id === canonicalId);
       if (!pr) return prs;
-      pr._contextOnly = !observe;
-      pr._autoObserve = !!observe;
-      updated = { id: pr.id, _contextOnly: pr._contextOnly, _autoObserve: pr._autoObserve };
+      pr.contextOnly = !observe;
+      updated = { id: pr.id, contextOnly: pr.contextOnly };
       updatedPath = prPath;
       return prs;
     });
@@ -1052,16 +1074,21 @@ function resolvePlanPath(file) {
 }
 
 // Test-mode banner: surfaced in <title> + <h1> + body class when the dashboard
-// is started under MINIONS_TEST_DIR or on a non-default port. Makes it visually
-// obvious that the user is looking at a sandboxed instance, not their live
-// fleet — prevents acting on test fixtures by mistake.
+// is started under MINIONS_TEST_DIR or on a non-default REQUESTED port. Makes
+// it visually obvious that the user is looking at a sandboxed instance, not
+// their live fleet — prevents acting on test fixtures by mistake. Anchored to
+// REQUESTED_PORT (not the bound PORT) so an EADDRINUSE auto-fallback from
+// 7331 → 7332 does NOT promote a live dashboard to TEST-mode.
 function _isTestMode() {
-  return !!process.env.MINIONS_TEST_DIR || (typeof PORT === 'number' && PORT !== 7331);
+  return !!process.env.MINIONS_TEST_DIR
+    || (typeof REQUESTED_PORT === 'number' && REQUESTED_PORT !== shared.DEFAULT_DASHBOARD_PORT);
 }
 
 function _testBadgeLabel() {
   if (process.env.MINIONS_TEST_DIR) return 'TEST';
-  if (typeof PORT === 'number' && PORT !== 7331) return `TEST :${PORT}`;
+  if (typeof REQUESTED_PORT === 'number' && REQUESTED_PORT !== shared.DEFAULT_DASHBOARD_PORT) {
+    return `TEST :${REQUESTED_PORT}`;
+  }
   return '';
 }
 
@@ -11351,7 +11378,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // /api/prd/regenerate removed — use /api/plans/approve which does diff-aware update
 
     // Agents
-    { method: 'POST', path: '/api/pull-requests/link', desc: 'Manually link an external PR for tracking', params: 'url, title?, project?, autoObserve?, context?, workItemId?', handler: async (req, res) => {
+    { method: 'POST', path: '/api/pull-requests/link', desc: 'Manually link an external PR for tracking', params: 'url, title?, project?, contextOnly?, autoObserve? (deprecated alias for !contextOnly), context?, workItemId?', handler: async (req, res) => {
       const body = await readBody(req);
       const { url } = body;
       if (!url) return jsonReply(res, 400, { error: 'url required' });
@@ -11448,13 +11475,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       })();
     }},
 
-    { method: 'POST', path: '/api/pull-requests/observe', desc: 'Toggle auto-observe (_contextOnly flag) on a tracked PR', params: 'host (github|ado), slug, number, observe (boolean)', handler: async (req, res) => {
+    { method: 'POST', path: '/api/pull-requests/observe', desc: 'Toggle canonical contextOnly flag on a tracked PR (public `observe` body param is preserved as the inverse for backward compat)', params: 'host (github|ado), slug, number, observe (boolean)', handler: async (req, res) => {
       const body = await readBody(req);
       reloadConfig();
       try {
         const result = updatePullRequestObserveFlag(body, CONFIG);
         invalidateStatusCache();
-        return jsonReply(res, 200, { ok: true, ...result, observe: !result._contextOnly });
+        return jsonReply(res, 200, { ok: true, ...result, observe: !result.contextOnly });
       } catch (e) {
         return jsonReply(res, e.statusCode || 400, { error: e.message });
       }
@@ -12279,7 +12306,54 @@ if (require.main === module) {
       console.warn(`[boot] pre-warm git status failed: ${e && e.message}`);
     }
 
-    server.listen(PORT, '127.0.0.1', () => {
+    // Listen with EADDRINUSE auto-fallback (W-mq5nwl9l). Tries REQUESTED_PORT
+    // first; on EADDRINUSE scans upward through shared.DASHBOARD_PORT_SCAN_MAX
+    // ports and binds to the first free one. The actually-bound port is
+    // written to engine/dashboard-port.json as soon as listen resolves so
+    // every downstream consumer (CLI status/dash/restart, cli-api-client,
+    // supervisor) discovers it instead of guessing 7331. The original
+    // server.on('error') one-shot exit is replaced by the retry loop — only
+    // non-EADDRINUSE errors abort.
+    const maxScan = shared.DASHBOARD_PORT_SCAN_MAX || 100;
+    let listenErr = null;
+    for (let attempt = 0; attempt < maxScan; attempt++) {
+      const tryPort = REQUESTED_PORT + attempt;
+      try {
+        await new Promise((resolve, reject) => {
+          const onError = (e) => { server.removeListener('listening', onListen); reject(e); };
+          const onListen = () => { server.removeListener('error', onError); resolve(); };
+          server.once('error', onError);
+          server.once('listening', onListen);
+          server.listen(tryPort, '127.0.0.1');
+        });
+        if (tryPort !== REQUESTED_PORT) {
+          console.log(`[dashboard] requested port ${REQUESTED_PORT} in use, bound to ${tryPort}`);
+        }
+        PORT = tryPort;
+        listenErr = null;
+        break;
+      } catch (e) {
+        listenErr = e;
+        if (e && e.code !== 'EADDRINUSE') break;
+        // Loop to next candidate port.
+      }
+    }
+    if (listenErr) {
+      if (listenErr.code === 'EADDRINUSE') {
+        console.error(`\n  No free port in [${REQUESTED_PORT}..${REQUESTED_PORT + maxScan - 1}]. Free one and retry.\n`);
+      } else {
+        console.error(listenErr);
+      }
+      process.exit(1);
+    }
+
+    // Persist the actually-bound port for every downstream consumer.
+    try {
+      shared.writeDashboardPortFile({ port: PORT, pid: process.pid, minionsHome: MINIONS_DIR });
+    } catch (e) {
+      console.warn(`[dashboard] could not write dashboard-port.json: ${e && e.message}`);
+    }
+
     console.log(`\n  Minions Mission Control`);
     console.log(`  -----------------------------------`);
     console.log(`  http://localhost:${PORT}`);
@@ -12358,20 +12432,14 @@ if (require.main === module) {
       }
     }, 30000).unref();
     console.log(`  Engine watchdog: active (checks every 30s)`);
-  });
   })();
 
-  server.on('error', e => {
-    if (e.code === 'EADDRINUSE') {
-      console.error(`\n  Port ${PORT} already in use. Kill the existing process or change PORT.\n`);
-    } else {
-      console.error(e);
-    }
-    process.exit(1);
-  });
-
-  // ── Graceful shutdown: flush debounced writes ──────────────────────────────
-  server.on('close', () => flushPendingDocSessions());
-  process.on('SIGTERM', () => { flushPendingDocSessions(); process.exit(0); });
-  process.on('SIGINT', () => { flushPendingDocSessions(); process.exit(0); });
+  // ── Graceful shutdown: flush debounced writes + clear runtime port file ──
+  function _gracefulShutdown() {
+    try { flushPendingDocSessions(); } catch {}
+    try { shared.clearDashboardPortFile(MINIONS_DIR); } catch {}
+  }
+  server.on('close', () => _gracefulShutdown());
+  process.on('SIGTERM', () => { _gracefulShutdown(); process.exit(0); });
+  process.on('SIGINT', () => { _gracefulShutdown(); process.exit(0); });
 }