pi-better-harness 0.29.2 → 0.30.1

package/extensions/minimal-output/index.ts

@@ -21,10 +21,6 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     return initialDefault = value?.enabled === true;
   }
 
-  function status(ctx: ExtensionContext): void {
-    ctx.ui.setStatus(ENTRY, enabled ? "tools: minimal" : undefined);
-  }
-
   function collapseTools(ctx: ExtensionContext): void {
     // setToolsExpanded is a no-op when already false; force a redraw of restored transcript rows.
     if (!ctx.ui.getToolsExpanded()) ctx.ui.setToolsExpanded(true);
@@ -77,7 +73,6 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
       if (enabled) collapseTools(ctx);
       hook!.setEnabled(enabled);
     } else enabled = false;
-    status(ctx);
   }
 
   async function change(value: string, ctx: ExtensionContext): Promise<void> {
@@ -98,7 +93,6 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     if (enabled) collapseTools(ctx);
     hook!.setEnabled(enabled);
     if (enabled && !running) hook!.completeRun();
-    status(ctx);
   }
 
   const setting: SettingsControl = {

package/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-background-tasks/src/process.ts

@@ -95,6 +95,10 @@ export function withWindowsLogRedirect(spec: CommandSpec, logPath: string): Comm
     return {
       ...spec,
       shell: true,
+      // The trampoline only redirects and execs an absolute program; sourcing
+      // the login profile (/etc/profile and friends) adds seconds of cold-start
+      // cost on a Windows runner and nothing the exec needs.
+      loginShell: false,
       // The MSYS2 runtime rewrites POSIX-looking argv (e.g. `/c`, `/opt/x.sh`)
       // when exec'ing native Windows binaries. Node spawn passed argv verbatim,
       // so conversion is disabled to keep raw-argv semantics unchanged. The
@@ -404,7 +408,7 @@ export function commandExecution(spec: CommandSpec): { execPath: string; execArg
     const [command, ...args] = spec.argv!;
     return { execPath: command!, execArgs: args };
   }
-  return { execPath: resolveDefaultShell(), execArgs: ["-lc", spec.command!] };
+  return { execPath: resolveDefaultShell(), execArgs: [spec.loginShell === false ? "-c" : "-lc", spec.command!] };
 }
 
 /** Stdio for a spawned task: stdin is always ignored; stdout/stderr are piped (collected) or ignored (redirected into the log by the child itself). */

package/node_modules/pi-better-background-tasks/src/shared-navigator.ts

@@ -174,8 +174,9 @@ export function isNavigatorUiAvailable(ctx: ExtensionContext | undefined): boole
   }
 }
 
