pi-better-harness 0.3.2 → 0.3.3

package/README.md

@@ -1,6 +1,6 @@
 # pi-better-harness
 
-`pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions: an opt-in foreground write sandbox, delegated subagents, durable background tasks, and goal tracking.
+`pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions: an opt-in foreground write sandbox, delegated subagents, durable background tasks, synchronous SSH commands, and goal tracking.
 
 ## Quick Answer
 
@@ -9,6 +9,7 @@ Use `pi-better-harness` when you want the full working set for Pi. It manages:
 - `pi-better-sandbox` for an opt-in write sandbox around Pi's foreground tools.
 - `pi-better-subagents` for detached, sandboxed subagent runs.
 - `pi-better-background-tasks` for durable shell tasks and watchers.
+- `pi-better-ssh` for short remote commands over reusable SSH connections.
 - `pi-better-goal` for objective tracking that is aware of background work.
 
 `pi-better-plan` and `pi-better-read-aloud` are intentionally not included yet.
@@ -60,7 +61,7 @@ need interactive confirmation. Full policy: [pi-better-sandbox](https://github.c
 
 ## When To Use
 
-Use the installer when you want every core extension with standalone package identities. Install an individual package instead when you only need the sandbox, subagents, shell task supervision, or goal tracking.
+Use the installer when you want every core extension with standalone package identities. Install an individual package instead when you only need the sandbox, subagents, shell task supervision, synchronous SSH, or goal tracking.
 
 ## Compatibility
 

package/extensions/ssh/index.ts

@@ -0,0 +1 @@
+export { default } from "../../node_modules/pi-better-ssh/src/index.ts";

package/lib/cli.mjs

@@ -12,6 +12,7 @@ export const componentPackages = [
   "pi-better-sandbox",
   "pi-better-subagents",
   "pi-better-background-tasks",
+  "pi-better-ssh",
   "pi-better-goal",
 ];
 

package/node_modules/pi-better-ssh/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1aboveio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,99 @@
+# pi-better-ssh
+
+`pi-better-ssh` runs short synchronous remote commands over safe, reusable SSH connections. It adds explicit remote tools; Pi's built-in `bash` remains local and is never overridden.
+
+## Install
+
+```sh
+pi install npm:pi-better-ssh
+```
+
+For one session without changing Pi settings:
+
+```sh
+pi -e npm:pi-better-ssh
+```
+
+## Choose The Right Tool
+
+Use `remote_bash` when the foreground turn should wait for a short remote command's output and exit code. Use `bg_task_spawn` and the `bg_task_*` lifecycle tools with structured `ssh` for long-running or durable remote jobs; those jobs use remote tmux for lifecycle control.
+
+| Tool | Purpose |
+| --- | --- |
+| `remote_bash` | Run one short remote bash command and wait for its result. |
+| `ssh_profile` | List SSH aliases or manage the active session's host, workdir, and environment defaults. |
+| `ssh_mux` | Inspect or stop reusable ControlMaster connections. |
+
+## SSH Hosts
+
+Prefer a literal `Host` alias in `~/.ssh/config`; OpenSSH applies its configured hostname, user, port, key, jump host, and other policy. Wildcard entries are honored by OpenSSH but are not listed by `ssh_profile`.
+
+```sshconfig
+Host airflow-prod
+  HostName airflow.internal.example
+  User deploy
+  IdentityFile ~/.ssh/airflow_ed25519
+  ProxyJump bastion.example
+```
+
+Tool calls can use the alias (`airflow-prod`) or an explicit `user@host` target. Structured `user`, `port`, `identity_file`, `jump`, and `options` fields override connection details without constructing a shell command.
+
+## Run A Command
+
+`remote_bash` requires `command`. It requires `host` unless an active profile supplies one. `workdir` and `env` apply on the remote host; `timeout` is an optional positive number of seconds.
+
+```json
+{
+  "command": "airflow dags list",
+  "host": "airflow-prod",
+  "workdir": "/opt/airflow",
+  "env": { "AIRFLOW_HOME": "/opt/airflow" },
+  "timeout": 30
+}
+```
+
+A remote non-zero exit is a normal tool result with output and `exitCode`, so agents can inspect command failures. Output follows Pi bash limits: the last 2,000 lines or 50KB, whichever is reached first. Complete truncated output is retained in a local temporary file.
+
+## Session Profile
+
+A profile sets defaults for later `remote_bash` calls. `use` accepts a configured Host alias or `user@host`, plus optional remote `workdir` and `env`. The active profile is stored in the Pi session and survives `/reload`; it is not a separate host inventory.
+
+```json
+{ "action": "list" }
+```
+
+```json
+{
+  "action": "use",
+  "host": "airflow-prod",
+  "workdir": "/opt/airflow",
+  "env": { "AIRFLOW_HOME": "/opt/airflow" }
+}
+```
+
+Call `ssh_profile` with `status` to inspect the active profile or `clear` to remove it. A footer chip shows the active target, workdir, and whether its mux is up or down. An explicit `host`, `workdir`, or environment entry on `remote_bash` takes precedence over the corresponding profile default.
+
+## ControlMaster
+
+`remote_bash` checks for a reusable ControlMaster and opens one when needed. Its ControlPath lives under the harness-owned `~/.pi/agent/ssh-control` directory, which is forced to mode `0700`; the socket key includes the connection identity and Pi session. A stale socket is removed and reopened once. Repeated commands for the same target and session reuse the master.
+
+Use `ssh_mux` with `status` or `stop` and either a target, the active profile, or `all:true` for masters observed in the current Pi process and session:
+
+```json
+{ "action": "status", "host": "airflow-prod" }
+```
+
+```json
+{ "action": "stop", "all": true }
+```
+
+Stopping a mux does not stop remote tmux jobs. A `remote_bash` timeout terminates only that slave SSH process; a healthy reusable master remains available.
+
+## Safety Defaults
+
+- SSH is launched as argv with `shell:false`; connection fields are never interpolated into a local shell command.
+- `BatchMode=yes`, a bounded connect timeout, and no TTY are always enforced, so password prompts fail fast.
+- Caller `options` cannot disable required SSH or mux safety settings.
+- Remote workdir and environment values are shell-quoted by the shared SSH core before `bash -c` runs.
+- Identity file paths may appear in status details, but key material is never read or displayed.
+- This package provides no interactive shell, PTY attach, remote IDE mode, or local `bash` override.

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

@@ -0,0 +1,57 @@
+{
+  "name": "pi-better-ssh",
+  "version": "0.1.1",
+  "description": "Pi extension for safe synchronous remote bash commands over reusable SSH connections.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "ssh",
+    "remote-bash"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1aboveio/pi-better-harness.git",
+    "directory": "packages/pi-better-ssh"
+  },
+  "bugs": {
+    "url": "https://github.com/1aboveio/pi-better-harness/issues"
+  },
+  "homepage": "https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-ssh#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "pretest": "node ../../scripts/sync-shared-ssh-core.mjs",
+    "prepack": "node ../../scripts/sync-shared-ssh-core.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/shared-ssh-core/test-support/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "typebox": "^1.1.39",
+    "typescript": "^6.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

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

@@ -0,0 +1,314 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { createSshMuxRegistry } from "./mux-registry.js";
+import type { SshMuxEntryMap, SshMuxRegistry } from "./mux-registry.js";
+import { createProcessRemoteRunner } from "./process-runner.js";
+import {
+  createSshProfile,
+  formatSshProfileChip,
+  listSshHostAliases,
+  profileStateEntry,
+  restoreSshProfile,
+  SSH_PROFILE_ENTRY_TYPE,
+} from "./profile.js";
+import type { SshProfile } from "./profile.js";
+import { executeRemoteBash, resolveRemoteBashConnection } from "./remote-bash.js";
+import type { RemoteBashDependencies, RemoteBashResult } from "./remote-bash.js";
+import { resolveSshCommand } from "./shared-ssh-core/index.js";
+
+const STATUS_KEY = "pi-better-ssh";
+
+const RemoteBashParams = Type.Object({
+  command: Type.String({ description: "Bash command string to execute remotely." }),
+  host: Type.Optional(Type.String({ description: "SSH Host alias or user@host target. Optional when an active SSH profile supplies the host." })),
+  workdir: Type.Optional(Type.String({ description: "Remote working directory applied before the command." })),
+  timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout). Cancels only this SSH slave command." })),
+  env: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Remote environment variables exported before the command." })),
+  user: Type.Optional(Type.String({ description: "Structured SSH user override." })),
+  port: Type.Optional(Type.Integer({ minimum: 1, maximum: 65_535, description: "Structured SSH port override." })),
+  identity_file: Type.Optional(Type.String({ description: "Structured SSH identity file path." })),
+  jump: Type.Optional(Type.String({ description: "Structured SSH jump host passed with -J." })),
+  options: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Additional SSH -o key/value options. Callers cannot disable required BatchMode, connect-timeout, no-TTY, or mux safety options." })),
+});
+
+const SshMuxParams = Type.Object({
+  action: Type.Union([Type.Literal("status"), Type.Literal("stop")]),
+  all: Type.Optional(Type.Boolean({ description: "Apply to every ControlMaster known in this Pi process for the current session." })),
+  host: Type.Optional(Type.String({ description: "SSH Host alias or user@host target. Defaults to the active profile." })),
+  user: Type.Optional(Type.String({ description: "Structured SSH user override." })),
+  port: Type.Optional(Type.Integer({ minimum: 1, maximum: 65_535 })),
+  identity_file: Type.Optional(Type.String()),
+  jump: Type.Optional(Type.String()),
+  options: Type.Optional(Type.Record(Type.String(), Type.String())),
+});
+
+const SshProfileParams = Type.Object({
+  action: Type.Union([
+    Type.Literal("list"),
+    Type.Literal("use"),
+    Type.Literal("status"),
+    Type.Literal("clear"),
+  ]),
+  host: Type.Optional(Type.String({ description: "SSH config Host alias or user@host. Required for use." })),
+  workdir: Type.Optional(Type.String({ description: "Default remote working directory." })),
+  env: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Default remote environment variables." })),
+});
+
+export interface RegisterRemoteBashDependencies {
+  runner: RemoteBashDependencies["runner"];
+  controlPathRoot?: string;
+  getActiveProfile?: () => SshProfile | undefined;
+  muxRegistry?: SshMuxRegistry;
+  onResult?: (result: RemoteBashResult, params: { host?: string }, ctx: ExtensionContext) => void | Promise<void>;
+}
+
+export interface RegisterSshExtensionDependencies extends RegisterRemoteBashDependencies {
+  sshConfigPath?: string;
+  muxEntries?: SshMuxEntryMap;
+}
+
+export function registerRemoteBashTool(pi: ExtensionAPI, dependencies: RegisterRemoteBashDependencies): void {
+  pi.registerTool({
+    name: "remote_bash",
+    label: "Remote Bash",
+    description: `Run one short remote bash command synchronously over a reusable SSH ControlMaster. Pass an SSH Host alias or user@host, or omit host when an active SSH profile supplies it; optional workdir, env, timeout, and structured identity fields are supported. Required SSH safety options cannot be disabled. Returns remote output and exitCode without turning a non-zero remote exit into a tool failure. Output is truncated to the last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first), with full output saved locally. For long-running remote work, use bg_task_spawn (or bg_task_* lifecycle tools) with structured ssh instead. Pi's built-in bash remains local.`,
+    promptSnippet: "Run a short synchronous remote command through safe reusable SSH",
+    promptGuidelines: [
+      "Use remote_bash for short synchronous remote commands instead of writing ssh commands inside local bash.",
+      "Use bg_task_spawn with structured ssh for long-running or durable remote work instead of remote_bash.",
+    ],
+    parameters: RemoteBashParams,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const sessionScope = ctx.sessionManager.getSessionId();
+      const activeProfile = dependencies.getActiveProfile?.();
+      const result = await executeRemoteBash(params, {
+        runner: dependencies.runner,
+        sessionScope,
+        ...(dependencies.controlPathRoot ? { controlPathRoot: dependencies.controlPathRoot } : {}),
+        ...(activeProfile ? { activeProfile } : {}),
+        ...(dependencies.muxRegistry ? { muxRegistry: dependencies.muxRegistry } : {}),
+      }, signal);
+      await dependencies.onResult?.(result, params, ctx);
+      return {
+        content: [{ type: "text" as const, text: formatToolResult(result, params.timeout) }],
+        details: result,
+      };
+    },
+  });
+}
+
+export function registerSshExtension(pi: ExtensionAPI, dependencies: RegisterSshExtensionDependencies): void {
+  let activeProfile: SshProfile | undefined;
+  const muxRegistry = dependencies.muxRegistry ?? createSshMuxRegistry({
+    runner: dependencies.runner,
+    ...(dependencies.controlPathRoot ? { controlPathRoot: dependencies.controlPathRoot } : {}),
+    ...(dependencies.muxEntries ? { entries: dependencies.muxEntries } : {}),
+  });
+
+  registerRemoteBashTool(pi, {
+    ...dependencies,
+    muxRegistry,
+    getActiveProfile: () => activeProfile,
+    onResult: (result, params, ctx) => {
+      if (activeProfile && params.host === undefined) {
+        setFooter(ctx, activeProfile, result.mux.state);
+      }
+    },
+  });
+
+  const resolveMuxTarget = (params: {
+    host?: string;
+    user?: string;
+    port?: number;
+    identity_file?: string;
+    jump?: string;
+    options?: Record<string, string>;
+  }) => {
+    const host = params.host ?? activeProfile?.host;
+    if (!host) {
+      throw new Error("ssh_mux requires host (an SSH Host alias or user@host) or an active SSH profile");
+    }
+    const ssh = resolveRemoteBashConnection({
+      command: "true",
+      host,
+      ...(params.user !== undefined ? { user: params.user } : {}),
+      ...(params.port !== undefined ? { port: params.port } : {}),
+      ...(params.identity_file !== undefined ? { identity_file: params.identity_file } : {}),
+      ...(params.jump !== undefined ? { jump: params.jump } : {}),
+      ...(params.options !== undefined ? { options: params.options } : {}),
+    });
+    return resolveSshCommand({ command: "true", ssh });
+  };
+
+  const queryMux = async (profile: SshProfile, sessionScope: string) => {
+    try {
+      const status = await muxRegistry.statusTarget(resolveMuxTarget({ host: profile.host }), sessionScope);
+      return { state: status.state, target: status.target, detail: status.detail };
+    } catch (error) {
+      return {
+        state: "down" as const,
+        target: profile.host,
+        detail: error instanceof Error ? error.message : String(error),
+      };
+    }
+  };
+
+  const setFooter = (ctx: ExtensionContext, profile: SshProfile | undefined, muxState?: "up" | "down"): void => {
+    try {
+      ctx.ui.setStatus(STATUS_KEY, profile ? formatSshProfileChip(profile, muxState ?? "down") : undefined);
+    } catch {
+      // Footer status is best-effort in non-interactive and partial harness contexts.
+    }
+  };
+
+  const refreshFooter = async (ctx: ExtensionContext) => {
+    if (!activeProfile) {
+      setFooter(ctx, undefined);
+      return undefined;
+    }
+    const mux = await queryMux(activeProfile, ctx.sessionManager.getSessionId());
+    setFooter(ctx, activeProfile, mux.state);
+    return mux;
+  };
+
+  pi.registerTool({
+    name: "ssh_profile",
+    label: "SSH Profile",
+    description: "List SSH config Host aliases and manage the active session default host, workdir, and environment. Profile state is stored in the Pi session and survives /reload; it does not create a separate host inventory.",
+    promptSnippet: "List or manage the active SSH default profile",
+    parameters: SshProfileParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (params.action === "list") {
+        const aliases = listSshHostAliases(dependencies.sshConfigPath);
+        const details = { action: "list" as const, aliases, active: activeProfile ?? null };
+        return { content: [{ type: "text" as const, text: formatProfileList(aliases, activeProfile) }], details };
+      }
+      if (params.action === "use") {
+        const aliases = listSshHostAliases(dependencies.sshConfigPath);
+        activeProfile = createSshProfile(params, aliases, dependencies.sshConfigPath);
+        pi.appendEntry(SSH_PROFILE_ENTRY_TYPE, profileStateEntry(activeProfile));
+        const mux = await refreshFooter(ctx);
+        const details = { action: "use" as const, active: activeProfile, mux };
+        return { content: [{ type: "text" as const, text: `Active SSH profile: ${formatSshProfileChip(activeProfile, mux?.state ?? "down")}` }], details };
+      }
+      if (params.action === "clear") {
+        activeProfile = undefined;
+        pi.appendEntry(SSH_PROFILE_ENTRY_TYPE, profileStateEntry(undefined));
+        setFooter(ctx, undefined);
+        const details = { action: "clear" as const, active: null };
+        return { content: [{ type: "text" as const, text: "Active SSH profile cleared." }], details };
+      }
+
+      const mux = activeProfile ? await refreshFooter(ctx) : undefined;
+      const details = { action: "status" as const, active: activeProfile ?? null, ...(mux ? { mux } : {}) };
+      return {
+        content: [{
+          type: "text" as const,
+          text: activeProfile
+            ? formatSshProfileChip(activeProfile, mux?.state ?? "down")
+            : "No active SSH profile.",
+        }],
+        details,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "ssh_mux",
+    label: "SSH Mux",
+    description: "Inspect or stop the SSH ControlMaster for one target, the active profile, or all masters observed in this Pi process for the current session.",
+    promptSnippet: "Inspect or stop reusable SSH ControlMaster connections",
+    parameters: SshMuxParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const identityFields = [params.host, params.user, params.port, params.identity_file, params.jump, params.options];
+      if (params.all && identityFields.some((value) => value !== undefined)) {
+        throw new Error("ssh_mux all cannot be combined with target identity fields");
+      }
+      const sessionScope = ctx.sessionManager.getSessionId();
+      if (params.all) {
+        const results = params.action === "status"
+          ? await muxRegistry.statusAll(sessionScope)
+          : await muxRegistry.stopAll(sessionScope);
+        const masters = results.map(muxResultDetails);
+        if (activeProfile) {
+          const activeTarget = resolveMuxTarget({ host: activeProfile.host }).identity.target;
+          const activeMux = masters.find((master) => master.target === activeTarget);
+          if (params.action === "stop") setFooter(ctx, activeProfile, "down");
+          else if (activeMux) setFooter(ctx, activeProfile, activeMux.state === "up" ? "up" : "down");
+        }
+        const details = { action: params.action, scope: "all" as const, masters };
+        return { content: [{ type: "text" as const, text: formatMuxResults(masters) }], details };
+      }
+
+      const resolved = resolveMuxTarget(params);
+      const result = params.action === "status"
+        ? await muxRegistry.statusTarget(resolved, sessionScope)
+        : await muxRegistry.stopTarget(resolved, sessionScope);
+      const masters = [muxResultDetails(result)];
+      if (activeProfile) {
+        const activeTarget = resolveMuxTarget({ host: activeProfile.host }).identity.target;
+        if (resolved.identity.target === activeTarget) {
+          setFooter(ctx, activeProfile, result.state === "up" ? "up" : "down");
+        }
+      }
+      const details = { action: params.action, scope: "target" as const, masters };
+      return { content: [{ type: "text" as const, text: formatMuxResults(masters) }], details };
+    },
+  });
+
+  const restore = async (ctx: ExtensionContext): Promise<void> => {
+    activeProfile = restoreSshProfile(ctx.sessionManager.getBranch());
+    await refreshFooter(ctx);
+  };
+  pi.on("session_start", async (_event, ctx) => restore(ctx));
+  pi.on("session_tree", async (_event, ctx) => restore(ctx));
+  pi.on("session_shutdown", async (_event, ctx) => setFooter(ctx, undefined));
+}
+
+export default function sshExtension(pi: ExtensionAPI): void {
+  registerSshExtension(pi, { runner: createProcessRemoteRunner() });
+}
+
+function formatProfileList(aliases: string[], active: SshProfile | undefined): string {
+  const lines = aliases.length > 0
+    ? aliases.map((alias) => `${active?.host === alias ? "*" : "-"} ${alias}`)
+    : ["(no literal Host aliases found in ~/.ssh/config)"];
+  if (active && !aliases.includes(active.host)) lines.unshift(`* ${active.host} (active user@host profile)`);
+  return lines.join("\n");
+}
+
+function muxResultDetails(result: { state: string; target: string; controlPath: string; detail: string }) {
+  return {
+    target: result.target,
+    state: result.state,
+    controlPath: result.controlPath,
+    detail: result.detail,
+  };
+}
+
+function formatMuxResults(results: Array<{ target: string; state: string; detail: string }>): string {
+  if (results.length === 0) return "No SSH ControlMasters are known for this session.";
+  return results.map((result) => `${result.target}: mux ${result.state} - ${result.detail}`).join("\n");
+}
+
+function formatToolResult(result: RemoteBashResult, timeoutSeconds?: number): string {
+  let text = result.output || "(no output)";
+  if (result.truncated && result.truncation && result.fullOutputPath) {
+    const startLine = result.truncation.totalLines - result.truncation.outputLines + 1;
+    const endLine = result.truncation.totalLines;
+    text += result.truncation.truncatedBy === "lines"
+      ? `\n\n[Showing lines ${startLine}-${endLine} of ${result.truncation.totalLines}. Full output: ${result.fullOutputPath}]`
+      : `\n\n[Showing lines ${startLine}-${endLine} of ${result.truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${result.fullOutputPath}]`;
+  }
+  if (result.timedOut) return `${text}\n\nCommand timed out after ${timeoutSeconds} seconds`;
+  if (result.cancelled) return `${text}\n\nCommand cancelled`;
+  if (result.exitCode !== 0 && result.exitCode !== undefined) {
+    return `${text}\n\nCommand exited with code ${result.exitCode}`;
+  }
+  return text;
+}

