hotmilk 0.1.11 → 0.1.12

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) |
-| **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) (side channel — see below), [@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`.
 
@@ -91,7 +91,7 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
     "context-mode": true,
     "ask-user": true,
     "graphify": true,
-    "subagents": false,
+    "subagents": true,
     "goal": true,
     "docparser": true,
     "obsidian": true,
@@ -122,23 +122,48 @@ Or ask Pi to use the planning-with-files skill. The extension maintains `task_pl
 }
 ```
 
-| Key / area                        | Behavior                                                                                                                                                                                        |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `extensions.*`                    | Set to `false` to skip registering that bundled extension                                                                                                                                       |
-| `extensions.subagents`            | Default `false`. When `true`, imports pi-subagents (~10s). Use with `gentle-ai` for delegation                                                                                                  |
-| `extensions.context-mode`         | Default `true`. Prefer `ctx_*` for large outputs (see project context-window rules)                                                                                                             |
-| `extensions.rtk-optimizer`        | Default `false`. Bash/read/grep output compaction; enable with `context-mode` for leftover shell output. Install [`rtk` CLI](https://github.com/rtk-ai/rtk) for command rewrite (`/rtk verify`) |
-| `extensions.goal` … `mcp-adapter` | Integration / perf extensions (formerly always loaded via `pi.extensions`; now toggled like other bundled deps)                                                                                 |
-| Enabled extensions                | Loaded **in parallel** on session start (faster than sequential import when many toggles are on)                                                                                                |
-| `graph.warnOnStale`               | Notify when `graphify-out/needs_update` exists                                                                                                                                                  |
-| `graph.autoSuggestUpdate`         | Append `graphify update .` to that notification                                                                                                                                                 |
-| `defaults.persona`                | Seeds `.pi/gentle-ai/persona.json` when missing (`gentleman` \| `neutral`)                                                                                                                      |
-| `defaults.language`               | Appends a project language hint to the system prompt each turn                                                                                                                                  |
-| `mcp.seedOnStart`                 | Copy `mcp.json` template into `~/.pi/agent/mcp.json` when missing (empty template; for pi-mcp-adapter)                                                                                          |
-| `extensions.mcp-adapter`          | Default `false`. Enable only when you want MCP servers from `~/.pi/agent/mcp.json` (do not duplicate context-mode)                                                                              |
+| Key / area                        | Behavior                                                                                                                                                                                               |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `extensions.*`                    | Set to `false` to skip registering that bundled extension                                                                                                                                              |
+| `extensions.subagents`            | Default `true`. Imports pi-subagents (~10s). Use with `gentle-ai` for delegation; set `false` for faster startup without Task tools                                                                    |
+| `extensions.btw`                  | Default `true`. Side conversation via `/btw` while main runs. **Delegate implementation to subagents**; use BTW for quick human questions. See [pi-btw coexistence](#pi-btw-with-subagents-default-on) |
+| `extensions.context-mode`         | Default `true`. Prefer `ctx_*` for large outputs (see project context-window rules)                                                                                                                    |
+| `extensions.rtk-optimizer`        | Default `false`. Bash/read/grep output compaction; enable with `context-mode` for leftover shell output. Install [`rtk` CLI](https://github.com/rtk-ai/rtk) for command rewrite (`/rtk verify`)        |
+| `extensions.goal` … `mcp-adapter` | Integration / perf extensions (formerly always loaded via `pi.extensions`; now toggled like other bundled deps)                                                                                        |
+| Enabled extensions                | Loaded **in parallel** on session start (faster than sequential import when many toggles are on)                                                                                                       |
+| `graph.warnOnStale`               | Notify when `graphify-out/needs_update` exists                                                                                                                                                         |
+| `graph.autoSuggestUpdate`         | Append `graphify update .` to that notification                                                                                                                                                        |
+| `defaults.persona`                | Seeds `.pi/gentle-ai/persona.json` when missing (`gentleman` \| `neutral`)                                                                                                                             |
+| `defaults.language`               | Appends a project language hint to the system prompt each turn                                                                                                                                         |
+| `mcp.seedOnStart`                 | Copy `mcp.json` template into `~/.pi/agent/mcp.json` when missing (empty template; for pi-mcp-adapter)                                                                                                 |
+| `extensions.mcp-adapter`          | Default `false`. Enable only when you want MCP servers from `~/.pi/agent/mcp.json` (do not duplicate context-mode)                                                                                     |
 
 **MCP (default):** `context-mode` extension registers `ctx_*` via its built-in bridge (same module as [upstream `.pi/extensions/context-mode`](https://github.com/mksglu/context-mode/tree/main/.pi/extensions/context-mode), loaded from `build/adapters/pi/extension.js`). Hotmilk removes any `context-mode` server from `~/.pi/agent/mcp.json` when the extension is on. Enable `mcp-adapter` only for **other** MCP servers—not a second context-mode entry.
 
+### pi-btw with subagents (default on)
+
+Both **`subagents`** and **`btw`** default to **on**. They do not share commands or extension IDs; hotmilk loads them in parallel.
+
+| Do this                                         | Tool                                                                                         |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Exploration, implementation, review, SDD phases | **subagents** (`Task`, `/run`, `/chain`; use `worktree: true` when running parallel writers) |
+| Ask a quick question while main is working      | **`/btw`** or **`/btw:tangent`** (`Alt+/` toggles BTW ↔ main)                                |
+| Bring BTW results back to the main thread       | **`/btw:inject`**                                                                            |
+
+BTW runs a **separate** Pi session. hotmilk wraps upstream pi-btw (`src/extensions/btw.ts`):
+
+- **`subagents: true` (default):** read-biased tools only (`read`, `grep`, `find`, `ls`, `bash`) — no main-cwd `edit`/`write`.
+- **`graphify: true` + `graphify-out/graph.json`:** adds **`graphify_query`** (CLI-backed) for architecture questions.
+- **`context-mode: true`:** adds **`ctx_search`** proxy to the main session knowledge base (read-only).
+- Inherited prompts drop main-session harness noise (gentle-ai orchestrator, graphify rules, caveman); project AGENTS.md stays.
+- Still **no** `ctx_execute`, Task, or MCP inside BTW — use main/subagents for heavy ctx work.
+
+Global `npm:pi-btw` in Pi settings skips the hotmilk shim (standard dedupe). Prefer bundled hotmilk so BTW gets prompt/tool patches via `createAgentSession` hook.
+
+During subagent chains, avoid BTW file edits on the main cwd; use read-only or `:tangent` until workers finish.
+
+Set `"btw": false` in `/mode` if you want delegation only with no side channel.
+
 ### Optional extensions (off by default)
 
 Enable in `/mode` or set the key to `true` in `hotmilk.json`, then `/reload`.
@@ -160,7 +185,7 @@ Enable in `/mode` or set the key to `true` in `hotmilk.json`, then `/reload`.
 - 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.
+- **`ERR TypeScript loader` / jiti or tsx not found** (paths under `~/.pi-dashboard/node_modules/`): the dashboard doctor checks the legacy managed install dir and hardcodes port **8000** in its messages. Hotmilk runs on **8102** with bundled jiti from `pi-dashboard-server`. If `http://localhost:8102/api/health` returns `{"ok":true}`, the doctor error is a false positive — hotmilk logs a hint on warm-start. To silence it entirely: run **Help → Setup** once, or `npm install jiti` under `~/.pi-dashboard` after setup creates that tree.
 
 ### Cursor models (optional, not bundled)
 

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.12",
   "description": "hotmilk — Pi package bundling gentle-pi, context-mode, graphify, subagents, and bundled extension toggles via hotmilk.json",
   "keywords": [
     "hotmilk",
@@ -96,7 +96,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/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.`,
+  );
+}

package/src/bootstrap/extensions.ts

@@ -72,11 +72,25 @@ export async function registerBundledExtensions(
 
   if (enabledIds.has("agent-dashboard")) {
     enabledIds.delete("agent-dashboard");
-    const { ensureDashboardWarmStarted } = await import("./dashboard.ts");
-    await ensureDashboardWarmStarted();
+    const { ensureDashboardWarmStarted, logHotmilkDashboardDoctorHint } =
+      await import("./dashboard.ts");
+    const warmStart = await ensureDashboardWarmStarted();
+    if (warmStart.status === "failed" || warmStart.status === "skipped-conflict") {
+      const detail = warmStart.message ?? `port ${warmStart.port}`;
+      console.warn(`[hotmilk] Dashboard warm-start ${warmStart.status}: ${detail}`);
+    } else {
+      logHotmilkDashboardDoctorHint(warmStart);
+    }
     await registerOne(pi, "agent-dashboard");
   }
 
+  if (enabledIds.has("btw")) {
+    const { setHotmilkBtwConfig } = await import("./btw.ts");
+    setHotmilkBtwConfig({ extensionToggles: enabled });
+    await registerOne(pi, "btw");
+    enabledIds.delete("btw");
+  }
+
   await Promise.all([...enabledIds].map((id) => registerOne(pi, id)));
 
   return { globalSkips: appliedSkips };

package/src/bootstrap/resolve-bundled.ts

@@ -1,9 +1,43 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+const HOTMILK_MODULE_PREFIX = "hotmilk/";
+
+function findHotmilkPackageRoot(fromModuleUrl: string): string {
+  let dir = dirname(fileURLToPath(fromModuleUrl));
+
+  while (true) {
+    const pkgJsonPath = join(dir, "package.json");
+    if (existsSync(pkgJsonPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as { name?: string };
+        if (pkg.name === "hotmilk") {
+          return dir;
+        }
+      } catch {
+        // ignore invalid package.json while walking up
+      }
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+
+  throw new Error("Cannot locate hotmilk package root");
+}
+
 /** Split `pkg/subpath` — supports scoped packages (`@scope/name/...`). */
 export function parseBundledModulePath(relativePath: string): { pkgName: string; subpath: string } {
+  if (relativePath.startsWith(HOTMILK_MODULE_PREFIX)) {
+    return {
+      pkgName: "hotmilk",
+      subpath: relativePath.slice(HOTMILK_MODULE_PREFIX.length),
+    };
+  }
   if (relativePath.startsWith("@")) {
     const parts = relativePath.split("/");
     return { pkgName: `${parts[0]}/${parts[1]}`, subpath: parts.slice(2).join("/") };
@@ -23,6 +57,16 @@ export function resolveBundledModule(
   relativePath: string,
   fromModuleUrl = import.meta.url,
 ): string {
+  if (relativePath.startsWith(HOTMILK_MODULE_PREFIX)) {
+    const local = join(
+      findHotmilkPackageRoot(fromModuleUrl),
+      relativePath.slice(HOTMILK_MODULE_PREFIX.length),
+    );
+    if (existsSync(local)) {
+      return local;
+    }
+  }
+
   const { pkgName, subpath } = parseBundledModulePath(relativePath);
   let dir = dirname(fileURLToPath(fromModuleUrl));
 
@@ -39,6 +83,13 @@ export function resolveBundledModule(
       }
     }
 
+    if (pkgName === "hotmilk") {
+      const inTree = join(dir, subpath);
+      if (existsSync(inTree)) {
+        return inTree;
+      }
+    }
+
     const parent = dirname(dir);
     if (parent === dir) {
       break;

package/src/config/bundled-extensions.ts

@@ -100,7 +100,7 @@ export const BUNDLED_EXTENSION_DEFINITIONS = [
   {
     id: "btw",
     package: { packageName: "pi-btw" },
-    module: "pi-btw/extensions/btw.ts",
+    module: "hotmilk/src/extensions/btw.ts",
     group: "Integrations",
   },
   {

package/src/extensions/btw.ts

@@ -0,0 +1,17 @@
+/**
+ * hotmilk shim for pi-btw: patches createAgentSession before upstream loads so BTW
+ * sub-sessions get lighter prompts, read-biased tools when subagents are on, and
+ * optional graphify_query — without vendoring pi-btw (~2k lines).
+ */
+import type { ExtensionAPI, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { installHotmilkBtwSessionHook } from "../bootstrap/btw.ts";
+import { bundledImportUrl } from "../bootstrap/resolve-bundled.ts";
+
+installHotmilkBtwSessionHook();
+
+const upstreamModule = await import(bundledImportUrl("pi-btw/extensions/btw.ts"));
+const upstream = upstreamModule.default as ExtensionFactory;
+
+export default async function hotmilkBtw(pi: ExtensionAPI): Promise<void> {
+  await upstream(pi);
+}

package/src/index.ts

@@ -11,12 +11,14 @@ import { registerGraphHandlers } from "./bootstrap/graph.ts";
 import { registerSessionHandlers } from "./bootstrap/session.ts";
 import { registerInputCommands, routeInputCommand } from "./controller/input.ts";
 import { registerHotmilkSessionLogo } from "./ui/session-logo.ts";
+import { installHotmilkCtxSearchCapture } from "./bootstrap/btw.ts";
 
 export default async function registerHotmilk(pi: ExtensionAPI): Promise<void> {
   const runtime = createHotmilkRuntime();
 
   // Register before bundled imports so session_start handlers exist when bindExtensions emits.
   registerHotmilkSessionLogo(pi);
+  installHotmilkCtxSearchCapture(pi);
 
   prepareContextStack(runtime.extensionToggles);
 

package/src/ui/github-user.ts

@@ -13,7 +13,9 @@ function githubUserFromEnv(env: NodeJS.ProcessEnv): string | undefined {
   return env.GITHUB_USER?.trim() || env.GH_USER?.trim() || undefined;
 }
 
-function githubUsernameCommands(cwd: string): Array<{ file: string; args: string[]; cwd?: string }> {
+function githubUsernameCommands(
+  cwd: string,
+): Array<{ file: string; args: string[]; cwd?: string }> {
   return [
     { file: "gh", args: ["api", "user", "-q", ".login"] },
     { file: "git", args: ["config", "--global", "github.user"] },