gentle-pi 3.7.0 → 4.1.0

package/tests/agent-risk-escalation.test.ts

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { NATIVE_REVIEW_MODE_SOURCE, type NativeReviewCli } from "../lib/native-review-cli.ts";
+import {
+	decodeAgentRiskEscalation,
+	escalatedRisk,
+	HIGH_RISK_ITEMS,
+	REVIEW_ASSESSMENT_SCHEMA,
+	VERIFICATION_TIER,
+} from "../lib/review-risk-assessment.ts";
+
+// gentle-shell#1494 S6: the agent may raise a candidate's risk to high by
+// citing one item of the shared high-risk list, never lower it. The raise
+// travels inside the existing assess call; no new operation.
+
+test("the high-risk list has exactly the six items of the always-on Task Size section", () => {
+	assert.deepEqual(Object.keys(HIGH_RISK_ITEMS).map(Number), [1, 2, 3, 4, 5, 6]);
+	assert.equal(HIGH_RISK_ITEMS[2], "security");
+	assert.equal(HIGH_RISK_ITEMS[6], "no test would catch a regression");
+});
+
+test("decodeAgentRiskEscalation accepts an item from 1 to 6 with a non-empty reason", () => {
+	assert.deepEqual(decodeAgentRiskEscalation({ item: 2, reason: "weakens the permission check in utils.ts" }), {
+		item: 2,
+		reason: "weakens the permission check in utils.ts",
+	});
+});
+
+test("decodeAgentRiskEscalation rejects unknown items, empty or oversized reasons, and extra fields", () => {
+	for (const bad of [
+		{ item: 0, reason: "x" },
+		{ item: 7, reason: "x" },
+		{ item: 2.5, reason: "x" },
+		{ item: "2", reason: "x" },
+		{ item: 2, reason: "   " },
+		{ item: 2, reason: "x".repeat(501) },
+		{ item: 2, reason: "x", tier: "low" },
+		{ item: 2 },
+		null,
+		"high",
+	]) {
+		assert.throws(() => decodeAgentRiskEscalation(bad), /escalate/, `must reject ${JSON.stringify(bad)}`);
+	}
+});
+
+test("escalatedRisk raises passive and medium to high and never lowers", () => {
+	const escalation = { item: 3 as const, reason: "changes a published export" };
+	assert.equal(escalatedRisk(VERIFICATION_TIER.PASSIVE, escalation), VERIFICATION_TIER.HIGH);
+	assert.equal(escalatedRisk(VERIFICATION_TIER.MEDIUM, escalation), VERIFICATION_TIER.HIGH);
+	assert.equal(escalatedRisk(VERIFICATION_TIER.HIGH, escalation), VERIFICATION_TIER.HIGH);
+	assert.equal(escalatedRisk(VERIFICATION_TIER.UNASSESSABLE, escalation), VERIFICATION_TIER.UNASSESSABLE);
+	for (const tier of Object.values(VERIFICATION_TIER)) assert.equal(escalatedRisk(tier, undefined), tier);
+});
+
+function assessTool(): { execute: (id: string, params: Record<string, unknown>, signal: AbortSignal | undefined, onUpdate: undefined, ctx: ExtensionContext) => Promise<{ details: unknown }> } {
+	const tools = new Map<string, any>();
+	const pi = { on() {}, registerCommand() {}, registerTool(tool: { name: string }) { tools.set(tool.name, tool); } } as unknown as ExtensionAPI;
+	const nativeReviewCli: Partial<NativeReviewCli> = {
+		reviewMode: async () => ({ operation: "status", scope: "clone", status: { global: "off", cloneLocal: "off", effective: "off", source: NATIVE_REVIEW_MODE_SOURCE.GLOBAL } }),
+		assess: async () => ({
+			schema: REVIEW_ASSESSMENT_SCHEMA,
+			risk: "medium",
+			reasons: [],
+			changedPaths: 1,
+			changedLines: 3,
+			candidate: { kind: "current-changes", baseRef: undefined },
+		}),
+	};
+	createGentleAiExtension({ nativeReviewCli: nativeReviewCli as NativeReviewCli })(pi);
+	return tools.get("gentle_review");
+}
+
+const ctx = { cwd: process.cwd() } as ExtensionContext;
+
+test("gentle_review assess: an agent escalation raises a medium candidate to high and records why", async () => {
+	const tool = assessTool();
+	const input = JSON.stringify({ writerModelId: "openai/gpt-6.1-sol", writerEffort: "high", escalate: { item: 2, reason: "weakens the permission check in utils.ts" } });
+	const { details } = await tool.execute("esc-1", { operation: "assess", input }, undefined, undefined, ctx);
+	const plan = details as { risk: string; nativeRisk: string; agentEscalation: { item: number; label: string; reason: string }; plan: { independentVerifier: boolean } };
+	assert.equal(plan.nativeRisk, "medium");
+	assert.equal(plan.risk, VERIFICATION_TIER.HIGH);
+	assert.deepEqual(plan.agentEscalation, { item: 2, label: "security", reason: "weakens the permission check in utils.ts", applied: true });
+	assert.equal(plan.plan.independentVerifier, true, "a raised candidate always gets the independent verifier");
+});
+
+test("gentle_review assess: without an escalation the native tier stands", async () => {
+	const tool = assessTool();
+	const input = JSON.stringify({ writerModelId: "openai/gpt-6.1-sol", writerEffort: "high" });
+	const { details } = await tool.execute("esc-2", { operation: "assess", input }, undefined, undefined, ctx);
+	const plan = details as { risk: string; nativeRisk: string; agentEscalation?: unknown; plan: { independentVerifier: boolean } };
+	assert.equal(plan.risk, "medium");
+	assert.equal(plan.nativeRisk, "medium");
+	assert.equal(plan.agentEscalation, undefined);
+	assert.equal(plan.plan.independentVerifier, false);
+});
+
+test("gentle_review assess: a malformed escalation is rejected instead of ignored", async () => {
+	const tool = assessTool();
+	await assert.rejects(
+		() => tool.execute("esc-3", { operation: "assess", input: JSON.stringify({ escalate: { item: 9, reason: "x" } }) }, undefined, undefined, ctx),
+		/escalate/,
+	);
+});
+
+test("the rule text tells the agent when and how to escalate, and that it never lowers", async () => {
+	const { readFileSync } = await import("node:fs");
+	const verification = readFileSync(new URL("../assets/orchestrator-verification.md", import.meta.url), "utf8");
+	const tracking = readFileSync(new URL("../assets/orchestrator-tracking.md", import.meta.url), "utf8");
+	const extension = readFileSync(new URL("../extensions/gentle-ai.ts", import.meta.url), "utf8");
+	assert.match(verification, /"escalate": \{"item": <1-6>, "reason": "<one line>"\}/);
+	assert.match(verification, /never lowers a tier/);
+	assert.match(tracking, /assess `escalate` field \(`orchestrator-verification\.md`\); never lower one/);
+	assert.match(extension, /\{"escalate":\{"item":1-6,"reason":"<one line>"\}\}/);
+});
+
+test("gentle_review assess: agentEscalation says whether the escalation changed the tier", async () => {
+	const tool = assessTool();
+	const input = JSON.stringify({ escalate: { item: 4, reason: "reorders an async write" } });
+	const { details } = await tool.execute("esc-5", { operation: "assess", input }, undefined, undefined, ctx);
+	assert.equal((details as { agentEscalation: { applied: boolean } }).agentEscalation.applied, true, "medium raised to high is applied");
+});

