gentle-pi 4.1.0 → 4.3.0

package/skills/gentle-ai/SKILL.md

@@ -17,7 +17,7 @@ When asked who or what you are, answer as el Gentleman: a Pi-specific coding-age
 - Size every task by the orchestrator's Task Size section: understood, contained risk, and resumable from the original request plus `git diff`. Counts of files, commands, tests, or fixes never decide it. Track only large work in its task document and mirror.
 - For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observe RED, GREEN, relevant alternate cases, then REFACTOR and record evidence. Test presence alone does not establish applicability. For passive documentation, non-testable changes, an unavailable runner, or no meaningful RED, state why and run proportionate ordinary functional or structural verification. Never invent RED/GREEN, skip checks, or require a chat/TUI toggle.
 - Keep one parent session responsible for orchestration; child subagents should receive concrete phase work and must not spawn more subagents.
-- Parent-only delegation triggers fire one mechanism at a time: an open decision (ask), understanding beyond the evidence budget (explore), high risk (independent verifier), a large task (track), a writer reason (parallel units or context), tooling/worktree incidents, or a parent context past the context backstop.
+- Parent-only delegation triggers fire one mechanism at a time: an open decision (ask), understanding beyond the evidence budget (explore), a named high-risk item (independent verifier, through assess `escalate`), a large task (track), a writer reason (parallel units or context), tooling/worktree incidents, or a parent context past the context backstop.
 - Parallel writers only with disjoint Allowed edit surfaces (runtime-enforced) or isolated worktrees.
 - Forecast review workload before large changes; ask before producing oversized or multi-area diffs.
 - Keep dangerous-command safety independent and authoritative.
@@ -45,9 +45,9 @@ Hard delegation triggers:
 
 - **Evidence-budget rule**: read inline only when the evidence fits one parallel batch of at most 3 calls, ~10k tokens (grep and line ranges, never whole large files). When understanding needs more reading or more than ~5 sequential lookups, delegate one explorer that returns a handoff of at most ~2k tokens with `path:line` evidence. Never force delegation for a small targeted question; do not re-read what the handoff covered beyond one spot check.
 - **Writer rule**: a writer only for a reason (parallel units launched together, or context); size and file count never fire it.
-- **Verification rule**: a high-risk change gets an independent verifier; otherwise the change's own focused test and suite run inline.
+- **Verification rule**: a change that touches a named high-risk item gets an independent verifier (assess `escalate`); otherwise the change's own focused test and suite run inline.
 - **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, diagnose separately.
-- **Context backstop**: when the parent context passes ~150k tokens, pause and delegate the next bounded unit of work to a non-review subagent. Keep command output bounded (counts, `--stat`, `tail`).
+- **Context backstop**: when the runtime signals the context backstop (measured parent context past the smaller of an absolute cap and a fraction of the model's context window), pause and delegate the next bounded unit that needs several steps to a non-review subagent; small edits stay inline. Keep command output bounded (counts, `--stat`, `tail`).
 
 ## Review Lens Selection
 

package/skills/work-unit-commits/SKILL.md

@@ -18,7 +18,7 @@ Use it for:
 - Turning a large change into chained or stacked PRs.
 - Keeping reviewer cognitive load healthy.
 - Applying SDD tasks without accidentally producing a PR above 400 changed lines.
-- Closing an ODD task with a work-unit commit.
+- Committing ODD work in reviewable slices of about 400 authored changed lines.
 
 ## Critical Rules
 
@@ -80,11 +80,13 @@ Each SDD work unit should map cleanly to a commit or PR with:
 
 ## ODD Relationship
 
-Every ODD task closes with at least one work-unit commit:
+ODD commits work units in reviewable slices of about 400 authored changed lines, not one commit per task:
 
+- A slice holds one or more whole tasks with their tests and docs; the last slice closes the feature.
+- A unit whose Risk line names a high-risk item gets its own commit, so native review takes it alone.
 - The native review candidate is that commit, or the PR slice it belongs to when review is deferred, evaluated against the previous reviewed boundary.
 - The running authored line count from work-unit commits feeds the same delivery-strategy vocabulary as SDD.
-- The feature document records the commit identity and, once a delivery strategy applies, the slice boundaries.
+- The feature document records the commit that holds each task and, once a delivery strategy applies, the slice boundaries.
 
 ## Commands
 

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

@@ -5,15 +5,17 @@ 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,
+	verificationRisk,
 } 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.
