hotmilk 0.1.11 → 0.1.13

package/agents/reviewer.md

@@ -0,0 +1,48 @@
+---
+name: reviewer
+description: Hotmilk adversarial review — evidence, bun check, plan alignment, no scope creep
+tools: read, grep, find, ls, bash, edit, write, intercom
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+defaultReads: plan.md, progress.md
+defaultContext: fresh
+package: hotmilk
+---
+
+You are the **hotmilk** review subagent. Inspect and report with **evidence** — do not guess.
+
+## Review focus
+
+- Diff matches intent and `plan.md` (when provided).
+- **Surgical diff**: unrelated refactors, manifest/doc drift vs `bundled-extensions.ts` and README Configuration.
+- Tests and types: suggest or run `bun test` / `bun run check` when TS touched; cite failures.
+- **Extension changes**: bundled row ↔ README toggle table ↔ `bundled-extensions.ts`; competition slots respected.
+- If estimated diff >400 lines, flag **chained PR** reviewer load (gentle-ai / chained-pr).
+
+## Working rules
+
+- With pi-subagents 0.28+ acceptance gates: **reviewed** requires your independent result — worker self-attestation alone is not enough.
+- Parse fenced `acceptance-report` blocks when present; required criteria must be satisfied with cited evidence.
+- Read `plan.md`, `progress.md`, and relevant files first.
+- `bash` for read-only inspection (`git diff`, tests).
+- Review-only wins over progress writes when conflicted.
+- Small fixes allowed when parent authorized; otherwise findings only.
+- Repo-local `progress.md` scratch files are OK if untracked/gitignored.
+
+## Output format
+
+```
+## Review
+- Correct: … (evidence)
+- Fixed: … (if you applied a fix)
+- Blocker: … (must fix before merge)
+- Note: …
+```
+
+Cite `path` and line ranges. If clean, say so plainly.
+
+## Supervisor coordination
+
+`contact_supervisor` with `need_decision` when blocked. No routine completion handoffs.

package/hotmilk.json

@@ -6,7 +6,7 @@
     "context-mode": true,
     "ask-user": true,
     "graphify": true,
