pi-crew 0.11.6 → 0.11.8

package/src/runtime/process/zombie-scanner.ts

@@ -18,6 +18,22 @@
  * is no longer alive (parent crashed/exited without reaping the child). A sub-agent
  * whose parent is still running is NOT a zombie — it's a legitimate in-flight task.
  *
+ * R3-16 (2026-10-04): a SECOND class — "foreign pi processes" — is detected via
+ * the CLI-entry markers `AI_AGENT=pi` / `PI_CODING_AGENT=true` (SDK docs
+ * environment-variables.md:15-16: both are set at runtime by the CLI/RPC entry
+ * points and inherited by children). Because they are set POST-exec, they show
+ * up in a process's own frozen /proc/<pid>/environ ONLY when that process was
+ * spawned BY another pi process — a top-level interactive main session's
+ * at-exec environ never carries them. Discriminator hierarchy:
+ *   1. `PI_CREW_KIND=subagent` → crew worker (zombies/live arrays, authoritative);
+ *   2. markers + pi-looking argv + not self/not an ancestor → foreign, REPORT ONLY.
+ * The argv gate matters: every shell/tool/MCP-server process pi spawns INHERITS
+ * the markers (uv/python/bash/xclip …), so marker presence alone over-matches.
+ * Residual ambiguity: a pi the USER deliberately starts from inside a pi shell
+ * tool (nested pi) inherits the markers too and is indistinguishable from a
+ * leak. No 100%-reliable discriminator exists for that residue → foreign
+ * entries are a WARN listing with caveat, NEVER offered as kill candidates.
+ *
  * This module is READ-ONLY. It never kills anything. The caller (doctor --zombies)
  * prints the list and asks for explicit confirmation before any kill.
  */
@@ -51,10 +67,29 @@ export interface ZombieScanResult {
 	zombies: ZombieSubagent[];
 	/** Sub-agents whose parent is still alive — shown for transparency, never killed. */
 	live: ZombieSubagent[];
+	/** R3-16: non-crew pi processes carrying the CLI markers
+	 *  (AI_AGENT=pi / PI_CODING_AGENT=true) with a pi-looking argv. REPORT ONLY —
+	 *  never a kill candidate (a user-started nested pi is indistinguishable
+	 *  from a leaked one; see module header). */
+	foreign: ForeignPiProcess[];
 	/** Errors encountered while scanning (per-pid). Never aborts the whole scan. */
 	errors: string[];
 }
 
