@howarewoo/pi-subagents 0.0.0-stage → 0.2.0

package/src/profile-viewer.ts

@@ -0,0 +1,246 @@
+import type { Skill, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  colorToOklch,
+  oklchColor,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+  type Component,
+  type KeybindingsManager,
+} from "@earendil-works/pi-tui";
+import { safe } from "./thread.ts";
+import { bundledProfiles, resolveProfile, type Profile } from "./profiles.ts";
+
+export const profileToolPolicy =
+  "Profile tools are maximum allowlists, not requirements. Admission intersects callable parent builtins without activating tools. Command context has no callable-tool dispatcher: effective tools are unknown here. Active declarations are not proof of callability. General inherits available parent skills and callable builtins within its ceiling, not parent instructions/history; only operator-reviewed leaf tools may be forwarded and all require a writer lease. Leaf grants assert trusted code, not a sandbox. Inspect task snapshot tools, leafTools, skills and capabilityDenials for admitted grants.";
+
+/** Resolve through the same trust/config/skill validation boundary used by admission. */
+export async function resolvedProfiles(
+  cwd: string,
+  trusted: boolean,
+  operatorDir?: string,
+  availableSkills: readonly Skill[] = [],
+): Promise<Profile[]> {
+  return Promise.all(
+    bundledProfiles().map(
+      async ({ name }) =>
+        (await resolveProfile(name, cwd, trusted, operatorDir, availableSkills)).profile,
+    ),
+  );
+}
+
+type DetailLine = { text: string; heading?: boolean };
+
+function details(profile: Profile): DetailLine[] {
+  const list = (items: readonly string[] | undefined) =>
+    items?.length ? items.join(", ") : "none";
+  const known = new Set([
+    "name",
+    "description",
+    "prompt",
+    "tools",
+    "skills",
+    "leafTools",
+    "spawn",
+    "coordination",
+    "models",
+    "model",
+    "prewalk",
+  ]);
+  const heading = (text: string): DetailLine => ({ text, heading: true });
+  const value = (text: string): DetailLine => ({ text });
+  const structured = (label: string, item: unknown, indent = ""): DetailLine[] => {
+    if (Array.isArray(item))
+      return [
+        value(`${indent}${label}:${item.length ? "" : " none (empty grant)"}`),
+        ...item.flatMap((entry, index) =>
+          structured(`Selection ${index + 1}`, entry, indent + "  "),
+        ),
+      ];
+    if (item && typeof item === "object")
+      return [
+        value(`${indent}${label}:`),
+        ...Object.entries(item).flatMap(([key, entry]) => structured(key, entry, indent + "  ")),
+      ];
+    return [value(`${indent}${label}: ${String(item)}`)];
+  };
+  return [
+    heading("Description"),
+    value(profile.description),
+    value(""),
+    heading("Prompt"),
+    value(profile.prompt),
+    value(""),
+    heading("Tools and permissions"),
+    value(`Tools ceiling: ${list(profile.tools)}`),
+    value("Callable tools: unknown in command context; inspect admitted task tools."),
+    ...(profile.name === "general"
+      ? [
+          value(
+            "Inheritance: available parent skills and callable builtins; no parent instructions/history.",
+          ),
+        ]
+      : []),
+    value(
+      `Reviewed leaf ceiling: ${list(profile.leafTools)} (writer lease; trusted code, not sandboxed)`,
+    ),
+    value(`Spawn ceiling: ${list(profile.spawn)}`),
+    value(`Coordination: ${list(profile.coordination)}`),
+    value(""),
+    heading("Skills (exact paths)"),
+    ...(profile.skills.length ? profile.skills.map(value) : [value("none")]),
+    value(""),
+    heading("Model policy"),
+    ...structured("Model default", profile.model ?? "selected parent model"),
+    ...structured("Models grant", profile.models ?? "no explicit override grant"),
+    ...structured("Prewalk", profile.prewalk ?? "off"),
+    ...Object.entries(profile)
+      .filter(([key]) => !known.has(key))
+      .map(([key, item]) => value(`${key}: ${JSON.stringify(item)}`)),
+    value(""),
+    value(
+      "Admission also applies parent/ancestry, model availability, capacity and writer checks. This viewer grants nothing.",
+    ),
+  ];
+}
+
+/** Read-only snapshot consumer; no fixed role count or policy defaults in the renderer. */
+export function createProfileViewer(
+  profiles: readonly Profile[],
+  theme: Pick<Theme, "fg" | "style"> & { colors: Pick<Theme["colors"], "customMessageBg"> },
+  keys: Pick<KeybindingsManager, "matches" | "getKeys">,
+  requestRender: () => void,
+  done: () => void,
+  availableRows: () => number,
+): Component {
+  let selected = 0;
+  let offset = 0;
+  let viewport = 1;
+  let maximum = 0;
+  const cell = (text: string, width: number) => {
+    const clipped = truncateToWidth(text, width);
+    return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+  };
+  return {
+    render(width) {
+      width = Math.max(0, width);
+      const height = Math.max(1, Math.floor(availableRows()));
+      const close = keys.getKeys("tui.select.cancel").join("/") || "Esc";
+      const panelBg = oklchColor(colorToOklch(theme.colors.customMessageBg).l, 0, 0);
+      // Match the Hub: foreground helpers may reset both colors inside a painted line.
+      const paint = (text: string) => {
+        const padded = cell(text, width);
+        const restoreBg = theme.style("", { bg: panelBg }).replace("\x1b[49m", "");
+        return padded
+          .split("\x1b[0m")
+          .map((part) => theme.style(part.replaceAll("\x1b[49m", restoreBg), { bg: panelBg }))
+          .join("\x1b[0m");
+      };
+      const fallback = () =>
+        [`Profiles · ${safe(close)}: close`, "Resize for details"].slice(0, height).map(paint);
+      if (width < 24) return fallback();
+      const inner = width - 4;
+      const wide = width >= 88;
+      const leftWidth = wide ? Math.min(28, Math.floor(inner / 3)) : inner;
+      const rightWidth = wide ? inner - leftWidth - 3 : inner;
+      const footer = [
+        "↑↓ select · j/k scroll · PgUp/Dn · Home/End",
+        `${safe(close)}: close · callable tools unknown here`,
+      ].flatMap((line) => wrapTextWithAnsi(line, inner));
+      // Frames, divider and hints are reserved before assigning any viewport rows.
+      const bodyHeight = height - 3 - footer.length;
+      const listHeight = wide ? bodyHeight : Math.min(3, Math.max(1, Math.floor(bodyHeight / 3)));
+      const detailHeight = wide ? bodyHeight : bodyHeight - listHeight - 1;
+      if (detailHeight < 4) return fallback();
+      viewport = detailHeight - 3;
+      const start = Math.max(0, selected - listHeight + 1);
+      const roster = profiles
+        .slice(start, start + listHeight)
+        .map((profile, index) =>
+          theme.fg(
+            start + index === selected ? "accent" : "text",
+            `${start + index === selected ? ">" : " "} ${safe(profile.name).replaceAll("\n", " ")}`,
+          ),
+        );
+      const profile = profiles[selected];
+      const name = profile ? safe(profile.name).replaceAll("\n", " ") : "No selection";
+      const content = profile ? details(profile) : [{ text: "No resolved profiles" }];
+      // A clipped pinned name still has a complete, scrollable representation.
+      if (profile && (visibleWidth(name) > rightWidth || profile.name.includes("\n")))
+        content.unshift({ text: profile.name });
+      const lines = content.flatMap(({ text, heading }) =>
+        safe(text)
+          .split("\n")
+          .flatMap((line) =>
+            wrapTextWithAnsi(line, rightWidth).map((wrapped) =>
+              theme.fg(heading ? "accent" : "text", wrapped),
+            ),
+          ),
+      );
+      maximum = Math.max(0, lines.length - viewport);
+      offset = Math.min(maximum, offset);
+      const detail = [
+        theme.fg("accent", name),
+        theme.fg("muted", "resolved · read-only"),
+        ...lines.slice(offset, offset + viewport),
+        ...Array(Math.max(0, viewport - (lines.length - offset))).fill(""),
+        theme.fg(
+          "muted",
+          `${profiles.length ? selected + 1 : 0}/${profiles.length} · detail ${offset + 1}–${Math.min(lines.length, offset + viewport)}/${lines.length}`,
+        ),
+      ];
+      const body = wide
+        ? Array.from(
+            { length: bodyHeight },
+            (_, index) =>
+              cell(roster[index] ?? "", leftWidth) +
+              theme.fg("border", " │ ") +
+              cell(detail[index] ?? "", rightWidth),
+          )
+        : [
+            ...roster,
+            ...Array(Math.max(0, listHeight - roster.length)).fill(""),
+            theme.fg("border", "─".repeat(inner)),
+            ...detail,
+          ];
+      const row = (text: string) =>
+        paint(theme.fg("border", "│") + ` ${cell(text, inner)} ` + theme.fg("border", "│"));
+      const frame = (left: string, title: string, right: string) =>
+        paint(
+          theme.fg("border", left) +
+            theme.fg("accent", title) +
+            theme.fg("border", "─".repeat(Math.max(0, width - 2 - visibleWidth(title))) + right),
+        );
+      return [
+        frame("╭", " Subagent Profiles ", "╮"),
+        ...body.map(row),
+        frame("├", "", "┤"),
+        ...footer.map((line) => row(theme.fg("muted", line))),
+        frame("╰", "", "╯"),
+      ];
+    },
+    handleInput(data) {
+      if (keys.matches(data, "tui.select.cancel")) {
+        done();
+        return;
+      }
+      if (keys.matches(data, "tui.select.up") || keys.matches(data, "tui.select.down")) {
+        selected = Math.max(
+          0,
+          Math.min(profiles.length - 1, selected + (keys.matches(data, "tui.select.up") ? -1 : 1)),
+        );
+        offset = 0;
+      } else if (data === "j") offset = Math.min(maximum, offset + 1);
+      else if (data === "k") offset = Math.max(0, offset - 1);
+      else if (keys.matches(data, "tui.select.pageDown"))
+        offset = Math.min(maximum, offset + viewport);
+      else if (keys.matches(data, "tui.select.pageUp")) offset = Math.max(0, offset - viewport);
+      else if (matchesKey(data, "home")) offset = 0;
+      else if (matchesKey(data, "end")) offset = maximum;
+      else return;
+      requestRender();
+    },
+    invalidate() {},
+  };
+}

