pi-famulus 0.1.4 → 0.1.7

package/README.md

@@ -1,38 +1,163 @@
-# pi-famulus
+<div align="center">
+  <img src="https://raw.githubusercontent.com/Leechael/pi-famulus/main/assets/logo.png" alt="pi-famulus" width="120" />
+  <h1>pi-famulus</h1>
+  <p><b>Let your agent delegate, and keep working.</b></p>
+  <p>English · <a href="https://github.com/Leechael/pi-famulus/blob/main/README_CN.md">中文</a></p>
+  <p>Subagents and long-running bash for <a href="https://pi.dev">pi</a> and agents built on it. Results wake the agent when work finishes, so it never has to poll. One daemon owns every shell it starts.</p>
+  <p>
+    <a href="https://github.com/Leechael/pi-famulus/blob/main/docs/tools.md">Tools</a> ·
+    <a href="https://github.com/Leechael/pi-famulus/blob/main/docs/cli.md">CLI</a> ·
+    <a href="https://github.com/Leechael/pi-famulus/blob/main/docs/design.md">Architecture</a> ·
+    <a href="https://github.com/Leechael/pi-famulus/blob/main/eval/RESULTS.md">Eval results</a>
+  </p>
+  <a href="https://www.npmjs.com/package/pi-famulus"><img src="https://img.shields.io/npm/v/pi-famulus?style=flat-square" alt="npm"></a>
+  <a href="https://github.com/Leechael/pi-famulus/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Leechael/pi-famulus/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
+  <a href="https://github.com/Leechael/pi-famulus/stargazers"><img src="https://img.shields.io/github/stars/Leechael/pi-famulus?style=flat-square" alt="Stars"></a>
+  <a href="https://github.com/Leechael/pi-famulus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License"></a>
+  <a href="https://github.com/Leechael/pi-famulus/commits"><img src="https://img.shields.io/github/commit-activity/m/Leechael/pi-famulus?style=flat-square" alt="Commits"></a>
+  <a href="https://x.com/leechael"><img src="https://img.shields.io/badge/follow-leechael-red?style=flat-square&logo=x" alt="X"></a>
+</div>
 
-Subagent orchestration, auto-backgrounding bash, monitoring, and agent-to-agent communication for pi 1.0.0 or newer.
+<!-- TODO(visual): a full-width screenshot or GIF goes here. None exists yet. Candidate: a recording of `/tasks` and the fleet line while a test suite runs in the background and a subagent reports back. -->
 
-Workers inherit user/global and trusted-project pi configuration and resources, including codemode and MCP, then receive famulus communication tools. An explicit agent `tools` list remains an allowlist; omitting it inherits the user’s default tools. Parent-only CLI resource overrides are not copied.
+## Why
 