-export function navigatorFooterHint(count: number): string | null {
-  return count > 0 ? `← work · ${count}` : null;
+export function navigatorFooterHint(_count: number): string | null {
+  // Retain the compatibility helper so refresh/reload clears any old badge.
+  return null;
 }
 
 export function applyNavigatorFooter(ui: { setStatus(key: string, value: string | undefined): void }, count: number): string | null {

package/node_modules/pi-better-background-tasks/src/shared-ssh-core/index.ts

@@ -58,6 +58,8 @@ export interface ResolvedSshIdentity {
 export const DEFAULT_SSH_CONNECT_TIMEOUT_SECONDS = 10;
 export const DEFAULT_SSH_CONTROL_PERSIST_SECONDS = 600;
 export const MAX_SSH_CONTROL_PATH_BYTES = 100;
+/** The longest socket name under a ControlPath root: `cm-` plus a 32-char hash. */
+const MUX_CONTROL_PATH_NAME_TEMPLATE = `cm-${"0".repeat(32)}`;
 export const DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS = 120_000;
 
 export interface RemoteRunner {
@@ -111,18 +113,33 @@ export interface SshMuxCleanupResult {
   commandResult: CommandResult;
 }
 
+export interface SshMuxForwardResult {
+  target: string;
+  localPath: string;
+  remotePath: string;
+  detail: string;
+  commandResult: CommandResult;
+}
+
 export interface SshMuxController {
   readonly controlPath: string;
   ensure(): Promise<SshMuxEnsureResult>;
+  /** Forward a local Unix socket to a remote Unix socket through the running ControlMaster (`ssh -O forward -L local:remote`). */
+  forwardUnixSocket(localPath: string, remotePath: string): Promise<SshMuxForwardResult>;
+  /** Cancel a forward made by `forwardUnixSocket` (`ssh -O cancel -L local:remote`) and remove the local socket file. */
+  cancelUnixSocketForward(localPath: string, remotePath: string): Promise<SshMuxForwardResult>;
   status(): Promise<SshMuxStatus>;
   cleanup(): Promise<SshMuxCleanupResult>;
   withMux(commandSpec: CommandSpec): CommandSpec;
 }
 
 export class SshMuxError extends Error {
-  constructor(message: string, readonly commandResult: CommandResult) {
+  // Declared, not a parameter property: Node's native type stripping (pi-better-server) cannot run those.
+  readonly commandResult: CommandResult;
+  constructor(message: string, commandResult: CommandResult) {
     super(message);
     this.name = "SshMuxError";
+    this.commandResult = commandResult;
   }
 }
 
@@ -311,7 +328,10 @@ export function wrapRemoteBashCommand(input: RemoteBashCommandInput): string {
 
 export function defaultSshControlPathRoot(): string {
   const agentDirectory = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-  return join(agentDirectory, "ssh-control");
+  const root = join(agentDirectory, "ssh-control");
+  // A long agent directory would push the socket past the unix path limit; fall back to a short per-user root.
+  if (Buffer.byteLength(join(root, MUX_CONTROL_PATH_NAME_TEMPLATE)) <= MAX_SSH_CONTROL_PATH_BYTES) return root;
+  return join("/tmp", `pi-ssh-${process.getuid?.() ?? "user"}`);
 }
 
 /**
@@ -328,6 +348,26 @@ export function createSshMuxController(options: SshMuxControllerOptions): SshMux
   const target = options.identity.target;
 
   const prepareRoot = (): void => ensureControlPathRoot(controlPathRoot);
+  const forwardOperation = async (operation: "forward" | "cancel", localPath: string, remotePath: string): Promise<SshMuxForwardResult> => {
+    for (const [name, value] of [["localPath", localPath], ["remotePath", remotePath]] as const) {
+      if (!value || /[\s:]/.test(value)) throw new Error(`ssh forward ${name} must be non-empty and contain no whitespace or colon`);
+    }
+    prepareRoot();
+    const commandResult = await options.runner.runOnce(muxCommandSpec(options.commandSpec, target, [
+      "-o", "ControlMaster=no",
+      "-o", `ControlPath=${controlPath}`,
+      "-O", operation,
+      "-L", `${localPath}:${remotePath}`,
+    ], false));
+    if (operation === "cancel") rmSync(localPath, { force: true });
+    if (!commandSucceeded(commandResult)) {
+      throw new SshMuxError(
+        `SSH ${operation} of ${localPath} -> ${target}:${remotePath} failed${resultDetail(commandResult) ? `: ${resultDetail(commandResult)}` : "."}`,
+        commandResult,
+      );
+    }
+    return { target, localPath, remotePath, detail: resultDetail(commandResult), commandResult };
+  };
   const buildControlCommand = (operation: "check" | "exit"): CommandSpec => {
     prepareRoot();
     return muxCommandSpec(options.commandSpec, target, [
@@ -350,6 +390,11 @@ export function createSshMuxController(options: SshMuxControllerOptions): SshMux
   return {
     controlPath,
     status,
+    forwardUnixSocket: async (localPath, remotePath) => {
+      rmSync(localPath, { force: true }); // ssh will not bind over a stale socket file
+      return await forwardOperation("forward", localPath, remotePath);
+    },
+    cancelUnixSocketForward: (localPath, remotePath) => forwardOperation("cancel", localPath, remotePath),
     withMux: (commandSpec) => {
       prepareRoot();
       return muxCommandSpec(commandSpec, target, [
@@ -452,6 +497,9 @@ function ensureControlPathRoot(controlPathRoot: string): void {
   if (!stats.isDirectory() || stats.isSymbolicLink()) {
     throw new Error(`ssh mux ControlPath root must be a real directory: ${controlPathRoot}`);
   }
+  if (process.getuid && stats.uid !== process.getuid()) {
+    throw new Error(`ssh mux ControlPath root must be owned by the current user: ${controlPathRoot}`);
+  }
   chmodSync(controlPathRoot, 0o700);
 }
 

package/node_modules/pi-better-background-tasks/src/types.ts

@@ -22,6 +22,8 @@ export interface CommandSpec {
   command?: string;
   argv?: string[];
   shell?: boolean;
+  /** Run the shell as a login shell (`bash -lc`, the default). False runs `bash -c`, skipping profile sourcing. */
+  loginShell?: boolean;
   cwd?: string;
   env?: Record<string, string>;
 }

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

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

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

@@ -703,11 +703,8 @@ export default function (pi: ExtensionAPI): void {
       }
     }
     if (waitingOnAnswer > 0) return `${waitingOnAnswer} background done; waiting on your answer`;
-    const background = snapshot?.backgroundRunning
-      ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
-      : undefined;
-    if (goal?.status === "paused") return background ? `${pausedGoalStatus(goal, preferences.conversationalResume)} · ${background}` : pausedGoalStatus(goal, preferences.conversationalResume);
-    if (background) return background;
+    if (goal?.status === "paused") return pausedGoalStatus(goal, preferences.conversationalResume);
+    if (snapshot?.backgroundRunning) return undefined;
     const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
     if (continuation?.blocked) return "waiting: no progress";
     const goalStall = observeGoalStall(goal, continuation, {

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

@@ -322,12 +322,11 @@ directory. Existing evidence is retained; enforcement is unaffected.
 /sandbox rules               open the write-denied paths editor
 ```
 
-The footer shows `sandbox · available` when a backend is available but inactive,
-`sandbox · inactive` when inactive without a backend, and
-`sandbox · on · <project>` while protection is active. Explicitly enabled
-sessions report `UNAVAILABLE` or `FAILED` when protection cannot be applied.
-Both surfaces report what the runtime actually resolved — which backend, which
-executable — never what was merely configured.
+Sandbox status is not displayed in the footer. Use `/sandbox` to inspect the
+permission table, or the text status report outside the TUI. Explicitly enabled
+sessions still warn when protection cannot be applied. Status reports describe
+what the runtime actually resolved, including the backend and executable, never
+what was merely configured.
 
 `/sandbox off` and `/sandbox default off` need interactive confirmation and are
 refused outright when there is no interactive UI. There is no tool for changing

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

@@ -42,12 +42,9 @@ import { defaultSandboxPermissions, describeLoosening, type SandboxPermissionSet
 import { openPermissionsPage } from "./permissions-page.ts";
 import { appendSessionPermissions, readSessionPermissions } from "./session-permissions.ts";
 
-import { footerTone, formatFooterStatus } from "./status.ts";
 import { ForegroundSandboxController, type ForegroundSandboxStatus } from "./state.ts";
 import { SandboxDiagnostics, diagnosticPackageVersion } from "./shared-sandbox-diagnostics.ts";
 
-const FOOTER_KEY = "sandbox";
-
 export default function piBetterSandbox(pi: ExtensionAPI): void {
     const controller = new ForegroundSandboxController();
     let diagnosticsWarning: ((error: unknown) => void) | undefined;
@@ -97,11 +94,8 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
         }
     });
 
-    let paintFooter: ((status: ForegroundSandboxStatus) => void) | undefined;
-
     const announce = (status: ForegroundSandboxStatus): void => {
         publishForegroundSandboxPolicy(pi.events, status);
-        paintFooter?.(status);
     };
 
     // A consumer that loaded after the last publication can ask for the current
@@ -115,13 +109,6 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
     const denyRules = new DenyRuleManager({ controller, onStateChange: announce });
 
     const restorePermissions = (ctx: ExtensionContext): void => {
-        paintFooter = (status) => {
-            ctx.ui.setStatus(
-                FOOTER_KEY,
-                formatFooterStatus(status, (tone, text) => ctx.ui.theme.fg(tone, text)),
-            );
-        };
-
         // Session policy takes precedence over global defaults. Never skip an
         // invalid latest entry to recover an older, potentially broader policy.
         let settings = defaultSandboxPermissions();
@@ -151,8 +138,8 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
 
         // Then the rules are re-read and re-resolved, because the same global
         // template set means different absolute paths in a different project.
-        // Loading is what announces the session's first policy, so consumers and
-        // the footer never see the pre-rule state.
+        // Loading announces the session's first policy, so consumers never see
+        // the pre-rule state.
         const report = denyRules.load();
         const status = report.status;
 

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-sandbox",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "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-ssh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-ssh",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Pi extension for safe synchronous remote bash commands over reusable SSH connections.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-ssh/src/shared-ssh-core/index.ts

@@ -58,6 +58,8 @@ export interface ResolvedSshIdentity {
 export const DEFAULT_SSH_CONNECT_TIMEOUT_SECONDS = 10;
 export const DEFAULT_SSH_CONTROL_PERSIST_SECONDS = 600;
 export const MAX_SSH_CONTROL_PATH_BYTES = 100;
+/** The longest socket name under a ControlPath root: `cm-` plus a 32-char hash. */
+const MUX_CONTROL_PATH_NAME_TEMPLATE = `cm-${"0".repeat(32)}`;
 export const DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS = 120_000;
 
 export interface RemoteRunner {
@@ -111,18 +113,33 @@ export interface SshMuxCleanupResult {
   commandResult: CommandResult;
 }
 
+export interface SshMuxForwardResult {
+  target: string;
+  localPath: string;
+  remotePath: string;
+  detail: string;
+  commandResult: CommandResult;
+}
+
 export interface SshMuxController {
   readonly controlPath: string;
   ensure(): Promise<SshMuxEnsureResult>;
+  /** Forward a local Unix socket to a remote Unix socket through the running ControlMaster (`ssh -O forward -L local:remote`). */
+  forwardUnixSocket(localPath: string, remotePath: string): Promise<SshMuxForwardResult>;
+  /** Cancel a forward made by `forwardUnixSocket` (`ssh -O cancel -L local:remote`) and remove the local socket file. */
+  cancelUnixSocketForward(localPath: string, remotePath: string): Promise<SshMuxForwardResult>;
   status(): Promise<SshMuxStatus>;
   cleanup(): Promise<SshMuxCleanupResult>;
   withMux(commandSpec: CommandSpec): CommandSpec;
 }
 
 export class SshMuxError extends Error {
-  constructor(message: string, readonly commandResult: CommandResult) {
+  // Declared, not a parameter property: Node's native type stripping (pi-better-server) cannot run those.
+  readonly commandResult: CommandResult;
+  constructor(message: string, commandResult: CommandResult) {
     super(message);
     this.name = "SshMuxError";
+    this.commandResult = commandResult;
   }
 }
 
@@ -311,7 +328,10 @@ export function wrapRemoteBashCommand(input: RemoteBashCommandInput): string {
 
 export function defaultSshControlPathRoot(): string {
   const agentDirectory = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-  return join(agentDirectory, "ssh-control");
+  const root = join(agentDirectory, "ssh-control");
+  // A long agent directory would push the socket past the unix path limit; fall back to a short per-user root.
+  if (Buffer.byteLength(join(root, MUX_CONTROL_PATH_NAME_TEMPLATE)) <= MAX_SSH_CONTROL_PATH_BYTES) return root;
+  return join("/tmp", `pi-ssh-${process.getuid?.() ?? "user"}`);
 }
 
 /**
@@ -328,6 +348,26 @@ export function createSshMuxController(options: SshMuxControllerOptions): SshMux
   const target = options.identity.target;
 
   const prepareRoot = (): void => ensureControlPathRoot(controlPathRoot);
+  const forwardOperation = async (operation: "forward" | "cancel", localPath: string, remotePath: string): Promise<SshMuxForwardResult> => {
+    for (const [name, value] of [["localPath", localPath], ["remotePath", remotePath]] as const) {
+      if (!value || /[\s:]/.test(value)) throw new Error(`ssh forward ${name} must be non-empty and contain no whitespace or colon`);
+    }
+    prepareRoot();
+    const commandResult = await options.runner.runOnce(muxCommandSpec(options.commandSpec, target, [
+      "-o", "ControlMaster=no",
+      "-o", `ControlPath=${controlPath}`,
+      "-O", operation,
+      "-L", `${localPath}:${remotePath}`,
+    ], false));
+    if (operation === "cancel") rmSync(localPath, { force: true });
+    if (!commandSucceeded(commandResult)) {
+      throw new SshMuxError(
+        `SSH ${operation} of ${localPath} -> ${target}:${remotePath} failed${resultDetail(commandResult) ? `: ${resultDetail(commandResult)}` : "."}`,
+        commandResult,
+      );
+    }
+    return { target, localPath, remotePath, detail: resultDetail(commandResult), commandResult };
+  };
   const buildControlCommand = (operation: "check" | "exit"): CommandSpec => {
     prepareRoot();
     return muxCommandSpec(options.commandSpec, target, [
@@ -350,6 +390,11 @@ export function createSshMuxController(options: SshMuxControllerOptions): SshMux
   return {
     controlPath,
     status,
+    forwardUnixSocket: async (localPath, remotePath) => {
+      rmSync(localPath, { force: true }); // ssh will not bind over a stale socket file
+      return await forwardOperation("forward", localPath, remotePath);
+    },
+    cancelUnixSocketForward: (localPath, remotePath) => forwardOperation("cancel", localPath, remotePath),
     withMux: (commandSpec) => {
       prepareRoot();
       return muxCommandSpec(commandSpec, target, [
@@ -452,6 +497,9 @@ function ensureControlPathRoot(controlPathRoot: string): void {
   if (!stats.isDirectory() || stats.isSymbolicLink()) {
     throw new Error(`ssh mux ControlPath root must be a real directory: ${controlPathRoot}`);
   }
+  if (process.getuid && stats.uid !== process.getuid()) {
+    throw new Error(`ssh mux ControlPath root must be owned by the current user: ${controlPathRoot}`);
+  }
   chmodSync(controlPathRoot, 0o700);
 }
 

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",
@@ -570,7 +572,15 @@ function syncWidgetNavSelection(running: RunMeta[]): void {
  */
 function renderWidget(): void {
     const ctx = uiCtx;
-    if (!ctx || !ctx.hasUI) return;
+    if (!ctx) return;
+    // A run can exit after Pi replaced the session that captured this ctx; Pi then throws on any
+    // property read. That session's UI is gone, so drop the ctx instead of failing the finalizer.
+    try {
+        if (!ctx.hasUI) return;
+    } catch {
+        if (uiCtx === ctx) uiCtx = undefined;
+        return;
+    }
     updateNavigatorFooter(ctx);
     try { ctx.ui.setWidget("subagents", WIDGET_CLEAR); } catch { /* ignore */ }
     spendCache.clear();
@@ -1522,6 +1532,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() });
@@ -1838,7 +1855,9 @@ export default function (pi: ExtensionAPI) {
         const snapshot = taskRuntime ? takeRecoverySnapshot(taskRuntime.policy.permissions) : undefined;
         if (snapshot?.started) {
             void snapshot.done.then((outcome) => {
-                if (!outcome.ok) ctx.ui?.notify?.(`Subagent ${id}: recovery snapshot failed (run continues): ${outcome.detail}`, "warning");
+                if (outcome.ok) return;
+                // The snapshot can finish after the session was replaced and ctx went stale.
+                try { ctx.ui?.notify?.(`Subagent ${id}: recovery snapshot failed (run continues): ${outcome.detail}`, "warning"); } catch { /* ignore */ }
             });
         }
         const cmd = taskRuntime ? { file: taskRuntime.file, fileArgs: [...taskRuntime.fileArgs, ...args] } : { file: piBin, fileArgs: args };
@@ -1846,6 +1865,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 +1982,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 +2117,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 +2270,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 +2311,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 +2380,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);
@@ -2472,6 +2507,9 @@ export default function (pi: ExtensionAPI) {
         // running/orphaned children before dropping the session origin, so they
         // cannot become live process groups with no coordinator.
         stopCurrentSessionSubagents(ctx);
+        // The stopped children exit after this handler returns; their finalizers
+        // must not reach for a ctx that Pi invalidates once the session is replaced.
+        uiCtx = undefined;
         agentSessionSettings.clear();
         catalogModelRegistry = undefined;
         activeCallbackOrigin = undefined;

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

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

package/node_modules/pi-better-subagents/shared-navigator.ts

@@ -174,8 +174,9 @@ export function isNavigatorUiAvailable(ctx: ExtensionContext | undefined): boole
   }
 }
 
-export function navigatorFooterHint(count: number): string | null {
-  return count > 0 ? `← work · ${count}` : null;
+export function navigatorFooterHint(_count: number): string | null {
+  // Retain the compatibility helper so refresh/reload clears any old badge.
+  return null;
 }
 
 export function applyNavigatorFooter(ui: { setStatus(key: string, value: string | undefined): void }, count: number): string | null {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.29.2",
+  "version": "0.30.1",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -53,12 +53,12 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "pi-better-background-tasks": "0.9.0",
-    "pi-better-goal": "0.9.0",
+    "pi-better-background-tasks": "0.9.1",
+    "pi-better-goal": "0.9.1",
     "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-sandbox": "0.12.1",
+    "pi-better-ssh": "0.1.3",
+    "pi-better-subagents": "0.19.1",
     "proper-lockfile": "^4.1.2",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"