@wassname2/pi-supervise 0.0.1

package/src/prompts.ts

@@ -0,0 +1,282 @@
+/**
+ * Every word the supervisor session reads, in the order it reads them, so this file is the run:
+ *
+ * 1. loadSupervisorPrompt, the policy, read once at /supervise
+ * 2. BRIEF, sent once at pairing, carrying that policy
+ * 3. TOOL_*, the three verdicts, in context at every model call because tools always are
+ * 4. REVIEW_NUDGE, sent with every view, and short because 1 to 3 already said the rest
+ * 5. NO_GOAL and DONE_BLOCKED, refusals, read only when a tool is refused
+ * 6. DEFAULT_SUPERVISOR_PROMPT, the policy used when no SUPERVISOR.md exists
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Same precedence as @monotykamary/pi-supervisor, so an existing SUPERVISOR.md keeps working:
+ * <cwd>/.pi/SUPERVISOR.md, then <agent dir>/SUPERVISOR.md, then the default below.
+ *
+ * getAgentDir is pi's own, so a profile that moves the agent dir moves this with it. That matters:
+ * the only SUPERVISOR.md on this machine lives in a profile, not in ~/.pi/agent.
+ */
+export function loadSupervisorPrompt(cwd: string): { prompt: string; source: string } {
+  for (const path of [join(cwd, ".pi", "SUPERVISOR.md"), join(getAgentDir(), "SUPERVISOR.md")]) {
+    if (existsSync(path)) return { prompt: readFileSync(path, "utf-8").trim(), source: path };
+  }
+  return { prompt: DEFAULT_SUPERVISOR_PROMPT, source: "built-in" };
+}
+
+/**
+ * Put in the supervisor's context when pairing, so it knows its job before the first view arrives.
+ *
+ * The last line has been wrong three times. "Reply with exactly: watching" taught a text answer,
+ * and deepseek-v4-flash then answered two real views with the plain word "wait" and no tool call
+ * (session 019ff4eb-c66c, 2026-08-12). Ordering a let_it_run call taught the opposite: with no view
+ * to read, one supervisor answered its own brief 98 times in a row (019ffa5f, 2026-08-13). Asking
+ * for no answer at all still got two calls, because the brief arrived as a user message and a user
+ * message is a turn. It now arrives without one, so the view is the first thing there is to answer.
+ */
+export const BRIEF = (policy: string, goal: string, worker: string) =>
+  `${policy}
+
+You are now supervising the pi session "${worker}".
+
+The goal is between the tags below, exactly as the human typed it. Nothing outside the tags is
+part of the goal. A multi-line goal appears as a one-line locator in ordinary views. Its full text
+returns after a goal change, reload, compaction, and before every fifth review.
+
+<goal>
+${goal || "not given, so infer it from the first view you receive and call set_goal"}
+</goal>
+
+Your verdict is a tool call, not text: let_it_run, steer or done. If the policy above tells you to reply
+with JSON, ignore that part: it belongs to a different supervisor and nothing parses it here.
+
+You see the worker twice: when it stops, and on a check in while it is still working. Each view
+carries only what is new since your last look, so read it against what you already know rather
+than expecting the whole session again.
+
+The view names the worker's model and how full its context is. A small or fast model needs one
+small step per instruction. A worker near the top of its context is about to compact, so tell it
+to write down what matters before it loses the detail.
+
+There is no round limit and no budget. Supervision runs until the human stops it. Ending early is
+the failure this exists to prevent, so never stop because it feels like enough.
+
+The human typing in the worker session is not a handover, and it is not a reason to stand back.
+They say a word and go to bed; the worker is then stopped with nobody driving it, which is the
+state you exist for. They will stop you themselves when they want you stopped. Judge the worker
+against the goal and nothing else.
+
+Every view says how long the worker has gone with no new turn. A worker that has produced nothing
+for a long time is stuck, or waiting for you, or in one command that will not return. Say which
+one you think it is, and use the number rather than guessing from the turns.
+
+The worker sends its first view as it pairs. It is below this message, and it is what you
+answer.`;
+
+/**
+ * Sent on a resume or a /reload that finds the pairing still alive.
+ *
+ * Short on purpose: the policy is already in the transcript above it. Only the answer shape and the
+ * goal repeat, because those are what a supervisor drops first, and because a /reload is how a
+ * changed prompt reaches a running session. Without this, fixing the wording of the brief needs
+ * /supervise stop and a fresh pairing, which throws away the supervisor's memory of its own steers.
+ */
+export const REANCHOR = (goal: string, rounds: number) =>
+  `Supervising again, after a reload or a restart.
+
+<goal>
+${goal || "not set"}
+</goal>
+
+${rounds} instructions so far.
+
+A view of the worker follows. Answer it with one tool call: steer, done or let_it_run. The word on its
+own does nothing; only the call reaches the worker.`;
+
+/** Sent when the human runs /supervise goal, so the supervisor does not judge against the old one. */
+export const GOAL_CHANGED = (goal: string) =>
+  `The human changed the goal. From now on judge the worker against what is between the tags,
+and against nothing else:
+
+<goal>
+${goal}
+</goal>
+
+A fresh view follows. Answer it with one tool call: steer, done or let_it_run.`;
+
+/**
+ * The three verdicts. These live in the tool descriptions, which the API sends at every model call,
+ * so they are the only instructions here that a supervisor compaction cannot lose.
+ */
+export const TOOL_LET_IT_RUN =
+  "Use when the current worker view gives quoted evidence that no instruction is needed."
+  + " The call sends no message to the worker. Call it once, then end the current supervisor response."
+  // Repeated here because a tool description survives a compaction and the brief does not. The
+  // live failure was a let_it_run reasoned "human is actively directing", two hours before dawn.
+  + " A human message does not end supervision; only an explicit stop command ends supervision.";
+
+/**
+ * How a look ends, and it must appear in every verdict's result.
+ *
+ * A tool result reads as a prompt to act again. A turn ends only when the assistant writes text and
+ * calls no tool, so a result that does not name that exit leaves another tool call as the only move.
+ * The let_it_run result used to say "Say nothing more until the next view arrives", which forbids the
+ * exit outright: session 019ffa73 answered with a second let_it_run on all sixteen looks before 11:05Z
+ * and aborted every one. The steer result said nothing about ending, and cost a spare let_it_run on
+ * 22 of 22 steers in the fifteen hours after.
+ */
+export const END_TURN =
+  `End the current supervisor response now: write one short line or no text, then make no further tool call.`;
+
+export const LET_IT_RUN_ACK = (reason: string, workerStopped = false) =>
+  `No supervisor instruction was sent for the current worker view. Supervisor-provided reason, not independently verified: ${reason}\n\nThe supervisor has completed its verdict for the current worker view. ${END_TURN}
+${workerStopped ? STOPPED_WARNING : "A later worker view starts the next supervisor review."}`;
+
+/**
+ * Added to the let_it_run result when the view said the worker had stopped.
+ *
+ * Session 019ffa73, 2026-08-14: the worker stopped, the supervisor answered let_it_run "waiting for
+ * the worker to re-queue", and both sat still for two and a half hours. A stopped worker does not
+ * resume on its own, so letting it run leaves it stopped. The timer now looks again either way, and
+ * this says why that look will show the same thing.
+ */
+export const STOPPED_WARNING =
+  `The current worker view reports that worker execution stopped. A stopped worker does not resume
+without a new user or supervisor message. If the goal remains unmet, send a concrete continuation
+instruction. A human message does not end supervision. A later worker view will report the worker state.`;
+
+/** The answer to a second let_it_run in one look. Costs a round trip and no error line. */
+export const LET_IT_RUN_AGAIN =
+  `The supervisor already recorded a verdict for the current worker view. This second let_it_run call
+sent no instruction. ${END_TURN}`;
+
+/** The answer after a supervisor directive is sent. A repeat warning is appended after it. */
+export const STEER_ACK = (round: number, workerId: string) =>
+  `Supervisor instruction ${round} was sent to worker session ${workerId}. Worker receipt and execution
+are not confirmed. The supervisor has completed its verdict for the current worker view. ${END_TURN}`;
+export const TOOL_STEER =
+  "Send one concrete next action to the worker. The extension sends the message to the paired worker session; worker receipt and execution require a later worker view.";
+export const TOOL_DONE =
+  "Declare the goal met and stop supervising. Only call this with quoted evidence from the view.";
+
+/**
+ * Sent with every view, so it is deliberately short.
+ *
+ * What used to be here and is now sent once: the verdict rules (BRIEF, and the tool descriptions,
+ * which survive a compaction) and the instructions already sent (the supervisor's own steer calls
+ * are in its context; the steer tool warns about a repeat when it happens). A multi-line goal
+ * stays as a one-line locator inside the view.
+ *
+ * A check in is not a decision point. Interrupting a working agent is expensive and usually wrong,
+ * so the two triggers ask for different things.
+ */
+/**
+ * The two openers, and the test the context pruner uses to find a view it can drop.
+ *
+ * They are constants because two things read them: the nudge that writes a view, and the pruner
+ * that later collapses it. Matching the prose in two places would let them drift silently, and a
+ * pruner that stops recognising views just quietly stops working.
+ */
+export const VIEW_STOPPED = "The worker stopped.";
+export const VIEW_CHECKIN = "Checking in on the worker, which is still going.";
+export const isViewText = (text: string) => text.startsWith(VIEW_STOPPED) || text.startsWith(VIEW_CHECKIN);
+
+/** What an old view is replaced with. Short, and it says where the content went. */
+export const VIEW_PRUNED =
+  "[an earlier view of the worker, dropped once you had judged it. Your verdict on it follows.]";
+
+export const REVIEW_NUDGE = (view: string, rounds: number, stopped: boolean) =>
+  stopped
+    ? `${VIEW_STOPPED}
+
+${view}
+
+${rounds} instructions so far. The status line says how long it has had no new turn. It will not start
+again by itself, and the human being present does not count as somebody driving it. Answer with one
+tool call: steer, done or let_it_run. The word on its own does nothing; only the call reaches the
+worker.`
+    : `${VIEW_CHECKIN}
+
+${view}
+
+Call let_it_run unless the view gives concrete evidence that the worker needs an instruction.`;
+
+/** Refusal shown when done is called while the worker still has work running. */
+export const DONE_BLOCKED = (what: string) =>
+  `Cannot finish: the worker still has work running (${what}). Wait for the next view.`;
+
+/** Refusal shown when the supervisor tries to steer with no goal set. */
+export const NO_GOAL = `No goal is set, so you must not steer or finish. Inventing a task is worse
+than doing nothing. Either call set_goal with the goal you infer from the worker's view, which
+tells the human what you chose, or reply in plain text asking them for it. Your reply reaches
+their phone.`;
+
+/**
+ * Default supervisor prompt. A project SUPERVISOR.md overrides it, same as @monotykamary/pi-supervisor.
+ * Unlike that extension there is no JSON verdict to parse, because the verdict is a tool call.
+ */
+export const DEFAULT_SUPERVISOR_PROMPT = `You supervise a coding agent from outside its session.
+Your job is to make it reach the goal without the human stepping in.
+
+Judge from the view only. You cannot see the worker's files unless you read them yourself.
+
+Call steer when the work is incomplete, when the worker asked a question you can answer with a
+sensible default, or when it claims success without evidence. One concrete next action per steer.
+Never repeat a steer that had no effect; change the approach instead.
+
+The view line "child pi processes still running" means the worker delegated to a subagent that is
+still working. It stopped, the subagent did not. Do not call done, it will be refused. Steer the
+worker to wait for that subagent and report what it produced.
+
+The view line "no new file or commit for N reviews in a row" means your last N instructions
+moved nothing the worker's session can show. Two or more is your signal to change approach, ask the
+human, or check whether the goal is already met. Sometimes it is honest work on one file, so read
+the recent turns before you decide.
+
+Call done only when all of these hold:
+1. the worker named the artifact file it produced, with a path
+2. the worker quoted text from that file, rather than summarising it
+3. nothing in the view contradicts the claim
+
+A confident summary is not evidence. When in doubt, steer.
+
+When the worker does machine learning or data research, a wrong result looks exactly like a right
+one. These steers come from wassname's ml-debug skill, roughly in the order they bite. Each one is
+something you can see in the view.
+- It concluded without reading its data. Steer it to paste the lines it read into the chat, a raw
+  sample and the metric line, not a summary of them. Quoting is the point, twice over: you and the
+  human can then check the same text, and an agent that has to quote has to look (Karpathy inspects
+  the data before touching the model; Nanda: read your data, often it is quite bad). A conclusion
+  with no quoted output, a ranking with no per-item evidence, or "the method failed" with no sample
+  of what the output looked like, all mean it has not looked.
+- It reports a surprising win. Most true results are boring, so an exciting one is more likely to
+  be false (Neel Nanda). Steer it to rule out a bug, leakage or a broken evaluation first.
+- It reports a failure and moves on, or calls the failure a property of the method. Assume a bug:
+  bugs are far more common, and far cheaper to find, than a real negative result (Andy Jones).
+  Steer it to write two or three diagnoses, one of them a bug in its own code, put a rough
+  probability on each, and run the cheapest test that tells them apart. Broken research code fails
+  silently and still runs, so "it ran" is not evidence that it worked.
+- It is about to start another long run without saying what each outcome would mean. Steer it to
+  write that prediction first (Rahtz: think more, experiment less). On a shared GPU that is the
+  cheapest hour you can buy.
+- It compares two methods from one run each. Seed variance alone splits identical configurations
+  into different distributions (Henderson), so steer it to say what varies before it ranks
+  anything.
+- It changed two things in one run and credits one of them. Changing anything changes everything
+  (Sculley et al., CACE). Steer it to say what it can actually attribute, or to rerun with one
+  change.
+- It saw a number it cannot explain and carried on. An anomaly it did not go looking for is the
+  cheapest bug it will ever find, so steer it to chase that before anything else.
+
+Three more ways work gets faked, from @monotykamary/pi-supervisor's cheating list. Steer, and ask
+for the output that would settle it.
+- the worker edits a test to weaken an assertion, or skips a failing one, and calls that progress
+- it reports a number without the command output it came from, or edits the measurement instead of
+  the thing being measured
+- it runs a smaller dataset or part of the suite, then reports as if it ran the whole thing
+
+Do not answer questions that need real human knowledge: passwords, credentials, spending money,
+or a choice between two designs the human cares about. For those, reply in plain text saying what
+you need. Your reply reaches the human's phone.`;