package/tests/agents-completion-delivery.test.ts

@@ -92,3 +92,20 @@ test("dropAll discards pending, consumed, and delivered state", () => {
 	queue.enqueue(task("t1"), 5000);
 	assert.deepEqual(queue.takeDeliverable(5000).map((entry) => entry.task.id), ["t1"], "the queue is fresh after dropAll");
 });
+
+test("requeue returns a failed delivery once, keeps its settle time, and respects consume", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.enqueue(task("t1"), 1000);
+	queue.enqueue(task("t2"), 1000);
+	const [first, second] = queue.takeDeliverable(2000);
+	queue.requeue(first!);
+	queue.requeue(first!);
+	queue.requeue(second!);
+	queue.consume("t2");
+	const retried = queue.takeDeliverable(1000 + STALE_COMPLETION_MS);
+	assert.deepEqual(retried.map((entry) => entry.task.id), ["t1"], "a double requeue yields one entry and a consumed one is dropped");
+	assert.equal(retried[0]!.settledAt, 1000, "the original settle time is kept");
+	assert.equal(retried[0]!.stale, true, "a retried completion can become stale");
+	queue.enqueue(task("t1"), 5000);
+	assert.deepEqual(queue.takeDeliverable(5000), [], "a delivered retry is still delivered at most once");
+});

