pi-legion 2.0.0 → 2.0.2

package/skills/pi-legion/SKILL.md

@@ -32,14 +32,20 @@ directly.
 
 ## Legion visualization
 
-In an interactive Pi session, `/legion` opens the paged Legion tree. Navigate
-with `j`/`k` or the arrow keys, use Enter/Space to expand or collapse, `/` to
-search, and PageUp/PageDown to scroll; `q` or Esc closes the tree. Press `o` on
-the selected node, or use a component-routed mouse click in the full-screen
-tree, to open its live overlay. `/legion <name>` opens a node directly. If
-short names are ambiguous, use the full node ID shown in command completion.
-Esc closes an overlay and unsubscribes its node's live feed. OSC 8 links are
-visual anchors only; they do not open overlays or route clicks.
+In an interactive Pi session, bare `/legion` opens the **galaxy / tok-s / log**
+full view (when a viz snapshot is available and you did not pass `--tree`).
+Tab switches panes; arrows move or scroll; Enter selects an agent; `o` opens
+its live overlay; `q` or Esc closes. `/legion --tree` opens the classic paged
+tree (`j`/`k`, Enter/Space fold, `/` search, PageUp/PageDown). `/legion <name>`
+opens a node overlay directly; if short names are ambiguous, use the full node
+ID from completion. `/legion status` prints the whole tree in chat (same lines
+as `legion_tree`); `/legion status <name>` prints one node like
+`subagent({ action: "status", name })`. Esc closes an overlay and unsubscribes
+its live feed. OSC 8 links are visual anchors only.
+
+To stop live children yourself: `/legion stop` (or `/legion stop <name>`), idle
+Esc with an empty editor (confirm "Stop N running subagents?"), or `x` then `y`
+on the selected live agent in the `/legion` view or overlay.
 
 ## Tree tools and phases
 