package/src/protocol.ts

@@ -0,0 +1,110 @@
+/**
+ * What the two sessions say to each other over the pi-intercom extension channel.
+ *
+ * The channel never enters a transcript and never starts a turn, so each side triggers its own
+ * turn locally with pi.sendUserMessage after it receives one of these.
+ */
+
+export const NAMESPACE = "wassname/pi-intercom-supervisor/v1";
+
+// No round cap, no budget, on purpose. Supervision runs until the human stops it with
+// /supervise stop, because premature stopping is the failure this whole thing exists to prevent
+// (wassname's SUPERVISOR.md, citing arXiv:2410.07095: 8.7% vs 0.8% on MLE-bench).
+
+export type Wire =
+  /** Roll call, broadcast, so "to" is the wildcard rather than a session. Only /supervise sends it. */
+  | { t: "who"; to: "*" }
+  /** The answer to a roll call: I load this extension, I am free, and I am not a child run. */
+  | { t: "here"; to: string }
+  | { t: "pair"; to: string; goal: string }
+  | { t: "paired"; to: string }
+  | { t: "goal"; to: string; goal: string }
+  /** stopped: the worker settled, so this is a decision point. false: a check in mid-turn. */
+  | { t: "view"; to: string; view: string; stopped: boolean }
+  /** Supervisor asks for a view now. Its own turn cannot make one: the worker publishes them. */
+  | { t: "look"; to: string }
+  | { t: "directive"; to: string; text: string }
+  | { t: "done"; to: string; reason: string }
+  | { t: "unpair"; to: string };
+
+/** Validates the field each kind carries, so a malformed peer cannot inject "[supervisor] undefined". */
+export function isWire(payload: unknown): payload is Wire {
+  if (typeof payload !== "object" || payload === null) return false;
+  const { t, to, goal, view, stopped, text, reason } = payload as Record<string, unknown>;
+  if (typeof to !== "string") return false;
+  if (t === "pair" || t === "goal") return typeof goal === "string";
+  if (t === "view") return typeof view === "string" && typeof stopped === "boolean";
+  if (t === "directive") return typeof text === "string" && text.trim().length > 0;
+  if (t === "done") return typeof reason === "string";
+  return t === "unpair" || t === "paired" || t === "look" || t === "who" || t === "here";
+}
+
+/**
+ * Words two instructions share, over the words either uses. Stopwords and short words dropped.
+ *
+ * Six remembered instructions do not stop repetition, because the same order rephrased reads as
+ * new. This catches the rephrasing that shares vocabulary; it cannot catch a true paraphrase.
+ */
+export function overlap(a: string, b: string): number {
+  const words = (s: string) =>
+    new Set(
+      s
+        .toLowerCase()
+        .split(/[^a-z0-9_./-]+/)
+        .filter((w) => w.length > 3 && !STOPWORDS.has(w)),
+    );
+  const [x, y] = [words(a), words(b)];
+  if (!x.size || !y.size) return 0;
+  const shared = [...x].filter((w) => y.has(w)).length;
+  return shared / (x.size + y.size - shared);
+}
+
+const STOPWORDS = new Set([
+  "then", "with", "that", "this", "from", "into", "your", "each", "have", "then", "should", "please",
+  "make", "sure", "also", "them", "they", "what", "when", "here", "there", "which", "will", "would",
+]);
+
+/**
+ * Two instructions sharing this much vocabulary get flagged back to the supervisor.
+ *
+ * Measured on rewordings of one instruction: about 0.44. On two different instructions: under 0.2.
+ * A true paraphrase that shares no words scores 0 and slips through, so this is a floor on
+ * repetition, not a bound.
+ */
+export const OVERLAP_WARN = 0.4;
+
+export interface SuperviseState {
+  role: "none" | "worker" | "supervisor";
+  /** Intercom session ID of the other side. The broker stamps this, so it cannot be forged. */
+  pairedId: string;
+  goal: string;
+  steerRounds: number;
+  /** Recent steer texts, so the supervisor can see repetition after its own context is compacted. */
+  recentSteers: string[];
+}
+
+export const EMPTY_STATE: SuperviseState = {
+  role: "none",
+  pairedId: "",
+  goal: "",
+  steerRounds: 0,
+  recentSteers: [],
+};
+
+/** How many past steers to keep and show back. Enough to spot a loop, small enough to stay cheap. */
+export const STEER_MEMORY = 6;
+
+/** Session entry type used to persist state, so a compaction or reload cannot reset the count. */
+export const STATE_ENTRY = "supervise-state";
+
+/** Rebuild state from session entries. The last one written wins. */
+export function restoreState(entries: Array<{ type: string; customType?: string; data?: unknown }>): SuperviseState {
+  let state = EMPTY_STATE;
+  for (const entry of entries) {
+    if (entry.type === "custom" && entry.customType === STATE_ENTRY && entry.data) {
+      // Merge over the defaults so a record written before a field existed still loads.
+      state = { ...EMPTY_STATE, ...(entry.data as Partial<SuperviseState>) };
+    }
+  }
+  return state;
+}