package/tests/agents-fake-child.ts

@@ -9,7 +9,7 @@ export interface FakeChild {
 	child: ChildLike;
 	written: Array<Record<string, unknown>>;
 	emit(event: Record<string, unknown>): void;
-	exit(code: number): void;
+	exit(code: number | null, signal?: string | null): void;
 	fail(message: string): void;
 	killed: string[];
 	sent: Array<Record<string, unknown>>;
@@ -62,5 +62,5 @@ export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}):
 			return child;
 		},
 	};
-	return { child, written, killed, sent, get disconnects() { return disconnects; }, message: (event) => emitter.emit("message", event), emit: (event) => stdout.write(`${JSON.stringify(event)}\n`), exit: (code) => emitter.emit("exit", code, null), fail: (message) => emitter.emit("error", new Error(message)) };
+	return { child, written, killed, sent, get disconnects() { return disconnects; }, message: (event) => emitter.emit("message", event), emit: (event) => stdout.write(`${JSON.stringify(event)}\n`), exit: (code, signal = null) => emitter.emit("exit", code, signal), fail: (message) => emitter.emit("error", new Error(message)) };
 }

package/tests/agents-message-delivery.test.ts

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createAgentMessageQueue, STALE_NOTIFICATION_MS } from "../lib/agents-message-delivery.ts";
+
+test("delivers live notifications and queries in order for the active session", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "First progress", 1000);
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Which branch?", 1050);
+
+	assert.equal(queue.pendingCount(), 2);
+	const deliverable = queue.takeDeliverable(1100, "s1", () => true);
+	assert.equal(deliverable.length, 2);
+
+	assert.equal(deliverable[0]?.kind, "notification");
+	assert.equal(deliverable[0]?.content, "First progress");
+	assert.equal(deliverable[0]?.display, false);
+
+	assert.equal(deliverable[1]?.kind, "query");
+	assert.match(deliverable[1]?.content ?? "", /Which branch\?/);
+	assert.equal(deliverable[1]?.display, true);
+	assert.equal(deliverable[1]?.requestId, "q1");
+
+	assert.equal(queue.pendingCount(), 0);
+	assert.equal(queue.takeDeliverable(1200, "s1", () => true).length, 0, "messages are delivered at most once");
+});
+
+test("a notification from a task that settled before delivery is dropped silently", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "Late notice", 1000);
+
+	// The task finishes and is invalidated before the parent turn boundary.
+	queue.invalidateTask("task-1");
+
+	const deliverable = queue.takeDeliverable(1050, "s1", () => false);
+	assert.equal(deliverable.length, 0, "notification from settled task must never enter conversation");
+});
+
+test("an answered query is consumed and never delivered", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Which target?", 1000);
+
+	// Parent replies before queue flush.
+	queue.consumeQuery("task-1", "q1");
+
+	const deliverable = queue.takeDeliverable(1050, "s1", () => true);
+	assert.equal(deliverable.length, 0, "answered query must not be delivered");
+});
+
+test("an expired query is dropped and never delivered", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Need approval", 1000);
+
+	// Query times out.
+	queue.expireQuery("task-1", "q1");
+
+	const deliverable = queue.takeDeliverable(1050, "s1", () => true);
+	assert.equal(deliverable.length, 0, "expired query must not be delivered");
+});
+
+test("a notification exceeding the stale window is dropped", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "Slow notice", 1000);
+
+	// Held past the 90-second threshold.
+	const deliverable = queue.takeDeliverable(1000 + STALE_NOTIFICATION_MS + 10, "s1", () => true);
+	assert.equal(deliverable.length, 0, "stale notification must not be delivered");
+});
+
+test("isTaskLive returning false drops messages for non-live tasks", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "Dead task notice", 1000);
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Dead task query", 1000);
+
+	const deliverable = queue.takeDeliverable(1050, "s1", (id) => id !== "task-1");
+	assert.equal(deliverable.length, 0, "non-live task messages must be dropped");
+});
+
+test("session mismatch drops foreign session messages", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "session-old" }, "Old session notice", 1000);
+
+	const deliverable = queue.takeDeliverable(1050, "session-new", () => true);
+	assert.equal(deliverable.length, 0, "foreign session message must be dropped");
+});
+
+test("deduplicates identical query requests for the same task and requestId", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "First ask", 1000);
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Duplicate ask", 1001);
+
+	assert.equal(queue.pendingCount(), 1);
+	const deliverable = queue.takeDeliverable(1050, "s1", () => true);
+	assert.equal(deliverable.length, 1);
+	assert.match(deliverable[0]!.content, /First ask/);
+});
+
+test("dropAll clears everything across session reset", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "Notice", 1000);
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Query", 1000);
+	assert.equal(queue.pendingCount(), 2);
+
+	queue.dropAll();
+	assert.equal(queue.pendingCount(), 0);
+	assert.equal(queue.takeDeliverable(1050, "s1", () => true).length, 0);
+});