+// travels inside the existing assess call; no new operation. Verification by
+// named risk: that escalation is now the only way to get the independent
+// verifier; a native high or unassessable tier informs only.
 
 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]);
@@ -45,23 +47,25 @@ test("decodeAgentRiskEscalation rejects unknown items, empty or oversized reason
 	}
 });
 
-test("escalatedRisk raises passive and medium to high and never lowers", () => {
+// Replaces the escalatedRisk test: the plan risk is high only with an
+// escalation; without one a native high or unassessable tier becomes medium.
+test("verificationRisk makes every escalated tier high and maps the rest to passive or medium", () => {
 	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);
+	for (const tier of Object.values(VERIFICATION_TIER)) assert.equal(verificationRisk(tier, escalation), VERIFICATION_TIER.HIGH, tier);
+	assert.equal(verificationRisk(VERIFICATION_TIER.PASSIVE, undefined), VERIFICATION_TIER.PASSIVE);
+	for (const tier of [VERIFICATION_TIER.MEDIUM, VERIFICATION_TIER.HIGH, VERIFICATION_TIER.UNASSESSABLE]) {
+		assert.equal(verificationRisk(tier, undefined), VERIFICATION_TIER.MEDIUM, tier);
+	}
 });
 
-function assessTool(): { execute: (id: string, params: Record<string, unknown>, signal: AbortSignal | undefined, onUpdate: undefined, ctx: ExtensionContext) => Promise<{ details: unknown }> } {
+function assessTool(nativeRisk: "passive" | "medium" | "high" = "medium"): { 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",
+			risk: nativeRisk,
 			reasons: [],
 			changedPaths: 1,
 			changedLines: 3,
@@ -121,3 +125,26 @@ test("gentle_review assess: agentEscalation says whether the escalation changed
 	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");
 });
+
+test("gentle_review assess: a native high without an escalation informs only and adds no verifier", async () => {
+	const tool = assessTool("high");
+	for (const writer of [{ writerModelId: "openai/gpt-6.1-sol", writerEffort: "high" }, { writerModelId: "openai/gpt-5-mini", writerEffort: "low" }]) {
+		const { details } = await tool.execute("esc-6", { operation: "assess", input: JSON.stringify(writer) }, undefined, undefined, ctx);
+		const plan = details as { risk: string; nativeRisk: string; plan: { independentVerifier: boolean; writerSelfVerification: boolean } };
+		assert.equal(plan.nativeRisk, VERIFICATION_TIER.HIGH);
+		assert.equal(plan.risk, VERIFICATION_TIER.MEDIUM, writer.writerModelId);
+		assert.equal(plan.plan.writerSelfVerification, true);
+		assert.equal(plan.plan.independentVerifier, false, `${writer.writerModelId}: neither a native high nor the writer's model adds a verifier`);
+	}
+});
+
+test("gentle_review assess: an escalation over a native high is what adds the verifier", async () => {
+	const tool = assessTool("high");
+	const input = JSON.stringify({ escalate: { item: 1, reason: "rewrites stored records" } });
+	const { details } = await tool.execute("esc-7", { operation: "assess", input }, undefined, undefined, ctx);
+	const plan = details as { risk: string; nativeRisk: string; agentEscalation: { applied: boolean }; plan: { independentVerifier: boolean } };
+	assert.equal(plan.nativeRisk, VERIFICATION_TIER.HIGH);
+	assert.equal(plan.risk, VERIFICATION_TIER.HIGH);
+	assert.equal(plan.agentEscalation.applied, true, "without the escalation the plan would be medium");
+	assert.equal(plan.plan.independentVerifier, true);
+});

package/tests/agents-runner.test.ts

@@ -2,8 +2,11 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import fs, { existsSync, readFileSync, statSync } from "node:fs";
 import { syncBuiltinESMExports } from "node:module";
-import { basename, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
 import { PassThrough } from "node:stream";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createSessionScratchExtension } from "../extensions/session-scratch.ts";
 import { AGENT_MODE, parseAgentsConfig, resolveAgentProfile, type AgentDefinition } from "../lib/agents-config.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";
@@ -618,6 +621,21 @@ test("runner captures resolved model and effort, retaining omitted launch values
 	h.runner.cancel(task.id);
 });
 
+test("record creation copies the launch-layer model source next to the model (#2180)", () => {
+	const sourced = harness({ state: { model: { provider: "anthropic", id: "resolved-model" } } });
+	const sourcedTask = sourced.runner.run(request({ modelSource: "binding" }));
+	assert.equal(sourced.store.get(sourcedTask.id)?.modelSource, "binding", "the record keeps the host-computed layer next to the resolved model");
+	sourced.runner.cancel(sourcedTask.id);
+
+	// The absence contract: a request without a model source (older callers,
+	// peers) records no field at all, so the card renders exactly as before.
+	const plain = harness({ state: { model: { provider: "anthropic", id: "resolved-model" } } });
+	const plainTask = plain.runner.run(request());
+	assert.equal(plain.store.get(plainTask.id)?.modelSource, undefined);
+	assert.equal("modelSource" in (plain.store.get(plainTask.id) as TaskRecord), false, "no modelSource key is recorded when the launch did not name a layer");
+	plain.runner.cancel(plainTask.id);
+});
+
 test("runner delivers each response combination once at finish, never attributing launch selection", async () => {
 	const snapshots: NonNullable<Parameters<NonNullable<RunnerHooks["onFinish"]>>[1]>[] = [];
 	const h = harness({ exitOnKill: false, state: { model: { provider: "anthropic", id: "launch" }, thinkingLevel: "max" },
@@ -1029,10 +1047,13 @@ for (const [platform, detached] of [["win32", false], ["linux", true]] as const)
 	await tick();
 	const ownedIpc = launches[0]?.options.env.GENTLE_PI_AGENTS_OWNED_IPC;
 	assert.match(ownedIpc ?? "", /^\d+-[a-z0-9]+$/, "the runner creates an opaque owned-IPC marker");
+	const scratch = launches[0]?.options.env.TMPDIR;
+	assert.match(basename(scratch ?? ""), /^ga[A-Za-z0-9]{6}$/, "the child gets its own TMPDIR");
+	const scratchEnv = platform === "win32" ? { TMPDIR: scratch, TMP: scratch, TEMP: scratch } : { TMPDIR: scratch };
 	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, [REQUESTED_TOOLS_ENV]: "read,grep,subagent_parent_message" }, detached, windowsHide: true, 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", ...scratchEnv }, 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" });
@@ -1115,7 +1136,8 @@ 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", [REQUESTED_TOOLS_ENV]: "read,grep,subagent_parent_message" });
+	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", TMPDIR: launch?.env.TMPDIR });
+	assert.match(basename(launch?.env.TMPDIR ?? ""), /^ga[A-Za-z0-9]{6}$/);
 	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" }] });
@@ -1778,3 +1800,238 @@ test("temporary instructions transport file is cleaned up if child emits an earl
 	assert.ok(!existsSync(capturedPromptPath), "temporary transport file must be cleaned up on early child error");
 	assert.ok(!existsSync(dirname(capturedPromptPath)), "temporary transport directory must be cleaned up on early child error");
 });
+
+// Harness roadmap T3 (R1): asking the parent to remove a child's scratch failed
+// in 3 of 6 bench cells, so each child gets its own TMPDIR that the runtime
+// removes when the child ends.
+function scratchRunner(spawnImpl: (env: NodeJS.ProcessEnv) => ChildLike) {
+	let clock = 1000;
+	const deps: RunnerDeps = {
+		spawn: (_command, _args, options) => spawnImpl((options as { env: NodeJS.ProcessEnv }).env),
+		now: () => (clock += 1),
+		schedule: (_fn, _ms) => () => {},
+		pi: { command: "pi", args: [] },
+	};
+	return new AgentRunner(new TaskStore(), { maxConcurrency: 1, stallTimeoutMs: 10_000 }, deps, { askUser: async () => ({ value: "yes" }) });
+}
+
+test("each child gets its own TMPDIR under the parent's temp dir, removed with its contents on exit", async () => {
+	const fake = fakeChild();
+	let childTmp = "";
+	const runner = scratchRunner((env) => { childTmp = env.TMPDIR ?? ""; return fake.child; });
+	const task = runner.run(request({ env: { ...process.env, TMPDIR: tmpdir() } }));
+	await tick();
+	assert.ok(childTmp.startsWith(tmpdir()) && childTmp !== tmpdir(), `child TMPDIR ${childTmp} is a fresh dir under ${tmpdir()}`);
+	assert.ok(statSync(childTmp).isDirectory());
+	const scratch = fs.mkdtempSync(`${childTmp}/check-`);
+	fs.writeFileSync(`${scratch}/state.json`, "{}");
+	fake.exit(0);
+	await runner.waitFor(task.id);
+	assert.equal(existsSync(childTmp), false, "the child's TMPDIR and everything mktemp created in it are removed");
+});
+
+test("a child TMPDIR is removed when spawn throws", async () => {
+	let childTmp = "";
+	const runner = scratchRunner((env) => { childTmp = env.TMPDIR ?? ""; throw new Error("spawn failed intentionally"); });
+	const task = runner.run(request());
+	await tick();
+	assert.equal((await runner.waitFor(task.id)).status, TASK_STATUS.FAILED);
+	assert.ok(childTmp, "the failed launch still received a child TMPDIR");
+	assert.equal(existsSync(childTmp), false);
+});
+
+test("a quarantined child keeps its TMPDIR, since a descendant may still use it", async () => {
+	const timers: Array<{ fn: () => void; ms: number }> = [];
+	let now = 1_000;
+	let childTmp = "";
+	let fake: FakeChild | undefined;
+	const store = new TaskStore();
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 10_000 }, {
+		spawn: (_command, _args, options) => { childTmp = (options as { env: NodeJS.ProcessEnv }).env.TMPDIR ?? ""; return (fake = fakeChild({ exitOnKill: false, pid: 91 })).child; },
+		now: () => now,
+		schedule: (fn, ms) => { timers.push({ fn, ms }); return () => {}; },
+		pi: { command: "pi", args: [] },
+		process: { platform: "win32", kill: () => {} },
+	}, { askUser: async () => ({ value: "yes" }) });
+	const task = runner.run(request());
+	await tick();
+	runner.cancel(task.id);
+	timers.find((timer) => timer.ms === 250)!.fn();
+	now = 5_000;
+	timers.filter((timer) => timer.ms === 25).at(-1)!.fn();
+	await tick();
+	assert.match(store.get(task.id)?.error ?? "", /capacity quarantined/);
+	assert.equal(existsSync(childTmp), true, "an unconfirmed exit must not delete files a live descendant may hold");
+	fake!.exit(0);
+	await tick();
+	assert.equal(existsSync(childTmp), false, "the proven exit removes the quarantined child's TMPDIR");
+});
+
+// R1 review advisory: a quarantined POSIX child whose own exit arrived while a
+// descendant still held its group was never probed again, so its TMPDIR and
+// slot stayed for the rest of the session after the group ended.
+test("a quarantined child whose exit is seen before its group ends frees its TMPDIR and slot once the group is gone", async () => {
+	const timers: Array<{ fn: () => void; ms: number; cancelled: boolean }> = [];
+	let now = 1_000;
+	let groupAlive = true;
+	let launches = 0;
+	const childTmps: string[] = [];
+	const store = new TaskStore();
+	let fake: FakeChild | undefined;
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 10_000 }, {
+		spawn: (_command, _args, options) => {
+			childTmps.push((options as { env: NodeJS.ProcessEnv }).env.TMPDIR ?? "");
+			return (fake = fakeChild({ exitOnKill: false, pid: 90 + (launches += 1) })).child;
+		},
+		now: () => now,
+		schedule: (fn, ms) => {
+			const timer = { fn, ms, cancelled: false };
+			timers.push(timer);
+			return () => { timer.cancelled = true; };
+		},
+		pi: { command: "pi", args: [] },
+		process: { platform: "linux", kill: (_pid, signal) => {
+			if (signal === 0 && !groupAlive) throw Object.assign(new Error("group probe"), { code: "ESRCH" });
+		} },
+	}, { askUser: async () => ({ value: "yes" }) });
+	const first = runner.run(request());
+	const second = runner.run(request({ prompt: "queued" }));
+	await tick();
+	const quarantined = fake!;
+	runner.cancel(first.id);
+	timers.find((timer) => timer.ms === 250)!.fn();
+	now = 5_000;
+	timers.filter((timer) => timer.ms === 25).at(-1)!.fn();
+	await tick();
+	assert.match(store.get(first.id)?.error ?? "", /capacity quarantined/);
+	quarantined.exit(0);
+	await tick();
+	assert.equal(existsSync(childTmps[0]), true, "a descendant still holds the group, so the TMPDIR stays");
+	assert.equal(store.get(second.id)?.status, TASK_STATUS.QUEUED, "the slot stays quarantined while the group lives");
+	groupAlive = false;
+	const probe = timers.filter((timer) => !timer.cancelled && timer.ms === 1_000).at(-1);
+	assert.ok(probe, "the observed exit keeps probing the remaining group");
+	probe.fn();
+	await tick();
+	assert.equal(existsSync(childTmps[0]), false, "the gone group removes the quarantined child's TMPDIR");
+	assert.equal(store.get(second.id)?.status, TASK_STATUS.RUNNING, "the freed slot starts queued work");
+	assert.equal(store.get(first.id)?.error, `process cleanup unconfirmed after 1000ms; capacity quarantined`, "the recorded outcome is unchanged");
+	runner.cancel(second.id);
+	fake!.exit(0);
+	await tick();
+});
+
+test("a relative inherited TMPDIR falls back to the system temp dir, so the child's path is absolute", async () => {
+	const fake = fakeChild();
+	let childTmp = "";
+	const runner = scratchRunner((env) => { childTmp = env.TMPDIR ?? ""; return fake.child; });
+	const task = runner.run(request({ env: { TMPDIR: "reltmp" } }));
+	await tick();
+	assert.ok(childTmp.startsWith(join(tmpdir(), "ga")), childTmp);
+	fake.exit(0);
+	await runner.waitFor(task.id);
+	assert.equal(existsSync(childTmp), false);
+});
+
+// odd/tasks/session-scratch-ledger.md S9: TMPDIR nests the session scratch and the
+// subagent's own TMPDIR, and a Unix socket path (104 bytes with the NUL on macOS)
+// under it must still fit, as Python's `pymp-XXXXXXXX/listener-XXXXXXXX` (32 bytes).
+test("S9: under a 48-byte inherited TMPDIR, a subagent TMPDIR leaves room for a 32-byte socket name", async (t) => {
+	const INHERITED_BYTES = 48;
+	const SOCKET_NAME = "/pymp-XXXXXXXX/listener-XXXXXXXX";
+	// An unresolved parent, like macOS `/var/folders/xx/<30 chars>/T`, padded to 48 bytes.
+	const parent = [tmpdir(), "/tmp"].map((root) => { try { return fs.mkdtempSync(join(root, "b")); } catch { return undefined; } })
+		.find((dir): dir is string => dir !== undefined && Buffer.byteLength(dir) + 2 <= INHERITED_BYTES);
+	if (!parent) { t.skip("no temp directory short enough to build a 48-byte path"); return; }
+	t.after(() => fs.rmSync(parent, { recursive: true, force: true }));
+	const inherited = join(parent, "x".repeat(INHERITED_BYTES - Buffer.byteLength(parent) - 1));
+	fs.mkdirSync(inherited);
+	assert.equal(Buffer.byteLength(inherited), INHERITED_BYTES);
+	const env: NodeJS.ProcessEnv = { TMPDIR: inherited, GENTLE_PI_CONFIG_HOME: join(parent, "config") };
+	const handlers = new Map<string, (event: unknown, ctx: unknown) => unknown>();
+	createSessionScratchExtension({ env })({ on: (name: string, handler: (event: unknown, ctx: unknown) => unknown) => { handlers.set(name, handler); }, registerCommand: () => {} } as unknown as ExtensionAPI);
+	const ctx = { cwd: parent, hasUI: false, sessionManager: { getSessionId: () => "a-session-id-much-longer-than-the-scratch-name" } };
+	handlers.get("session_start")?.({ type: "session_start", reason: "startup" }, ctx);
+	t.after(() => handlers.get("session_shutdown")?.({ type: "session_shutdown", reason: "quit" }, ctx));
+	assert.equal(dirname(env.TMPDIR!), inherited, "the session scratch keeps the inherited spelling");
+	const fake = fakeChild();
+	let childTmp = "";
+	const runner = scratchRunner((childEnv) => { childTmp = childEnv.TMPDIR ?? ""; return fake.child; });
+	const task = runner.run(request({ env: { TMPDIR: env.TMPDIR } }));
+	await tick();
+	assert.equal(dirname(childTmp), env.TMPDIR, "the subagent TMPDIR nests under the session scratch");
+	const socketPath = Buffer.byteLength(`${childTmp}${SOCKET_NAME}`);
+	assert.ok(socketPath <= 103, `${childTmp}${SOCKET_NAME} is ${socketPath} bytes`);
+	fake.exit(0);
+	await runner.waitFor(task.id);
+});
+
+// odd/tasks/scratch-review-advisories.md S2 (native review advisories of #2300):
+// session shutdown removed the whole scratch, including the TMPDIR of a child
+// still running or quarantined, whose descendants may still hold files there.
+test("advisories S2: session shutdown keeps a running or quarantined subagent's TMPDIR, removes the rest, and leaves the scratch to the sweep", async (t) => {
+	const root = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), "gentle-pi-advisories-s2-")));
+	t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+	const base = join(root, "tmp");
+	fs.mkdirSync(base);
+	const configHome = join(root, "config");
+	const env: NodeJS.ProcessEnv = { TMPDIR: base, GENTLE_PI_CONFIG_HOME: configHome };
+	const scratchSession = (sessionId: string, options: { isProcessAlive?: (pid: number) => boolean; now?: () => number } = {}) => {
+		const handlers = new Map<string, (event: unknown, ctx: unknown) => unknown>();
+		createSessionScratchExtension({ env, ...options })({ on: (name: string, handler: (event: unknown, ctx: unknown) => unknown) => { handlers.set(name, handler); }, registerCommand: () => {} } as unknown as ExtensionAPI);
+		const ctx = { cwd: root, hasUI: false, sessionManager: { getSessionId: () => sessionId } };
+		return {
+			start: () => handlers.get("session_start")?.({ type: "session_start", reason: "startup" }, ctx),
+			shutdown: () => handlers.get("session_shutdown")?.({ type: "session_shutdown", reason: "quit" }, ctx),
+		};
+	};
+	const parent = scratchSession("s-1");
+	parent.start();
+	const scratch = env.TMPDIR!;
+	assert.equal(dirname(scratch), base);
+	const timers: Array<{ fn: () => void; ms: number }> = [];
+	let now = 1_000;
+	const fakes: FakeChild[] = [];
+	const childTmps: string[] = [];
+	const store = new TaskStore();
+	const runner = new AgentRunner(store, { maxConcurrency: 2, stallTimeoutMs: 10_000 }, {
+		spawn: (_command, _args, options) => {
+			childTmps.push((options as { env: NodeJS.ProcessEnv }).env.TMPDIR ?? "");
+			const fake = fakeChild({ exitOnKill: false, pid: 80 + fakes.length });
+			fakes.push(fake);
+			return fake.child;
+		},
+		now: () => now,
+		schedule: (fn, ms) => { timers.push({ fn, ms }); return () => {}; },
+		pi: { command: "pi", args: [] },
+		process: { platform: "win32", kill: () => {} },
+	}, { askUser: async () => ({ value: "yes" }) });
+	const quarantined = runner.run(request({ env: { TMPDIR: scratch } }));
+	const running = runner.run(request({ prompt: "running", env: { TMPDIR: scratch } }));
+	await tick();
+	runner.cancel(quarantined.id);
+	timers.find((timer) => timer.ms === 250)!.fn();
+	now = 5_000;
+	timers.filter((timer) => timer.ms === 25).at(-1)!.fn();
+	await tick();
+	assert.match(store.get(quarantined.id)?.error ?? "", /capacity quarantined/);
+	assert.deepEqual(childTmps.map((dir) => dirname(dir)), [scratch, scratch]);
+	fs.writeFileSync(join(childTmps[0], "held.txt"), "x");
+	fs.writeFileSync(join(scratch, "junk.txt"), "x");
+	parent.shutdown();
+	assert.ok(existsSync(join(childTmps[0], "held.txt")), "a quarantined child's TMPDIR stays");
+	assert.ok(existsSync(childTmps[1]), "a running child's TMPDIR stays");
+	assert.equal(existsSync(join(scratch, "junk.txt")), false, "the rest of the scratch is removed");
+	assert.equal(env.TMPDIR, base, "the inherited TMPDIR is restored");
+	const ledger = JSON.parse(readFileSync(join(configHome, "scratch", "s-1.json"), "utf8")) as { scratchDir: string | null };
+	assert.equal(ledger.scratchDir, scratch, "the ledger keeps the scratch for a later sweep");
+	fakes[0].exit(0);
+	runner.cancel(running.id);
+	fakes[1].exit(0);
+	await tick();
+	assert.ok(childTmps.every((dir) => !existsSync(dir)), "each proven exit removes its TMPDIR");
+	const next = scratchSession("next", { isProcessAlive: () => false, now: () => Date.now() + 2 * 3_600_000 });
+	next.start();
+	assert.equal(existsSync(scratch), false, "the startup sweep removes the kept scratch once its owner ended");
+	next.shutdown();
+});

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",

