@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/scripts/real-pi-smoke.mjs

@@ -1,29 +1,15 @@
 #!/usr/bin/env node
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import process from "node:process";
-import { setTimeout as delay } from "node:timers/promises";
-import { isChildTreeAlive } from "../src/shared/post-exit-stdio-guard.ts";
-import { SmokeProcesses, filesIn, processRef } from "./real-pi-processes.mjs";
-import { getBrokerSocketPath } from "../src/pi-intercom/broker/paths.ts";
+import { runLiveSmoke } from "./real-pi-live.mjs";
+import { SmokeProcesses } from "./real-pi-processes.mjs";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
-const authAgentDir =
-  process.env.PI_REAL_SMOKE_AUTH_AGENT_DIR ??
-  (process.env.HOME ? join(process.env.HOME, ".pi", "agent") : undefined);
 
 function usage() {
   console.log(
-    `Usage: node scripts/real-pi-smoke.mjs [--llm] [--llm-full] [--keep-temp] [--timeout-ms <ms>]\n\nRuns an opt-in real Pi package smoke for this checkout. It uses an isolated\ntemporary Pi home, installs the single pi-subagents package with bundled intercom, verifies pi list,\nand loads both extension entries. It does not install pi-fitch-kit, publish anything,\nor create GitHub Actions.\n\nOptions:\n  --llm             Also run live model-backed list, foreground, and async-completion smoke prompts\n  --llm-full        Also run broader live parallel, chain, output, and acceptance prompts\n  --keep-temp       Keep the isolated temporary home for debugging\n  --timeout-ms <ms> Per-command timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})\n  -h, --help        Show this help\n\nEnvironment:\n  PI_REAL_SMOKE_AUTH_AGENT_DIR     Source Pi agent dir for auth.json/models.json during --llm (default: ~/.pi/agent)\n  PI_REAL_SMOKE_MODEL              Model passed to live --llm smoke prompts, e.g. openai/gpt-6-astra\n  PI_REAL_SMOKE_PROVIDER           Provider passed to live --llm smoke prompts\n\nExit codes:\n  0  real Pi smoke passed\n  1  install/list/live smoke failed\n  2  invalid arguments`,
+    `Usage: node scripts/real-pi-smoke.mjs [--llm] [--llm-full] [--keep-temp] [--timeout-ms <ms>]\n\nRuns an opt-in real Pi package smoke for this checkout. It uses an isolated\ntemporary Pi home, installs the single pi-subagents package with bundled intercom, verifies pi list,\nand loads the single compiled entry. It does not install pi-fitch-kit, publish anything,\nor create GitHub Actions.\n\nOptions:\n  --llm             Also run live model-backed intercom, list, and delegate prompts in a persistent RPC main\n                    that stays open until each launch receipt's completion notification resumes it\n  --llm-full        Also verify forked completion context and saved-conversation continuation\n  --keep-temp       Keep the isolated temporary home for debugging\n  --timeout-ms <ms> Per-command timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})\n  -h, --help        Show this help\n\nEnvironment:\n  PI_REAL_SMOKE_AUTH_AGENT_DIR     Source Pi agent dir for auth.json/models.json during --llm (default: ~/.pi/agent)\n  PI_REAL_SMOKE_MODEL              Model passed to live --llm smoke prompts, e.g. openai/gpt-6-astra\n  PI_REAL_SMOKE_PROVIDER           Provider passed to live --llm smoke prompts\n\nExit codes:\n  0  real Pi smoke passed\n  1  install/list/live smoke failed\n  2  invalid arguments`,
   );
 }
 
@@ -77,37 +63,22 @@ function parseArgs(argv) {
   return options;
 }
 
