pi-better-harness 0.30.0 → 0.31.0

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/README.md

@@ -57,6 +57,15 @@ Invoking the alias (`/skill:resolve-issues`, or `/goal /skill:resolve-issues tas
 
 After every successful context compaction (Pi's `session_compact` event) while a coordinator owns the session, the goal extension re-injects the skill so the model sees it before its next step; the compaction summary keeps run state but not the skill's rules, and the summary itself is left unchanged. If the skill directory ships `scripts/rehydrate.mjs` (checked first) or `rehydrate.mjs`, it runs as `node <script> --cwd <session cwd>` (no shell, 10-second timeout, stderr ignored) and its trimmed stdout becomes the message; empty output injects nothing, so the script decides whether a run is in progress. Without a script, or when it fails or times out, the message is: "Your context was just compacted while you coordinate the `<name>` workflow. Before your next step, read `<SKILL.md path>` in full, with no line limit." The message is a `workflow-rehydrate` custom message: inside a running agent loop (or before an overflow retry) it steers the next model call; otherwise it is appended without starting a turn.
 
+### Scheduler-backed workflow gates
+
+A coordinator that ships the resolve-issues scheduler (`scripts/next-actions.mjs` in its skill directory, or in a sibling `resolve-issues` skill) keeps its Goal from ending while the run still has work. The extension runs `node next-actions.mjs --run <run dir> --slots 1 --peek --json` (read-only, 20-second timeout), where the run directory is the folder of the task plan bound through `update_plan`. Every gate fails open: if the scheduler is missing, errors, times out, prints bad output, or no plan is bound yet, the call proceeds and its result carries a warning, so nothing deadlocks.
+
+- **Completion.** `update_goal` complete is refused, with each due action (action, unit, first 200 characters of detail), unless the scheduler reports `finish` and nothing else is due (an empty due list means workers are still running, so it is refused too). The Goal stays active.
+- **Pause.** `release_workflow` is refused unless every unfinished unit is quiet (nothing due for it) or blocked `human-decision` with `humanItem` 2-5. A unit blocked `retry-ci` or any other reason the run retries itself, or a `human-decision` item 1, is named in the refusal and the Goal stays active.
+- **Auto-bind.** Invoking `/skill:rush-issues` or `/skill:resolve-issues` with no active goal (none, or a completed one) creates and activates a Goal whose objective is the invocation text, exactly as `/goal <invocation>` would, without sending the command a second time. A paused or active Goal is left alone.
+- **Wait timer.** When the scheduler's only due action is `wait` with a "next automatic attempt is at <ISO time>" detail, the next automatic continuation is scheduled for that time (at most the maximum timer delay, at least 5 seconds) and the wake-up is not counted as a no-progress retry. Other due work, or an unparseable time, uses the ordinary retry schedule. `autoContinue` off disables this timer.
+
 When `pi-better-plan` is installed, it defers its prompt, checklist, and `update_plan` tool to a skill-owned task plan. Skills without this metadata retain normal goal and plan behavior. The skill itself owns its planning format and worker policy; the harness does not enumerate skills or impose a shared workflow schema. The former `pi-better-plan-workflow: coordinator` metadata remains supported for installed skills.
 
 ## Install

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

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

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

@@ -40,6 +40,7 @@ import {
 import { createRenderScheduler } from "./shared-render-scheduler.js";
 import { collectSubagentActivity } from "./subagents.js";
 import { currentWorkflowOwner, skillCommandName, workflowEntry, workflowOwnerFromSkill, WORKFLOW_ENTRY_TYPE } from "./workflow.js";
+import { completionGate, pauseGate, schedulerWaitUntil } from "./workflow-gates.js";
 import { workflowRehydrateMessage, WORKFLOW_REHYDRATE_MESSAGE_TYPE } from "./rehydrate.js";
 import {
   EVENT_ACTIVITY,
@@ -58,6 +59,10 @@ const POLL_INTERVAL_MS = 2_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;
+/** Never re-poll a workflow's scheduler sooner than this, even when its stated attempt time has passed. */
+const MIN_WAIT_DELAY_MS = 5_000;
+/** Workflow skills whose invocation binds a goal when none is active, so the run cannot stop silently. */
+const AUTO_BIND_SKILLS = new Set(["rush-issues", "resolve-issues"]);
 const WAKE_DISABLED =
   process.env.PI_BETTER_GOAL_DISABLE_WAKE === "1" ||
   process.env.PI_BETTER_EXTENSION_DISABLE_WAKE === "1";
@@ -477,6 +482,21 @@ export default function (pi: ExtensionAPI): void {
       ? workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath)
       : null;
 
+  /**
+   * The session's workflow owner when an active goal is bound to it through its skill command, else
+   * null. Only these goals are gated by the workflow's scheduler.
+   */
+  const boundWorkflow = (goal: GoalSnapshot, ctx: ExtensionContext): NonNullable<ReturnType<typeof currentWorkflowOwner>> | null => {
+    const owner = getWorkflow(ctx);
+    if (!owner || goal.status !== "active" || goal.command?.source !== "skill") return null;
+    try {
+      const bound = goalWorkflowOwner(goal);
+      return bound?.name === owner.name && bound.path === owner.path ? owner : null;
+    } catch {
+      return null;
+    }
+  };
+
   /**
    * The one resume path shared by `/goal resume`, the hotkey, and `goal_resume`:
    * reactivate a paused goal or reopen an active no-progress hold.
@@ -568,6 +588,8 @@ export default function (pi: ExtensionAPI): void {
     ctx: ExtensionContext,
     kind: "continuation" | "background-drained",
     snapshot?: ActivitySnapshot,
+    /** Fixed delay for a workflow scheduler's wait; replaces any pending timer and ignores no-progress backoff. */
+    waitDelayMs?: number,
   ): void => {
     if (WAKE_DISABLED || !preferences.autoContinue || !isPokeable(goal) || continuationQueuedFor === goal.goalId) {
       return;
@@ -576,8 +598,8 @@ export default function (pi: ExtensionAPI): void {
     if (currentContinuationState(ctx, goal.goalId)?.blocked) {
       return;
     }
-    const signature = `${goal.goalId}:${kind}`;
-    if (idleContinuationTimer && (idleContinuationSignature === signature ||
+    const signature = `${goal.goalId}:${waitDelayMs === undefined ? kind : "wait"}`;
+    if (waitDelayMs === undefined && idleContinuationTimer && (idleContinuationSignature === signature ||
         (kind === "continuation" && idleContinuationSignature === `${goal.goalId}:background-drained`))) {
       return;
     }
@@ -587,7 +609,7 @@ export default function (pi: ExtensionAPI): void {
       idleContinuationTimer = undefined;
       idleContinuationSignature = "";
       void sendIdleContinuationAfterAudit(goal.goalId, ctx, kind, snapshot);
-    }, idleContinuationDelay(kind === "continuation" ? currentContinuationState(ctx, goal.goalId)?.noProgressRetries ?? 0 : 0));
+    }, waitDelayMs ?? idleContinuationDelay(kind === "continuation" ? currentContinuationState(ctx, goal.goalId)?.noProgressRetries ?? 0 : 0));
     idleContinuationTimer.unref?.();
   };
 
@@ -626,6 +648,8 @@ export default function (pi: ExtensionAPI): void {
     tokenBudget: number | null,
     ctx: ExtensionContext,
     source: "command",
+    /** False when the user's own message already invoked the command, so the goal must not send it again. */
+    dispatch = true,
   ): GoalSnapshot => {
     const objectiveError = validateObjective(objective);
     if (objectiveError) {
@@ -647,8 +671,8 @@ export default function (pi: ExtensionAPI): void {
     setGoal(goal, ctx, source);
     if (command) {
       if (owner) recordWorkflow(owner);
-      pi.sendUserMessage(commandInvocation(command), { deliverAs: "followUp", expandPromptTemplates: true });
-      if (command.source === "extension") scheduleIdleContinuation(goal, ctx, "continuation");
+      if (dispatch) pi.sendUserMessage(commandInvocation(command), { deliverAs: "followUp", expandPromptTemplates: true });
+      if (dispatch && command.source === "extension") scheduleIdleContinuation(goal, ctx, "continuation");
     } else {
       queueGoalContinuation(goal, ctx);
     }
@@ -703,11 +727,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, {
@@ -1052,12 +1073,21 @@ export default function (pi: ExtensionAPI): void {
           details: { ok: true, goal: current },
         };
       }
+      const gated = boundWorkflow(current, ctx);
+      const verdict = gated ? await completionGate(ctx.sessionManager.getBranch(), gated) : null;
+      if (verdict && !verdict.allow) {
+        return {
+          content: [{ type: "text", text: verdict.message }],
+          details: { ok: false, goal: current, due: verdict.due },
+        };
+      }
       const goal = goalWithStatus(current, "complete");
       setGoal(goal, ctx, "tool");
       if (getWorkflow(ctx)) recordWorkflow(null);
+      const warning = verdict?.allow ? verdict.warning : undefined;
       return {
-        content: [{ type: "text", text: "Goal marked complete." }],
-        details: { ok: true, goal },
+        content: [{ type: "text", text: warning ? `Goal marked complete. ${warning}` : "Goal marked complete." }],
+        details: { ok: true, goal, ...(warning ? { warning } : {}) },
       };
     },
   });
@@ -1138,6 +1168,12 @@ export default function (pi: ExtensionAPI): void {
       const owner = getWorkflow(ctx);
       if (!owner) return { content: [{ type: "text", text: "No workflow owns this session." }], details: { released: false } };
       const goal = getGoal(ctx);
+      const gated = goal ? boundWorkflow(goal, ctx) : null;
+      const verdict = gated ? await pauseGate(ctx.sessionManager.getBranch(), gated) : null;
+      if (verdict && !verdict.allow) {
+        return { content: [{ type: "text", text: verdict.message }], details: { released: false, goalPaused: false } };
+      }
+      const warning = verdict?.allow ? verdict.warning : undefined;
       let resumeCommand: string | undefined;
       if (goal?.status === "active" && goal.command?.source === "skill") {
         const boundOwner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
@@ -1148,7 +1184,7 @@ export default function (pi: ExtensionAPI): void {
       }
       recordWorkflow(null);
       return {
-        content: [{ type: "text", text: `Released ${owner.name} workflow ownership.${resumeCommand ? ` Its Goal is paused, not complete; the user's go-ahead or /goal resume rebinds /${resumeCommand}.` : ""}` }],
+        content: [{ type: "text", text: `Released ${owner.name} workflow ownership.${resumeCommand ? ` Its Goal is paused, not complete; the user's go-ahead or /goal resume rebinds /${resumeCommand}.` : ""}${warning ? ` ${warning}` : ""}` }],
         details: { released: true, owner: owner.name, goalPaused: resumeCommand !== undefined },
       };
     },
@@ -1245,7 +1281,21 @@ export default function (pi: ExtensionAPI): void {
       if (command) {
         try {
           const owner = workflowOwnerFromSkill(skillName, command.sourceInfo.path, registeredSkillPath);
-          if (owner) recordWorkflow(owner);
+          if (owner) {
+            // Without a goal nothing re-prompts the coordinator when it stops early, so bind one now
+            // exactly as `/goal <this invocation>` would. The user's message already runs the skill.
+            const existing = getGoal(ctx);
+            if (AUTO_BIND_SKILLS.has(skillName) && (!existing || existing.status === "complete")) {
+              try {
+                startOrReplaceGoal(event.text.trim(), null, ctx, "command", false);
+              } catch (error) {
+                recordWorkflow(owner);
+                notifyGoal(ctx, `Could not bind a goal to /skill:${skillName}: ${error instanceof Error ? error.message : String(error)}`, "warning");
+              }
+            } else {
+              recordWorkflow(owner);
+            }
+          }
         } catch (error) {
           notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
           return { action: "handled" as const };
@@ -1453,6 +1503,21 @@ export default function (pi: ExtensionAPI): void {
     if (!isPokeable(goal) || snapshot.backgroundRunning) {
       return;
     }
+    // A run the scheduler says is only waiting (a retry is due at a known time) is not stuck: wake at
+    // that time and leave the no-progress count alone, since nothing the model could do changes it.
+    const waitOwner = preferences.autoContinue && !WAKE_DISABLED ? boundWorkflow(goal, ctx) : null;
+    if (waitOwner) {
+      const execution = executionGeneration;
+      const waitUntil = await schedulerWaitUntil(ctx.sessionManager.getBranch(), waitOwner);
+      if (execution !== executionGeneration) return;
+      if (waitUntil !== undefined) {
+        resetContinuationState(goal);
+        lastAgentEvidence = null;
+        scheduleIdleContinuation(goal, ctx, "continuation", snapshot,
+          Math.min(MAX_TIMER_DELAY_MS, Math.max(MIN_WAIT_DELAY_MS, waitUntil - Date.now())));
+        return;
+      }
+    }
     const evidence = lastAgentEvidence;
     if (!evidence) {
       scheduleIdleContinuation(goal, ctx, "continuation", snapshot);

package/node_modules/pi-better-goal/src/workflow-gates.ts

@@ -0,0 +1,247 @@
+import { execFile } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { WorkflowOwner } from "./workflow.js";
+
+/** Branch entry the plan extension writes when it binds a workflow-owned task plan. */
+const WORKFLOW_PLAN_ENTRY = "pi-better-workflow-plan";
+const WORKFLOW_ENTRY = "pi-better-workflow";
+export const SCHEDULER_TIMEOUT_MS = 20_000;
+const DETAIL_LIMIT = 200;
+
+/** Scheduler locations relative to the owner's skill directory, in precedence order. */
+const SCHEDULER_SCRIPTS = [
+  join("scripts", "next-actions.mjs"),
+  join("..", "resolve-issues", "scripts", "next-actions.mjs"),
+];
+
+/** Units in these states are done; every other unit is unfinished work. */
+const FINISHED_STATUSES = new Set(["succeeded", "cancelled", "canceled"]);
+/** `humanItem` values 2-5 are genuine holds only a human can lift; item 1 is a decision the run takes itself. */
+const HUMAN_HOLD_ITEMS = new Set([2, 3, 4, 5]);
+
+export interface SchedulerAction {
+  action: string;
+  unit: string | null;
+  detail: string;
+}
+
+export type SchedulerRun =
+  | { ok: true; due: SchedulerAction[] }
+  | { ok: false; reason: string };
+
+/** A gate either lets the call through (optionally with a warning when it could not check) or refuses it. */
+export type GateVerdict =
+  | { allow: true; warning?: string }
+  | { allow: false; message: string; due?: SchedulerAction[] };
+
+interface EntryLike {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** The first next-actions scheduler the owner's skill ships, or undefined when it ships none. */
+export function findScheduler(owner: WorkflowOwner): string | undefined {
+  const skillDir = dirname(owner.path);
+  for (const relative of SCHEDULER_SCRIPTS) {
+    const candidate = join(skillDir, relative);
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      // Missing or unreadable: try the next location.
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The task-plan.json the session bound for `owner`, or undefined before a plan is bound.
+ * Invoking a workflow skill again starts a new run, so a later owner entry drops the old binding.
+ */
+export function boundPlanPath(entries: Iterable<EntryLike>, owner: WorkflowOwner): string | undefined {
+  let path: string | undefined;
+  for (const entry of entries) {
+    if (entry.type !== "custom") continue;
+    const data = entry.data;
+    if (entry.customType === WORKFLOW_ENTRY && isRecord(data) && data.version === 1 && data.kind === "set") path = undefined;
+    if (entry.customType !== WORKFLOW_PLAN_ENTRY || !isRecord(data) || data.version !== 1) continue;
+    if (data.kind === "clear") path = undefined;
+    else if (data.kind === "set" && data.owner === owner.name && typeof data.path === "string") path = data.path;
+  }
+  return path;
+}
+
+function parseSchedulerOutput(stdout: string): SchedulerRun {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return { ok: false, reason: "the scheduler printed output that is not JSON" };
+  }
+  if (!isRecord(parsed) || !Array.isArray(parsed.due)) return { ok: false, reason: "the scheduler output has no due list" };
+  const due = parsed.due.flatMap((item): SchedulerAction[] => isRecord(item) && typeof item.action === "string"
+    ? [{
+      action: item.action,
+      unit: item.unit === null || item.unit === undefined ? null : String(item.unit),
+      detail: typeof item.detail === "string" ? item.detail : "",
+    }]
+    : []);
+  return { ok: true, due };
+}
+
+/**
+ * Runs the scheduler read-only (`--peek`) for a run directory. The scheduler exits 1 when actions
+ * are due and 2 on a usage or plan error, so only the latter, a timeout, or bad output is a failure.
+ */
+export function runScheduler(script: string, runDir: string, timeoutMs = SCHEDULER_TIMEOUT_MS): Promise<SchedulerRun> {
+  return new Promise((resolve) => {
+    execFile("node", [script, "--run", runDir, "--slots", "1", "--peek", "--json"],
+      { cwd: runDir, timeout: timeoutMs, encoding: "utf8", windowsHide: true, maxBuffer: 8 * 1024 * 1024 },
+      (error, stdout, stderr) => {
+        if (error) {
+          // An exit status of 1 means "actions due"; any other failure (exit 2, timeout, spawn error) is real.
+          if ((error as { code?: unknown }).code !== 1) {
+            const detail = String(stderr).trim().split("\n")[0] || error.message;
+            resolve({ ok: false, reason: `the scheduler failed (${detail.slice(0, DETAIL_LIMIT)})` });
+            return;
+          }
+        }
+        resolve(parseSchedulerOutput(stdout));
+      });
+  });
+}
+
+interface PlannedRun {
+  runDir: string;
+  script: string;
+}
+
+function locateRun(entries: Iterable<EntryLike>, owner: WorkflowOwner): PlannedRun | { warning: string } {
+  const script = findScheduler(owner);
+  if (!script) return { warning: `${owner.name} ships no scheduler, so the run was not checked` };
+  const plan = boundPlanPath(entries, owner);
+  if (!plan) return { warning: `no task plan is bound for ${owner.name} yet, so the run was not checked` };
+  return { runDir: dirname(plan), script };
+}
+
+function unchecked(warning: string): GateVerdict {
+  return { allow: true, warning: `Warning: ${warning}. The gate is open so nothing deadlocks.` };
+}
+
+function describe(action: SchedulerAction): string {
+  const detail = action.detail.length > DETAIL_LIMIT ? `${action.detail.slice(0, DETAIL_LIMIT)}...` : action.detail;
+  return `- ${action.action}${action.unit ? ` (unit ${action.unit})` : ""}: ${detail}`;
+}
+
+/** Completion is allowed only when the scheduler reports `finish` and nothing else is due. */
+export async function completionGate(
+  entries: Iterable<EntryLike>,
+  owner: WorkflowOwner,
+  options: { timeoutMs?: number } = {},
+): Promise<GateVerdict> {
+  const located = locateRun(entries, owner);
+  if ("warning" in located) return unchecked(located.warning);
+  const run = await runScheduler(located.script, located.runDir, options.timeoutMs);
+  if (!run.ok) return unchecked(`could not check the ${owner.name} run (${run.reason})`);
+  const open = run.due.filter((action) => action.action !== "finish");
+  if (open.length === 0 && run.due.length > 0) return { allow: true };
+  if (open.length === 0) {
+    // Nothing due means workers are still running, not that the run is done.
+    return {
+      allow: false,
+      due: [],
+      message: `Goal not marked complete: the ${owner.name} run's workers are still running; the scheduler has not reported finish. ` +
+        "Wait for them, then call update_goal again once the scheduler reports finish.",
+    };
+  }
+  return {
+    allow: false,
+    due: open,
+    message: `Goal not marked complete: the ${owner.name} scheduler still has work due, so the run is not finished. ` +
+      `Do the due actions, then call update_goal again once the scheduler reports finish.\n${open.map(describe).join("\n")}`,
+  };
+}
+
+function readUnits(runDir: string): Array<Record<string, unknown>> | null {
+  try {
+    const plan: unknown = JSON.parse(readFileSync(join(runDir, "task-plan.json"), "utf8"));
+    return isRecord(plan) && Array.isArray(plan.units) ? plan.units.filter(isRecord) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Releasing (pausing the goal) is allowed only for genuine human holds. Every unfinished unit must be
+ * either quiet (the scheduler has nothing due for it) or blocked on human-decision item 2-5.
+ */
+export async function pauseGate(
+  entries: Iterable<EntryLike>,
+  owner: WorkflowOwner,
+  options: { timeoutMs?: number } = {},
+): Promise<GateVerdict> {
+  const located = locateRun(entries, owner);
+  if ("warning" in located) return unchecked(located.warning);
+  const units = readUnits(located.runDir);
+  if (!units) return unchecked(`could not read the ${owner.name} task plan`);
+  const run = await runScheduler(located.script, located.runDir, options.timeoutMs);
+  if (!run.ok) return unchecked(`could not check the ${owner.name} run (${run.reason})`);
+
+  const refusals: string[] = [];
+  const unfinished = new Set<string>();
+  for (const unit of units) {
+    const id = String(unit.id);
+    const status = typeof unit.status === "string" ? unit.status : "";
+    if (FINISHED_STATUSES.has(status)) continue;
+    unfinished.add(id);
+    const due = run.due.filter((action) => action.unit === id && action.action !== "finish");
+    if (due.length === 0) continue;
+    const humanHold = status === "blocked" && unit.blockedReason === "human-decision" &&
+      typeof unit.humanItem === "number" && HUMAN_HOLD_ITEMS.has(unit.humanItem);
+    if (humanHold) continue;
+    refusals.push(status === "blocked" && typeof unit.blockedReason === "string"
+      ? unit.blockedReason === "human-decision"
+        ? `unit ${id} is blocked human-decision${unit.humanItem === undefined ? "" : ` item ${String(unit.humanItem)}`}; only items 2-5 are genuine holds, so decide it yourself (${due[0]!.action})`
+        : `unit ${id} is blocked ${unit.blockedReason}; the run retries it itself (${due[0]!.action})`
+      : `unit ${id} is ${status || "unfinished"} with ${due[0]!.action} due`);
+  }
+  for (const action of run.due) {
+    if (action.action !== "finish" && (action.unit === null || !unfinished.has(action.unit))) {
+      refusals.push(`${action.unit ? `unit ${action.unit}` : "the run"} has ${action.action} due: ${action.detail.slice(0, DETAIL_LIMIT)}`);
+    }
+  }
+  if (refusals.length === 0) return { allow: true };
+  return {
+    allow: false,
+    message: `Workflow not released: the ${owner.name} run still has work it can do itself, so the goal stays active.\n` +
+      refusals.map((line) => `- ${line}`).join("\n"),
+  };
+}
+
+/** The instant of the scheduler's `wait` heartbeat, when it is the only thing due. */
+export function waitUntil(due: readonly SchedulerAction[]): number | undefined {
+  if (due.length === 0 || due.some((action) => action.action !== "wait")) return undefined;
+  const times = due.map((action) => {
+    const match = /next automatic attempt is at (\d{4}-\d{2}-\d{2}T[0-9:.]+Z?)/.exec(action.detail);
+    return match ? Date.parse(match[1]!) : Number.NaN;
+  }).filter(Number.isFinite);
+  return times.length > 0 ? Math.min(...times) : undefined;
+}
+
+/** When the bound run next wants a continuation, or undefined when it is not only waiting. */
+export async function schedulerWaitUntil(
+  entries: Iterable<EntryLike>,
+  owner: WorkflowOwner,
+  options: { timeoutMs?: number } = {},
+): Promise<number | undefined> {
+  const located = locateRun(entries, owner);
+  if ("warning" in located) return undefined;
+  const run = await runScheduler(located.script, located.runDir, options.timeoutMs);
+  return run.ok ? waitUntil(run.due) : undefined;
+}

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

@@ -572,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();
@@ -1847,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 };
@@ -2497,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.19.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.30.0",
+  "version": "0.31.0",
   "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.10.0",
     "pi-better-plan": "0.9.1",
-    "pi-better-sandbox": "0.12.0",
-    "pi-better-ssh": "0.1.2",
-    "pi-better-subagents": "0.19.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"