package/tests/auto-mode-human-answers.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import choiceExtension from "../extensions/ask-user-choice.ts";
+import questionnaireExtension from "../extensions/ask-user-question.ts";
+
+for (const toolName of ["ask_user_choice", "ask_user_question"] as const) {
+ test(`public ${toolName} UI answer unpauses Auto without synthetic input`, async t => {
+  const root=mkdtempSync(join(tmpdir(),"auto-human-answer-")), home=join(root,"config");
+  mkdirSync(home);t.after(()=>rmSync(root,{recursive:true,force:true}));
+  const manager=SessionManager.inMemory(root);
+  const hooks=new Map<string,any[]>(), commands=new Map<string,any>(), tools=new Map<string,any>();
+  const requests:any[]=[];
+  let allow=false;
+  const pi:any={
+   events:{on(){return ()=>{};},emit(){}},
+   on(name:string,fn:any){hooks.set(name,[...hooks.get(name)??[],fn]);},
+   registerTool(tool:any){tools.set(tool.name,tool);},
+   registerCommand(name:string,command:any){commands.set(name,command);},
+   registerFlag(){},registerMessageRenderer(){},getActiveTools(){return [];},appendEntry(){},
+  };
+  const ctx:any={cwd:root,mode:"tui",hasUI:true,sessionManager:manager,model:{id:"fixture",provider:"fixture"},
+   signal:new AbortController().signal,
+   ui:{notify(){},setStatus(){},setWidget(){},confirm:async()=>false,
+    custom:async()=>toolName==="ask_user_choice" ? {index:1,label:"Yes",value:"opaque-choice"} :
+     {cancelled:false,answers:[{questionIndex:0,question:"May I edit source.ts?",kind:"option",answer:"Yes"}]}},
+  };
+  createGentleAiExtension({processEnv:{GENTLE_PI_CONFIG_HOME:home},nativeReviewCli:null,candidateViews:null,
+   autoPermissionClassifier:{cancel(){},async run(request:any){requests.push(request);return {status:"available",decision:allow?"allow":"deny",reason:"Fixture scope"};}},
+   resolveTelemetryTriggerBinary:()=>{throw Error("native disabled in fixture");},
+  })(pi);
+  choiceExtension(pi);questionnaireExtension(pi);
+  const emit=async(name:string,event:any)=>{
+   let output:any;
+   for(const hook of hooks.get(name)??[]){const next=await hook(event,ctx);if(next!==undefined)output=next;}
+   return output;
+  };
+  await commands.get("gentle:mode").handler("auto",ctx);
+  await emit("input",{source:"interactive",text:"Inspect only; ask before editing."});
+  manager.appendMessage({role:"user",content:"Inspect only; ask before editing.",timestamp:1});
+  const action={toolName:"write",toolCallId:"edit",input:{path:join(root,"source.ts"),content:"x"}};
+  for(let i=0;i<3;i++)assert.equal((await emit("tool_call",action))?.block,true);
+  assert.match((await emit("tool_call",action)).reason,/paused/);
+  const question="May I edit source.ts?";
+  const options=[{label:"Yes",description:"Edit source.ts only; do not publish.",value:"opaque-choice"},
+   {label:"No",description:"Keep this task read-only.",value:"opaque-no"}];
+  const args=toolName==="ask_user_choice" ? {question,options} :
+   {questions:[{question,header:"Scope",options:options.map(({label,description})=>({label,description}))}]};
+  manager.appendMessage({role:"assistant",content:[{type:"toolCall",id:"question",name:toolName,arguments:args}],
+   api:"fixture" as any,provider:"fixture",model:"fixture",usage:{input:0,output:0,cacheRead:0,cacheWrite:0,totalTokens:0,cost:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0}},stopReason:"toolUse",timestamp:2});
+  assert.equal((await emit("tool_call",{toolName,toolCallId:"question",input:args}))?.block,undefined);
+  const result=await tools.get(toolName).execute("question",args,ctx.signal,undefined,ctx);
+  assert.ok(result.content.length>0,"the original question result is retained");
+  allow=true;
+  assert.equal((await emit("tool_call",action))?.block,undefined);
+  assert.deepEqual(requests.at(-1).trustedMessages,["Inspect only; ask before editing.","Yes"]);
+  const pair=requests.at(-1).answeredPrompts.find((item:any)=>item.reply==="Yes");
+  assert.match(pair.prompt,/Edit source.ts only; do not publish\./);
+  assert.ok(!pair.prompt.includes("opaque-choice"));
+  await emit("session_tree",{});
+  await emit("tool_call",action);
+  assert.deepEqual(requests.at(-1).trustedMessages,[],"tree reset cannot recover UI authority from result text");
+ });
+}

