@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/packages/server/src/changelog-fs.ts

@@ -0,0 +1,167 @@
+/**
+ * Filesystem helpers for locating an installed package's
+ * `CHANGELOG.md` and `package.json`, plus deriving a public GitHub
+ * URL from the `repository` field.
+ *
+ * Search order matches the ToolRegistry resolution chain for `pi`:
+ *   1. Managed install (`~/.pi-dashboard/node_modules/<pkg>/`)
+ *   2. Bare-import via `createRequire` (process resolves the package
+ *      through its own node_modules — covers npm-global on Unix when
+ *      the symlink lands inside this Node prefix, and dev-checkout
+ *      paths during local builds).
+ *
+ * Both helpers return `null` rather than throwing on absence so route
+ * handlers can degrade to the empty-changelog response per spec
+ * `pi-changelog-display#Scenario: Package not installed returns empty`.
+ *
+ * See change: pi-update-whats-new-panel.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createRequire } from "node:module";
+
+/** Default managed install root. Test seam: caller may override. */
+function defaultManagedDir(): string {
+  return path.join(os.homedir(), ".pi-dashboard");
+}
+
+/**
+ * Locate a package's CHANGELOG.md on disk.
+ *
+ * Returns `{ changelogPath, packageDir }` so callers can read the
+ * adjacent `package.json` without re-resolving.
+ *
+ * Strategy:
+ *   1. `<managedDir>/node_modules/<pkg>/CHANGELOG.md` (Electron + CLI bootstrap).
+ *   2. `createRequire(import.meta.url).resolve("<pkg>/package.json")` then
+ *      look for `CHANGELOG.md` next to it (covers bare-import / npm-global
+ *      via the standard Node resolution mechanism).
+ *
+ * Returns `null` when no readable CHANGELOG can be located.
+ */
+export interface ChangelogLocation {
+  changelogPath: string;
+  packageDir: string;
+}
+
+export interface FindOptions {
+  /** Override managed dir for tests. */
+  managedDir?: string;
+  /**
+   * Override the require-resolver used for bare-import lookup. Tests
+   * pass a stub that throws to force the managed path; production
+   * uses `createRequire(import.meta.url).resolve`.
+   */
+  resolveBareImport?: (pkgJsonSpec: string) => string;
+}
+
+export function findChangelogPath(
+  pkg: string,
+  opts: FindOptions = {},
+): ChangelogLocation | null {
+  // Strategy 1: managed install.
+  const managedDir = opts.managedDir ?? defaultManagedDir();
+  const managedPkg = path.join(managedDir, "node_modules", pkg);
+  const managedCl = path.join(managedPkg, "CHANGELOG.md");
+  if (fs.existsSync(managedCl)) {
+    return { changelogPath: managedCl, packageDir: managedPkg };
+  }
+
+  // Strategy 2: bare-import via require.resolve.
+  const resolver =
+    opts.resolveBareImport ??
+    ((spec: string) => createRequire(import.meta.url).resolve(spec));
+  try {
+    const pkgJsonPath = resolver(`${pkg}/package.json`);
+    const dir = path.dirname(pkgJsonPath);
+    const cl = path.join(dir, "CHANGELOG.md");
+    if (fs.existsSync(cl)) {
+      return { changelogPath: cl, packageDir: dir };
+    }
+  } catch {
+    /* not resolvable — fall through */
+  }
+
+  return null;
+}
+
+/**
+ * Read and parse `package.json` next to a previously-located
+ * CHANGELOG. Returns the parsed object or `null` on read/parse error.
+ */
+export function readPackageJson(packageDir: string): Record<string, unknown> | null {
+  const p = path.join(packageDir, "package.json");
+  try {
+    const raw = fs.readFileSync(p, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") {
+      return parsed as Record<string, unknown>;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive a public GitHub URL pointing at the CHANGELOG given a
+ * `package.json#repository` field. Returns `null` when the field is
+ * missing, not GitHub-hosted, or unparseable.
+ *
+ * Accepted shapes (per spec `pi-changelog-display#Requirement: Changelog URL derivation`):
+ *   - `"github:org/repo"` shorthand
+ *   - `"https://github.com/org/repo.git"` URL string
+ *   - `{ "type": "git", "url": "git+https://github.com/org/repo.git" }`
+ *   - same object form with optional `"directory": "packages/foo"` (monorepo)
+ */
+export function deriveChangelogUrl(repository: unknown): string | null {
+  if (!repository) return null;
+
+  let urlStr: string | null = null;
+  let directory: string | null = null;
+
+  if (typeof repository === "string") {
+    urlStr = repository;
+  } else if (typeof repository === "object" && repository !== null) {
+    const rec = repository as Record<string, unknown>;
+    if (typeof rec.url === "string") urlStr = rec.url;
+    if (typeof rec.directory === "string" && rec.directory.length > 0) {
+      directory = rec.directory.replace(/^\/+|\/+$/g, "");
+    }
+  }
+  if (!urlStr) return null;
+
+  const m = parseGitHubUrl(urlStr);
+  if (!m) return null;
+
+  const subPath = directory ? `${directory}/` : "";
+  return `https://github.com/${m.org}/${m.repo}/blob/main/${subPath}CHANGELOG.md`;
+}
+
+/**
+ * Parse the various GitHub URL forms used in `package.json#repository`
+ * into `{ org, repo }`. Returns null for non-GitHub or unparseable
+ * inputs.
+ */
+function parseGitHubUrl(s: string): { org: string; repo: string } | null {
+  const trimmed = s.trim();
+
+  // github:org/repo shorthand
+  let m = trimmed.match(/^github:([^/]+)\/([^/#]+)/i);
+  if (m) return { org: m[1], repo: stripGitSuffix(m[2]) };
+
+  // git+https://github.com/org/repo.git
+  // https://github.com/org/repo
+  // git://github.com/org/repo.git
+  // ssh://git@github.com/org/repo.git
+  // git@github.com:org/repo.git
+  m = trimmed.match(/(?:^|[/@:])github\.com[/:]([^/]+)\/([^/#?]+)/i);
+  if (m) return { org: m[1], repo: stripGitSuffix(m[2]) };
+
+  return null;
+}
+
+function stripGitSuffix(repo: string): string {
+  return repo.replace(/\.git$/i, "");
+}

package/packages/server/src/changelog-parser.ts

@@ -0,0 +1,321 @@
+/**
+ * Pure parser for Keep-a-Changelog-style markdown files.
+ *
+ * Pi (`@mariozechner/pi-coding-agent`) ships a `CHANGELOG.md` whose
+ * format is mechanically reliable:
+ *   - H2 release headers: `## [<version>] - <date>`
+ *   - H3 sub-section headers: `### Breaking Changes`, `### New Features`,
+ *     `### Added`, `### Changed`, `### Fixed`
+ *   - Bullets at column 0 starting `- `
+ *   - Issue/PR links as `([#NNN](URL))` at end of bullet
+ *
+ * The parser is regex-based on purpose — a full markdown AST would
+ * add hundreds of LOC of dependency surface for marginal gain. When
+ * the file deviates from convention the parser degrades gracefully:
+ * unrecognized H3 headings are dropped from typed slots but the
+ * release's `raw` field still contains the verbatim section.
+ *
+ * Plus a 60-second mtime-keyed in-memory cache so the REST route
+ * doesn't re-parse 150 KB of markdown on every dialog open.
+ *
+ * See change: pi-update-whats-new-panel.
+ */
+import fs from "node:fs";
+import type { ChangelogBullet, ChangelogRelease } from "@blackbelt-technology/pi-dashboard-shared/changelog-types.js";
+
+/** Single line, anchors at line start: `## [<version>] - <date>` (date optional). */
+const RELEASE_HEADER_RE = /^## \[([^\]]+)\](?:\s*-\s*(.+?))?\s*$/gm;
+
+/** Single line, anchors at line start: `### <heading>`. */
+const SUBSECTION_HEADER_RE = /^### (.+?)\s*$/gm;
+
+/** End-of-bullet issue ref: `([#NNN](URL))`. */
+const ISSUE_LINK_RE = /\(\[#(\d+)\]\((https?:\/\/[^)]+)\)\)/g;
+
+/** Subset of YYYY-MM-DD-ish date strings we treat as "valid enough". */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Recognized H3 sub-section names → release-field key. */
+const KNOWN_SUBSECTIONS: Record<string, "breaking" | "features" | "changed" | "fixed"> = {
+  "Breaking Changes": "breaking",
+  "New Features": "features",
+  "Added": "features",
+  "Changed": "changed",
+  "Fixed": "fixed",
+};
+
+/**
+ * Parse a CHANGELOG.md text into a list of release entries, latest
+ * first. Pure function — no I/O. Returns `[]` when the input contains
+ * no recognizable H2 release headers.
+ */
+export function parseChangelog(markdown: string): ChangelogRelease[] {
+  if (!markdown || typeof markdown !== "string") return [];
+
+  // Locate every H2 release header and split the document by them.
+  // The regex's `lastIndex` walks the string giving us each header's
+  // (start offset, captured groups) in one pass.
+  const headers: { version: string; date: string | null; start: number; bodyStart: number }[] = [];
+
+  // Reset the global regex lastIndex to be safe across re-entrant calls.
+  RELEASE_HEADER_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = RELEASE_HEADER_RE.exec(markdown)) !== null) {
+    const version = m[1].trim();
+    const dateRaw = (m[2] ?? "").trim();
+    const date = ISO_DATE_RE.test(dateRaw) ? dateRaw : null;
+    headers.push({
+      version,
+      date,
+      start: m.index,
+      bodyStart: m.index + m[0].length,
+    });
+  }
+
+  if (headers.length === 0) return [];
+
+  // Sort by occurrence order (already in order since regex walks
+  // left→right). Assemble each release as the slice from this
+  // header's start to (the next header's start, or EOF).
+  const releases: ChangelogRelease[] = [];
+  for (let i = 0; i < headers.length; i++) {
+    const h = headers[i];
+    const nextStart = i + 1 < headers.length ? headers[i + 1].start : markdown.length;
+    const raw = markdown.slice(h.start, nextStart).replace(/\s+$/, "");
+    const body = markdown.slice(h.bodyStart, nextStart);
+    const sections = splitSubsections(body);
+
+    const release: ChangelogRelease = {
+      version: h.version,
+      date: h.date,
+      breaking: [],
+      features: [],
+      changed: [],
+      fixed: [],
+      raw,
+    };
+
+    for (const sec of sections) {
+      const slot = KNOWN_SUBSECTIONS[sec.heading];
+      if (!slot) continue;
+      const bullets = extractBullets(sec.body);
+      // `features` is the merge of New Features + Added; both map to
+      // the same slot, so just push in source order.
+      release[slot].push(...bullets);
+    }
+    releases.push(release);
+  }
+
+  return releases;
+}
+
+/**
+ * Walk a release's body (text between its H2 and the next H2) and
+ * return one entry per H3 sub-heading. Text before the first H3 is
+ * dropped — pi never puts content there.
+ */
+function splitSubsections(body: string): { heading: string; body: string }[] {
+  const out: { heading: string; body: string }[] = [];
+  const positions: { heading: string; bodyStart: number; headerStart: number }[] = [];
+
+  SUBSECTION_HEADER_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = SUBSECTION_HEADER_RE.exec(body)) !== null) {
+    positions.push({
+      heading: m[1].trim(),
+      headerStart: m.index,
+      bodyStart: m.index + m[0].length,
+    });
+  }
+  for (let i = 0; i < positions.length; i++) {
+    const p = positions[i];
+    const nextStart = i + 1 < positions.length ? positions[i + 1].headerStart : body.length;
+    out.push({ heading: p.heading, body: body.slice(p.bodyStart, nextStart) });
+  }
+  return out;
+}
+
+/**
+ * Extract bullets from a sub-section body. A bullet starts with `- `
+ * at column 0 and continues until the next column-0 `- ` line, the
+ * next H-heading line, or end-of-section.
+ */
+function extractBullets(body: string): ChangelogBullet[] {
+  const lines = body.split("\n");
+  const bullets: string[] = [];
+  let current: string | null = null;
+
+  for (const line of lines) {
+    if (/^- /.test(line)) {
+      if (current !== null) bullets.push(current);
+      current = line.slice(2);
+    } else if (current !== null) {
+      // Continuation of the current bullet only when the line is
+      // either blank-and-followed-by-content (we drop blanks) or
+      // indented. Stop on an undented non-bullet line that looks
+      // like new content.
+      if (line.trim() === "") {
+        // Skip blank lines inside a bullet block; they may separate
+        // paragraphs but don't terminate the bullet.
+        continue;
+      }
+      if (/^\s/.test(line)) {
+        current += "\n" + line.replace(/^\s+/, "");
+      } else {
+        // Undented non-bullet line: treat as end of bullet block.
+        bullets.push(current);
+        current = null;
+      }
+    }
+  }
+  if (current !== null) bullets.push(current);
+
+  return bullets.map((text) => ({
+    text: text.trim(),
+    issues: extractIssues(text),
+  }));
+}
+
+/** Collect all `([#NNN](URL))` matches in a bullet's prose. */
+function extractIssues(text: string): { num: number; url: string }[] {
+  const out: { num: number; url: string }[] = [];
+  ISSUE_LINK_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = ISSUE_LINK_RE.exec(text)) !== null) {
+    const num = parseInt(m[1], 10);
+    if (!Number.isNaN(num)) out.push({ num, url: m[2] });
+  }
+  return out;
+}
+
+// ── Cache ──────────────────────────────────────────────────────────
+
+const CACHE_TTL_MS = 60_000;
+
+export type ChangelogSource = "local" | "remote";
+
+interface CacheEntry {
+  /** Result of parsing the file/text. */
+  releases: ChangelogRelease[];
+  /**
+   * mtime of the source file when this entry was created (local source
+   * only). 0 for remote entries (mtime irrelevant; ETag drives remote
+   * freshness).
+   */
+  mtimeMs: number;
+  /** Wall-clock expiry. */
+  expiresAt: number;
+  /** ETag from a remote response, if any. Used for conditional GET. */
+  etag: string | null;
+}
+
+/** Cache key combines pkg + source so remote and local don't collide. */
+function cacheKey(pkg: string, source: ChangelogSource): string {
+  return `${source}:${pkg}`;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * Read + parse a CHANGELOG.md file with a 60-second mtime-keyed
+ * cache. The cache is keyed by `pkg`; the entry is invalidated when
+ * the file's mtime changes (e.g. after a fresh `npm install`) or
+ * when 60 seconds have elapsed.
+ *
+ * Returns `[]` (not throwing) for ENOENT — callers treat "not found"
+ * the same as "no releases". Other I/O errors propagate.
+ */
+export function readAndParseChangelog(
+  pkg: string,
+  filePath: string,
+  now: () => number = Date.now,
+): ChangelogRelease[] {
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(filePath);
+  } catch (err: any) {
+    if (err?.code === "ENOENT") return [];
+    throw err;
+  }
+  const mtimeMs = stat.mtimeMs;
+  const t = now();
+
+  const key = cacheKey(pkg, "local");
+  const hit = cache.get(key);
+  if (hit && hit.mtimeMs === mtimeMs && t < hit.expiresAt) {
+    return hit.releases;
+  }
+
+  const content = fs.readFileSync(filePath, "utf8");
+  const releases = parseChangelog(content);
+  cache.set(key, {
+    releases,
+    mtimeMs,
+    expiresAt: t + CACHE_TTL_MS,
+    etag: null,
+  });
+  return releases;
+}
+
+/**
+ * Cache-hit accessor for the remote-source entry. Returns the cached
+ * releases + last-known ETag. Caller decides what to do with `expired`
+ * (typically: try a conditional GET, reuse on 304).
+ */
+export function getCachedRemoteChangelog(
+  pkg: string,
+  now: () => number = Date.now,
+): { releases: ChangelogRelease[]; etag: string | null; expired: boolean } | undefined {
+  const hit = cache.get(cacheKey(pkg, "remote"));
+  if (!hit) return undefined;
+  return {
+    releases: hit.releases,
+    etag: hit.etag,
+    expired: now() >= hit.expiresAt,
+  };
+}
+
+/** Store a remote fetch result. */
+export function setRemoteChangelog(
+  pkg: string,
+  releases: ChangelogRelease[],
+  etag: string | null,
+  now: () => number = Date.now,
+): void {
+  cache.set(cacheKey(pkg, "remote"), {
+    releases,
+    mtimeMs: 0,
+    expiresAt: now() + CACHE_TTL_MS,
+    etag,
+  });
+}
+
+/**
+ * Extend a remote cache entry's TTL without re-parsing. Used after a
+ * 304 Not Modified response.
+ */
+export function refreshRemoteChangelogTtl(
+  pkg: string,
+  now: () => number = Date.now,
+): void {
+  const entry = cache.get(cacheKey(pkg, "remote"));
+  if (entry) entry.expiresAt = now() + CACHE_TTL_MS;
+}
+
+/** Clear all cache entries. Test seam + invalidation hook. */
+export function _resetChangelogCache(): void {
+  cache.clear();
+}
+
+/**
+ * Clear a single package's cache entries (both local and remote
+ * sources). Wired into PiCoreChecker.invalidate.
+ */
+export function invalidateChangelogCache(pkg?: string): void {
+  if (pkg === undefined) {
+    cache.clear();
+    return;
+  }
+  cache.delete(cacheKey(pkg, "local"));
+  cache.delete(cacheKey(pkg, "remote"));
+}

package/packages/server/src/changelog-remote.ts

@@ -0,0 +1,134 @@
+/**
+ * Fetches the upstream CHANGELOG.md from GitHub raw, so the dashboard
+ * can show release notes for versions newer than the locally-installed
+ * tarball describes.
+ *
+ * Trust model identical to `pi-dev-version-check`: HTTPS, default Node
+ * trust store, 10-second timeout, env-skippable via `PI_OFFLINE`.
+ *
+ * See change: read-changelog-from-github.
+ */
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Discriminated result of a remote fetch attempt. */
+export type RemoteChangelogResult =
+  | { status: "ok"; text: string; etag: string | null }
+  | { status: "not-modified" }
+  | null; // hard failure (network, parse, env-skipped) → caller falls back to local
+
+export interface FetchRemoteChangelogOptions {
+  /** Optional ETag from a previous response. When set, sent as `If-None-Match`. */
+  etag?: string | null;
+  /** Override fetch timeout. Default 10 s. */
+  timeoutMs?: number;
+  /** Test seam. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Sibling of `deriveChangelogUrl` that returns the *raw* form suitable
+ * for parsing (vs the `/blob/main/` URL which is for human viewing).
+ *
+ * Accepts the same `repository` field shapes:
+ *   - `"github:org/repo"` shorthand
+ *   - URL strings (`"https://github.com/org/repo.git"`, `"git@github.com:org/repo.git"`, etc.)
+ *   - object form `{ url, directory? }` (monorepos)
+ *
+ * Returns `null` for non-GitHub or unparseable input.
+ */
+export function deriveChangelogRawUrl(repository: unknown): string | null {
+  if (!repository) return null;
+
+  let urlStr: string | null = null;
+  let directory: string | null = null;
+
+  if (typeof repository === "string") {
+    urlStr = repository;
+  } else if (typeof repository === "object" && repository !== null) {
+    const rec = repository as Record<string, unknown>;
+    if (typeof rec.url === "string") urlStr = rec.url;
+    if (typeof rec.directory === "string" && rec.directory.length > 0) {
+      directory = rec.directory.replace(/^\/+|\/+$/g, "");
+    }
+  }
+  if (!urlStr) return null;
+
+  const m = parseGitHubUrl(urlStr);
+  if (!m) return null;
+
+  const subPath = directory ? `${directory}/` : "";
+  return `https://raw.githubusercontent.com/${m.org}/${m.repo}/main/${subPath}CHANGELOG.md`;
+}
+
+/**
+ * Parse the various GitHub URL forms used in `package.json#repository`
+ * into `{ org, repo }`. Internal helper duplicating the same logic in
+ * `changelog-fs.ts::parseGitHubUrl` — kept inline to avoid cross-module
+ * coupling for a 10-line regex.
+ */
+function parseGitHubUrl(s: string): { org: string; repo: string } | null {
+  const trimmed = s.trim();
+
+  // github:org/repo shorthand
+  let m = trimmed.match(/^github:([^/]+)\/([^/#]+)/i);
+  if (m) return { org: m[1], repo: stripGitSuffix(m[2]) };
+
+  // git+https://github.com/org/repo.git
+  // https://github.com/org/repo
+  // ssh://git@github.com/org/repo.git
+  // git@github.com:org/repo.git
+  m = trimmed.match(/(?:^|[/@:])github\.com[/:]([^/]+)\/([^/#?]+)/i);
+  if (m) return { org: m[1], repo: stripGitSuffix(m[2]) };
+
+  return null;
+}
+
+function stripGitSuffix(repo: string): string {
+  return repo.replace(/\.git$/i, "");
+}
+
+/**
+ * Fetch the markdown text at `rawUrl`. Returns:
+ *   - `{ status: "ok", text, etag }` on 2xx
+ *   - `{ status: "not-modified" }` on 304 (when If-None-Match was sent and
+ *     server confirmed the cached body is current)
+ *   - `null` for: PI_OFFLINE / env-skipped, non-2xx (other than 304),
+ *     network error, abort, malformed response.
+ *
+ * Caller is responsible for falling back to the local CHANGELOG on
+ * `null` return.
+ */
+export async function fetchRemoteChangelog(
+  rawUrl: string,
+  opts: FetchRemoteChangelogOptions = {},
+): Promise<RemoteChangelogResult> {
+  if (process.env.PI_OFFLINE) return null;
+
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const headers: Record<string, string> = { accept: "text/plain, */*" };
+  if (opts.etag) headers["If-None-Match"] = opts.etag;
+
+  try {
+    const response = await fetchFn(rawUrl, {
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+      redirect: "follow",
+    });
+
+    // 304: server confirms cache is current. Caller reuses cached body.
+    if (response.status === 304) {
+      return { status: "not-modified" };
+    }
+    if (!response.ok) return null;
+
+    const text = await response.text();
+    if (typeof text !== "string" || text.length === 0) return null;
+
+    const etag = response.headers.get("etag");
+    return { status: "ok", text, etag };
+  } catch {
+    return null;
+  }
+}

package/packages/server/src/cli.ts

@@ -53,6 +53,8 @@ import {
 import type { DashboardServer } from "./server.js";
 import { updateBootstrapCompatibility } from "./pi-version-skew.js";
 import type { BootstrapStateStore } from "./bootstrap-state.js";
+import { parseDashboardStarter } from "@blackbelt-technology/pi-dashboard-shared/dashboard-starter.js";
+import { bootstrapInstallFromList } from "./bootstrap-install-from-list.js";
 
 /**
  * Emit a stderr warning at CLI startup when the resolved pi version is
@@ -166,6 +168,12 @@ async function runForeground(config: ServerConfig): Promise<void> {
   assertNodeVersionSupported();
   const server = await createServer(config);
 
+  // Stamp the bootstrap state with who started this server process.
+  // parseDashboardStarter defaults to "Standalone" when DASHBOARD_STARTER is unset.
+  const starter = parseDashboardStarter(process.env);
+  server.bootstrapState.set({ starter });
+  console.log(`[bootstrap] starter=${starter}`);
+
   let shuttingDown = false;
   const shutdown = async () => {
     if (shuttingDown) {
@@ -181,6 +189,19 @@ async function runForeground(config: ServerConfig): Promise<void> {
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
 
+  // Reconcile installable.json before binding the port.
+  // Required-package failures throw and prevent server start.
+  // Optional failures are logged and continue.
+  // File-absent is a no-op (Bridge/Standalone starters don't seed installable.json).
+  // See change: simplify-electron-bootstrap-derived-state.
+  try {
+    await bootstrapInstallFromList(server.bootstrapState);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[bootstrap] installable reconcile failed (required package): ${message}`);
+    process.exit(1);
+  }
+
   await server.start();
 
   // Kick off the degraded-mode first-run bootstrap if pi is unresolvable.
@@ -231,7 +252,7 @@ async function runDegradedModeBootstrap(server: DashboardServer): Promise<void>
     return;
   }
 
-  const installPackages = ["@mariozechner/pi-coding-agent", "@fission-ai/openspec", "tsx"];
+  const installPackages = ["@earendil-works/pi-coding-agent", "@fission-ai/openspec", "tsx"];
   server.bootstrapState.setLastInstallPackages(installPackages);
   console.log("[bootstrap] installing (pi unresolved, running background install)");
   server.bootstrapState.set({
@@ -577,7 +598,7 @@ async function cmdUpgradePi(config: ServerConfig): Promise<void> {
 
   console.log("[upgrade-pi] no dashboard running — installing directly");
   const res = await bootstrapInstall({
-    packages: ["@mariozechner/pi-coding-agent"],
+    packages: ["@earendil-works/pi-coding-agent"],
     progress: (p) => {
       const line = p.output
         ? `[upgrade-pi] ${p.step} ${p.status}: ${p.output}`