@@ -92,7 +98,15 @@ subagent({ action: "resume", name: "worker-0" })
 subagent({ action: "retire", name: "worker-0" })
 ```
 
+A person can read that same status without a tool call: `/legion status` for
+the tree, `/legion status <name>` for one child.
+
 For a blocked extension UI request, the RPC supervisor bubbles the request up
 to the root Pi UI for human response by default. A child completion or a
 `legion_mail` message is not a substitute for checking its saved result and
 machine-recorded state.
+
+`pi --print` and JSON mode wait for live async children during session
+shutdown, up to each child's turn timeout. That keeps a just-spawned child
+from being retired before its first assistant message. To put the child's
+result in the same print turn, use `wait`, `collect`, or `async: false`.

package/src/agents/agents.ts

@@ -63,12 +63,24 @@ export const BUILTIN_AGENTS_DIR = path.resolve(
  * or vendored roles without copying them into the writable user agent dir. These
  * load as `user`-level, at LOWER precedence than the real user directory, so a
  * user's own definition of the same name still wins.
+ *
+ * Canonical env: `PI_LEGION_EXTRA_AGENT_DIRS`. The Herdr-era name
+ * `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS` remains a compatibility alias for at
+ * least one minor version. When both are set, the new name wins (old ignored).
  */
-export const EXTRA_AGENT_DIRS_ENV = "PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS";
+export const EXTRA_AGENT_DIRS_ENV = "PI_LEGION_EXTRA_AGENT_DIRS";
 
-/** Split `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS` into absolute directory paths. */
-function extraAgentDirs(): string[] {
-	const raw = process.env[EXTRA_AGENT_DIRS_ENV];
+/** @deprecated Use {@link EXTRA_AGENT_DIRS_ENV} (`PI_LEGION_EXTRA_AGENT_DIRS`). */
+export const LEGACY_EXTRA_AGENT_DIRS_ENV = "PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS";
+
+let legacyExtraAgentDirsWarned = false;
+
+/** @internal Reset one-shot deprecation warn (unit tests). */
+export function resetExtraAgentDirsDeprecationWarnForTests(): void {
+	legacyExtraAgentDirsWarned = false;
+}
+
+function splitExtraAgentDirEntries(raw: string | undefined): string[] {
 	if (!raw) return [];
 	return raw.split(path.delimiter).flatMap((entry) => {
 		const trimmed = entry.trim();
@@ -76,6 +88,49 @@ function extraAgentDirs(): string[] {
 	});
 }
 
+function envHasContent(value: string | undefined): value is string {
+	return value !== undefined && value.trim() !== "";
+}
+
+/**
+ * Resolve PATH-style extra agent dirs from env.
+ *
+ * Priority: `PI_LEGION_EXTRA_AGENT_DIRS` overrides
+ * `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS` when both are set. Setting the legacy
+ * name alone still works and emits one stderr deprecation warning per process.
+ */
+export function resolveExtraAgentDirs(
+	env: NodeJS.ProcessEnv = process.env,
+	warn: (message: string) => void = (message) => console.warn(message),
+): string[] {
+	const modern = env[EXTRA_AGENT_DIRS_ENV];
+	const legacy = env[LEGACY_EXTRA_AGENT_DIRS_ENV];
+	const hasModern = envHasContent(modern);
+	const hasLegacy = envHasContent(legacy);
+
+	if (hasLegacy && !legacyExtraAgentDirsWarned) {
+		legacyExtraAgentDirsWarned = true;
+		if (hasModern) {
+			warn(
+				`[pi-legion] Both ${EXTRA_AGENT_DIRS_ENV} and ${LEGACY_EXTRA_AGENT_DIRS_ENV} are set; using ${EXTRA_AGENT_DIRS_ENV} (new name wins). Remove the deprecated ${LEGACY_EXTRA_AGENT_DIRS_ENV}.`,
+			);
+		} else {
+			warn(
+				`[pi-legion] ${LEGACY_EXTRA_AGENT_DIRS_ENV} is deprecated; use ${EXTRA_AGENT_DIRS_ENV}. The old name remains as a compatibility alias for at least one minor version.`,
+			);
+		}
+	}
+
+	if (hasModern) return splitExtraAgentDirEntries(modern);
+	if (hasLegacy) return splitExtraAgentDirEntries(legacy);
+	return [];
+}
+
+/** Split env extra-agent-dir entries into absolute directory paths. */
+function extraAgentDirs(): string[] {
+	return resolveExtraAgentDirs();
+}
+
 const VALID_KINDS: ReadonlySet<string> = new Set(AGENT_KINDS);
 
 const VALID_ON_BLOCKED: ReadonlySet<string> = new Set([
@@ -600,7 +655,7 @@ export interface DiscoverOptions {
  *
  * Precedence, lowest to highest:
  *   builtin (shipped with the package)
- *   extra dirs (`PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS`)
+ *   extra dirs (`PI_LEGION_EXTRA_AGENT_DIRS`, legacy `PI_HERDR_SUBAGENTS_EXTRA_AGENT_DIRS`)
  *   user    (`~/.pi/agent/agents`)
  *   project (`<nearest>/.pi/agents`)
  *

package/src/api.ts

@@ -34,6 +34,7 @@ export {
 	BUILTIN_AGENT_NAMES,
 	BUILTIN_AGENTS_DIR,
 	EXTRA_AGENT_DIRS_ENV,
+	LEGACY_EXTRA_AGENT_DIRS_ENV,
 	discoverAgents,
 	findAgent,
 	findNearestProjectAgentsDir,
@@ -41,6 +42,7 @@ export {
 	formatAgentRoster,
 	loadAgentsFromDir,
 	parseAgentDocument,
+	resolveExtraAgentDirs,
 } from "./agents/agents.ts";
 export type { DiscoverOptions } from "./agents/agents.ts";
 export {

package/src/extension/legion-commands.ts

@@ -4,11 +4,16 @@ import { matchesKey, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { resolveStopTarget, runLegionStop, stopCompletions, type StopDeps } from "./legion-stop.ts";
 import {
 	DOCTOR_SECTIONS,
+	LEGION_SLASH_HELP_LINES,
 	expectedModelsFromSettings,
 	parseDoctorSections,
 	runLegionDoctor,
 	type DoctorRuntimeSnapshot,
 } from "./legion-doctor.ts";
+import {
+	renderLegionStatus,
+	type LegionChildStatusFacts,
+} from "./legion-status.ts";
 import { ALLOW_NESTED_ENV } from "./budget.ts";
 import {
 	createAgentsCommand,
@@ -91,6 +96,11 @@ export interface LegionCommandDeps {
 	supervisor: RpcEventSource;
 	/** Graceful retire via the subagent `stop` action (see legion-stop.ts). */
 	stop?: (params: { name?: string; all?: boolean }) => Promise<{ ok: boolean; text: string }>;
+	/**
+	 * Persisted child snapshot used by `subagent({ action: "status" })`.
+	 * Undefined when this process has no run-store record for `name`.
+	 */
+	childStatus?: (name: string, cwd: string) => LegionChildStatusFacts | undefined;
 	/** Existing user-facing subcommand handlers; absent only in isolated tests. */
 	commands?: {
 		team: TeamCommandDeps;
@@ -181,6 +191,32 @@ function nodeLabel(nodeId: string, name: string): string {
 	return `${name} (${nodeId})`;
 }
 
+/** Completions for `/legion status <prefix>`: tree nodes, then live jobs the tree does not already name. */
+function statusArgumentCompletions(
+	prefix: string,
+	deps: LegionCommandDeps,
+): Array<{ value: string; label: string }> {
+	const nodes = deps.runtime.treeNodes();
+	const out: Array<{ value: string; label: string }> = [];
+	const seen = new Set<string>();
+	const add = (value: string, label: string): void => {
+		if (!value.startsWith(prefix) || seen.has(value)) return;
+		seen.add(value);
+		out.push({ value: `status ${value}`, label });
+	};
+	for (const node of nodes) {
+		const value = nodes.filter((candidate) => candidate.name === node.name).length > 1
+			? node.id
+			: node.name;
+		add(value, nodeLabel(node.id, node.name));
+	}
+	for (const job of deps.runtime.activeJobs()) {
+		if (job.state === "retired") continue;
+		add(job.name, `${job.name} (live)`);
+	}
+	return out;
+}
+
 function resolveNode(
 	nodes: readonly TreeNodeSnapshot[],
 	query: string,
@@ -483,7 +519,7 @@ function buildDoctorReport(
 				: undefined,
 		})),
 		stopAvailable: Boolean(deps.stop),
-		idleEscWired: true,
+		idleEscWired: false,
 		legionTools: ["subagent", "vexillatio"],
 		allowNestedEnv: process.env[ALLOW_NESTED_ENV] === "1",
 	};
@@ -525,15 +561,7 @@ export function registerLegionCommand(
 	};
 	const helpText = [
 		"Legion commands:",
-		"  /legion team [list|use <name> [--global]|create <name> a,b,c [--global]]",
-		"  /legion agents [user|project|both]",
-		"  /legion on | off — enable/disable subagents for this session (status is shown after each run)",
-		"  /scout-guard | /no-scout-guard — session override for the main-session scout guard",
-		"  /legion summary [--all] [<name>]",
-		"  /legion doctor [section]",
-		"  /legion stop [name]",
-		"  /legion --tree | /legion <node>",
-		"  /legion help",
+		...LEGION_SLASH_HELP_LINES.map((line) => `  ${line}`),
 	].join("\n");
 	pi.registerCommand(LEGION_COMMAND, {
 		description: "Open the Legion view or manage teams, agents, subagent runs, and settings",
@@ -554,6 +582,9 @@ export function registerLegionCommand(
 				return stopCompletions(rest, deps.runtime.activeJobs(), deps.runtime.treeNodes())
 					.map((item) => ({ value: `stop ${item.value}`, label: item.label }));
 			}
+			if (/^status\s/i.test(trimmed)) {
+				return statusArgumentCompletions(trimmed.replace(/^status\s+/i, ""), deps);
+			}
 			if (/^doctor(\s|$)/i.test(prefix)) {
 				const rest = prefix.replace(/^doctor\s*/i, "");
 				return DOCTOR_SECTIONS
@@ -570,6 +601,12 @@ export function registerLegionCommand(
 					}
 				}
 			}
+			if ("status".startsWith(prefix)) {
+				verbs.push({
+					value: "status",
+					label: "status [name] — tree summary, or one node (same text as subagent status)",
+				});
+			}
 			if ("doctor".startsWith(prefix)) {
 				verbs.push({ value: "doctor", label: "doctor [section] — full self-check (extensions/models/spawn/memory/tools/storage/runtime)" });
 			}
@@ -601,6 +638,23 @@ export function registerLegionCommand(
 				sendSlashText(pi, helpText);
 				return;
 			}
+			if (normalizedKeyword === "status") {
+				const report = renderLegionStatus({
+					query: rest.join(" "),
+					nodes: deps.runtime.treeNodes(),
+					jobs: deps.runtime.activeJobs(),
+					lookupChild: deps.childStatus
+						? (name) => deps.childStatus!(name, ctx.cwd)
+						: undefined,
+					now: Date.now(),
+				});
+				if (!report.ok) {
+					notify(ctx, report.text, "error");
+					return;
+				}
+				sendSlashText(pi, report.text);
+				return;
+			}
 			if (/^doctor(?:\s|$)/i.test(query)) {
 				const sectionArg = query.replace(/^doctor\s*/i, "").trim();
 				const report = buildDoctorReport(deps, ctx.cwd, sectionArg || undefined);

package/src/extension/legion-doctor.ts

@@ -2,8 +2,9 @@
  * `/legion doctor` and `subagent action=diagnose`: broad self-check for
  * pi-legion (inspired by `pi list` / `pi auth check` / `pi --help`).
  *
- * Sections are filterable via `/legion doctor <section>` so the main agent can
- * pull only what it needs, then act on the structured Next steps.
+ * Sections are filterable via `/legion doctor [section]` or
+ * `subagent({ action: "diagnose", section })` so the main agent can pull only
+ * what it needs, then act on the structured Next steps.
  */
 
 import { execFileSync } from "node:child_process";
@@ -13,11 +14,16 @@ import * as path from "node:path";
 import {
 	CHILD_EXTENSIONS_ENV,
 	CHILD_INHERIT_EXTENSIONS_ENV,
-	childExtraExtensions,
-	childInheritsExtensions,
 	buildPiArgs,
+	childExtraExtensions,
 	childGuardExtensionPath,
+	childInheritsExtensions,
+	collectChildExtensions,
 } from "../runs/args.ts";
+import {
+	collectRoleToolExtensionIssues,
+	roleToolGateNextSteps,
+} from "../runs/role-tool-gates.ts";
 import { getAgentDir } from "../agents/paths.ts";
 import {
 	CHILD_MAX_OLD_SPACE_ENV,
@@ -50,6 +56,24 @@ import { IDLE_STOP_HINT, IDLE_STOP_HINT_SHORT } from "./legion-stop.ts";
 import type { AgentConfig } from "../shared/types.ts";
 import { recentSpawnFailures, type SpawnFailureRecord } from "./spawn-hints.ts";
 
+/**
+ * Canonical slash surface. `/legion help` and the doctor Tools section both
+ * print these lines so the two lists cannot drift.
+ */
+export const LEGION_SLASH_HELP_LINES = [
+	"/legion — open the Legion view (TUI)",
+	"/legion status [name] — whole-tree summary, or one node (same text as subagent status)",
+	"/legion team [list|use <name> [--global]|create <name> a,b,c [--global]]",
+	"/legion agents [user|project|both]",
+	"/legion on | /legion off — enable/disable subagents for this session (status is shown after each run)",
+	"/scout-guard | /no-scout-guard — session override for the main-session scout guard",
+	"/legion summary [--all] [<name>]",
+	"/legion doctor [section]",
+	"/legion stop [name|all]",
+	"/legion --tree | /legion <node>",
+	"/legion help",
+] as const;
+
 export const DOCTOR_SECTIONS = [
 	"summary",
 	"extensions",
@@ -64,6 +88,15 @@ export const DOCTOR_SECTIONS = [
 
 export type DoctorSection = (typeof DOCTOR_SECTIONS)[number];
 
+/**
+ * Doctor warns when `.hygiene-last.json` is missing or older than this.
+ * Shorter than the 14-day run-retention default so a week without a root
+ * restart surfaces before retention pruning goes quiet (#85).
+ */
+export const HYGIENE_SWEEP_STALE_DAYS = 7;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
 export interface DoctorPackage {
 	source: string;
 	name: string;
@@ -352,17 +385,10 @@ export function parseDoctorSections(raw: string | undefined): DoctorSection[] |
 	return out.length ? out : undefined;
 }
 
-function extensionsForRole(agent: AgentConfig, env: NodeJS.ProcessEnv, extras: string[]): string[] {
+function extensionsForRole(agent: AgentConfig, env: NodeJS.ProcessEnv, _extras: string[]): string[] {
 	if (childInheritsExtensions(agent, env)) return ["(all host-discovered extensions)"];
-	const seen = new Set<string>();
-	const out: string[] = [];
-	for (const ext of [...(agent.extensions ?? []), ...(agent.subagentOnlyExtensions ?? []), ...extras, childGuardExtensionPath()]) {
-		const resolved = path.resolve(ext);
-		if (seen.has(resolved)) continue;
-		seen.add(resolved);
-		out.push(ext);
-	}
-	return out;
+	// Same effective list as `buildPiArgs` / `collectChildExtensions` (#89 builtin:codemode).
+	return collectChildExtensions(agent, env);
 }
 
 function scanOrphanTemps(storeRoot: string): { total: number; orphanDead: number; live: number; unknown: number; samples: string[] } {
@@ -401,6 +427,61 @@ function formatBytes(n: number): string {
 	return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
 }
 
+interface HygieneLastMarker {
+	at?: number;
+	removedTempDirs?: number;
+	prunedRuns?: number;
+	deletedEvents?: number;
+	freedBytes?: number;
+	errors?: number;
+}
+
+function readHygieneLast(storeRoot: string): HygieneLastMarker | undefined {
+	const last = readJson(path.join(storeRoot, HYGIENE_LAST_FILE));
+	if (!last || typeof last !== "object") return undefined;
+	return last as HygieneLastMarker;
+}
+
+function hygieneSweepAt(last: HygieneLastMarker | undefined): number | undefined {
+	return typeof last?.at === "number" && Number.isFinite(last.at) ? last.at : undefined;
+}
+
+/**
+ * Mirrors `envNumber` in hygiene.ts: blank or non-finite / negative values
+ * fall back to the built-in default, so doctor labels those as default.
+ */
+function hygieneConfigSource(env: NodeJS.ProcessEnv, key: string): "default" | "env" {
+	const raw = env[key]?.trim();
+	if (!raw) return "default";
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 0 ? "env" : "default";
+}
+
+function formatHygieneToggleSource(env: NodeJS.ProcessEnv): string {
+	const raw = env[HYGIENE_ENV.disable]?.trim();
+	if (!raw) return `default; ${HYGIENE_ENV.disable}`;
+	return `env ${HYGIENE_ENV.disable}=${raw}`;
+}
+
+/** Effective `resolveHygieneConfig()` values, each tagged default or env. */
+function formatHygieneConfigLines(env: NodeJS.ProcessEnv): string[] {
+	const hy = resolveHygieneConfig(env);
+	const rows: Array<[string, string, string]> = [
+		["retentionDays", `${hy.retentionDays}d`, HYGIENE_ENV.retentionDays],
+		["staleNodeHours", `${hy.staleNodeHours}h`, HYGIENE_ENV.staleNodeHours],
+		["legacyTempHours", `${hy.legacyTempHours}h`, HYGIENE_ENV.legacyTempHours],
+		["eventRetentionDays", `${hy.eventRetentionDays}d`, HYGIENE_ENV.eventRetentionDays],
+		["eventMaxRows", String(hy.eventMaxRows), HYGIENE_ENV.eventMaxRows],
+	];
+	return rows.map(([label, value, envKey]) => {
+		const source = hygieneConfigSource(env, envKey);
+		return `    ${label}=${value} (${source === "env" ? `env ${envKey}` : "default"})`;
+	});
+}
+
+const HYGIENE_SWEEP_HINT =
+	`Restart the root pi session so startup hygiene runs, or check ${HYGIENE_ENV.disable}=0.`;
+
 export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 	const env = options.env ?? process.env;
 	const agentDir = options.agentDir ?? getAgentDir();
@@ -524,20 +605,12 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 	}
 
 	const agents = options.agents ?? (options.sampleAgent ? [options.sampleAgent] : []);
+	// #97: extensible tool→extension gates (lens #70, codemode #89, …).
 	for (const agent of agents) {
-		const needsLens = (agent.tools ?? []).some((t) => /lens|symbol_search|project_report|module_report|read_symbol|read_enclosing/i.test(t));
-		const exts = extensionsForRole(agent, env, extras);
-		const hasLens =
-			childInheritsExtensions(agent, env) ||
-			exts.some((e) => /pi-lens/i.test(e));
-		if (needsLens && !hasLens && !inheritGlobal) {
-			issues.push({
-				severity: "warning",
-				code: "ROLE_MISSING_LENS",
-				section: "extensions",
-				message: `Role "${agent.name}" lists lens tools but would not load pi-lens under --no-extensions.`,
-				fix: `Add pi-lens to ${agent.name}'s extensions: frontmatter, or to ${CHILD_EXTENSIONS_ENV}.`,
-			});
+		const inherits = childInheritsExtensions(agent, env) || inheritGlobal;
+		const exts = inherits ? [] : extensionsForRole(agent, env, extras);
+		for (const issue of collectRoleToolExtensionIssues(agent, exts, { inheritsExtensions: inherits })) {
+			issues.push(issue);
 		}
 	}
 
