pi-better-harness 0.15.2 → 0.16.0

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

@@ -17,7 +17,7 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 - Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.
-- A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (30s through 300s by default), followed by a hold recoverable with `/goal resume`. Delays saturate at Node's timer limit, and observed background drains reset progress before callback turns can cancel the wake. Pi's network retry policy remains independent.
+- A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (60s through 600s by default), followed by a hold recoverable with `/goal resume`. Delays saturate at Node's timer limit, and observed background drains reset progress before callback turns can cancel the wake. Pi's network retry policy remains independent.
 - An observable-progress stall state for active goals.
 
 ## Skill-Owned Workflows

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

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

@@ -50,7 +50,7 @@ import {
 } from "./types.js";
 
 const POLL_INTERVAL_MS = 2_000;
-const DEFAULT_IDLE_CONTINUATION_DELAY_MS = 30_000;
+const DEFAULT_IDLE_CONTINUATION_DELAY_MS = 60_000;
 const DEFAULT_MAX_NO_PROGRESS_RETRIES = 10;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const WAKE_DISABLED =
@@ -124,7 +124,7 @@ function parseDurationEnv(raw: string | undefined, fallback: number): number {
 
 /**
  * Linear backoff for no-progress retries: each identical outcome waits one more
- * grace period than the last (30s, 60s, 90s, ... by default).
+ * grace period than the last (60s, 120s, 180s, ... by default).
  */
 export function idleContinuationDelay(noProgressRetries: number, baseMs = IDLE_CONTINUATION_DELAY_MS): number {
   return Math.min(MAX_TIMER_DELAY_MS, baseMs * (1 + Math.max(0, noProgressRetries)));

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

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

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

@@ -40,7 +40,7 @@ const PlanStepSchema = Type.Object({
 });
 
 const WorkflowRowChangeSchema = Type.Object({
-  id: Type.Optional(Type.String({ description: "Unit id, component id (e.g. C1), or fleet stage (explore, combine, canary, review, cicd). Omit for run-level fields." })),
+  id: Type.Optional(Type.String({ description: "Unit id, component id (e.g. C1), or fleet stage (explore, implement, review, ci, canary). Omit for run-level fields." })),
   target: Type.Optional(StringEnum(["unit", "component", "fleet", "run"] as const, { description: "Required with add. Otherwise only needed when the same id names two kinds of row." })),
   set: Type.Optional(Type.Object({}, {
     additionalProperties: true,

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

@@ -43,7 +43,7 @@ export interface RushPlanUpdateResult {
 /** Contract values from rush-issues references/task-plan.md. */
 export const RUSH_UNIT_STATUSES = ["pending", "in-flight", "diagnosing", "succeeded", "blocked", "cancelled"] as const;
 export const RUSH_UNIT_STAGES = ["pending", "implement", "validate", "self-review", "diagnose", "done"] as const;
-export const RUSH_COMPONENT_STATUSES = ["building", "combining", "review", "cicd", "merged", "blocked"] as const;
+export const RUSH_COMPONENT_STATUSES = ["building", "combining", "review", "ci", "cicd", "merged", "blocked"] as const;
 export const RUSH_FLEET_STATUSES = [
   "pending", "in-flight", "diagnosing", "succeeded", "failed", "blocked", "cancelled", "not-applicable", "merged",
 ] as const;

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

@@ -91,7 +91,9 @@ export function projectRushPlan(data: unknown, runId: string): RushPlan {
     planRevision: data.planRevision as number,
     issues,
     fleet,
-    warehouseCanaryRequired: data.warehouseCanaryRequired === true,
+    // The skill marks canary work per unit (`warehouseCanary`); older plans set a run-level flag.
+    warehouseCanaryRequired: data.warehouseCanaryRequired === true ||
+      persistedUnits.some((unit: unknown) => isRecord(unit) && unit.warehouseCanary != null && unit.warehouseCanary !== false),
     spec: isRecord(data.spec) && typeof data.spec.title === "string" ? { title: data.spec.title } : undefined,
   };
 }
@@ -132,9 +134,10 @@ function workflowStatus(status: string): DisplayStatus {
 }
 
 function presentRushPlan(plan: RushPlan): PlanPresentation {
-  const fleet = ["explore", "combine", "canary", "review", "cicd"].map((stage) => {
-    const status = stage === "canary" && !plan.warehouseCanaryRequired
-      ? "not-applicable" : plan.fleet[stage]?.status ?? "pending";
+  // The warehouse canary only applies to data work; hide it otherwise.
+  const stages = ["explore", "implement", "review", "ci", ...(plan.warehouseCanaryRequired ? ["canary"] : [])];
+  const fleet = stages.map((stage) => {
+    const status = plan.fleet[stage]?.status ?? "pending";
     const display = workflowStatus(status);
     const style = statusStyle(display);
     return { color: style.color, text: `  ${stage} ${style.glyph}${display === "unknown" ? ` ${planText(status)}` : ""}` };

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-sandbox",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Pi extension with independent Main and Subagents permission profiles, file guards, and OS sandbox enforcement.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-sandbox/shared-task-sandbox.ts

@@ -6,6 +6,8 @@ const { createBashToolDefinition, createReadToolDefinition, createWriteToolDefin
     createEditToolDefinition, createLocalBashOperations, getShellConfig } = PiCodingAgent;
 import { pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { unlink } from "node:fs/promises";
 import { accessSync, constants, lstatSync, mkdirSync, mkdtempSync, readlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
@@ -117,42 +119,51 @@ export function createTaskBashOperations(
             const scratch = plan.policy.runtimeWrite?.[0];
             const taskEnv = { ...process.env, ...options.env,
                 ...(scratch ? { TMPDIR: scratch, TMP: scratch, TEMP: scratch } : {}) };
-            const wrapped = maybeBuildSandboxCommand({
-                policy: plan.policy, profilePath: plan.profilePath,
-                execPath: "/usr/bin/env", execArgs: ["-i", "--", ...Object.entries(taskEnv)
-                    .filter((entry): entry is [string, string] => entry[1] !== undefined)
-                    .map(([key, value]) => `${key}=${value}`), shell.shell, ...shell.args, command],
-            }, { sandboxEnabled: true, explicitSandbox: true });
-            if (!wrapped) throw new Error("Sandbox: no task execution backend is available.");
-            for (const line of wrapped.notices ?? []) options.onData(Buffer.from(`${line}\n`));
             if (options.signal?.aborted) throw new Error("aborted");
             if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout <= 0 || options.timeout * 1000 > 2147483647)) {
                 throw new Error("Invalid timeout: must be a positive, supported number of seconds");
             }
-            // No shell or caller-controlled loader environment runs before the boundary.
-            return new Promise((resolve, reject) => {
-                const child = spawn(wrapped.file, wrapped.fileArgs, { cwd, detached: true,
-                    env: { PATH: "/usr/bin:/bin", HOME: plan.policy.home }, stdio: ["ignore", "pipe", "pipe"] });
-                let timedOut = false;
-                const kill = () => { if (child.pid) { try { process.kill(-child.pid, "SIGKILL"); } catch { child.kill("SIGKILL"); } } };
-                const timer = options.timeout === undefined ? undefined : setTimeout(() => { timedOut = true; kill(); }, options.timeout * 1000);
-                if (child.pid) trackDetachedChildPid(child.pid);
-                const cleanup = () => {
-                    if (child.pid) untrackDetachedChildPid(child.pid);
-                    if (timer) clearTimeout(timer);
-                    options.signal?.removeEventListener("abort", kill);
-                };
-                child.stdout.on("data", options.onData);
-                child.stderr.on("data", options.onData);
-                options.signal?.addEventListener("abort", kill, { once: true });
-                if (options.signal?.aborted) kill();
-                void waitForChildProcess(child).then((exitCode: number | null) => {
-                    cleanup();
-                    if (options.signal?.aborted) reject(new Error("aborted"));
-                    else if (timedOut) reject(new Error(`timeout:${options.timeout}`));
-                    else resolve({ exitCode });
-                }, (error: unknown) => { cleanup(); reject(error); });
-            });
+            // A sibling launch must never rewrite a profile another process is reading.
+            const profilePath = `${plan.profilePath}.${randomUUID()}.bash.sb`;
+            try {
+                const wrapped = maybeBuildSandboxCommand({
+                    policy: plan.policy, profilePath,
+                    execPath: "/usr/bin/env", execArgs: ["-i", "--", ...Object.entries(taskEnv)
+                        .filter((entry): entry is [string, string] => entry[1] !== undefined)
+                        .map(([key, value]) => `${key}=${value}`), shell.shell, ...shell.args, command],
+                }, { sandboxEnabled: true, explicitSandbox: true });
+                if (!wrapped) throw new Error("Sandbox: no task execution backend is available.");
+                for (const line of wrapped.notices ?? []) options.onData(Buffer.from(`${line}\n`));
+                if (options.signal?.aborted) throw new Error("aborted");
+                // No shell or caller-controlled loader environment runs before the boundary.
+                return await new Promise<{ exitCode: number | null }>((resolve, reject) => {
+                    const child = spawn(wrapped.file, wrapped.fileArgs, { cwd, detached: true,
+                        env: { PATH: "/usr/bin:/bin", HOME: plan.policy.home }, stdio: ["ignore", "pipe", "pipe"] });
+                    let timedOut = false;
+                    const kill = () => { if (child.pid) { try { process.kill(-child.pid, "SIGKILL"); } catch { child.kill("SIGKILL"); } } };
+                    const timer = options.timeout === undefined ? undefined : setTimeout(() => { timedOut = true; kill(); }, options.timeout * 1000);
+                    if (child.pid) trackDetachedChildPid(child.pid);
+                    const cleanup = () => {
+                        if (child.pid) untrackDetachedChildPid(child.pid);
+                        if (timer) clearTimeout(timer);
+                        options.signal?.removeEventListener("abort", kill);
+                    };
+                    child.stdout.on("data", options.onData);
+                    child.stderr.on("data", options.onData);
+                    options.signal?.addEventListener("abort", kill, { once: true });
+                    if (options.signal?.aborted) kill();
+                    void waitForChildProcess(child).then((exitCode: number | null) => {
+                        cleanup();
+                        if (options.signal?.aborted) reject(new Error("aborted"));
+                        else if (timedOut) reject(new Error(`timeout:${options.timeout}`));
+                        else resolve({ exitCode });
+                    }, (error: unknown) => { cleanup(); reject(error); });
+                });
+            } finally {
+                await unlink(profilePath).catch((error: NodeJS.ErrnoException) => {
+                    if (error.code !== "ENOENT") throw error;
+                });
+            }
         },
     };
 }

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

@@ -36,10 +36,13 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
 ## Delegation Modes
 
 `config.json` sets `delegationMode` to `manual`, `adaptive` (default), or
-`coordinator`. `/subagents` displays the active mode, and
-`/subagents mode manual|adaptive|coordinator` changes it for the current
-session without changing config. `/subagents save` writes the current mode as
-the next session's default. The navigator's `main` row opens the same control:
+`coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
+for delegation mode and the concurrent-subagent cap (default 4). Edits apply to
+this session; Save as defaults persists both, 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:
 `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

@@ -21,7 +21,7 @@ export interface SubagentConfig extends TimingSettings {
     delegationMode?: DelegationMode | null;
     defaultModel?: string | null;
     defaultTools?: string | null;
-    /** Max subagents allowed to run at once. */
+    /** Default concurrency cap; /subagents cap overrides it for the current session. */
     maxConcurrent?: number | null;
     /**
      * Tool name → extension package(s) that provide it. Drives which extension
@@ -74,6 +74,14 @@ export interface SubagentConfig extends TimingSettings {
 /** Concurrency cap when config.json sets none. */
 export const DEFAULT_MAX_CONCURRENT = 4;
 
+export function isConcurrencyCap(value: unknown): value is number {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+export function normalizeConcurrencyCap(value: unknown): number {
+    return isConcurrencyCap(value) ? value : DEFAULT_MAX_CONCURRENT;
+}
+
 /** Built-in default tool set when config.json sets nothing. */
 export const SAFE_DEFAULT_TOOLS = "read, bash, edit, write, web_search, web_fetch";
 /** Safe default for a hermetic (clean) child where extension tools don't exist. */
@@ -123,6 +131,25 @@ export function writeDelegationMode(mode: DelegationMode, path = configPath()):
     if (path === configPath()) cached = current;
 }
 
+/** Save human-facing defaults together, preserving unrelated configuration. */
+export function writeSubagentSettings(settings: { delegationMode: DelegationMode; maxConcurrent: number }, path = configPath()): void {
+    if (!isDelegationMode(settings.delegationMode)) throw new Error("Invalid delegation mode.");
+    if (!isConcurrencyCap(settings.maxConcurrent)) throw new Error("Concurrent subagents must be a positive whole number.");
+    let current: Record<string, unknown> = {};
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Config must be a JSON object.");
+        current = parsed as Record<string, unknown>;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    Object.assign(current, settings);
+    const pending = `${path}.${process.pid}.tmp`;
+    writeFileSync(pending, `${JSON.stringify(current, null, 2)}\n`);
+    renameSync(pending, path);
+    if (path === configPath()) cached = current as SubagentConfig;
+}
+
 /** Normalize a comma/space tool list to pi's bare comma form: "a, b" → "a,b". */
 export function normalizeTools(list: string): string {
     return list.split(",").map((t) => t.trim()).filter(Boolean).join(",");

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

@@ -1,5 +1,7 @@
 export type DelegationMode = "manual" | "adaptive" | "coordinator";
 
+export const DELEGATION_MODES = ["manual", "adaptive", "coordinator"] as const;
+
 export const DELEGATION_MODE_REQUEST = "pi-better-subagents:delegation-mode-request";
 
 export function isDelegationMode(value: unknown): value is DelegationMode {

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

@@ -16,14 +16,33 @@ launch is the result · completion triggers fetch · the foreground never blocks
 
 Set `delegationMode` in this package's `config.json` to `manual`, `adaptive`, or
 `coordinator` (default `adaptive`). This controls foreground delegation guidance,
-not child permissions or catalog definitions. `/subagents` reports the active
-mode; `/subagents mode manual|adaptive|coordinator` overrides it for the current
-session without editing config. `/subagents save` writes the current mode into
-`config.json` after confirmation when a UI is available, and clears the session
-override so the next session starts there. On the navigator `main` sheet, `m`
-cycles the session mode and `ctrl+s` saves that default.
-Other arguments show usage. `/reload` retains a session override; new sessions
-use config, while resuming a session restores that session's override.
+not child permissions or catalog definitions. `/subagents settings` (or simply
+`/subagents`) opens the terminal settings page with mode and concurrent-subagent
+cap controls, saved defaults, Save as defaults, and Reset to defaults. Changes
+apply immediately to this session; Escape closes the page without undoing them.
+Enter edits the cap as a positive whole number; Escape cancels an unfinished edit.
+Ctrl+S saves both settings as defaults. Sandbox permissions remain in `/sandbox`.
+
+Command equivalents also work outside the terminal UI:
+
+```text
+/subagents mode manual|adaptive|coordinator
+/subagents cap 6
+/subagents save
+/subagents reset
+```
+
+The cap defaults to 4 and applies to both single and batch launches. Lowering it
+below the running count leaves existing work untouched and blocks new admissions
+until capacity becomes available. Slots already reserved by an in-flight launch
+remain admitted. Settings apply to this parent Pi process, not
+all Pi sessions on the machine. Saving preserves unrelated config keys and
+clears both session overrides. The command form asks for confirmation when a UI
+is available. Reset restores saved defaults without changing config.
+
+`/reload` retains session overrides; new sessions use config, while resuming or
+navigating a branch restores its settings. On the navigator `main` sheet, `m`
+cycles the session mode and `ctrl+s` saves only that mode default.
 
 - **Manual:** no proactive delegation, including in plan mode. A user request or
   explicit workflow requirement may still delegate.
@@ -383,9 +402,12 @@ top.
   foreground model).
 - `delegationMode` — foreground policy (`manual`, `adaptive`, or `coordinator`;
   default `adaptive`). `/subagents mode ...` changes only the current session.
-  `/subagents save` writes that mode as the config default.
-- `maxConcurrent` — how many subagents may run at once (**default 4**). A spawn
-  past the cap is rejected until a running one finishes.
+  `/subagents save` saves mode and cap together as config defaults.
+- `maxConcurrent` — positive whole-number concurrency cap (**default 4**).
+  `/subagents cap <number>` overrides it for this session. Both single and batch
+  admissions respect the cap; existing runs are never stopped by a cap change.
+  Use `/subagents settings` to edit both controls or `/subagents reset` to return
+  to saved defaults.
 
 ## The allowlist also decides what LOADS
 

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

@@ -35,7 +35,8 @@ import {
 import { spawnDetached, type SpawnResult } from "./spawn.ts";
 import { parseRun, readRunTranscript, resetParseRunCursor, type Usage } from "./parse.ts";
 import { finalizeRun as finalizeRunCore } from "./finalization.ts";
-import { loadConfig, writeDelegationMode, normalizeTools, resolveExtensionPath, selfDir, SAFE_DEFAULT_TOOLS, SAFE_CLEAN_TOOLS, DEFAULT_MAX_CONCURRENT } from "./config.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 { STEER_FILE_ENV, readSteerReceipt } from "./child-steer.ts";
 import {
     decideTiming,
@@ -52,7 +53,7 @@ import {
     type TimingStopReason,
 } from "./timing.ts";
 import { readAppendedLines, type LogCursor } from "./log-cursor.ts";
-import { DELEGATION_MODE_REQUEST, delegationPrompt, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
+import { DELEGATION_MODES, DELEGATION_MODE_REQUEST, delegationPrompt, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
 import { resolveExtensions, extensionArgs } from "./extensions.ts";
 import { prepareTaskRuntime } from "./task-policy.ts";
 import { canonicalizePath, takeRecoverySnapshot } from "./shared-sandbox-core.ts";
@@ -162,10 +163,13 @@ import {
 import { defaultUserRoot, type CatalogSnapshot } from "./catalog-store.ts";
 
 const SUBAGENT_MODE_ACTIONS: readonly AutocompleteItem[] = [
+    { value: "settings", label: "settings", description: "Open delegation mode and concurrency settings" },
+    { value: "cap", label: "cap <number>", description: "Set a positive concurrent subagent limit for this session" },
+    { value: "reset", label: "reset", description: "Reset session mode and cap to saved defaults" },
     { value: "mode manual", label: "mode manual", description: "Delegate only when explicitly requested" },
     { value: "mode adaptive", label: "mode adaptive", description: "Delegate substantial independent work" },
     { value: "mode coordinator", label: "mode coordinator", description: "Delegate role-owned work by default" },
-    { value: "save", label: "save", description: "Write the current mode as the next session's default" },
+    { value: "save", label: "save", description: "Save the current mode and cap as defaults" },
 ];
 
 export function subagentsArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
@@ -1176,7 +1180,6 @@ function subagentWorkRows(now: number): BackgroundWorkRow[] {
     });
 }
 
-const DELEGATION_MODES = ["manual", "adaptive", "coordinator"] as const;
 const DELEGATION_BLURB: Record<DelegationMode, string> = {
     manual: "only when you or a workflow asks",
     adaptive: "substantial independent work",
@@ -1496,7 +1499,33 @@ function catalogRoleSchema(purpose: string) {
 
 export default function (pi: ExtensionAPI) {
     let delegationOverride: DelegationMode | undefined;
+    let capOverride: number | undefined;
+    const activeConcurrencyCap = (): number => capOverride ?? normalizeConcurrencyCap(loadConfig().maxConcurrent);
+    const changeCap = (cap: number): void => {
+        if (!isConcurrencyCap(cap)) throw new Error("Concurrent subagents must be a positive whole number.");
+        capOverride = cap;
+        pi.appendEntry("pi-better-subagents-cap", { version: 1, maxConcurrent: cap });
+    };
+    const changeMode = (mode: DelegationMode): void => {
+        delegationOverride = mode;
+        pi.appendEntry("pi-better-subagents-delegation", { version: 1, mode });
+    };
+    const resetSettings = (): void => {
+        capOverride = undefined;
+        delegationOverride = undefined;
+        pi.appendEntry("pi-better-subagents-cap", { version: 1, maxConcurrent: null });
+        pi.appendEntry("pi-better-subagents-delegation", { version: 1, mode: null });
+    };
     const activeDelegationMode = (): DelegationMode => delegationOverride ?? normalizeDelegationMode(loadConfig().delegationMode);
+    const saveSettings = (): { ok: boolean; message: string } => {
+        try {
+            writeSubagentSettings({ delegationMode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap() });
+            resetSettings();
+            return { ok: true, message: "Subagent defaults saved." };
+        } catch (error) {
+            return { ok: false, message: `Could not save subagent defaults: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    };
     readDelegation = () => ({
         mode: activeDelegationMode(),
         source: delegationOverride ? "session" : "config",
@@ -1504,8 +1533,7 @@ export default function (pi: ExtensionAPI) {
     cycleDelegation = () => {
         const current = activeDelegationMode();
         const next = DELEGATION_MODES[(DELEGATION_MODES.indexOf(current) + 1) % DELEGATION_MODES.length]!;
-        delegationOverride = next;
-        pi.appendEntry("pi-better-subagents-delegation", { version: 1, mode: next });
+        changeMode(next);
     };
     saveDelegationDefault = (mode) => {
         try {
@@ -1519,9 +1547,17 @@ export default function (pi: ExtensionAPI) {
     };
     const restoreDelegationMode = (ctx: ExtensionContext): void => {
         delegationOverride = undefined;
+        capOverride = undefined;
         const branch = ctx.sessionManager?.getBranch?.();
         if (!Array.isArray(branch)) return;
         for (const entry of branch) {
+            if (entry.type === "custom" && entry.customType === "pi-better-subagents-cap") {
+                const data = entry.data as { version?: unknown; maxConcurrent?: unknown } | null;
+                if (data?.version === 1) {
+                    if (data.maxConcurrent === null) capOverride = undefined;
+                    else if (isConcurrencyCap(data.maxConcurrent)) capOverride = data.maxConcurrent;
+                }
+            }
             if (entry.type !== "custom" || entry.customType !== "pi-better-subagents-delegation") continue;
             const data = entry.data as { version?: unknown; mode?: unknown } | null;
             if (data?.version !== 1) continue;
@@ -1905,8 +1941,7 @@ export default function (pi: ExtensionAPI) {
             const blankSelector = blankCatalogSelector(p);
             if (blankSelector) throw new Error(blankSelector);
 
-            const cfg = loadConfig();
-            const maxConcurrent = cfg.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+            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
@@ -1926,7 +1961,7 @@ export default function (pi: ExtensionAPI) {
                 }
                 if (catalog.jobs.length > 1) {
                     const extra = catalog.jobs.length - 1;
-                    if (extra > 0 && !gate.tryReserve(extra, maxConcurrent)) {
+                    if (extra > 0 && !gate.tryReserve(extra, activeConcurrencyCap())) {
                         gate.release(1);
                         reserved = 0;
                         throw new Error(`Choosing split needs ${catalog.jobs.length} subagent slots, but only one was free. Nothing was launched.`);
@@ -2044,7 +2079,6 @@ export default function (pi: ExtensionAPI) {
             };
 
             const cfg = loadConfig();
-            const maxConcurrent = cfg.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
             const countRunning = () =>
                 listActiveMetasForParent(process.pid).filter((m) => effectiveStatus(m) === "running").length;
             const launchAvailable = p.onCapacity === "launch-available";
@@ -2087,6 +2121,7 @@ export default function (pi: ExtensionAPI) {
             // until each job commits (or the unused remainder is released) closes the
             // interleaving oversubscribe class — a stale plan alone is not enough.
             if (!launchAvailable) {
+                const maxConcurrent = activeConcurrencyCap();
                 // planBatchLaunches still produces the public error text (incl. pending).
                 planBatchLaunches({
                     jobs: p.jobs,
@@ -2122,7 +2157,7 @@ export default function (pi: ExtensionAPI) {
                 const merged = mergeJobOptions(p.shared, job);
 
                 if (launchAvailable) {
-                    if (!gate.tryReserve(1, maxConcurrent)) {
+                    if (!gate.tryReserve(1, activeConcurrencyCap())) {
                         for (let j = i; j < p.jobs.length; j++) {
                             skipped.push({ job: j + 1, name: names[j] });
                         }
@@ -2235,30 +2270,53 @@ export default function (pi: ExtensionAPI) {
     if (typeof pi.registerCommand === "function") {
         agentOperations.registerCommands(pi);
         pi.registerCommand("subagents", {
-            description: "[mode manual|adaptive|coordinator|save] — Session mode, or save it as the next session's default",
+            description: "[settings|mode manual|adaptive|coordinator|cap <number>|save|reset] — Subagent settings",
             getArgumentCompletions: subagentsArgumentCompletions,
             async handler(args, ctx) {
                 const tokens = args.trim().split(/\s+/).filter(Boolean);
-                if (tokens.length === 0) {
-                    ctx.ui.notify(`Delegation mode: ${activeDelegationMode()}.`, "info");
+                if (tokens.length === 0 || (tokens.length === 1 && tokens[0] === "settings")) {
+                    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),
+                            }),
+                            changeMode, changeCap, save: saveSettings, reset: resetSettings,
+                        }, () => { refreshBackgroundWorkNavigator(ctx); tui.requestRender(); }, () => done()));
+                    } else {
+                        ctx.ui.notify(`Delegation mode: ${activeDelegationMode()}. Concurrent subagents: ${activeConcurrencyCap()}. Use /subagents mode <mode> or /subagents cap <number>; /subagents save persists both.`, "info");
+                    }
                     return;
                 }
                 const requested = tokens[1];
                 if (tokens.length === 1 && tokens[0] === "save") {
-                    const mode = activeDelegationMode();
-                    if (ctx.hasUI && !(await ctx.ui.confirm("Save delegation default?", `Future sessions will start in ${mode}.`))) {
-                        ctx.ui.notify("Delegation default unchanged.", "info");
+                    if (ctx.hasUI && !(await ctx.ui.confirm("Save subagent defaults?", `Future sessions will start in ${activeDelegationMode()} with a cap of ${activeConcurrencyCap()}.`))) {
+                        ctx.ui.notify("Subagent defaults unchanged.", "info");
                         return;
                     }
-                    const saved = saveDelegationDefault(mode);
+                    const saved = saveSettings();
                     ctx.ui.notify(saved.message, saved.ok ? "info" : "warning");
+                } else if (tokens.length === 1 && tokens[0] === "reset") {
+                    resetSettings();
+                    ctx.ui.notify("Session subagent settings reset to saved defaults.", "info");
                 } else if (tokens.length === 2 && tokens[0] === "mode" && isDelegationMode(requested)) {
-                    delegationOverride = requested;
-                    pi.appendEntry("pi-better-subagents-delegation", { version: 1, mode: delegationOverride });
-                    ctx.ui.notify(`Delegation mode: ${delegationOverride} (current session).`, "info");
+                    changeMode(requested);
+                    ctx.ui.notify(`Delegation mode: ${activeDelegationMode()} (current session).`, "info");
+                } else if (tokens.length === 2 && tokens[0] === "cap") {
+                    const cap = /^\d+$/.test(requested!) ? Number(requested) : NaN;
+                    if (!isConcurrencyCap(cap)) {
+                        ctx.ui.notify("Concurrent subagents must be a positive whole number. Nothing changed.", "warning");
+                        return;
+                    }
+                    changeCap(cap);
+                    ctx.ui.notify(`Concurrent subagents: ${cap} (current session). Running subagents are unchanged.`, "info");
                 } else {
-                    ctx.ui.notify("Usage: /subagents [mode manual|adaptive|coordinator|save]", "warning");
+                    ctx.ui.notify("Usage: /subagents [settings|mode manual|adaptive|coordinator|cap <number>|save|reset]", "warning");
                 }
+                refreshBackgroundWorkNavigator(ctx);
             },
         });
     }

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

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

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

@@ -0,0 +1,128 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import * as Tui from "@earendil-works/pi-tui";
+import { isConcurrencyCap } from "./config.ts";
+import { DELEGATION_MODES, type DelegationMode } from "./delegation.ts";
+
+export interface SubagentSettingsSnapshot {
+    mode: DelegationMode;
+    maxConcurrent: number;
+    modeSource: "session" | "config";
+    capSource: "session" | "config";
+    defaultMode: DelegationMode;
+    defaultCap: number;
+}
+
+export interface SubagentSettingsHandlers {
+    get(): SubagentSettingsSnapshot;
+    changeMode(mode: DelegationMode): void;
+    changeCap(cap: number): void;
+    save(): { ok: boolean; message: string };
+    reset(): void;
+}
+
+const labels = ["Delegation mode", "Concurrent subagents", "Save as defaults", "Reset to defaults"];
+
+export function createSubagentSettingsPage(
+    theme: Theme,
+    handlers: SubagentSettingsHandlers,
+    requestRender: () => void,
+    close: () => void,
+): Tui.Component & Tui.Focusable {
+    const input = new Tui.Input();
+    let focused = false;
+    let row = 0;
+    let editing = false;
+    let message = "";
+    let error = false;
+    function report(text: string, failed = false): void {
+        message = text;
+        error = failed;
+        requestRender();
+    }
+    function action(): void {
+        try {
+            const settings = handlers.get();
+            if (row === 0) {
+                const next = DELEGATION_MODES[(DELEGATION_MODES.indexOf(settings.mode) + 1) % DELEGATION_MODES.length]!;
+                handlers.changeMode(next);
+                report("Session mode updated.");
+            } else if (row === 1) {
+                editing = true;
+                input.setValue(String(settings.maxConcurrent));
+                input.handleInput("\x05");
+                input.focused = focused;
+                report("");
+            } else if (row === 2) {
+                const result = handlers.save();
+                report(result.message, !result.ok);
+            } else {
+                handlers.reset();
+                report("Session settings reset to saved defaults.");
+            }
+        } catch (cause) {
+            report(cause instanceof Error ? cause.message : String(cause), true);
+        }
+    }
+    input.onSubmit = (value) => {
+        const cap = /^\d+$/.test(value.trim()) ? Number(value.trim()) : NaN;
+        if (!isConcurrencyCap(cap)) {
+            report("Enter a positive whole number.", true);
+            return;
+        }
+        try {
+            handlers.changeCap(cap);
+            editing = false;
+            input.focused = false;
+            report("Session cap updated.");
+        } catch (cause) {
+            report(cause instanceof Error ? cause.message : String(cause), true);
+        }
+    };
+    input.onEscape = () => {
+        editing = false;
+        input.focused = false;
+        report("");
+    };
+    return {
+        get focused() { return focused; },
+        set focused(value: boolean) { focused = value; input.focused = editing && value; },
+        invalidate() { input.invalidate(); },
+        handleInput(data: string) {
+            if (editing) {
+                input.handleInput(data);
+                requestRender();
+                return;
+            }
+            if (Tui.matchesKey(data, Tui.Key.escape)) close();
+            else if (Tui.matchesKey(data, Tui.Key.up)) row = Math.max(0, row - 1);
+            else if (Tui.matchesKey(data, Tui.Key.down)) row = Math.min(labels.length - 1, row + 1);
+            else if (Tui.matchesKey(data, Tui.Key.enter) || data === " ") action();
+            else if (Tui.matchesKey(data, "ctrl+s")) {
+                const selected = row;
+                row = 2;
+                action();
+                row = selected;
+            }
+            requestRender();
+        },
+        render(width: number) {
+            const settings = handlers.get();
+            const values = [
+                `${settings.mode} (${settings.modeSource})`,
+                `${settings.maxConcurrent} (${settings.capSource})`,
+                "",
+                "",
+            ];
+            const lines = [theme.fg("accent", theme.bold("Subagent settings")), ""];
+            labels.forEach((label, index) => {
+                const text = `${index === row ? ">" : " "} ${label}${values[index] ? `: ${values[index]}` : ""}`;
+                lines.push(index === row ? theme.fg("accent", theme.bold(text)) : text);
+            });
+            if (editing) lines.push("", ...input.render(Math.max(1, width)));
+            lines.push("", theme.fg("muted", `Saved defaults: ${settings.defaultMode}, cap ${settings.defaultCap}`));
+            if (message) lines.push(theme.fg(error ? "error" : "success", message));
+            lines.push("", theme.fg("dim", editing ? "Enter apply  Esc cancel" : "Up/Down select  Enter change  Ctrl+S save  Esc close"));
+            return lines.map((line) => Tui.truncateToWidth(line, Math.max(1, width), ""));
+        },
+    };
+}

package/node_modules/pi-better-subagents/shared-task-sandbox.ts

@@ -6,6 +6,8 @@ const { createBashToolDefinition, createReadToolDefinition, createWriteToolDefin
     createEditToolDefinition, createLocalBashOperations, getShellConfig } = PiCodingAgent;
 import { pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { unlink } from "node:fs/promises";
 import { accessSync, constants, lstatSync, mkdirSync, mkdtempSync, readlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
@@ -117,42 +119,51 @@ export function createTaskBashOperations(
             const scratch = plan.policy.runtimeWrite?.[0];
             const taskEnv = { ...process.env, ...options.env,
                 ...(scratch ? { TMPDIR: scratch, TMP: scratch, TEMP: scratch } : {}) };
-            const wrapped = maybeBuildSandboxCommand({
-                policy: plan.policy, profilePath: plan.profilePath,
-                execPath: "/usr/bin/env", execArgs: ["-i", "--", ...Object.entries(taskEnv)
-                    .filter((entry): entry is [string, string] => entry[1] !== undefined)
-                    .map(([key, value]) => `${key}=${value}`), shell.shell, ...shell.args, command],
-            }, { sandboxEnabled: true, explicitSandbox: true });
-            if (!wrapped) throw new Error("Sandbox: no task execution backend is available.");
-            for (const line of wrapped.notices ?? []) options.onData(Buffer.from(`${line}\n`));
             if (options.signal?.aborted) throw new Error("aborted");
             if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout <= 0 || options.timeout * 1000 > 2147483647)) {
                 throw new Error("Invalid timeout: must be a positive, supported number of seconds");
             }
-            // No shell or caller-controlled loader environment runs before the boundary.
-            return new Promise((resolve, reject) => {
-                const child = spawn(wrapped.file, wrapped.fileArgs, { cwd, detached: true,
-                    env: { PATH: "/usr/bin:/bin", HOME: plan.policy.home }, stdio: ["ignore", "pipe", "pipe"] });
-                let timedOut = false;
-                const kill = () => { if (child.pid) { try { process.kill(-child.pid, "SIGKILL"); } catch { child.kill("SIGKILL"); } } };
-                const timer = options.timeout === undefined ? undefined : setTimeout(() => { timedOut = true; kill(); }, options.timeout * 1000);
-                if (child.pid) trackDetachedChildPid(child.pid);
-                const cleanup = () => {
-                    if (child.pid) untrackDetachedChildPid(child.pid);
-                    if (timer) clearTimeout(timer);
-                    options.signal?.removeEventListener("abort", kill);
-                };
-                child.stdout.on("data", options.onData);
-                child.stderr.on("data", options.onData);
-                options.signal?.addEventListener("abort", kill, { once: true });
-                if (options.signal?.aborted) kill();
-                void waitForChildProcess(child).then((exitCode: number | null) => {
-                    cleanup();
-                    if (options.signal?.aborted) reject(new Error("aborted"));
-                    else if (timedOut) reject(new Error(`timeout:${options.timeout}`));
-                    else resolve({ exitCode });
-                }, (error: unknown) => { cleanup(); reject(error); });
-            });
+            // A sibling launch must never rewrite a profile another process is reading.
+            const profilePath = `${plan.profilePath}.${randomUUID()}.bash.sb`;
+            try {
+                const wrapped = maybeBuildSandboxCommand({
+                    policy: plan.policy, profilePath,
+                    execPath: "/usr/bin/env", execArgs: ["-i", "--", ...Object.entries(taskEnv)
+                        .filter((entry): entry is [string, string] => entry[1] !== undefined)
+                        .map(([key, value]) => `${key}=${value}`), shell.shell, ...shell.args, command],
+                }, { sandboxEnabled: true, explicitSandbox: true });
+                if (!wrapped) throw new Error("Sandbox: no task execution backend is available.");
+                for (const line of wrapped.notices ?? []) options.onData(Buffer.from(`${line}\n`));
+                if (options.signal?.aborted) throw new Error("aborted");
+                // No shell or caller-controlled loader environment runs before the boundary.
+                return await new Promise<{ exitCode: number | null }>((resolve, reject) => {
+                    const child = spawn(wrapped.file, wrapped.fileArgs, { cwd, detached: true,
+                        env: { PATH: "/usr/bin:/bin", HOME: plan.policy.home }, stdio: ["ignore", "pipe", "pipe"] });
+                    let timedOut = false;
+                    const kill = () => { if (child.pid) { try { process.kill(-child.pid, "SIGKILL"); } catch { child.kill("SIGKILL"); } } };
+                    const timer = options.timeout === undefined ? undefined : setTimeout(() => { timedOut = true; kill(); }, options.timeout * 1000);
+                    if (child.pid) trackDetachedChildPid(child.pid);
+                    const cleanup = () => {
+                        if (child.pid) untrackDetachedChildPid(child.pid);
+                        if (timer) clearTimeout(timer);
+                        options.signal?.removeEventListener("abort", kill);
+                    };
+                    child.stdout.on("data", options.onData);
+                    child.stderr.on("data", options.onData);
+                    options.signal?.addEventListener("abort", kill, { once: true });
+                    if (options.signal?.aborted) kill();
+                    void waitForChildProcess(child).then((exitCode: number | null) => {
+                        cleanup();
+                        if (options.signal?.aborted) reject(new Error("aborted"));
+                        else if (timedOut) reject(new Error(`timeout:${options.timeout}`));
+                        else resolve({ exitCode });
+                    }, (error: unknown) => { cleanup(); reject(error); });
+                });
+            } finally {
+                await unlink(profilePath).catch((error: NodeJS.ErrnoException) => {
+                    if (error.code !== "ENOENT") throw error;
+                });
+            }
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -53,11 +53,11 @@
   },
   "dependencies": {
     "pi-better-background-tasks": "0.6.3",
-    "pi-better-goal": "0.6.0",
-    "pi-better-plan": "0.5.1",
-    "pi-better-sandbox": "0.8.1",
+    "pi-better-goal": "0.6.1",
+    "pi-better-plan": "0.5.2",
+    "pi-better-sandbox": "0.8.2",
     "pi-better-ssh": "0.1.1",
-    "pi-better-subagents": "0.11.0",
+    "pi-better-subagents": "0.12.0",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"
   },