package/tests/agents-protocol.test.ts

@@ -3,7 +3,9 @@ import test from "node:test";
 import {
 	applyTaskEvent,
 	emptyThread,
+	MISSING_TOOLS_NOTE_PREFIX,
 	normalizeRpcEvent,
+	ToolArgumentProgress,
 	TASK_EVENT,
 	TASK_STATUS,
 	taskLabel,
@@ -12,6 +14,51 @@ import {
 	type TaskRecord,
 } from "../lib/agents-protocol.ts";
 
+test("status observers see only live transitions, remain isolated and cannot fail mutations", () => {
+	const store = new TaskStore();
+	const changes: Array<{ status: string; sequence: number; parentSessionId: string; producerId: string; runId: string }> = [];
+	store.subscribeStatusChanges(() => { throw new Error("listener failure"); });
+	store.subscribeStatusChanges(async () => { throw new Error("async failure"); });
+	const stop = store.subscribeStatusChanges(change => { changes.push(change); });
+	store.restore(record({ id: "restored" }), emptyThread());
+	store.add(record());
+	store.update("t1", { status: TASK_STATUS.RUNNING });
+	store.update("t1", { status: TASK_STATUS.RUNNING, label: "new label" });
+	const ask = { type: TASK_EVENT.ASK, request: { id: "q", method: "input", title: "Question" } } as const;
+	store.apply("t1", ask, 2);
+	store.apply("t1", ask, 3);
+	store.apply("t1", { type: TASK_EVENT.TEXT, text: "answer" }, 4);
+	store.apply("t1", { type: TASK_EVENT.TEXT, text: "more" }, 5);
+	store.add(record({ id: "other", parentSessionId: "s2" }));
+	assert.deepEqual(changes.map(change => change.status), ["queued", "running", "waiting", "running", "queued"]);
+	assert.deepEqual(changes.map(change => change.sequence), [1, 2, 3, 4, 5]);
+	assert.deepEqual(changes.map(change => change.parentSessionId), ["s1", "s1", "s1", "s1", "s2"]);
+	assert.equal(new Set(changes.slice(0, 4).map(change => change.runId)).size, 1);
+	assert.equal(store.get("t1")?.status, "running");
+	const another = new TaskStore();
+	let otherProducer: string | undefined;
+	another.subscribeStatusChanges(change => { otherProducer = change.producerId; });
+	another.add(record());
+	assert.notEqual(otherProducer, changes[0].producerId);
+	stop();
+	store.update("t1", { status: TASK_STATUS.COMPLETED });
+	assert.equal(changes.length, 5);
+});
+
+test("all terminal statuses produce exactly one transition and restore establishes a silent baseline", () => {
+	for (const status of [TASK_STATUS.COMPLETED, TASK_STATUS.FAILED, TASK_STATUS.CANCELLED, TASK_STATUS.TIMED_OUT]) {
+		const store = new TaskStore();
+		const statuses: string[] = [];
+		store.subscribeStatusChanges(change => { statuses.push(change.status); });
+		store.restore(record({ status: TASK_STATUS.RUNNING }), emptyThread());
+		store.update("t1", { status });
+		store.update("t1", { status, result: "report" });
+		store.add(record({ status }));
+		assert.deepEqual(statuses, [status]);
+		assert.equal(store.get("t1")?.status, status);
+	}
+});
+
 // Gentle Agents protocol: the child pi process streams RPC events; the host
 // normalizes them into small typed deltas, applies them to an append-only
 // thread, and notifies only the listeners of the task that changed.
@@ -67,6 +114,56 @@ test("normalizeRpcEvent maps pi RPC events to task deltas and ignores the rest",
 	assert.deepEqual(normalizeRpcEvent("garbage"), []);
 });
 