@@ -575,6 +648,7 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 
 	const storeRoot = options.storeRoot ?? (options.cwd ? path.join(options.cwd, ".pi-subagents") : undefined);
 	const orphans = storeRoot ? scanOrphanTemps(storeRoot) : undefined;
+	const hygieneLast = storeRoot ? readHygieneLast(storeRoot) : undefined;
 	if (orphans && orphans.orphanDead > 0) {
 		issues.push({
 			severity: "info",
@@ -583,6 +657,19 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 			message: `${orphans.orphanDead} rpc-child temp dir(s) have a dead owner (startup hygiene will remove them).`,
 		});
 	}
+	const sweepAt = hygieneSweepAt(hygieneLast);
+	const sweepStale = storeRoot !== undefined && (sweepAt === undefined || Date.now() - sweepAt > HYGIENE_SWEEP_STALE_DAYS * DAY_MS);
+	if (sweepStale) {
+		issues.push({
+			severity: "info",
+			code: "HYGIENE_SWEEP_STALE",
+			section: "storage",
+			message: sweepAt === undefined
+				? `No ${HYGIENE_LAST_FILE} marker — startup hygiene has not recorded a sweep.`
+				: `Last hygiene sweep ${new Date(sweepAt).toISOString()} is older than ${HYGIENE_SWEEP_STALE_DAYS} days.`,
+			fix: HYGIENE_SWEEP_HINT,
+		});
+	}
 
 	const verify = inspectVerifySlots(resolveVerifyQueueConfig(env));
 	const staleVerify = verify.holders.filter((h) => h.alive === false);
