hotmilk 0.1.13 → 0.1.15

package/src/bootstrap/dashboard.ts

@@ -1,3 +1,11 @@
+/**
+ * Dashboard warm-start and config migration.
+ *
+ * Prepares the bundled agent-dashboard extension by migrating the upstream
+ * default port, disabling zrok when unavailable, and launching the server so
+ * the bridge extension sees a healthy dashboard on session start.
+ */
+
 import { execSync } from "node:child_process";
 import { createRequire } from "node:module";
 import fs from "node:fs";
@@ -35,28 +43,49 @@ const WARM_START_PROBE_OPTS = {
 
 const WARM_START_HEALTH_TIMEOUT_MS = 60_000;
 
+/** @returns the path to the dashboard server log file under `~/.pi/dashboard`. */
 export function dashboardServerLogPath(): string {
   return path.join(os.homedir(), ".pi", "dashboard", "server.log");
 }
 
-/** Bridge auto-start only waits 2s; warm-start uses 30s readiness. */
+/**
+ * Resolve the bundled `@blackbelt-technology/pi-agent-dashboard` server CLI.
+ *
+ * @returns absolute path to `pi-dashboard.mjs`.
+ */
 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). */
+/**
+ * Resolve the dashboard server entry script used by {@link launchDashboardServer}.
+ *
+ * @returns absolute path to the server CLI source.
+ */
 export function resolveDashboardServerCliPath(): string {
   const pkgJson = require.resolve("@blackbelt-technology/pi-dashboard-server/package.json");
   return path.join(path.dirname(pkgJson), "src", "cli.ts");
 }
 
+/**
+ * Build command-line args for a warm-start launch.
+ *
+ * @param config - dashboard config (port + pi gateway port)
+ * @returns CLI args like `["--port", "8102", "--pi-port", "9999"]`
+ */
 export function buildWarmStartLaunchArgs(
   config: Pick<DashboardConfig, "port" | "piPort">,
 ): string[] {
   return ["--port", String(config.port), "--pi-port", String(config.piPort)];
 }
 
+/**
+ * Probe whether a TCP port is currently free.
+ *
+ * @param port - port to test
+ * @param host - interface to bind (default: 127.0.0.1)
+ */
 export function isTcpPortFree(port: number, host = "127.0.0.1"): Promise<boolean> {
   return new Promise((resolve) => {
     const server = net.createServer();
@@ -68,7 +97,14 @@ export function isTcpPortFree(port: number, host = "127.0.0.1"): Promise<boolean
   });
 }
 