+// #1690: Pi drops unknown --tools names silently, so the child reports them
+// with one marked notify; only that notify reaches the task thread.
+test("normalizeRpcEvent turns the marked missing-tools notify into a note and drops every other notify", () => {
+	const message = `${MISSING_TOOLS_NOTE_PREFIX} gentle_review_scope, codegraph`;
+	assert.deepEqual(normalizeRpcEvent({ type: "extension_ui_request", id: "u1", method: "notify", message, notifyType: "warning" }), [{ type: TASK_EVENT.NOTE, text: message }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "extension_ui_request", id: "u2", method: "notify", message: "requested tools missing in child: x" }), [], "an unmarked notify stays dropped");
+	assert.deepEqual(normalizeRpcEvent({ type: "extension_ui_request", id: "u3", method: "notify", message: ` ${MISSING_TOOLS_NOTE_PREFIX} x` }), [], "the marker must be a prefix");
+	assert.deepEqual(normalizeRpcEvent({ type: "extension_ui_request", id: "u4", method: "setStatus", statusKey: "k", statusText: `${MISSING_TOOLS_NOTE_PREFIX} x` }), [], "only notify carries the marker");
+	assert.deepEqual(normalizeRpcEvent({ type: "extension_ui_request", id: "u5", method: "notify", message: `${MISSING_TOOLS_NOTE_PREFIX} \u001B[2Jx` }), [{ type: TASK_EVENT.NOTE, text: `${MISSING_TOOLS_NOTE_PREFIX} x` }], "child text is sanitized");
+});
+
+test("argument liveness accepts current and legacy Pi starts without display or usage deltas", () => {
+	for (const start of [{ type: "toolcall_start", contentIndex: 0, id: "c1", toolName: "write" },
+		{ type: "toolcall_start", contentIndex: 0, partial: { content: [{ type: "toolCall", id: "c1", name: "write", arguments: {} }] } }]) {
+		const progress = new ToolArgumentProgress();
+		const update = (inner: Record<string, unknown>) => ({ type: "message_update", assistantMessageEvent: inner });
+		const delta = update({ type: "toolcall_delta", contentIndex: 0, delta: "private" });
+		assert.equal(progress.observe(delta), false, "no active generation");
+		progress.observe({ type: "message_start", message: { role: "assistant", timestamp: 1 } });
+		assert.equal(progress.observe(delta), false, "no announced block");
+		assert.equal(progress.observe(update(start)), false, "announcement alone is not progress");
+		assert.equal(progress.observe(delta), true);
+		assert.equal(progress.observe(delta), false);
+		assert.deepEqual(normalizeRpcEvent(delta), [], "no arguments in display events or provisional totals");
+		progress.observe(update({ type: "toolcall_end", contentIndex: 0 }));
+		assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "late" })), false);
+		progress.observe(update(start));
+		assert.equal(progress.observe(delta), false, "a closed block cannot be reopened");
+	}
+});
+
+test("argument liveness fails closed on malformed starts, stale generations and fingerprint exhaustion", () => {
+	const progress = new ToolArgumentProgress();
+	const update = (inner: Record<string, unknown>) => ({ type: "message_update", assistantMessageEvent: inner });
+	for (const timestamp of [undefined, "1", -1, 1.5]) progress.observe({ type: "message_start", message: { role: "assistant", timestamp } });
+	assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "x" })), false);
+	progress.observe({ type: "message_start", message: { role: "assistant", timestamp: 1 } });
+	for (const fields of [{ id: 1, toolName: "write" }, { id: "c", toolName: "" }, { partial: null }]) {
+		progress.observe(update({ type: "toolcall_start", contentIndex: 0, ...fields }));
+		assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "x" })), false);
+	}
+	progress.observe(update({ type: "toolcall_start", contentIndex: 0, id: "c", toolName: "write" }));
+	for (let index = 0; index < 4096; index++) assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: String(index) })), true);
+	assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "over-cap" })), false);
+	progress.observe({ type: "message_end" });
+	progress.observe({ type: "message_start", message: { role: "assistant", timestamp: 1 } });
+	progress.observe(update({ type: "toolcall_start", contentIndex: 0, id: "c", toolName: "write" }));
+	assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "stale" })), false);
+});
+
 test("response observations are opt-in, finalized, field-specific and content-free", () => {
 	const message = { role: "assistant", provider: "openai", model: "gpt-4o", responseModel: "gpt-4o-2024-08-06",
 		providerThinkingLevel: "high", stopReason: "stop", content: [{ type: "text", text: "private response" }],

package/tests/agents-queries.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { AGENT_MODE, type AgentDefinition } from "../lib/agents-config.ts";
+import { AGENT_MODE, type AgentDefinition, type AgentMode } from "../lib/agents-config.ts";
 import { CHILD_MESSAGE_MAX_BYTES, ChildMessenger } from "../lib/agents-messaging.ts";
 import { TaskStore } from "../lib/agents-protocol.ts";
 import { AgentRunner } from "../lib/agents-runner.ts";
@@ -8,7 +8,7 @@ import { fakeChild } from "./agents-fake-child.ts";
 
 const tick = () => new Promise((resolve) => setImmediate(resolve));
 const agent: AgentDefinition = { name: "worker", description: "", filePath: "/a.md", scope: "global", instructions: "", model: undefined, thinking: undefined, mode: undefined, tools: ["read"] };
-const request = (mode = AGENT_MODE.BACKGROUND) => ({ agent, prompt: "work", label: undefined, context: undefined, mode, cwd: "/repo", parentSessionId: "s1", model: undefined, thinking: undefined, sessionDir: "/sessions", resumeSessionPath: undefined, env: {} });
+const request = (mode: AgentMode = AGENT_MODE.BACKGROUND) => ({ agent, prompt: "work", label: undefined, context: undefined, mode, cwd: "/repo", parentSessionId: "s1", model: undefined, thinking: undefined, sessionDir: "/sessions", resumeSessionPath: undefined, env: {} });
 
 test("ChildMessenger validates query replies and settles timeout, callback failure, and disconnect once", async () => {
 	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
@@ -74,7 +74,7 @@ test("ChildMessenger rejects an empty reply error and ignores mixed reply fields
 
 test("runner sends bounded static query rejection frames that settle the child before timeout", async () => {
 	const child = fakeChild();
-	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const listeners = new Map<string, Array<(value: unknown) => void>>();
 	const timers: Array<{ cancelled: boolean; fn: () => void }> = [];
 	child.child.send = (frame, done) => {
 		child.sent.push(frame);
@@ -83,8 +83,8 @@ test("runner sends bounded static query rejection frames that settle the child b
 		return true;
 	};
 	const messenger = new ChildMessenger({
-		send: (frame) => { child.message(frame); return true; },
-		on: (event, listener) => listeners.set(event, [...(listeners.get(event) ?? []), listener as (value: Record<string, unknown>) => void]),
+		send: (frame: Record<string, unknown>) => { child.message(frame); return true; },
+		on: (event, listener) => listeners.set(event, [...(listeners.get(event) ?? []), listener]),
 	}, (fn) => {
 		const timer = { cancelled: false, fn };
 		timers.push(timer);
@@ -102,7 +102,7 @@ test("runner sends bounded static query rejection frames that settle the child b
 
 test("a malformed query with a valid q ID gets a reply that clears the matching child query", async () => {
 	const child = fakeChild();
-	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const listeners = new Map<string, Array<(value: unknown) => void>>();
 	const timers: Array<{ cancelled: boolean; fn: () => void }> = [];
 	child.child.send = (frame, done) => {
 		child.sent.push(frame);
@@ -111,8 +111,8 @@ test("a malformed query with a valid q ID gets a reply that clears the matching
 		return true;
 	};
 	const messenger = new ChildMessenger({
-		send: (frame) => { child.message(frame); return true; },
-		on: (event, listener) => listeners.set(event, [...(listeners.get(event) ?? []), listener as (value: Record<string, unknown>) => void]),
+		send: (frame: Record<string, unknown>) => { child.message(frame); return true; },
+		on: (event, listener) => listeners.set(event, [...(listeners.get(event) ?? []), listener]),
 	}, (fn) => {
 		const timer = { cancelled: false, fn };
 		timers.push(timer);
@@ -133,7 +133,7 @@ test("background queries keep correlation, bounds, and ownership before replying
 	const child = fakeChild();
 	const queries: Array<{ taskId: string; requestId: string; message: string }> = [];
 	const runner = new AgentRunner(new TaskStore(), { maxConcurrency: 1, stallTimeoutMs: 10_000 }, { spawn: () => child.child, now: () => 1, schedule: () => () => {}, pi: { command: "pi", args: [] } }, {
-		askUser: async () => ({ cancelled: true }), onQuery: (task, requestId, message) => queries.push({ taskId: task.id, requestId, message }),
+		askUser: async () => ({ cancelled: true }), onQuery: (task, requestId, message) => { queries.push({ taskId: task.id, requestId, message }); },
 	});
 	const task = runner.run(request());
 	await tick();

package/tests/agents-runner-process.test.ts

@@ -5,6 +5,7 @@ import test from "node:test";
 import { AGENT_MODE, type AgentDefinition } from "../lib/agents-config.ts";
 import { AgentRunner, type ChildLike, type RunnerDeps, type TaskRequest } from "../lib/agents-runner.ts";
 import { TASK_STATUS, TaskStore } from "../lib/agents-protocol.ts";
+import { fakeChild } from "./agents-fake-child.ts";
 
 const fixture = fileURLToPath(new URL("./fixtures/agents-process-child.mjs", import.meta.url));
 const agent: AgentDefinition = { name: "process", description: "test", filePath: "/test.md", scope: "global", instructions: "", model: undefined, thinking: undefined, mode: undefined, tools: [] };
@@ -18,6 +19,36 @@ const waitFor = async (predicate: () => boolean, timeoutMs = 10_000): Promise<vo
 	}
 };
 
+test("missing RPC streams fail the task without announcing a launch or leaking its queue slot", async () => {
+	const store = new TaskStore();
+	const child = fakeChild();
+	let launched = false;
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 1000 }, {
+		spawn: () => ({ ...child.child, stdin: null, stdout: null }), now: Date.now,
+		schedule: (fn, ms) => { const timer = setTimeout(fn, ms); return () => clearTimeout(timer); },
+		pi: { command: "pi", args: [] },
+	}, { askUser: async () => ({ cancelled: true }) });
+	const task = runner.run({ ...request("missing streams"), onLaunch: () => { launched = true; } });
+	await waitFor(() => store.get(task.id)?.status === TASK_STATUS.FAILED);
+	assert.equal(launched, false);
+	assert.match(store.get(task.id)!.error!, /RPC streams/);
+	assert.ok(child.killed.length > 0, "the malformed child is still stopped");
+});
+
+test("a real failed OS spawn has no pid and is retained as a launch failure", async () => {
+	const store = new TaskStore();
+	let launched = false;
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 1000 }, {
+		spawn: (_command, _args, options) => nodeSpawn("/nonexistent/gentle-pi-child", [], { ...options, stdio: ["pipe", "pipe", "pipe", "ipc"] }),
+		now: Date.now, schedule: (fn, ms) => { const timer = setTimeout(fn, ms); return () => clearTimeout(timer); },
+		pi: { command: "unused", args: [] },
+	}, { askUser: async () => ({ cancelled: true }) });
+	const task = runner.run({ ...request("failed spawn"), onLaunch: () => { launched = true; } });
+	await waitFor(() => store.get(task.id)?.status === TASK_STATUS.FAILED);
+	assert.equal(launched, false);
+	assert.match(store.get(task.id)!.error!, /ENOENT/);
+});
+
 test("POSIX cleanup retains queue slots when a leader exits but its TERM-resisting descendant remains", { skip: process.platform === "win32" }, async () => {
 	const store = new TaskStore();
 	let launches = 0;