-function copyLiveAuth(agentDir) {
-  if (!authAgentDir || !existsSync(authAgentDir)) {
-    return [];
-  }
-  mkdirSync(agentDir, { recursive: true });
-  const copied = [];
-  for (const filename of ["auth.json", "models.json"]) {
-    const source = join(authAgentDir, filename);
-    if (!existsSync(source)) {
-      continue;
-    }
-    copyFileSync(source, join(agentDir, filename));
-    copied.push(filename);
-  }
-  return copied;
-}
-
 function isolatedEnv(root, agentDir) {
   const home = join(root, "home");
   const env = { ...process.env };
   for (const key of Object.keys(env)) {
-    if (key.startsWith("PI_SUBAGENT_")) {
+    if (key.startsWith("PI_SUBAGENT_") || key.startsWith("PI_INTERCOM_")) {
       delete env[key];
     }
   }
   return {
     ...env,
     HOME: home,
+    USERPROFILE: home,
     XDG_CONFIG_HOME: join(home, ".config"),
     XDG_CACHE_HOME: join(home, ".cache"),
     PI_CODING_AGENT_DIR: agentDir,
+    PI_INTERCOM_RUNTIME_DIR: join(root, "ic"),
     PI_SUBAGENT_TEMP_ROOT: join(root, "pi-subagents-runtime"),
     PI_OFFLINE: "1",
     PATH: process.env.PATH ?? "",
@@ -119,21 +90,40 @@ function runPi(label, args, options) {
 }
 
 async function verifyBundledResources(options) {
+  const marker = join(options.root, "resources.json");
+  const observer = join(options.root, "observe-resources.mjs");
+  writeFileSync(
+    observer,
+    `import { writeFileSync } from "node:fs"; export default function(pi) { pi.on("session_start", () => { writeFileSync(${JSON.stringify(marker)}, JSON.stringify(pi.getActiveTools())); }); }`,
+  );
   const output = await runPi(
     "pi load bundled resources",
-    ["--mode", "rpc", "--no-session", "--offline", "--approve"],
-    {
-      ...options,
-      input: `${JSON.stringify({ id: "commands", type: "get_commands" })}\n`,
-    },
+    ["--mode", "rpc", "--no-session", "--offline", "--approve", "-e", observer],
+    { ...options, input: `${JSON.stringify({ id: "commands", type: "get_commands" })}\n` },
   );
-  const response = commandResponse(output);
-  const commands = registeredCommands(response);
-  for (const name of ["intercom", "subagents-doctor", "skill:pi-intercom", "skill:pi-subagents"]) {
+  const commands = registeredCommands(commandResponse(output));
+  for (const name of ["skill:pi-intercom", "skill:pi-subagents"]) {
     if (!commands.includes(name)) {
       throw new Error(`bundled Pi resources did not register ${name}:\n${output}`);
     }
   }
+  const tools = JSON.parse(readFileSync(marker, "utf8"));
+  for (const name of ["delegate", "agent_runs", "intercom"]) {
+    if (!tools.includes(name)) {
+      throw new Error(`${name} must be eager on the single package entry`);
+    }
+  }
+  for (const name of [
+    "subagent",
+    "load_subagent",
+    "load_intercom",
+    "contact_supervisor",
+    "structured_output",
+  ]) {
+    if (tools.includes(name)) {
+      throw new Error(`retired package tool is still exposed: ${name}`);
+    }
+  }
 }
 
 function commandResponse(output) {
@@ -157,266 +147,9 @@ function registeredCommands(response) {
     : [];
 }
 
-async function runLivePrompt(label, prompt, options, expectedTool) {
-  const args = [
-    "--print",
-    "--mode",
-    "json",
-    "--session-dir",
-    join(options.root, "sessions"),
-    "--approve",
-  ];
-  if (process.env.PI_REAL_SMOKE_PROVIDER) {
-    args.push("--provider", process.env.PI_REAL_SMOKE_PROVIDER);
-  }
-  if (process.env.PI_REAL_SMOKE_MODEL) {
-    args.push(
-      "--model",
-      process.env.PI_REAL_SMOKE_MODEL,
-      "--models",
-      process.env.PI_REAL_SMOKE_MODEL,
-    );
-  }
-  args.push(prompt);
-  const output = await runPi(label, args, options);
-  writeFileSync(join(options.root, `${label.replace(/ /g, "-")}.jsonl`), output);
-  const events = output.split("\n").flatMap((line) => {
-    try {
-      return [JSON.parse(line)];
-    } catch {
-      return [];
-    }
-  });
-  if (
-    !events.some(
-      (event) => event.type === "tool_execution_start" && event.toolName === expectedTool,
-    )
-  ) {
-    throw new Error(
-      `${label} never invoked ${expectedTool}; a matching final sentence is not execution evidence.`,
-    );
-  }
-  const errors = events.filter((event) => event.type === "tool_execution_end" && event.isError);
-  if (errors.length) {
-    throw new Error(
-      `${label} had ${errors.length} failed tool call(s); inspect its saved wire log.`,
-    );
-  }
-  if (!events.some((event) => event.type === "agent_settled")) {
-    throw new Error(`${label} did not reach agent_settled.`);
-  }
-  return events
-    .filter((event) => event.type === "message_end" && event.message?.role === "assistant")
-    .flatMap((event) =>
-      event.message.content.filter((part) => part.type === "text").map((part) => part.text),
-    )
-    .join("\n");
-}
-
-function* savedAssistantModels(file) {
-  for (const line of readFileSync(file, "utf8").split("\n")) {
-    if (!line.trim()) {
-      continue;
-    }
-    const entry = JSON.parse(line);
-    if (entry.type === "message" && entry.message?.role === "assistant") {
-      yield `${entry.message.provider}/${entry.message.model}`;
-    }
-  }
-}
-
-function auditSavedModels(dir, expectedModel) {
-  const models = new Set();
-  let responses = 0;
-  for (const file of filesIn(dir)) {
-    if (!file.endsWith(".jsonl")) {
-      continue;
-    }
-    for (const model of savedAssistantModels(file)) {
-      responses++;
-      models.add(model);
-    }
-  }
-  if (!responses) {
-    throw new Error("No saved assistant messages found for model audit.");
-  }
-  if (expectedModel?.includes("/") && [...models].some((model) => model !== expectedModel)) {
-    throw new Error(`Unexpected model in saved parent/child sessions: ${[...models].join(", ")}`);
-  }
-  console.log(
-    `[real-pi-smoke] audited ${responses} saved parent/child responses: ${[...models].join(", ")}`,
-  );
-}
-
-function requireOutput(label, output, pattern) {
-  if (!pattern.test(output)) {
-    throw new Error(`${label} did not include expected evidence ${pattern}.\nOutput:\n${output}`);
-  }
-  const compact = output.trim().split(/\r?\n/).slice(-8).join("\n");
-  console.log(`[real-pi-smoke] ${label} output evidence:\n${compact}`);
-}
-
-async function waitForAsyncCompletion(runId, pattern, { env, timeoutMs, signal }) {
-  const dir = join(env.PI_SUBAGENT_TEMP_ROOT, "async-subagent-runs", runId);
-  const deadline = Date.now() + timeoutMs;
-  let lastState = "missing";
-  let lastOutput = "";
-  while (Date.now() < deadline) {
-    signal.throwIfAborted();
-    const statusPath = join(dir, "status.json");
-    const outputPath = join(dir, "output-0.log");
-    if (existsSync(outputPath)) {
-      lastOutput = readFileSync(outputPath, "utf8");
-    }
-    if (existsSync(statusPath)) {
-      const status = JSON.parse(readFileSync(statusPath, "utf8"));
-      lastState = String(status.state ?? "unknown");
-      if (asyncProcessComplete(status)) {
-        requireOutput(`async run ${runId} completed`, lastOutput, pattern);
-        return;
-      }
-      if (lastState === "failed" || lastState === "paused") {
-        throw new Error(`async run ${runId} ended ${lastState}.\nOutput:\n${lastOutput}`);
-      }
-    }
-    // Poll only after reading status and process liveness; the runner may still write final artifacts.
-    // oxlint-disable-next-line no-await-in-loop
-    await delay(500, undefined, { signal });
-  }
-  throw new Error(
-    `async run ${runId} did not complete after ${timeoutMs}ms (last state: ${lastState}).\nOutput:\n${lastOutput}`,
-  );
-}
-
-function asyncProcessComplete(status) {
-  return status.state === "complete" && status.pid && !isChildTreeAlive(processRef(status.pid));
-}
-
-async function runLiveSmoke(options, runOptions, agentDir) {
-  const { root } = runOptions;
-  const copiedAuthFiles = copyLiveAuth(agentDir);
-  if (copiedAuthFiles.length > 0) {
-    console.log(
-      `[real-pi-smoke] copied ${copiedAuthFiles.join(" and ")} into isolated Pi agent dir for live provider auth`,
-    );
-  }
-  const childModelInstruction = process.env.PI_REAL_SMOKE_MODEL
-    ? ` Pass model override '${process.env.PI_REAL_SMOKE_MODEL}' to every subagent run.`
-    : "";
-  await runBasicLiveSmoke(runOptions, childModelInstruction);
-  if (options.llmFull) {
-    await runFullLiveSmoke(runOptions, childModelInstruction);
-  }
-  auditSavedModels(join(root, "sessions"), process.env.PI_REAL_SMOKE_MODEL);
-}
-
-async function runBasicLiveSmoke(runOptions, childModelInstruction) {
-  const intercomPrompt =
-    "Call the intercom tool with action status. Reply exactly with 'real-pi-smoke intercom ok' if the tool output includes 'Connected: Yes'.";
-  const listPrompt =
-    "Use the agent_runs tool with action profiles. Reply exactly with 'real-pi-smoke list ok' if reviewer, scout, oracle, and watcher are available.";
-  const foregroundPrompt = `Use the delegate tool to run real-smoke with task 'Reply exactly: real-pi-smoke foreground ok', async false and output false.${childModelInstruction} If the tool returns an output artifact path instead of inline output, read that file. Then reply exactly 'real-pi-smoke foreground ok' only if the child result contains it.`;
-  const asyncPrompt = `Use the delegate tool to run real-smoke with task 'Reply exactly: real-pi-smoke async ok', output false.${childModelInstruction} Set async true so it launches in the background. Do not call status and do not wait for completion. Reply with 'real-pi-smoke async launched ok' and quote the exact tool result line beginning 'Async:' including the run id.`;
-  requireOutput(
-    "real Pi intercom prompt",
-    await runLivePrompt("real Pi intercom prompt", intercomPrompt, runOptions, "intercom"),
-    /real-pi-smoke intercom ok/,
-  );
-  requireOutput(
-    "real Pi subagent list prompt",
-    await runLivePrompt("real Pi subagent list prompt", listPrompt, runOptions, "agent_runs"),
-    /real-pi-smoke list ok/,
-  );
-  requireOutput(
-    "real Pi foreground subagent prompt",
-    await runLivePrompt(
-      "real Pi foreground subagent prompt",
-      foregroundPrompt,
-      runOptions,
-      "delegate",
-    ),
-    /real-pi-smoke foreground ok/,
-  );
-  const asyncOutput = await runLivePrompt(
-    "real Pi async subagent prompt",
-    asyncPrompt,
-    runOptions,
-    "delegate",
-  );
-  requireOutput(
-    "real Pi async subagent prompt",
-    asyncOutput,
-    /real-pi-smoke async (?:launched )?ok/i,
-  );
-  const asyncRunId =
-    asyncOutput.match(/Async(?: parallel)?:\s+(?:\S+|\[[^\]]+\])\s+\[([0-9a-f-]{36})\]/i)?.[1] ??
-    asyncOutput.match(/\[([0-9a-f-]{36})\]/i)?.[1] ??
-    asyncOutput.match(/\b([0-9a-f]{8}-[0-9a-f-]{27})\b/i)?.[1];
-  if (!asyncRunId) {
-    throw new Error(`Could not parse async run id from output:\n${asyncOutput}`);
-  }
-  await waitForAsyncCompletion(asyncRunId, /^real-pi-smoke async ok$/m, runOptions);
-}
-
-async function runFullLiveSmoke(runOptions, childModelInstruction) {
-  const outputPath = join(runOptions.root, "live-output-smoke.txt");
-  const parallelPrompt = `Use the subagent tool in parallel mode with two delegate tasks and async false. Task 1 replies exactly 'real-pi-smoke parallel A ok'. Task 2 replies exactly 'real-pi-smoke parallel B ok'. Set output false and progress false for both.${childModelInstruction} Reply exactly 'real-pi-smoke parallel ok' only if both child outputs are present.`;
-  const chainPrompt = `Use the subagent tool chain mode with two delegate steps and async false.${childModelInstruction} Step 1 task: 'Reply exactly: real-pi-smoke chain step1 ok'. Step 2 task: 'Previous output is {previous}. Reply exactly: real-pi-smoke chain step2 ok'. Reply exactly 'real-pi-smoke chain ok' only if step 2 ran after step 1.`;
-  const outputPrompt = `Use the subagent tool to run delegate with task 'Write exactly real-pi-smoke output ok plus newline to the requested output path, then reply exactly wrote output smoke'. Set async false, output to ${JSON.stringify(outputPath)}, and outputMode to file-only.${childModelInstruction} Reply exactly 'real-pi-smoke output ok' only after the tool returns.`;
-  const acceptancePrompt = `Use the subagent tool to run delegate with task 'Final answer exactly: real-pi-smoke acceptance ok evidence=manual-notes'. Set async false. Include acceptance criteria requiring the final answer to contain real-pi-smoke acceptance ok and evidence manual-notes, with maxFinalizationTurns 2.${childModelInstruction} Reply exactly 'real-pi-smoke acceptance ok' only if the child completed.`;
-  requireOutput(
-    "real Pi parallel subagent prompt",
-    await runLivePrompt("real Pi parallel subagent prompt", parallelPrompt, runOptions, "subagent"),
-    /real-pi-smoke parallel ok/,
-  );
-  requireOutput(
-    "real Pi chain subagent prompt",
-    await runLivePrompt("real Pi chain subagent prompt", chainPrompt, runOptions, "subagent"),
-    /real-pi-smoke chain ok/,
-  );
-  requireOutput(
-    "real Pi output subagent prompt",
-    await runLivePrompt("real Pi output subagent prompt", outputPrompt, runOptions, "subagent"),
-    /real-pi-smoke output ok/,
-  );
-  if (
-    !existsSync(outputPath) ||
-    !/real-pi-smoke output ok/.test(readFileSync(outputPath, "utf8"))
-  ) {
-    throw new Error(`output smoke file missing expected content: ${outputPath}`);
-  }
-  requireOutput(
-    "real Pi acceptance subagent prompt",
-    await runLivePrompt(
-      "real Pi acceptance subagent prompt",
-      acceptancePrompt,
-      runOptions,
-      "subagent",
-    ),
-    /real-pi-smoke acceptance ok/,
-  );
-}
-
 function createProject(root) {
   const projectRoot = join(root, "project");
-  const projectAgentsDir = join(projectRoot, ".pi", "agents");
-  mkdirSync(projectAgentsDir, { recursive: true });
-  writeFileSync(
-    join(projectAgentsDir, "real-smoke.md"),
-    `---
-name: real-smoke
-description: Isolated live smoke agent
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
-tools: read
-extensions:
----
-
-Follow the task exactly and return its requested text without using tools.
-`,
-    "utf-8",
-  );
+  mkdirSync(projectRoot, { recursive: true });
   return projectRoot;
 }
 
@@ -431,7 +164,7 @@ async function main() {
   }
 
   const repoRoot = resolve(process.cwd());
-  const root = mkdtempSync(join(tmpdir(), "pi-subagents-real-pi-smoke-"));
+  const root = mkdtempSync(join("/tmp", "pi-subagents-real-pi-smoke-"));
   const agentDir = join(root, "pi-agent");
   const projectRoot = createProject(root);
   const env = isolatedEnv(root, agentDir);
@@ -470,12 +203,12 @@ async function main() {
     );
     if (!options.llm) {
       console.log(
-        "[real-pi-smoke] live model subagent prompts skipped; pass --llm to exercise foreground/async paths.",
+        "[real-pi-smoke] live model subagent prompts skipped; pass --llm to exercise launch receipts and completion notifications.",
       );
     }
   } finally {
     await runOptions.processes.stop();
-    rmSync(dirname(getBrokerSocketPath(agentDir)), { recursive: true, force: true });
+    rmSync(env.PI_INTERCOM_RUNTIME_DIR, { recursive: true, force: true });
     for (const name of ["auth.json", "models.json"]) {
       rmSync(join(agentDir, name), { force: true });
     }

package/scripts/run-tests.mjs

@@ -81,7 +81,7 @@ function testFiles(dir) {
 function sanitizedEnv() {
   const env = { ...process.env };
   for (const key of Object.keys(env)) {
-    if (key.startsWith("PI_SUBAGENT_")) {
+    if (key.startsWith("PI_SUBAGENT_") || key.startsWith("PI_INTERCOM_")) {
       delete env[key];
     }
   }
@@ -91,9 +91,12 @@ function sanitizedEnv() {
 function runNodeTest(label, files, timeoutMs, concurrency) {
   const args = [...(concurrency ? [`--test-concurrency=${concurrency}`] : []), "--test", ...files];
   const startedAt = Date.now();
-  const tempRoot = mkdtempSync(join(tmpdir(), "pi-subagents-test-"));
+  const tempRoot = mkdtempSync(
+    join(process.platform === "android" ? tmpdir() : "/tmp", "pi-subagents-"),
+  );
   const env = sanitizedEnv();
   env.PI_SUBAGENT_TEMP_ROOT = tempRoot;
+  env.PI_INTERCOM_RUNTIME_DIR = join(tempRoot, "ic");
   env.HOME = tempRoot;
   delete env.PI_CODING_AGENT_DIR;
   let result;

package/scripts/typescript.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Android's npm compiler package is not published; use its installed native compiler.
+ * @param {string} [script]
+ * @returns {{ command: string, args: string[] }}
+ */
+export function compilerInvocation(script) {
+  if (script === undefined && process.platform === "android") {
+    return { command: "tsgo", args: [] };
+  }
+  const compiler = script ?? join(process.cwd(), "node_modules", "typescript", "bin", "tsc");
+  if (!existsSync(compiler)) {
+    throw new Error(`typescript is not installed at ${compiler}; run npm install first.`);
+  }
+  return { command: process.execPath, args: [compiler] };
+}
+
+if (import.meta.main) {
+  const compiler = compilerInvocation();
+  const result = spawnSync(compiler.command, [...compiler.args, ...process.argv.slice(2)], {
+    stdio: "inherit",
+  });
+  if (result.error) {
+    console.error(
+      process.platform === "android"
+        ? `Cannot run native TypeScript: install an Android build of tsgo on PATH. ${result.error.message}`
+        : result.error.message,
+    );
+  }
+  process.exitCode = result.status ?? 1;
+}

package/skills/pi-intercom/SKILL.md

@@ -1,113 +1,60 @@
 ---
 name: pi-intercom
-description: "Coordinate local Pi sessions with pi-intercom: list peers, send updates, ask blocking questions, reply to inbound asks, use contact_supervisor, or handle pi-subagents escalations. Do not use for generic chat, remote/cross-machine messaging, unrelated repos, routine subagent completion, or work this session can finish."
+description: "Discover eligible local Pi sessions, send guidance, ask/reply, or read a peer's last completed response without waking it. Use for same-machine Pi coordination, not generic chat or unrelated remote messaging."
 ---
 
 # Pi Intercom
 
-## Goal
-
-Coordinate named Pi sessions on the same machine with the least context loss and the fewest interruptions.
-
-## Source of truth
-
-- Fresh sessions keep the peer schema behind `load_intercom({})`; presence and delivery remain active. Actionable inbound/recovered reply needs load it automatically. Presence alone, passive or routine child notices, and human chat messages do not.
-- A bounded ambient hint may report that same-project peers are connected. It is a constant count-free string and never sends a message; use `intercom({ action: "list" })` before choosing a target.
-- `intercom({ action: "list" })` is the source of truth for targetable sessions in the current Git repository and its worktrees. Use `intercom({ action: "list", scope: "all" })` only when intentionally discovering connected sessions in other projects. Both scopes show only intercom-connected sessions, not every Pi process, with live ask capability, busy/idle/unknown state, recent intercom activity, and delivery guidance. The current-session row is not targetable; choose a peer from Other sessions.
-- Tool call shapes and options live in the live `intercom` / `contact_supervisor` schemas, `docs/intercom.md`, and `src/pi-intercom/index.ts`. Read those when a parameter detail is needed; do not invent fields.
-- Pi CLI flags for local peer sessions are `--name`, `--extension`, and `--skill`.
-
-## Use when
-
-- Delegating a bounded task to another already-running Pi session.
-- Sending findings, code snippets, file context, progress, or blockers to a specific session.
-- Asking a peer for a decision or clarification you need before continuing.
-- Replying to an inbound intercom ask.
-- Handling a formatted `pi-subagents` supervisor escalation.
-
-## Do not use when
-
-- The current session can finish the work directly.
-- The target is remote or on another machine; pi-intercom is local IPC only.
-- The task is unrelated to the recipient's repo or role.
-- A normal `subagent` run is enough and no visible peer conversation is needed.
-- The message would expose secrets, tokens, passwords, private data, or unrelated user context without explicit approval.
-- Routine subagent completion or final handoff; return that through `pi-subagents`, not intercom/`contact_supervisor`.
-
-## Default workflow
-
-1. Decide whether a peer is actually needed. If not, keep working locally.
-2. Call `load_intercom({})` if `intercom` is inactive, then discover targets with `intercom({ action: "list" })` before sending. This defaults to the current repository and its worktrees; use `scope: "all"` only for intentional cross-project coordination.
-3. Pick the displayed name or target ID exactly. If names collide, use the target shown by `list`. Never message the current session.
-4. Choose the lightest action:
-
-| Action    | Use for                                                                               | Effect                                                                                                                                                                                                                                            |
-| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `send`    | Guidance, answers, corrections, blockers, context, or other non-blocking coordination | Defaults to steer: it wakes idle recipients or reaches busy recipients at the next tool boundary, then returns after broker acceptance. Use explicit queue only when delay is intentional and passive only for human-visible breadcrumbs.         |
-| `ask`     | A required answer when this process must remain alive waiting for it                  | Use `delivery:"steer"`; waits up to `askTimeoutMs` (default 2 minutes). Default asks to peers reporting `accepts_asks:false` return `delivered:true`, `replied:false`, `reason:"peer_busy"`, while explicit steer asks keep waiting; not passive. |
-| `reply`   | Answering an inbound ask                                                              | Uses the active ask, or the single pending ask                                                                                                                                                                                                    |
-| `pending` | Multiple or delayed inbound asks                                                      | Lists unresolved asks so you can disambiguate                                                                                                                                                                                                     |
-| `status`  | Troubleshooting connection state                                                      | Shows connection, active session count, and the same live recipient capability/guidance rows as `list`                                                                                                                                            |
-
-5. Write compact messages with objective, scope, relevant files, stop boundary, and expected reply. Attachments only when the recipient needs the extra context.
-6. For live agent-to-agent coordination, use non-blocking `send`; omitted delivery steers by default. Then end the turn or continue independent work. Use explicit queue only when delay is intentional; optional `delivery:"queue", queueMode:"replace", threadId:"<non-empty>"` keeps only the latest undelivered update for that thread.
-7. Treat inbound steers as coordination within the active task: incorporate relevant context and continue. Replace the task only when the message explicitly says so. Reply to an active ask with `reply`; otherwise respond with default-steered `send`.
-8. Use blocking `ask` only when this process must stay alive and cannot safely continue without the answer. After any tool result, handle the reply or error; do not assume delivery after failure.
-
-## Quiet current state
-
-Use explicit `subscribe` / `unsubscribe` with an exact `topic`, and `publish` with a self-contained `message`. Routine `event: "update"` replaces one inspectable record per sender/topic without entering model context or waking a turn; inspect with `topics` or `/intercom topics`. Use resource-specific names for browser/tab ownership. `resource` + `ownership: "held" | "released"` is advisory state, not a lock; disconnection means unavailable, not released. Blocker/decision events steer subscribers; release events steer only subscriptions using `awaitRelease: true`. Direct messages always bypass subscriptions. Skip redundant status prose and keep material findings in the final task result.
-
-## Supervisor escalations from pi-subagents
-
-When present, child sessions get a child-only `contact_supervisor` tool; normal sessions use `intercom`. Do not assume `contact_supervisor` exists unless the tool is listed.
-
-Child-side reasons only: blocking `need_decision` or `interview_request` when the ephemeral child cannot safely continue and must remain alive for the reply, or a non-blocking `progress_update` for a discovery or change the supervisor needs while working. Progress steers at the next tool boundary; skip starts, redundant status, and routine completion, and retain material findings in the final result.
-
-Supervisor-side: while connected, `intercom` `reply` answers formatted child escalations. After reload/reconnect, resume the same saved supervisor session, list `agent_runs({ action: "questions" })`, and use `agent_runs({ action: "answer", id, questionId, message })`. These questions do not use the ordinary ask timeout. A nudge is not an answer. Saved answers reach a live waiter or revive an exited child's saved session; a receipt does not mean the work completed. Use `agent_runs({ action: "stop", id })` to cancel a pending question and its live waiter.
-
-| Type                | Meaning                                                          | Supervisor response                     |
-| ------------------- | ---------------------------------------------------------------- | --------------------------------------- |
-| `need_decision`     | Child cannot safely continue without one decision or approval    | Reply promptly with a clear decision    |
-| `interview_request` | Child cannot safely continue without multiple structured answers | Reply with JSON using the requested ids |
-| `progress_update`   | Child steers a material discovery needed during active work      | Read it; reply only if redirecting      |
-
-Interview replies use plain JSON or a fenced JSON block. `info` questions are context only and need no response entries:
-
-```json
-{
-  "responses": [
-    { "id": "api", "value": "Stable API" },
-    { "id": "constraints", "value": "Keep the public error shape unchanged." }
-  ]
-}
-```
-
-If a subagent status line advertises an intercom target, trust it only when that target appears in `intercom({ action: "list" })`. If absent, use `agent_runs` inspection, continuation, nudging, or result artifacts; the child may be Claude Code-backed or already exited and have no child-side `contact_supervisor`. From a parent session, prefer `agent_runs({ action: "nudge", id, message })` for non-blocking live child coordination; it supplements the active child task unless it explicitly replaces it. Use direct `intercom({ action: "ask", to, delivery: "steer", message })` only when the parent process must remain alive and cannot safely continue without a listed child reply.
-
-## Optional visible peer sessions
-
-Read `references/peer-sessions.md` before starting a new visible peer session. Spawn one only when all are true:
-
-- No connected peer from `intercom({ action: "list" })` already fits.
-- The user benefits from watching or resuming a long-lived peer conversation.
-- The peer works in the same repo or an intentional reference repo.
-- You can run a smoke ask before delegating real work.
-
-## Failure handling
-
-- No other project sessions: do not invent a target. Use `scope: "all"` only when cross-project coordination is intentional; otherwise start a peer only if the optional visible-peer rule holds.
-- `Session not found`: run `list`, choose the exact displayed target, then retry if still useful.
-- `Already waiting for a reply`: wait for the current ask, use `send` for non-blocking context, or continue local work.
-- Multiple pending asks: run `pending`, then use its copy-ready `reply` call or disambiguate with the displayed `to` or `replyTo` value.
-- Ask timeout: summarize the blocked decision and continue only with safe local work.
-- Busy non-interactive recipient auto-reply: it cannot respond while running; use subagent controls or wait.
-
-## Completion evidence
-
-A good intercom-assisted turn ends with:
-
-- Target came from `list` or from the active inbound ask.
-- Action matched intent: default-steered `send` for live coordination, `ask` only for a required blocking reply, `reply` for an inbound ask, explicit queue only for intentional delay, and passive only when deliberately not waking the model.
-- Delivery result or failure was handled.
-- Any spawned peer was smoke-tested and either still needed or cleaned up.
+The `intercom` tool is eager. There is no loader, separate child supervisor tool,
+workflow UI, or topic registry.
+
+1. Use `intercom({action:"list"})` before choosing a peer. Default discovery spans
+   projects and agent directories under the same OS user; optional
+   `scope:"project"` filters to this repository and its worktrees.
+2. Pick the exact displayed target. Names are not unique; resolve ambiguity rather
+   than guessing. The current session is not a peer target.
+3. Choose the lightest operation:
+   - `send`: non-blocking guidance/corrections/blockers; default delivery steers.
+   - `last`: original last completed assistant text, without waking the peer.
+   - `ask`: bounded correlated wait only when the sender must stay alive waiting.
+   - `reply`: answer the active/sole pending ask, or specify `replyTo` when ambiguous.
+   - `pending`: unresolved inbound asks and their correlation.
+   - `status`: connection, peer health and inbound queue state.
+4. Handle the actual outcome. Broker acceptance is not recipient persistence,
+   model consumption, a reply, completion, or process exit. Do not replay an
+   uncertain side effect merely because its response was lost.
+
+## Topology
+
+A main and its children form one group. Every pair inside it can communicate.
+Mains can also communicate with other mains. Children cannot discover, send to,
+or read a foreign group's agents—even with an exact ID. Only mains delegate;
+there is one level. Cwd and agentDir do not define groups. These are coordination
+rules, not a sandbox against other code running as the same OS user.
+
+## Delivery and paging
+
+Default `send` steers at the next tool boundary or wakes an idle peer. Explicit
+`delivery:"queue"` intentionally defers. Explicit `delivery:"passive"` never wakes
+and is for breadcrumbs, not actionable work. Ordinary live agent guidance should
+not be passive.
+
+`last` returns a stable entry ID and offsets. Follow its exact next-page call to
+retrieve all text; offsets are UTF-16 code units, not bytes. A read never sends a
+model prompt. It does not substitute a fabricated status summary for the answer.
+
+Keep messages compact and self-contained: objective, scope, files, authority,
+stop boundary, and expected reply. Never attach secrets or unrelated private
+context. Use ordinary run completion for delegated handoff, not duplicate sends.
+
+## Recovery
+
+If a target disappears, list again. A timeout is not a reply. Multiple pending
+asks require explicit correlation. Ordinary asks do not recreate the retired
+persistent supervisor question/approval workflow.
+
+Old agent-directory brokers may coexist during migration; updated sessions use
+the same-user broker. Do not kill another broker or change runtime configuration
+to force discovery. Only intercom-connected eligible sessions appear, not all
+open Pi processes. See [local messaging](../../docs/intercom.md) for broker and
+persistence contracts.