-After the first public release:
+A famulus is the assistant who runs a scholar's errands, as Wagner does for Faust. pi's core leaves subagents, background bash and monitoring to extensions on purpose ([design, section 1](https://github.com/Leechael/pi-famulus/blob/main/docs/design.md#1-background-and-goals)). pi-famulus adds them. It is for people who run pi, or an agent built on pi, on real projects and want to hand off slow or parallel work, such as a test suite, a build, a dev server or a code review, without stalling the conversation.
 
-```sh
+Three things go wrong when an agent has to wait:
+
+- **A foreground watch blocks the chat.** With pi-famulus, `bash` moves a command to the background after 20 seconds, and the turn goes on.
+- **A backgrounded command finishes silently.** With pi-famulus, the result is injected into the conversation when the command exits, so the model reacts instead of polling.
+- **A subagent reports "done" while its work still runs.** With pi-famulus, a subagent's `bash` cannot move to the background, and a subagent cannot start subagents or monitors. When it reports done, nothing it started through pi-famulus is still running, unless a command detached itself with `setsid` or left a process running with `&`.
+
+One machine-wide daemon (`pi-famulus`, written in Rust) starts every shell command and monitor, including the ones subagents run, and is their parent. If the daemon crashes or is killed, the process groups it started are stopped, except commands that moved into a new session with `setsid`. Subagents themselves run inside pi.
+
+pi-famulus is a pi extension, so it works wherever pi loads extensions: the pi TUI, RPC mode, and agents you build with the pi SDK. Outside the TUI there is no `/tasks` list and no fleet line, but results still wake the agent. Print mode (`pi -p`) exits when the first run ends, so results that arrive later are not seen.
+
+## Quick Start
+
+> **Before you install**: pi-famulus registers the tools `bash` (replacing the built-in), `subagent`, `monitor`, `agent_message`, `task_list`, `task_output` and `task_stop`, and the commands `/tasks`, `/famulus` and `/reply`. In pi 1.0.0, when two extensions register the same tool name, the extension loaded first keeps it, and the other one's tool is hidden.
+>
+> - `pi-subagents` also registers `subagent`. Do not install it alongside pi-famulus.
+> - `pi-background-tasks` also registers `/tasks`, so pi lists both as `/tasks:1` and `/tasks:2`. It overlaps with pi-famulus in purpose. Choose one of the two.
+>
+> Details: [conflicts](https://github.com/Leechael/pi-famulus/blob/main/docs/development.md#conflicts-with-other-packages).
+
+```bash
 pi install npm:pi-famulus
 ```
 
-npm installs the matching native manager automatically through an exact-version optional dependency. No Rust compiler, postinstall download, or separate manager installation is needed. Keep optional dependencies enabled.
+Requires pi 1.0.0 or newer. Native daemon builds ship for Linux x64 and arm64, macOS x64 and arm64 (macOS 13+), and Windows x64 and arm64. The daemon ships as an exact-version optional dependency of the npm package, so keep optional dependencies enabled. No Rust compiler or extra download is needed.
+
+You do not write tool calls. After installing, ask the agent in plain language:
+
+```text
+Run the full test suite and tell me what fails.
+```
+
+`bash` waits 20 seconds. If the command is still running, it moves to the background and the turn continues. The result arrives in the conversation when the command exits.
+
+## Features
+
+- **Auto-backgrounding bash**: A command that runs longer than `foregroundBudgetMs` (20 seconds by default) moves to the background. Set `run_in_background` to start it there at once. Bare `sleep` is rejected.
+- **Wake on completion**: A finished command, a monitor event or a subagent result is injected into the conversation. The agent continues from it without polling.
+- **Subagents**: A call takes up to 10 subagents, which run 4 at a time by default, or a `chain` that runs in order. If the wait passes 45 seconds, the call returns and the run continues in the background. Each subagent reports back when it finishes.
+- **Clean finish**: A subagent's `bash` runs in the foreground until the command exits or times out, and subagents cannot start subagents or monitors. So a finished subagent leaves nothing it started through pi-famulus running, unless a command detached itself with `setsid` or left a process running with `&`.
+- **One daemon for every process**: The daemon is the parent of every shell and monitor task across your pi sessions. If it crashes or is killed with `kill -9`, each task's process group is stopped. Commands that move into a new session with `setsid` escape this.
+- **Shared capacity**: By default, at most 8 subagents run at once across all pi sessions on the machine (`pi-famulus config set max-agents <n>` changes it). The rest wait in a queue. Subagents labelled `work_kind: "test-suite"` or `"test"` are capped at 2 at a time; without a label, a subagent counts as `other`.
+- **Parent and subagent talk**: A subagent asks its parent a question with `contact_supervisor` and waits for the answer. You can answer it yourself with `/reply`. `agent_message` sends messages between parent and subagents.
+- **Inspectable**: `pi-famulus top`, `ls`, `show`, `agent` and `events` show what ran, why it ended, and why a notification did or did not arrive.
+- **Tested against real models**: Tool descriptions are graded on real-model runs. The latest matrix (2026-10-08; 12 xAI and OpenAI configurations, 10 scenarios, k=10) recorded 1198 passes and 2 failures, with 6 invalid or errored episodes excluded ([eval/RESULTS.md](https://github.com/Leechael/pi-famulus/blob/main/eval/RESULTS.md)). It predates a later wording change to the `subagent` and wake prompts ([PR #62](https://github.com/Leechael/pi-famulus/pull/62)), which has not been through the full matrix yet.
+
+## Usage Guide
+
+| Ask the agent | What happens |
+| :--- | :--- |
+| `Run the full test suite and tell me what fails.` | `bash` moves the run to the background after 20 seconds; the result arrives when it exits |
+| `Start the dev server and tell me if an error shows up in its output.` | `monitor` turns each output line into an event and wakes the agent when one arrives |
+| `Review these three modules in parallel with subagents.` | `subagent` runs the tasks in parallel; each subagent reports back when it finishes |
+| `Which models can subagents use?` | The agent calls `subagent({action: "models"})` and lists the choices |
+
+| In the pi TUI | Does |
+| :--- | :--- |
+| `/tasks` | Live list of shells, monitors and subagents; `ctrl+x` stops the selected item |
+| `/reply <child> <text>` | Answers a subagent's question without going through the model |
+| `/famulus` | Shows the `pi-famulus` binary path and the manager and extension versions |
+| Fleet line (the status line below the editor) | Shows the shells, monitors and subagents that are running |
+
+**Plan with your strongest model, implement with a cheap one.** Select your strongest model in pi, then save this as `~/.pi/agent/agents/worker.md`:
+
+```markdown
+---
+name: worker
+description: Implements one concrete task end to end
+model: haiku
+---
+Do the task you were given. Make the edits and run the tests that prove it works.
+Stay within the task's scope. Report what you changed and how you verified it.
+```
+
+Now ask:
+
+```text
+Plan the move from callbacks to async/await in src/api/. When the plan is settled,
+have subagents implement it one module at a time, then review what they return.
+```
+
+The session model writes the plan. `subagent` runs `worker` by default, and `worker` uses the model that `haiku` matches.
+
+- `model` is matched against the model ids and names that pi lets you use: your `enabledModels` or `--models` scope, or every available model when no scope is set. It must match exactly one. In an agent file, no match or several matches fall back to the parent model with a warning. On a single `subagent` call, they are an error, and the model is told the candidates.
+- Add a thinking level with a suffix, for example `model: haiku:high`.
+- A `worker.md` in `<project>/.pi/agents/` overrides the one in your home directory. Without any `worker.md`, subagents use the parent's model.
+- Built-in agents are `explorer` (read, grep, find, ls, bash) and `worker` (inherits your tools). Add your own as markdown files in the same folders.
+- `subagent({action: "steer" | "resume" | "extend" | "interrupt"})` redirects a running subagent, continues a finished one, gives it more time, or stops it.
+
+## Reliability
+
+pi-famulus starts and stops processes for you. This section states what it guarantees and where the guarantee ends.
+
+- On Unix, the daemon starts every shell and monitor task in a process group, and is its parent. When the daemon ends (`shutdown`, `kill -9`, panic), each group gets SIGTERM, then SIGKILL 2 seconds later. Windows tasks run in Job Objects and are terminated as a unit when stopped or when the daemon exits.
+- A command that moves a child into a new session (`setsid`) leaves the group and escapes this. A process left running with `&` keeps running until it exits or the daemon stops it.
+- Running work does not survive the last pi session closing. Five seconds after the last session disconnects, the daemon stops what is left and exits. Records, output and transcripts stay on disk for 24 hours.
+- A subagent still running when its 30-minute turn budget ends is not killed, unless you set `hardTimeoutMs`. The parent is told and chooses to extend, steer or interrupt it.
+- A subagent with no activity for 5 minutes is resumed once on the same session, with its transcript kept. The timer pauses while a tool runs or a `contact_supervisor` question waits for an answer. If the subagent stalls again, it is marked failed.
+- `monitor` batches output every 200 ms. It allows a burst of 10 events, then one event every 2 seconds. Batches over that limit are dropped. If at least half the batches are dropped over a 30-second window that holds at least 10 batches, the monitor stops and you are told.
+- On Linux and macOS, the daemon checks its own executable every 2 seconds. When the file is replaced, the running daemon re-executes itself with the same pid. `pi-famulus upgrade` does the same on demand. Running commands keep going and clients reconnect. The measured gap was 30 to 46 ms.
+
+## FAQ
+
+- **How is pi-famulus different from `pi-subagents` or `pi-background-tasks`?** They are alternatives, so choose one. Choose [`pi-subagents`](https://github.com/nicobailon/pi-subagents) for ready-made roles, saved workflows, `/council`, or background subagents in a detached process. Choose [`pi-background-tasks`](https://github.com/ismailsaleekh/pi-background-tasks) for named background shell jobs with output files, a read-only delegated agent, or its Fusion workflows. Choose pi-famulus for one daemon that owns every shell and monitor process across your pi sessions, a shared cap on concurrent subagents, and a CLI for inspecting past runs.
+- **Can I attach to a subagent like a tmux pane?** No. Subagents run inside the agent's process, so you cannot attach to one or take over its session. Steer, resume or interrupt it through the parent, answer its questions with `/reply`, and read what it did with `pi-famulus agent <id> -f`, `show <id>` and `top`.
+- **Does it work outside the pi TUI?** Yes. It loads wherever pi loads extensions, including RPC mode (`pi --mode rpc`) and agents built with the pi SDK. Print mode (`pi -p`) loads it too, but exits when the first run ends, so later results are not seen. In an SDK agent, load it through `DefaultResourceLoader` (for example with `additionalExtensionPaths`) and call `session.bindExtensions()`. The real-model eval drives pi in RPC mode.
+- **Can a subagent start its own subagents?** No. Nesting is limited to one level.
+- **What happens to background tasks when pi exits?** Five seconds after the last pi session closes, the daemon stops whatever is still running and exits. Read the records afterwards with `pi-famulus show <id>`.
+- **Does `/reload` stop running work?** No. Shells, monitors and subagents keep running, and their results still arrive. If the reload loads a different pi-famulus version, the old version's work is stopped first.
+- **Which binary and versions am I running?** Type `/famulus`. It shows the `pi-famulus` binary path and its version, the running manager's version and pid, and the extension version.
+- **Why does my pi bash command hang on long builds?** With pi-famulus, `bash` stops waiting after 20 seconds and moves the command to the background, so the turn continues. To change the limit, set `foregroundBudgetMs` in `~/.pi/agent/pi-famulus/config.json` ([configuration](https://github.com/Leechael/pi-famulus/blob/main/docs/configuration.md)).
+- **How do I see or stop running work?** Type `/tasks` in the pi TUI and press `ctrl+x` on an item. From a terminal, `pi-famulus ls` lists what is running.
+- **Does it work on Windows?** Yes, on x64 and arm64. The in-place upgrade, where the daemon re-executes itself, works only on Linux and macOS. On Windows, replace the binary and restart the daemon manually.
+- **What if a notification does not arrive?** Run `pi-famulus events --id <id>` to see whether the wake was emitted, delivered and injected. Run `pi-famulus doctor` to check daemon health.
 
-Supported native packages:
+## Docs
 
-| System | CPU | Package |
-|---|---|---|
-| Linux | x64 | `pi-famulus-linux-x64` |
-| Linux | arm64 | `pi-famulus-linux-arm64` |
-| macOS | Intel x64 | `pi-famulus-darwin-x64` |
-| macOS | Apple Silicon arm64 | `pi-famulus-darwin-arm64` |
+- [Tool reference](https://github.com/Leechael/pi-famulus/blob/main/docs/tools.md): parameters, agent files, terminal UI
+- [Configuration](https://github.com/Leechael/pi-famulus/blob/main/docs/configuration.md): `config.json`, timeouts, binary lookup, degraded mode
+- [CLI manual](https://github.com/Leechael/pi-famulus/blob/main/docs/cli.md): `doctor`, `ls`, `show`, `top`, `agent`, `stats`, `events`
+- [Architecture](https://github.com/Leechael/pi-famulus/blob/main/docs/design.md): daemon, lifeline, wakes, subagent runner
+- [Machine-wide capacity](https://github.com/Leechael/pi-famulus/blob/main/docs/global-capacity.md): `max-agents` and work-kind limits
+- [Eval results](https://github.com/Leechael/pi-famulus/blob/main/eval/RESULTS.md): real-model scenario matrix
+- [Development](https://github.com/Leechael/pi-famulus/blob/main/docs/development.md): building from source, tests, package conflicts
+- [Releasing](https://github.com/Leechael/pi-famulus/blob/main/docs/releasing.md)
 
-Linux binaries are statically linked with musl. macOS binaries target macOS 13 or newer; your Node/pi runtime's requirements also apply. Windows and other CPU architectures are not supported.
+## Background
 
-The npm package also exposes the `pi-famulus` CLI (`npx pi-famulus --help`). The extension's binary search order is:
+pi-famulus borrows several behaviors from other agents. From Claude Code it takes background-on-timeout instead of kill, completion injected into the conversation, a batched `monitor`, and bare-`sleep` interception. From grok-build it takes a 45-second wait budget for subagents and an admission queue that waits instead of rejecting. From lain it takes foreground-only bash for child agents. It also takes lessons from `pi-subagents` and `pi-intercom` about what to leave out. The research notes are in [design, section 1](https://github.com/Leechael/pi-famulus/blob/main/docs/design.md#1-background-and-goals).
 
-1. Executable `managerPath` from configuration.
-2. Executable `PI_FAMULUS_MANAGER_PATH` override.
-3. The matching-version installed native npm package.
-4. Executable `~/.pi/agent/pi-famulus/bin/pi-famulus` (or the equivalent beneath `PI_FAMULUS_HOME`).
-5. Executable `pi-famulus` on `PATH`.
+## Support
 
-Configuration and runtime state remain in `~/.pi/agent/pi-famulus`. Installing/updating the npm package does not move that state or copy a binary into the shared home. The npm CLI uses the package's native executable; use the extension configuration above when intentionally running a separately built manager.
+- If pi-famulus helped you, give it a star, or open an [issue](https://github.com/Leechael/pi-famulus/issues) or a pull request.
+- When you report a problem, include the output of `pi-famulus doctor` and `pi-famulus events --id <id>`.
 
-If optional dependencies were omitted, reinstall with them enabled. The CLI reports an actionable error; the extension can still discover an explicitly installed manager and otherwise enters degraded mode. An arbitrary different-version native npm package is never substituted.
+## License
 
-See the [project README](https://github.com/Leechael/pi-famulus#readme) for tools, settings, one-time migration, and source-build instructions; see the [CLI manual](https://github.com/Leechael/pi-famulus/blob/main/docs/cli.md) for operations.
+Released under the [MIT License](https://github.com/Leechael/pi-famulus/blob/main/LICENSE).

package/bin/pi-famulus.js

@@ -7,7 +7,7 @@ if (!binary) {
   const name = nativePackageName(process.platform, process.arch);
   console.error(name
     ? `pi-famulus: missing usable ${name}. Reinstall pi-famulus with optional dependencies enabled (npm install --include=optional pi-famulus).`
-    : `pi-famulus: unsupported ${process.platform}/${process.arch}; only Linux/macOS x64/arm64 are supported.`);
+    : `pi-famulus: unsupported ${process.platform}/${process.arch}; only Linux/macOS/Windows x64/arm64 are supported.`);
   process.exit(1);
 }
 const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });

package/package.json

@@ -1,9 +1,32 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.4",
-  "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
+  "version": "0.1.7",
+  "description": "Done means done: subagents and long-running background bash for Pi. One daemon owns every shell it starts and wakes the agent when work finishes. No polling.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "subagent",
+    "subagents",
+    "background",
+    "background-tasks",
+    "bash",
+    "daemon",
+    "multi-agent",
+    "monitor",
+    "agent-orchestration"
+  ],
+  "author": "Leechael Yim",
+  "homepage": "https://github.com/Leechael/pi-famulus",
+  "bugs": {
+    "url": "https://github.com/Leechael/pi-famulus/issues"
+  },
   "type": "module",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/Leechael/pi-famulus",
@@ -15,7 +38,8 @@
   },
   "os": [
     "linux",
-    "darwin"
+    "darwin",
+    "win32"
   ],
   "cpu": [
     "x64",
@@ -30,10 +54,12 @@
     "pi-famulus": "./bin/pi-famulus.js"
   },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.1.4",
-    "pi-famulus-linux-arm64": "0.1.4",
-    "pi-famulus-darwin-x64": "0.1.4",
-    "pi-famulus-darwin-arm64": "0.1.4"
+    "pi-famulus-linux-x64": "0.1.7",
+    "pi-famulus-linux-arm64": "0.1.7",
+    "pi-famulus-darwin-x64": "0.1.7",
+    "pi-famulus-darwin-arm64": "0.1.7",
+    "pi-famulus-win-x64": "0.1.7",
+    "pi-famulus-win-arm64": "0.1.7"
   },
   "pi": {
     "extensions": [
@@ -44,6 +70,7 @@
     "deps": "nub install --frozen-lockfile --node-linker hoisted",
     "prompts": "node scripts/build-prompts.ts",
     "test": "vitest run",
+    "test:compat": "vitest run tests/unit/impl-child-resource-isolation.test.ts tests/unit/impl-child-tools.test.ts tests/unit/impl-child-guidelines.test.ts tests/unit/impl-subagent-lifecycle.test.ts tests/unit/impl-steering-drain.test.ts tests/unit/impl-model-spec.test.ts tests/unit/impl-eval-fixes.test.ts tests/integration/behavior-guidelines.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

package/src/bash-override.ts

@@ -18,11 +18,12 @@ import { writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Type, type Static } from "typebox";
-import type {
-  AgentToolResult,
-  BashToolDetails,
-  ExtensionContext,
-  ToolDefinition,
+import {
+  getShellConfig,
+  type AgentToolResult,
+  type BashToolDetails,
+  type ExtensionContext,
+  type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { taskOutputPath, type FamulusConfig } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
@@ -166,15 +167,29 @@ async function executeLocal(
 ): Promise<AgentToolResult<FamulusBashDetails | undefined>> {
   const timeoutMs = resolveTimeoutMs(params.timeout);
   const startedAtMs = clock.now();
-  const shell = process.env.SHELL && process.env.SHELL.length > 0 ? process.env.SHELL : "/bin/bash";
+  // pi's own choice (Git Bash on Windows, /bin/bash on Unix): commands are
+  // written for pi's bash tool, not for whatever $SHELL is.
+  let shell: ReturnType<typeof getShellConfig>;
+  try {
+    shell = getShellConfig();
+  } catch (err) {
+    throw new Error(`Failed to start shell: ${(err as Error).message}`);
+  }
+  const viaStdin = shell.commandTransport === "stdin";
 
   const output = await new Promise<{ text: string; exitCode: number | null; signal: string | null; timedOut: boolean; aborted: boolean }>(
     (resolve, reject) => {
-      const child = spawn(shell, ["-c", params.command], {
+      const child = spawn(shell.shell, viaStdin ? shell.args : [...shell.args, params.command], {
         cwd: ctx.cwd,
         env: process.env,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: [viaStdin ? "pipe" : "ignore", "pipe", "pipe"],
+        windowsHide: true,
       });
+      if (viaStdin) {
+        // Swallow EPIPE if the shell exits before consuming stdin (pi's runner does the same).
+        child.stdin?.on("error", () => {});
+        child.stdin?.end(params.command);
+      }
       const chunks: Buffer[] = [];
       let settled = false;
       let timedOut = false;

package/src/config.ts

@@ -6,7 +6,7 @@
  */
 import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { delimiter, join } from "node:path";
+import { delimiter, join, win32 } from "node:path";
 import { nativePackageName, resolveNativeManagerPath } from "./native-manager.js";
 
 export interface FamulusConfig {
@@ -141,11 +141,43 @@ export function getFamulusHome(env: NodeJS.ProcessEnv = process.env): string {
   return join(homedir(), ".pi", "agent", "pi-famulus");
 }
 
+/** FNV-1a 64-bit over UTF-8 bytes — must match manager `sys::fnv1a64`. */
+export function fnv1a64(input: string): string {
+  let h = 0xcbf29ce484222325n;
+  for (const byte of Buffer.from(input, "utf8")) {
+    h ^= BigInt(byte);
+    h = (h * 0x0100000001b3n) & 0xffffffffffffffffn;
+  }
+  return h.toString(16);
+}
+
+/**
+ * Named-pipe identity of a home — must match manager `lifecycle::windows_pipe_ident`.
+ * The home is made absolute lexically (`path.win32.resolve` against `cwd`):
+ * `.` / `..` and repeated separators collapse, symlinks and junctions are
+ * not expanded. One spelling per directory (backslashes, no trailing
+ * separator except a drive root, lower case). The same relative home from
+ * two working directories must not share a pipe.
+ */
+export function windowsHomeKey(home: string, cwd: string = process.cwd()): string {
+  let s = win32.resolve(cwd, home);
+  while (s.length > 3 && s.endsWith("\\")) s = s.slice(0, -1);
+  return s.toLowerCase();
+}
+
+export function windowsPipeName(home: string, cwd: string = process.cwd()): string {
+  return `\\\\.\\pipe\\pi-famulus-${fnv1a64(windowsHomeKey(home, cwd))}`;
+}
+
 /** Well-known paths inside the pi-famulus home directory (design doc §3.1). */
-export function famulusPaths(home: string) {
+export function famulusPaths(home: string, platform: NodeJS.Platform = process.platform) {
+  const socket =
+    platform === "win32"
+      ? windowsPipeName(home)
+      : join(home, "manager.sock");
   return {
     home,
-    socket: join(home, "manager.sock"),
+    socket,
     pidFile: join(home, "manager.pid"),
     spawnLock: join(home, "manager.spawn.lock"),
     log: join(home, "manager.log"),
@@ -225,6 +257,9 @@ export function loadConfig(home: string = getFamulusHome()): FamulusConfig {
   return config;
 }
 
+/** File name of the manager in <home>/bin and on PATH: Windows only starts `.exe` images. */
+export const MANAGER_FILE_NAME = process.platform === "win32" ? "pi-famulus.exe" : "pi-famulus";
+
 /** Return why a candidate is unusable, or null for an executable regular file. */
 function managerCandidateProblem(path: string): string | null {
   try {
@@ -260,14 +295,15 @@ export function describeManagerSearch(
   tried.push(nativeName
     ? `npm ${nativeName}${native ? ` ${native}` : " (missing or unusable, ignored)"}`
     : `npm native manager (unsupported ${process.platform}/${process.arch})`);
-  tried.push(describeCandidate(join(home, "bin", "pi-famulus")));
+  tried.push(describeCandidate(join(home, "bin", MANAGER_FILE_NAME)));
   tried.push("pi-famulus on PATH");
   return tried.join("; ");
 }
 
 /**
  * Resolve an executable regular pi-famulus binary, or null if none is usable.
- * Priority: config.managerPath > PI_FAMULUS_MANAGER_PATH env > npm native package > <home>/bin/pi-famulus > PATH.
+ * Priority: config.managerPath > PI_FAMULUS_MANAGER_PATH env > npm native package > <home>/bin/pi-famulus > PATH
+ * (`pi-famulus.exe` on Windows).
  */
 export function resolveManagerPath(
   config: FamulusConfig,
@@ -279,11 +315,11 @@ export function resolveManagerPath(
   if (envPath && managerCandidateProblem(envPath) === null) return envPath;
   const native = resolveNativeManagerPath();
   if (native) return native;
-  const bundled = join(home, "bin", "pi-famulus");
+  const bundled = join(home, "bin", MANAGER_FILE_NAME);
   if (managerCandidateProblem(bundled) === null) return bundled;
   for (const dir of (env.PATH ?? "").split(delimiter)) {
     if (!dir) continue;
-    const candidate = join(dir, "pi-famulus");
+    const candidate = join(dir, MANAGER_FILE_NAME);
     if (managerCandidateProblem(candidate) === null) return candidate;
   }
   return null;

package/src/index.ts

@@ -25,7 +25,7 @@ import { createAgentMessageTool, createContactSupervisorTool } from "./comms/too
 import { registerReplyCommand } from "./comms/reply-command";
 import { describeManagerSearch, getFamulusHome, loadConfig, resolveManagerPath, resolveSubagentConfig } from "./config";
 import type { TaskExitInfo } from "./format";
-import { ManagerClient, type ManagerEvent, type TaskRecord } from "./manager-client";
+import { EXTENSION_VERSION, ManagerClient, type ManagerEvent, type TaskRecord } from "./manager-client";
 import { createMonitorTool, exitEventFromRecord, MonitorRegistry } from "./monitor";
 import { admitAgentChild, reregisterAgentLeases } from "./subagent/admission";
 import { NotifyCenter } from "./notify";
@@ -48,6 +48,8 @@ import { SubagentRegistry } from "./subagent/registry";
 import { InProcessRunner } from "./subagent/runner";
 import { createSubagentTool } from "./subagent/tool";
 import { createTaskListTool, createTaskOutputTool, createTaskStopTool } from "./task-tools";
+import { createPiBinding, parkRuntime, takeParkedRuntime } from "./reload-handoff";
+import { registerFamulusCommand } from "./tui/famulus-command";
 import { registerFamulusMessageRenderers } from "./tui/message-renderers";
 import { registerTasksCommand } from "./tui/tasks-command";
 import { stderrPathFor } from "./tui/task-output-paths";
@@ -69,8 +71,31 @@ function toExitStatus(event: ManagerEvent): TaskExitInfo["status"] {
   return "failed";
 }
 
+interface FamulusRuntime {
+  attach(pi: ExtensionAPI): void;
+}
+
 export default function (pi: ExtensionAPI): void {
   if (isFamulusChildSession(pi)) return;
+  // A /reload parked the previous instance's runtime: adopt it so its shells,
+  // monitors and subagents keep running (see reload-handoff.ts). Another
+  // version's runtime is torn down instead; its code may not match ours.
+  const parked = takeParkedRuntime<FamulusRuntime>();
+  if (parked?.version === EXTENSION_VERSION) {
+    parked.runtime.attach(pi);
+    return;
+  }
+  const retiring = parked?.dispose().catch(() => {});
+  createFamulusRuntime(retiring).attach(pi);
+}
+
+/**
+ * Everything one pi session owns. It registers on a PiBinding rather than on
+ * pi directly, so a /reload can re-attach it to the next extension instance.
+ */
+function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
+  const binding = createPiBinding();
+  const pi = binding.api;
   registerBehaviorGuidelines(pi);
   const home = getFamulusHome();
   const config = loadConfig(home);
@@ -366,6 +391,12 @@ export default function (pi: ExtensionAPI): void {
     clock,
     syncWithManager: deps.syncWithManager,
   });
+  registerFamulusCommand(pi, {
+    extensionVersion: EXTENSION_VERSION,
+    managerPath,
+    describeSearch: () => describeManagerSearch(config, home),
+    getClient: () => client,
+  });
   monitorRegistry.onChange(() => {
     for (const mon of monitorRegistry.listActive()) {
       const existing = workIndex.get(mon.taskId);
@@ -432,8 +463,37 @@ export default function (pi: ExtensionAPI): void {
   // each child session via customTools, see below).
   pi.registerTool(createAgentMessageTool(comms, { kind: "parent" }, commsHost, clock));
 
-  pi.on("session_start", async (_event, startCtx) => {
+  /** Session whose runtime a /reload parked; the reloaded instance's session_start resumes it. */
+  let parkedSessionId: string | null = null;
+  const startFleetWidget = (startCtx: ExtensionContext) => {
+    if (!startCtx.hasUI) return;
+    fleetWidget = new FleetWidget({
+      index: workIndex,
+      getUi: () => (ctx?.hasUI ? (ctx.ui as never) : null),
+      clock,
+    });
+    fleetWidget.start();
+  };
+
+  pi.on("session_start", async (event, startCtx) => {
+    if (parkedSessionId !== null) {
+      const resumed = event.reason === "reload" && startCtx.sessionManager.getSessionId() === parkedSessionId;
+      parkedSessionId = null;
+      if (resumed) {
+        // Same session after /reload: the client, registry and monitors kept
+        // running; only the context and the UI belong to the new instance.
+        ctx = startCtx;
+        binding.ready();
+        startFleetWidget(startCtx);
+        void syncWithManager();
+        return;
+      }
+      binding.discardQueued();
+      await teardown();
+    }
+    await retiring;
     ctx = startCtx;
+    binding.ready();
     notifyCenter?.dispose();
     notifyCenter = new NotifyCenter({
       sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
@@ -586,11 +646,15 @@ export default function (pi: ExtensionAPI): void {
         return tools;
       },
     });
+    // The registry outlives startCtx across a /reload, which leaves startCtx
+    // stale; its closures keep plain values instead.
+    const sessionId = startCtx.sessionManager.getSessionId();
+    const sessionCwd = startCtx.cwd;
     const transcripts = new TranscriptWriter(home, clock);
     const syncTranscript = (childId: string): string | undefined => {
       const handle = registry.handle(childId);
       if (!handle) return undefined;
-      return transcripts.sync(startCtx.sessionManager.getSessionId(), childId, handle.conversation());
+      return transcripts.sync(sessionId, childId, handle.conversation());
     };
     const runner = new InProcessRunner({
       createSession,
@@ -657,7 +721,7 @@ export default function (pi: ExtensionAPI): void {
     registry.setRunner(runner);
     subagentRegistry = registry;
     // Persist child records so `pi-famulus ls` / task_list can see in-process agents.
-    const sessionIdForAgents = () => startCtx.sessionManager.getSessionId();
+    const sessionIdForAgents = () => sessionId;
     const previousAgentStatus = new Map<string, string>();
     registry.onTransition((run) => {
       const sid = sessionIdForAgents();
@@ -743,7 +807,7 @@ export default function (pi: ExtensionAPI): void {
           workKind: c.workKind ?? "other",
           ...(c.queueMs !== undefined ? { queueMs: c.queueMs } : {}),
           ...(c.model !== undefined ? { model: c.model } : {}),
-          cwd: startCtx.cwd,
+          cwd: sessionCwd,
           ...(c.prompt !== undefined ? { prompt: c.prompt } : {}),
           ...(c.preamble !== undefined ? { preamble: c.preamble } : {}),
           ...(c.result?.text ? { text: c.result.text } : {}),
@@ -751,14 +815,7 @@ export default function (pi: ExtensionAPI): void {
         });
       }
     });
-    if (startCtx.hasUI) {
-      fleetWidget = new FleetWidget({
-        index: workIndex,
-        getUi: () => (ctx?.hasUI ? (ctx.ui as never) : null),
-        clock,
-      });
-      fleetWidget.start();
-    }
+    startFleetWidget(startCtx);
 
     // Connect in the background: a cold manager spawn must not stall the
     // first prompt. Tools call ensureAvailable() lazily before use.
@@ -770,11 +827,13 @@ export default function (pi: ExtensionAPI): void {
           if (c.protocolLevel() >= 4) void reconcileAgentLeases(c).catch(() => {});
           return;
         }
-        if (startCtx.hasUI) {
+        // A /reload may have replaced startCtx by now; report to the live one.
+        const current = ctx;
+        if (current?.hasUI) {
           const detail = c.lastError();
           const reason = detail ? ` (${detail})` : "";
           const searched = managerPath ? `using ${managerPath}` : `looked in: ${describeManagerSearch(config, home)}`;
-          startCtx.ui.notify(
+          current.ui.notify(
             `pi-famulus unavailable${reason}; ${searched}. ` +
               "Bash runs locally without auto-backgrounding, task_*/monitor are disabled, " +
               "and subagents cannot run bash. Install it or set PI_FAMULUS_MANAGER_PATH (see README Install).",
@@ -785,7 +844,7 @@ export default function (pi: ExtensionAPI): void {
       .catch(() => {});
   });
 
-  pi.on("session_shutdown", async () => {
+  const teardown = async (): Promise<void> => {
     exitWatchdog.dispose();
     fleetWidget?.dispose();
     fleetWidget = null;
@@ -807,6 +866,22 @@ export default function (pi: ExtensionAPI): void {
       }
     }
     ctx = null;
+  };
+  const runtime: FamulusRuntime = { attach: (host) => binding.attach(host) };
+
+  pi.on("session_shutdown", async (event) => {
+    if (event.reason === "reload" && ctx) {
+      // Keep the session's shells, monitors and subagents running; the
+      // reloaded instance adopts this runtime.
+      parkedSessionId = ctx.sessionManager.getSessionId();
+      fleetWidget?.dispose();
+      fleetWidget = null;
+      ctx = null;
+      binding.detach();
+      parkRuntime({ version: EXTENSION_VERSION, runtime, dispose: teardown });
+      return;
+    }
+    await teardown();
   });
 
   pi.on("agent_settled", async () => {
@@ -822,4 +897,6 @@ export default function (pi: ExtensionAPI): void {
     });
     return message ? { message } : undefined;
   });
+
+  return runtime;
 }

package/src/manager-client.ts

@@ -5,7 +5,7 @@
  *   lifetime-lock holder cleans up stale socket/pid files.
  * - Request/response multiplexing over a single long-lived connection.
  * - Server events dispatched to registered handlers.
- * - On unexpected disconnect: immediate then exponential-backoff reconnect for 22s,
+ * - On unexpected disconnect: immediate then exponential-backoff reconnect for 27s,
  *   re-hello after reconnect. If all attempts fail the client is marked unavailable
  *   and callers are expected to degrade (bash falls back to local execution).
  */
@@ -18,7 +18,8 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.1.4";
+const EXTENSION_VERSION = "0.1.7";
+export { EXTENSION_VERSION };
 // 5: speaks per-kind agent admission and queued acquire.
 const PROTOCOL = 5;
 const HELLO_TIMEOUT_MS = 5000;
@@ -281,6 +282,7 @@ export class ManagerClient {
   private eventHandlers = new Set<EventHandler>();
   private reconnectHandlers = new Set<() => void>();
   private protocolLevel_ = 0;
+  private daemonInfo: { version: string; pid: number } | null = null;
   private state: ClientState = "disconnected";
   private intentionalClose = false;
   private rebound = false;
@@ -313,6 +315,11 @@ export class ManagerClient {
     return this.protocolLevel_;
   }
 
+  /** Version and pid the connected daemon reported on hello; null before the first hello. */
+  managerInfo(): { version: string; pid: number } | null {
+    return this.daemonInfo;
+  }
+
   /** Last connect/reconnect failure reason (empty when never failed / currently connected). */
   lastError(): string {
     return this.lastFailureMessage;
@@ -631,7 +638,8 @@ export class ManagerClient {
     const deadline = this.now() + timeoutMs;
     for (;;) {
       this.checkStartupOpen();
-      if (existsSync(socketPath)) {
+      // A named pipe is not a file: existsSync does not see it, connecting does.
+      if (process.platform === "win32" || existsSync(socketPath)) {
         const ok = await this.openSocket(socketPath, Math.min(SOCKET_READY_POLL_MS, Math.max(0, deadline - this.now())))
           .then((probe) => { probe.destroy(); return true; }, () => false);
         if (ok) return;
@@ -791,7 +799,10 @@ export class ManagerClient {
     }
     if (this.helloWaiter && typeof msg.ok === "boolean") {
       // Unnamed response: correlate by order with the outstanding hello.
-      if (msg.ok === true) this.helloWaiter.resolve();
+      if (msg.ok === true) {
+        this.recordDaemonInfo(msg);
+        this.helloWaiter.resolve();
+      }
       else this.helloWaiter.reject(errorFromResponse(msg));
       this.helloWaiter = null;
       return;
@@ -799,6 +810,13 @@ export class ManagerClient {
     this.log(`unmatched message: ${JSON.stringify(msg).slice(0, 200)}`);
   }
 
+  private recordDaemonInfo(hello: Record<string, unknown>): void {
+    this.daemonInfo = {
+      version: typeof hello.version === "string" ? hello.version : "unknown",
+      pid: typeof hello.pid === "number" ? hello.pid : 0,
+    };
+  }
+
   private settle(id: string, msg: Record<string, unknown>): void {
     const entry = this.pending.get(id);
     if (!entry) return;
@@ -810,6 +828,7 @@ export class ManagerClient {
       if (entry.message.type === "hello") {
         const serverMaximum = typeof msg.protocol === "number" ? msg.protocol : 0;
         this.protocolLevel_ = Math.min(PROTOCOL, serverMaximum);
+        this.recordDaemonInfo(msg);
       }
       entry.resolve(msg);
     } else {

package/src/native-manager.js

@@ -14,10 +14,13 @@ const resolutionErrorCodes = new Set([
 const packageVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const resolveInstalled = createRequire(import.meta.url).resolve;
 
-/** The four native optional packages are selected by npm's os/cpu constraints. */
+/** The native optional packages are selected by npm's os/cpu constraints. */
 export function nativePackageName(platform, arch) {
-  if (!["linux", "darwin"].includes(platform) || !["x64", "arm64"].includes(arch)) return null;
-  return `pi-famulus-${platform}-${arch}`;
+  if (!["linux", "darwin", "win32"].includes(platform) || !["x64", "arm64"].includes(arch)) return null;
+  // npm package names use `win` (not `win32`) after unscoped `*-win32-*` names
+  // were blocked by registry spam detection on first publish.
+  const packageOs = platform === "win32" ? "win" : platform;
+  return `pi-famulus-${packageOs}-${arch}`;
 }
 
 /** Resolve the exact-version optional package without loading native executable bytes. */

package/src/reload-handoff.ts

@@ -0,0 +1,137 @@
+/**
+ * /reload keeps background work alive.
+ *
+ * pi's /reload emits session_shutdown(reason "reload") on the old extension
+ * instance, re-imports every extension (fresh module scope), then emits
+ * session_start(reason "reload") on the new instances. Shells, monitors and
+ * subagents belong to the pi session, not to one module instance, so the old
+ * instance parks its runtime here instead of tearing it down, and the new
+ * instance adopts it.
+ *
+ * The runtime registers its tools, commands and handlers on a PiBinding: a
+ * stand-in ExtensionAPI that records registrations and replays them on every
+ * pi it is attached to. Other calls go to the attached pi; sendMessage is
+ * queued while no live pi can take it (between the old instance going stale
+ * and the new one's session_start).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { realClock, type Clock } from "./clock";
+
+const HANDOFF_KEY = Symbol.for("pi-famulus.reload-handoff");
+
+/** A parked runtime nobody adopts (pi-famulus removed from the config) is torn down after this. */
+export const HANDOFF_EXPIRY_MS = 60_000;
+
+const REGISTRATIONS = new Set<PropertyKey>([
+  "on",
+  "registerTool",
+  "registerCommand",
+  "registerShortcut",
+  "registerFlag",
+  "registerMessageRenderer",
+  "registerProvider",
+]);
+
+export interface PiBinding {
+  /** Pass this to the runtime in place of the real pi. */
+  readonly api: ExtensionAPI;
+  /** Replay every registration on `pi` and route calls to it. */
+  attach(pi: ExtensionAPI): void;
+  /** Deliver queued messages; call once the attached pi's session has started. */
+  ready(): void;
+  /** Stop calling the attached pi (it is about to go stale). */
+  detach(): void;
+  /** Drop queued messages; they belong to a session that is not coming back. */
+  discardQueued(): void;
+}
+
+export function createPiBinding(): PiBinding {
+  const registrations: Array<{ method: PropertyKey; args: unknown[] }> = [];
+  const queued: unknown[][] = [];
+  let current: ExtensionAPI | null = null;
+  let live = false;
+
+  const call = (pi: ExtensionAPI, method: PropertyKey, args: unknown[]): unknown =>
+    (Reflect.get(pi, method) as (...a: unknown[]) => unknown).apply(pi, args);
+
+  const api = new Proxy({} as ExtensionAPI, {
+    get(_target, key) {
+      if (REGISTRATIONS.has(key)) {
+        return (...args: unknown[]) => {
+          registrations.push({ method: key, args });
+          return current ? call(current, key, args) : undefined;
+        };
+      }
+      if (key === "sendMessage") {
+        return (...args: unknown[]) => {
+          if (current && live) return call(current, key, args);
+          queued.push(args);
+        };
+      }
+      if (!current) throw new Error(`pi-famulus: pi.${String(key)} used while detached (between reloads)`);
+      const value = Reflect.get(current, key) as unknown;
+      return typeof value === "function" ? (value as (...a: unknown[]) => unknown).bind(current) : value;
+    },
+  });
+
+  return {
+    api,
+    attach(pi) {
+      current = pi;
+      live = false;
+      for (const { method, args } of registrations) call(pi, method, args);
+    },
+    ready() {
+      if (!current) return;
+      live = true;
+      for (const args of queued.splice(0)) call(current, "sendMessage", args);
+    },
+    detach() {
+      current = null;
+      live = false;
+    },
+    discardQueued() {
+      queued.length = 0;
+    },
+  };
+}
+
+export interface ParkedRuntime<R> {
+  /** Extension version that parked it; another version's runtime is not adopted. */
+  version: string;
+  runtime: R;
+  /** Full teardown (what a non-reload session_shutdown does). */
+  dispose(): Promise<void>;
+}
+
+interface Slot {
+  parked: ParkedRuntime<unknown>;
+  expiry: unknown;
+}
+
+/** Park a runtime for the next instance; tear it down if nobody takes it in time. */
+export function parkRuntime<R>(parked: ParkedRuntime<R>, clock: Clock = realClock): void {
+  const store = globalThis as Record<symbol, Slot | undefined>;
+  const previous = store[HANDOFF_KEY];
+  if (previous) {
+    clock.clearTimeout(previous.expiry);
+    void previous.parked.dispose().catch(() => {});
+  }
+  const expiry = clock.setTimeout(() => {
+    if (store[HANDOFF_KEY]?.parked !== parked) return;
+    store[HANDOFF_KEY] = undefined;
+    void parked.dispose().catch(() => {});
+  }, HANDOFF_EXPIRY_MS);
+  clock.unref?.(expiry);
+  store[HANDOFF_KEY] = { parked: parked as ParkedRuntime<unknown>, expiry };
+}
+
+/** Take the parked runtime, if any. The caller adopts or disposes it. */
+export function takeParkedRuntime<R>(clock: Clock = realClock): ParkedRuntime<R> | null {
+  const store = globalThis as Record<symbol, Slot | undefined>;
+  const slot = store[HANDOFF_KEY];
+  if (!slot) return null;
+  store[HANDOFF_KEY] = undefined;
+  clock.clearTimeout(slot.expiry);
+  return slot.parked as ParkedRuntime<R>;
+}

package/src/tui/famulus-command.ts

@@ -0,0 +1,71 @@
+/**
+ * /famulus — which pi-famulus binary this session uses and which versions run.
+ */
+import { execFile } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ManagerClient } from "../manager-client";
+
+export interface FamulusCommandDeps {
+  extensionVersion: string;
+  managerPath: string | null;
+  /** Where the binary was looked for, shown when none was found. */
+  describeSearch: () => string;
+  getClient: () => ManagerClient | null;
+  /** `<binary> --version`; null when it cannot be run. */
+  binaryVersion?: (path: string) => Promise<string | null>;
+}
+
+export interface FamulusInfo {
+  extensionVersion: string;
+  managerPath: string | null;
+  searched: string;
+  binaryVersion: string | null;
+  daemon: { version: string; pid: number } | null;
+  daemonError: string;
+}
+
+export function formatFamulusInfo(info: FamulusInfo): string {
+  const binary = info.managerPath
+    ? `${info.managerPath}${info.binaryVersion ? ` (${info.binaryVersion})` : ""}`
+    : `not found; looked in: ${info.searched}`;
+  const manager = info.daemon
+    ? `${info.daemon.version} (pid ${info.daemon.pid})`
+    : `not connected${info.daemonError ? ` (${info.daemonError})` : ""}`;
+  return [
+    `pi-famulus extension ${info.extensionVersion}`,
+    `CLI binary: ${binary}`,
+    `Manager: ${manager}`,
+  ].join("\n");
+}
+
+export function readBinaryVersion(path: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile(path, ["--version"], { timeout: 2000, windowsHide: true }, (err, stdout) => {
+      if (err) return resolve(null);
+      // "pi-famulus 0.1.6+<sha>"
+      resolve(stdout.trim().replace(/^pi-famulus\s+/, "") || null);
+    });
+  });
+}
+
+export async function collectFamulusInfo(deps: FamulusCommandDeps): Promise<FamulusInfo> {
+  const client = deps.getClient();
+  const connected = client?.isAvailable() ?? false;
+  return {
+    extensionVersion: deps.extensionVersion,
+    managerPath: deps.managerPath,
+    searched: deps.managerPath ? "" : deps.describeSearch(),
+    binaryVersion: deps.managerPath ? await (deps.binaryVersion ?? readBinaryVersion)(deps.managerPath) : null,
+    daemon: connected ? client?.managerInfo() ?? null : null,
+    daemonError: connected ? "" : client?.lastError() ?? "",
+  };
+}
+
+export function registerFamulusCommand(pi: ExtensionAPI, deps: FamulusCommandDeps): void {
+  pi.registerCommand("famulus", {
+    description: "Show the pi-famulus binary path and the manager and extension versions",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(formatFamulusInfo(await collectFamulusInfo(deps)), "info");
+    },
+  });
+}

package/src/tui/tasks-command.ts

@@ -64,10 +64,6 @@ export function registerTasksCommand(pi: ExtensionAPI, deps: TasksCommandDeps):
     description: "List and inspect background work",
     handler: async (_args, ctx) => openTasksUi(ctx, deps),
   });
-  pi.registerCommand("bashes", {
-    description: "Alias for /tasks",
-    handler: async (_args, ctx) => openTasksUi(ctx, deps),
-  });
 }
 
 type TaskListRow = { type: "run"; runId: string; count: number } | { type: "task"; item: WorkItem; indent: boolean };