pi-better-background-tasks 0.8.0 → 0.9.1

package/package.json

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

package/src/index.ts

@@ -5,8 +5,10 @@ import { clearBackgroundTasksNavigatorSession, ensureBackgroundTasksNavigator, e
 import { resumeScheduledWork, suspendScheduledWork } from "./runtime.js";
 import { observeForegroundSandboxPolicy } from "./sandbox.js";
 import { registerTools } from "./tools.js";
+import { appendExecutionPolicy } from "./shared-execution-policy.js";
 
 export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => ({ systemPrompt: appendExecutionPolicy(event.systemPrompt) }));
   registerBackgroundTasksGoalProvider(pi);
   ensureBackgroundTasksNavigatorProvider(pi);
   // Subscribed at load so a sandbox extension that publishes later is heard, and

package/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/src/shared-execution-policy.ts

@@ -0,0 +1,19 @@
+// Generated from packages/pi-better-harness/extensions/execution-policy.ts. Do not edit directly.
+/** Harness-wide scheduling guidance, vendored so standalone extensions share it. */
+const EXECUTION_POLICY = [
+  "Harness execution policy: concurrency is separate from subagent delegation.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent independently verifiable deliverables (such as each host migration) separately in the plan; do not hide them in one serial rollout step or create dependencies merely from list order.",
+  "Start all ready, authorized, non-conflicting units concurrently within known resource limits before waiting for any one to finish. Reassess ready work after launches and results; continue unblocked foreground work instead of polling running tasks. Do not equate one background launch with scheduling all ready work.",
+  "Serialize only for a concrete dependency, conflicting writes or ownership, resource or concurrency limit, documented rollout gate, or explicit availability requirement. Record the reason in the plan or explain it to the user. Do not invent a canary or host-by-host availability requirement.",
+  "If concurrency raises an unresolved material operational trade-off (for example, draining all hosts could leave no available runners), ask the user once before the affected operations. Continue independent preparation meanwhile. Existing authorization, safety checks, workflow prerequisites, and human-approved rollout constraints remain binding; urgency does not waive them.",
+  "Choose the execution mechanism after deciding what can run together: foreground tools for small, tightly coupled, or interactive work; subagents for bounded independent reasoning or implementation when the active delegation mode permits; background tasks for independent long-running commands or waits. Manual delegation forbids proactive subagents, not concurrent foreground tools or background commands. Use available batch or parallel tool interfaces where appropriate and inspect every launch receipt for failures or skipped work.",
+  "A unit waiting or failing does not block other ready independent units unless the evidence shows a shared blocker. Preserve each unit's guards and rollback boundary. Before completing verification, the plan, or the goal, inspect and integrate every relevant terminal result or failure; launch is not completion.",
+].join("\n");
+
+export function appendExecutionPolicy(systemPrompt: string): string {
+  // Inspect the prompt, not module-global state: vendored copies have separate
+  // module identities, and every fresh turn or reload needs the policy again.
+  return systemPrompt.includes(EXECUTION_POLICY)
+    ? systemPrompt
+    : `${systemPrompt}\n\n${EXECUTION_POLICY}`;
+}

package/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/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/src/tools.ts

@@ -184,6 +184,7 @@ const StatusActionParams = Type.Object({
 });
 
 const BACKGROUND_ORCHESTRATION_GUIDELINES = [
+  "Follow the Harness execution policy when scheduling independent background operations; subagent delegation mode does not require background commands to run serially.",
   "Use background tasks for genuinely long-running processes or repeated checks. Run short commands in the foreground.",
   "When a structured plan is active, keep it as the coordinator ledger: launch relevant background work early, continue unblocked foreground work without polling, and update the plan after inspecting each terminal result or failure.",
   "Do not treat launch as completion of the parent milestone; relevant background work must be terminal, inspected, and integrated before verification or completion.",

package/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>;
 }