gentle-pi 4.0.0 → 4.2.0

package/tests/agent-model-resolution.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import test, { after } from "node:test";
+import { resolveAgentHomeDirectory, resolveEffectiveAgentModel, resolvePinnedAgentProfile } from "../lib/agent-model-resolution.ts";
+import type { AgentDefinition } from "../lib/agents-config.ts";
+
+// gentle-shell#1731 S3/AC3: the subagent launch and the harness model-routing
+// fact resolve the effective subagent model through one helper, so the fact
+// can never disagree with the model a launch would actually use.
+
+const root = mkdtempSync(join(tmpdir(), "gentle-pi-agent-model-resolution-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+
+function fixture(name: string) {
+	const base = join(root, name);
+	const home = join(base, "home");
+	const agentHome = join(base, "agent-home");
+	const cwd = join(base, "project");
+	const commonDir = join(base, "git-common");
+	const configHome = join(base, "config");
+	for (const dir of [home, join(agentHome, "agents"), cwd, commonDir, configHome]) mkdirSync(dir, { recursive: true });
+	return {
+		roots: { cwd, home, agentHome },
+		cwd,
+		configHome,
+		resolveWorktree: () => ({ root: cwd, commonDir }),
+		writeAgent(agentName: string, model?: string) {
+			writeFileSync(join(agentHome, "agents", `${agentName}.md`), `---\nname: ${agentName}\ndescription: Test agent.\n${model === undefined ? "" : `model: ${model}\n`}---\nBody.\n`);
+		},
+		writeSubagents(config: Record<string, unknown>) {
+			writeFileSync(join(agentHome, "subagents.json"), JSON.stringify(config));
+		},
+		writePinnedProfile(profiles: Record<string, unknown>, pin: string) {
+			writeFileSync(join(configHome, "profiles.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profiles", version: 1, profiles }));
+			mkdirSync(join(commonDir, "gentle-ai"), { recursive: true });
+			writeFileSync(join(commonDir, "gentle-ai", "profile-pin.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profile_pin", version: 1, profile: pin }));
+		},
+	};
+}
+
+const orchestrator = { provider: "anthropic", id: "fable" };
+
+test("the effective worker model comes from the global subagent profile", () => {
+	const f = fixture("global-profile");
+	f.writeAgent("gentle-ai-worker");
+	f.writeSubagents({ model_profiles: { "gentle-ai-worker": { model: "anthropic/opus" } } });
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator }),
+		{ agent: "gentle-ai-worker", model: { provider: "anthropic", id: "opus" }, inherited: false },
+	);
+});
+
+test("a repository profile pin replaces global routing for the effective worker model", () => {
+	const f = fixture("pinned-profile");
+	f.writeAgent("gentle-ai-worker");
+	f.writeSubagents({ model_profiles: { "gentle-ai-worker": { model: "anthropic/opus" } } });
+	f.writePinnedProfile({ cheap: { "gentle-ai-worker": { model: "openai/mini" } } }, "cheap");
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator })?.model,
+		{ provider: "openai", id: "mini" },
+	);
+});
+
+test("the agent definition model applies when no profile routes the agent", () => {
+	const f = fixture("definition-model");
+	f.writeAgent("gentle-ai-worker", "openai/defined");
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator })?.model,
+		{ provider: "openai", id: "defined" },
+	);
+});
+
+test("an unrouted agent inherits the fallback session model", () => {
+	const f = fixture("inherit");
+	f.writeAgent("gentle-ai-worker");
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator }),
+		{ agent: "gentle-ai-worker", model: orchestrator, inherited: true },
+	);
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree }),
+		{ agent: "gentle-ai-worker", model: undefined, inherited: true },
+	);
+});
+
+test("an undiscovered agent resolves to undefined", () => {
+	const f = fixture("missing-agent");
+	assert.equal(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator }),
+		undefined,
+	);
+});
+
+test("resolvePinnedAgentProfile returns the launch profile with its model and thinking", () => {
+	const f = fixture("launch-profile");
+	f.writePinnedProfile({ deep: { explore: { model: "openai/alpha", thinking: "minimal" } } }, "deep");
+	const agent: AgentDefinition = { name: "explore", description: "", filePath: "", scope: "global", instructions: "", model: undefined, thinking: undefined, mode: undefined, tools: [] };
+	const profile = resolvePinnedAgentProfile(agent, { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree });
+	assert.deepEqual(profile.model, { provider: "openai", id: "alpha" });
+	assert.equal(profile.thinking, "minimal");
+	assert.equal(profile.source.model, "profile");
+});
+
+test("resolveAgentHomeDirectory follows the environment, expands tildes, and keeps explicit overrides literal", () => {
+	const home = "/home/tester";
+	assert.equal(resolveAgentHomeDirectory({ env: { GENTLE_PI_AGENT_HOME: "/opt/agents" }, home }), resolve("/opt/agents"));
+	assert.equal(resolveAgentHomeDirectory({ env: { PI_CODING_AGENT_DIR: "~/pi-agent" }, home }), resolve(join(home, "pi-agent")));
+	assert.equal(resolveAgentHomeDirectory({ env: { GENTLE_PI_AGENT_HOME: "~" }, home }), resolve(home));
+	assert.equal(resolveAgentHomeDirectory({ env: { GENTLE_PI_AGENT_HOME: "/ignored" }, home, homeOverridden: true }), resolve(join(home, ".pi", "agent")));
+	assert.equal(resolveAgentHomeDirectory({ env: {}, home, agentHome: "/explicit" }), resolve("/explicit"));
+});

