pi-legion 2.0.0 → 2.0.2

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,
@@ -62,6 +64,7 @@ import { nativeModelFor } from "./kind.ts";
 import { applyVerification, type VerifyRunner } from "./acceptance.ts";
 import {
 	createChildWorktree,
+	isInsideChildWorktree,
 	removeChildWorktree,
 	resolveLaunchWorktree,
 } from "./worktree.ts";
@@ -239,6 +242,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 +496,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;
@@ -529,7 +536,11 @@ export class Orchestrator {
 			? true
 			: this.legion && parentRole === "centurion"
 				? false
-				: resolveLaunchWorktree({ roleDefault: input.agent.worktree, launch: input.worktree });
+				: resolveLaunchWorktree({
+					roleDefault: input.agent.worktree,
+					launch: input.worktree,
+					parentInWorktree: isInsideChildWorktree(this.cwd),
+				});
 		let worktreePath = previous?.worktreePath;
 		let worktreeBranch = previous?.worktreeBranch;
 		let createdWorktree = false;
@@ -598,6 +609,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 +872,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 +1115,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/provision.ts

@@ -58,7 +58,13 @@ function writeMarker(worktreePath: string, mode: string): void {
 	fs.renameSync(tmp, file);
 }
 
-/** Repo-relative manifests, in resolution order, for the npm-install mode. */
+/** Repo-relative manifests, in resolution order, for the npm-install mode.
+ *
+ * The bare package.json fallback was removed: a package.json without any
+ * lockfile is far more often a non-npm repo caught by mistake (Java/Maven
+ * repos carry stray package.json files for docs/tooling) than a real npm
+ * project (which always has a lockfile). Without a lockfile we skip
+ * provisioning instead of firing npm install into a Java checkout. */
 function installCommandFor(worktreePath: string): string | null {
 	if (fs.existsSync(path.join(worktreePath, "pnpm-lock.yaml"))) {
 		return "pnpm install --frozen-lockfile";
@@ -72,9 +78,6 @@ function installCommandFor(worktreePath: string): string | null {
 	if (fs.existsSync(path.join(worktreePath, "package-lock.json"))) {
 		return "npm ci";
 	}
-	if (fs.existsSync(path.join(worktreePath, "package.json"))) {
-		return "npm install";
-	}
 	return null;
 }
 

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/runs/worktree.ts

@@ -24,17 +24,49 @@ export function worktreePathFor(runDir: string, name: string): string {
  * Per-step tool field wins, then the top-level `subagent({ worktree })`
  * argument, then the role default. The parent (group) agent is supposed to
  * pick this; the role default is only the fallback when it omits the field.
+ *
+ * Nesting suppression: when the parent cwd is itself a child worktree
+ * (git-dir ≠ git-common-dir), the role default and launch fallback collapse
+ * to false — a worktree of a worktree only re-pays the bootstrap tax.
+ * Explicit `launch: true`/`step: true` still wins: the caller saw the
+ * suppression and insisted.
  */
 export function resolveLaunchWorktree(opts: {
 	roleDefault?: boolean;
 	launch?: boolean;
 	step?: boolean;
+	parentInWorktree?: boolean;
 }): boolean {
 	if (typeof opts.step === "boolean") return opts.step;
 	if (typeof opts.launch === "boolean") return opts.launch;
+	if (opts.parentInWorktree) return false;
 	return opts.roleDefault === true;
 }
 
+/**
+ * True when cwd is itself a linked git worktree (child of a main checkout).
+ * Detected via `git rev-parse --git-dir` vs `--git-common-dir`: they differ
+ * inside any linked worktree, including ones created by other agent runs.
+ * Non-git directories report both as ".git" and are treated as not-in-worktree;
+ * the later createChildWorktree call owns the "not a repo" error.
+ */
+export function isInsideChildWorktree(cwd: string): boolean {
+	try {
+		const gitDir = execFileSync("git", ["-C", cwd, "rev-parse", "--git-dir"], {
+			stdio: ["ignore", "pipe", "pipe"],
+			encoding: "utf8",
+		}).trim();
+		const commonDir = execFileSync(
+			"git",
+			["-C", cwd, "rev-parse", "--git-common-dir"],
+			{ stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" },
+		).trim();
+		return gitDir !== commonDir && gitDir !== "" && commonDir !== "";
+	} catch {
+		return false;
+	}
+}
+
 /** Branch the child commits on. Unique per launch so two workers never collide. */
 export function worktreeBranchFor(name: string, nonce?: string): string {
 	const tag = nonce ?? randomBytes(4).toString("hex");

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/status.ts

@@ -598,7 +598,7 @@ export interface StatusVizSnapshot {
 	nodes: VizNode[];
 	sampler: RateSampler;
 	now: number;
-	/** Shared output tok/s (ΔtokensOut / ΔgenerationMs over trailing 60s). */
+	/** Header "now" tok/s (live agents only; 0 when none running). */
 	rate: number;
 }
 
@@ -608,8 +608,6 @@ export interface StatusBoard {
 	vizSnapshot?(now?: number): StatusVizSnapshot;
 	paint(entries: StatusEntry[], now: number): void;
 	clear(): void;
-	/** Show the idle stop hint in the railway header (main agent idle, children live). */
-	setIdleHint?(on: boolean): void;
 	/** The TUI the widget is mounted in, when registered (for focus/overlay checks). */
 	getTui?(): unknown;
 }
@@ -646,7 +644,6 @@ export function createStatusBoard(options: {
 	let tui: WidgetTui | undefined;
 	let railScroll: RailScroll = { offset: 0 };
 	let railWindow: { offset: number; total: number; maxLanes: number } | undefined;
-	let idleHint = false;
 
 	const renderLines = (now: number, theme: Theme, width?: number): {
 		lines: string[];
@@ -655,8 +652,9 @@ export function createStatusBoard(options: {
 	} => {
 		if (strip === "railway" && hasTreeIdentity(entries) && width !== undefined && width >= 20) {
 			const nodes = nodesFromEntries(entries);
-			const hint = idleHint ? { hint: IDLE_STOP_HINT, hintShort: IDLE_STOP_HINT_SHORT } : {};
-			const rendered = railwayLines({ nodes, now, width, rate: sampler.totalRate(now), scroll: railScroll, ...hint }, theme);
+			// Live-child gate: railway only renders when lanes exist; always show stop hint.
+			const hint = { hint: IDLE_STOP_HINT, hintShort: IDLE_STOP_HINT_SHORT };
+			const rendered = railwayLines({ nodes, now, width, rate: sampler.nowRate(now, nodes), scroll: railScroll, ...hint }, theme);
 			// Persist the clamped window (anchored on the top lane's agent) so later
 			// renders follow ends/starts without jumping; resets to 0 when all fit.
 			railWindow = rendered.window;
@@ -666,10 +664,14 @@ export function createStatusBoard(options: {
 		railWindow = undefined;
 		const visible = visiblePanelEntries(entries);
 		const totals = statusTotals(entries);
-		const rows = formatWidgetRows(visible, now, totals);
+		let rows = formatWidgetRows(visible, now, totals);
+		// Tree strip + Legion identity: short stop hint on its own row (survives width squeeze).
+		if (strip === "tree" && hasTreeIdentity(entries) && rows.length > 0) {
+			rows = [rows[0]!, { text: IDLE_STOP_HINT_SHORT }, ...rows.slice(1)];
+		}
 		const nodeIdsByRow = rows.map((row) => row.nodeId);
 		return {
-			lines: themeLines(formatWidgetLines(visible, now, totals), theme),
+			lines: themeLines(rows.map((row) => row.text), theme),
 			hitAt: (_x, y) => nodeIdsByRow[y],
 		};
 	};
@@ -796,16 +798,12 @@ export function createStatusBoard(options: {
 			if (hasTreeIdentity(next)) sampler.record(_now, nodesFromEntries(next));
 			paint();
 		},
-		setIdleHint(on) {
-			if (idleHint === on) return;
-			idleHint = on;
-			tui?.requestRender();
-		},
 		getTui() {
 			return tui;
 		},
 		vizSnapshot(now = Date.now()) {
-			return { nodes: nodesFromEntries(entries), sampler, now, rate: sampler.totalRate(now) };
+			const nodes = nodesFromEntries(entries);
+			return { nodes, sampler, now, rate: sampler.nowRate(now, nodes) };
 		},
 		clear() {
 			entries = [];

package/src/tui/viz/canvas.ts

@@ -87,6 +87,11 @@ function isWide(code: number): boolean {
 	);
 }
 
+/** Grapheme / cell count (UTF-16-safe). Prefer over `String.length` for layout budgets. */
+export function cellWidth(value: string): number {
+	return Array.from(value).length;
+}
+
 /** Truncate plain text to `width` single-width cells with an ellipsis. */
 export function ellipsize(value: string, width: number): string {
 	const chars = Array.from(value).map(sanitizeChar);

package/src/tui/viz/panels.ts

@@ -1,6 +1,6 @@
 /** Panel renderers for the /legion full view. All drawing is clipped to its rect. */
 
-import { Canvas, ellipsize } from "./canvas.ts";
+import { Canvas, cellWidth, ellipsize } from "./canvas.ts";
 import type { Rect } from "./layout.ts";
 import { formatCount, formatDuration, isAgent, type VizNode } from "./model.ts";
 import { nodeToken, roleColor } from "./palette.ts";
@@ -12,7 +12,7 @@ export interface ViewData {
 	nodes: readonly VizNode[];
 	sampler: RateSampler;
 	now: number;
-	/** Shared output tok/s (ΔtokensOut / ΔgenerationMs over trailing 60s). */
+	/** Header "now" tok/s (live agents only; 0 when none running). Chart avg/buckets keep full-series windows. */
 	rate: number;
 }
 
@@ -241,21 +241,29 @@ export function drawGalaxy(cv: Canvas, r: Rect, data: ViewData, selectedId: stri
 		}
 	}
 	// Legend: roles that actually appear (dynamic), then status hints.
+	// Reserve room for failed/retired glyphs first so a narrow panel still matches live scout (#102/#125).
 	const ly = r.y + r.h - 1;
 	let lx = r.x + 1;
 	const roles: string[] = [];
 	for (const node of dfsOrder(nodes)) if (isAgent(node) && !roles.includes(node.role)) roles.push(node.role);
+	const statuses = new Set(nodes.map((node) => node.status));
+	const statusItems = ([["failed", "✗ failed", "error"], ["retired", "⣿ retired", "dim"]] as const)
+		.filter(([status]) => statuses.has(status));
+	// Budget in grapheme cells (not String.length) so multi-byte / emoji labels do not squeeze roles (#128).
+	const statusBudget = statusItems.reduce((sum, [, label]) => sum + cellWidth(label) + 2, 0);
+	const roleLimit = r.x + r.w - 1 - statusBudget;
 	for (const role of roles) {
-		const w = Array.from(role).length + 4;
-		if (lx + w > r.x + r.w - 1) break;
+		const w = cellWidth(role) + 4;
+		if (lx + w > roleLimit) break;
 		cv.set(lx, ly, "⣿", roleColor(role));
 		cv.text(lx + 2, ly, role, "dim");
 		lx += w;
 	}
-	for (const [label, col] of [["✗ failed", "error"], ["⣿ retired", "dim"]] as const) {
-		if (lx + label.length + 1 > r.x + r.w - 1) break;
+	for (const [, label, col] of statusItems) {
+		const lw = cellWidth(label);
+		if (lx + lw + 1 > r.x + r.w - 1) break;
 		cv.text(lx, ly, label, col);
-		lx += label.length + 2;
+		lx += lw + 2;
 	}
 }
 
@@ -300,7 +308,7 @@ export function computeStats(data: ViewData, buckets: number): ChartStats {
 	}
 	return {
 		now: data.rate,
-		// Same definition as header "now", averaged over the chart window.
+		// Full-series window average (includes settled); differs from header "now" on purpose.
 		avg: data.sampler.totalRate(to, Math.max(1, to - from)),
 		peak,
 		peakAt,

package/src/tui/viz/railway.ts

@@ -39,14 +39,14 @@ export interface RailInput {
 	nodes: readonly VizNode[];
 	now: number;
 	width: number;
-	/** Output tok/s over the shared 60s generation window. */
+	/** Header "now" tok/s (live agents only; 0 when none running). */
 	rate: number;
 	windowMs?: number;
 	/** Lane scroll position when more agents are live than lanes fit. */
 	scroll?: RailScroll;
-	/** Dim hint on the header rule (e.g. stop controls while the main agent is idle). */
+	/** Dim hint on the header rule (e.g. `/legion stop` while children are live). */
 	hint?: string;
-	/** Shorter variant used when the full hint does not fit. */
+	/** Shorter variant used when the full hint does not fit; truncated further under squeeze. */
 	hintShort?: string;
 }
 
@@ -234,18 +234,41 @@ export function renderRailway(input: RailInput): RailRender | undefined {
 	const winLabel = ` −${Math.max(1, Math.round(windowMs / 60000))}m `;
 	canvas.text(LX + 1, 0, winLabel, "dim");
 	const range = above || below ? ` · ${scrollIndicator(current.offset, rows, live)} ${above ? "▲" : " "}${below ? "▼" : " "}` : "";
-	const header = portrait
+	const headerFull = portrait
 		? ` ${live} live${range} · ${rateText} `
 		: ` legion ${live} live${range} · ${rateText} `;
-	const headerX = Math.max(LX + 1 + winLabel.length, width - header.length - 1);
-	canvas.text(headerX, 0, header, "accent", { bold: true, maxX: width - 1 });
+	// Hint sits between the window label and the right-hand summary. Prefer the
+	// full string, then short; when width squeezes, shrink the summary so the
+	// short `/legion stop` still fits, and only then ellipsize the hint.
+	const labelEnd = LX + 1 + winLabel.length;
+	const hx = labelEnd + 1;
+	let header = headerFull;
+	let headerX = Math.max(labelEnd, width - Array.from(header).length - 1);
+	let hintPick: string | undefined;
 	if (input.hint) {
-		// Between the window label and the summary, with a rule gap on both sides.
-		const hx = LX + 1 + winLabel.length + 1;
-		const room = headerX - 1 - hx;
-		const pick = [input.hint, input.hintShort].find((text) => text && Array.from(text).length + 2 <= room);
-		if (pick) canvas.text(hx, 0, ` ${pick} `, "dim");
+		const short = input.hintShort ?? input.hint;
+		const shortBlock = Array.from(short).length + 2; // leading+trailing spaces
+		const gap = 1; // rule cell between hint and summary
+		const needHeaderX = hx + shortBlock + gap;
+		if (headerX < needHeaderX) {
+			// Pull/truncate the summary so short hint keeps a slot.
+			headerX = Math.min(width - 1, Math.max(needHeaderX, labelEnd));
+			const avail = Math.max(0, width - 1 - headerX);
+			header = avail >= 3 ? ` ${ellipsize(headerFull.trim(), avail - 2)} ` : "";
+			if (header) headerX = Math.max(labelEnd, width - Array.from(header).length - 1);
+			// Re-assert short reservation if summary still crowds the hint.
+			if (header && headerX < needHeaderX) {
+				headerX = needHeaderX;
+				const clipped = Math.max(0, width - 1 - headerX);
+				header = clipped >= 3 ? ` ${ellipsize(headerFull.trim(), clipped - 2)} ` : "";
+			}
+		}
+		const room = Math.max(0, (header ? headerX - 1 : width - 1) - hx);
+		hintPick = [input.hint, input.hintShort].find((text) => text && Array.from(text).length + 2 <= room);
+		if (!hintPick && room >= 3) hintPick = ellipsize(short, room - 2);
 	}
+	if (header) canvas.text(headerX, 0, header, "accent", { bold: true, maxX: width - 1 });
+	if (hintPick) canvas.text(hx, 0, ` ${hintPick} `, "dim");
 	for (const [c, tick] of headerTicks) {
 		if (canvas.get(LX + c, 0)?.ch !== "─") continue; // never draw over header text
 		canvas.set(LX + c, 0, "┬", tick.color);