pi-crew 0.9.5 → 0.9.8

package/src/runtime/zombie-scanner.ts

@@ -0,0 +1,297 @@
+/**
+ * zombie-scanner.ts — safely detect orphaned pi-crew sub-agent processes.
+ *
+ * LESSON (learned the hard way): a heuristic like "old `pi` process + high RSS +
+ * orphaned (ppid=1/bash)" will match a user's interactive MAIN session just as
+ * readily as a real zombie. The result is a live main session being killed by
+ * accident. This module replaces that heuristic with an authoritative signal.
+ *
+ * Authoritative marker (set by buildPiWorkerArgs on every child-pi spawn):
+ *   - argv:   `--crew-subagent` is the first positional arg
+ *   - env:    `PI_CREW_KIND=subagent` is the machine-readable signal
+ *
+ * A process is a "pi-crew sub-agent" ONLY IF it carries `PI_CREW_KIND=subagent`
+ * in its environment. The user's main `pi` session NEVER has this var, so it can
+ * never be matched here — by construction.
+ *
+ * A sub-agent is a "zombie" ONLY IF its `PI_CREW_PARENT_PID` points at a PID that
+ * 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.
+ *
+ * This module is READ-ONLY. It never kills anything. The caller (doctor --zombies)
+ * prints the list and asks for explicit confirmation before any kill.
+ */
+
+import * as fs from "node:fs";
+
+export interface ZombieSubagent {
+	pid: number;
+	ppid: number;
+	/** PID recorded in PI_CREW_PARENT_PID (may differ from ppid if re-parented to init/bash). */
+	crewParentPid: number;
+	/** Whether the recorded crew parent PID is still alive. */
+	parentAlive: boolean;
+	role: string | undefined;
+	rssKb: number;
+	elapsedSec: number | undefined;
+	cmd: string;
+}
+
+export interface ZombieScanResult {
+	zombies: ZombieSubagent[];
+	/** Sub-agents whose parent is still alive — shown for transparency, never killed. */
+	live: ZombieSubagent[];
+	/** Errors encountered while scanning (per-pid). Never aborts the whole scan. */
+	errors: string[];
+}
+
+/** Read /proc/<pid>/environ as a key=value record. Returns {} if unreadable. */
+function readProcEnviron(pid: number): Record<string, string> {
+	try {
+		// /proc/<pid>/environ is NUL-separated key=value pairs.
+		const raw = fs.readFileSync(`/proc/${pid}/environ`, "utf-8");
+		const out: Record<string, string> = {};
+		for (const entry of raw.split("\0")) {
+			const eq = entry.indexOf("=");
+			if (eq > 0) out[entry.slice(0, eq)] = entry.slice(eq + 1);
+		}
+		return out;
+	} catch {
+		return {};
+	}
+}
+
+/** Read /proc/<pid>/stat to get ppid + elapsed. Returns undefined if unreadable. */
+function readProcStat(pid: number): { ppid: number; elapsedSec: number | undefined } | undefined {
+	try {
+		const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+		// stat format: pid (comm) state ppid ... starttime ...
+		// comm may contain spaces/parens, so parse from the LAST ')' backwards.
+		const closeParen = stat.lastIndexOf(")");
+		if (closeParen < 0) return undefined;
+		const rest = stat.slice(closeParen + 2).trim().split(/\s+/);
+		// rest[0] = state, rest[1] = ppid
+		const ppid = Number.parseInt(rest[1] ?? "", 10);
+		// starttime (clock ticks since boot) is field 22 in the full stat → index 19 in `rest`
+		const starttimeTicksRaw = Number.parseInt(rest[19] ?? "", 10);
+		const starttimeTicks = Number.isFinite(starttimeTicksRaw) ? starttimeTicksRaw : undefined;
+		const elapsedSec = computeElapsedSec(starttimeTicks);
+		return { ppid: Number.isFinite(ppid) ? ppid : 0, elapsedSec };
+	} catch {
+		return undefined;
+	}
+}
+
+function computeElapsedSec(starttimeTicks: number | undefined): number | undefined {
+	if (starttimeTicks === undefined || !Number.isFinite(starttimeTicks)) return undefined;
+	try {
+		// Linux CLK_TCK is virtually always 100 (sysconf(_SC_CLK_TCK)). Reading it
+		// portably from Node requires a native addon; hardcoding 100 matches every
+		// mainstream Linux distro and keeps this dependency-free.
+		const ticksPerSec = 100;
+		// /proc/uptime: first field is seconds since boot.
+		const uptimeRaw = fs.readFileSync("/proc/uptime", "utf-8");
+		const uptimeSec = Number.parseFloat(uptimeRaw.split(" ")[0] ?? "");
+		if (!Number.isFinite(uptimeSec)) return undefined;
+		// starttime (ticks since boot) → process age in seconds = uptime - starttime/ticksPerSec.
+		const startAgeSec = starttimeTicks / ticksPerSec;
+		return Math.max(0, uptimeSec - startAgeSec);
+	} catch {
+		return undefined;
+	}
+}
+
+function isPidAlive(pid: number): boolean {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		// process.kill(pid, 0) throws if the pid is not alive (or not ours).
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function readProcCmdline(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}`;
+	} catch {
+		return `pid ${pid}`;
+	}
+}
+
+function readProcRssKb(pid: number): number {
+	try {
+		const status = fs.readFileSync(`/proc/${pid}/status`, "utf-8");
+		const match = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
+		return match ? Number.parseInt(match[1] ?? "", 10) : 0;
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * Enumerate candidate pi-crew sub-agent PIDs under the current uid.
+ *
+ * Reads /proc directly (Linux only) — no shelling out to pgrep/ps, so the
+ * result is deterministic and unaffected by shell quoting or locale. On
+ * non-Linux platforms the scanner returns an empty result with a note in
+ * `errors` (zombie detection is best-effort; the doctor report still renders).
+ */
+function listCandidatePids(): number[] {
+	if (process.platform !== "linux") return [];
+	const pids: number[] = [];
+	try {
+		for (const entry of fs.readdirSync("/proc")) {
+			if (/^\d+$/.test(entry)) pids.push(Number.parseInt(entry, 10));
+		}
+	} catch {
+		// /proc unreadable (e.g. sandboxed). Caller surfaces via errors[].
+	}
+	return pids;
+}
+
+/**
+ * Scan for orphaned pi-crew sub-agent processes. READ-ONLY — never kills.
+ *
+ * Returns the full picture: zombies (parent dead), live (parent alive), and
+ * any scan errors. Callers decide what to do with the result; this module
+ * has no side effects.
+ */
+export function scanZombieSubagents(): ZombieScanResult {
+	const result: ZombieScanResult = { zombies: [], live: [], errors: [] };
+	if (process.platform !== "linux") {
+		result.errors.push("zombie scan is Linux-only (/proc required); skipping on " + process.platform);
+		return result;
+	}
+
+	const myUid = tryGetUid();
+	for (const pid of listCandidatePids()) {
+		try {
+			// Cheap rejection first: only inspect processes we own (avoid scanning system procs).
+			if (myUid !== undefined && getProcUid(pid) !== myUid) continue;
+
+			const environ = readProcEnviron(pid);
+			// 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;
+
+			const crewParentPid = Number.parseInt(environ.PI_CREW_PARENT_PID ?? "", 10);
+			const stat = readProcStat(pid);
+			const entry: ZombieSubagent = {
+				pid,
+				ppid: stat?.ppid ?? 0,
+				crewParentPid: Number.isFinite(crewParentPid) ? crewParentPid : 0,
+				parentAlive: Number.isFinite(crewParentPid) && isPidAlive(crewParentPid),
+				role: environ.PI_CREW_ROLE,
+				rssKb: readProcRssKb(pid),
+				elapsedSec: stat?.elapsedSec,
+				cmd: readProcCmdline(pid),
+			};
+
+			if (entry.parentAlive) {
+				result.live.push(entry);
+			} else {
+				result.zombies.push(entry);
+			}
+		} catch (error) {
+			// Race: process may have exited between readdir and read. Don't abort the scan.
+			result.errors.push(`pid ${pid}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	// Sort: zombies first by descending RSS (biggest leaks first), live by pid.
+	result.zombies.sort((a, b) => b.rssKb - a.rssKb);
+	result.live.sort((a, b) => a.pid - b.pid);
+	return result;
+}
+
+function tryGetUid(): number | undefined {
+	try {
+		return process.getuid?.();
+	} catch {
+		return undefined;
+	}
+}
+
+function getProcUid(pid: number): number | undefined {
+	try {
+		// /proc/<pid>/status has Uid: <real> <eff> <sav> <fs>
+		const status = fs.readFileSync(`/proc/${pid}/status`, "utf-8");
+		const match = status.match(/^Uid:\s+(\d+)/m);
+		return match ? Number.parseInt(match[1] ?? "", 10) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Render a ZombieScanResult as human-readable text for the doctor report.
+ * Explicitly labels main-session safety and never suggests killing live parents.
+ */
+export function formatZombieReport(scan: ZombieScanResult): string {
+	const lines: string[] = [];
+	lines.push("## Zombie sub-agent scan (read-only — nothing killed)");
+	lines.push("");
+	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) {
+		lines.push("No pi-crew sub-agent processes found.");
+		if (scan.errors.length > 0) {
+			lines.push("");
+			lines.push(`Scan notes (${scan.errors.length}):`);
+			for (const err of scan.errors.slice(0, 5)) lines.push(`  - ${err}`);
+		}
+		return lines.join("\n");
+	}
+
+	if (scan.zombies.length > 0) {
+		lines.push(`### Zombies — parent dead (${scan.zombies.length})`);
+		lines.push("These sub-agents are orphaned. Safe to kill after review:");
+		lines.push("");
+		lines.push("  PID       PARENT  RSS       ROLE          CMD");
+		for (const z of scan.zombies) {
+			lines.push(
+				`  ${String(z.pid).padEnd(9)}${String(z.crewParentPid).padEnd(8)}${formatRss(z.rssKb).padEnd(10)}${(z.role ?? "?").padEnd(14)}${z.cmd.slice(0, 60)}`,
+			);
+		}
+		lines.push("");
+	}
+
+	if (scan.live.length > 0) {
+		lines.push(`### Live — parent still running (${scan.live.length})`);
+		lines.push("NOT zombies. Do not kill (parent PID is alive and may still reap them).");
+		lines.push("");
+		lines.push("  PID       PARENT  RSS       ROLE          CMD");
+		for (const l of scan.live) {
+			lines.push(
+				`  ${String(l.pid).padEnd(9)}${String(l.crewParentPid).padEnd(8)}${formatRss(l.rssKb).padEnd(10)}${(l.role ?? "?").padEnd(14)}${l.cmd.slice(0, 60)}`,
+			);
+		}
+		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}`);
+		lines.push("");
+	}
+
+	lines.push("To kill a zombie: `kill <PID>` (the OS will reap it). This tool never kills.");
+	return lines.join("\n");
+}
+
+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`;
+	return `${kb}K`;
+}
+
+// Re-export for tests + callers that want to inspect proc helpers in isolation.
+export const __test = { readProcEnviron, isPidAlive, computeElapsedSec };

package/src/schema/team-tool-schema.ts

@@ -289,6 +289,26 @@ export const TeamToolParams = Type.Object({
 			},
 		),
 	),