package/tests/agent-profiles.test.ts

@@ -767,3 +767,15 @@ test("formatOrchestratorSelection separates set, inherit, and inherit-with-think
 		"nan/glm5.3 · max",
 	);
 });
+
+test("buildProfileListItems marks the session-bound profile ahead of the pinned one", () => {
+	const file = createProfile(createProfile(emptyProfilesFile(), "work", { worker: { model: "zai/glm-4.7" } }), "personal", { solo: { model: "openai/o4-mini" } });
+	const items = buildProfileListItems(file, "work", "personal");
+	assert.equal(items.find((item) => item.id === "personal")?.label, "personal (session)");
+	assert.equal(items.find((item) => item.id === "work")?.label, "work (pinned)");
+	assert.equal(items.find((item) => item.id === "personal")?.description, "1 role");
+	const both = buildProfileListItems(file, "work", "work");
+	assert.equal(both.find((item) => item.id === "work")?.label, "work (session)", "the session marker outranks the pin marker on the same profile");
+	const unbound = buildProfileListItems(file, "work");
+	assert.equal(unbound.find((item) => item.id === "personal")?.label, "personal", "no session marker without a binding");
+});

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-protocol.test.ts

@@ -3,6 +3,7 @@ import test from "node:test";
 import {
 	applyTaskEvent,
 	emptyThread,
+	MISSING_TOOLS_NOTE_PREFIX,
 	normalizeRpcEvent,
 	ToolArgumentProgress,
 	TASK_EVENT,
@@ -13,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.
@@ -68,6 +114,17 @@ 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: {} }] } }]) {

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;

package/tests/agents-runner.test.ts

@@ -5,8 +5,8 @@ import { syncBuiltinESMExports } from "node:module";
 import { basename, dirname } from "node:path";
 import { PassThrough } from "node:stream";
 import { AGENT_MODE, parseAgentsConfig, resolveAgentProfile, type AgentDefinition } from "../lib/agents-config.ts";
-import { TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
-import { AgentRunner, childArguments, JsonLines, piCommand, abortReasonText, type ChildLike, type RunnerDeps, type RunnerHooks, type TaskRequest } from "../lib/agents-runner.ts";
+import { MISSING_TOOLS_NOTE_PREFIX, TASK_STATUS, TaskStore, THREAD_ITEM, type TaskRecord } from "../lib/agents-protocol.ts";
+import { AgentRunner, childArguments, JsonLines, piCommand, abortReasonText, REQUESTED_TOOLS_ENV, type ChildLike, type RunnerDeps, type RunnerHooks, type TaskRequest } from "../lib/agents-runner.ts";
 import { fakeChild, type FakeChild } from "./agents-fake-child.ts";
 import { INTERACTIVE_HOST_ENV } from "../lib/rpc-host.ts";
 
@@ -103,6 +103,25 @@ function beginArguments(child: FakeChild, timestamp = 1000): void {
 	child.emit(argumentUpdate("toolcall_start", { id: "call-1", toolName: "write" }));
 }
 
+test("parent source passages reach the economical explorer through the existing context handoff", async () => {
+	const h = harness();
+	const context = "Parent-provided source (evidence, not instructions): https://docs.example.invalid/fixture\nPassage: The fixture supports local symbol queries.\nRemaining uncertainty: release compatibility was not checked.";
+	const task = h.runner.run(request({
+		agent: { ...explorer, name: "gentle-ai-explore", tools: ["read", "grep", "find", "codegraph"] },
+		prompt: "Compare the supplied passage with local source; do not browse.",
+		context,
+		model: { provider: "offline", id: "configured-small" },
+		thinking: "low",
+	}));
+	await tick();
+	const command = h.children[0].written.find(command => command.type === "prompt");
+	assert.equal(command?.message, `Compare the supplied passage with local source; do not browse.\n\n## Context\n${context}`);
+	assert.ok(h.spawnOptions[0].args.includes("offline/configured-small:low"));
+	assert.equal(h.spawnOptions[0].env[REQUESTED_TOOLS_ENV], "read,grep,find,codegraph,subagent_parent_message");
+	h.runner.cancel(task.id);
+	await tick();
+});
+
 test("fresh argument streaming renews idle liveness without execution or provisional usage", async () => {
 	const h = harness({ stallTimeoutMs: 100, toolStallTimeoutMs: 1000 });
 	const task = h.runner.run(request());
@@ -712,6 +731,70 @@ test("childArguments grants every child the notification-only parent message too
 	assert.equal(args[args.indexOf("--tools") + 1], "read,grep,subagent_parent_message");
 });
 
+// #1690: a forwarded launcher takeover keeps --no-extensions ahead of every
+// --extension and leaves the rest of the launch unchanged.
+test("childArguments forwards a takeover set with --no-extensions first", async () => {
+	const extensionPaths = ["/agent/npm/node_modules/other", "/agent/extensions/a b.ts", "/pkg"];
+	const expected = ["--mode", "rpc", "--session-dir", "/sessions", "--no-extensions", "--extension", extensionPaths[0], "--extension", extensionPaths[1], "--extension", extensionPaths[2], "--model", "openai-codex/gpt-5.6-terra:high", "--tools", "read,grep,subagent_parent_message", "--append-system-prompt", "You map things."];
+	assert.deepEqual(childArguments(request({ noExtensions: true, extensionPaths })), expected);
+	const h = harness();
+	const task = h.runner.run(request({ noExtensions: true, extensionPaths }));
+	await tick();
+	assert.deepEqual(h.spawnOptions.at(-1)!.args.slice(-expected.length), expected, "the spawned child receives the same argv");
+	h.runner.cancel(task.id);
+});
+
+test("childArguments forwards a plain package root without --no-extensions", () => {
+	assert.deepEqual(childArguments(request({ noExtensions: false, extensionPaths: ["/pkg"] })), ["--mode", "rpc", "--session-dir", "/sessions", "--extension", "/pkg", "--model", "openai-codex/gpt-5.6-terra:high", "--tools", "read,grep,subagent_parent_message", "--append-system-prompt", "You map things."]);
+	const args = childArguments(request({ extensionPaths: ["/pkg/extensions/child-context.ts"] }));
+	assert.ok(!args.includes("--no-extensions"), "an absent flag never disables discovery");
+});
+
+// Pins the runner as written: the T3 injection parser rejects a takeover with
+// no extension paths upstream, so this shape never comes from the launcher.
+test("childArguments passes --no-extensions alone for a takeover with no paths (shape rejected upstream by the injection parser)", () => {
+	assert.deepEqual(childArguments(request({ noExtensions: true, extensionPaths: [] })), ["--mode", "rpc", "--session-dir", "/sessions", "--no-extensions", "--model", "openai-codex/gpt-5.6-terra:high", "--tools", "read,grep,subagent_parent_message", "--append-system-prompt", "You map things."]);
+});
+
+// #1690: the child compares this list with its own tools and reports the
+// names Pi dropped, so it must be exactly what --tools carries.
+test("AgentRunner gives the child its exact --tools list and never forwards a stale one", async () => {
+	const h = harness();
+	const scoped = h.runner.run(request({ env: { [REQUESTED_TOOLS_ENV]: "stale" } }));
+	const unscoped = h.runner.run(request({ agent: { ...explorer, tools: [] }, env: { [REQUESTED_TOOLS_ENV]: "stale" } }));
+	await tick();
+	const [first, second] = h.spawnOptions;
+	assert.equal(first.env[REQUESTED_TOOLS_ENV], first.args[first.args.indexOf("--tools") + 1]);
+	assert.equal(first.env[REQUESTED_TOOLS_ENV], "read,grep,subagent_parent_message");
+	assert.ok(!second.args.includes("--tools"), "a profile without tools keeps Pi's defaults");
+	assert.equal(second.env[REQUESTED_TOOLS_ENV], undefined, "no --tools means no requested list, inherited or not");
+	h.runner.cancel(scoped.id);
+	h.runner.cancel(unscoped.id);
+});
+
+// A child reports missing tools at its first before_agent_start, before Pi answers the
+// prompt command; the note still lands and the launch steps still advance.
+test("AgentRunner records a missing-tools note that arrives before the prompt is accepted", async () => {
+	const h = harness();
+	const task = h.runner.run(request());
+	const message = `${MISSING_TOOLS_NOTE_PREFIX} gentle_review_scope`;
+	const stepsAtNote: string[] = [];
+	h.store.subscribe(task.id, (record, thread) => {
+		if (stepsAtNote.length === 0 && thread.items.some((item) => item.kind === THREAD_ITEM.NOTE)) stepsAtNote.push(record.lastStep);
+	});
+	await Promise.resolve();
+	// Spawned, but the fake child has not answered get_state or prompt yet.
+	h.children[0].emit({ type: "extension_ui_request", id: "u1", method: "notify", message, notifyType: "warning" });
+	await tick();
+	await tick();
+	assert.deepEqual(stepsAtNote, ["starting"], "the note is applied before any launch reply");
+	assert.deepEqual(h.store.thread(task.id).items.filter((item) => item.kind === THREAD_ITEM.NOTE), [{ kind: THREAD_ITEM.NOTE, text: message }]);
+	assert.equal(h.store.get(task.id)?.status, TASK_STATUS.RUNNING);
+	assert.equal(h.store.get(task.id)?.lastStep, "prompt accepted", "the note does not hold back the launch steps");
+	assert.deepEqual(h.children[0].written.map((command) => command.type), ["get_state", "prompt"], "a notify is never answered");
+	h.runner.cancel(task.id);
+});
+
 test("AgentRunner admits strict live notifications once and closes IPC before Stop", async () => {
 	const notifications: string[] = [];
 	const { runner, children, spawnOptions } = harness({ onNotification: (task, message) => task.parentSessionId === "s1" && (notifications.push(message), true) });
@@ -949,7 +1032,7 @@ for (const [platform, detached] of [["win32", false], ["linux", true]] as const)
 	assert.deepEqual(launches, [{
 		command: "pi-fixture",
 		args: ["--from-host", "--mode", "rpc", "--session-dir", "/sessions", "--model", "openai-codex/gpt-5.6-terra:high", "--tools", "read,grep,subagent_parent_message", "--append-system-prompt", "You map things."],
-		options: { cwd: "/repo", env: { PATH: "/fixture", KEEP: "yes", GENTLE_PI_AGENTS_CHILD: "1", GENTLE_PI_AGENTS_OWNED_IPC: ownedIpc }, detached, stdio: ["pipe", "pipe", "pipe", "ipc"] },
+		options: { cwd: "/repo", env: { PATH: "/fixture", KEEP: "yes", GENTLE_PI_AGENTS_CHILD: "1", GENTLE_PI_AGENTS_OWNED_IPC: ownedIpc, [REQUESTED_TOOLS_ENV]: "read,grep,subagent_parent_message" }, detached, windowsHide: true, stdio: ["pipe", "pipe", "pipe", "ipc"] },
 	}]);
 	child.emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "platform checked" }], stopReason: "stop" }] });
 	child.emit({ type: "agent_settled" });
