@fitchmultz/pi-subagents 0.49.1 → 0.50.0

package/scripts/real-pi-smoke.mjs

@@ -8,13 +8,11 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, relative, isAbsolute } 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";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const authAgentDir =
@@ -23,7 +21,7 @@ const authAgentDir =
 
 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 list, foreground, and async-completion smoke prompts\n  --llm-full        Also verify forked tool-result 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`,
   );
 }
 
@@ -98,16 +96,18 @@ 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 +119,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) {
@@ -205,12 +224,15 @@ async function runLivePrompt(label, prompt, options, expectedTool) {
   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");
+  return {
+    events,
+    text: 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) {
@@ -225,10 +247,10 @@ function* savedAssistantModels(file) {
   }
 }
 
-function auditSavedModels(dir, expectedModel) {
+function auditSavedModels(directories, expectedModel) {
   const models = new Set();
   let responses = 0;
-  for (const file of filesIn(dir)) {
+  for (const file of directories.flatMap((dir) => [...filesIn(dir)])) {
     if (!file.endsWith(".jsonl")) {
       continue;
     }
@@ -256,44 +278,57 @@ function requireOutput(label, output, pattern) {
   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);
+function asyncCompletion(dir, runId) {
+  const resultPath = join(dir, "result.json");
+  if (!existsSync(resultPath)) {
+    return { status: "missing" };
+  }
+  const result = JSON.parse(readFileSync(resultPath, "utf8"));
+  if (result.id !== runId) {
+    throw new Error("Async completion belongs to another saved run");
+  }
+  if (result.status !== "completed") {
+    throw new Error(`async run ${runId} ended ${result.status}: ${result.error ?? ""}`);
+  }
+  const processPath = join(dir, "actor.lock", "process.json");
+  if (!existsSync(processPath)) {
+    return { status: "completed; actor exit unconfirmed" };
+  }
+  const actor = JSON.parse(readFileSync(processPath, "utf8"));
+  return {
+    status: result.status,
+    output: isChildTreeAlive(processRef(actor.pid))
+      ? undefined
+      : readFileSync(join(dir, "output.txt"), "utf8"),
+  };
+}
+
+async function waitForAsyncCompletion(run, pattern, { env, timeoutMs, signal }) {
+  const dir = dirname(run.sessionFile);
+  const within = relative(join(env.PI_CODING_AGENT_DIR, "sessions", "agent-runs"), dir);
+  if (isAbsolute(within) || within.startsWith("..") || !/^[a-zA-Z0-9_-]{1,128}$/.test(run.id)) {
+    throw new Error("Async receipt did not identify this smoke's private saved run");
+  }
   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");
+    const completion = asyncCompletion(dir, run.id);
+    lastState = completion.status;
+    if (completion.output !== undefined) {
+      requireOutput(`async run ${run.id} completed and actor exited`, completion.output, pattern);
+      return;
     }
-    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.
+    // Result publication is not process exit; retain resources until final actor writes finish.
     // oxlint-disable-next-line no-await-in-loop
-    await delay(500, undefined, { signal });
+    await delay(100, undefined, { signal });
   }
   throw new Error(
-    `async run ${runId} did not complete after ${timeoutMs}ms (last state: ${lastState}).\nOutput:\n${lastOutput}`,
+    `async run ${run.id} did not complete and exit after ${timeoutMs}ms (last state: ${lastState}).`,
   );
 }
 
-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(
@@ -301,122 +336,96 @@ async function runLiveSmoke(options, runOptions, agentDir) {
     );
   }
   const childModelInstruction = process.env.PI_REAL_SMOKE_MODEL
-    ? ` Pass model override '${process.env.PI_REAL_SMOKE_MODEL}' to every subagent run.`
+    ? ` Pass model '${process.env.PI_REAL_SMOKE_MODEL}' to every delegate call.`
     : "";
   await runBasicLiveSmoke(runOptions, childModelInstruction);
   if (options.llmFull) {
     await runFullLiveSmoke(runOptions, childModelInstruction);
   }
-  auditSavedModels(join(root, "sessions"), process.env.PI_REAL_SMOKE_MODEL);
+  auditSavedModels(
+    [join(runOptions.root, "sessions"), join(agentDir, "sessions", "agent-runs")],
+    process.env.PI_REAL_SMOKE_MODEL,
+  );
+}
+
+function toolDetails(events, name) {
+  return events
+    .filter((event) => event.type === "tool_execution_end" && event.toolName === name)
+    .map((event) => event.result?.details);
+}
+
+function requireCompleted(run, expected) {
+  if (run?.status !== "completed" || run.output?.text !== expected) {
+    throw new Error(`Native child did not complete with expected output: ${expected}`);
+  }
 }
 
 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,
+  const prompts = [
+    [
+      "intercom",
+      "Call the intercom tool with action status. Reply exactly 'real-pi-smoke intercom ok' only if it reports 'Connected: Yes'.",
+      "intercom",
+    ],
+    [
+      "list",
+      "Call agent_runs with action list. Reply exactly 'real-pi-smoke list ok' only if it successfully returns a saved-run list. There are no profiles to discover.",
+      "agent_runs",
+    ],
+    [
+      "foreground",
+      `Call delegate with prompt 'Reply exactly: real-pi-smoke foreground ok', name 'smoke-foreground', and async false.${childModelInstruction} Reply exactly 'real-pi-smoke foreground ok' only if the actual child result contains it.`,
       "delegate",
-    ),
-    /real-pi-smoke foreground ok/,
-  );
-  const asyncOutput = await runLivePrompt(
-    "real Pi async subagent prompt",
-    asyncPrompt,
+    ],
+  ];
+  for (const [kind, prompt, tool] of prompts) {
+    // Keep separate native parent sessions so each smoke owns its saved runs.
+    // oxlint-disable-next-line no-await-in-loop
+    const result = await runLivePrompt(`real Pi ${kind} prompt`, prompt, runOptions, tool);
+    if (kind === "foreground") {
+      requireCompleted(toolDetails(result.events, "delegate")[0], "real-pi-smoke foreground ok");
+    }
+    requireOutput(`real Pi ${kind} prompt`, result.text, new RegExp(`real-pi-smoke ${kind} ok`));
+  }
+  const result = await runLivePrompt(
+    "real Pi async prompt",
+    `Call delegate with prompt 'Reply exactly: real-pi-smoke async ok', name 'smoke-async', and async true.${childModelInstruction} Do not wait or call agent_runs. Reply exactly 'real-pi-smoke async launched ok' after receiving a launch receipt, not claiming completion.`,
     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);
+  requireOutput("real Pi async prompt", result.text, /real-pi-smoke async launched ok/);
+  const receipt = toolDetails(result.events, "delegate")[0];
+  if (receipt?.receipt !== "launch" || !receipt.id || !receipt.sessionFile) {
+    throw new Error("Native delegate did not return a saved asynchronous launch receipt");
+  }
+  await waitForAsyncCompletion(receipt, /^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/,
-  );
+  const prompt = `First call delegate with prompt 'Reply exactly CALIBRATION_FACT=packed-otter-7319', name 'fact', context fresh and async false.${childModelInstruction} Then call delegate with context fork, async false, and prompt 'Read the preceding delegate tool result in inherited conversation. Without tools, filesystem reads, or guessing, return the CALIBRATION_FACT line exactly; return FACT_NOT_VISIBLE if absent.' Finally call agent_runs with action continue, the first saved run id, async false, and prompt 'Without tools, repeat the CALIBRATION_FACT line from your own saved conversation exactly.' Reply exactly 'real-pi-smoke fork ok' only if both the forked child and continued child actually return CALIBRATION_FACT=packed-otter-7319. There are no profiles, task prefixes, output settings, or canned role instructions.`;
+  const result = await runLivePrompt("real Pi fork prompt", prompt, runOptions, "delegate");
+  const delegates = toolDetails(result.events, "delegate");
+  const continuation = toolDetails(result.events, "agent_runs")[0];
+  for (const run of [...delegates, continuation]) {
+    requireCompleted(run, "CALIBRATION_FACT=packed-otter-7319");
+  }
   if (
-    !existsSync(outputPath) ||
-    !/real-pi-smoke output ok/.test(readFileSync(outputPath, "utf8"))
+    delegates.length !== 2 ||
+    delegates[0].context !== "fresh" ||
+    delegates[1].context !== "fork" ||
+    continuation.predecessor !== delegates[0].id ||
+    continuation.sessionFile !== delegates[0].sessionFile
   ) {
-    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/,
-  );
+    throw new Error(
+      "Fork/continuation smoke did not execute the two contexts and reuse the first saved conversation",
+    );
+  }
+  requireOutput("real Pi fork prompt", result.text, /real-pi-smoke fork 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 +440,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);
@@ -475,7 +484,7 @@ async function main() {
     }
   } 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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { mkdtempSync, readdirSync, rmSync } from "node:fs";
-import { availableParallelism, tmpdir } from "node:os";
+import { availableParallelism } from "node:os";
 import { join } from "node:path";
 
 // ponytail: integration is sized for the 3-vCPU macOS hosted runner, where the suite takes
@@ -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,10 @@ 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("/tmp", "pi-subagents-test-"));
   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/skills/pi-intercom/SKILL.md

@@ -1,113 +1,59 @@
 ---
 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 `docs/intercom.md` for broker and persistence contracts.