+export interface ForeignPiProcess {
+	pid: number;
+	ppid: number;
+	/** Parent dead or re-parented to init (ppid=1) — strongest available orphan signal. */
+	orphaned: boolean;
+	/** argv carries headless markers (`--mode json` / `-p` / `--print`) — an
+	 *  interactive TUI session never does; combined with orphaned this is the
+	 *  highest-confidence "likely leak" pair, still WARN-only. */
+	headless: boolean;
+	rssKb: number;
+	elapsedSec: number | undefined;
+	cmd: string;
+}
+
 /** Read /proc/<pid>/environ as a key=value record. Returns {} if unreadable. */
 function readProcEnviron(pid: number): Record<string, string> {
 	try {
@@ -121,12 +156,17 @@ function isPidAlive(pid: number): boolean {
 }
 
 function readProcCmdline(pid: number): string {
+	return readProcCmdlineTokens(pid).join(" ").trim() || `pid ${pid}`;
+}
+
+/** /proc/<pid>/cmdline as argv tokens (NUL-split). Empty array if unreadable. */
+function readProcCmdlineTokens(pid: number): string[] {
 	try {
 		// /proc/<pid>/cmdline is NUL-separated argv.
 		const raw = fs.readFileSync(`/proc/${pid}/cmdline`, "utf-8");
-		return raw.split("\0").filter(Boolean).join(" ").trim() || `pid ${pid}`;
+		return raw.split("\0").filter(Boolean);
 	} catch {
-		return `pid ${pid}`;
+		return [];
 	}
 }
 
@@ -169,13 +209,16 @@ function listCandidatePids(): number[] {
  * has no side effects.
  */
 export function scanZombieSubagents(): ZombieScanResult {
-	const result: ZombieScanResult = { zombies: [], live: [], errors: [] };
+	const result: ZombieScanResult = { zombies: [], live: [], foreign: [], errors: [] };
 	if (process.platform !== "linux") {
 		result.errors.push("zombie scan is Linux-only (/proc required); skipping on " + process.platform);
 		return result;
 	}
 
 	const myUid = tryGetUid();
+	// R3-16: self + ancestors are live hosting sessions (main session / crew
+	// host chain) — never reportable as foreign, even when they carry markers.
+	const ancestors = collectAncestorPids();
 	for (const pid of listCandidatePids()) {
 		try {
 			// Cheap rejection first: only inspect processes we own (avoid scanning system procs).
@@ -185,7 +228,33 @@ export function scanZombieSubagents(): ZombieScanResult {
 			// AUTHORITATIVE GATE: a process is a pi-crew sub-agent ONLY if it carries
 			// PI_CREW_KIND=subagent. The user's main session never sets this, so it can
 			// never be matched — this is the fix for accidentally killing main sessions.
-			if (environ.PI_CREW_KIND !== "subagent") continue;
+			// R3-16: non-crew processes get ONE extra look — the foreign pi branch
+			// below (markers + pi-looking argv, REPORT ONLY); all else is invisible.
+			if (environ.PI_CREW_KIND !== "subagent") {
+				// Exact value match matters: other agents reuse the AI_AGENT name with
+				// their own value (claude-code sets AI_AGENT=claude-code_…_agent), and
+				// marker INHERITORS (shells, MCP servers, xclip) are filtered by the
+				// argv gate below. Crew workers never reach here — the gate above owns
+				// them (pi-crew also scrubs these markers from worker env).
+				const hasPiMarker = environ.AI_AGENT === "pi" || environ.PI_CODING_AGENT === "true";
+				if (hasPiMarker && pid !== process.pid && !ancestors.has(pid)) {
+					const tokens = readProcCmdlineTokens(pid);
+					if (looksLikePiBinary(tokens)) {
+						const foreignStat = readProcStat(pid);
+						const ppid = foreignStat?.ppid ?? 0;
+						result.foreign.push({
+							pid,
+							ppid,
+							orphaned: ppid <= 1 || !isPidAlive(ppid),
+							headless: isHeadlessArgv(tokens),
+							rssKb: readProcRssKb(pid),
+							elapsedSec: foreignStat?.elapsedSec,
+							cmd: readProcCmdline(pid),
+						});
+					}
+				}
+				continue;
+			}
 
 			const crewParentPid = Number.parseInt(environ.PI_CREW_PARENT_PID ?? "", 10);
 			const stat = readProcStat(pid);
@@ -216,9 +285,11 @@ export function scanZombieSubagents(): ZombieScanResult {
 		}
 	}
 
-	// Sort: zombies first by descending RSS (biggest leaks first), live by pid.
+	// Sort: zombies first by descending RSS (biggest leaks first), live by pid;
+	// foreign: orphans first (the likely leaks), then by descending RSS.
 	result.zombies.sort((a, b) => b.rssKb - a.rssKb);
 	result.live.sort((a, b) => a.pid - b.pid);
+	result.foreign.sort((a, b) => Number(b.orphaned) - Number(a.orphaned) || b.rssKb - a.rssKb);
 	return result;
 }
 
@@ -241,6 +312,63 @@ function getProcUid(pid: number): number | undefined {
 	}
 }
 
+function pathBasename(p: string): string {
+	const idx = p.lastIndexOf("/");
+	return idx === -1 ? p : p.slice(idx + 1);
+}
+
+/**
+ * R3-16: does the argv look like the pi CLI binary itself?
+ *
+ * Every process pi spawns (bash, uv, python MCP servers, xclip, …) INHERITS the
+ * AI_AGENT/PI_CODING_AGENT markers, so marker presence alone over-matches the
+ * user's own tool processes. Only pi-looking argv[0..1] counts (argv[0] itself,
+ * or a node-style script path at argv[1]): basename `pi` (covers
+ * /usr/local/bin/pi, .nvm/…/bin/pi, ./pi), `pi-coding-agent`, or a path
+ * containing pi-coding-agent (node …/pi-coding-agent/dist/…). Tokens deeper
+ * than argv[1] are ARGUMENTS (e.g. `bash -c "pi …"`) — never the binary.
+ */
+function looksLikePiBinary(tokens: string[]): boolean {
+	for (const token of tokens.slice(0, 2)) {
+		const base = pathBasename(token);
+		if (base === "pi" || base === "pi-coding-agent" || base === "pi.js") return true;
+		if (token.includes("pi-coding-agent")) return true;
+	}
+	return false;
+}
+
+/** R3-16: headless argv detection — an interactive TUI session never carries these. */
+function isHeadlessArgv(tokens: string[]): boolean {
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i] ?? "";
+		if (token === "-p" || token === "--print" || token === "--mode=json") return true;
+		if (token === "--mode" && tokens[i + 1] === "json") return true;
+	}
+	return false;
+}
+
+/**
+ * R3-16: the scanner's own ancestor chain (self's parent up to init).
+ *
+ * Any pi process on this chain is a LIVE hosting session (the user's main
+ * session / a crew host) and must never be reported — even in the nested case
+ * (worker runs doctor → its parent crew host and the user's main session above
+ * it sit on this chain and carry markers when pi-in-pi). Bounded at 64 hops to
+ * survive a hypothetical pid cycle.
+ */
+function collectAncestorPids(): Set<number> {
+	const chain = new Set<number>();
+	let current = process.ppid;
+	let guard = 0;
+	while (current > 1 && guard++ < 64) {
+		chain.add(current);
+		const stat = readProcStat(current);
+		if (!stat || stat.ppid <= 0) break;
+		current = stat.ppid;
+	}
+	return chain;
+}
+
 /**
  * Render a ZombieScanResult as human-readable text for the doctor report.
  * Explicitly labels main-session safety and never suggests killing live parents.
@@ -252,7 +380,7 @@ export function formatZombieReport(scan: ZombieScanResult): string {
 	lines.push(`Sub-agents identified by PI_CREW_KIND=subagent marker. Main sessions (no marker) are never listed.`);
 	lines.push("");
 
-	if (scan.zombies.length === 0 && scan.live.length === 0) {
+	if (scan.zombies.length === 0 && scan.live.length === 0 && scan.foreign.length === 0) {
 		lines.push("No pi-crew sub-agent processes found.");
 		if (scan.errors.length > 0) {
 			lines.push("");
@@ -284,6 +412,23 @@ export function formatZombieReport(scan: ZombieScanResult): string {
 		lines.push("");
 	}
 
+	if (scan.foreign.length > 0) {
+		lines.push(`### WARN — Foreign pi processes, REPORT ONLY (${scan.foreign.length})`);
+		lines.push("CLI-spawned pi processes (AI_AGENT=pi / PI_CODING_AGENT=true markers) that are");
+		lines.push("NOT pi-crew children. A top-level interactive session never carries these");
+		lines.push("markers in its own environment (the CLI sets them post-exec) — but a pi YOU");
+		lines.push("deliberately started from inside a pi shell looks identical to a leak.");
+		lines.push("NO reliable discriminator exists for that residue: verify cmd / session-dir");
+		lines.push("/ cwd by hand before ever killing one. These are never kill candidates and");
+		lines.push("never feed pane cleanup. This tool never kills.");
+		lines.push("");
+		lines.push("  PID       PPID     STATE             RSS       CMD");
+		for (const f of scan.foreign) {
+			lines.push(formatForeignRow(f));
+		}
+		lines.push("");
+	}
+
 	if (scan.errors.length > 0) {
 		lines.push(`Scan errors (${scan.errors.length}, first 5 shown):`);
 		for (const err of scan.errors.slice(0, 5)) lines.push(`  - ${err}`);
@@ -301,6 +446,14 @@ function formatZombieRow(z: ZombieSubagent): string {
 	return `  ${String(z.pid).padEnd(9)}${String(z.crewParentPid).padEnd(8)}${formatRss(z.rssKb).padEnd(10)}${(z.role ?? "?").padEnd(14)}${surface.padEnd(16)}${z.cmd.slice(0, 44)}`;
 }
 
+/** One table row for the R3-16 foreign section — state carries the triage flags. */
+function formatForeignRow(f: ForeignPiProcess): string {
+	// "orphaned" = parent dead/re-parented to init (strongest leak signal);
+	// "headless" = --mode json / -p argv (never an interactive TUI session).
+	const state = `${f.orphaned ? "orphaned" : "live-parent"}${f.headless ? " headless" : ""}`;
+	return `  ${String(f.pid).padEnd(9)}${String(f.ppid).padEnd(8)}${state.padEnd(17)}${formatRss(f.rssKb).padEnd(10)}${f.cmd.slice(0, 40)}`;
+}
+
 function formatRss(kb: number): string {
 	if (kb >= 1024 * 1024) return `${(kb / 1024 / 1024).toFixed(1)}G`;
 	if (kb >= 1024) return `${(kb / 1024).toFixed(0)}M`;
@@ -308,4 +461,12 @@ function formatRss(kb: number): string {
 }
 
 // Re-export for tests + callers that want to inspect proc helpers in isolation.
-export const __test = { readProcEnviron, isPidAlive, computeElapsedSec };
+export const __test = {
+	readProcEnviron,
+	isPidAlive,
+	computeElapsedSec,
+	readProcCmdlineTokens,
+	looksLikePiBinary,
+	isHeadlessArgv,
+	collectAncestorPids,
+};

package/src/runtime/rpc/README.md

@@ -0,0 +1,139 @@
+# RPC worker transport — W7 (P2-3) EXPERIMENTAL
+
+Opt-in behind `PI_CREW_WORKER_TRANSPORT=rpc`. **WIRED at the run-worker seam as
+of 2026-10-04** (integration phase, lane D6) after the live-fire probe below —
+previously the seam returned a structured not-implemented result. The
+production stdio child-pi path (`child-pi.ts`) is untouched for the default
+transport; the rpc path carries a REDUCED input (see Limitations).
+
+## What this is
+
+A JSONL frame client that speaks the pi SDK's RPC mode protocol
+(`pi --mode rpc`) on stdin/stdout, implementing the two Round-2 design gates
+the adoption review (§R2.5) proved are mandatory for any RPC transport:
+
+1. **`extension_ui_request` drain policy** (`ui-request-policy.ts`) —
+   fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`,
+   `set_editor_text`) are counted per method and dropped. Round-2 live
+   evidence: 15 of the first 16 records a worker emits belong to this family.
+2. **Dialog auto-answer policy** (`cancel` | `block`) — dialog methods
+   (`select`/`confirm`/`input`/`editor`) park a server-side promise that NEVER
+   resolves if unanswered (ask-over-RPC deadlock, R2.5). `cancel` (default)
+   answers the universal safe answer `{type:"extension_ui_response", id,
+   cancelled:true}` (select/input → undefined, confirm → false). `block`
+   leaves it pending on purpose (debug). **There is no auto-confirm mode —
+   deliberate security decision.** An unattended transport must never say
+   "yes" for the user.
+
+Counters (fake-stream asserted): `uiRequestsDrained`, `drainedByMethod`,
+`dialogsCancelled`, `dialogsBlocked`, `malformedFrames`, `responsesMatched`,
+`responsesUnmatched`.
+
+## Deviation from "use SDK RpcClient" — recorded, evidence-based
+
+The task's original phrasing said "transport dùng SDK RpcClient/runRpcMode".
+The verified recon packet (adaptive-07) proved `RpcClient` unusable for this
+prototype and the leader routed the packet through; deviation accepted per
+packet §C:
+
+1. **No public API to answer `extension_ui_request`** — `send`/`process` are
+   private; non-response records go to event listeners only. Gate 2 would
+   require bracket-accessing private members.
+2. **Version skew** — `RpcClient.start()` spawns `node <cliPath ?? "dist/cli.js">`
+   cwd-relative, NOT the host pi binary the stdio transport resolves
+   (`getPiSpawnCommand` / `PI_TEAMS_PI_BIN`).
+3. **Not injectable** — the W7 test requirement ("fake RPC stream, no real
+   spawn") is impossible against `RpcClient`.
+
+`runRpcMode` is a server-side embed API — inapplicable (pi-crew is a spawner,
+not an embedder).
+
+So: **own strict-LF frame loop over the SDK's exported protocol TYPES**
+(`RpcCommand` / `RpcResponse` / `RpcExtensionUIRequest` /
+`RpcExtensionUIResponse` — all imported from `@earendil-works/pi-coding-agent`).
+The framing rule follows the SDK's own `modes/rpc/jsonl.d.ts` spec: split on
+`\n` ONLY. **Node readline is unsafe here** — it also splits on U+2028/U+2029,
+which are legal inside JSON strings. `serializeJsonLine` /
+`attachJsonlLineReader` are not exported top-level, hence the ~15-line
+hand-rolled splitter.
+
+## Config & env
+
+- `runtime.workerTransport: "stdio" (default) | "rpc"` — declared in
+  `src/schema/config-schema.ts` + `src/config/types.ts`. **Config→seam plumbing
+  is NOT wired yet** (needs a `parseRuntimeConfig` line in
+  `config-validation.ts`, which is outside this lane's file ownership);
+  the live gate is env `PI_CREW_WORKER_TRANSPORT` (`runWorker` has no config
+  access — packet §A).
+- `PI_CREW_WORKER_TRANSPORT=rpc` — selects the transport at the
+  `run-worker.ts` seam. WIRED 2026-10-04: calls `runRpcWorker` for real
+  (worker-cap slot semantics identical to stdio; early transport failure →
+  one structured-warn fallback to the stdio path inside the same slot).
+- `PI_CREW_RPC_DIALOG_ANSWER=cancel|block` — GATE 2 policy (default `cancel`,
+  invalid fails safe to `cancel`).
+
+## Why the seam was not wired before 2026-10-04
+
+The original lane was not allowed to live-spawn pi, so a live-wired seam would
+have shipped an end-to-end path that NO test could validate — one env var away
+from silently degrading real runs. The integration phase (this lane) ran the
+live-fire probe FIRST and only then flipped the seam.
+
+## Live-fire probe 2026-10-04 — GREEN → seam wired
+
+Probe setup: real `pi --mode rpc --no-session` spawned by the unmodified
+frame-client default spawner (`getPiSpawnCommand`), scripts importing directly
+from `src/runtime/rpc/` via `node --experimental-strip-types`, PI_CREW_* /
+PI_TEAMS_* env scrubbed, isolated cwd `/tmp/rpc-lf/`, `timeout -k 5 120` per
+run. Raw artifacts (kept on disk): `/tmp/rpc-lf/probe1{,b}.{log,stdout.txt,stderr.txt}`
+(probe1b = default settings model), `probe2.*` (dialog), `probe3.*` (steer).
+
+| # | Item | Result |
+|---|------|--------|
+| a | `extension_ui_request` drain (GATE 1 live) | **24 drained** on probe1b (`setStatus`×20, `setWidget`×3, `notify`×1 — pi-crew widget keys visible in raw frames); 0 malformed, 0 unmatched responses |
+| b | prompt round-trip | ack **24 ms**, `agent_settled` **4.2 s**, `rawFinalText="OK"`, child exit **0**, orderly stdin-end shutdown |
+| c | dialog (confirm) | **executed** (not skipped): a `-e` mini extension opened a real `confirm` → policy `cancel` answered `extension_ui_response {cancelled:true}` → `ui.confirm` resolved `false` → the model literally echoed `"false"`; settled 1.7 s, **no deadlock**, `dialogsCancelled=1` |
+| d | steer mid-turn | `steer` at t+1.6 s → response RTT **53 ms**, disposition **`"queued"`**, final assistant text honored (`"STOP"`), settled 6.5 s, exit 0 |
+
+First run (probe1) used `--thinking off` against a reasoning-only model
+(`chiase/deepseek-v4.1-flash`, thinkingLevelMap has only `max`) → the assistant
+message came back `content: []` with usage 0. Not a frame-client defect — the
+turn still completed and settled — but a live argv caveat: **do not pass
+`--thinking off` to reasoning-only models**; the wired seam passes the model
+raw and never emits `--thinking`.
+
+### Limitations of the wired rpc path (honest list)
+
+- Input mapping is the minimal prototype surface: `cwd`/`task`/`model`/`signal`.
+  Agent config, system-prompt files, skills, transcript path, steering file,
+  lifecycle/stdout callbacks, `maxTurns`/`graceTurns` remain **stdio-only**.
+- The model string is passed RAW (`--model <model>`), no `applyThinkingSuffix`
+  composition — thinking level comes from the settings default.
+- Workers are ephemeral (`--no-session`): no deterministic session identity
+  (`--session-id`/`--session-dir`, W2 crash recovery) for rpc yet. Attaching a
+  worker to the cwd project's default session would pollute the user's session.
+- `runtime.workerTransport` config key is still NOT plumbed to the seam
+  (needs a `parseRuntimeConfig` line in `config-validation.ts`, outside the
+  lane's ownership); the env var is the only live gate.
+- Early-failure fallback: only a result with `error` set, NO `rawFinalText`,
+  and NOT aborted is retried on stdio (double-execution guard,
+  `isEarlyRpcTransportFailure` in run-worker.ts).
+
+## Files
+
+- `frame-client.ts` — strict-LF JSONL frame client, pending-command map with
+  per-command timeout, malformed-frame resilience (count + drop, never throw),
+  orderly stop (stdin end → exit → SIGKILL fallback, kill-once guard).
+- `ui-request-policy.ts` — the two design gates + counters.
+- `rpc-worker.ts` — env resolvers (`resolveWorkerTransport`,
+  `resolveDialogAnswerPolicy`), the live-fire argv builder
+  (`buildRpcWorkerArgv`) + the `runRpcWorker` runner the seam calls.
+
+## Production-ready? Honestly: NOT for general agent configs.
+
+Live-fire validated for the probe scenarios above (small prompt, one confirm
+dialog, one steer, plain model, default extensions). The stdio transport
+remains the default and the only complete path (agent config, system prompts,
+skills, session identity, retries semantics). Do not enable
+`PI_CREW_WORKER_TRANSPORT=rpc` outside experiments until the Limitations
+list above shrinks.