pi-better-harness 0.29.1 → 0.30.0

package/README.md

@@ -69,8 +69,8 @@ The bundled harness provides **Tool output: Normal / Minimal** in
 `/tool-output` (toggle) remain compatibility shortcuts to the same preference.
 Minimal mode folds each tool call into a single-line header, including running
 calls. The tool-specific icon and tool name share a state color: accent while
-running, muted when completed, and error-colored when failed. In fullscreen Pi, a soft highlight travels through visible running names; inline
-command/path arguments stay dim. Scrollback terminals keep static state colors.
+running, muted when completed, and error-colored when failed. In fullscreen Pi, a soft highlight travels through the entire visible running tool name and its
+inline command/path details; details stay dim between highlight passes. Scrollback terminals keep static state colors.
 Choose **Tool animation: Off** in `/harness-settings` for static running headers.
 Running and failed calls retain text labels so state never depends on color or
 motion alone. Tool rows are indented two columns past

package/extensions/minimal-output/hook.ts

@@ -174,8 +174,10 @@ function compactCall(component: ToolComponent, width: number, theme?: Theme, ind
   const suffix = failed ? " (failed)" : running ? " (running)" : "";
   const icon = TOOL_ICONS[component.toolName] ?? "\u25c7";
   const title = ` ${icon} ${label}`;
+  const visibleDetail = animationTime === undefined ? detail : truncateToWidth(detail,
+    Math.max(0, width - Math.min(indent, Math.max(0, width - 1)) - visibleWidth(title) - 2));
   const styled = theme
-    ? ` ${toolIdentity(icon, label, failed ? "error" : running ? "accent" : "muted", theme, animationTime)}${detail ? `  ${theme.fg("dim", detail)}` : ""}${theme.fg(failed ? "error" : "dim", suffix)}`
+    ? ` ${toolIdentity(icon, label, failed ? "error" : running ? "accent" : "muted", theme, animationTime, visibleDetail)}${theme.fg(failed ? "error" : "dim", suffix)}`
     : `${title}${detail ? `  ${detail}` : ""}${suffix}`;
   return [truncateToWidth(`${" ".repeat(Math.min(indent, Math.max(0, width - 1)))}${styled}`, width)];
 }

package/extensions/minimal-output/tool-identity.ts

