pi-legion 5.0.1 → 5.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-legion",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "description": "Pi Legion v2: recursive centurion teams on Pi. Children run in-process by default (rpc only for a worktree-owning centurion); shared SQLite WAL legion.db. Declarative per-team phase machine (built-in default: planning/implementing/reviewing/verifying), parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume.",
   "type": "module",
   "license": "MIT",
@@ -87,10 +87,10 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^1.0.0",
-    "@earendil-works/pi-ai": "^1.0.0",
-    "@earendil-works/pi-coding-agent": "^1.0.0",
-    "@earendil-works/pi-tui": "^1.0.0",
+    "@earendil-works/pi-agent-core": "^1.4.0",
+    "@earendil-works/pi-ai": "^1.4.0",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
     "@types/node": "^22.0.0",
     "typebox": "^1.3.30",
     "typescript": "^5.6.0"

package/skills/pi-legion/SKILL.md

@@ -70,7 +70,8 @@ commands under the supervisor, without an LLM deciding whether they passed.
 
 A centurion owns a Git worktree for its subtree; squad members share that
 worktree, and a nested centurion gets a nested Git worktree. Each squad
-squashes its subtree into an MR for its parent. MRs move upward until the root
+squashes its subtree onto a branch for its parent — the branch is the deliverable, and an
+MR is added only when the repository has a remote. Deliveries move upward until the root
 reviews and merges into the default branch. Do not merge a child squad's work
 at the wrong level.
 

package/src/agents/agents.ts