-    "subagents": false,
+    "subagents": true,
     "goal": true,
     "docparser": true,
     "obsidian": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotmilk",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "hotmilk — Pi package bundling gentle-pi, context-mode, graphify, subagents, and bundled extension toggles via hotmilk.json",
   "keywords": [
     "hotmilk",
@@ -19,6 +19,7 @@
   },
   "files": [
     "src",
+    "agents",
     "prompts",
     "skills",
     "themes",
@@ -30,9 +31,6 @@
   ],
   "type": "module",
   "scripts": {
-    "dashboard:start": "pi-dashboard start",
-    "dashboard:stop": "pi-dashboard stop",
-    "dashboard:status": "pi-dashboard status",
     "lint": "vp lint",
     "format": "vp fmt --write",
     "test": "vp test",
@@ -44,37 +42,41 @@
     "@haispeed/pi-obsidian": "^0.1.1",
     "@tomxprime/planning-with-files": "^1.1.0",
     "context-mode": "^1.0.151",
-    "gentle-pi": "^0.3.10",
+    "gentle-pi": "^0.4.5",
     "graphify-pi": "^0.3.0",
-    "pi-ask-user": "^0.11.1",
+    "pi-ask-user": "^0.11.2",
     "pi-btw": "^0.4.0",
     "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-mcp-adapter": "^2.9.0",
     "pi-red-green": "^0.2.2",
-    "pi-rtk-optimizer": "^0.8.1",
+    "pi-rtk-optimizer": "^0.8.2",
     "pi-simplify": "^0.2.2",
-    "pi-subagents": "^0.25.0",
+    "pi-subagents": "^0.28.0",
     "pi-tetris": "^1.3.1",
     "pi-web-access": "^0.10.7"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.78.0",
-    "@earendil-works/pi-ai": "^0.78.0",
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@earendil-works/pi-tui": "^0.78.0",
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
     "@types/node": "^22.19.19",
-    "typebox": "^1.1.39",
-    "vite-plus": "^0.1.23"
+    "typebox": "^1.2.0",
+    "vite-plus": "^0.1.24"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "^0.78.0",
-    "@earendil-works/pi-ai": "^0.78.0",
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@earendil-works/pi-tui": "^0.78.0",
-    "typebox": "^1.1.39"
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
+    "typebox": "^1.2.0"
+  },
+  "overrides": {
+    "@fastify/static": "9.1.3",
+    "@mozilla/readability": "0.6.0"
   },
   "engines": {
     "node": "22"
@@ -96,7 +98,6 @@
       "node_modules/pi-subagents/skills",
       "node_modules/pi-docparser/skills",
       "node_modules/@haispeed/pi-obsidian/skills",
-      "node_modules/pi-btw/skills",
       "node_modules/pi-ask-user/skills",
       "node_modules/pi-web-access/skills",
       "node_modules/@tomxprime/planning-with-files"

package/skills/recommend-research/SKILL.md

@@ -10,4 +10,4 @@ description: "Single entry for technology recommendations: judge scope, shortlis
 3. **Verify** — Official docs for contracts and usage; repository / local checkout when internals, edge cases, or performance matter.
 4. **Mechanics** — Web search and doc pages for reading; `ghq` or `git clone` when the tree must be local.
 
-Same repo still holds detailed playbooks under `.agents/skills/`; open them only when this flow is not enough.
+If the repo ships extra skills under `./skills/`, load those `SKILL.md` files only when this flow is not enough.

package/src/bootstrap/btw.ts

@@ -0,0 +1,395 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Type } from "@sinclair/typebox";
+import * as piSdk from "@earendil-works/pi-coding-agent";
+import {
+  createExtensionRuntime,
+  defineTool,
+  type AgentToolResult,
+  type CreateAgentSessionOptions,
+  type ExtensionAPI,
+  type ResourceLoader,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { BundledExtensionId } from "../config/bundled-extensions.ts";
+import { bundledImportUrl } from "./resolve-bundled.ts";
+
+// --- Session config (injected before btw extension loads) ---
+
+export type HotmilkBtwConfig = {
+  extensionToggles: Readonly<Record<BundledExtensionId, boolean>>;
+};
+
+let activeConfig: HotmilkBtwConfig | null = null;
+
+export function setHotmilkBtwConfig(config: HotmilkBtwConfig): void {
+  activeConfig = config;
+}
+
+export function getHotmilkBtwConfig(): HotmilkBtwConfig {
+  if (!activeConfig) {
+    throw new Error(
+      "hotmilk BTW config not initialized — registerBundledExtensions must call setHotmilkBtwConfig first",
+    );
+  }
+  return activeConfig;
+}
+
+export function resetHotmilkBtwConfigForTests(): void {
+  activeConfig = null;
+}
+
+// --- Prompt shaping ---
+
+export function stripDynamicSystemPromptFooter(systemPrompt: string): string {
+  return systemPrompt
+    .replace(/\nCurrent date and time:[^\n]*(?:\nCurrent working directory:[^\n]*)?$/u, "")
+    .replace(/\nCurrent working directory:[^\n]*$/u, "")
+    .trim();
+}
+
+const MAIN_SESSION_SECTION_MARKERS = [
+  /^## graphify\b/im,
+  /^## el Gentleman Orchestrator\b/im,
+  /^# el Gentleman Identity and Harness\b/im,
+  /^<context_window_protection>/im,
+  /^IMPORTANT: You are in CAVEMAN MODE\./im,
+  /^## SDD Session Preflight\b/im,
+  /^<behavioral_directive>/im,
+] as const;
+
+export function stripHotmilkMainSessionHarness(systemPrompt: string): string {
+  let next = systemPrompt;
+  for (const marker of MAIN_SESSION_SECTION_MARKERS) {
+    const match = marker.exec(next);
+    if (!match || match.index === undefined) continue;
+    next = next.slice(0, match.index).trimEnd();
+  }
+  return next.trim();
+}
+
+export const HOTMILK_BTW_SYSTEM_PROMPT = [
+  "You are having an aside conversation with the user, separate from their main working session.",
+  "If main session messages are provided, they are for context only — that work is being handled by another agent.",
+  "If no main session messages are provided, treat this as a fully contextless tangent thread and rely only on the user's words plus your general instructions.",
+  "Focus on answering the user's side questions, helping them think through ideas, or planning next steps.",
+  "Do not act as if you need to continue unfinished work from the main session unless the user explicitly asks you to prepare something for injection back to it.",
+  "hotmilk routing: multi-file implementation, scout/worker/review, and SDD phases belong on the main line via subagents (Task, /run, /chain) — not in BTW.",
+  "While subagents may be writing in worktrees, avoid edit/write on the main cwd unless the user explicitly asks; prefer read-only checks and :tangent for brainstorming.",
+  "ctx_search is available as a read-only proxy to the main session knowledge base — use it for timeline recall, prior decisions, and indexed content. Do not use ctx_execute, ctx_batch_execute, or ctx_purge from BTW; loading context-mode here would spawn a second MCP child.",
+].join(" ");
+
+export function buildHotmilkBtwAppendPrompt(options: {
+  graphifyEnabled: boolean;
+  subagentsEnabled: boolean;
+  contextModeEnabled: boolean;
+}): string[] {
+  const lines = [HOTMILK_BTW_SYSTEM_PROMPT];
+  if (options.contextModeEnabled) {
+    lines.push(
+      "Prefer ctx_search(queries: [...]) for session memory and indexed corpus recall instead of large bash output or re-reading raw files.",
+    );
+  }
+  if (options.graphifyEnabled) {
+    lines.push(
+      'When graphify-out/graph.json exists, prefer the graphify_query tool (or `graphify query "..."` via bash) over broad grep for architecture and cross-module questions.',
+    );
+  }
+  if (options.subagentsEnabled) {
+    lines.push(
+      "When the user asks for implementation or multi-file exploration, answer briefly in BTW if possible, then suggest /btw:inject plus a main-line Task — do not start parallel file edits here.",
+    );
+  }
+  return lines;
+}
+
+const PI_BTW_APPEND_MARKERS = [
+  "aside conversation with the user, separate from their main working session",
+  "Summarize the side conversation concisely",
+] as const;
+
+/** BTW must never load bundled extensions (context-mode → MCP fork-bomb #516). */
+function createBtwEmptyExtensionsResult() {
+  return { extensions: [], errors: [], runtime: createExtensionRuntime() };
+}
+
+function isPiBtwResourceLoader(loader: ResourceLoader): boolean {
+  const append = loader.getAppendSystemPrompt();
+  const text = (Array.isArray(append) ? append : []).join("\n");
+  return PI_BTW_APPEND_MARKERS.some((marker) => text.includes(marker));
+}
+
+function isBtwSummarizeSession(loader: ResourceLoader): boolean {
+  const append = loader.getAppendSystemPrompt();
+  const text = (Array.isArray(append) ? append : []).join("\n");
+  return text.includes("Summarize the side conversation");
+}
+
+export function adaptBtwResourceLoaderForHotmilk(
+  loader: ResourceLoader,
+  config: HotmilkBtwConfig,
+): ResourceLoader {
+  const emptyExtensions = createBtwEmptyExtensionsResult();
+  const sharedLoader = {
+    getExtensions: () => emptyExtensions,
+    getSkills: () => ({ skills: [], diagnostics: [] }),
+    getPrompts: () => ({ prompts: [], diagnostics: [] }),
+    getThemes: () => ({ themes: [], diagnostics: [] }),
+    getAgentsFiles: () => ({ agentsFiles: [] }),
+    extendResources: () => {},
+    reload: async () => {},
+  };
+
+  if (isBtwSummarizeSession(loader)) {
+    return {
+      ...sharedLoader,
+      getSystemPrompt: () => stripHotmilkMainSessionHarness(loader.getSystemPrompt() ?? ""),
+      getAppendSystemPrompt: () => loader.getAppendSystemPrompt(),
+    };
+  }
+
+  return {
+    ...sharedLoader,
+    getSystemPrompt: () => stripHotmilkMainSessionHarness(loader.getSystemPrompt() ?? ""),
+    getAppendSystemPrompt: () =>
+      buildHotmilkBtwAppendPrompt({
+        graphifyEnabled: config.extensionToggles.graphify === true,
+        subagentsEnabled: config.extensionToggles.subagents === true,
+        contextModeEnabled: config.extensionToggles["context-mode"] === true,
+      }),
+  };
+}
+
+// --- Main-session ctx_search capture (proxy target for BTW) ---
+
+type MainCtxSearchTool = {
+  description: string;
+  parameters: ToolDefinition["parameters"];
+  execute: (
+    toolCallId: string,
+    params: Record<string, unknown>,
+  ) => Promise<AgentToolResult<unknown>>;
+};
+
+let mainCtxSearchTool: MainCtxSearchTool | null = null;
+let ctxSearchCaptureInstalled = false;
+
+export function captureMainCtxSearchTool(tool: {
+  name: string;
+  description: string;
+  parameters: ToolDefinition["parameters"];
+  execute: ToolDefinition["execute"];
+}): void {
+  if (tool.name !== "ctx_search") return;
+  mainCtxSearchTool = {
+    description: tool.description,
+    parameters: tool.parameters,
+    execute: (toolCallId, params) =>
+      tool.execute(toolCallId, params as never, undefined, undefined, undefined as never),
+  };
+}
+
+export function getMainCtxSearchToolForTests(): MainCtxSearchTool | null {
+  return mainCtxSearchTool;
+}
+
+export function resetMainCtxSearchCaptureForTests(): void {
+  mainCtxSearchTool = null;
+  ctxSearchCaptureInstalled = false;
+}
+
+async function resolveMainCtxSearchTool(): Promise<MainCtxSearchTool | null> {
+  if (mainCtxSearchTool) return mainCtxSearchTool;
+  try {
+    const mod = await import(bundledImportUrl("context-mode/build/adapters/pi/extension.js"));
+    await mod._mcpBridgeReady;
+  } catch {
+    return null;
+  }
+  return mainCtxSearchTool;
+}
+
+/**
+ * Capture context-mode's main-session ctx_search registration so BTW can proxy
+ * without loading context-mode inside the BTW sub-session (fork-bomb guard #516).
+ */
+export function installHotmilkCtxSearchCapture(pi: ExtensionAPI): void {
+  if (ctxSearchCaptureInstalled) return;
+  ctxSearchCaptureInstalled = true;
+
+  const original = pi.registerTool.bind(pi);
+  pi.registerTool = (tool) => {
+    captureMainCtxSearchTool(tool);
+    return original(tool);
+  };
+}
+
+// --- Tools ---
+
+const GRAPH_JSON = join("graphify-out", "graph.json");
+
+const CTX_SEARCH_FALLBACK_PARAMS = Type.Object({
+  queries: Type.Optional(
+    Type.Array(
+      Type.String({ description: "Search queries — batch all related questions in one call." }),
+    ),
+  ),
+  query: Type.Optional(
+    Type.String({ description: "Single search query (legacy alias for queries[0])." }),
+  ),
+  limit: Type.Optional(Type.Number({ description: "Results per query (default 3)." })),
+  source: Type.Optional(
+    Type.String({ description: "Filter to an indexed source label (partial match)." }),
+  ),
+  contentType: Type.Optional(
+    Type.Union([Type.Literal("code"), Type.Literal("prose")], {
+      description: "Filter by content shape.",
+    }),
+  ),
+  sort: Type.Optional(
+    Type.Union([Type.Literal("relevance"), Type.Literal("timeline")], {
+      description: "relevance (default) or timeline for session memory.",
+    }),
+  ),
+});
+
+export function graphifyGraphExists(cwd = process.cwd()): boolean {
+  return existsSync(join(cwd, GRAPH_JSON));
+}
+
+export function resolveHotmilkBtwTools(config: HotmilkBtwConfig): string[] {
+  if (config.extensionToggles.subagents === true) {
+    return ["read", "grep", "find", "ls", "bash"];
+  }
+  return ["read", "bash", "edit", "write"];
+}
+
+function createCtxSearchProxyTool(mainTool: MainCtxSearchTool | null): ToolDefinition {
+  return defineTool({
+    name: "ctx_search",
+    label: "Search indexed content",
+    description:
+      mainTool?.description ??
+      "Search the main session knowledge base (read-only proxy). Batch related questions in queries: [...].",
+    parameters: mainTool?.parameters ?? CTX_SEARCH_FALLBACK_PARAMS,
+    execute: async (toolCallId, params) => {
+      const main = await resolveMainCtxSearchTool();
+      if (!main) {
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                "ctx_search unavailable — context-mode bridge is not ready on the main session. " +
+                "Ensure context-mode is enabled, wait for startup, or use small bounded bash output.",
+            },
+          ],
+          details: { ok: false as const },
+        };
+      }
+      return main.execute(toolCallId, params as Record<string, unknown>);
+    },
+  });
+}
+
+export function createHotmilkBtwCustomTools(config: HotmilkBtwConfig): ToolDefinition[] {
+  const tools: ToolDefinition[] = [];
+
+  if (config.extensionToggles["context-mode"] === true) {
+    tools.push(createCtxSearchProxyTool(mainCtxSearchTool));
+  }
+
+  if (config.extensionToggles.graphify !== true || !graphifyGraphExists()) {
+    return tools;
+  }
+
+  const graphifyQuery = defineTool({
+    name: "graphify_query",
+    label: "Graphify query",
+    description:
+      "Traverse graphify-out/graph.json for architecture and relationship questions. Prefer this over grep for cross-module queries.",
+    parameters: Type.Object({
+      question: Type.String({ description: "Natural-language question about the codebase graph" }),
+      dfs: Type.Optional(
+        Type.Boolean({ description: "Use depth-first traversal for dependency chains" }),
+      ),
+      budget: Type.Optional(
+        Type.Number({ description: "Optional token budget cap for the graphify answer" }),
+      ),
+    }),
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+      const args = ["query", params.question, "--graph", GRAPH_JSON];
+      if (params.dfs) args.push("--dfs");
+      if (params.budget !== undefined) args.push("--budget", String(params.budget));
+
+      try {
+        const output = execFileSync("graphify", args, {
+          cwd: ctx.cwd,
+          encoding: "utf8",
+          maxBuffer: 512 * 1024,
+          timeout: 120_000,
+        });
+        return {
+          content: [{ type: "text", text: output.trim() || "(graphify returned no output)" }],
+          details: { question: params.question, ok: true as const },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `graphify query failed: ${message}. Ensure graphify-out/graph.json exists or run graphify on the main session.`,
+            },
+          ],
+          details: { question: params.question, ok: false as const, error: message },
+        };
+      }
+    },
+  });
+
+  tools.push(graphifyQuery);
+  return tools;
+}
+
+function patchHotmilkBtwSessionOptions(
+  options: CreateAgentSessionOptions,
+): CreateAgentSessionOptions {
+  const loader = options.resourceLoader;
+  if (!loader || !isPiBtwResourceLoader(loader)) {
+    return options;
+  }
+
+  const config = getHotmilkBtwConfig();
+  const summarize = isBtwSummarizeSession(loader);
+  const next: CreateAgentSessionOptions = {
+    ...options,
+    resourceLoader: adaptBtwResourceLoaderForHotmilk(loader, config),
+  };
+
+  if (!summarize) {
+    next.tools = resolveHotmilkBtwTools(config);
+    next.customTools = createHotmilkBtwCustomTools(config);
+  }
+
+  return next;
+}
+
+let btwHookInstalled = false;
+
+/**
+ * Wrap Pi {@link createAgentSession} so pi-btw sub-sessions get hotmilk prompts/tools
+ * without vendoring the upstream extension (~2k lines).
+ */
+export function installHotmilkBtwSessionHook(): void {
+  if (btwHookInstalled) return;
+  btwHookInstalled = true;
+
+  const original = piSdk.createAgentSession.bind(piSdk);
+  const patched = async (options?: CreateAgentSessionOptions) => {
+    const resolved = options ? patchHotmilkBtwSessionOptions(options) : options;
+    return original(resolved);
+  };
+  (piSdk as { createAgentSession: typeof patched }).createAgentSession = patched;
+}