package/tests/auto-mode-invariants.test.ts

@@ -29,19 +29,22 @@ function fixture(t: test.TestContext) {
  const manager = SessionManager.inMemory(root), anchor = manager.appendCustomEntry("probe-anchor", {});
  const commands = new Map<string, any>(), hooks = new Map<string, any[]>();
  const receipts: any[] = [], providerCalls: any[] = [], notices: string[] = [], statuses: any[] = [];
- let decision = "allow", pending = false, announce!: () => void, receiptChanged: (() => void) | undefined;
+ let decision = "allow", pending = false, inspectPath: string | undefined, announce!: () => void, receiptChanged: (() => void) | undefined;
  const started = new Promise<void>(resolve => { announce = resolve; });
  const registry: any = {
   streamSimple(selected: any, context: any, options: any) {
-   assert.deepEqual(context.tools, []);
-   assert.equal(options.toolChoice, "none");
+   const paths=JSON.parse(context.messages[0].content).evidencePaths ?? [];
+   assert.equal(options.toolChoice, paths.length ? "auto" : "none");
+   assert.deepEqual(context.tools.map((tool:any)=>tool.name),paths.length ? ["inspect_permission_file"] : []);
+   if(paths.length)assert.deepEqual(context.tools[0].parameters.properties.path.enum,paths);
    assert.equal(options.maxRetries, 0);
    let resolve!: (value: any) => void;
    const promise = new Promise(r => { resolve = r; });
    const call = { selected, context, options, resolve: () => resolve({
     role: "assistant", api: "fixture", provider: selected.provider, model: selected.id,
-    stopReason: "stop", timestamp: 1,
-    content: [{ type: "text", text: JSON.stringify({ decision, reason: decision === "deny"
+    stopReason: inspectPath && context.messages.length===1 ? "toolUse" : "stop", timestamp: 1,
+    content: inspectPath && context.messages.length===1 ? [{type:"toolCall",id:"inspect",name:"inspect_permission_file",arguments:{path:inspectPath}}] :
+     [{ type: "text", text: JSON.stringify({ decision, reason: decision === "deny"
      ? "Only inspection is authorized; do not change files." : "Local fixture action." }) }],
     usage: { input: 5, output: 3, cacheRead: 0, cacheWrite: 0, totalTokens: 8,
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0.02 } },
@@ -81,6 +84,7 @@ function fixture(t: test.TestContext) {
   call: (toolName: string, input: any) => emit("tool_call", { toolName, input, toolCallId: "probe-call" }),
   enable: () => commands.get("gentle:mode").handler("auto", ctx),
   setDecision(value: string) { decision = value; }, setPending(value: boolean) { pending = value; },
+  inspect(path: string) { inspectPath=path; },
   started: () => deadline(started, "one inference started"),
   waitForReceipts(count: number) {
    if (receipts.length >= count) return Promise.resolve();
@@ -91,6 +95,20 @@ function fixture(t: test.TestContext) {
  };
 }
 
+test("public hook supplies exact script evidence without executing or modifying the script", async t=>{
+ const f=fixture(t);mkdirSync(join(f.root,"scripts"));
+ const script=join(f.root,"scripts","check.mjs"), content="console.log('fixture-only');\n";
+ writeFileSync(script,content);
+ await f.enable();await f.input("Run the local checker after inspecting its effects.");
+ f.inspect("scripts/check.mjs");
+ const result=await f.call("bash",{command:"node scripts/check.mjs"});
+ assert.equal(result?.block,undefined);
+ assert.equal(f.providerCalls.length,2);
+ const evidence=f.providerCalls.at(-1).context.messages.find((message:any)=>message.role==="toolResult");
+ assert.deepEqual(JSON.parse(evidence.content[0].text).untrustedFileEvidence,{path:"scripts/check.mjs",content});
+ assert.equal(readFileSync(script,"utf8"),content,"inspection is read-only");
+});
+
 function deadline<T>(event: Promise<T>, label: string): Promise<T> {
  return new Promise((resolve, reject) => {
   const timer = setTimeout(() => reject(new Error(`Deadline: ${label}`)), 1500);