package/src/subagents.ts

@@ -0,0 +1,38 @@
+/**
+ * Child pi processes, so a settled worker with a subagent still running is not called finished.
+ *
+ * The in-session check only sees tool calls that never got a result. A subagent spawned as its own
+ * process leaves no such trace, so the worker settles and the view looks quiet.
+ *
+ * This is a snapshot, not a wait. The original polls here for up to two minutes, and pi awaits the
+ * settle handler (agent-session.js:330), so that holds the worker's own settle for the whole poll.
+ * The loop already does the waiting: the supervisor sees the process listed, done is refused, and
+ * it steers instead. That leaves the waiting in the transcript where you can read it.
+ *
+ * Ported from @monotykamary/pi-supervisor (MIT), src/subagent-detector.ts. Extension agnostic: it
+ * does not matter who spawned them. Nothing is caught here, so a broken ps is loud.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+interface PiProcess {
+  pid: number;
+  ppid: number;
+}
+
+async function piProcesses(): Promise<PiProcess[]> {
+  if (process.platform !== "darwin" && process.platform !== "linux") return [];
+  const { stdout } = await execAsync(`ps -eo ppid,pid,comm | grep -E "\\bpi\\b" || true`);
+  return stdout
+    .trim()
+    .split("\n")
+    .map((line) => line.trim().split(/\s+/))
+    .filter((parts) => parts.length >= 3 && parts[2] === "pi")
+    .map((parts) => ({ ppid: Number(parts[0]), pid: Number(parts[1]) }));
+}
+
+export async function childPiProcesses(): Promise<number[]> {
+  return (await piProcesses()).filter((p) => p.ppid === process.pid).map((p) => p.pid);
+}