+	tokenBudget: Type.Optional(
+		Type.Number({
+			description:
+				"Per-workflow token budget for dynamic-workflow runs. When set, ctx.agent() auto-rejects with ok:false once exhausted. Accumulated from each agent run's reported usage. Overrides workflow.maxTokenBudget.",
+			minimum: 0,
+		}),
+	),
+	args: Type.Optional(
+		// round-14 P1-5: typed workflow arguments. Type.Any() generates an empty {} schema
+		// (matches any JSON value) which is strict-provider friendly — no array type union.
+		// Description lives in the JSDoc / TeamToolParamsValue below to avoid the
+		// "description-only schema" strict-provider check.
+		Type.Any(),
+	),
+	focus: Type.Optional(
+		Type.String({
+			description:
+				"Sub-focus for the doctor action. 'zombies' runs a READ-ONLY scan for orphaned pi-crew sub-agent processes (identified by PI_CREW_KIND=subagent); it never kills and never matches the user's interactive main session.",
+		}),
+	),
 });
 
 export interface TeamToolParamsValue {
@@ -365,6 +385,10 @@ export interface TeamToolParamsValue {
 	skill?: string | string[] | boolean;
 	scope?: "user" | "project" | "both";
 	config?: Record<string, unknown>;
+	/** Sub-focus for the `doctor` action. `"zombies"` runs a READ-ONLY scan for
+	 *  orphaned pi-crew sub-agent processes (identified by PI_CREW_KIND=subagent);
+	 *  it never kills and never matches the user's interactive main session. */
+	focus?: string;
 	dryRun?: boolean;
 	confirm?: boolean;
 	force?: boolean;
@@ -393,4 +417,8 @@ export interface TeamToolParamsValue {
 	budgetAbort?: number;
 	/** Background dispatch discriminator. Default "team-run". "goal-loop"/"dynamic-workflow" dispatch to their runners (P0/P2). */
 	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
+	/** Per-workflow token budget for dynamic-workflow runs (round-14 P1-2). */
+	tokenBudget?: number;
+	/** Typed workflow arguments for .dwf.ts scripts, accessible via ctx.args<T>() (round-14 P1-5). */
+	args?: unknown;
 }

package/src/skills/discover-skills.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { getAgentDir } from "../runtime/peer-dep.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { parseSkillFrontmatter, validateSkillFrontmatter, type SkillValidationError } from "./validate.ts";
 
 const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
 
@@ -54,16 +55,44 @@ function listSkillDirs(cwd: string): Array<{ root: string; source: SkillDescript
 	];
 }
 
-function frontmatterDescription(content: string): string | undefined {
-	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
-	if (!match) return undefined;
-	const line = match[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
-	return line?.slice("description:".length).trim();
+// ── Diagnostics (L3) ──────────────────────────────────────────────────────────
+// Module-level buffer populated each `discoverSkills()` call. Cleared at the
+// start of every call so callers see only the most recent run's diagnostics.
+// Surfaced via `getLastDiscoveryDiagnostics()` so capability-inventory and
+// other consumers can convert silent exclusions into visible feedback.
+let lastDiagnostics: SkillValidationError[] = [];
+
+export function getLastDiscoveryDiagnostics(): SkillValidationError[] {
+	return lastDiagnostics;
+}
+
+/**
+ * Parse frontmatter defensively. Falls back to the legacy line-prefix match
+ * if YAML parsing fails — preserves back-compat for malformed but readable
+ * SKILL.md files that pre-date the validator (we record a diagnostic in that
+ * case but still return the description we could salvage).
+ */
+function readDescription(content: string): { description: string; parseError: string | null } {
+	const parsed = parseSkillFrontmatter(content);
+	if (parsed.ok) {
+		const d = parsed.data.description;
+		return { description: typeof d === "string" ? d : "", parseError: null };
+	}
+	// YAML parse failed — fall back to legacy line-prefix match so we don't
+	// regress existing skills whose frontmatter the old parser could read.
+	const legacyMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (legacyMatch) {
+		const line = legacyMatch[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
+		const fallback = line?.slice("description:".length).trim() ?? "";
+		return { description: fallback, parseError: parsed.error };
+	}
+	return { description: "", parseError: parsed.error };
 }
 
 export function discoverSkills(cwd: string): SkillDescriptor[] {
 	if (cache && cache.cwd === cwd && Date.now() - cache.cachedAt < CACHE_TTL_MS) return cache.skills;
 	const results: SkillDescriptor[] = [];
+	const diagnostics: SkillValidationError[] = [];
 	for (const dir of listSkillDirs(cwd)) {
 		if (!fs.existsSync(dir.root)) continue;
 		try {
@@ -94,7 +123,16 @@ export function discoverSkills(cwd: string): SkillDescriptor[] {
 						// (e.g. macOS /var → /private/var). Fall through with un-resolved path.
 					}
 					const content = fs.readFileSync(readPath, "utf-8");
-					description = frontmatterDescription(content) ?? "";
+					const { description: desc, parseError } = readDescription(content);
+					description = desc;
+					if (parseError) {
+						diagnostics.push({
+							path: path.dirname(skillMdPath),
+							field: "frontmatter",
+							reason: parseError,
+							severity: "error",
+						});
+					}
 				} catch (error) {
 					logInternalError("discoverSkills.readSkill", error, `skill=${entry.name}`);
 				}
@@ -104,6 +142,21 @@ export function discoverSkills(cwd: string): SkillDescriptor[] {
 			logInternalError("discoverSkills.readdir", error, `root=${dir.root}`);
 		}
 	}
-	cache = { skills: results, cachedAt: Date.now(), cwd };
-	return results;
+	// L3: strict validation pass after we've collected every (skill, source)
+	// candidate. Excludes malformed skills (HYBRID policy: missing/malformed
+	// `name`/`description` hard-fail; unknown props warn). Diagnostics are
+	// always recorded, including for skills that PASSED validation but had
+	// unknown-prop warnings.
+	const filtered: SkillDescriptor[] = [];
+	for (const skill of results) {
+		const validation = validateSkillFrontmatter(path.dirname(skill.path));
+		if (validation.ok) {
+			filtered.push(skill);
+		} else {
+			diagnostics.push(...validation.errors);
+		}
+	}
+	lastDiagnostics = diagnostics;
+	cache = { skills: filtered, cachedAt: Date.now(), cwd };
+	return filtered;
 }