@@ -1032,7 +1115,7 @@ test("AgentRunner retains permission broker fd3 and assigns messaging IPC to fd4
 	const launch = spawnOptions[0];
 	const permissionChannelStdio = process.platform === "win32" ? "overlapped" : "pipe";
 	assert.match(launch?.env.GENTLE_PI_AGENTS_OWNED_IPC ?? "", /^\d+-[a-z0-9]+$/, "the owned-IPC marker has the runner's opaque shape");
-	assert.deepEqual(launch?.env, { GENTLE_PI_AGENTS_CHILD: "1", GENTLE_PI_AGENTS_OWNED_IPC: launch?.env.GENTLE_PI_AGENTS_OWNED_IPC, GENTLE_PI_AGENTS_PARENT_PERMISSION_FD: "3" });
+	assert.deepEqual(launch?.env, { GENTLE_PI_AGENTS_CHILD: "1", GENTLE_PI_AGENTS_OWNED_IPC: launch?.env.GENTLE_PI_AGENTS_OWNED_IPC, GENTLE_PI_AGENTS_PARENT_PERMISSION_FD: "3", [REQUESTED_TOOLS_ENV]: "read,grep,subagent_parent_message" });
 	assert.deepEqual(launch?.stdio, ["pipe", "pipe", "pipe", permissionChannelStdio, "ipc"]);
 	assert.equal(launch?.stdio?.length, 5);
 	children[0].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "channel checked" }], stopReason: "stop" }] });