@@ -6,7 +6,7 @@ const concreteColors = (theme: Theme) => (theme as Theme & { colors?: Record<str
 const PERIOD = 2400;
 const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 
-function themeRgb(theme: Theme, token: "accent" | "text"): RGB | undefined {
+function themeRgb(theme: Theme, token: "accent" | "text" | "dim"): RGB | undefined {
   const color = concreteColors(theme)?.[token];
   if (color?.kind === "rgb" && color.r !== undefined && color.g !== undefined && color.b !== undefined) {
     return [color.r, color.g, color.b];
@@ -43,23 +43,27 @@ function foreground(color: RGB, mode: "truecolor" | "256color"): string {
   return `\x1b[38;5;${index}m`;
 }
 
-export function toolIdentity(icon: string, label: string, tone: "accent" | "muted" | "error", theme: Theme, time?: number): string {
-  if (tone !== "accent" || time === undefined) return theme.fg(tone, `${icon} ${label}`);
+export function toolIdentity(icon: string, label: string, tone: "accent" | "muted" | "error", theme: Theme, time?: number, detail = ""): string {
+  const staticHeader = () => theme.fg(tone, `${icon} ${label}`) + (detail ? `  ${theme.fg("dim", detail)}` : "");
+  if (tone !== "accent" || time === undefined || !supportsToolShimmer(theme)) return staticHeader();
   const base = themeRgb(theme, "accent");
   const light = themeRgb(theme, "text");
-  if (!supportsToolShimmer(theme)) return theme.fg(tone, `${icon} ${label}`);
-  const letters = Array.from(graphemes.segment(label), part => part.segment);
+  const letters = Array.from(graphemes.segment(label + (detail ? `  ${detail}` : "")), part => part.segment);
+  const nameLength = Array.from(graphemes.segment(label)).length;
   const radius = Math.max(2, Math.min(4, letters.length / 3));
   const position = (time % PERIOD) / PERIOD * (letters.length + radius * 2) - radius;
   const mode = theme.getColorMode();
+  const detailBase = detail ? themeRgb(theme, "dim") : undefined;
   const name = letters.map((letter, index) => {
+    const token = index < nameLength ? "accent" : "dim";
+    const letterBase = token === "accent" ? base : detailBase;
     const distance = Math.abs(index - position) / radius;
     const shine = distance < 1 ? (1 + Math.cos(distance * Math.PI)) * 0.48 : 0;
-    if (!base || !light) {
+    if (!base || !light || !letterBase) {
       const intensity = shine > 0.72 ? "\x1b[1m" : shine > 0.18 ? "" : "\x1b[2m";
-      return `\x1b[22m${intensity}${letter}`;
+      return `${theme.getFgAnsi(token)}\x1b[22m${intensity}${letter}`;
     }
-    const color = base.map((value, channel) => Math.round(value + (light[channel] - value) * shine)) as RGB;
+    const color = letterBase.map((value, channel) => Math.round(value + (light[channel] - value) * shine)) as RGB;
     return `${foreground(color, mode)}${letter}`;
   }).join("");
   return theme.fg(tone, `${icon} \x1b[22m${name}\x1b[22m`);

package/node_modules/pi-better-plan/README.md

@@ -16,7 +16,7 @@ By default, you see up to five steps around the current work. The view starts at
 
 Click the plan to expand or collapse it in Pi's fullscreen mode. In regular terminal mode, use `/plan expand` or `/plan collapse`. For the full plan with details, run `/plan`.
 
-Rows show `✓` for done, `●` for active, `○` for pending, and `!` for blocked. Pi marks steps complete explicitly; the count is not an estimate of effort.
+Rows show `✓` for done, `●` for active, `○` for pending, and `!` for blocked. Pi marks steps complete explicitly; the count is not an estimate of effort. The completion count is completed items / total eligible items: canceled workflow items (`cancelled` or `canceled`) are excluded from the total, while skipped and not-applicable items remain in it. Canceled items remain visible for 30 seconds after the cancellation is first observed, then disappear from the widget and plan lists without deleting their workflow records. This delay survives session reloads; reactivating an item makes it visible again. An all-canceled plan shows `0/0` complete.
 
 Your plan and display settings survive reload and follow the session branch. A completed checklist clears after 30 seconds. A released workflow plan stays visible for reference, but cannot be edited until the workflow resumes.
 

package/node_modules/pi-better-plan/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-plan",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Structured execution plans with persistent progress for Pi.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-plan/src/cancelled-rows.ts

@@ -0,0 +1,36 @@
+import { CANCELLED_ROW_RETENTION_MS, isRecord, type RushPlan, type WorkflowPlanBinding } from "./workflow-plan.js";
+
+export const CANCELLED_ROWS_ENTRY = "pi-better-plan-cancelled-rows";
+
+export function observeCancelledRows(
+  plan: RushPlan,
+  binding: WorkflowPlanBinding,
+  entries: Iterable<{ type: string; customType?: string; data?: unknown }>,
+  append: (type: string, data: unknown) => void,
+  now = Date.now(),
+): void {
+  // Keep display deadlines in branch history, not in the workflow-owned task plan.
+  let previous: Record<string, unknown> = {};
+  for (const entry of entries) {
+    const data = entry.data;
+    if (entry.type === "custom" && entry.customType === CANCELLED_ROWS_ENTRY && isRecord(data) &&
+        data.version === 1 && data.path === binding.path && data.runId === binding.runId &&
+        data.owner === binding.owner && isRecord(data.rows)) previous = data.rows;
+  }
+  const rows: Record<string, number> = Object.create(null);
+  for (const unit of plan.issues) {
+    if (unit.status !== "cancelled" && unit.status !== "canceled") continue;
+    const saved = previous[unit.id];
+    unit.cancelledAt = typeof saved === "number" && Number.isFinite(saved) && saved >= 0 ? saved : now;
+    rows[unit.id] = unit.cancelledAt;
+  }
+  if (JSON.stringify(rows) !== JSON.stringify(previous)) {
+    append(CANCELLED_ROWS_ENTRY, { version: 1, ...binding, rows });
+  }
+}
+
+export function cancelledRowsClearDelay(plan: RushPlan, now = Date.now()): number | null {
+  const deadlines = plan.issues.flatMap(unit => unit.cancelledAt === undefined ? [] : [unit.cancelledAt + CANCELLED_ROW_RETENTION_MS])
+    .filter(deadline => deadline > now);
+  return deadlines.length ? Math.min(...deadlines) - now : null;
+}

package/node_modules/pi-better-plan/src/index.ts

@@ -18,8 +18,9 @@ import { createPlanWidget } from "./plan-widget.js";
 import { COMPACT_PLAN_ROWS } from "./plan-presentation.js";
 import {
   createRushPlanComponent, readRushPlan, renderRushPlan, workflowBinding,
-  WORKFLOW_PLAN_ENTRY, type RushPlan, type WorkflowPlanBinding,
+  WORKFLOW_PLAN_ENTRY, visibleRushUnits, type RushPlan, type WorkflowPlanBinding,
 } from "./workflow-plan.js";
+import { cancelledRowsClearDelay, observeCancelledRows } from "./cancelled-rows.js";
 import { applyRushPlanUpdate, type RushPlanUpdate } from "./workflow-plan-update.js";
 import {
   EXTENSION_NAME,
@@ -131,18 +132,45 @@ export default function planExtension(pi: ExtensionAPI): void {
   let rushError: string | null = null;
   let refreshWidget: ((force?: boolean) => void) | undefined;
   let completedPlanClearTimer: ReturnType<typeof setTimeout> | undefined;
+  let cancelledRowsTimer: ReturnType<typeof setTimeout> | undefined;
+  let refreshFullPlan: (() => void) | undefined;
+  const cancelCancelledRowsTimer = (): void => {
+    if (cancelledRowsTimer !== undefined) clearTimeout(cancelledRowsTimer);
+    cancelledRowsTimer = undefined;
+  };
+  const scheduleCancelledRowsClear = (): void => {
+    cancelCancelledRowsTimer();
+    if (!rushPlan) return;
+    const delay = cancelledRowsClearDelay(rushPlan);
+    if (delay === null) return;
+    const timer = setTimeout(() => {
+      if (cancelledRowsTimer !== timer) return;
+      cancelledRowsTimer = undefined;
+      refresh(true);
+      scheduleCancelledRowsClear();
+    }, delay);
+    cancelledRowsTimer = timer;
+    timer.unref?.();
+  };
+  const observeCancellations = (plan: RushPlan, binding: WorkflowPlanBinding, ctx: ExtensionContext): void => {
+    observeCancelledRows(plan, binding, ctx.sessionManager.getBranch(), (type, data) => pi.appendEntry(type, data));
+  };
   const unsubscribeWorkflow = pi.events.on("pi-better-workflow:changed", (owner) => {
     displayedWorkflowOwner = owner && typeof owner === "object" && "name" in owner && typeof owner.name === "string"
       ? owner.name : null;
     if (displayedWorkflowOwner) {
+      cancelCancelledRowsTimer();
       rushBinding = null;
       rushPlan = null;
       rushError = null;
     }
-    refreshWidget?.(true);
+    refresh(true);
   });
 
-  const refresh = (force = false): void => refreshWidget?.(force);
+  const refresh = (force = false): void => {
+    refreshWidget?.(force);
+    refreshFullPlan?.();
+  };
 
   const loadRushPlan = (ctx: ExtensionContext): RushPlan | null => {
     const owner = workflowPlanOwner(ctx);
@@ -152,33 +180,39 @@ export default function planExtension(pi: ExtensionAPI): void {
     if (!rushBinding) {
       rushPlan = null;
       rushError = null;
+      cancelCancelledRowsTimer();
       return null;
     }
     try {
       const plan = readRushPlan(rushBinding.path, ctx.cwd);
       if (plan.runId !== rushBinding.runId) throw new Error("Rush run identity changed.");
+      observeCancellations(plan, rushBinding, ctx);
       rushPlan = plan;
       rushError = null;
     } catch (error) {
       rushPlan = null;
       rushError = error instanceof Error ? error.message : String(error);
     }
+    scheduleCancelledRowsClear();
     refresh(true);
     return rushPlan;
   };
 
-  const displayWorkflowPlan = (plan: RushPlan, binding: WorkflowPlanBinding, readOnly = false): void => {
+  const displayWorkflowPlan = (plan: RushPlan, binding: WorkflowPlanBinding, ctx: ExtensionContext, readOnly = false): void => {
     if (!rushBinding || rushBinding.owner !== binding.owner || rushBinding.path !== binding.path || rushBinding.runId !== binding.runId) {
       pi.appendEntry(WORKFLOW_PLAN_ENTRY, { version: 1, kind: "set", ...binding });
     }
     displayedWorkflowOwner = readOnly ? null : binding.owner;
     rushBinding = binding;
+    observeCancellations(plan, binding, ctx);
     rushPlan = plan;
     rushError = null;
+    scheduleCancelledRowsClear();
     refresh(true);
   };
 
   const clearWorkflowPlan = (): void => {
+    cancelCancelledRowsTimer();
     if (rushBinding) pi.appendEntry(WORKFLOW_PLAN_ENTRY, { version: 1, kind: "clear" });
     rushBinding = null;
     rushPlan = null;
@@ -215,6 +249,7 @@ export default function planExtension(pi: ExtensionAPI): void {
 
   const restore = (ctx: ExtensionContext): void => {
     cancelCompletedPlanClear();
+    cancelCancelledRowsTimer();
     const state = reconstructPlanState(ctx.sessionManager.getBranch());
     currentPlan = state.plan;
     displayedWorkflowOwner = workflowPlanOwner(ctx);
@@ -271,7 +306,7 @@ export default function planExtension(pi: ExtensionAPI): void {
             if (!currentPlan) return [];
             return renderCompactPlan(currentPlan, width, theme as never, expanded);
           },
-          () => (rushBinding ? rushPlan?.issues.length ?? 0 : currentPlan?.steps.length ?? 0) > COMPACT_PLAN_ROWS,
+          () => (rushBinding && rushPlan ? visibleRushUnits(rushPlan).length : currentPlan?.steps.length ?? 0) > COMPACT_PLAN_ROWS,
           () => expanded,
           () => setExpanded(!expanded),
         );
@@ -300,16 +335,21 @@ export default function planExtension(pi: ExtensionAPI): void {
         ctx.ui.notify(renderRushPlan(plan, 160, true, undefined, planOwner, !owner).join("\n"), "info");
         return;
       }
-      await ctx.ui.custom<void>((tui, theme, _keys, done) => {
-        const fg = typeof theme?.fg === "function"
-          ? (color: string, value: string) => theme.fg(color as never, value)
-          : undefined;
-        const component = createRushPlanComponent(plan, () => done(), fg, planOwner, !owner);
-        return { render: (width) => component.render(width), handleInput(data) {
-          component.handleInput?.(data);
-          tui.requestRender();
-        }, invalidate: () => component.invalidate() };
-      });
+      try {
+        await ctx.ui.custom<void>((tui, theme, _keys, done) => {
+          refreshFullPlan = () => tui.requestRender();
+          const fg = typeof theme?.fg === "function"
+            ? (color: string, value: string) => theme.fg(color as never, value)
+            : undefined;
+          const component = createRushPlanComponent(() => rushPlan ?? { ...plan, issues: [] }, () => done(), fg, planOwner, !owner);
+          return { render: (width) => component.render(width), handleInput(data) {
+            component.handleInput?.(data);
+            tui.requestRender();
+          }, invalidate: () => component.invalidate() };
+        });
+      } finally {
+        refreshFullPlan = undefined;
+      }
       return;
     }
     if (!currentPlan) {
@@ -384,14 +424,14 @@ export default function planExtension(pi: ExtensionAPI): void {
           }
           binding = { owner: owner ?? binding!.owner, path, runId: plan.runId };
           if (transition.event === undefined) {
-            displayWorkflowPlan(plan, binding, !owner);
+            displayWorkflowPlan(plan, binding, ctx, !owner);
             return { content: [{ type: "text", text: `Showing ${binding.owner} rev ${plan.planRevision}: ${plan.issues.length} units.${owner ? "" : " Read-only handoff."}` }], details: { ok: true, runId: plan.runId, revision: plan.planRevision, ...(!owner ? { readOnly: true } : {}) } };
           }
         }
         if (!binding) throw new Error(`No ${owner} plan is bound; send workflow.path and workflow.revision to update_plan first.`);
         if (transition.event === undefined) throw new Error("workflow.path is required to bind or reload a plan; otherwise send workflow.event and changes.");
         const result = applyRushPlanUpdate(binding.path, ctx.cwd, binding.runId, { ...transition, event: transition.event });
-        displayWorkflowPlan(result.plan, binding);
+        displayWorkflowPlan(result.plan, binding, ctx);
         const rows = result.changed.map(({ target, id, added }) =>
           `${added ? "+" : ""}${id === null ? "run" : target === "unit" ? `#${id}` : id}`);
         const logNote = result.logAheadRevision === undefined ? ""
@@ -521,6 +561,8 @@ export default function planExtension(pi: ExtensionAPI): void {
   });
   pi.on("session_shutdown", async (_event, ctx) => {
     cancelCompletedPlanClear();
+    cancelCancelledRowsTimer();
+    refreshFullPlan = undefined;
     if (typeof unsubscribeWorkflow === "function") unsubscribeWorkflow();
     refreshWidget = undefined;
     try {

package/node_modules/pi-better-plan/src/plan-presentation.ts

@@ -12,6 +12,8 @@ export interface PlanRow {
   label: string;
   title: string;
   status: DisplayStatus;
+  // Workflow cancellations keep skipped styling but are excluded from the completion total.
+  cancelled?: boolean;
   statusLabel?: string;
   details?: string[];
 }
@@ -65,7 +67,8 @@ export function renderPlanPresentation(
 ): string[] {
   const size = Math.max(1, Math.floor(width));
   const count = (status: DisplayStatus) => plan.rows.filter((row) => row.status === status).length;
-  const summary = [`${count("completed")}/${plan.rows.length} complete`];
+  const total = plan.rows.filter((row) => !row.cancelled).length;
+  const summary = [`${count("completed")}/${total} complete`];
   for (const [status, label] of [
     ["in_progress", "in progress"], ["implemented", "implemented"], ["reviewed", "review passed"],
     ["blocked", "blocked"], ["failed", "failed"],
@@ -129,16 +132,22 @@ export function renderPlanPresentation(
 }
 
 export function createPlanPresentationComponent(
-  plan: PlanPresentation, theme: PlanRenderTheme, onClose: () => void,
+  source: PlanPresentation | (() => PlanPresentation), theme: PlanRenderTheme, onClose: () => void,
 ): Component {
+  const presentation = () => typeof source === "function" ? source() : source;
+  const plan = presentation();
   let selected = plan.rows.findIndex((row) => row.status === "in_progress");
   if (selected < 0) selected = plan.rows.findIndex((row) => row.status !== "completed");
   if (selected < 0) selected = Math.max(0, plan.rows.length - 1);
   return {
-    render: (width) => renderPlanPresentation(plan, width, theme, true, selected),
+    render: (width) => {
+      const current = presentation();
+      selected = Math.min(selected, Math.max(0, current.rows.length - 1));
+      return renderPlanPresentation(current, width, theme, true, selected);
+    },
     handleInput(data) {
       if (matchesKey(data, "up")) selected = Math.max(0, selected - 1);
-      else if (matchesKey(data, "down")) selected = Math.min(Math.max(0, plan.rows.length - 1), selected + 1);
+      else if (matchesKey(data, "down")) selected = Math.min(Math.max(0, presentation().rows.length - 1), selected + 1);
       else if (matchesKey(data, "escape") || matchesKey(data, "left") || matchesKey(data, "ctrl+c")) onClose();
     },
     invalidate() {},

package/node_modules/pi-better-plan/src/workflow-plan.ts

@@ -7,12 +7,14 @@ import {
 } from "./plan-presentation.js";
 
 export const WORKFLOW_PLAN_ENTRY = "pi-better-workflow-plan";
+export const CANCELLED_ROW_RETENTION_MS = 30_000;
 
 interface RushUnit {
   id: string;
   title: string;
   stage: string;
   status: string;
+  cancelledAt?: number;
   dependsOn: string[];
   worker?: string | number | undefined;
   note?: string | undefined;
@@ -134,7 +136,7 @@ function workflowStatus(status: string): DisplayStatus {
     case "pending": return "pending";
     case "blocked": return "blocked";
     case "failed": return "failed";
-    case "skipped": case "not-applicable": case "cancelled": return "skipped";
+    case "skipped": case "not-applicable": case "cancelled": case "canceled": return "skipped";
     default: return "unknown";
   }
 }
@@ -162,19 +164,25 @@ function presentRushPlan(plan: RushPlan, owner: string, readOnly = false): PlanP
   if (plan.spec?.title) metadata.push([{ color: "dim", text: plan.spec.title }]);
   return {
     metadata,
-    rows: plan.issues.map((unit) => {
+    rows: visibleRushUnits(plan).map((unit) => {
       const status = unitStatus(unit);
+      const cancelled = unit.status === "cancelled" || unit.status === "canceled";
       const details = [`${unit.stage} · ${unit.status}${unit.delivery ? ` · ${unit.delivery}` : ""}${unit.worker !== undefined ? ` · worker ${unit.worker}` : ""}`];
       if (unit.dependsOn.length) details.push(`after: ${unit.dependsOn.map((id) => `#${id}`).join(", ")}`);
       if (unit.note) details.push(unit.note);
       return {
-        label: `#${unit.id}`, title: unit.title, status, details,
-        ...(status === "unknown" || unit.status === "cancelled" ? { statusLabel: unit.status } : {}),
+        label: `#${unit.id}`, title: unit.title, status, cancelled, details,
+        ...(status === "unknown" || cancelled ? { statusLabel: unit.status } : {}),
       };
     }),
   };
 }
 
+export function visibleRushUnits(plan: RushPlan, now = Date.now()): RushPlan["issues"] {
+  return plan.issues.filter(unit => (unit.status !== "cancelled" && unit.status !== "canceled") ||
+    unit.cancelledAt === undefined || now < unit.cancelledAt + CANCELLED_ROW_RETENTION_MS);
+}
+
 export function renderRushPlan(
   plan: RushPlan,
   width: number,
@@ -189,12 +197,12 @@ export function renderRushPlan(
 }
 
 export function createRushPlanComponent(
-  plan: RushPlan,
+  source: RushPlan | (() => RushPlan),
   onClose: () => void,
   fg?: (color: string, value: string) => string,
   owner = "rush-issues",
   readOnly = false,
 ): Component {
   const theme = fg ? { fg } : plainPlanTheme;
-  return createPlanPresentationComponent(presentRushPlan(plan, owner, readOnly), theme, onClose);
+  return createPlanPresentationComponent(() => presentRushPlan(typeof source === "function" ? source() : source, owner, readOnly), theme, onClose);
 }

package/node_modules/pi-better-subagents/README.md

@@ -42,8 +42,21 @@ this session and persist across reloads; Ctrl+S saves both as defaults, and
 Reset to defaults clears
 session overrides. `/subagents mode manual|adaptive|coordinator` and
 `/subagents cap <number>` are command equivalents; `/subagents save` persists
-both. Lowering the cap blocks new single and batch launches without stopping
-running work. The navigator's `main` row retains its mode-only controls:
+both. Lowering the cap blocks new single and batch launches, including launches
+still preparing, without stopping running work. Saved configuration changes are
+picked up on subsequent reads; explicit session overrides still take precedence.
+Before every model request, including continuations after tool calls,
+the foreground receives one temporary settings block with the current mode, cap,
+setting sources, revision, and running/reserved/available slots. The latest block
+replaces older snapshots and delegation guidance; it is not saved as conversation
+history. Changes reach the model at its next request, not during an in-flight
+response, and are not broadcast to running children. The cap is a ceiling, not a
+target number of agents. `subagent_settings` inspects the same effective state
+without changing it. Its revision is a stable fingerprint of mode, cap, and
+sources; occupancy changes do not change the revision. Admission rechecks capacity
+when spawning because the snapshot can become stale.
+
+The navigator's `main` row retains its mode-only controls:
 `m` cycles the session mode, `ctrl+s` saves that default, and `x`
 does not stop it. Manual delegates only on explicit user or workflow request, even with a
 plan. Adaptive delegates substantial independent work when useful. Coordinator

package/node_modules/pi-better-subagents/config.ts

@@ -8,7 +8,7 @@
  * `defaultTools` absent → the built-in SAFE_DEFAULT_TOOLS.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
@@ -89,19 +89,23 @@ export const SAFE_DEFAULT_TOOLS = "read, bash, edit, write, web_search, web_fetc
 export const SAFE_CLEAN_TOOLS = "read, bash";
 
 let cached: SubagentConfig | undefined;
+let cachedIdentity: string | undefined;
+let configOverrideForTests = false;
 let configPathForTests: string | undefined;
 let bundledConfigPathForTests: string | undefined;
 
 /** Test seam. Pass undefined to reload config.json on the next loadConfig call. */
 export function setConfigForTests(next: SubagentConfig | undefined): void {
     cached = next;
+    cachedIdentity = undefined;
+    configOverrideForTests = next !== undefined;
 }
 
 /** Test seam. Isolate user config, optionally supplying a package fallback. */
 export function setConfigPathForTests(path: string | undefined, bundledPath?: string): void {
     configPathForTests = path;
     bundledConfigPathForTests = bundledPath;
-    cached = undefined;
+    setConfigForTests(undefined);
 }
 
 export function configPath(): string {
@@ -128,8 +132,12 @@ function savedConfig(): SubagentConfig {
     return user === undefined ? {} : parseConfig(user);
 }
 
+function bundledConfigPath(): string | undefined {
+    return bundledConfigPathForTests ?? (configPathForTests ? undefined : join(selfDir(), "config.json"));
+}
+
 function bundledConfig(): SubagentConfig {
-    const path = bundledConfigPathForTests ?? (configPathForTests ? undefined : join(selfDir(), "config.json"));
+    const path = bundledConfigPath();
     if (!path) return {};
     try {
         return readConfig(path);
@@ -138,12 +146,31 @@ function bundledConfig(): SubagentConfig {
     }
 }
 
+function configIdentity(): string {
+    const paths = [configPath(), bundledConfigPath(),
+        configPathForTests ? undefined : join(piAgentDir(), "extensions", "pi-better-subagents-config.json")];
+    return JSON.stringify(paths.map(path => {
+        if (!path) return null;
+        try {
+            const stat = statSync(path, { bigint: true });
+            return [path, stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].map(String);
+        } catch (error) {
+            return [path, (error as NodeJS.ErrnoException).code];
+        }
+    }));
+}
+
 /** Saved user choices take precedence; missing/invalid files contribute no keys. */
 export function loadConfig(): SubagentConfig {
-    if (cached) return cached;
+    if (configOverrideForTests) return cached!;
+    const identity = configIdentity();
+    if (cached && cachedIdentity === identity) return cached;
     let user: SubagentConfig = {};
     try { user = savedConfig(); } catch { /* retain package fallback */ }
     cached = { ...bundledConfig(), ...user };
+    // Keep the pre-read identity: migration or a concurrent replacement must
+    // trigger another read rather than label an older value with a newer stat.
+    cachedIdentity = identity;
     return cached;
 }
 
@@ -162,10 +189,10 @@ export function writeSubagentSettings(settings: { delegationMode: DelegationMode
 
 function writeConfigSettings(settings: Partial<SubagentConfig>, path: string): void {
     if (path === configPath()) savedConfig();
-    const current = updateHarnessSetting("subagents", previous => ({
+    updateHarnessSetting("subagents", previous => ({
         ...(previous === undefined ? {} : parseConfig(previous)), ...settings,
     }), { agentDir: () => dirname(path) });
-    if (path === configPath()) cached = { ...bundledConfig(), ...current };
+    if (path === configPath()) setConfigForTests(undefined);
 }
 
 /** Normalize a comma/space tool list to pi's bare comma form: "a, b" → "a,b". */

package/node_modules/pi-better-subagents/docs/usage.md

@@ -97,6 +97,7 @@ thresholds continue to take precedence for subagent health.
 |------|---------|--------------|
 | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
 | `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; same optional params as `subagent_spawn`), `onCapacity` (`reject` or `launch-available`). |
+| `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, per-setting `sources` (`session` or `config`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
 | `subagent_list` | never | Compact current-session list (default 10 rows / 1 KiB page). Params: `all` (machine-global / foreign session), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. |
 | `subagent_output` | never | Bounded current-session excerpt (default 1 KiB / 10 lines). Params: `id`, `lines` (`tail_lines` is a deprecated alias), `cursor` (a returned `nextCursor`, `statusCursor`, or `incidentCursor`), `max_bytes` (max 4 KiB; raw 16 KiB default, 64 KiB max), `mode` (`raw` pages retained log bytes), `include` (`["cost"]`, `["tools"]`, or both: opt-in spend and tool-count lines), `all` (foreign-session id). Missing/unreadable logs are gaps, not empty healthy output. |
 | `subagent_result` | never | Finished-run answer for the current session (2048-byte page). Params: `id`, `cursor` (a returned `nextCursor` continues the answer; `statusCursor` / `incidentCursor` also accepted), `max_bytes` (maximum 8192 bytes), `lines` (optional line cap per answer page), `mode` (`raw`), `include` (`["cost"]`, `["tools"]`, or both), `all` (foreign-session id). Failures and exceptional lifecycle facts come before progress; no tool-name histories. TUI folding is display-only. |

package/node_modules/pi-better-subagents/effective-settings.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { delegationPrompt, type DelegationMode } from "./delegation.ts";
+
+export const SUBAGENT_SETTINGS_CONTEXT = "pi-better-subagents-settings";
+
+export interface EffectiveSubagentSettings {
+    revision: string;
+    delegationMode: DelegationMode;
+    maxConcurrent: number;
+    sources: { delegationMode: "session" | "config"; maxConcurrent: "session" | "config" };
+    runningCount: number;
+    pendingCount: number;
+    occupiedSlots: number;
+    availableSlots: number;
+}
+
+export function effectiveSubagentSettings(
+    settings: Pick<EffectiveSubagentSettings, "delegationMode" | "maxConcurrent" | "sources">,
+    runningCount: number,
+    pendingCount: number,
+): EffectiveSubagentSettings {
+    const revision = createHash("sha256").update(JSON.stringify([
+        settings.delegationMode, settings.maxConcurrent, settings.sources.delegationMode, settings.sources.maxConcurrent,
+    ])).digest("hex").slice(0, 12);
+    const occupiedSlots = runningCount + pendingCount;
+    return { ...settings, revision, runningCount, pendingCount, occupiedSlots,
+        availableSlots: Math.max(0, settings.maxConcurrent - occupiedSlots) };
+}
+
+export function formatSubagentSettings(settings: EffectiveSubagentSettings): string {
+    return [
+        `Subagent settings: revision ${settings.revision}`,
+        `Delegation: ${settings.delegationMode} (${settings.sources.delegationMode})`,
+        `Concurrency limit: ${settings.maxConcurrent} (${settings.sources.maxConcurrent})`,
+        `Running: ${settings.runningCount}; reserved: ${settings.pendingCount}`,
+        `Occupied slots: ${settings.occupiedSlots}`,
+        `Available slots: ${settings.availableSlots}`,
+        "The limit is a ceiling, not a target. Launch ready, independent, useful work within available capacity. " +
+            "This is a point-in-time snapshot; spawn admission rechecks capacity. Lowering the limit does not stop existing runs.",
+        delegationPrompt(settings.delegationMode),
+    ].join("\n");
+}
+
+export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSettings) {
+    return {
+        name: "subagent_settings",
+        label: "Subagent Settings",
+        description: "Inspect effective subagent delegation mode, concurrency limit, setting sources, revision, and running/reserved/available slots. Read-only; does not change settings or launch work. The limit is a ceiling, not a target.",
+        parameters: Type.Object({}),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        outputSchema: Type.Object({
+            revision: Type.String(), delegationMode: Type.String(), maxConcurrent: Type.Number({ minimum: 1, multipleOf: 1 }),
+            sources: Type.Object({ delegationMode: Type.String(), maxConcurrent: Type.String() }),
+            runningCount: Type.Number({ minimum: 0, multipleOf: 1 }), pendingCount: Type.Number({ minimum: 0, multipleOf: 1 }),
+            occupiedSlots: Type.Number({ minimum: 0, multipleOf: 1 }), availableSlots: Type.Number({ minimum: 0, multipleOf: 1 }),
+        }),
+        async execute() {
+            const settings = read();
+            return { content: [{ type: "text" as const, text: formatSubagentSettings(settings) }],
+                details: settings, structuredContent: settings };
+        },
+    };
+}

package/node_modules/pi-better-subagents/index.ts

@@ -37,6 +37,7 @@ import { parseRun, readRunTranscript, resetParseRunCursor, type Usage } from "./
 import { finalizeRun as finalizeRunCore } from "./finalization.ts";
 import { loadConfig, writeDelegationMode, writeSubagentSettings, isConcurrencyCap, normalizeConcurrencyCap, normalizeTools, resolveExtensionPath, selfDir, SAFE_DEFAULT_TOOLS, SAFE_CLEAN_TOOLS } from "./config.ts";
 import { createSubagentSettingsPage } from "./settings-page.ts";
+import { effectiveSubagentSettings, formatSubagentSettings, subagentSettingsTool, SUBAGENT_SETTINGS_CONTEXT } from "./effective-settings.ts";
 import { STEER_FILE_ENV, readSteerReceipt } from "./child-steer.ts";
 import {
     decideTiming,
@@ -53,7 +54,7 @@ import {
     type TimingStopReason,
 } from "./timing.ts";
 import { readAppendedLines, type LogCursor } from "./log-cursor.ts";
-import { DELEGATION_MODES, DELEGATION_MODE_REQUEST, delegationPrompt, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
+import { DELEGATION_MODES, DELEGATION_MODE_REQUEST, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
 import { appendExecutionPolicy } from "./shared-execution-policy.ts";
 import { resolveExtensions, extensionArgs } from "./extensions.ts";
 import { prepareTaskRuntime } from "./task-policy.ts";
@@ -186,6 +187,7 @@ const SUBAGENT_TOOLS = [
     "subagent_spawn",
     "subagent_spawn_batch",
     "subagent_list",
+    "subagent_settings",
     "subagent_output",
     "subagent_stop",
     "subagent_result",
@@ -1522,6 +1524,13 @@ export default function (pi: ExtensionAPI) {
         pi.appendEntry("pi-better-subagents-delegation", { version: 1, mode: null });
     };
     const activeDelegationMode = (): DelegationMode => delegationOverride ?? normalizeDelegationMode(loadConfig().delegationMode);
+    const countRunning = () =>
+        listActiveMetasForParent(process.pid).filter((meta) => effectiveStatus(meta) === "running").length;
+    const effectiveSettings = () => effectiveSubagentSettings({
+        delegationMode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap(),
+        sources: { delegationMode: delegationOverride ? "session" : "config",
+            maxConcurrent: capOverride !== undefined ? "session" : "config" },
+    }, countRunning(), getSharedCapacityGate(countRunning).pending);
     const saveSettings = (): { ok: boolean; message: string } => {
         try {
             writeSubagentSettings({ delegationMode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap() });
@@ -1846,6 +1855,13 @@ export default function (pi: ExtensionAPI) {
 
         let spawned: ReturnType<typeof spawnDetached>;
         try {
+            // Reservations prevent competing admissions, but do not grandfather
+            // unstarted work after a cap reduction. No await separates this live
+            // occupancy check, child creation, and the running metadata below.
+            const maxConcurrent = activeConcurrencyCap();
+            if (countRunning() >= maxConcurrent) {
+                throw new Error(`Max concurrent subagents (${maxConcurrent}) reached. Stop or let some finish first.`);
+            }
             spawned = spawnDetached({ file: cmd.file, fileArgs: cmd.fileArgs, cwd, logPath: logPathFor(id),
                 env: { [STEER_FILE_ENV]: steerPathFor(id) } });
         } catch (error) {
@@ -1956,8 +1972,6 @@ export default function (pi: ExtensionAPI) {
             if (blankSelector) throw new Error(blankSelector);
 
             const maxConcurrent = activeConcurrencyCap();
-            const countRunning = () =>
-                listActiveMetasForParent(process.pid).filter((m) => effectiveStatus(m) === "running").length;
             // Shared with batch-spawn: reserve before any async work so an interleaved
             // batch cannot oversubscribe after this check and before writeMeta.
             const gate = getSharedCapacityGate(countRunning);
@@ -2093,8 +2107,6 @@ export default function (pi: ExtensionAPI) {
             };
 
             const cfg = loadConfig();
-            const countRunning = () =>
-                listActiveMetasForParent(process.pid).filter((m) => effectiveStatus(m) === "running").length;
             const launchAvailable = p.onCapacity === "launch-available";
             // Shared with single-spawn. Reservations count against maxConcurrent so a
             // concurrent single spawn cannot take a slot the batch already admitted.
@@ -2248,6 +2260,7 @@ export default function (pi: ExtensionAPI) {
         getActiveOrigin: (ctx?: unknown) => activeCallbackOrigin ?? verifiedOriginFromContext(ctx as ExtensionContext | undefined),
     };
     pi.registerTool(subagentListTool(Type, toolSession));
+    pi.registerTool(subagentSettingsTool(Type, effectiveSettings));
     pi.registerTool(subagentOutputTool(Type, toolSession));
     const acceptanceResultTool = subagentResultTool(Type, toolSession);
     pi.registerTool(acceptanceResultTool);
@@ -2288,13 +2301,16 @@ export default function (pi: ExtensionAPI) {
     const openSettings = async (ctx: ExtensionCommandContext): Promise<void> => {
         if (ctx.mode === "tui" && ctx.hasUI && typeof ctx.ui.custom === "function") {
             await ctx.ui.custom<void>((tui, theme, _kb, done) => createSubagentSettingsPage(theme, {
-                get: () => ({
-                    mode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap(),
-                    modeSource: delegationOverride ? "session" : "config",
-                    capSource: capOverride !== undefined ? "session" : "config",
-                    defaultMode: normalizeDelegationMode(loadConfig().delegationMode),
-                    defaultCap: normalizeConcurrencyCap(loadConfig().maxConcurrent),
-                }),
+                get: () => {
+                    const settings = effectiveSettings();
+                    return {
+                        mode: settings.delegationMode, maxConcurrent: settings.maxConcurrent,
+                        modeSource: settings.sources.delegationMode,
+                        capSource: settings.sources.maxConcurrent,
+                        defaultMode: normalizeDelegationMode(loadConfig().delegationMode),
+                        defaultCap: normalizeConcurrencyCap(loadConfig().maxConcurrent),
+                    };
+                },
                 changeMode, changeCap, save: saveSettings, reset: resetSettings,
             }, () => { refreshBackgroundWorkNavigator(ctx); tui.requestRender(); }, () => done()));
         } else {
@@ -2354,9 +2370,18 @@ export default function (pi: ExtensionAPI) {
     pi.registerTool(discoveryTool as Parameters<ExtensionAPI["registerTool"]>[0]);
 
     pi.on("before_agent_start", (event) => ({
-        systemPrompt: `${appendExecutionPolicy(event.systemPrompt)}\n\n${delegationPrompt(activeDelegationMode())}`,
+        systemPrompt: `${appendExecutionPolicy(event.systemPrompt)}\n\nUse the latest Subagent settings context block as the authoritative delegation mode and capacity snapshot. Its delegation guidance replaces earlier mode-specific guidance, including guidance in a plan. Inspect subagent_settings when needed; never treat the concurrency limit as a target number of agents.`,
     }));
 
+    pi.on("context", (event) => {
+        const settings = effectiveSettings();
+        return { messages: [
+            ...event.messages.filter(message => message.role !== "custom" || message.customType !== SUBAGENT_SETTINGS_CONTEXT),
+            { role: "custom" as const, customType: SUBAGENT_SETTINGS_CONTEXT,
+                content: formatSubagentSettings(settings), display: false, details: settings, timestamp: Date.now() },
+        ] };
+    });
+
     // ---- live-status lifecycle -----------------------------------------
     pi.on("agent_start", async (_event, ctx) => {
         setCallbackBatchContext(pi, ctx);

package/node_modules/pi-better-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -55,10 +55,10 @@
   "dependencies": {
     "pi-better-background-tasks": "0.9.0",
     "pi-better-goal": "0.9.0",
-    "pi-better-plan": "0.9.0",
+    "pi-better-plan": "0.9.1",
     "pi-better-sandbox": "0.12.0",
     "pi-better-ssh": "0.1.2",
-    "pi-better-subagents": "0.18.0",
+    "pi-better-subagents": "0.19.0",
     "proper-lockfile": "^4.1.2",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"