package/src/profiles.ts

@@ -0,0 +1,225 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import {
+  CONFIG_DIR_NAME,
+  getAgentDir,
+  loadSkills,
+  type Skill,
+} from "@earendil-works/pi-coding-agent";
+
+import { narrowModelPolicy, allowsModel, sameSelection, type ModelPolicy } from "./model-policy.ts";
+
+export const READ_TOOLS = ["read", "grep", "find", "ls"] as const;
+export const WRITE_TOOLS = [...READ_TOOLS, "write", "edit", "bash"] as const;
+export type BuiltinTool = (typeof WRITE_TOOLS)[number];
+export const COORDINATION_ACTIONS = ["message", "inbox", "wait"] as const;
+export type CoordinationAction = (typeof COORDINATION_ACTIONS)[number];
+/** Tool arrays are ceilings; admission intersects callable parent builtins before writer/ancestry checks. */
+export type Profile = Readonly<
+  ModelPolicy & {
+    name: string;
+    description: string;
+    prompt: string;
+    tools: readonly BuiltinTool[];
+    skills: readonly string[];
+    /** Operator-reviewed leaf tools; never a tool-to-tool forwarding grant. */
+    leafTools?: readonly string[];
+    spawn?: readonly string[];
+    coordination?: readonly CoordinationAction[];
+  }
+>;
+const bundled: Record<string, Profile> = {
+  general: {
+    name: "general",
+    description: "General delegation with restricted parent capabilities",
+    prompt: "Complete the assigned analysis and report the evidence and limitations.",
+    tools: WRITE_TOOLS,
+    skills: [],
+    spawn: ["scout", "review"],
+  },
+  scout: {
+    name: "scout",
+    description: "Explore and locate evidence",
+    prompt:
+      "Explore the assignment using read-only tools. Report precise source locations and findings.",
+    tools: READ_TOOLS,
+    skills: [],
+    spawn: ["scout", "review"],
+  },
+  review: {
+    name: "review",
+    description: "Review without modifying files",
+    prompt:
+      "Review the assigned work. Report actionable findings with source locations; do not edit files.",
+    tools: READ_TOOLS,
+    skills: [],
+    spawn: ["scout", "review"],
+  },
+  implementation: {
+    name: "implementation",
+    description:
+      "Implement changes in the supplied workspace (exclusive model-tool writer; manual shells are uncoordinated)",
+    prompt:
+      "Implement the assigned bounded change, verify it and report changed files and remaining risks. Work in your supplied cwd; root permissions and global model-tool writer coordination still apply.",
+    tools: WRITE_TOOLS,
+    skills: [],
+    spawn: ["scout", "review"],
+  },
+};
+
+async function config(path: string): Promise<Record<string, unknown>> {
+  try {
+    const value: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("expected object");
+    return value as Record<string, unknown>;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error(`Invalid delegation config ${path}: ${String(error)}`);
+  }
+}
+function strings(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string"))
+    throw new Error(`${field} must be a string array`);
+  return value;
+}
+function specialize(base: Profile, value: unknown, operator: boolean): Profile {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`Invalid profile ${base.name}`);
+  const input = value as Record<string, unknown>;
+  for (const key of Object.keys(input))
+    if (
+      ![
+        "description",
+        "prompt",
+        "tools",
+        "skills",
+        "leafTools",
+        "spawn",
+        "coordination",
+        "models",
+        "model",
+        "prewalk",
+      ].includes(key)
+    )
+      throw new Error(`Unsupported profile field: ${key}`);
+  const tools = input.tools === undefined ? [...base.tools] : strings(input.tools, "tools");
+  if (tools.some((tool) => !base.tools.includes(tool as BuiltinTool)))
+    throw new Error(`Profile ${base.name} cannot broaden tool grants`);
+  const skills = input.skills === undefined ? [...base.skills] : strings(input.skills, "skills");
+  if (skills.some((path) => !isAbsolute(path) || (!operator && !base.skills.includes(path))))
+    throw new Error(
+      `Profile ${base.name} cannot mint skill grants; operator paths must be absolute`,
+    );
+  const leafTools =
+    input.leafTools === undefined
+      ? [...(base.leafTools ?? [])]
+      : strings(input.leafTools, "leafTools");
+  if (
+    leafTools.some(
+      (name) => !name || base.name !== "general" || (!operator && !base.leafTools?.includes(name)),
+    )
+  )
+    throw new Error("Cannot mint leaf tool grants");
+  for (const field of ["description", "prompt"] as const)
+    if (input[field] !== undefined && typeof input[field] !== "string")
+      throw new Error(`${field} must be text`);
+  const spawn = input.spawn === undefined ? [...(base.spawn ?? [])] : strings(input.spawn, "spawn");
+  if (
+    spawn.some(
+      (name) => !Object.hasOwn(bundled, name) || (!operator && !base.spawn?.includes(name)),
+    )
+  )
+    throw new Error("Cannot mint spawn grants");
+  const coordination =
+    input.coordination === undefined
+      ? [...(base.coordination ?? [])]
+      : strings(input.coordination, "coordination");
+  if (
+    coordination.some(
+      (action) =>
+        !COORDINATION_ACTIONS.includes(action as CoordinationAction) ||
+        (!operator && !base.coordination?.includes(action as CoordinationAction)),
+    )
+  )
+    throw new Error("Cannot mint coordination grants");
+  return {
+    ...base,
+    ...narrowModelPolicy(base, input, operator),
+    coordination: coordination as CoordinationAction[],
+    spawn,
+    description: (input.description as string) ?? base.description,
+    prompt: (input.prompt as string) ?? base.prompt,
+    tools: tools as BuiltinTool[],
+    skills,
+    leafTools,
+  };
+}
+
+/** Operator config can grant exact skill paths; trusted project config can only narrow those grants. */
+export async function resolveProfile(
+  name: string,
+  cwd: string,
+  trusted: boolean,
+  operatorDir = getAgentDir(),
+  availableSkills: readonly Skill[] = [],
+): Promise<{ profile: Profile; skills: Skill[] }> {
+  let profile = bundled[name];
+  if (!Object.hasOwn(bundled, name)) throw new Error(`Unknown delegation profile: ${name}`);
+  if (name === "general")
+    profile = { ...profile, skills: availableSkills.map((skill) => skill.filePath) };
+  const user = await config(join(operatorDir, "delegation.json"));
+  for (const key of Object.keys(user))
+    if (key !== "scheduling" && !Object.hasOwn(bundled, key))
+      throw new Error(`Unknown operator profile: ${key}`);
+  if (user[name] !== undefined) profile = specialize(profile, user[name], true);
+  if (trusted) {
+    const project = await config(join(cwd, CONFIG_DIR_NAME, "delegation.json"));
+    for (const key of Object.keys(project))
+      if (key !== "scheduling" && !Object.hasOwn(bundled, key))
+        throw new Error(`Unknown project profile: ${key}`);
+    if (project[name] !== undefined) profile = specialize(profile, project[name], false);
+  }
+  for (const path of profile.skills) await readFile(path, "utf8");
+  const loaded = loadSkills({
+    cwd,
+    agentDir: operatorDir,
+    skillPaths: [...profile.skills],
+    includeDefaults: false,
+  });
+  if (loaded.diagnostics.length || loaded.skills.length !== profile.skills.length)
+    throw new Error(
+      "Granted skills must be valid, distinct skill files (not discovery directories)",
+    );
+  return { profile, skills: loaded.skills };
+}
+export function isWriter(profile: Profile): boolean {
+  return (
+    !!profile.leafTools?.length ||
+    profile.tools.some((tool) => !READ_TOOLS.includes(tool as (typeof READ_TOOLS)[number]))
+  );
+}
+
+export function bundledProfiles(): Profile[] {
+  return structuredClone(Object.values(bundled));
+}
+
+/** Keep current definitions/prompts but intersect executable grants with an admitted ceiling. */
+export function intersectProfileGrants(profile: Profile, maximum: Profile): Profile {
+  return {
+    ...profile,
+    models:
+      maximum.models === undefined
+        ? undefined
+        : (profile.models ?? []).filter((selection) => allowsModel(maximum, selection)),
+    prewalk:
+      profile.prewalk && maximum.prewalk && sameSelection(profile.prewalk, maximum.prewalk)
+        ? profile.prewalk
+        : undefined,
+    tools: profile.tools.filter((tool) => maximum.tools.includes(tool)),
+    leafTools: profile.leafTools?.filter((name) => maximum.leafTools?.includes(name)),
+    skills: profile.skills.filter((skill) => maximum.skills.includes(skill)),
+    spawn: profile.spawn?.filter((role) => maximum.spawn?.includes(role)),
+    coordination: profile.coordination?.filter((action) => maximum.coordination?.includes(action)),
+  };
+}