-/** Pick a free pi gateway port when the configured default is already taken. */
+/**
+ * Pick a free pi gateway port descending from a preferred value.
+ *
+ * @param preferred - starting port
+ * @param isFree - port probe function (default: {@link isTcpPortFree})
+ * @param maxAttempts - how many ports to try
+ * @returns the first free port, or `preferred` if none are found
+ */
 export async function resolveAvailablePiPort(
   preferred: number,
   isFree: (port: number) => Promise<boolean> = isTcpPortFree,
@@ -86,6 +122,12 @@ export async function resolveAvailablePiPort(
   return preferred;
 }
 
+/**
+ * Persist the chosen pi gateway port to dashboard config.
+ *
+ * @param piPort - port to save
+ * @returns whether the file was actually changed
+ */
 export function persistDashboardPiPort(piPort: number): boolean {
   ensureConfig();
   const raw = readDashboardConfigRaw();
@@ -97,6 +139,7 @@ export function persistDashboardPiPort(piPort: number): boolean {
   return true;
 }
 
+/** Decision made by {@link resolveDashboardWarmStartDecision}. */
 export type DashboardWarmStartDecision = "skip-running" | "skip-conflict" | "launch";
 
 /** When TCP is bound but /api/health is not ready yet (cold boot). */
@@ -112,6 +155,17 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * Decide whether the dashboard needs a warm-start launch.
+ *
+ * Skips when already running, waits briefly for a cold boot to become ready,
+ * and treats persistent occupancy as a conflict.
+ *
+ * @param port - dashboard HTTP port
+ * @param probe - running-state probe (default: `isDashboardRunning`)
+ * @param isFree - TCP port probe (default: {@link isTcpPortFree})
+ * @param opts - wait/poll timing overrides
+ */
 export async function resolveDashboardWarmStartDecision(
   port: number,
   probe: typeof isDashboardRunning = isDashboardRunning,
@@ -153,6 +207,7 @@ export async function resolveDashboardWarmStartDecision(
   return "launch";
 }
 
+/** @returns whether the `zrok` binary is available on `$PATH`. */
 export function isZrokOnPath(): boolean {
   try {
     execSync("command -v zrok", { stdio: "ignore" });
@@ -174,6 +229,7 @@ function writeDashboardConfigRaw(raw: Record<string, unknown>): void {
   fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
 }
 
+/** Result of {@link applyHotmilkDashboardDefaults}. */
 export type ApplyHotmilkDashboardDefaultsResult = {
   updated: boolean;
   path: string;
@@ -181,7 +237,13 @@ export type ApplyHotmilkDashboardDefaultsResult = {
 
 /**
  * Apply hotmilk-specific dashboard defaults to a parsed config object.
- * Preserves custom ports; only migrates upstream default 8000 → {@link HOTMILK_DASHBOARD_PORT}.
+ *
+ * Preserves custom ports; only migrates upstream default `8000` to
+ * {@link HOTMILK_DASHBOARD_PORT}. Disables the zrok tunnel when zrok is missing.
+ *
+ * @param raw - parsed dashboard config
+ * @param opts - optional zrok availability override
+ * @returns whether any changes were made
  */
 export function applyHotmilkDashboardDefaultsToRaw(
   raw: Record<string, unknown>,
@@ -209,8 +271,9 @@ export function applyHotmilkDashboardDefaultsToRaw(
 }
 
 /**
- * Seed hotmilk dashboard defaults into ~/.pi/dashboard/config.json:
- * port 8102 (when still on upstream 8000) and disable zrok when the binary is missing.
+ * Seed hotmilk dashboard defaults into `~/.pi/dashboard/config.json`.
+ *
+ * @returns whether the file was updated
  */
 export function applyHotmilkDashboardDefaults(): ApplyHotmilkDashboardDefaultsResult {
   ensureConfig();
@@ -227,11 +290,12 @@ export function applyHotmilkDashboardDefaults(): ApplyHotmilkDashboardDefaultsRe
 /** Dedupes concurrent warm-start only; each session_start/reload re-probes. */
 let warmStartInFlight: Promise<DashboardWarmStartResult> | undefined;
 
-/** @internal Clears in-flight warm-start dedupe (tests). */
+/** Reset the in-flight warm-start promise so tests can re-launch. */
 export function resetDashboardWarmStartForTests(): void {
   warmStartInFlight = undefined;
 }
 
+/** Result returned by {@link ensureDashboardWarmStarted}. */
 export type DashboardWarmStartResult = {
   status: "running" | "started" | "skipped-conflict" | "failed";
   port: number;
@@ -249,8 +313,12 @@ function warmStartResult(
 }
 
 /**
- * Start the dashboard via shared launcher (60s readiness) and wait until
- * the bridge extension loads so its 2s auto-start sees a healthy server.
+ * Start the dashboard via shared launcher and wait until it is ready.
+ *
+ * Concurrent calls are deduplicated. The bridge extension then sees a healthy
+ * server during its short auto-start probe.
+ *
+ * @returns warm-start outcome
  */
 export async function ensureDashboardWarmStarted(): Promise<DashboardWarmStartResult> {
   if (warmStartInFlight) {
@@ -318,7 +386,14 @@ async function runDashboardWarmStart(): Promise<DashboardWarmStartResult> {
   }
 }
 
-/** Doctor checks ~/.pi-dashboard; hotmilk warm-start uses bundled jiti instead. */
+/**
+ * Warn when the dashboard doctor may flag hotmilk-managed warm-start.
+ *
+ * Hotmilk uses bundled jiti, so legacy `~/.pi-dashboard` warnings can be ignored
+ * when `/api/health` is healthy.
+ *
+ * @param result - warm-start result
+ */
 export function logHotmilkDashboardDoctorHint(result: DashboardWarmStartResult): void {
   if (result.status !== "running" && result.status !== "started") {
     return;

package/src/bootstrap/defaults.ts

@@ -1,11 +1,25 @@
+/**
+ * Persona / language defaults bootstrap.
+ *
+ * Seeds a project-level Gentle AI persona file from hotmilk config and injects
+ * a language hint into the system prompt when `defaults.language` is set.
+ */
+
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { ResolvedDefaults } from "../config/hotmilk.ts";
 
+/** Warning shown when caveman terse-mode clashes with Japanese language default. */
 export const CAVEMAN_JA_CONFLICT_MESSAGE =
   "caveman is on while defaults.language is ja — caveman adds English terse rules that fight the Japanese language hint. Turn off caveman (/mode), clear defaults.language, or use /caveman off.";
 
+/**
+ * Detect the caveman + Japanese language conflict.
+ *
+ * @param cavemanEnabled - whether caveman toggle is on
+ * @param language - configured language hint
+ */
 export function shouldWarnCavemanJaConflict(
   cavemanEnabled: boolean,
   language: string | undefined,
@@ -13,6 +27,12 @@ export function shouldWarnCavemanJaConflict(
   return cavemanEnabled && language?.trim().toLowerCase() === "ja";
 }
 
+/**
+ * Write `.pi/gentle-ai/persona.json` from resolved defaults when absent.
+ *
+ * @param cwd - project root
+ * @param defaults - resolved defaults containing persona mode
+ */
 export function seedPersonaFromDefaults(cwd: string, defaults: ResolvedDefaults): void {
   const path = join(cwd, ".pi", "gentle-ai", "persona.json");
   if (existsSync(path)) {
@@ -22,6 +42,12 @@ export function seedPersonaFromDefaults(cwd: string, defaults: ResolvedDefaults)
   writeFileSync(path, `${JSON.stringify({ mode: defaults.persona }, null, 2)}\n`, "utf8");
 }
 
+/**
+ * Register handlers that inject the configured language into system prompts.
+ *
+ * @param pi - Pi extension API
+ * @param defaults - resolved defaults
+ */
 export function registerDefaultsHandlers(pi: ExtensionAPI, defaults: ResolvedDefaults): void {
   if (!defaults.language) {
     return;

package/src/bootstrap/extensions.ts

@@ -32,23 +32,32 @@ async function registerOne(pi: ExtensionAPI, id: BundledExtensionId): Promise<vo
   await (mod.default as ExtensionFactory)(pi);
 }
 
+/** Options controlling how bundled extensions are registered. */
 export type RegisterBundledExtensionsOptions = {
   cwd?: string;
   /** Precomputed skips (tests); defaults to scanning Pi settings. */
   globalSkips?: GlobalBundledExtensionSkip[];
+  /** When false, only global Pi settings are scanned (trust-safe startup). */
+  includeProjectSettings?: boolean;
 };
 
+/** Result of bundled-extension registration, including skipped ids. */
 export type RegisterBundledExtensionsResult = {
   globalSkips: GlobalBundledExtensionSkip[];
 };
 
+/** Register all enabled bundled extensions with the Pi extension API. */
 export async function registerBundledExtensions(
   pi: ExtensionAPI,
   enabled: Record<BundledExtensionId, boolean>,
   options: RegisterBundledExtensionsOptions = {},
 ): Promise<RegisterBundledExtensionsResult> {
   const globalSkips =
-    options.globalSkips ?? detectGlobalBundledExtensionSkips({ cwd: options.cwd });
+    options.globalSkips ??
+    detectGlobalBundledExtensionSkips({
+      cwd: options.cwd,
+      includeProjectSettings: options.includeProjectSettings ?? true,
+    });
   const skipById = new Map(globalSkips.map((skip) => [skip.id, skip] as const));
 
   const enabledIds = new Set<BundledExtensionId>();

package/src/bootstrap/global-extension-sources.ts

@@ -1,3 +1,9 @@
+/**
+ * Detect bundled extensions that the user already installed globally or locally.
+ *
+ * Skips registering those extensions a second time through hotmilk.
+ */
+
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -9,14 +15,20 @@ import { BUNDLED_EXTENSION_IDS, type BundledExtensionId } from "../config/hotmil
 
 const PI_PROJECT_CONFIG_DIR = ".pi";
 
+/** A bundled extension that should be skipped because it is already installed. */
 export type GlobalBundledExtensionSkip = {
   id: BundledExtensionId;
   packageName: string;
 };
 
+/** Options for reading Pi settings files. */
 export type CollectGlobalExtensionSourcesOptions = {
+  /** Project root for resolving local package paths. */
   cwd?: string;
+  /** Override `$HOME` resolution. */
   homedir?: string;
+  /** When false, skip project `.pi/settings.json` (Pi project trust gate). */
+  includeProjectSettings?: boolean;
 };
 
 function isLocalPackageEntry(entry: string): boolean {
@@ -62,7 +74,14 @@ function resolvePackageNameFromLocalPath(entry: string, baseDir: string): string
   }
 }
 
-/** Parse `npm:@scope/pkg@1.2.3` → `@scope/pkg`, or `npm:pkg` → `pkg`. */
+/**
+ * Extract the package name from a Pi `npm:` settings entry.
+ *
+ * @example `npm:@scope/pkg@1.2.3` → `@scope/pkg`
+ * @example `npm:pkg` → `pkg`
+ *
+ * @param entry - raw settings entry
+ */
 export function parseNpmPackageName(entry: string): string | null {
   const trimmed = entry.trim();
   if (!trimmed.startsWith("npm:")) {
@@ -99,12 +118,20 @@ function readSettingsEntries(settingsPath: string): string[] {
   }
 }
 
-/** Collect npm package names referenced by Pi settings (global + project). */
+/**
+ * Collect npm package names referenced by Pi settings (global + project).
+ *
+ * Resolves local package paths to their `package.json` `name`.
+ *
+ * @param options - settings search options
+ * @returns set of installed package names, excluding hotmilk itself
+ */
 export function collectInstalledPackageNamesFromPiSettings(
   options: CollectGlobalExtensionSourcesOptions = {},
 ): Set<string> {
   const home = options.homedir ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
   const cwd = options.cwd ?? process.cwd();
+  const includeProjectSettings = options.includeProjectSettings ?? true;
   const names = new Set<string>();
 
   const sources: Array<{ settingsPath: string; baseDir: string }> = [
@@ -112,9 +139,15 @@ export function collectInstalledPackageNamesFromPiSettings(
       settingsPath: path.join(home, ".pi", "agent", "settings.json"),
       baseDir: path.join(home, ".pi", "agent"),
     },
-    { settingsPath: path.join(cwd, PI_PROJECT_CONFIG_DIR, "settings.json"), baseDir: cwd },
   ];
 
+  if (includeProjectSettings) {
+    sources.push({
+      settingsPath: path.join(cwd, PI_PROJECT_CONFIG_DIR, "settings.json"),
+      baseDir: cwd,
+    });
+  }
+
   for (const { settingsPath, baseDir } of sources) {
     for (const entry of readSettingsEntries(settingsPath)) {
       const npmName = parseNpmPackageName(entry);
@@ -136,7 +169,13 @@ export function collectInstalledPackageNamesFromPiSettings(
   return names;
 }
 
-/** Bundled ids that should not register because Pi settings already provide the package. */
+/**
+ * Find bundled ids that should not register because Pi settings already
+ * provide the same package.
+ *
+ * @param options - settings search options
+ * @returns list of bundled ids to skip and the package that replaces them
+ */
 export function detectGlobalBundledExtensionSkips(
   options: CollectGlobalExtensionSourcesOptions = {},
 ): GlobalBundledExtensionSkip[] {

package/src/bootstrap/graph.ts

@@ -1,8 +1,20 @@
+/**
+ * Graphify stale-graph warnings.
+ *
+ * Warns the user at session start when `graphify-out/needs_update` exists.
+ */
+
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { ResolvedGraphSettings } from "../config/hotmilk.ts";
 
+/**
+ * Register the session_start handler that warns about stale graphify output.
+ *
+ * @param pi - Pi extension API
+ * @param settings - resolved graph settings
+ */
 export function registerGraphHandlers(pi: ExtensionAPI, settings: ResolvedGraphSettings): void {
   if (!settings.warnOnStale) {
     return;

package/src/bootstrap/project-trust.ts

@@ -0,0 +1,55 @@
+import type {
+  ExtensionAPI,
+  ProjectTrustContext,
+  ProjectTrustEventResult,
+} from "@earendil-works/pi-coding-agent";
+import type { ResolvedProjectTrust } from "../config/hotmilk.ts";
+
+const HOTMILK_TRUST_PROMPT = (cwd: string): string =>
+  `Trust this project for hotmilk?\n\n${cwd}\n\nEnables: .pi/settings.json, project extensions, .agents/skills, gentle-ai files under .pi/. Decline keeps global hotmilk bundles only.`;
+
+/**
+ * Resolve the trust decision for a project based on hotmilk project-trust settings.
+ *
+ * @param settings - resolved project trust settings
+ * @param ctx - project trust context
+ * @param cwd - current working directory
+ * @returns promise resolving to trust decision result
+ */
+export function resolveProjectTrustDecision(
+  settings: ResolvedProjectTrust,
+  ctx: ProjectTrustContext,
+  cwd: string,
+): Promise<ProjectTrustEventResult> {
+  switch (settings.mode) {
+    case "always":
+      return Promise.resolve({ trusted: "yes", remember: settings.remember });
+    case "never":
+      return Promise.resolve({ trusted: "no", remember: settings.remember });
+    case "prompt":
+      if (!ctx.hasUI) {
+        return Promise.resolve({ trusted: "undecided" });
+      }
+      return ctx.ui.confirm(HOTMILK_TRUST_PROMPT(cwd), "Trust project").then((trusted) => ({
+        trusted: trusted ? "yes" : "no",
+        remember: trusted ? settings.remember : false,
+      }));
+    default:
+      return Promise.resolve({ trusted: "undecided" });
+  }
+}
+
+/**
+ * Register the Pi project-trust event handler.
+ *
+ * @param pi - Pi extension API
+ * @param settings - resolved project trust settings
+ */
+export function registerProjectTrustHandlers(
+  pi: ExtensionAPI,
+  settings: ResolvedProjectTrust,
+): void {
+  pi.on("project_trust", async (event, ctx): Promise<ProjectTrustEventResult> => {
+    return resolveProjectTrustDecision(settings, ctx, event.cwd);
+  });
+}

package/src/bootstrap/resolve-bundled.ts

@@ -1,3 +1,10 @@
+/**
+ * Resolution helpers for bundled extension modules.
+ *
+ * Bundled deps may be nested under hotmilk or hoisted next to it; these helpers
+ * walk the package tree to find them without depending on npm internals.
+ */
+
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -30,7 +37,13 @@ function findHotmilkPackageRoot(fromModuleUrl: string): string {
   throw new Error("Cannot locate hotmilk package root");
 }
 
-/** Split `pkg/subpath` — supports scoped packages (`@scope/name/...`). */
+/**
+ * Split a bundled module specifier into package name and subpath.
+ *
+ * Supports scoped packages (`@scope/name/...`) and the `hotmilk/` prefix.
+ *
+ * @param relativePath - specifier like `pkg/subpath` or `@scope/pkg/subpath`
+ */
 export function parseBundledModulePath(relativePath: string): { pkgName: string; subpath: string } {
   if (relativePath.startsWith(HOTMILK_MODULE_PREFIX)) {
     return {
@@ -50,8 +63,15 @@ export function parseBundledModulePath(relativePath: string): { pkgName: string;
 }
 
 /**
- * Resolve a bundled dependency file whether npm nested it under hotmilk or hoisted
- * it next to hotmilk (e.g. `~/.pi/npm/node_modules/context-mode`).
+ * Resolve a bundled dependency file on disk.
+ *
+ * Handles both npm-nested (`.../hotmilk/node_modules/pkg/...`) and hoisted
+ * (`.../node_modules/pkg/...`) layouts.
+ *
+ * @param relativePath - bundled module specifier
+ * @param fromModuleUrl - module URL to start the search from (default: `import.meta.url`)
+ * @returns absolute path to the resolved file
+ * @throws when the module cannot be located
  */
 export function resolveBundledModule(
   relativePath: string,
@@ -100,7 +120,11 @@ export function resolveBundledModule(
   throw new Error(`Cannot resolve bundled module "${relativePath}" from hotmilk`);
 }
 
-/** Dynamic import URL for a bundled extension entry (works with nested and hoisted installs). */
+/**
+ * Build a `file://` URL for a bundled module suitable for dynamic `import()`.
+ *
+ * @param relativePath - bundled module specifier
+ */
 export function bundledImportUrl(relativePath: string): string {
   return pathToFileURL(resolveBundledModule(relativePath)).href;
 }

package/src/bootstrap/session.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { applyContextStackOnSessionStart } from "./context-stack.ts";
+import { detectGlobalBundledExtensionSkips } from "./global-extension-sources.ts";
 import { seedAgentMcpJsonIfMissing } from "../config/mcp.ts";
 import { AGENT_HOTMILK_CONFIG_LABEL, seedHotmilkConfigIfMissing } from "../config/hotmilk.ts";
 import type { HotmilkRuntime } from "../config/runtime.ts";
@@ -10,12 +11,61 @@ import {
   shouldWarnCavemanJaConflict,
 } from "./defaults.ts";
 
+/** Message shown when hotmilk config is seeded. */
 const HOTMILK_SEEDED_MESSAGE = `Created ${AGENT_HOTMILK_CONFIG_LABEL} (toggle bundled extensions with /mode, then /reload).`;
+/**
+ * Format error message for hotmilk config parse failures.
+ *
+ * @param path - config file path
+ * @param error - error message
+ * @returns formatted error message
+ */
 const HOTMILK_PARSE_ERROR_MESSAGE = (path: string, error: string): string =>
   `Failed to parse ${path}: ${error}. Using default extension toggles.`;
+/**
+ * Message shown when MCP config is seeded.
+ *
+ * @param path - seeded MCP config path
+ * @returns formatted message
+ */
 const MCP_SEEDED_MESSAGE = (path: string): string =>
   `Created ${path} from hotmilk MCP template (add servers for pi-mcp-adapter; context-mode uses the extension bridge).`;
 
+/**
+ * Format message for project trust skips.
+ *
+ * @param skips - global extension skips
+ * @returns formatted message or undefined if no skips
+ */
+function formatProjectTrustSkipMessage(
+  skips: HotmilkRuntime["globalExtensionSkips"],
+): string | undefined {
+  if (skips.length === 0) {
+    return undefined;
+  }
+  const rows = skips.map((skip) => `${skip.id}: project ${skip.packageName}`).join("\n");
+  return `Project settings also provide bundled packages (run /reload to dedupe):\n${rows}`;
+}
+
+/**
+ * Detect bundled extensions that are provided only by project settings.
+ *
+ * @param cwd - current working directory
+ * @returns project-only bundled extension skips
+ */
+function detectProjectOnlyBundledSkips(cwd: string): HotmilkRuntime["globalExtensionSkips"] {
+  const globalOnly = detectGlobalBundledExtensionSkips({ cwd, includeProjectSettings: false });
+  const withProject = detectGlobalBundledExtensionSkips({ cwd, includeProjectSettings: true });
+  const globalIds = new Set(globalOnly.map((skip) => skip.id));
+  return withProject.filter((skip) => !globalIds.has(skip.id));
+}
+
+/**
+ * Format message for global extension skips.
+ *
+ * @param skips - global extension skips
+ * @returns formatted message or undefined if no skips
+ */
 function formatGlobalExtensionSkipsMessage(
   skips: HotmilkRuntime["globalExtensionSkips"],
 ): string | undefined {
@@ -26,6 +76,7 @@ function formatGlobalExtensionSkipsMessage(
   return `Bundled extensions skipped (Pi settings already provide the package):\n${rows}`;
 }
 
+/** Register hotmilk session-start handlers (seed config, footer, context stack, MCP). */
 export function registerSessionHandlers(pi: ExtensionAPI, runtime: HotmilkRuntime): void {
   const termProgram = process.env.TERM_PROGRAM ?? "none";
 
@@ -43,7 +94,7 @@ export function registerSessionHandlers(pi: ExtensionAPI, runtime: HotmilkRuntim
       uiNotify(HOTMILK_PARSE_ERROR_MESSAGE(runtime.configPath, runtime.configError), "warning");
     }
 
-    if (runtime.extensionToggles["gentle-ai"]) {
+    if (runtime.extensionToggles["gentle-ai"] && ctx.isProjectTrusted()) {
       seedPersonaFromDefaults(ctx.cwd, runtime.defaults);
     }
 
@@ -54,6 +105,15 @@ export function registerSessionHandlers(pi: ExtensionAPI, runtime: HotmilkRuntim
       uiNotify(globalSkipMessage, "info");
     }
 
+    if (ctx.isProjectTrusted()) {
+      const projectSkipMessage = formatProjectTrustSkipMessage(
+        detectProjectOnlyBundledSkips(ctx.cwd),
+      );
+      if (projectSkipMessage) {
+        uiNotify(projectSkipMessage, "warning");
+      }
+    }
+
     if (shouldWarnCavemanJaConflict(runtime.extensionToggles.caveman, runtime.defaults.language)) {
       uiNotify(CAVEMAN_JA_CONFLICT_MESSAGE, "warning");
     }

package/src/bootstrap/subagents-doctor.ts

@@ -1,3 +1,10 @@
+/**
+ * Direct `/subagents-doctor` command registration.
+ *
+ * Bypasses the upstream slash-event bridge so the doctor report works even
+ * when `state.lastUiContext` is unset after `/reload`.
+ */
+
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -77,6 +84,11 @@ function buildDirectDoctorReport(
  * reads `state.lastUiContext` instead of the command handler's `ctx`. After `/reload`
  * that context can be unset while the command still runs — override with a direct report.
  */
+/**
+ * Register the `/subagents-doctor` Pi command with a direct report builder.
+ *
+ * @param pi - Pi extension API
+ */
 export async function registerSubagentsDoctorCommand(pi: ExtensionAPI): Promise<void> {
   await ensureChainRunsDir();