@@ -718,29 +805,28 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 
 	if (want(selected, "tools")) {
 		push("## Tools / commands");
-		push("- slash: `/legion` (view), `/legion doctor [section]`, `/legion stop [name|all]`, `/legion --tree`, `/legion <name>`");
+		push("- slash:");
+		for (const line of LEGION_SLASH_HELP_LINES) push(`    ${line}`);
 		push(`- stop wired: ${runtime.stopAvailable === undefined ? "(unknown)" : runtime.stopAvailable ? "yes" : "no"}`);
 		push(`- idle Esc stop wired: ${runtime.idleEscWired === undefined ? "(unknown)" : runtime.idleEscWired ? "yes" : "no"}`);
-		push(`- idle strip hints: "${IDLE_STOP_HINT}" / short "${IDLE_STOP_HINT_SHORT}"`);
+		push(`- stop strip hints: "${IDLE_STOP_HINT}" / short "${IDLE_STOP_HINT_SHORT}"`);
 		push(`- legion tools registered: ${(runtime.legionTools ?? ["(unknown — typically subagent, vexillatio, legion-* mail/tools)"]).join(", ")}`);
-		push("- diagnose: `subagent({ action: \"diagnose\" })` or `subagent({ action: \"diagnose\" })` with section via `/legion doctor <section>`");
+		push("- slash: `/legion doctor [section]`");
+		push("- tool: `subagent({ action: \"diagnose\", section? })` — optional section filter (same as `/legion doctor [section]`)");
 		push("");
 	}
 
 	if (want(selected, "storage")) {
 		push("## Storage / hygiene");
-		push(`- hygiene enabled: ${hygieneEnabled(env)}`);
-		const hy = resolveHygieneConfig(env);
-		push(`- retention: runs ${hy.retentionDays}d, stale nodes ${hy.staleNodeHours}h, legacy temps ${hy.legacyTempHours}h, events ${hy.eventRetentionDays}d / max ${hy.eventMaxRows}`);
-		push(`- env: ${HYGIENE_ENV.disable}, ${HYGIENE_ENV.retentionDays}, ${HYGIENE_ENV.staleNodeHours}, …`);
+		push(`- hygiene enabled: ${hygieneEnabled(env)} (${formatHygieneToggleSource(env)})`);
+		push("- resolveHygieneConfig():");
+		for (const line of formatHygieneConfigLines(env)) push(line);
 		if (!storeRoot) {
 			push("- storeRoot: (not provided — pass cwd/storeRoot for db/orphan stats)");
 		} else {
 			push(`- storeRoot: ${homeize(storeRoot, home)}`);
-			const lastPath = path.join(storeRoot, HYGIENE_LAST_FILE);
-			const last = readJson(lastPath) as { at?: number; removedTempDirs?: number; prunedRuns?: number; deletedEvents?: number; freedBytes?: number; errors?: number } | undefined;
-			if (last?.at) {
-				push(`- last sweep: ${new Date(last.at).toISOString()} (removedTemps=${last.removedTempDirs ?? 0}, prunedRuns=${last.prunedRuns ?? 0}, deletedEvents=${last.deletedEvents ?? 0}, freed=${formatBytes(last.freedBytes ?? 0)}, errors=${last.errors ?? 0})`);
+			if (sweepAt !== undefined) {
+				push(`- last sweep: ${new Date(sweepAt).toISOString()} (removedTemps=${hygieneLast?.removedTempDirs ?? 0}, prunedRuns=${hygieneLast?.prunedRuns ?? 0}, deletedEvents=${hygieneLast?.deletedEvents ?? 0}, freed=${formatBytes(hygieneLast?.freedBytes ?? 0)}, errors=${hygieneLast?.errors ?? 0})`);
 			} else {
 				push("- last sweep: (no marker yet — written on next root-session startup hygiene)");
 			}
@@ -817,15 +903,16 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 			steps.push(`export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}  # then restart pi`);
 			steps.push(`# or role frontmatter extensions: […] / inheritExtensions: true (more RAM)`);
 		}
-		if (issues.some((i) => i.code === "ROLE_MISSING_LENS")) {
-			steps.push("Add pi-lens extension path to roles that list lens_* tools, or to PI_LEGION_CHILD_EXTENSIONS.");
-		}
+		steps.push(...roleToolGateNextSteps(issues));
 		if (issues.some((i) => i.code === "MEMORY_GATE_WOULD_REFUSE")) {
 			steps.push("Stop idle children (`/legion stop`) or lower/disable PI_LEGION_MIN_FREE_MEM_MB before launching more.");
 		}
 		if (issues.some((i) => i.code === "ORPHAN_TEMPS")) {
 			steps.push("Orphan temps clear on next root session start; or restart pi to trigger hygiene.");
 		}
+		if (selected.has("storage") && issues.some((i) => i.code === "HYGIENE_SWEEP_STALE")) {
+			steps.push(HYGIENE_SWEEP_HINT);
+		}
 		if (issues.some((i) => i.code === "STALE_VERIFY_SLOTS")) {
 			steps.push("Stale verify locks are reclaimed automatically; delete slot-*.lock under the lock dir if a slot stays stuck.");
 		}