package/src/scheduling.ts

@@ -0,0 +1,73 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type ExecutionLimits = {
+  deadlineMs: number;
+  requests: number;
+  tools: number;
+  depth: number;
+  spawns: number;
+};
+export type SchedulingPolicy = ExecutionLimits & {
+  concurrency: number;
+  queue: number;
+  batch: number;
+};
+export const DEFAULT_POLICY: Readonly<SchedulingPolicy> = {
+  concurrency: 16,
+  queue: 32,
+  batch: 16,
+  depth: 2,
+  spawns: 8,
+  deadlineMs: 1800000,
+  requests: 100,
+  tools: 100,
+};
+const ceilings: SchedulingPolicy = {
+  concurrency: 16,
+  queue: 256,
+  batch: 64,
+  depth: 4,
+  spawns: 32,
+  deadlineMs: 3600000,
+  requests: 1000,
+  tools: 1000,
+};
+export function narrowLimits<T extends object>(base: T, value: unknown, maximum: T = base): T {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Limits must be an object");
+  const result = { ...base };
+  for (const [key, number] of Object.entries(value)) {
+    if (
+      !Object.hasOwn(base, key) ||
+      !Number.isSafeInteger(number) ||
+      (number as number) < (key === "depth" || key === "spawns" || key === "queue" ? 0 : 1) ||
+      (number as number) > (maximum as Record<string, number>)[key]
+    )
+      throw new Error(`Invalid or broadened limit: ${key}`);
+    (result as Record<string, unknown>)[key] = number;
+  }
+  return result;
+}
+export function validatePolicy(value: unknown): SchedulingPolicy {
+  return narrowLimits({ ...DEFAULT_POLICY }, value, ceilings);
+}
+export async function resolveScheduling(
+  cwd: string,
+  trusted: boolean,
+  operatorDir = getAgentDir(),
+): Promise<SchedulingPolicy> {
+  async function load(path: string): Promise<unknown> {
+    try {
+      return JSON.parse(await readFile(path, "utf8")).scheduling ?? {};
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+      throw error;
+    }
+  }
+  const operator = validatePolicy(await load(join(operatorDir, "delegation.json")));
+  return trusted
+    ? narrowLimits(operator, await load(join(cwd, CONFIG_DIR_NAME, "delegation.json")))
+    : operator;
+}