package/node_modules/pi-better-ssh/src/mux-registry.ts

@@ -0,0 +1,86 @@
+import { createSshMuxController } from "./shared-ssh-core/index.js";
+import type {
+  RemoteRunner,
+  ResolvedSshCommand,
+  SshMuxCleanupResult,
+  SshMuxController,
+  SshMuxStatus,
+} from "./shared-ssh-core/index.js";
+
+const GLOBAL_MUX_ENTRIES = Symbol.for("pi-better-ssh.mux-entries.v1");
+
+export interface KnownSshMuxEntry {
+  sessionScope: string;
+  resolved: ResolvedSshCommand;
+}
+
+export type SshMuxEntryMap = Map<string, KnownSshMuxEntry>;
+
+export interface SshMuxRegistry {
+  controllerFor(resolved: ResolvedSshCommand, sessionScope: string): SshMuxController;
+  statusTarget(resolved: ResolvedSshCommand, sessionScope: string): Promise<SshMuxStatus>;
+  stopTarget(resolved: ResolvedSshCommand, sessionScope: string): Promise<SshMuxCleanupResult>;
+  statusAll(sessionScope: string): Promise<SshMuxStatus[]>;
+  stopAll(sessionScope: string): Promise<SshMuxCleanupResult[]>;
+}
+
+export function createSshMuxRegistry(options: {
+  runner: RemoteRunner;
+  controlPathRoot?: string;
+  entries?: SshMuxEntryMap;
+}): SshMuxRegistry {
+  const entries = options.entries ?? processMuxEntries();
+
+  const makeController = (resolved: ResolvedSshCommand, sessionScope: string): SshMuxController =>
+    createSshMuxController({
+      ...resolved,
+      runner: options.runner,
+      sessionScope,
+      ...(options.controlPathRoot ? { controlPathRoot: options.controlPathRoot } : {}),
+    });
+
+  const controllerFor = (resolved: ResolvedSshCommand, sessionScope: string): SshMuxController => {
+    const controller = makeController(resolved, sessionScope);
+    entries.set(controller.controlPath, { sessionScope, resolved });
+    return controller;
+  };
+
+  const knownForSession = (sessionScope: string): Array<[string, KnownSshMuxEntry]> =>
+    [...entries].filter(([, entry]) => entry.sessionScope === sessionScope);
+
+  return {
+    controllerFor,
+    statusTarget: (resolved, sessionScope) => controllerFor(resolved, sessionScope).status(),
+    stopTarget: async (resolved, sessionScope) => {
+      const controller = controllerFor(resolved, sessionScope);
+      try {
+        return await controller.cleanup();
+      } finally {
+        entries.delete(controller.controlPath);
+      }
+    },
+    statusAll: async (sessionScope) => {
+      const statuses: SshMuxStatus[] = [];
+      for (const [, entry] of knownForSession(sessionScope)) {
+        statuses.push(await makeController(entry.resolved, sessionScope).status());
+      }
+      return statuses;
+    },
+    stopAll: async (sessionScope) => {
+      const results: SshMuxCleanupResult[] = [];
+      for (const [controlPath, entry] of knownForSession(sessionScope)) {
+        try {
+          results.push(await makeController(entry.resolved, sessionScope).cleanup());
+        } finally {
+          entries.delete(controlPath);
+        }
+      }
+      return results;
+    },
+  };
+}
+
+function processMuxEntries(): SshMuxEntryMap {
+  const globalState = globalThis as typeof globalThis & { [GLOBAL_MUX_ENTRIES]?: SshMuxEntryMap };
+  return globalState[GLOBAL_MUX_ENTRIES] ??= new Map();
+}