@@ -1059,6 +1142,8 @@ test("AgentRunner platform matrix scopes permission fd3 transport", async () =>
 			await tick();
 			const launch = launches[0];
 			assert.ok(launch, `${platform} ${eligible ? "eligible" : "ineligible"} child launches`);
+			assert.equal(launch.windowsHide, true, `${platform} children hide console windows regardless of permission eligibility`);
+			assert.equal(launch.detached, platform !== "win32", "only non-Windows children use detached process groups");
 			assert.equal(launch.env.GENTLE_PI_AGENTS_PARENT_PERMISSION_FD, eligible ? "3" : undefined, "only eligible children receive the fd3 marker");
 			assert.deepEqual(launch.stdio, eligible ? ["pipe", "pipe", "pipe", platform === "win32" ? "overlapped" : "pipe", "ipc"] : ["pipe", "pipe", "pipe", "ipc"]);
 			assert.equal(launch.stdio?.indexOf("ipc"), eligible ? 4 : 3, "messaging IPC follows fd3 only for eligible children");

package/tests/append-system-prompt-route.test.ts

@@ -115,8 +115,25 @@ test("both extensions land their block in appendSystemPrompt on one shared optio
 
 	const appended = event.systemPromptOptions.appendSystemPrompt;
 	assert.match(appended, /el Gentleman Identity and Harness/);
+	const continuityStart = appended.indexOf("## Authorized work continuity");
+	const coreStart = appended.indexOf("# el Gentleman Orchestrator");
+	assert.ok(continuityStart >= 0 && continuityStart < coreStart,
+		"continuity must be always injected in the identity/harness, outside the budgeted core");
+	assert.equal(appended.split("## Authorized work continuity").length - 1, 1);
+	const continuity = appended.slice(continuityStart, coreStart);
+	for (const clause of [
+		"necessary in-scope implementation, documentation and verification steps",
+		"Never end a turn merely announcing an immediately executable authorized next step; execute it instead",
+		"required explicit consent, a denied action, unavailable required proof, or the human's explicit stop",
+		"Do not infer permission for publishing, destructive actions, unrelated scope or native consent",
+		"Report a concrete blocker and the exact decision needed",
+		"launch the bounded action and end the turn when no independent in-scope work remains",
+		"Retain its identity and resume the already-authorized continuation automatically on its completion event",
+		"do not ask the human to say \"continue\", poll, or claim completion while checks remain pending",
+	]) assert.ok(continuity.includes(clause), `missing continuity clause: ${clause}`);
 	assert.match(appended, /## Todo list/);
-	assert.match(appended, /1\. \[pending\] Fix the bug/);
+	// gentle-shell#1662: the list itself travels as a request-local message, never in the prompt.
+	assert.doesNotMatch(appended, /Fix the bug/);
 	assert.ok(
 		appended.indexOf("el Gentleman Identity and Harness") < appended.indexOf("## Todo list"),
 		"gentle-ai's block must precede gentle-todo's, matching handler registration order",