pi-legion 2.0.0 → 2.0.1

package/src/extension/scout-guard.ts

@@ -3,8 +3,11 @@
  *
  * Counts consecutive read-like tool calls in the parent session. When the
  * streak reaches N with no subagent/vexillatio dispatch in between, inject
- * one follow-up reminder. The tool_call hook only updates state; the
- * reminder is scheduled so it cannot block the current tool call.
+ * one follow-up reminder. First-class read tools (`read`, `grep`, `find`,
+ * `ls`) count the same as read-only bash; playbooks prefer those over bash,
+ * so ignoring them let a main-session scout miss the threshold. The
+ * tool_call hook only updates state; the reminder is scheduled so it cannot
+ * block the current tool call.
  *
  * Children carry PI_SUBAGENT_ROLE and must not run this logic.
  */
@@ -74,6 +77,12 @@ const PACKAGE_WRITE = new Set([
 ]);
 
 const DISPATCH_TOOLS = new Set(["subagent", "vexillatio"]);
+/**
+ * Pi built-in read-only tools (`createReadOnlyTools`): `read`, `grep`,
+ * `find`, `ls`. `find` here is the read-only search tool, not shell `find
+ * -delete` (that path is classified from bash).
+ */
+const READ_TOOLS = new Set(["read", "grep", "find", "ls"]);
 const WRITE_TOOLS = new Set(["edit", "write"]);
 
 export function initialScoutGuardState(): ScoutGuardState {
@@ -132,7 +141,7 @@ export function classifyScoutToolCall(toolName: string, input: unknown): ScoutTo
 	if (DISPATCH_TOOLS.has(toolName)) {
 		return isDispatchCall(toolName, input) ? "dispatch" : "ignore";
 	}
-	if (toolName === "read") return "read";
+	if (READ_TOOLS.has(toolName)) return "read";
 	if (WRITE_TOOLS.has(toolName)) return "write";
 	if (toolName !== "bash") return "ignore";
 	const command = record(input)?.command;

package/src/runs/args.ts

@@ -76,6 +76,8 @@ export interface BuildArgsInput {
 	sessionFile: string;
 	/** Resolved model id, may already include a `:thinking` suffix. */
 	model?: string;
+	/** Provider id for `--provider` when the resolved model id is ambiguous. */
+	modelProvider?: string;
 	thinking?: string | false;
 	/** Where to write an oversized task / system prompt. */
 	tempDir: string;
@@ -128,7 +130,17 @@ export function buildPiArgs(input: BuildArgsInput): BuildArgsResult {
 /** `--model provider/id[:thinking]`, omitted when no model resolved. */
 function pushModelArgs(args: string[], input: BuildArgsInput): void {
 	const modelArg = applyThinkingSuffix(input.model, input.thinking);
-	if (modelArg) args.push("--model", modelArg);
+	if (!modelArg) return;
+	args.push("--model", modelArg);
+	// Pin the provider so a bare model id cannot be hijacked by a colliding
+	// static provider in models.json (#123: `workbuddy/...` ids also exist under
+	// a provider with no usable auth; under `--no-extensions` the child resolved
+	// them there and died with "No API key found"). Models may carry their own
+	// slash (e.g. `any-endpoint/workbuddy/hy4-preview-ioa`), so only the longest
+	// known provider prefix qualifies; an id with no provider stays bare, and
+	// `--provider` without `--model` is rejected by pi, so both move together.
+	const provider = input.modelProvider;
+	if (provider) args.push("--provider", provider);
 }
 
 export const CHILD_INHERIT_EXTENSIONS_ENV = "PI_LEGION_CHILD_INHERIT_EXTENSIONS";
@@ -152,6 +164,60 @@ export function childInheritsExtensions(agent: Pick<AgentConfig, "inheritExtensi
 	return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
 }
 
+/** Light pi builtin that registers the `codemode` tool (`-e builtin:codemode`). */
+export const BUILTIN_CODEMODE = "builtin:codemode";
+
+/** True for `builtin:<name>` refs — must not be `path.resolve`d. */
+export function isBuiltinExtensionRef(ext: string): boolean {
+	return ext.trimStart().startsWith("builtin:");
+}
+
+/** Dedup key for an `--extension` value (path or builtin ref). */
+export function extensionDedupeKey(ext: string): string {
+	return isBuiltinExtensionRef(ext) ? ext.trim() : path.resolve(ext);
+}
+
+export function roleListsCodemode(agent: Pick<AgentConfig, "tools">): boolean {
+	return (agent.tools ?? []).some((t) => t === "codemode");
+}
+
+export function isCodemodeExtension(ext: string): boolean {
+	const t = ext.trim();
+	return t === BUILTIN_CODEMODE || t.endsWith("/" + BUILTIN_CODEMODE);
+}
+
+/**
+ * Effective `--extension` values for a child under `--no-extensions`.
+ *
+ * Includes role `extensions` / `subagentOnlyExtensions`, `PI_LEGION_CHILD_EXTENSIONS`,
+ * auto `builtin:codemode` when `tools` lists `codemode` (#89), and the child-guard.
+ */
+export function collectChildExtensions(
+	agent: Pick<AgentConfig, "tools" | "extensions" | "subagentOnlyExtensions">,
+	env: NodeJS.ProcessEnv = process.env,
+): string[] {
+	const list = [
+		...(agent.extensions ?? []),
+		...(agent.subagentOnlyExtensions ?? []),
+		...childExtraExtensions(env),
+	];
+	// #89: codemode is a light builtin (unlike heavy pi-lens). Keep tools:codemode
+	// honest when discovery is disabled via `--no-extensions`.
+	if (roleListsCodemode(agent) && !list.some(isCodemodeExtension)) {
+		list.push(BUILTIN_CODEMODE);
+	}
+	list.push(childGuardExtensionPath());
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const ext of list) {
+		const key = extensionDedupeKey(ext);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(ext);
+	}
+	return out;
+}
+
 /** `--tools a,b`, `--no-extensions` (unless inherited), plus one `--extension` per explicit extension. */
 function pushToolArgs(args: string[], agent: AgentConfig): void {
 	const tools = agent.tools?.filter(Boolean) ?? [];
@@ -164,19 +230,9 @@ function pushToolArgs(args: string[], agent: AgentConfig): void {
 	// silently inherit every extension the parent happens to have loaded
 	// (#43: each host extension such as an LSP stack costs ~1 GB per child).
 	// `--no-extensions` stops discovery; explicit `--extension` paths below
-	// (the role's list + this package for the guard / nested spawning) still load.
+	// (the role's list + auto builtin:codemode + this package for the guard) still load.
 	if (!childInheritsExtensions(agent)) args.push("--no-extensions");
-	const extensions = [
-		...(agent.extensions ?? []),
-		...(agent.subagentOnlyExtensions ?? []),
-		...childExtraExtensions(),
-		childGuardExtensionPath(),
-	];
-	const seen = new Set<string>();
-	for (const ext of extensions) {
-		const resolved = path.resolve(ext);
-		if (seen.has(resolved)) continue;
-		seen.add(resolved);
+	for (const ext of collectChildExtensions(agent)) {
 		args.push("--extension", ext);
 	}
 }

package/src/runs/orchestrator.ts

@@ -31,6 +31,7 @@ import {
 import { canUseCachedCollect } from "../extension/recycle.ts";
 import {
 	countAssistantMessages,
+	attributeParentSessionShutdown,
 	deriveOutcome,
 	emptyParsedSession,
 	extractVerdict,
@@ -51,6 +52,7 @@ import {
 	MAX_NESTED_PATH_ENTRIES,
 	type ModelOrigin,
 	type NestedPathEntry,
+	type RetireOptions,
 	type RunRecord,
 	SubagentError,
 	type Usage,
@@ -239,6 +241,8 @@ export class Orchestrator {
 	private readonly children = new Map<string, ChildRecord>();
 	private readonly nameCounter = new Map<string, number>();
 	private readonly pendingWaits = new Map<string, Promise<SettleResult>>();
+	/** Children retired because the parent session is shutting down. */
+	private readonly parentShutdownRetire = new Set<string>();
 
 	constructor(deps: OrchestratorDeps) {
 		this.supervisor = deps.supervisor ?? new RpcSupervisor();
@@ -491,6 +495,8 @@ export class Orchestrator {
 		name?: string;
 		team?: string;
 		model?: string;
+		/** Provider id pinning `--provider` for an ambiguous bare model id (#123). */
+		modelProvider?: string;
 		thinking?: string | false;
 		worktree?: boolean;
 		modelOrigin?: ModelOrigin;
@@ -598,6 +604,7 @@ export class Orchestrator {
 					cwd: worktreePath ?? this.cwd,
 					env: childEnv,
 					...(model ? { model } : {}),
+					...(input.modelProvider ? { modelProvider: input.modelProvider } : {}),
 					...(input.stripLegionIdentity ? { stripLegionIdentity: true } : {}),
 					...(input.thinking !== undefined ? { thinking: input.thinking } : input.agent.thinking !== undefined ? { thinking: input.agent.thinking } : {}),
 					...(input.agent.allowNestedSubagents !== undefined && !input.agent.utility ? { allowNestedSubagents: input.agent.allowNestedSubagents } : {}),
@@ -860,6 +867,11 @@ export class Orchestrator {
 				execution = { status: "aborted", reason: "RPC child exited before writing session JSONL", model: child.model ?? null };
 			}
 		}
+		// A parent shutdown can resolve the in-flight wait by killing the child.
+		// That is not the child settling a turn with no assistant reply.
+		if (this.parentShutdownRetire.has(name) && wait !== "settled") {
+			execution = attributeParentSessionShutdown(execution, parsed);
+		}
 		return this.finishCollect(child, parsed, execution, deadline);
 	}
 
@@ -1098,10 +1110,18 @@ export class Orchestrator {
 		return cached;
 	}
 
-	async retire(name: string): Promise<ChildRecord> {
+	async retire(name: string, opts?: RetireOptions): Promise<ChildRecord> {
 		const child = this.requireChild(name);
+		if (opts?.cause === "session-shutdown") this.parentShutdownRetire.add(name);
 		if (child.state === "retired") return child;
-		if (!child.execution && fs.existsSync(child.sessionFile)) child.execution = deriveOutcome(parseSessionFile(child.sessionFile));
+		const sessionExists = fs.existsSync(child.sessionFile);
+		const parsed = sessionExists ? parseSessionFile(child.sessionFile) : emptyParsedSession();
+		if (!child.execution && sessionExists) child.execution = deriveOutcome(parsed);
+		// Stamp the cause before killing so an in-flight collect cannot
+		// overwrite it with "no assistant message" after the process dies.
+		if (opts?.cause === "session-shutdown" && this.supervisor.isAlive(name)) {
+			child.execution = attributeParentSessionShutdown(child.execution ?? deriveOutcome(parsed), parsed);
+		}
 		if (this.supervisor.isAlive(name)) await this.supervisor.retire(name);
 		if (child.nodeId && this.legion) {
 			if (child.execution && child.execution.status !== "unknown" && child.execution.status !== "running") {

package/src/runs/provider-pin.ts

@@ -0,0 +1,59 @@
+/**
+ * Provider pinning for ambiguous bare model ids (#123).
+ *
+ * A model id like `workbuddy/hy4-preview-ioa` can exist under more than one
+ * provider: one registered live by an extension (any-endpoint) and one static
+ * in models.json without usable auth. Children start with `--no-extensions`,
+ * so the live provider only exists when the role lists its extension — and a
+ * bare `--model workbuddy/...` still resolves into the FIRST provider that
+ * declares the id, which may be the auth-less static one. The child then dies
+ * instantly with "No API key found for <provider>".
+ *
+ * Fix: at dispatch time, ask the PARENT's registry which provider actually
+ * owns the resolved model and pass it as `--provider` alongside `--model`.
+ * The parent registry reflects the live extension providers, so the pinned
+ * provider is the one that can authenticate.
+ */
+
+/** Minimal registry surface `providerForModel` needs (subset of ModelRegistry). */
+export interface ProviderLookup {
+	getAll(): Array<{ provider: string; id: string }>;
+}
+
+/**
+ * Find the provider that owns `model` in the parent's registry.
+ *
+ * Returns `undefined` when the model cannot be found or when more than one
+ * provider declares the same id AND the id carries no provider prefix — in
+ * that ambiguous case pinning a wrong provider is worse than leaving the
+ * child to resolve it. Models with a `provider/id` prefix are matched on the
+ * full prefixed id first (extension providers register such ids verbatim),
+ * then on the suffix after the first slash.
+ */
+export function providerForModel(
+	registry: ProviderLookup | undefined,
+	model: string | undefined,
+): string | undefined {
+	if (!registry || !model) return undefined;
+	const bare = model.trim();
+	if (!bare) return undefined;
+
+	const models = registry.getAll();
+	// Candidates: the id verbatim (extension providers may register prefixed
+	// ids) and, when `bare` carries a provider prefix, the id after stripping it
+	// (`any-endpoint/workbuddy/x` ↔ registry id `workbuddy/x`).
+	const suffix = bare.includes("/") ? bare.slice(bare.indexOf("/") + 1) : undefined;
+	const matches = models.filter(
+		(m) => m.id === bare || (suffix !== undefined && m.id === suffix),
+	);
+	if (matches.length === 1) {
+		return matches[0]!.provider;
+	}
+	if (matches.length > 1) {
+		// Prefer the provider named by the id's own prefix (`any-endpoint/...`).
+		const prefix = bare.split("/")[0]!;
+		const prefixed = matches.find((m) => m.provider === prefix);
+		return prefixed?.provider;
+	}
+	return undefined;
+}

package/src/runs/role-tool-gates.ts

@@ -0,0 +1,103 @@
+/**
+ * Extensible doctor gates: role `tools:` that need an extension under
+ * `--no-extensions` (#70 lens, #89/#97 codemode, future builtins).
+ *
+ * Add a row here when a new tool would otherwise false-promise under
+ * `--no-extensions`. Keep stable `code` values when tests/docs depend on them.
+ */
+
+import { CHILD_EXTENSIONS_ENV, BUILTIN_CODEMODE, isCodemodeExtension } from "./args.ts";
+import type { AgentConfig } from "../shared/types.ts";
+
+export interface RoleToolExtensionGate {
+	/** Stable issue code (lens/codemode keep specific codes for back-compat). */
+	code: string;
+	/** Match against role `tools:` entries. */
+	matchesTools: (tools: readonly string[]) => boolean;
+	/** True when the effective child extension list satisfies the requirement. */
+	extensionsSatisfy: (exts: readonly string[]) => boolean;
+	toolLabel: string;
+	extensionLabel: string;
+	fix: (roleName: string) => string;
+	nextStep: string;
+}
+
+/**
+ * Configurable tool → extension requirements for `/legion doctor` (#97).
+ *
+ * Order is the issue emission order. Prefer specific codes over a single
+ * `ROLE_TOOL_UNAVAILABLE` so Next steps and existing tests stay precise.
+ */
+export const ROLE_TOOL_EXTENSION_GATES: readonly RoleToolExtensionGate[] = [
+	{
+		code: "ROLE_MISSING_LENS",
+		matchesTools: (tools) =>
+			tools.some((t) =>
+				/lens|symbol_search|project_report|module_report|read_symbol|read_enclosing/i.test(t),
+			),
+		extensionsSatisfy: (exts) => exts.some((e) => /pi-lens/i.test(e)),
+		toolLabel: "lens tools",
+		extensionLabel: "pi-lens",
+		fix: (roleName) =>
+			`Add pi-lens to ${roleName}'s extensions: frontmatter, or to ${CHILD_EXTENSIONS_ENV}.`,
+		nextStep:
+			"Add pi-lens extension path to roles that list lens_* tools, or to PI_LEGION_CHILD_EXTENSIONS.",
+	},
+	{
+		code: "ROLE_MISSING_CODEMODE",
+		matchesTools: (tools) => tools.some((t) => t === "codemode"),
+		extensionsSatisfy: (exts) => exts.some(isCodemodeExtension),
+		toolLabel: "codemode",
+		extensionLabel: BUILTIN_CODEMODE,
+		fix: (roleName) =>
+			`Add ${BUILTIN_CODEMODE} to ${roleName}'s extensions: frontmatter, or ensure tools: includes codemode so Legion auto-loads it.`,
+		nextStep: `Add ${BUILTIN_CODEMODE} to roles that list codemode (or keep tools: codemode so Legion auto-loads it).`,
+	},
+];
+
+/** Plain issue shape so this module stays free of doctor imports. */
+export interface RoleToolGateIssue {
+	severity: "warning";
+	code: string;
+	section: "extensions";
+	message: string;
+	fix: string;
+}
+
+/**
+ * Collect role-tool / extension mismatch issues for one agent.
+ *
+ * `effectiveExts` should be the same list the child argv would load
+ * (e.g. `collectChildExtensions`). When `inheritsExtensions` is true the
+ * child loads host discovery — gates do not fire.
+ */
+export function collectRoleToolExtensionIssues(
+	agent: Pick<AgentConfig, "name" | "tools">,
+	effectiveExts: readonly string[],
+	opts: { inheritsExtensions: boolean },
+): RoleToolGateIssue[] {
+	if (opts.inheritsExtensions) return [];
+	const tools = agent.tools ?? [];
+	const out: RoleToolGateIssue[] = [];
+	for (const gate of ROLE_TOOL_EXTENSION_GATES) {
+		if (!gate.matchesTools(tools)) continue;
+		if (gate.extensionsSatisfy(effectiveExts)) continue;
+		out.push({
+			severity: "warning",
+			code: gate.code,
+			section: "extensions",
+			message: `Role "${agent.name}" lists ${gate.toolLabel} but would not load ${gate.extensionLabel} under --no-extensions.`,
+			fix: gate.fix(agent.name),
+		});
+	}
+	return out;
+}
+
+/** Next-step lines for any gate codes present in `issues`. */
+export function roleToolGateNextSteps(issues: readonly { code: string }[]): string[] {
+	const steps: string[] = [];
+	for (const gate of ROLE_TOOL_EXTENSION_GATES) {
+		if (issues.some((i) => i.code === gate.code)) steps.push(gate.nextStep);
+	}
+	return steps;
+}

package/src/shared/session.ts

@@ -513,6 +513,40 @@ export function isTransientConnectionFailure(
 	return /connection error/i.test(text);
 }
 
+/**
+ * Session ended with a user prompt and no assistant reply.
+ * This is a model/stream failure when the child finished on its own.
+ * A parent `session_shutdown` that kills the child first must not reuse it;
+ * see `attributeParentSessionShutdown`.
+ */
+export const NO_ASSISTANT_ABORT_REASON = "no assistant message for the last prompt";
+
+/**
+ * Parent process shutdown retired the child before any assistant message
+ * was written. Distinct from {@link NO_ASSISTANT_ABORT_REASON}.
+ */
+export const PARENT_SESSION_SHUTDOWN_ABORT_REASON =
+	"parent session shutdown retired the child before it produced an assistant message";
+
+/** True when the last turn (or the whole file) has no assistant message. */
+export function lastTurnHasNoAssistant(parsed: ParsedSession): boolean {
+	const last = parsed.turns.at(-1);
+	return parsed.turns.length === 0 || !last || last.assistants.length === 0;
+}
+
+/**
+ * Rewrite a missing-assistant abort when the parent session shut down and
+ * retired the child. A turn the child actually settled keeps `deriveOutcome`.
+ */
+export function attributeParentSessionShutdown(execution: Execution, parsed: ParsedSession): Execution {
+	if (execution.status === "success" || !lastTurnHasNoAssistant(parsed)) return execution;
+	return {
+		...execution,
+		status: "aborted",
+		reason: PARENT_SESSION_SHUTDOWN_ABORT_REASON,
+	};
+}
+
 /**
  * Derive the execution outcome from a parsed session.
  *
@@ -542,10 +576,11 @@ export function deriveOutcome(parsed: ParsedSession): Execution {
 	}
 
 	// F29: hard kill / interrupt before any reply was persisted.
+	// Parent-session cascade shutdown rewrites this in the orchestrator.
 	if (last.assistants.length === 0) {
 		return {
 			status: "aborted",
-			reason: "no assistant message for the last prompt",
+			reason: NO_ASSISTANT_ABORT_REASON,
 			turns: turns.length,
 			toolErrors: parsed.toolErrors,
 			lastTurn: { stopReason: null, toolErrors: last.toolErrors },
@@ -558,7 +593,7 @@ export function deriveOutcome(parsed: ParsedSession): Execution {
 	if (!final) {
 		return {
 			status: "aborted",
-			reason: "no assistant message for the last prompt",
+			reason: NO_ASSISTANT_ABORT_REASON,
 			turns: turns.length,
 			toolErrors: parsed.toolErrors,
 		};

package/src/shared/types.ts

@@ -246,6 +246,14 @@ export interface Execution {
 	completedAt?: string;
 }
 
+/**
+ * Why a still-live child is being retired.
+ * `session-shutdown` is the parent process leaving, not a model failure.
+ */
+export interface RetireOptions {
+	cause?: "session-shutdown";
+}
+
 export interface Usage {
 	input: number;
 	output: number;

package/src/tui/viz/panels.ts

@@ -252,7 +252,9 @@ export function drawGalaxy(cv: Canvas, r: Rect, data: ViewData, selectedId: stri
 		cv.text(lx + 2, ly, role, "dim");
 		lx += w;
 	}
-	for (const [label, col] of [["✗ failed", "error"], ["⣿ retired", "dim"]] as const) {
+	const statuses = new Set(nodes.map((node) => node.status));
+	for (const [status, label, col] of [["failed", "✗ failed", "error"], ["retired", "⣿ retired", "dim"]] as const) {
+		if (!statuses.has(status)) continue;
 		if (lx + label.length + 1 > r.x + r.w - 1) break;
 		cv.text(lx, ly, label, col);
 		lx += label.length + 2;