hotmilk 0.1.9 → 0.1.11

package/AGENTS.md

@@ -20,7 +20,7 @@ Requires **Node.js 22+**. Targets **Pi 0.78** (`@earendil-works/pi-coding-agent`
 - **Runtime**: [Pi](https://github.com/badlogic/pi-mono) with `@earendil-works/pi-coding-agent` — install hotmilk via `pi install npm:hotmilk`.
 - **Single extension entry**: only `./src/index.ts` is listed under `package.json` → `pi.extensions`. All other bundled packages load via **dynamic `import()`** when their toggle is `true`.
 - **Config**: `~/.pi/agent/hotmilk.json` — change with `/mode`, apply with `/reload`.
-- **Do not** add packages to `pi.extensions` for toggled deps; add `BUNDLED_EXTENSION_IDS` + a loader in `src/bootstrap/extensions.ts`.
+- **Do not** add packages to `pi.extensions` for toggled deps; add one row to `BUNDLED_EXTENSION_DEFINITIONS` in `src/config/bundled-extensions.ts`.
 
 Details: [docs/pi.md](docs/pi.md).
 

package/README.md

@@ -6,19 +6,19 @@ Use it when you want a practical engineering workstation without hand-picking a
 
 ## What you get
 
-| Layer                   | Packages / assets                                                                                                                                                                                                                                                                            |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Orchestration**       | [gentle-pi](https://www.npmjs.com/package/gentle-pi) (SDD, skill registry, `sdd-init`)                                                                                                                                                                                                       |
-| **Context**             | [context-mode](https://www.npmjs.com/package/context-mode)                                                                                                                                                                                                                                   |
-| **Codebase graph**      | [graphify-pi](https://www.npmjs.com/package/graphify-pi)                                                                                                                                                                                                                                     |
-| **Subagents**           | [pi-subagents](https://www.npmjs.com/package/pi-subagents), [pi-ask-user](https://www.npmjs.com/package/pi-ask-user)                                                                                                                                                                         |
-| **Goals & docs**        | [pi-goal](https://www.npmjs.com/package/pi-goal), [pi-docparser](https://www.npmjs.com/package/pi-docparser)                                                                                                                                                                                 |
-| **File-based planning** | [@tomxprime/planning-with-files](https://www.npmjs.com/package/@tomxprime/planning-with-files)                                                                                                                                                                                               |
-| **Integrations**        | [pi-mcp-adapter](https://www.npmjs.com/package/pi-mcp-adapter), [pi-btw](https://www.npmjs.com/package/pi-btw), [@haispeed/pi-obsidian](https://www.npmjs.com/package/@haispeed/pi-obsidian), [@netandreus/pi-cursor-provider](https://www.npmjs.com/package/@netandreus/pi-cursor-provider) |
-| **Dashboard**           | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard)                                                                                                                                                                           |
-| **Web tools**           | [pi-web-access](https://www.npmjs.com/package/pi-web-access)                                                                                                                                                                                                                                 |
-| **Flows**               | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows)                                                                                                                                                                                               |
-| **Local assets**        | `./prompts`, `./skills`, `./themes`, `mcp.json` template                                                                                                                                                                                                                                     |
+| Layer                   | Packages / assets                                                                                                                                                                            |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Orchestration**       | [gentle-pi](https://www.npmjs.com/package/gentle-pi) (SDD, skill registry, `sdd-init`)                                                                                                       |
+| **Context**             | [context-mode](https://www.npmjs.com/package/context-mode)                                                                                                                                   |
+| **Codebase graph**      | [graphify-pi](https://www.npmjs.com/package/graphify-pi)                                                                                                                                     |
+| **Subagents**           | [pi-subagents](https://www.npmjs.com/package/pi-subagents), [pi-ask-user](https://www.npmjs.com/package/pi-ask-user)                                                                         |
+| **Goals & docs**        | [pi-goal](https://www.npmjs.com/package/pi-goal), [pi-docparser](https://www.npmjs.com/package/pi-docparser)                                                                                 |
+| **File-based planning** | [@tomxprime/planning-with-files](https://www.npmjs.com/package/@tomxprime/planning-with-files)                                                                                               |
+| **Integrations**        | [pi-mcp-adapter](https://www.npmjs.com/package/pi-mcp-adapter), [pi-btw](https://www.npmjs.com/package/pi-btw), [@haispeed/pi-obsidian](https://www.npmjs.com/package/@haispeed/pi-obsidian) |
+| **Dashboard**           | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard)                                                                           |
+| **Web tools**           | [pi-web-access](https://www.npmjs.com/package/pi-web-access)                                                                                                                                 |
+| **Flows**               | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows)                                                                                               |
+| **Local assets**        | `./prompts`, `./skills`, `./themes`, `mcp.json` template                                                                                                                                     |
 
 Bundled extension **on/off** is controlled in `hotmilk.json` (via `/mode`), then `/reload`. Only `src/index.ts` is listed in `package.json` → `pi.extensions`; every other bundled package is loaded dynamically when its toggle is `true`.
 
@@ -95,7 +95,6 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
     "goal": true,
     "docparser": true,
     "obsidian": true,
-    "cursor-provider": true,
     "btw": true,
     "simplify": true,
     "rtk-optimizer": false,
@@ -105,7 +104,9 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
     "red-green": false,
     "agent-dashboard": false,
     "web-access": false,
-    "pi-flows": false
+    "pi-flows": false,
+    "kanagawa": false,
+    "tetris": false
   },
   "graph": {
     "warnOnStale": true,
@@ -142,20 +143,34 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
 
 Enable in `/mode` or set the key to `true` in `hotmilk.json`, then `/reload`.
 
-| Toggle            | Package                                                                                                            | Notes                                                                                                           |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `caveman`         | [pi-caveman](https://www.npmjs.com/package/pi-caveman)                                                             | Terse English (`/caveman`). Conflicts with `defaults.language: ja`                                              |
-| `red-green`       | [pi-red-green](https://www.npmjs.com/package/pi-red-green)                                                         | TDD via `/tdd`, `/tdd-status`. Config: `~/.pi/red-green/config.json`                                            |
-| `agent-dashboard` | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard) | Warm-starts via `pi-dashboard start` (~30s). Peers **0.74**; test on 0.78 before relying on it. Node.js ≥ 22.18 |
-| `web-access`      | [pi-web-access](https://www.npmjs.com/package/pi-web-access)                                                       | `web_search`, fetch, GitHub clone, PDF/video. Optional keys: `~/.pi/web-search.json`                            |
-| `pi-flows`        | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows)                     | YAML DAG workflows (`/flows`). Peers **0.74** + `@sinclair/typebox`; off by default on 0.78 stacks              |
+| Toggle            | Package                                                                                                            | Notes                                                                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `caveman`         | [pi-caveman](https://www.npmjs.com/package/pi-caveman)                                                             | Terse English (`/caveman`). Conflicts with `defaults.language: ja`                                                             |
+| `red-green`       | [pi-red-green](https://www.npmjs.com/package/pi-red-green)                                                         | TDD via `/tdd`, `/tdd-status`. Config: `~/.pi/red-green/config.json`                                                           |
+| `agent-dashboard` | [@blackbelt-technology/pi-agent-dashboard](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard) | Warm-starts before the bridge loads (cold boot up to ~60s). Peers **0.74**; test on 0.78 before relying on it. Node.js ≥ 22.18 |
+| `web-access`      | [pi-web-access](https://www.npmjs.com/package/pi-web-access)                                                       | `web_search`, fetch, GitHub clone, PDF/video. Optional keys: `~/.pi/web-search.json`                                           |
+| `pi-flows`        | [@blackbelt-technology/pi-flows](https://www.npmjs.com/package/@blackbelt-technology/pi-flows)                     | YAML DAG workflows (`/flows`). Peers **0.74** + `@sinclair/typebox`; off by default on 0.78 stacks                             |
+| `kanagawa`        | [pi-kanagawa](https://www.npmjs.com/package/pi-kanagawa)                                                           | Kanagawa theme (also in `/theme` via shipped assets), wave animation, `/thinking`. **Replaces hotmilk footer** when on         |
+| `tetris`          | [pi-tetris](https://www.npmjs.com/package/pi-tetris)                                                               | Play Tetris with `/tetris`. Lightweight; default off                                                                           |
 
 **Agent dashboard troubleshooting**
 
 - Run **one** dashboard process: either hotmilk warm-start (`agent-dashboard: true`) **or** manual `npm run dashboard:start`, not both.
 - Keep only `"hotmilk"` in `~/.pi/agent/settings.json` `packages[]` (not a standalone dashboard extension path). Hotmilk prunes duplicate dashboard paths on session start when `agent-dashboard` is enabled.
-- `EADDRINUSE` on `8000` or `9999`: `npm run dashboard:stop`, then `lsof -i :8000` / `:9999` and kill the stale PID before starting again.
+- Hotmilk seeds dashboard HTTP port **8102** (when config still has upstream default `8000`) to avoid common port conflicts. Custom ports are preserved.
+- `EADDRINUSE` on `8102` (or `9999` for pi bridge): stop the stale dashboard (`pi-dashboard stop` or `lsof -i :8102` / `:9999`), then restart Pi.
 - Without `zrok` on PATH, hotmilk sets `tunnel.enabled` to `false`.
+- **`ERR TypeScript loader` / jiti or tsx not found** (paths under `~/.pi-dashboard/node_modules/`): the bridge doctor checks the legacy managed dashboard dir. That directory is often empty when you only use hotmilk. Enable `agent-dashboard`, restart Pi (warm-start uses hotmilk’s bundled `pi-dashboard-server`, which ships jiti), or run `bun run dashboard:start` from a hotmilk checkout. If the error persists, install globally: `pi install npm:@blackbelt-technology/pi-agent-dashboard` and complete **Help → Setup**, or `npm install jiti` under `~/.pi-dashboard` after `pi-dashboard` setup creates that tree.
+
+### Cursor models (optional, not bundled)
+
+hotmilk does not ship [@netandreus/pi-cursor-provider](https://www.npmjs.com/package/@netandreus/pi-cursor-provider). Install when you route Pi through the Cursor Agent CLI:
+
+```bash
+pi install npm:@netandreus/pi-cursor-provider
+agent login
+# then in Pi: /model cursor/auto
+```
 
 ### Migrating from `pi-ninja`
 

package/hotmilk.json

@@ -10,7 +10,6 @@
     "goal": true,
     "docparser": true,
     "obsidian": true,
-    "cursor-provider": true,
     "btw": true,
     "simplify": true,
     "rtk-optimizer": false,
@@ -20,7 +19,9 @@
     "red-green": false,
     "agent-dashboard": false,
     "web-access": false,
-    "pi-flows": false
+    "pi-flows": false,
+    "kanagawa": false,
+    "tetris": false
   },
   "graph": {
     "warnOnStale": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotmilk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "hotmilk — Pi package bundling gentle-pi, context-mode, graphify, subagents, and bundled extension toggles via hotmilk.json",
   "keywords": [
     "hotmilk",
@@ -42,7 +42,6 @@
     "@blackbelt-technology/pi-agent-dashboard": "^0.5.4",
     "@blackbelt-technology/pi-flows": "^0.2.1",
     "@haispeed/pi-obsidian": "^0.1.1",
-    "@netandreus/pi-cursor-provider": "^0.1.4",
     "@tomxprime/planning-with-files": "^1.1.0",
     "context-mode": "^1.0.151",
     "gentle-pi": "^0.3.10",
@@ -52,11 +51,13 @@
     "pi-caveman": "^1.0.7",
     "pi-docparser": "^3.0.1",
     "pi-goal": "^0.1.5",
+    "pi-kanagawa": "^1.0.0",
     "pi-mcp-adapter": "^2.8.0",
     "pi-red-green": "^0.2.2",
     "pi-rtk-optimizer": "^0.8.1",
     "pi-simplify": "^0.2.2",
     "pi-subagents": "^0.25.0",
+    "pi-tetris": "^1.3.1",
     "pi-web-access": "^0.10.7"
   },
   "devDependencies": {
@@ -101,7 +102,8 @@
       "node_modules/@tomxprime/planning-with-files"
     ],
     "themes": [
-      "./themes"
+      "./themes",
+      "node_modules/pi-kanagawa/themes"
     ]
   }
 }

package/src/bootstrap/context-stack.ts

@@ -8,15 +8,6 @@ import type { BundledExtensionId } from "../config/hotmilk.ts";
 const RTK_EXTENSION_DIR = "pi-rtk-optimizer";
 const RTK_CONFIG_FILENAME = "config.json";
 
-/**
- * Register in this order so context-mode hooks run before rtk-optimizer compacts tool output.
- * Loader paths match upstream npm `pi.extensions` (not `.pi/extensions/` shims in the git repo).
- */
-export const CONTEXT_STACK_EXTENSION_IDS = [
-  "context-mode",
-  "rtk-optimizer",
-] as const satisfies readonly BundledExtensionId[];
-
 export function getRtkOptimizerConfigPath(): string {
   return `${getAgentDir()}/extensions/${RTK_EXTENSION_DIR}/${RTK_CONFIG_FILENAME}`;
 }
@@ -144,15 +135,16 @@ export function applyContextStackOnSessionStart(
   notify: (message: string, level: "info" | "warning") => void,
 ): void {
   const { extensionToggles } = runtime;
+  const contextModeEnabled = extensionToggles["context-mode"];
 
   if (extensionToggles["rtk-optimizer"]) {
-    const sync = syncRtkConfigForContextStack(extensionToggles["context-mode"], true);
+    const sync = syncRtkConfigForContextStack(contextModeEnabled, true);
     if (sync.updated && !sync.seeded) {
       notify(RTK_SYNC_MESSAGE, "info");
     }
   }
 
-  if (!extensionToggles["context-mode"]) {
+  if (!contextModeEnabled) {
     return;
   }
 

package/src/bootstrap/dashboard.ts

@@ -1,23 +1,118 @@
-import { execSync, spawn } from "node:child_process";
+import { execSync } from "node:child_process";
 import { createRequire } from "node:module";
 import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
 import path from "node:path";
-import { isDashboardRunning } from "@blackbelt-technology/pi-dashboard-shared/server-identity.js";
-import { pruneRedundantDashboardPackage } from "./dashboard-settings.ts";
+import type { DashboardConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import {
   CONFIG_FILE,
   ensureConfig,
   loadConfig,
 } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { isDashboardRunning } from "@blackbelt-technology/pi-dashboard-shared/server-identity.js";
+import {
+  EarlyExitError,
+  launchDashboardServer,
+  PortConflictError,
+} from "@blackbelt-technology/pi-dashboard-shared/server-launcher.js";
+import { pruneRedundantDashboardPackage } from "./dashboard-settings.ts";
 
 const require = createRequire(import.meta.url);
 
-/** Bridge auto-start only waits 2s; warm-start via CLI uses 30s readiness. */
+/** hotmilk default dashboard HTTP port (avoids common 8000 conflicts). */
+export const HOTMILK_DASHBOARD_PORT = 8102;
+
+/** Upstream pi-agent-dashboard default before hotmilk applies its seed. */
+export const UPSTREAM_DASHBOARD_DEFAULT_PORT = 8000;
+
+/** Cold dashboard bootstrap (jiti + session scan) can exceed bridge's 2s probe. */
+const WARM_START_PROBE_OPTS = {
+  timeoutMs: 8_000,
+  retries: 3,
+  retryDelayMs: 500,
+} as const;
+
+const WARM_START_HEALTH_TIMEOUT_MS = 60_000;
+
+export function dashboardServerLogPath(): string {
+  return path.join(os.homedir(), ".pi", "dashboard", "server.log");
+}
+
+/** Bridge auto-start only waits 2s; warm-start uses 30s readiness. */
 export function resolvePiDashboardCli(): string {
   const pkgJson = require.resolve("@blackbelt-technology/pi-agent-dashboard/package.json");
   return path.join(path.dirname(pkgJson), "packages/server/bin/pi-dashboard.mjs");
 }
 
+/** Entry script for {@link launchDashboardServer} (server CLI, not the mjs wrapper). */
+export function resolveDashboardServerCliPath(): string {
+  const pkgJson = require.resolve("@blackbelt-technology/pi-dashboard-server/package.json");
+  return path.join(path.dirname(pkgJson), "src", "cli.ts");
+}
+
+export function buildWarmStartLaunchArgs(
+  config: Pick<DashboardConfig, "port" | "piPort">,
+): string[] {
+  return ["--port", String(config.port), "--pi-port", String(config.piPort)];
+}
+
+export function isTcpPortFree(port: number, host = "127.0.0.1"): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, host);
+  });
+}
+
+/** Pick a free pi gateway port when the configured default is already taken. */
+export async function resolveAvailablePiPort(
+  preferred: number,
+  isFree: (port: number) => Promise<boolean> = isTcpPortFree,
+  maxAttempts = 20,
+): Promise<number> {
+  for (let offset = 0; offset < maxAttempts; offset += 1) {
+    const candidate = preferred - offset;
+    if (candidate <= 0) {
+      break;
+    }
+    if (await isFree(candidate)) {
+      return candidate;
+    }
+  }
+  return preferred;
+}
+
+export function persistDashboardPiPort(piPort: number): boolean {
+  ensureConfig();
+  const raw = readDashboardConfigRaw();
+  if (!raw || raw.piPort === piPort) {
+    return false;
+  }
+  raw.piPort = piPort;
+  writeDashboardConfigRaw(raw);
+  return true;
+}
+
+export type DashboardWarmStartDecision = "skip-running" | "skip-conflict" | "launch";
+
+export async function resolveDashboardWarmStartDecision(
+  port: number,
+  probe: typeof isDashboardRunning = isDashboardRunning,
+): Promise<DashboardWarmStartDecision> {
+  const status = await probe(port, "localhost", WARM_START_PROBE_OPTS);
+  if (status.running) {
+    return "skip-running";
+  }
+  if (status.portConflict) {
+    return "skip-conflict";
+  }
+  return "launch";
+}
+
 export function isZrokOnPath(): boolean {
   try {
     execSync("command -v zrok", { stdio: "ignore" });
@@ -27,66 +122,150 @@ export function isZrokOnPath(): boolean {
   }
 }
 
+function readDashboardConfigRaw(): Record<string, unknown> | undefined {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeDashboardConfigRaw(raw: Record<string, unknown>): void {
+  fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
+}
+
+export type ApplyHotmilkDashboardDefaultsResult = {
+  updated: boolean;
+  path: string;
+};
+
 /**
- * Disable zrok tunnel when the binary is missing — avoids slow/failed tunnel
- * setup and matches local-only hotmilk usage.
+ * Apply hotmilk-specific dashboard defaults to a parsed config object.
+ * Preserves custom ports; only migrates upstream default 8000 → {@link HOTMILK_DASHBOARD_PORT}.
  */
-export function applyHotmilkDashboardDefaults(): { updated: boolean; path: string } {
-  ensureConfig();
-  if (isZrokOnPath()) {
-    return { updated: false, path: CONFIG_FILE };
+export function applyHotmilkDashboardDefaultsToRaw(
+  raw: Record<string, unknown>,
+  opts: { zrokAvailable?: boolean } = {},
+): boolean {
+  const zrokAvailable = opts.zrokAvailable ?? isZrokOnPath();
+  let updated = false;
+
+  const port = raw.port;
+  if (port === undefined || port === UPSTREAM_DASHBOARD_DEFAULT_PORT) {
+    raw.port = HOTMILK_DASHBOARD_PORT;
+    updated = true;
   }
 
-  let raw: Record<string, unknown>;
-  try {
-    raw = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8")) as Record<string, unknown>;
-  } catch {
-    return { updated: false, path: CONFIG_FILE };
+  if (!zrokAvailable) {
+    const tunnel =
+      raw.tunnel && typeof raw.tunnel === "object" ? (raw.tunnel as Record<string, unknown>) : {};
+    if (tunnel.enabled !== false) {
+      raw.tunnel = { ...tunnel, enabled: false };
+      updated = true;
+    }
   }
 
-  const tunnel =
-    raw.tunnel && typeof raw.tunnel === "object" ? (raw.tunnel as Record<string, unknown>) : {};
-  if (tunnel.enabled === false) {
+  return updated;
+}
+
+/**
+ * Seed hotmilk dashboard defaults into ~/.pi/dashboard/config.json:
+ * port 8102 (when still on upstream 8000) and disable zrok when the binary is missing.
+ */
+export function applyHotmilkDashboardDefaults(): ApplyHotmilkDashboardDefaultsResult {
+  ensureConfig();
+
+  const raw = readDashboardConfigRaw();
+  if (!raw || !applyHotmilkDashboardDefaultsToRaw(raw)) {
     return { updated: false, path: CONFIG_FILE };
   }
 
-  raw.tunnel = { ...tunnel, enabled: false };
-  fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
+  writeDashboardConfigRaw(raw);
   return { updated: true, path: CONFIG_FILE };
 }
 
-let warmStartScheduled = false;
+let warmStartPromise: Promise<DashboardWarmStartResult> | undefined;
 
-async function runDashboardWarmStart(): Promise<void> {
+export type DashboardWarmStartResult = {
+  status: "running" | "started" | "skipped-conflict" | "failed";
+  port: number;
+  piPort: number;
+  message?: string;
+};
+
+function warmStartResult(
+  status: DashboardWarmStartResult["status"],
+  port: number,
+  piPort: number,
+  message?: string,
+): DashboardWarmStartResult {
+  return { status, port, piPort, message };
+}
+
+/**
+ * Start the dashboard via shared launcher (60s readiness) and wait until
+ * the bridge extension loads so its 2s auto-start sees a healthy server.
+ */
+export async function ensureDashboardWarmStarted(): Promise<DashboardWarmStartResult> {
+  if (warmStartPromise) {
+    return warmStartPromise;
+  }
+
+  warmStartPromise = runDashboardWarmStart().catch((err) => {
+    warmStartPromise = undefined;
+    throw err;
+  });
+  return warmStartPromise;
+}
+
+async function runDashboardWarmStart(): Promise<DashboardWarmStartResult> {
   pruneRedundantDashboardPackage();
   applyHotmilkDashboardDefaults();
   const config = loadConfig();
-  const status = await isDashboardRunning(config.port, "localhost", {
-    timeoutMs: 800,
-    retries: 1,
-    retryDelayMs: 200,
-  });
-  if (status.running) {
-    return;
+  const decision = await resolveDashboardWarmStartDecision(config.port);
+  if (decision === "skip-running") {
+    return warmStartResult("running", config.port, config.piPort);
+  }
+  if (decision === "skip-conflict") {
+    return warmStartResult(
+      "skipped-conflict",
+      config.port,
+      config.piPort,
+      `Port ${config.port} is occupied by a non-dashboard service`,
+    );
   }
 
-  const cli = resolvePiDashboardCli();
-  const child = spawn(process.execPath, [cli, "start"], {
-    detached: true,
-    stdio: "ignore",
-    env: process.env,
-  });
-  child.unref();
-}
+  let piPort = config.piPort;
+  if (!(await isTcpPortFree(piPort))) {
+    const resolved = await resolveAvailablePiPort(piPort);
+    if (resolved !== piPort) {
+      persistDashboardPiPort(resolved);
+      piPort = resolved;
+    }
+  }
 
-/**
- * Start the dashboard via `pi-dashboard start` (30s readiness) before the
- * bridge extension's 2s auto-start runs. Fire-and-forget; idempotent.
- */
-export function scheduleDashboardWarmStart(): void {
-  if (warmStartScheduled) {
-    return;
+  const launchConfig = { port: config.port, piPort };
+
+  try {
+    await launchDashboardServer({
+      cliPath: resolveDashboardServerCliPath(),
+      extraArgs: buildWarmStartLaunchArgs(launchConfig),
+      stdio: { logFile: dashboardServerLogPath() },
+      starter: "Hotmilk",
+      healthTimeoutMs: WARM_START_HEALTH_TIMEOUT_MS,
+      port: launchConfig.port,
+    });
+    return warmStartResult("started", launchConfig.port, launchConfig.piPort);
+  } catch (err: unknown) {
+    const { port, piPort } = launchConfig;
+    const recheck = await isDashboardRunning(port, "localhost", WARM_START_PROBE_OPTS);
+    if (recheck.running) {
+      return warmStartResult("running", port, piPort);
+    }
+    if (err instanceof PortConflictError || err instanceof EarlyExitError) {
+      return warmStartResult("failed", port, piPort, err.message);
+    }
+    const detail = err instanceof Error ? err.message : String(err);
+    return warmStartResult("failed", port, piPort, `${detail}. See ${dashboardServerLogPath()}`);
   }
-  warmStartScheduled = true;
-  void runDashboardWarmStart();
 }

package/src/bootstrap/extensions.ts

@@ -1,5 +1,13 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { CONTEXT_STACK_EXTENSION_IDS } from "./context-stack.ts";
+import {
+  BUNDLED_EXTENSION_DEFINITIONS,
+  CONTEXT_STACK_EXTENSION_IDS,
+} from "../config/bundled-extensions.ts";
+import {
+  detectGlobalBundledExtensionSkips,
+  type GlobalBundledExtensionSkip,
+} from "./global-extension-sources.ts";
+import { bundledImportUrl } from "./resolve-bundled.ts";
 import { BUNDLED_EXTENSION_IDS, type BundledExtensionId } from "../config/hotmilk.ts";
 
 type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;
@@ -7,47 +15,53 @@ type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;
 /** Bundled deps may type against @mariozechner/pi-coding-agent; hotmilk uses @earendil-works. */
 type ExtensionModule = { default: unknown };
 
-/**
- * Load bundled extensions on demand so disabled toggles do not pay import cost.
- * Context stack registers sequentially; other enabled extensions load in parallel.
- */
-const BUNDLED_EXTENSION_LOADERS: Record<BundledExtensionId, () => Promise<ExtensionModule>> = {
-  "skill-registry": () => import("../../node_modules/gentle-pi/extensions/skill-registry.ts"),
-  "sdd-init": () => import("../../node_modules/gentle-pi/extensions/sdd-init.ts"),
-  "gentle-ai": () => import("../../node_modules/gentle-pi/extensions/gentle-ai.ts"),
-  // Same entry as upstream .pi/extensions/context-mode → build/adapters/pi/extension.js
-  "context-mode": () => import("../../node_modules/context-mode/build/adapters/pi/extension.js"),
-  "ask-user": () => import("pi-ask-user"),
-  graphify: () => import("../../node_modules/graphify-pi/extensions/graphify.ts"),
-  subagents: () => import("../../node_modules/pi-subagents/src/extension/index.ts"),
-  goal: () => import("../../node_modules/pi-goal/.pi/extensions/pi-goal/index.ts"),
-  docparser: () => import("../../node_modules/pi-docparser/extensions/docparser/index.ts"),
-  obsidian: () => import("../../node_modules/@haispeed/pi-obsidian/extensions/obsidian-cli.ts"),
-  "cursor-provider": () => import("../../node_modules/@netandreus/pi-cursor-provider/index.ts"),
-  btw: () => import("../../node_modules/pi-btw/extensions/btw.ts"),
-  simplify: () => import("../../node_modules/pi-simplify/dist/index.js"),
-  "rtk-optimizer": () => import("../../node_modules/pi-rtk-optimizer/index.ts"),
-  "mcp-adapter": () => import("../../node_modules/pi-mcp-adapter/index.ts"),
-  "planning-with-files": () =>
-    import("../../node_modules/@tomxprime/planning-with-files/extensions/planning-with-files/index.ts"),
-  caveman: () => import("../../node_modules/pi-caveman/extensions/caveman.ts"),
-  "red-green": () => import("../../node_modules/pi-red-green/dist/index.js"),
-  "agent-dashboard": () =>
-    import("../../node_modules/@blackbelt-technology/pi-agent-dashboard/packages/extension/src/bridge.ts"),
-  "web-access": () => import("../../node_modules/pi-web-access/index.ts"),
-  "pi-flows": () => import("../../node_modules/@blackbelt-technology/pi-flows/extensions/index.ts"),
-};
+function loadBundled(relativePath: string): () => Promise<ExtensionModule> {
+  return () => import(bundledImportUrl(relativePath));
+}
+
+/** Derived from {@link BUNDLED_EXTENSION_DEFINITIONS} — one loader per manifest row. */
+const BUNDLED_EXTENSION_LOADERS = Object.fromEntries(
+  BUNDLED_EXTENSION_DEFINITIONS.map((definition) => [
+    definition.id,
+    loadBundled(definition.module),
+  ]),
+) as Record<BundledExtensionId, () => Promise<ExtensionModule>>;
 
 async function registerOne(pi: ExtensionAPI, id: BundledExtensionId): Promise<void> {
   const mod = await BUNDLED_EXTENSION_LOADERS[id]();
   await (mod.default as ExtensionFactory)(pi);
 }
 
+export type RegisterBundledExtensionsOptions = {
+  cwd?: string;
+  /** Precomputed skips (tests); defaults to scanning Pi settings. */
+  globalSkips?: GlobalBundledExtensionSkip[];
+};
+
+export type RegisterBundledExtensionsResult = {
+  globalSkips: GlobalBundledExtensionSkip[];
+};
+
 export async function registerBundledExtensions(
   pi: ExtensionAPI,
   enabled: Record<BundledExtensionId, boolean>,
-): Promise<void> {
-  const enabledIds = new Set(BUNDLED_EXTENSION_IDS.filter((id) => enabled[id]));
+  options: RegisterBundledExtensionsOptions = {},
+): Promise<RegisterBundledExtensionsResult> {
+  const globalSkips =
+    options.globalSkips ?? detectGlobalBundledExtensionSkips({ cwd: options.cwd });
+  const skipById = new Map(globalSkips.map((skip) => [skip.id, skip] as const));
+
+  const enabledIds = new Set<BundledExtensionId>();
+  const appliedSkips: GlobalBundledExtensionSkip[] = [];
+  for (const id of BUNDLED_EXTENSION_IDS) {
+    if (!enabled[id]) continue;
+    const skip = skipById.get(id);
+    if (skip) {
+      appliedSkips.push(skip);
+      continue;
+    }
+    enabledIds.add(id);
+  }
 
   for (const id of CONTEXT_STACK_EXTENSION_IDS) {
     if (enabledIds.has(id)) {
@@ -56,5 +70,14 @@ export async function registerBundledExtensions(
     }
   }
 
+  if (enabledIds.has("agent-dashboard")) {
+    enabledIds.delete("agent-dashboard");
+    const { ensureDashboardWarmStarted } = await import("./dashboard.ts");
+    await ensureDashboardWarmStarted();
+    await registerOne(pi, "agent-dashboard");
+  }
+
   await Promise.all([...enabledIds].map((id) => registerOne(pi, id)));
+
+  return { globalSkips: appliedSkips };
 }