@@ -31,10 +31,12 @@ import {
 import { getAgentDir } from "./paths.ts";
 import { ignoredKindMessage, reportIgnoredOnce } from "../shared/ignored-kind.ts";
 import {
+	canReachTerminal,
 	type PhaseDefinition,
 	type PhaseMachine,
 	type PhaseTransitionRule,
 	normalizePhaseMachine,
+	phaseStart,
 	validatePhaseMachine,
 } from "../legion/phase-machine.ts";
 import type { PhaseCondition } from "../legion/phase-conditions.ts";
@@ -528,8 +530,21 @@ function parsePhaseBlock(text: string): PhaseMachine | undefined {
  * Validation happens HERE, at load, and every problem is reported at once. A
  * machine that only fails mid-run would surface after a team had already spent
  * tokens on a workflow that could never complete.
+ *
+ * Exported since #371: the SAME parser reads a declaration handed to the
+ * `subagent` tool at dispatch time, so the card layer and the inline layer can
+ * never disagree about what a legal machine is.
+ *
+ * `requireTerminal` adds the one question this parser does not ask for a card:
+ * can the DECLARED graph actually reach a terminal phase (#371 G4)? A card has
+ * never been checked for it and its rules are frozen, so the check is opt-in
+ * rather than folded into `validatePhaseMachine`.
  */
-function parsePhaseMachine(value: unknown, filePath: string): PhaseMachine | undefined {
+export function parsePhaseMachine(
+	value: unknown,
+	filePath: string,
+	options: { requireTerminal?: boolean } = {},
+): PhaseMachine | undefined {
 	if (value === undefined || value === null) return undefined;
 	let raw: unknown = value;
 	if (typeof value === "string") {
@@ -570,6 +585,16 @@ function parsePhaseMachine(value: unknown, filePath: string): PhaseMachine | und
 	// on the machine as it will actually run.
 	const normalized = normalizePhaseMachine(machine);
 	const errors = validatePhaseMachine(normalized);
+	// #371 G4: a well-formed graph may still be a loop. Asked only when the graph
+	// is otherwise valid (a structural error already names the real problem), and
+	// asked of the DECLARED graph — `normalizePhaseMachine` appends `done` to every
+	// non-terminal phase, so the normalized machine answers "yes" by construction.
+	if (options.requireTerminal === true && errors.length === 0 && !canReachTerminal(machine)) {
+		errors.push({
+			path: "phases",
+			message: `phase machine cannot reach a terminal phase from '${phaseStart(machine)}'`,
+		});
+	}
 	if (errors.length > 0) {
 		const detail = errors.map((error) => `  - ${error.path}: ${error.message}`).join("\n");
 		throw new Error(`Agent '${filePath}' has an invalid phase machine:\n${detail}`);

package/src/agents/settings.ts

@@ -135,7 +135,16 @@ const LEGION_SETTING_FIELDS = [
 	"orphanStaleMs",
 ] as const satisfies readonly (keyof LegionSettings)[];
 
-interface LegionExplicitFields {
+/**
+ * Which `legion` values the operator actually wrote down (#358 review, major 1).
+ *
+ * `parseLegionSettings` FILLS every default so a consumer never has to invent a
+ * number, and that fill is indistinguishable from a decision once it has been
+ * spread into a plain object. Anything that treats "the setting is present" as
+ * "the operator chose it" therefore sees a choice that was never made — which is
+ * exactly how a card's own `timeoutMs` on a built-in phase came to be ignored.
+ */
+export interface LegionExplicitFields {
 	fields: Set<keyof LegionSettings>;
 	phaseTimeouts: Set<(typeof LEGION_PHASES)[number]>;
 }
@@ -253,7 +262,16 @@ function parseLegionSettings(
 	return out;
 }
 
-function legionExplicitFields(
+/**
+ * Read the operator's own decisions out of a `legion` block.
+ *
+ * A settings object produced by {@link parseLegionSettings} / {@link mergeLegionSettings}
+ * carries them on a symbol; a hand-built object (a test, a caller) falls back to
+ * "an own key means explicit", which is the only thing that is observable there.
+ * Read this — never `phaseTimeouts?.[phase] !== undefined` — to answer "did a
+ * human set this clock?".
+ */
+export function legionExplicitFields(
 	settings: LegionSettings | undefined,
 ): LegionExplicitFields {
 	if (!settings) return { fields: new Set(), phaseTimeouts: new Set() };
@@ -272,6 +290,53 @@ function legionExplicitFields(
 	};
 }
 
+/**
+ * Did the operator set this phase's advisory clock by hand (#358 review, major 1)?
+ *
+ * The answer consumers need is about the DECISION, not about the value being
+ * present: a filled-in default is present too. `phase` is free-form because a
+ * declared machine names its own phases.
+ */
+export function isExplicitPhaseTimeout(
+	settings: LegionSettings | undefined,
+	phase: string,
+): boolean {
+	return (legionExplicitFields(settings).phaseTimeouts as ReadonlySet<string>).has(phase);
+}
+
+/**
+ * The `legion` settings a run actually uses, defaults filled (#358 review, major 1).
+ *
+ * The fill is what lets every consumer read a number, but it must not masquerade
+ * as an operator decision: `checkOwnPhaseTimeout` asks
+ * {@link legionExplicitFields} whether a phase clock was set by a human, and a
+ * built-in default that arrived by being spread in would answer yes. This is the
+ * seam that keeps the two apart — replacing it with a plain spread silently turns
+ * `settings > machine > default` into `settings(filled) > nothing`, i.e. a card's
+ * `timeoutMs` on a built-in phase name never wins.
+ */
+export function legionSettingsForRun(
+	settings: SubagentsSettings | undefined,
+): LegionSettings {
+	const legion = settings?.legion;
+	const resolved: TrackedLegionSettings = {
+		...DEFAULT_LEGION_SETTINGS,
+		...(legion ?? {}),
+		phaseTimeouts: {
+			...DEFAULT_LEGION_SETTINGS.phaseTimeouts,
+			...(legion?.phaseTimeouts ?? {}),
+		},
+	};
+	const explicit = legionExplicitFields(legion);
+	Object.defineProperty(resolved, LEGION_EXPLICIT_FIELDS, {
+		value: {
+			fields: new Set(explicit.fields),
+			phaseTimeouts: new Set(explicit.phaseTimeouts),
+		} satisfies LegionExplicitFields,
+	});
+	return resolved;
+}
+
 function mergeLegionSettings(
 	user: LegionSettings | undefined,
 	project: LegionSettings | undefined,

package/src/api.ts

@@ -187,8 +187,24 @@ export {
 } from "./runs/worktree.ts";
 
 // ── parent session: completion notify + input-box status ────────────────────
+//
+// `SessionRuntime.consumeCollect*` answers with `ClaimedCollect`, not a bare
+// snapshot (#320):
+//
+// ```ts
+// const { snapshot, claimedNow } = await rt.consumeCollect("worker-0")!;
+// ```
+//
+// `claimedNow` is `true` only when THIS call took the round's completion claim, so a
+// caller that bails before handing the result to the agent (an aborted parent turn, a
+// failed persist) rolls it back with `unclaimUndelivered(name, snapshot, claimedNow)`
+// — a call that did not take the claim must leave the claim of the delivery that did
+// alone. The flag travels with the return value on purpose: two collects can await the
+// same job promise and therefore see the same snapshot object, so a per-snapshot record
+// would let the second call overwrite the first one's answer.
 export { createSessionRuntime, shouldRecycleAfterCollect } from "./extension/runtime.ts";
 export type {
+	ClaimedCollect,
 	CollectSnapshot,
 	SessionRuntime,
 	SessionRuntimeDeps,
@@ -261,6 +277,7 @@ export {
 	extractVerdict,
 	isLastTurnComplete,
 	parseSessionFile,
+	parseSessionFileCached,
 	parseSessionText,
 } from "./shared/session.ts";
 export {

package/src/extension/child-guard.ts

@@ -34,7 +34,8 @@ export function childTaskAppendix(opts?: {
 	const worktree = opts?.worktreeBranch
 		? [
 				`- You are in an isolated git worktree on branch \`${opts.worktreeBranch}\`. Do not write the parent checkout.`,
-				"- Commit on this branch and open a merge request / pull request into the repository default branch. Do not merge locally. Do not push to main or master. Put the MR/PR URL in your verdict reason.",
+				"- Commit on this branch. The branch is the deliverable: put its name and HEAD sha in your verdict reason. Do not merge locally; do not push to main or master.",
+				"- A merge request / pull request is a convenience, not a requirement: open one only when the repository has a remote and `gh`/`glab` is available, and then add its URL to the verdict. With no remote, write `no remote: branch <name> at <sha>`; never invent a URL, and a missing MR is not a failure.",
 			]
 		: [];
 	return [

package/src/extension/join.ts

@@ -51,6 +51,13 @@ function defaultJoinConfig(): JoinConfig {
 export interface JoinEntry {
 	runId: string;
 	name: string;
+	/**
+	 * Reporting round of this child (D10). The runtime assigns it from a per-name
+	 * monotonic counter in `track()`; the coordinator only carries it, because one
+	 * round is one deliverable result — two unread rounds of the same child must
+	 * both survive the buffer, which a `(runId, name)` key cannot express.
+	 */
+	round: number;
 	/** Raw collect result; the deliver sink feeds it to formatGroupedNotice. */
 	input: CompletionInput;
 	/** From the triggering watch() call, forwarded to the delivery options. */
@@ -127,6 +134,37 @@ export class JoinCoordinator {
 		}
 	}
 
+	/**
+	 * D8: drop the already-TERMINAL entries of one member.
+	 *
+	 * `remove()` only clears `pending` (a member that has already finished lives in
+	 * `buffered`, not in `pending`), so a released child left its buffered entry
+	 * behind as an orphan that fired at window expiry (W3) — most visibly right
+	 * after a `wait()` hit, which retires and releases the very child whose entry
+	 * is sitting in the window. Semantics of `remove()` are otherwise unchanged.
+	 */
+	dropBuffered(runId: string, name: string): void {
+		this.dropBufferedWhere(runId, (entry) => entry.name === name);
+	}
+
+	/**
+	 * D10: drop the terminal entries of ONE ROUND of one member.
+	 *
+	 * This is what `release()` needs. `release()` acts on a single tracked job, and
+	 * a job carries exactly one round, so the copy it may drop is the one that round
+	 * produced. The name-wide `dropBuffered` above is the REVOKE path (D7): a parent
+	 * asking to see the child again invalidates every copy of the name. Using the
+	 * name-wide form from `release()` would silently swallow an EARLIER round's
+	 * unread notice — the loss D10 exists to prevent (one round = one deliverable
+	 * result).
+	 */
+	dropBufferedRound(runId: string, name: string, round: number): void {
+		this.dropBufferedWhere(
+			runId,
+			(entry) => entry.name === name && entry.round === round,
+		);
+	}
+
 	/** Terminal entry point (success and collect-failure alike). */
 	onTerminal(entry: JoinEntry): void {
 		if (this.disposed) return;
@@ -184,6 +222,22 @@ export class JoinCoordinator {
 		this.groupOf.clear();
 	}
 
+	/** One implementation for both drops: keep every entry the predicate rejects. */
+	private dropBufferedWhere(
+		runId: string,
+		matches: (entry: BufferedEntry) => boolean,
+	): void {
+		if (this.disposed) return;
+		const group = this.groups.get(runId);
+		if (!group || group.buffered.length === 0) return;
+		const kept = group.buffered.filter((entry) => !matches(entry));
+		if (kept.length === group.buffered.length) return;
+		group.buffered = kept;
+		if (group.pending.size === 0 && group.buffered.length === 0) {
+			this.dropGroup(runId, group);
+		}
+	}
+
 	private ensureGroup(runId: string): Group {
 		let group = this.groups.get(runId);
 		if (!group) {

package/src/extension/legion-commands.ts

@@ -727,6 +727,20 @@ export function registerLegionCommand(
 			if (classicTree) query = "";
 			const vizSnapshot = deps.runtime.vizSnapshot?.bind(deps.runtime);
 			if (!query && !classicTree && vizSnapshot) {
+				// #347: mount the page on the main screen instead of as a full-screen
+				// overlay. pi-tui composites *every* row of a visible overlay through
+				// `compositeTuiLine` (three `Intl.Segmenter` grapheme walks, cached by
+				// whole line, which a live frame never repeats); for this page — 56–68%
+				// non-ASCII braille/box/block cells — that was 57–70% of the frame and
+				// ~183µs/row for the whole terminal height. A main-screen mount (the
+				// mount the classic `--tree` view below already uses) replaces
+				// the base instead of stacking on it, so the page costs one plain
+				// `render()` and nothing else: measured 2.5–2.7× on the same component
+				// and data, with the frame's bytes within 3% (`bench/perf-core/09`).
+				// Esc/q still return to the session view: the host restores the editor
+				// it swapped out. The detail modal opened from inside the page stays a
+				// 75% floating overlay (`openLiveOverlay` below).
+				// Contract: `docs/contracts/legion-main-screen-mount-v1.md`.
 				await ctx.ui.custom(createLegionViewFactory({
 					getData: () => vizSnapshot(),
 					onStopNode: deps.stop ? (nodeId) => void confirmStopNode(ctx, nodeId) : undefined,
@@ -735,10 +749,7 @@ export function registerLegionCommand(
 							openLiveOverlay(pi, ctx.ui, ctx.cwd, liveOverlay, nodeId, overlayStop(ctx.ui));
 						}
 					},
-				}), {
-					overlay: true,
-					overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", row: 0, col: 0 },
-				});
+				}), { overlay: false });
 				return;
 			}
 			if (query) {

package/src/extension/legion-doctor.ts

@@ -25,6 +25,10 @@ import {
 	roleToolGateNextSteps,
 } from "../runs/role-tool-gates.ts";
 import { getAgentDir } from "../agents/paths.ts";
+import {
+	hostExtensionDiscoveryState,
+	type HostExtensionDiscoveryState,
+} from "../runs/extension-inheritance.ts";
 import {
 	CHILD_MAX_OLD_SPACE_ENV,
 	CHILD_RESERVE_ENV,
@@ -355,11 +359,19 @@ function sampleAgentConfig(agent?: AgentConfig): AgentConfig {
 }
 
 
-/** Fix text for inprocess model/provider gaps — never recommends PI_LEGION_CHILD_EXTENSIONS (#212). */
+/**
+ * Fix text for inprocess model/provider gaps (#212, #329).
+ *
+ * #329: same two levers as `spawn-hints.ts` (#317/#328) — `models.json`, or the
+ * `PI_LEGION_CHILD_EXTENSIONS` path list. The dead switch (`inheritExtensions: true`,
+ * `PI_LEGION_CHILD_INHERIT_EXTENSIONS=1`) must not come back here: `true` is the default
+ * policy since #280, so it changes nothing, and when host discovery fails it still yields
+ * 0 extensions — the very state doctor is reporting on.
+ */
 export function inprocessModelFix(): string {
 	return (
 		"Declare the provider statically in models.json (agent dir / project), " +
-		"or set role frontmatter extensions: […] / inheritExtensions: true."
+		`or pass the provider extension explicitly with ${CHILD_EXTENSIONS_ENV}=<path>.`
 	);
 }
 
@@ -368,7 +380,7 @@ function rpcChildExtensionsFix(providerExtHome: readonly string[]): string | und
 	if (providerExtHome.length) {
 		return `export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}`;
 	}
-	return `Add the provider package extension path to ${CHILD_EXTENSIONS_ENV}, or set role extensions: / inheritExtensions: true.`;
+	return `Add the provider package extension path to ${CHILD_EXTENSIONS_ENV}, or add it under the role's extensions: frontmatter.`;
 }
 
 function previewChildArgv(agent: AgentConfig, env: NodeJS.ProcessEnv): string[] {
@@ -427,6 +439,29 @@ function extensionsForRole(agent: AgentConfig, env: NodeJS.ProcessEnv, _extras:
 	return collectChildExtensions(agent, env);
 }
 
+/**
+ * One-line answer to "is inheritance actually wired?" (#317).
+ *
+ * The role line above only says `(all host-discovered extensions)`, which reads
+ * identically whether discovery worked, failed, or never ran. This turns the
+ * three cases into text: `ok`, `failed <n>s ago` (with the age, because the
+ * backoff is 5 s and a stale stamp is a different diagnosis than a live one),
+ * and `never` (no probe in this process — the common shape for a doctor run
+ * before the first spawn).
+ */
+function formatDiscoveryProbe(state: HostExtensionDiscoveryState, now = Date.now()): string {
+	switch (state.status) {
+		case "ok":
+			return "ok";
+		case "failed": {
+			const ageS = Math.max(0, Math.floor((now - (state.at ?? now)) / 1000));
+			return `failed ${ageS}s ago`;
+		}
+		default:
+			return "never";
+	}
+}
+
 function scanOrphanTemps(storeRoot: string): { total: number; orphanDead: number; live: number; unknown: number; samples: string[] } {
 	const runsRoot = path.join(storeRoot, "runs");
 	let total = 0;
@@ -790,6 +825,12 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 		push("## Extensions");
 		push(`- spawnMode (sample/default): ${spawnMode}`);
 		push(`- inheritExtensions (env/role default): ${inheritGlobal ? "yes (loads all host extensions)" : "no"}`);
+		// #317: `(all host-discovered extensions)` alone cannot say whether inheritance
+		// is wired — failed discovery, an empty host and "never probed" all looked the
+		// same. The count comes from the last probe in THIS process; doctor never
+		// probes on its own, so `never` is honest and cheap.
+		const discovery = hostExtensionDiscoveryState();
+		push(`- discovered host extensions: ${discovery.count} (last probe: ${formatDiscoveryProbe(discovery)})`);
 		if (isInprocess) {
 			push("- child argv --no-extensions: n/a (inprocess has no child argv)");
 		} else {
@@ -1035,15 +1076,16 @@ export function runLegionDoctor(options: DoctorOptions = {}): DoctorReport {
 		const modelIssue = issues.some((i) =>
 			i.code === "CHILD_NO_MODELS" || i.code === "TEAM_MODELS_MISSING" || i.code === "RECENT_MODEL_SPAWN_FAIL",
 		);
+		// #329: never name the dead inheritance switch here (see `inprocessModelFix`).
 		if (modelIssue && isInprocess) {
 			steps.push(
-				"Inprocess: declare the provider in models.json, or set role extensions: […] / inheritExtensions: true — then restart pi (#212).",
+				`Inprocess: declare the provider in models.json, or pass the provider extension with ${CHILD_EXTENSIONS_ENV}=<path> — then restart pi (#212).`,
 			);
 		} else if (modelIssue && providerExtHome.length) {
 			steps.push(`export ${CHILD_EXTENSIONS_ENV}=${providerExtHome.join(",")}  # then restart pi`);
-			steps.push(`# or role frontmatter extensions: […] / inheritExtensions: true (more RAM)`);
+			steps.push(`# or role frontmatter extensions: […] (role-scoped only)`);
 		} else if (modelIssue) {
-			steps.push(`# set role frontmatter extensions: […] / inheritExtensions: true, or export ${CHILD_EXTENSIONS_ENV}=<paths>`);
+			steps.push(`# set role frontmatter extensions: […], or export ${CHILD_EXTENSIONS_ENV}=<paths>`);
 		}
 		steps.push(...roleToolGateNextSteps(issues));
 		if (issues.some((i) => i.code === "MEMORY_GATE_WOULD_REFUSE")) {

package/src/extension/legion-status.ts

@@ -7,6 +7,8 @@
  */
 
 import { NODE_STATUSES, type LegionNode } from "../legion/nodes.ts";
+import type { InFlightToolStack } from "../supervisor/types.ts";
+import { formatInFlightToolLine } from "../supervisor/types.ts";
 import { formatTree } from "./legion-tools.ts";
 import {
 	renderLiveChildStatus,
@@ -14,7 +16,39 @@ import {
 } from "./runtime.ts";
 
 /** Child snapshot the status tool already prints. `now` is supplied by the caller. */
-export type LegionChildStatusFacts = Omit<LiveChildStatusInput, "now">;
+export type LegionChildStatusFacts = Omit<LiveChildStatusInput, "now"> & {
+	/**
+	 * The tool calls in flight right now (#315, #331), innermost last. Read from
+	 * the supervisor, never persisted: it describes this process's live child, so
+	 * a rebuilt record (another session's child) has none and none is invented.
+	 */
+	inFlightTools?: InFlightToolStack;
+};
+
+/**
+ * Put the live-activity line at the TOP of one rendered child block (#315).
+ *
+ * The fact is the whole stack (#331) so the line can name nesting and parallel
+ * siblings; an absent or empty stack renders the block unchanged.
+ *
+ * A lead line, not a footnote: `working · bash 00:07:31` is the answer to "what
+ * is it doing, and for how long", and the block below it already leads its own
+ * liveness story with `alive · quiet Ns`. Prepending needs no knowledge of the
+ * block's internal line order, so this keeps working if
+ * `renderLiveChildStatus` grows or reorders lines.
+ *
+ * `undefined` (or an empty stack) renders the block unchanged: no fact, no
+ * line. This is display only — it never decides liveness and never stops
+ * anything.
+ */
+export function withInFlightToolLine(
+	block: string,
+	stack: InFlightToolStack | undefined,
+	now: number,
+): string {
+	if (stack === undefined || stack.length === 0) return block;
+	return `${formatInFlightToolLine(stack, now)}\n${block}`;
+}
 
 export interface LegionStatusJob {
 	name: string;
@@ -72,7 +106,15 @@ function liveJobForNode(node: LegionNode, jobs: readonly LegionStatusJob[]): Leg
 }
 
 function renderFacts(facts: LegionChildStatusFacts, now: number | undefined): string {
-	return renderLiveChildStatus(withNow(facts, now));
+	// The in-flight stack is display-only and lives outside
+	// `renderLiveChildStatus`, so it is split off before the snapshot is rendered
+	// and prepended afterwards.
+	const { inFlightTools, ...snapshot } = facts;
+	return withInFlightToolLine(
+		renderLiveChildStatus(withNow(snapshot, now)),
+		inFlightTools,
+		now ?? Date.now(),
+	);
 }
 
 function renderNode(