package/src/subagent-widget.ts

@@ -0,0 +1,115 @@
+import {
+  sliceByColumn,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+} from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ChildSnapshot } from "./coordinator.ts";
+import { active, activity, assignmentHeadline, lineText, statuses } from "./task-presentation.ts";
+
+/** Event-driven, bounded current-agent tree; history and full metrics remain in the Hub. */
+export function createChildWidget(
+  snapshot: () => ChildSnapshot[],
+  theme: Pick<Theme, "fg"> & Partial<Pick<Theme, "bold">>,
+  availableRows = () => 30,
+): Component {
+  return {
+    render(width) {
+      width = Math.max(0, width);
+      const children = snapshot();
+      if (!children.length) return [];
+      const queued = children.filter((child) => child.status === "queued").length;
+      const priority = (child: ChildSnapshot) =>
+        child.status === "draining" || child.status === "pausing"
+          ? 0
+          : child.status === "running"
+            ? 1
+            : child.status === "setup"
+              ? 2
+              : 3;
+      const live = children
+        .filter(
+          (child) =>
+            !child.disposed &&
+            (child.status === "setup" ||
+              child.status === "running" ||
+              child.status === "draining" ||
+              child.status === "pausing"),
+        )
+        .sort((a, b) => priority(a) - priority(b));
+      const budget = Math.max(1, Math.min(5, Math.floor(availableRows() / 4)));
+      const counts =
+        width < 60
+          ? `${live.filter(active).length} active · ${children.filter((child) => child.status === "paused").length} paused · ${queued} queued`
+          : statuses
+              .flatMap((status) => {
+                const count = children.filter((child) => child.status === status).length;
+                return count ? [`${count} ${status}`] : [];
+              })
+              .join(" · ");
+      const rows = [
+        theme.fg("accent", `● Subagents ${children.length}`) + theme.fg("muted", ` · ${counts}`),
+      ];
+      const room = Math.max(0, budget - 1);
+      const activityRows = live.length && room >= (live.length > 1 ? 3 : 2) ? 1 : 0;
+      const slots = room - activityRows;
+      const overflow = live.length > slots;
+      const shown = live.slice(0, Math.max(0, slots - (overflow ? 1 : 0)));
+      shown.forEach((child, index) => {
+        const last = index === shown.length - 1 && shown.length === live.length;
+        const color =
+          child.status === "draining" || child.status === "pausing" ? "warning" : "accent";
+        const role = lineText(child.profile);
+        const indent = "  ".repeat(Math.min(3, Math.max(0, child.depth - 1)));
+        const prefix =
+          theme.fg("muted", `${indent}${last ? "└─" : "├─"} `) +
+          theme.fg(color, "● ") +
+          (theme.bold?.(role) ?? role) +
+          " ";
+        const elapsed = Math.max(
+          0,
+          Math.floor(((child.endedAt ?? Date.now()) - child.createdAt) / 1000),
+        );
+        const stats = [
+          child.status,
+          `${elapsed}s`,
+          `${child.toolCalls} tools`,
+          ...(child.telemetry.requests === null ? [] : [`${child.telemetry.requests} req`]),
+          ...(child.telemetry.tokens ? [`${child.telemetry.tokens.total} tok`] : []),
+          ...(child.telemetry.cost === null ? [] : [`$${child.telemetry.cost.toFixed(3)}`]),
+        ].join(" · ");
+        const metric = truncateToWidth(stats, Math.max(8, Math.floor(width / 2)));
+        const headline = assignmentHeadline(child);
+        rows.push(
+          prefix +
+            theme.fg(
+              "text",
+              truncateToWidth(
+                headline,
+                Math.max(4, width - visibleWidth(prefix) - visibleWidth(metric) - 3),
+              ),
+            ) +
+            theme.fg("muted", " · " + metric),
+        );
+        if (!index && activityRows) {
+          const prefix = `${indent}${last ? "   " : "│  "} └ `;
+          const text = lineText(activity(child));
+          const columns = Math.max(0, width - visibleWidth(prefix));
+          const length = visibleWidth(text);
+          // Progress is an accumulated tail; keep its newest text, not a frozen opening paragraph.
+          const preview =
+            length > columns
+              ? "…" +
+                sliceByColumn(text, length - Math.max(0, columns - 1), Math.max(0, columns - 1))
+              : text;
+          rows.push(theme.fg("muted", prefix + preview));
+        }
+      });
+      if (shown.length < live.length && room)
+        rows.push(theme.fg("muted", `└─ ${live.length - shown.length} more · /subagent-hub`));
+      return rows.slice(0, budget).map((line) => truncateToWidth(line, width));
+    },
+    invalidate() {},
+  };
+}

package/src/supported-host.ts

@@ -0,0 +1,26 @@
+import { VERSION } from "@earendil-works/pi-coding-agent";
+
+const MINIMUM_PI_VERSION = "1.5.2";
+const minimum = MINIMUM_PI_VERSION.split(".").map(BigInt);
+
+/** Gate execution, not registration: root diagnostics and cleanup must remain usable. */
+export function requireSupportedHost(): void {
+  // Only stable SemVer, with optional build metadata (which has no precedence).
+  const stable =
+    typeof VERSION === "string"
+      ? /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+          VERSION,
+        )
+      : null;
+  if (stable && stable[0] === VERSION) {
+    // BigInt keeps numeric comparison exact without a version-component size limit.
+    const difference = stable
+      .slice(1, 4)
+      .map((part, index) => BigInt(part) - minimum[index]!)
+      .find((part) => part !== 0n);
+    if (difference === undefined || difference > 0n) return;
+  }
+  throw new Error(
+    `Delegated execution requires supported stable Pi >=${MINIMUM_PI_VERSION}; detected ${VERSION || "unknown"}. Install stable Pi ${MINIMUM_PI_VERSION} or newer and restart Pi after draining active tasks.`,
+  );
+}