package/src/bootstrap/dashboard.ts

@@ -99,17 +99,57 @@ export function persistDashboardPiPort(piPort: number): boolean {
 
 export type DashboardWarmStartDecision = "skip-running" | "skip-conflict" | "launch";
 
+/** When TCP is bound but /api/health is not ready yet (cold boot). */
+const WARM_START_PORT_OCCUPIED_WAIT_MS = 5_000;
+const WARM_START_PORT_OCCUPIED_POLL_MS = 500;
+
+export type DashboardWarmStartDecisionOpts = {
+  occupiedWaitMs?: number;
+  occupiedPollMs?: number;
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 export async function resolveDashboardWarmStartDecision(
   port: number,
   probe: typeof isDashboardRunning = isDashboardRunning,
+  isFree: (port: number) => Promise<boolean> = isTcpPortFree,
+  opts: DashboardWarmStartDecisionOpts = {},
 ): Promise<DashboardWarmStartDecision> {
-  const status = await probe(port, "localhost", WARM_START_PROBE_OPTS);
+  const occupiedWaitMs = opts.occupiedWaitMs ?? WARM_START_PORT_OCCUPIED_WAIT_MS;
+  const occupiedPollMs = opts.occupiedPollMs ?? WARM_START_PORT_OCCUPIED_POLL_MS;
+  let status = await probe(port, "localhost", WARM_START_PROBE_OPTS);
   if (status.running) {
     return "skip-running";
   }
   if (status.portConflict) {
     return "skip-conflict";
   }
+
+  if (!(await isFree(port))) {
+    const deadline = Date.now() + occupiedWaitMs;
+    while (Date.now() < deadline) {
+      await sleep(occupiedPollMs);
+      status = await probe(port, "localhost", WARM_START_PROBE_OPTS);
+      if (status.running) {
+        return "skip-running";
+      }
+      if (status.portConflict) {
+        return "skip-conflict";
+      }
+      if (await isFree(port)) {
+        return "launch";
+      }
+    }
+    status = await probe(port, "localhost", WARM_START_PROBE_OPTS);
+    if (status.running) {
+      return "skip-running";
+    }
+    return "skip-conflict";
+  }
+
   return "launch";
 }
 
@@ -184,7 +224,13 @@ export function applyHotmilkDashboardDefaults(): ApplyHotmilkDashboardDefaultsRe
   return { updated: true, path: CONFIG_FILE };
 }
 
-let warmStartPromise: Promise<DashboardWarmStartResult> | undefined;
+/** Dedupes concurrent warm-start only; each session_start/reload re-probes. */
+let warmStartInFlight: Promise<DashboardWarmStartResult> | undefined;
+
+/** @internal Clears in-flight warm-start dedupe (tests). */
+export function resetDashboardWarmStartForTests(): void {
+  warmStartInFlight = undefined;
+}
 
 export type DashboardWarmStartResult = {
   status: "running" | "started" | "skipped-conflict" | "failed";
@@ -207,15 +253,14 @@ function warmStartResult(
  * the bridge extension loads so its 2s auto-start sees a healthy server.
  */
 export async function ensureDashboardWarmStarted(): Promise<DashboardWarmStartResult> {
-  if (warmStartPromise) {
-    return warmStartPromise;
+  if (warmStartInFlight) {
+    return warmStartInFlight;
   }
 
-  warmStartPromise = runDashboardWarmStart().catch((err) => {
-    warmStartPromise = undefined;
-    throw err;
+  warmStartInFlight = runDashboardWarmStart().finally(() => {
+    warmStartInFlight = undefined;
   });
-  return warmStartPromise;
+  return warmStartInFlight;
 }
 
 async function runDashboardWarmStart(): Promise<DashboardWarmStartResult> {
@@ -246,9 +291,12 @@ async function runDashboardWarmStart(): Promise<DashboardWarmStartResult> {
 
   const launchConfig = { port: config.port, piPort };
 
+  const cliPath = resolveDashboardServerCliPath();
+
   try {
     await launchDashboardServer({
-      cliPath: resolveDashboardServerCliPath(),
+      cliPath,
+      anchor: cliPath,
       extraArgs: buildWarmStartLaunchArgs(launchConfig),
       stdio: { logFile: dashboardServerLogPath() },
       starter: "Hotmilk",
@@ -269,3 +317,17 @@ async function runDashboardWarmStart(): Promise<DashboardWarmStartResult> {
     return warmStartResult("failed", port, piPort, `${detail}. See ${dashboardServerLogPath()}`);
   }
 }
+
+/** Doctor checks ~/.pi-dashboard; hotmilk warm-start uses bundled jiti instead. */
+export function logHotmilkDashboardDoctorHint(result: DashboardWarmStartResult): void {
+  if (result.status !== "running" && result.status !== "started") {
+    return;
+  }
+  const managedDir = path.join(os.homedir(), ".pi-dashboard");
+  if (fs.existsSync(managedDir)) {
+    return;
+  }
+  console.warn(
+    `[hotmilk] Dashboard doctor may warn about TypeScript loader or ~/.pi-dashboard — hotmilk uses bundled jiti on port ${result.port}. Ignore if http://localhost:${result.port}/api/health is ok.`,
+  );
+}