pi-legion 4.0.0 → 5.0.0

package/src/legion/state-machine.ts

@@ -1,3 +1,20 @@
+import {
+	type PhaseMachine,
+	DEFAULT_PHASE_MACHINE,
+	DEFAULT_MAX_REWORK_COUNT,
+	findPhase,
+	normalizePhaseMachine,
+	isTerminalIn,
+	legacyReasonForCondition,
+} from "./phase-machine.ts";
+import {
+	checkPhaseCondition,
+	checkPhaseRequirements,
+	describeFailedCondition,
+	type PhaseCondition,
+	type PhaseConditionInput,
+} from "./phase-conditions.ts";
+
 export const LEGION_PHASES = [
 	"planning",
 	"implementing",
@@ -39,7 +56,11 @@ export type PhaseTransitionReason =
 	| "centurion_required"
 	| "children_not_terminal"
 	| "terminal_reason_required"
-	| "all_children_not_failed";
+	| "all_children_not_failed"
+	// #298: a declared machine can refuse for reasons the built-in table had no
+	// name for — an unmet custom condition, or an edge reserved to another actor.
+	| "condition_not_met"
+	| "actor_not_permitted";
 
 export interface PhaseChild {
 	id: string;
@@ -48,8 +69,9 @@ export interface PhaseChild {
 }
 
 export interface EvaluatePhaseTransitionInput {
-	from: LegionPhase | null;
-	to: LegionPhase;
+	/** Phase id. Free-form when a declared machine is supplied (#298). */
+	from: string | null;
+	to: string;
 	reworkCount?: number;
 	contractPath?: string | null;
 	children?: readonly PhaseChild[];
@@ -58,13 +80,21 @@ export interface EvaluatePhaseTransitionInput {
 	verificationPassed?: boolean;
 	actorRole?: string;
 	terminalReason?: "parent_decision" | "all_children_failed" | "rework_exhausted" | "parent_retire";
+	/**
+	 * #298: a declared machine. When present, transitions are evaluated from it
+	 * instead of the built-in table, so a team can define its own workflow.
+	 * Absent means DEFAULT_PHASE_MACHINE — identical to the old behaviour.
+	 */
+	machine?: PhaseMachine;
+	/** Whether the contract file exists and is non-empty (resolved by the caller). */
+	contractPresent?: boolean;
 }
 
 export type PhaseTransitionDecision =
 	| {
 		allowed: true;
-		from: LegionPhase | null;
-		to: LegionPhase;
+		from: string | null;
+		to: string;
 		reworkCount: number;
 		phaseSince: number;
 		notifyParent: boolean;
@@ -72,8 +102,8 @@ export type PhaseTransitionDecision =
 	}
 	| {
 		allowed: false;
-		from: LegionPhase | null;
-		to: LegionPhase;
+		from: string | null;
+		to: string;
 		reason: PhaseTransitionReason;
 		message: string;
 		forcedTransition?: {
@@ -84,26 +114,70 @@ export type PhaseTransitionDecision =
 		alarm: true;
 	};
 
-/** Pure decision function for the §7.1 transition table and entry invariants. */
-export function evaluatePhaseTransition(
+/**
+ * Evaluate a transition against a declared machine (#298).
+ *
+ * Structural invariants are the same ones the built-in path enforces, applied
+ * from data instead of a switch:
+ *
+ *   - a new team enters the machine's start phase
+ *   - terminal phases cannot transition
+ *   - `to` must be declared in the current phase's `next`
+ *   - rework edges increment past `maxRework` → forced failure
+ *   - `failed` still needs a reason, `aborted` still needs a parent retire
+ *
+ * Everything else — which edge is legal when — comes from the declaration.
+ */
+function evaluateDeclarative(
 	input: EvaluatePhaseTransitionInput,
-	now: () => number = () => Date.now(),
+	machine: PhaseMachine,
+	now: () => number,
 ): PhaseTransitionDecision {
 	const { from, to } = input;
 	const children = input.children ?? [];
 	const reworkCount = input.reworkCount ?? 0;
-	if (!isLegionPhase(to) || (from !== null && !isLegionPhase(from))) {
-		return denied(input, "invalid_phase", "phase is not part of the legion state machine");
+	const start = machine.start ?? machine.phases[0]?.id;
+	const maxRework = machine.maxRework ?? DEFAULT_MAX_REWORK_COUNT;
+
+	if (from !== null && !findPhase(machine, from)) {
+		return denied(input, "invalid_phase", `phase '${from}' is not part of this team's machine`);
+	}
+	if (!findPhase(machine, to)) {
+		return denied(input, "invalid_phase", `phase '${to}' is not part of this team's machine`);
 	}
 	if (!Number.isInteger(reworkCount) || reworkCount < 0) {
 		return denied(input, "invalid_phase", "reworkCount must be a non-negative integer");
 	}
 	if (from === to) return denied(input, "same_phase", "phase is already current");
-	if (from !== null && isTerminalPhase(from)) {
+	if (from !== null && isTerminalIn(machine, from)) {
 		return denied(input, "terminal_phase", `terminal phase ${from} cannot transition`);
 	}
-	if (from === null && to !== "planning") {
-		return denied(input, "invalid_transition", "a new team must start in planning");
+	if (from === null) {
+		if (to !== start) {
+			return denied(input, "invalid_transition", `a new team must start in ${String(start)}`);
+		}
+		return allowed(input, reworkCount, now(), false);
+	}
+
+	// A phase-level `require` still binds a FAILURE exit: leaving `implementing`
+	// for `failed` while a child is mid-run would strand that child, so the
+	// requirement is checked before the terminal shortcut.
+	//
+	// `aborted` is deliberately exempt. It is the emergency stop — the parent
+	// retire path — and gating it on "everything is settled" would mean a team
+	// with a wedged child could never be stopped. Availability of the stop button
+	// outranks tidiness.
+	const fromPhase = findPhase(machine, from);
+	const entryRequirement = to === "aborted"
+		? ({ ok: true } as const)
+		: checkPhaseRequirements(fromPhase?.require ?? [], conditionInput(input));
+	if (!entryRequirement.ok) {
+		const legacy = legacyReasonForCondition(entryRequirement.failed, { to });
+		return denied(
+			input,
+			legacy,
+			describeFailedCondition(entryRequirement.failed),
+		);
 	}
 	if (to === "aborted") {
 		if (input.terminalReason !== "parent_retire") {
@@ -111,87 +185,149 @@ export function evaluatePhaseTransition(
 		}
 		return allowed(input, reworkCount, now(), false);
 	}
-	if (from === "implementing" || to === "implementing") {
-		const planner = children.find((child) => child.role === "planner" && child.status === "running");
-		if (planner) {
-			return denied(input, "planner_still_active", `planner child ${planner.id} is still running during implementing`);
-		}
+	if (to === "failed") {
+		const failure = evaluateDeclaredFailure(input, children, reworkCount, maxRework, now);
+		if (failure) return failure;
 	}
-	if (to === "failed") return evaluateFailure(input, children, reworkCount, now);
-	if (from === null) return allowed(input, reworkCount, now(), false);
 
-	if (from === "planning" && to === "implementing") {
-		if (!input.contractPath?.trim()) {
-			return denied(input, "contract_path_required", "planning requires a non-empty contract_path");
-		}
-		return allowed(input, reworkCount, now(), false);
+	const phase = findPhase(machine, from);
+	const rule = phase?.next.find((candidate) => candidate.to === to);
+	if (!rule) {
+		// Name the legal exits. Without them a model invents plausible ones (measured:
+		// a custom `recon -> build` machine was described as offering `recon -> check`
+		// and `recon -> done`, neither of which existed), then wastes a turn being
+		// refused. The machine already knows the answer; say it.
+		const allowed = (phase?.next ?? []).map((candidate) => candidate.to);
+		const hint = allowed.length > 0 ? `legal next phases from '${from}': ${allowed.join(", ")}` : `phase '${from}' has no exits`;
+		return denied(
+			input,
+			"invalid_transition",
+			`transition ${from} → ${to} is not allowed by this team's machine (${hint})`,
+		);
 	}
-	if (from === "implementing" && to === "reviewing") {
-		const workers = children.filter((child) => child.role === "worker");
-		if (workers.some((child) => isActiveChild(child.status))) {
-			return denied(input, "worker_still_active", "all worker children must be settled before reviewing");
-		}
-		if (workers.length > 0 && workers.every((child) => child.status === "failed")) {
+	if (rule.actorRole !== undefined && input.actorRole !== rule.actorRole) {
+		// Preserve the historical code for the centurion-only edge so existing
+		// callers and tests keep their meaning; other reserved edges get the
+		// general name.
+		return denied(
+			input,
+			rule.actorRole === "centurion" ? "centurion_required" : "actor_not_permitted",
+			`only ${rule.actorRole} may transition ${from} → ${to}`,
+		);
+	}
+
+	// Phase-level requirements AND into this edge.
+	const requirement = checkPhaseRequirements(
+		[...(phase?.require ?? []), ...(rule.require ?? [])],
+		conditionInput(input),
+	);
+	if (!requirement.ok) {
+		// A team whose children ALL failed cannot succeed, so refusing the move it
+		// asked for while leaving it "running" strands it: nobody will ever satisfy
+		// the requirement it just failed. Force the terminal transition instead.
+		// The old code special-cased this for workers; the condition is structural,
+		// so it now covers any team whose dispatched children all failed.
+		if (
+			requirement.failed === "children_none_failed" &&
+			checkPhaseCondition("children_all_failed", conditionInput(input))
+		) {
 			return {
-				...denied(input, "all_workers_failed", "all worker children failed; team must fail"),
+				...denied(
+					input,
+					"all_workers_failed",
+					`all children failed; the team cannot reach ${to} and must fail`,
+				),
 				forcedTransition: { to: "failed", reworkCount, reason: "all_children_failed" },
 			};
 		}
-		const handled = new Set(input.failedWorkerHandledIds ?? []);
-		const unhandled = workers.find((child) => child.status === "failed" && !handled.has(child.id));
-		if (unhandled) {
-			return denied(input, "failed_worker_unhandled", `failed worker ${unhandled.id} must be reworked or transferred to failed`);
-		}
-		return allowed(input, reworkCount, now(), false);
+		const legacy = legacyReasonForCondition(requirement.failed, rule);
+		return denied(
+			input,
+			legacy,
+			describeFailedCondition(requirement.failed),
+		);
 	}
-	if (from === "reviewing" && to === "verifying") {
-		if (!children.some((child) => child.role === "reviewer" && child.status === "settled")) {
-			return denied(input, "reviewer_not_settled", "at least one reviewer must be settled before verifying");
-		}
-		if (input.reviewerVerdictOk !== true) {
-			return denied(input, "review_verdict_not_accepted", "reviewing requires a settled reviewer verdict ok:true");
-		}
-		return allowed(input, reworkCount, now(), false);
-	}
-	if (from === "reviewing" && to === "implementing") {
-		if (input.reviewerVerdictOk !== false) {
-			return denied(input, "review_verdict_not_rejected", "review rework requires reviewer verdict ok:false");
-		}
-		return evaluateRework(input, reworkCount, now);
-	}
-	if (from === "verifying" && to === "implementing") {
-		if (input.verificationPassed !== false) {
-			return denied(input, "verification_not_failed", "verification rework requires a failing verification result");
+
+	if (rule.rework === true) {
+		const next = reworkCount + 1;
+		if (next > maxRework) {
+			return {
+				...denied(input, "rework_limit_exceeded", `rework count ${next} exceeds limit ${maxRework}`),
+				forcedTransition: { to: "failed", reworkCount: next, reason: "rework_exhausted" },
+			};
 		}
-		return evaluateRework(input, reworkCount, now);
+		return allowed(input, next, now(), rule.notifyParent === true);
 	}
-	if (from === "reviewing" && to === "planning") {
-		if (input.actorRole !== "centurion") {
-			return denied(input, "centurion_required", "only the centurion may return a bad plan to planning");
+	return allowed(input, reworkCount, now(), rule.notifyParent === true);
+}
+
+/** `failed` is only reachable for a declared reason; returns undefined to continue. */
+function evaluateDeclaredFailure(
+	input: EvaluatePhaseTransitionInput,
+	children: readonly PhaseChild[],
+	reworkCount: number,
+	maxRework: number,
+	now: () => number,
+): PhaseTransitionDecision | undefined {
+	if (input.terminalReason === "parent_decision") return allowed(input, reworkCount, now(), false);
+	if (input.terminalReason === "rework_exhausted") {
+		if (reworkCount <= maxRework) {
+			return denied(input, "rework_limit_exceeded", `rework_count must exceed ${maxRework} for rework_exhausted`);
 		}
-		return allowed(input, reworkCount, now(), true);
+		return allowed(input, reworkCount, now(), false);
 	}
-	if (from === "verifying" && to === "done") {
-		if (input.verificationPassed !== true) {
-			return denied(input, "verification_not_passed", "done requires all verification commands to pass");
-		}
-		if (children.some((child) => !isTerminalChild(child.status))) {
-			return denied(input, "children_not_terminal", "DONE requires every child node to be terminal");
+	if (input.terminalReason === "all_children_failed") {
+		if (children.length === 0 || children.some((child) => child.status !== "failed")) {
+			return denied(input, "all_children_not_failed", "all_children_failed requires every child to have failed");
 		}
 		return allowed(input, reworkCount, now(), false);
 	}
-	return denied(input, "invalid_transition", `transition ${from} → ${to} is not allowed`);
+	return denied(input, "terminal_reason_required", "failed requires parent decision, all children failed, or exhausted rework");
+}
+
+function conditionInput(input: EvaluatePhaseTransitionInput): PhaseConditionInput {
+	return {
+		children: input.children ?? [],
+		...(input.failedWorkerHandledIds ? { handledIds: input.failedWorkerHandledIds } : {}),
+		...(input.contractPath !== undefined ? { contractPath: input.contractPath } : {}),
+		...(input.contractPresent !== undefined ? { contractPresent: input.contractPresent } : {}),
+		...(input.reviewerVerdictOk !== undefined ? { verdictOk: input.reviewerVerdictOk } : {}),
+		...(input.verificationPassed !== undefined ? { verificationPassed: input.verificationPassed } : {}),
+		reworkCount: input.reworkCount ?? 0,
+		...(input.machine?.maxRework !== undefined ? { maxRework: input.machine.maxRework } : {}),
+	};
+}
+
+/** Pure decision function for the §7.1 transition table and entry invariants. */
+export function evaluatePhaseTransition(
+	input: EvaluatePhaseTransitionInput,
+	now: () => number = () => Date.now(),
+): PhaseTransitionDecision {
+	// #298: the declarative path is the ONLY path, with the built-in machine as the
+	// default. The old switch was removed rather than kept as a fallback: it gated
+	// `reviewing -> verifying` on a settled `role === "reviewer"`, so once the
+	// bundled reviewer card is gone a team could never leave review. Conditions
+	// express the same intent without naming a role.
+	//
+	// Normalization happens here, not only at parse time: the universal terminals
+	// (`done`/`failed`/`aborted`) must exist for ANY machine reaching this point —
+	// including one built in code — because a team that cannot be aborted is a
+	// safety hole. Normalization only ADDS those terminals; taking them stays gated.
+	return evaluateDeclarative(input, normalizePhaseMachine(input.machine ?? DEFAULT_PHASE_MACHINE), now);
 }
 
+
 export interface PhaseTimeoutInput {
-	phase: LegionPhase;
+	/** Phase id; free-form under a declared machine (#298). */
+	phase: string;
 	phaseSince: number | null;
 	now?: number;
-	timeouts?: Partial<Record<LegionPhase, number>>;
+	/** Per-phase overrides. Free-form ids when a declared machine is in play. */
+	timeouts?: Partial<Record<string, number>>;
 }
 
 export interface PhaseTimeoutResult {
-	phase: LegionPhase;
+	phase: string;
 	timedOut: boolean;
 	phaseSince: number | null;
 	now: number;
@@ -204,20 +340,26 @@ export function checkPhaseTimeout(
 	input: PhaseTimeoutInput,
 	clock: () => number = () => Date.now(),
 ): PhaseTimeoutResult {
-	if (!isLegionPhase(input.phase)) throw new TypeError(`invalid legion phase: ${String(input.phase)}`);
+	// A declared machine defines its own phase names, so this no longer rejects an
+	// unknown id outright — the caller resolves a timeout first and only asks here
+	// for a declared phase.
+	if (typeof input.phase !== "string" || !input.phase) {
+		throw new TypeError(`invalid legion phase: ${String(input.phase)}`);
+	}
 	const now = input.now ?? clock();
 	if (!Number.isFinite(now)) throw new TypeError("now must be a finite millisecond timestamp");
 	if (input.phaseSince !== null && !Number.isFinite(input.phaseSince)) {
 		throw new TypeError("phaseSince must be null or a finite millisecond timestamp");
 	}
-	const timeoutMs = input.timeouts?.[input.phase] ?? DEFAULT_PHASE_TIMEOUTS[input.phase];
+	const override = input.timeouts?.[input.phase];
+	const timeoutMs = override ?? DEFAULT_PHASE_TIMEOUTS[input.phase as LegionPhase] ?? 0;
 	if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
 		throw new TypeError("phase timeout must be a finite non-negative duration");
 	}
 	const elapsedMs = input.phaseSince === null ? null : Math.max(0, now - input.phaseSince);
 	return {
 		phase: input.phase,
-		timedOut: elapsedMs !== null && !isTerminalPhase(input.phase) && elapsedMs >= timeoutMs,
+		timedOut: elapsedMs !== null && !isTerminalPhase(input.phase) && timeoutMs > 0 && elapsedMs >= timeoutMs,
 		phaseSince: input.phaseSince,
 		now,
 		elapsedMs,
@@ -225,7 +367,7 @@ export function checkPhaseTimeout(
 	};
 }
 
-export function isTerminalPhase(phase: LegionPhase): boolean {
+export function isTerminalPhase(phase: string): boolean {
 	return phase === "done" || phase === "failed" || phase === "aborted";
 }
 
@@ -237,42 +379,7 @@ export function isLegionPhase(value: unknown): value is LegionPhase {
 	return typeof value === "string" && (LEGION_PHASES as readonly string[]).includes(value);
 }
 
-function evaluateRework(
-	input: EvaluatePhaseTransitionInput,
-	reworkCount: number,
-	now: () => number,
-): PhaseTransitionDecision {
-	const next = reworkCount + 1;
-	if (next > MAX_REWORK_COUNT) {
-		return {
-			...denied(input, "rework_limit_exceeded", `rework count ${next} exceeds limit ${MAX_REWORK_COUNT}`),
-			forcedTransition: { to: "failed", reworkCount: next, reason: "rework_exhausted" },
-		};
-	}
-	return allowed(input, next, now(), false);
-}
 
-function evaluateFailure(
-	input: EvaluatePhaseTransitionInput,
-	children: readonly PhaseChild[],
-	reworkCount: number,
-	now: () => number,
-): PhaseTransitionDecision {
-	if (input.terminalReason === "parent_decision") return allowed(input, reworkCount, now(), false);
-	if (input.terminalReason === "rework_exhausted") {
-		if (reworkCount <= MAX_REWORK_COUNT) {
-			return denied(input, "rework_limit_exceeded", `rework_count must exceed ${MAX_REWORK_COUNT} for rework_exhausted`);
-		}
-		return allowed(input, reworkCount, now(), false);
-	}
-	if (input.terminalReason === "all_children_failed") {
-		if (children.length === 0 || children.some((child) => child.status !== "failed")) {
-			return denied(input, "all_children_not_failed", "all_children_failed requires every child to have failed");
-		}
-		return allowed(input, reworkCount, now(), false);
-	}
-	return denied(input, "terminal_reason_required", "failed requires parent decision, all children failed, or exhausted rework");
-}
 
 function allowed(
 	input: EvaluatePhaseTransitionInput,
@@ -308,6 +415,3 @@ function denied(
 	return { allowed: false, from: input.from, to: input.to, reason, message, alarm: true };
 }
 
-function isActiveChild(status: string): boolean {
-	return status === "starting" || status === "running" || status === "blocked";
-}

package/src/runs/args.ts

@@ -14,6 +14,7 @@ import {
 	isThinkingLevel,
 } from "../shared/types.ts";
 import { formatChildTask } from "../extension/child-guard.ts";
+import { childInheritsExtensions, discoveredHostExtensions, inheritedExtensions } from "./extension-inheritance.ts";
 
 /** Re-exported for callers that only need the level list. */
 export { THINKING_LEVELS };
@@ -162,15 +163,11 @@ export function childExtraExtensions(env: NodeJS.ProcessEnv = process.env): stri
 }
 
 /**
- * Escape hatch (#43): role frontmatter `inheritExtensions: true`, or
- * `PI_LEGION_CHILD_INHERIT_EXTENSIONS=1` for every child, restores the old
- * behaviour of loading all host-discovered extensions.
+ * Re-exported from `extension-inheritance.ts`, which owns the policy (#280).
+ * Kept here because `args.ts` is the historical import site for the rpc argument
+ * builder and `legion-doctor`.
  */
-export function childInheritsExtensions(agent: Pick<AgentConfig, "inheritExtensions">, env: NodeJS.ProcessEnv = process.env): boolean {
-	if (agent.inheritExtensions === true) return true;
-	const raw = env[CHILD_INHERIT_EXTENSIONS_ENV]?.trim().toLowerCase();
-	return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
-}
+export { childInheritsExtensions } from "./extension-inheritance.ts";
 
 /** Light pi builtin that registers the `codemode` tool (`-e builtin:codemode`). */
 export const BUILTIN_CODEMODE = "builtin:codemode";
@@ -195,16 +192,29 @@ export function isCodemodeExtension(ext: string): boolean {
 }
 
 /**
- * Effective `--extension` values for a child under `--no-extensions`.
+ * Effective `--extension` values for a child.
+ *
+ * Order is deliberate: inherited host extensions FIRST (they are ambient
+ * capabilities the child would otherwise lose), then the role's own explicit
+ * list, then `PI_LEGION_CHILD_EXTENSIONS`, then `builtin:codemode` (#89), and
+ * finally the child-guard — which is unconditional and never subject to
+ * `inheritExtensions` / `excludeExtensions`, because a child without it breaks
+ * the prompt/format contract regardless of what the card asked for.
  *
- * Includes role `extensions` / `subagentOnlyExtensions`, `PI_LEGION_CHILD_EXTENSIONS`,
- * auto `builtin:codemode` when `tools` lists `codemode` (#89), and the child-guard.
+ * #280: the inherited set is computed by `inheritedExtensions` and is empty when
+ * the card sets `inheritExtensions: false`; `excludeExtensions` subtracts from
+ * it. Inherited paths are subject to the same dedupe as everything else, so a
+ * card that also names an inherited extension does not load it twice.
  */
 export function collectChildExtensions(
-	agent: Pick<AgentConfig, "tools" | "extensions" | "subagentOnlyExtensions">,
+	agent: Pick<
+		AgentConfig,
+		"tools" | "extensions" | "subagentOnlyExtensions" | "inheritExtensions" | "excludeExtensions"
+	>,
 	env: NodeJS.ProcessEnv = process.env,
 ): string[] {
 	const list = [
+		...inheritedExtensions(agent, discoveredHostExtensions() ?? []),
 		...(agent.extensions ?? []),
 		...(agent.subagentOnlyExtensions ?? []),
 		...childExtraExtensions(env),
@@ -234,12 +244,16 @@ function pushToolArgs(args: string[], agent: AgentConfig): void {
 		args.push("--tools", tools.join(","));
 	}
 
-	// Only pass through what the agent explicitly lists: a child must not
-	// 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 + auto builtin:codemode + this package for the guard) still load.
-	if (!childInheritsExtensions(agent)) args.push("--no-extensions");
+	// #280: pi's own discovery is ALWAYS disabled and the full list is passed
+	// explicitly. `--no-extensions` only drops the settings-discovered set; `-e`
+	// paths (below) and builtins still load, so this is the shape that keeps the
+	// child's extension set exactly equal to what we computed — the inherited set
+	// minus `excludeExtensions`, plus the role's own list, plus the child-guard.
+	//
+	// Letting pi discover as well would silently re-add an extension the card
+	// excluded, and would make rpc disagree with in-process (which builds its
+	// loader with `noExtensions: true` for the same reason).
+	args.push("--no-extensions");
 	for (const ext of collectChildExtensions(agent)) {
 		args.push("--extension", ext);
 	}