pi-better-harness 0.3.1 → 0.3.3

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

@@ -162,6 +162,7 @@ function formatSnapshot(snapshot: ActivitySnapshot): string {
 
 export default function (pi: ExtensionAPI): void {
   const providers = new Map<string, BackgroundActivityProvider>();
+  const providerUnsubscribers = new Map<string, () => void>();
   providers.set("subagents", {
     id: "subagents",
     label: "Subagents",
@@ -172,6 +173,7 @@ export default function (pi: ExtensionAPI): void {
   let foregroundRunning = false;
   let pollTimer: ReturnType<typeof setInterval> | undefined;
   let collecting = false;
+  let collectionPending = false;
   let latestSnapshot: ActivitySnapshot | null = null;
   let backgroundDrainTracker: BackgroundDrainTracker | null = null;
   let lastWakeSignature = "";
@@ -230,6 +232,7 @@ export default function (pi: ExtensionAPI): void {
     continuationQueuedFor = null;
     backgroundDrainTracker = null;
     clearIdleContinuation();
+    syncPollingState();
     // Force a full redraw when the dock height changes (absent ↔ visible clock).
     refreshGoalWidget?.(!wasVisible || !isGoalClockVisible(goal));
   };
@@ -241,6 +244,7 @@ export default function (pi: ExtensionAPI): void {
     continuationQueuedFor = null;
     backgroundDrainTracker = null;
     clearIdleContinuation();
+    syncPollingState();
     refreshGoalWidget?.(wasVisible);
   };
 
@@ -409,12 +413,22 @@ export default function (pi: ExtensionAPI): void {
 
   const collectIfPossible = (): void => {
     const ctx = currentCtx;
-    if (!ctx || collecting) {
+    if (!ctx) {
+      return;
+    }
+    if (collecting) {
+      collectionPending = true;
       return;
     }
     collecting = true;
     void publishSnapshot(ctx).finally(() => {
       collecting = false;
+      if (collectionPending) {
+        collectionPending = false;
+        collectIfPossible();
+      } else {
+        syncPollingState();
+      }
     });
   };
 
@@ -424,7 +438,6 @@ export default function (pi: ExtensionAPI): void {
     }
     pollTimer = setInterval(collectIfPossible, POLL_INTERVAL_MS);
     pollTimer.unref?.();
-    collectIfPossible();
   };
 
   const stopPolling = (): void => {
@@ -435,6 +448,16 @@ export default function (pi: ExtensionAPI): void {
     pollTimer = undefined;
   };
 
+  const syncPollingState = (): void => {
+    const ctx = currentCtx;
+    const goal = ctx ? currentGoalSnapshot(ctx) : null;
+    if (ctx && (isPokeable(goal) || latestSnapshot?.backgroundRunning === true)) {
+      startPolling();
+    } else {
+      stopPolling();
+    }
+  };
+
   const installGoalWidget = (ctx: ExtensionContext): void => {
     if (!ctx.hasUI) {
       return;
@@ -494,8 +517,14 @@ export default function (pi: ExtensionAPI): void {
     if (!candidate || typeof candidate.id !== "string" || typeof candidate.getActivity !== "function") {
       return;
     }
-    providers.set(candidate.id, candidate as BackgroundActivityProvider);
-    collectIfPossible();
+    const accepted = candidate as BackgroundActivityProvider;
+    providerUnsubscribers.get(accepted.id)?.();
+    providerUnsubscribers.delete(accepted.id);
+    providers.set(accepted.id, accepted);
+    if (typeof accepted.onActivityChanged === "function") {
+      providerUnsubscribers.set(accepted.id, accepted.onActivityChanged(collectIfPossible));
+    }
+    if (latestSnapshot) collectIfPossible();
   });
 
   pi.registerCommand("goal", {
@@ -661,7 +690,8 @@ export default function (pi: ExtensionAPI): void {
     foregroundRunning = !ctx.isIdle();
     pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
     installGoalWidget(ctx);
-    startPolling();
+    latestSnapshot = await publishSnapshot(ctx);
+    syncPollingState();
   });
 
   pi.on("input", async (event, ctx) => {
@@ -762,6 +792,8 @@ export default function (pi: ExtensionAPI): void {
     foregroundRunning = false;
     clearIdleContinuation();
     currentCtx = undefined;
+    latestSnapshot = null;
+    collectionPending = false;
     try {
       ctx.ui.setStatus(EXTENSION_NAME, undefined);
       ctx.ui.setWidget(EXTENSION_NAME, undefined);

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

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -82,6 +82,46 @@ export function readSubagentMetas(baseDir = defaultSubagentBaseDir()): SubagentR
   return metas.sort((left, right) => right.startedAt - left.startedAt);
 }
 
+export function readParentSubagentMetas(
+  baseDir = defaultSubagentBaseDir(),
+  parentPid = process.pid,
+): SubagentRunMeta[] {
+  const directory = join(baseDir, "by-parent", String(parentPid));
+  ensureParentIndex(baseDir, directory, parentPid);
+  let ids: string[];
+  try {
+    ids = readdirSync(directory).filter((id) => id !== ".initialized");
+  } catch {
+    return [];
+  }
+  return ids
+    .map((id) => readSubagentMeta(baseDir, id))
+    .filter((meta): meta is SubagentRunMeta => meta !== undefined && meta.spawnPid === parentPid)
+    .sort((left, right) => right.startedAt - left.startedAt);
+}
+
+function readSubagentMeta(baseDir: string, id: string): SubagentRunMeta | undefined {
+  try {
+    const meta = JSON.parse(readFileSync(join(baseDir, "runs", id, "meta.json"), "utf8")) as SubagentRunMeta;
+    return typeof meta.id === "string" && typeof meta.status === "string" ? meta : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function ensureParentIndex(baseDir: string, directory: string, parentPid: number): void {
+  try {
+    readFileSync(join(directory, ".initialized"));
+    return;
+  } catch {
+    // Existing registries are backfilled once for this parent process.
+  }
+  const owned = readSubagentMetas(baseDir).filter((meta) => meta.spawnPid === parentPid);
+  mkdirSync(directory, { recursive: true });
+  for (const meta of owned) writeFileSync(join(directory, meta.id), "");
+  writeFileSync(join(directory, ".initialized"), "1");
+}
+
 export function subagentStatusToItem(
   meta: SubagentRunMeta,
   status: SubagentEffectiveStatus,
@@ -122,9 +162,7 @@ export function collectSubagentActivity(
 ): BackgroundProviderSnapshot {
   const parentPid = options.parentPid ?? process.pid;
   const processExists = options.processExists ?? defaultProcessExists;
-  const metas = readSubagentMetas(options.baseDir).filter((meta) =>
-    isCurrentParentSubagent(meta, parentPid),
-  );
+  const metas = readParentSubagentMetas(options.baseDir, parentPid);
 
   return {
     providerId: "subagents",

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

@@ -47,6 +47,7 @@ export interface BackgroundActivityProvider {
   id: string;
   label?: string;
   getActivity(ctx: ExtensionContext): BackgroundProviderSnapshot | Promise<BackgroundProviderSnapshot>;
+  onActivityChanged?(notify: () => void): () => void;
 }
 
 export interface ActivitySnapshot {

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;
+}