@blackbelt-technology/pi-agent-dashboard 0.4.4 → 0.4.5

package/packages/shared/src/__tests__/no-bash-on-windows.test.ts

@@ -0,0 +1,304 @@
+/**
+ * Repo-level invariant: no GitHub Actions step that can run on a
+ * Windows runner SHALL declare `shell: bash`. Bash on Windows runners
+ * is provided by Git for Windows' MSYS2 layer, which translates Win32
+ * paths to POSIX form (`D:\a\...` → `/d/a/...`) for any bash variable
+ * produced by `pwd`, `dirname`, etc. That POSIX-form string is invisible
+ * to native binaries (notably `node.exe`) when embedded in arguments,
+ * producing a recurring class of `MODULE_NOT_FOUND` / `ENOENT` bugs.
+ *
+ * Cross-OS build orchestration MUST be expressed in `.mjs` scripts
+ * invoked by `node`. POSIX-only steps MAY use `shell: bash` provided
+ * they are gated by an `if:` filter that excludes Windows. Windows-only
+ * steps MAY use `shell: pwsh`.
+ *
+ * If this test fails, port the offending step to `node` (cross-OS) or
+ * split it per-OS (`bash` for POSIX, `pwsh` for Windows) and gate each
+ * arm with an `if:` filter on `matrix.platform`.
+ *
+ * See change: eliminate-bash-on-windows-runners.
+ *
+ * Supported `if:` grammar (anything else fails closed → treated as
+ * Windows-reachable, forcing the contributor to write a recognised form
+ * or extend this evaluator):
+ *
+ *   - bare boolean       : `true` / `false`
+ *   - matrix comparison  : `matrix.platform == 'X'`, `matrix.platform != 'X'`
+ *                          `matrix.arch == 'X'`, `matrix.arch != 'X'`
+ *   - conjunction        : `<expr> && <expr>`
+ *   - disjunction        : `<expr> || <expr>`
+ *   - negation           : `!(<expr>)`
+ *   - parens             : `(<expr>)` are stripped
+ *
+ * The grammar is small because this repo's workflow YAML is small and
+ * stable; if a future workflow needs richer `if:` expressions, extend
+ * the evaluator (and the test grammar comment) rather than expand the
+ * lint's allowlist.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
+
+/** Workflow files this lint scans. */
+const WORKFLOW_FILES: readonly string[] = [
+  ".github/workflows/publish.yml",
+  ".github/workflows/ci.yml",
+];
+
+/** A platform value present in `matrix.platform` of any job we care about. */
+const WINDOWS_PLATFORMS = new Set(["win32"]);
+
+/**
+ * Extract the YAML body of a top-level job by name. Returns the lines
+ * between `  <jobName>:` and the next sibling-indent (`  `) job, or EOF.
+ *
+ * Same pattern as `publish-workflow-contract.test.ts` —
+ * regex-based extraction, no YAML library dep, tolerates the stable
+ * 2-space indented format used in this repo.
+ */
+function extractJobBlock(yaml: string, jobName: string): string | null {
+  const lines = yaml.split("\n");
+  const headerRe = new RegExp(`^  ${jobName}:\\s*$`);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (headerRe.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  const siblingRe = /^  [a-z][a-z0-9-]*:\s*$/;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (siblingRe.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/** Pull the matrix.include[*].platform values from a job block. */
+function extractMatrixPlatforms(jobBlock: string): string[] {
+  // Each matrix entry starts with `- os:` at a deeper indent. Capture
+  // the `platform:` line that sibling-belongs to it (the next platform
+  // line after each `- os:`).
+  const out: string[] = [];
+  const lines = jobBlock.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s+-\s*os:/.test(lines[i])) continue;
+    // Look at the next ~6 lines for a sibling `platform:` key.
+    for (let j = i + 1; j < Math.min(i + 8, lines.length); j++) {
+      if (/^\s+-\s*os:/.test(lines[j])) break; // next entry
+      const m = lines[j].match(/^\s+platform:\s*['"]?([\w-]+)['"]?\s*$/);
+      if (m) {
+        out.push(m[1]);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Step-level extraction. Each step starts with `      - name:` (6-space
+ * indent under `    steps:`). For each step we capture the line number,
+ * the `name:` value, the `shell:` value (if any), and the `if:` value
+ * (if any).
+ */
+interface Step {
+  line: number; // 1-indexed
+  name: string;
+  shell: string | null;
+  if_: string | null;
+}
+
+function extractSteps(jobBlock: string, baseLine: number): Step[] {
+  const lines = jobBlock.split("\n");
+  const steps: Step[] = [];
+  let cur: Step | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const stepHeader = line.match(/^      -\s*name:\s*(.+?)\s*$/);
+    if (stepHeader) {
+      if (cur) steps.push(cur);
+      cur = {
+        line: baseLine + i,
+        name: stepHeader[1].replace(/^['"]|['"]$/g, ""),
+        shell: null,
+        if_: null,
+      };
+      continue;
+    }
+    if (cur) {
+      // 8-space indented sibling keys of the step.
+      const sh = line.match(/^        shell:\s*(\S+)\s*$/);
+      if (sh) {
+        cur.shell = sh[1];
+        continue;
+      }
+      const ifM = line.match(/^        if:\s*(.+?)\s*$/);
+      if (ifM) {
+        // Strip a single layer of YAML-double-quote wrapping, e.g.
+        //   if: "!(matrix.platform == 'win32' && matrix.arch == 'arm64')"
+        // Single quotes inside the expression must be preserved.
+        let v = ifM[1];
+        if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+          v = v.slice(1, -1);
+        }
+        cur.if_ = v;
+        continue;
+      }
+      // A step body line at any non-step-header indent — keep accumulating.
+    }
+  }
+  if (cur) steps.push(cur);
+  return steps;
+}
+
+/**
+ * Pure evaluator: does an `if:` expression evaluate to `true` for ANY
+ * concrete (platform, arch) tuple in {windows} × {x64, arm64}? If yes,
+ * the step is reachable on Windows.
+ *
+ * Returns true if the expression is unrecognised (fail closed — force
+ * the contributor to write a recognisable form or extend the grammar).
+ */
+function reachableOnWindows(ifExpr: string | null, archs: string[]): boolean {
+  if (ifExpr == null || ifExpr === "") return true;
+  for (const arch of archs) {
+    for (const plat of WINDOWS_PLATFORMS) {
+      try {
+        if (evaluate(ifExpr, { platform: plat, arch })) return true;
+      } catch {
+        // Unrecognised — fail closed
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Evaluate a small grammar of `matrix.X op 'literal'` boolean expressions.
+ * Throws on unrecognised input.
+ */
+function evaluate(
+  expr: string,
+  ctx: { platform: string; arch: string },
+): boolean {
+  const e = expr.trim();
+  if (e === "true") return true;
+  if (e === "false") return false;
+
+  // Negation: `!(...)` — must have matching outer parens
+  if (e.startsWith("!(") && e.endsWith(")")) {
+    return !evaluate(e.slice(2, -1), ctx);
+  }
+
+  // Strip outer parens
+  if (e.startsWith("(") && e.endsWith(")") && balanced(e.slice(1, -1))) {
+    return evaluate(e.slice(1, -1), ctx);
+  }
+
+  // Top-level `&&` or `||` — split at the first unparenthesized operator
+  const splitAt = (op: string): [string, string] | null => {
+    let depth = 0;
+    for (let i = 0; i < e.length - op.length + 1; i++) {
+      if (e[i] === "(") depth += 1;
+      else if (e[i] === ")") depth -= 1;
+      else if (depth === 0 && e.slice(i, i + op.length) === op) {
+        return [e.slice(0, i).trim(), e.slice(i + op.length).trim()];
+      }
+    }
+    return null;
+  };
+  const andSplit = splitAt("&&");
+  if (andSplit) return evaluate(andSplit[0], ctx) && evaluate(andSplit[1], ctx);
+  const orSplit = splitAt("||");
+  if (orSplit) return evaluate(orSplit[0], ctx) || evaluate(orSplit[1], ctx);
+
+  // Atomic: `matrix.<key> <op> '<literal>'`
+  const atom = e.match(
+    /^matrix\.(platform|arch)\s*(==|!=)\s*['"]([^'"]+)['"]$/,
+  );
+  if (atom) {
+    const [, key, op, lit] = atom;
+    const ctxVal = key === "platform" ? ctx.platform : ctx.arch;
+    return op === "==" ? ctxVal === lit : ctxVal !== lit;
+  }
+
+  throw new Error(`unrecognised if-expression: ${expr}`);
+}
+
+function balanced(s: string): boolean {
+  let depth = 0;
+  for (const c of s) {
+    if (c === "(") depth += 1;
+    else if (c === ")") depth -= 1;
+    if (depth < 0) return false;
+  }
+  return depth === 0;
+}
+
+describe("no `shell: bash` step is reachable on a Windows runner", () => {
+  for (const wf of WORKFLOW_FILES) {
+    const abs = path.join(REPO_ROOT, wf);
+    if (!fs.existsSync(abs)) continue;
+    const yaml = fs.readFileSync(abs, "utf8");
+
+    // Find every job that has a Windows-able matrix.
+    const jobMatches = [...yaml.matchAll(/^  ([a-z][a-z0-9-]*):\s*$/gm)];
+    const jobNames = jobMatches.map((m) => m[1]);
+
+    for (const jobName of jobNames) {
+      const block = extractJobBlock(yaml, jobName);
+      if (!block) continue;
+
+      const platforms = extractMatrixPlatforms(block);
+      const hasWindows = platforms.some((p) => WINDOWS_PLATFORMS.has(p));
+      // Also count jobs whose runs-on directly names windows-*
+      const directWindows = /runs-on:\s*['"]?windows-[\w.-]+['"]?/.test(block);
+      if (!hasWindows && !directWindows) continue;
+
+      // Compute the matrix archs available; default to ['x64','arm64'].
+      const archs = [
+        ...new Set(
+          [...block.matchAll(/arch:\s*['"]?([\w-]+)['"]?/g)].map((m) => m[1]),
+        ),
+      ];
+      const archList = archs.length > 0 ? archs : ["x64"];
+
+      const baseLine = yaml.slice(0, yaml.indexOf(block)).split("\n").length;
+      const steps = extractSteps(block, baseLine);
+
+      it(`${wf} — job '${jobName}': no shell:bash steps reachable on Windows`, () => {
+        const offenders: string[] = [];
+        for (const s of steps) {
+          if (s.shell !== "bash") continue;
+          if (reachableOnWindows(s.if_, archList)) {
+            offenders.push(
+              `  ${wf}:${s.line} step '${s.name}' uses shell: bash` +
+                ` and is reachable on Windows (if: ${s.if_ ?? "<none>"})`,
+            );
+          }
+        }
+        if (offenders.length > 0) {
+          throw new Error(
+            `Found ${offenders.length} bash-on-Windows step(s).\n` +
+              offenders.join("\n") +
+              `\n\nPort each offender to .mjs (cross-OS) OR split per-OS ` +
+              `(bash gated by 'matrix.platform != \\'win32\\'' for POSIX, ` +
+              `pwsh for Windows).\n` +
+              `See change: eliminate-bash-on-windows-runners.`,
+          );
+        }
+        expect(offenders).toEqual([]);
+      });
+    }
+  }
+});

package/packages/shared/src/__tests__/no-hardcoded-node-modules-paths.test.ts

@@ -72,7 +72,7 @@ const ALLOWLIST: readonly string[] = [
  * The scope is intentionally narrow: only the build-time sites that the
  * `register-build-time-tools` change migrated, plus the postinstall
  * scripts that mirror the registry's `bare-import` semantics. Bundle /
- * Docker entrypoint scripts (`bundle-server.sh`, `docker-make.sh`,
+ * Docker entrypoint scripts (`bundle-server.mjs`, `docker-make.sh`,
  * `test-electron-install-inner.sh`, etc.) are NOT in scope: those
  * operate on a known WORKDIR with deterministic node_modules layout
  * inside the build image and are not affected by host-side hoisting.

package/packages/shared/src/__tests__/node-spawn-jiti-contract.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Pin Defect 2's jiti version contract for `shouldUrlWrapEntry()`.
+ *
+ * The Windows-non-tsx arm in `platform/node-spawn.ts::shouldUrlWrapEntry`
+ * assumes the jiti loader is from `@mariozechner/pi-coding-agent@0.70.x`
+ * (jiti 2.x with the file:// URL handling fix). Newer pi versions ship
+ * a different jiti that breaks this contract.
+ *
+ * This test ensures:
+ *   1. The offline-cacache pin in `packages/electron/offline-packages.json`
+ *      stays at `0.70.x` (the supported range). A bump elsewhere fires
+ *      this test and forces the contributor to either:
+ *        - re-verify the contract on Windows
+ *        - add a per-jiti-version branch
+ *        - switch the bundled loader to tsx
+ *   2. The `shouldUrlWrapEntry` header comment documents the contract
+ *      so future contributors discover the constraint at the call site.
+ *
+ * See change: fix-electron-windows-installer-and-server-bootstrap (Defect 2).
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
+const OFFLINE_PACKAGES_PATH = path.join(
+  REPO_ROOT,
+  "packages",
+  "electron",
+  "offline-packages.json",
+);
+const NODE_SPAWN_PATH = path.join(
+  REPO_ROOT,
+  "packages",
+  "shared",
+  "src",
+  "platform",
+  "node-spawn.ts",
+);
+
+describe("jiti version contract for shouldUrlWrapEntry", () => {
+  it("offline-packages.json pins @mariozechner/pi-coding-agent at a 0.70.x version", () => {
+    const raw = fs.readFileSync(OFFLINE_PACKAGES_PATH, "utf8");
+    const manifest = JSON.parse(raw) as {
+      packages: { name: string; version: string }[];
+    };
+    const piEntry = manifest.packages.find(
+      (p) => p.name === "@mariozechner/pi-coding-agent",
+    );
+    if (!piEntry) {
+      throw new Error(
+        "@mariozechner/pi-coding-agent not found in offline-packages.json. " +
+          "The offline cacache must include pi-coding-agent. " +
+          "See change: fix-electron-windows-installer-and-server-bootstrap (Defect 2).",
+      );
+    }
+    if (!piEntry.version.startsWith("0.70.")) {
+      throw new Error(
+        `pi-coding-agent pinned at ${piEntry.version}, but ` +
+          `shouldUrlWrapEntry()'s Windows-non-tsx arm only supports 0.70.x. ` +
+          `Newer jiti versions (e.g. 2.6.5 in pi 0.71.x) misnormalize ` +
+          `file:/// URL entries on Windows. Either re-verify the contract, ` +
+          `add a per-jiti-version branch in shouldUrlWrapEntry(), or switch ` +
+          `the bundled loader to tsx. See change: ` +
+          `fix-electron-windows-installer-and-server-bootstrap (Defect 2).`,
+      );
+    }
+    expect(piEntry.version).toMatch(/^0\.70\./);
+  });
+
+  it("node-spawn.ts source contains the documented JITI VERSION CONTRACT block", () => {
+    const source = fs.readFileSync(NODE_SPAWN_PATH, "utf8");
+
+    // Contract block markers
+    expect(source).toContain("JITI VERSION CONTRACT");
+    expect(source).toContain("0.70.x");
+
+    // Version drift markers (at least one of these identifies the broken jiti)
+    const hasVersionDriftMarker =
+      source.includes("0.71") || source.includes("2.6.5");
+    if (!hasVersionDriftMarker) {
+      throw new Error(
+        "shouldUrlWrapEntry() docstring is missing the version-drift marker. " +
+          "It must mention either '0.71' or '2.6.5' so contributors can " +
+          "identify the known-broken jiti versions. See change: " +
+          "fix-electron-windows-installer-and-server-bootstrap (Defect 2).",
+      );
+    }
+
+    // Remediation guidance markers (at least one)
+    const hasRemediationGuidance =
+      /re-verify/i.test(source) ||
+      /per-version branch/i.test(source) ||
+      /per-jiti-version/i.test(source) ||
+      /switch.*to tsx/i.test(source);
+    if (!hasRemediationGuidance) {
+      throw new Error(
+        "shouldUrlWrapEntry() docstring is missing remediation guidance. " +
+          "It must mention at least one of: re-verify, per-version branch, " +
+          "or switch to tsx. See change: " +
+          "fix-electron-windows-installer-and-server-bootstrap (Defect 2).",
+      );
+    }
+  });
+});

package/packages/shared/src/__tests__/protocol.test.ts

@@ -100,6 +100,17 @@ describe("Protocol message serialization round-trip", () => {
         requestId: "req-2",
         cancelled: true,
       },
+      // See change: fix-restart-bridge-auto-start-race
+      {
+        type: "server_restarting",
+        reason: "restart",
+        quiesceMs: 5000,
+      },
+      {
+        type: "server_restarting",
+        reason: "shutdown",
+        quiesceMs: 60000,
+      },
     ];
 
     for (const msg of messages) {

package/packages/shared/src/__tests__/publish-workflow-contract.test.ts

@@ -121,3 +121,95 @@ describe("publish.yml — electron job dependency-graph contract", () => {
     expect(m[1]).toBe("false");
   });
 });
+
+// ── Prerelease safety contract ───────────────────────────────────────────────────────
+// Prerelease versions (e.g. `0.4.5-rc.1`) MUST publish to npm under the
+// `next` dist-tag and surface as GitHub `prerelease: true` Releases. The
+// single source of truth is the `prepare` job's computed `is_prerelease`
+// output. See change: eliminate-bash-on-windows-runners (D6).
+
+describe("publish.yml — prerelease safety contract", () => {
+  const yaml = fs.readFileSync(WORKFLOW_PATH, "utf8");
+  const prepareBlock = extractJobBlock(yaml, "prepare");
+  const publishBlock = extractJobBlock(yaml, "publish");
+  const ghReleaseBlock = extractJobBlock(yaml, "github-release");
+
+  it("prepare job's outputs block declares `is_prerelease`", () => {
+    // Match the `outputs:` block under `prepare`. Accept any whitespace
+    // alignment after the colon, but the key must be present and wired
+    // to a step output.
+    const m = prepareBlock.match(/^\s{4}outputs:\s*\n((?:\s{6}\S.*\n)+)/m);
+    if (!m) {
+      throw new Error(
+        "prepare job has no `outputs:` block. Required to expose\n" +
+          "`is_prerelease` to downstream jobs. See change:\n" +
+          "eliminate-bash-on-windows-runners (D6).\n" +
+          "prepare block:\n" +
+          prepareBlock,
+      );
+    }
+    const block = m[1];
+    if (!/is_prerelease:\s*\$\{\{\s*steps\.[A-Za-z_]+\.outputs\.is_prerelease\s*\}\}/.test(block)) {
+      throw new Error(
+        "prepare job's outputs block must declare `is_prerelease` wired to a\n" +
+          "step output (e.g. `is_prerelease: ${{ steps.resolve.outputs.is_prerelease }}`).\n" +
+          "Without this, downstream `publish` and `github-release` jobs cannot\n" +
+          "distinguish prereleases from stable versions. See change:\n" +
+          "eliminate-bash-on-windows-runners (D6).\n" +
+          "outputs block was:\n" +
+          block,
+      );
+    }
+    expect(block).toMatch(/is_prerelease:/);
+  });
+
+  it("publish job uses `--tag next` conditionally on is_prerelease", () => {
+    // Two requirements:
+    //   1. The literal string `--tag next` appears in the publish loop body.
+    //   2. There's a guard checking `is_prerelease == "true"` (or the bash
+    //      equivalent `[ "$PRERELEASE" = "true" ]`).
+    if (!/--tag next/.test(publishBlock)) {
+      throw new Error(
+        "publish job is missing the `--tag next` literal. Prereleases must\n" +
+          "publish under the `next` dist-tag so consumers running plain\n" +
+          "`npm install <pkg>` keep getting the last stable release. See\n" +
+          "change: eliminate-bash-on-windows-runners (D6).",
+      );
+    }
+    const hasGuard =
+      /is_prerelease\s*==\s*['"]true['"]/.test(publishBlock) ||
+      /\[\s*"\$PRERELEASE"\s*=\s*"true"\s*\]/.test(publishBlock) ||
+      /PRERELEASE.*=.*"true"/.test(publishBlock);
+    if (!hasGuard) {
+      throw new Error(
+        "publish job uses `--tag next` but lacks the prerelease guard. The\n" +
+          "`--tag next` argument MUST be conditional on the `is_prerelease`\n" +
+          "output (e.g. `if [ \"$PRERELEASE\" = \"true\" ]; then ...`).\n" +
+          "Otherwise stable releases would also publish to `next`. See\n" +
+          "change: eliminate-bash-on-windows-runners (D6).",
+      );
+    }
+    expect(publishBlock).toContain("--tag next");
+  });
+
+  it("github-release job sets prerelease from is_prerelease", () => {
+    // softprops/action-gh-release accepts `prerelease: <bool>` in its
+    // `with:` block. The value MUST be derived from the prepare job's
+    // `is_prerelease` output (literal-string comparison required because
+    // GitHub Actions stringifies job outputs).
+    if (
+      !/prerelease:\s*\$\{\{\s*needs\.prepare\.outputs\.is_prerelease\s*==\s*['"]true['"]\s*\}\}/
+        .test(ghReleaseBlock)
+    ) {
+      throw new Error(
+        "github-release job's `softprops/action-gh-release` step must set\n" +
+          "`prerelease: ${{ needs.prepare.outputs.is_prerelease == 'true' }}`\n" +
+          "in its `with:` block. Otherwise rc tags surface as stable Releases.\n" +
+          "See change: eliminate-bash-on-windows-runners (D6).\n" +
+          "github-release block was:\n" +
+          ghReleaseBlock,
+      );
+    }
+    expect(ghReleaseBlock).toMatch(/prerelease:.*is_prerelease.*true/);
+  });
+});

package/packages/shared/src/browser-protocol.ts

@@ -726,6 +726,29 @@ export interface RequestRolesBrowserMessage {
  * which re-emits as `pi.events.emit(event, { ...params, action, _reply })`.
  * See change: add-extension-ui-modal.
  */
+/**
+ * Browser → server: declares which session a browser is currently displaying
+ * (typically when the URL is `/session/:id`). The server uses this to gate
+ * unread-trigger evaluation and to clear the unread bit when an unread session
+ * is opened. Browsers SHALL re-send `session_view` for the currently-displayed
+ * session on every WebSocket reconnect so server-side state stays coherent.
+ * See change: session-card-unread-stripes.
+ */
+export interface SessionViewBrowserMessage {
+  type: "session_view";
+  sessionId: string;
+}
+
+/**
+ * Browser → server: declares the browser is no longer displaying the session
+ * (e.g. user navigated away from `/session/:id`).
+ * See change: session-card-unread-stripes.
+ */
+export interface SessionUnviewBrowserMessage {
+  type: "session_unview";
+  sessionId: string;
+}
+
 export interface UiManagementBrowserMessage {
   type: "ui_management";
   sessionId: string;
@@ -775,4 +798,6 @@ export type BrowserToServerMessage =
   | RolePresetDeleteBrowserMessage
   | RequestRolesBrowserMessage
   | UiManagementBrowserMessage
+  | SessionViewBrowserMessage
+  | SessionUnviewBrowserMessage
   | KillProcessBrowserMessage;

package/packages/shared/src/config.ts

@@ -11,6 +11,39 @@ export const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
 
 export type SpawnStrategy = "tmux" | "headless";
 
+/**
+ * Policy applied when a bridge re-registers a session after a dashboard
+ * restart (i.e. the `session_register` carries `registerReason: "reattach"`).
+ *
+ * - `"always"` (default) — unconditionally move the session to the front
+ *   of `sessionOrder` for its cwd.
+ * - `"streaming-only"` — only move-to-front when the session's status is
+ *   currently `"streaming"`.
+ * - `"preserve"` — leave `sessionOrder` untouched (legacy behavior).
+ *
+ * See change: reattach-move-to-front.
+ */
+export type ReattachPlacement = "preserve" | "streaming-only" | "always";
+
+const VALID_REATTACH_PLACEMENTS: ReattachPlacement[] = [
+  "preserve",
+  "streaming-only",
+  "always",
+];
+
+export const DEFAULT_REATTACH_PLACEMENT: ReattachPlacement = "always";
+
+/**
+ * Validate a raw value against the {@link ReattachPlacement} union.
+ * Anything outside the union (including `undefined`, numbers, objects)
+ * falls back to {@link DEFAULT_REATTACH_PLACEMENT}.
+ */
+export function parseReattachPlacement(raw: unknown): ReattachPlacement {
+  return typeof raw === "string" && (VALID_REATTACH_PLACEMENTS as string[]).includes(raw)
+    ? (raw as ReattachPlacement)
+    : DEFAULT_REATTACH_PLACEMENT;
+}
+
 export interface AuthProviderConfig {
   clientId: string;
   clientSecret: string;
@@ -111,6 +144,12 @@ export interface DashboardConfig {
   lastServer?: string;
   /** Whether the server was launched by the Electron app */
   electronMode: boolean;
+  /**
+   * Policy applied when the bridge reattaches after a dashboard restart.
+   * See {@link ReattachPlacement}. Default `"always"`.
+   * See change: reattach-move-to-front.
+   */
+  reattachPlacement: ReattachPlacement;
   /** Persisted list of known remote servers */
   knownServers: KnownServer[];
   /**
@@ -148,6 +187,7 @@ const DEFAULTS: DashboardConfig = {
   cors: { allowedOrigins: [] },
   electronMode: false,
   knownServers: [],
+  reattachPlacement: DEFAULT_REATTACH_PLACEMENT,
 };
 
 /**
@@ -343,6 +383,7 @@ export function loadConfig(): DashboardConfig {
       ...(typeof parsed.lastServer === "string" ? { lastServer: parsed.lastServer } : {}),
       electronMode: parsed.electronMode === true,
       knownServers: parseKnownServers(parsed.knownServers),
+      reattachPlacement: parseReattachPlacement(parsed.reattachPlacement),
       plugins: parsePluginsConfig(parsed.plugins),
     };
 

package/packages/shared/src/mdns-discovery.ts

@@ -103,10 +103,41 @@ function getLocalAddresses(): Set<string> {
   return addresses;
 }
 
+/**
+ * Pick the best host string for a discovered service.
+ *
+ * Bonjour can advertise `service.host` as the OS computer-name (e.g. macOS
+ * "MacBook 242") which contains characters that are not valid in a DNS
+ * hostname — so the browser cannot resolve it. When that happens we fall back
+ * to `service.addresses` (preferring IPv4 over IPv6) so the saved entry is
+ * actually reachable.
+ *
+ * Rule: a host is DNS-safe iff it matches `[A-Za-z0-9.-]+` and does not
+ * begin or end with a hyphen (RFC 1123, relaxed for the `.local` suffix).
+ */
+export function pickBestHost(service: Pick<Service, "host" | "addresses">): string {
+  const host = service.host;
+  const isDnsSafe =
+    typeof host === "string" &&
+    host.length > 0 &&
+    /^[A-Za-z0-9.-]+$/.test(host) &&
+    !host.startsWith("-") &&
+    !host.endsWith("-");
+  if (isDnsSafe) return host;
+
+  const addresses = service.addresses ?? [];
+  const ipv4 = addresses.find((a) => /^\d+\.\d+\.\d+\.\d+$/.test(a));
+  if (ipv4) return ipv4;
+  if (addresses.length > 0) return addresses[0];
+
+  // Last-resort: keep the original host so we never return undefined.
+  return host ?? "unknown";
+}
+
 function serviceToServer(service: Service, isLocal: boolean): DiscoveredServer {
   const txt = service.txt as Record<string, string> | undefined;
   return {
-    host: service.host ?? "unknown",
+    host: pickBestHost(service),
     port: service.port,
     piPort: parseInt(txt?.piPort ?? "9999", 10),
     version: txt?.version ?? "unknown",