gentle-pi 4.2.0 → 4.3.0

package/extensions/startup-banner.ts

@@ -1,13 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, VERSION } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import * as os from "node:os";
 import { execFile } from "node:child_process";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveAnimationPolicy } from "../lib/animation-policy.ts";
 import { PI_SUBCOMMANDS } from "../lib/gentle-shell-launcher.ts";
-import { bundledGentlePiConfigHome } from "../lib/gentle-shell-bundled.ts";
+import { gentlePiConfigHome } from "../lib/agent-home.ts";
 
 
 export type BannerColor = "pink" | "cyan" | "yellow" | "green";
@@ -68,7 +67,7 @@ function rgb(r: number, g: number, b: number, text: string): string {
 }
 
 function gentleAiConfigHome(): string {
-  return bundledGentlePiConfigHome(process.env) ?? process.env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai");
+  return gentlePiConfigHome(process.env);
 }
 
 function bannerConfigPath(configHome = gentleAiConfigHome()): string {

package/lib/agent-home.ts

@@ -1,6 +1,8 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { bundledGentlePiConfigHome, runningBundledPrefix } from "./gentle-shell-bundled.ts";
+import { resolveGentlePiConfigHome, runningBundledPrefix } from "./gentle-shell-bundled.ts";
+
+export { GENTLE_SHELL_CONFIG_HOME_ENV } from "./gentle-shell-bundled.ts";
 
 // Pi Subagents resolves its global directory as `PI_CODING_AGENT_DIR || ~/.pi/agent`,
 // so an empty value must fall through here too or the two homes diverge again.
@@ -12,9 +14,12 @@ export function resolveGentlePiAgentHome(env: NodeJS.ProcessEnv = process.env):
 // commands own lives here. It is defined once because the launch-time profile pin
 // resolver reads the same profiles store the `/gentle:profiles` panel writes, and
 // two spellings of the override would silently read two different stores.
-// A bundled Gentle Shell keeps it inside its prefix (S9, bundledGentlePiConfigHome).
+// A bundled Gentle Shell keeps it inside its prefix (S9, bundledGentlePiConfigHome),
+// the standalone launcher's isolated home next to its agent dir (#2201). The rule
+// itself lives in resolveGentlePiConfigHome, a generated runtime module, so the
+// launcher and the Gentle AI process environment share it too.
 export function gentlePiConfigHome(env: NodeJS.ProcessEnv = process.env): string {
-	return bundledGentlePiConfigHome(env) ?? (env.GENTLE_PI_CONFIG_HOME || join(homedir(), ".pi", "gentle-ai"));
+	return resolveGentlePiConfigHome(env, homedir());
 }
 
 // The agent home Pi runs with, only in a bundled Gentle Shell (S9): there the

package/lib/agents-protocol.ts

@@ -127,6 +127,9 @@ export interface TaskRecord {
 	startedAt: number | null;
 	endedAt: number | null;
 	model: string;
+	/** Launch-layer token recorded next to `model` (#2180): which profile layer won.
+	 * Host-computed at the launch seam; absent for requests and records that never named one. */
+	modelSource?: string;
 	thinking: string | undefined;
 	sessionPath: string | null;
 	error: string | null;

package/lib/agents-runner.ts

@@ -2,7 +2,7 @@ import { isSessionChangeEvidence, type SessionChangeEvidence } from "./session-c
 import { chmodSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { tmpdir, userInfo } from "node:os";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { Duplex, type Readable, type Writable } from "node:stream";
 import { stripVTControlCharacters } from "node:util";
 import { withoutInteractiveHost } from "./rpc-host.ts";
@@ -12,6 +12,7 @@ import { CHILD_QUERY_MAX_INFLIGHT, CHILD_QUERY_TIMEOUT_MS, parseChildFrame, vali
 import { ParentStandingReviewPermissionBroker } from "./review-session-standing-permission-ipc.ts";
 import { isFinished, normalizeRpcEvent, ToolArgumentProgress, TASK_EVENT, TASK_STATUS, taskLabel, type AskRequest, type ChildResponseObservation, type TaskRecord, type TaskStore } from "./agents-protocol.ts";
 import { WriterSurfaceRegistry, writerSurfaceConflictMessage } from "./writer-surfaces.ts";
+import { holdSubagentScratch, releaseSubagentScratch, SUBAGENT_SCRATCH_PREFIX } from "./session-scratch.ts";
 
 // Gentle Agents runner. Every subagent is its own `pi --mode rpc` process:
 // the host never runs subagent work on the TUI thread. It writes JSON
@@ -133,6 +134,11 @@ export interface TaskRequest {
 	// Host-provided only: the launcher's package injection signal (#1690) or
 	// the curated fallback. Never derived from tool input or agent definitions.
 	extensionPaths?: string[];
+	// Host-computed launch-layer token for the card (#2180): which profile layer
+	// supplied `model` (`binding`, `frozen:*`, `pin:*`, `declaration`, `profile`,
+	// `definition`, `default`). Same host-only provenance as `extensionPaths`:
+	// never derived from tool input or agent definitions.
+	modelSource?: string;
 	// Same host-only provenance as extensionPaths (#1690).
 	noExtensions?: boolean;
 	// Parsed `## Allowed edit surfaces` of a bounded writer. While the task is
@@ -202,6 +208,8 @@ interface LiveTask {
 	childExit: number | null | undefined;
 	childExitSignal?: string | null;
 	instructionsTransportDir?: string;
+	/** The child's own TMPDIR, removed when the child ends unless its exit is unconfirmed. */
+	scratchDir?: string;
 	cleanupDeadlineAt: number | undefined;
 	quarantined: boolean;
 	nextId: number;
@@ -236,6 +244,7 @@ const DEFAULT_TOOLS: readonly string[] = [];
 const TERMINATION_GRACE_MS = 250;
 const GROUP_CONFIRM_MS = 25;
 const GROUP_CONFIRM_DEADLINE_MS = 1_000;
+const QUARANTINE_PROBE_MS = 1_000;
 const QUERY_REJECTION_ERRORS = new Set([
 	"invalid child IPC frame",
 	"invalid child IPC correlation",
@@ -407,6 +416,8 @@ export class AgentRunner {
 			startedAt: null,
 			endedAt: null,
 			model: formatModelRef(request.model),
+			// Copied, never recomputed: the layer token was resolved once at the seam (#2180).
+			...(request.modelSource === undefined ? {} : { modelSource: request.modelSource }),
 			thinking: request.thinking,
 			sessionPath: request.resumeSessionPath ?? null,
 			error: null,
@@ -562,6 +573,22 @@ export class AgentRunner {
 				return;
 			}
 		}
+		// Harness roadmap T3: scratch the child makes with mktemp lands in its own
+		// TMPDIR, under the inherited one, so the runtime removes it at the end
+		// instead of asking the parent. Best effort: without it the child keeps
+		// the inherited TMPDIR.
+		let scratchDir: string | undefined;
+		try {
+			const inherited = request.env.TMPDIR?.trim();
+			// A relative TMPDIR would resolve against this process, not the child cwd.
+			// A short name and no real path: socket paths under TMPDIR are capped near 104 bytes.
+			scratchDir = mkdtempSync(join(inherited && isAbsolute(inherited) ? inherited : tmpdir(), SUBAGENT_SCRATCH_PREFIX));
+			// Session shutdown keeps it while it is held (extensions/session-scratch.ts).
+			holdSubagentScratch(scratchDir);
+			try { chmodSync(scratchDir, DIR_MODE); } catch { /* best effort */ }
+			env.TMPDIR = scratchDir;
+			if (this.processControl.platform === "win32") { env.TMP = scratchDir; env.TEMP = scratchDir; }
+		} catch { scratchDir = undefined; }
 		let child: ChildLike;
 		try {
 			const pi = this.deps.resolvePi?.() ?? this.deps.pi;
@@ -573,15 +600,16 @@ export class AgentRunner {
 				stdio: hasParentPermissionChannel ? ["pipe", "pipe", "pipe", permissionChannelStdio, "ipc"] : ["pipe", "pipe", "pipe", "ipc"],
 			});
 		} catch (error) {
-			if (instructionsTransportDir) {
-				try { rmSync(instructionsTransportDir, { recursive: true, force: true }); } catch { /* best effort */ }
+			for (const dir of [instructionsTransportDir, scratchDir]) {
+				if (dir) try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
 			}
+			if (scratchDir) releaseSubagentScratch(scratchDir);
 			this.store.update(id, { status: TASK_STATUS.RUNNING, startedAt: this.deps.now(), lastStep: "starting" });
 			this.finish(id, TASK_STATUS.FAILED, `could not start pi: ${error instanceof Error ? error.message : String(error)}`);
 			return;
 		}
 		const processGroup = detached && typeof child.pid === "number" && child.pid > 0 ? child.pid : undefined;
-		const live: LiveTask = { child, sawRunEvent: false, mutationStarts: new Map(), inFlightTools: new Map(), argumentProgress: new ToolArgumentProgress(), pending: new Map(), queries: new Map(), replies: new Map(), cancelStall: () => {}, cancelGrace: () => {}, processGroup, terminal: undefined, childExit: undefined, childExitSignal: undefined, instructionsTransportDir, cleanupDeadlineAt: undefined, quarantined: false, nextId: 0, ipcClosed: false, acknowledgedIpcIds: new Set(), acknowledgedIpcOrder: [], stderrTail: "" };
+		const live: LiveTask = { child, sawRunEvent: false, mutationStarts: new Map(), inFlightTools: new Map(), argumentProgress: new ToolArgumentProgress(), pending: new Map(), queries: new Map(), replies: new Map(), cancelStall: () => {}, cancelGrace: () => {}, processGroup, terminal: undefined, childExit: undefined, childExitSignal: undefined, instructionsTransportDir, scratchDir, cleanupDeadlineAt: undefined, quarantined: false, nextId: 0, ipcClosed: false, acknowledgedIpcIds: new Set(), acknowledgedIpcOrder: [], stderrTail: "" };
 		if (request.prepareResponseObservations) {
 			let ready = false;
 			live.observationPreparation = () => ready;
@@ -997,7 +1025,8 @@ export class AgentRunner {
 		live.cancelGrace = this.deps.schedule(() => this.confirmGroupExit(id, live), GROUP_CONFIRM_MS);
 	}
 
-	private cleanupLive(live: LiveTask): void {
+	/** `exitProven` is true only in completeExit, after the child's exit was observed or its group is gone. */
+	private cleanupLive(live: LiveTask, exitProven = false): void {
 		live.permissionBroker?.close();
 		this.closeIpc(live);
 		live.cancelStall();
@@ -1006,6 +1035,13 @@ export class AgentRunner {
 			try { rmSync(live.instructionsTransportDir, { recursive: true, force: true }); } catch { /* best effort */ }
 			live.instructionsTransportDir = undefined;
 		}
+		// A quarantined child's exit is unconfirmed: a live descendant may still
+		// hold files there, so its scratch stays until the exit is proven.
+		if (live.scratchDir && (!live.quarantined || exitProven)) {
+			try { rmSync(live.scratchDir, { recursive: true, force: true }); } catch { /* best effort */ }
+			releaseSubagentScratch(live.scratchDir);
+			live.scratchDir = undefined;
+		}
 	}
 
 	private childError(id: string, error: Error): void {
@@ -1030,13 +1066,26 @@ export class AgentRunner {
 		const exitDesc = formatChildExit(code, signal);
 		if (this.groupExists(live)) {
 			if (!live.terminal) this.requestStop(id, TASK_STATUS.FAILED, `pi exited with ${exitDesc} before agent_settled${this.stderrSuffix(live)}`);
+			else if (live.quarantined) live.cancelGrace = this.deps.schedule(() => this.awaitQuarantinedGroup(id, live), QUARANTINE_PROBE_MS);
+			return;
+		}
+		this.completeExit(id, live);
+	}
+
+	// Quarantine stopped probing, and a descendant outlives the child's observed
+	// exit: no later event reports the group's end, so keep probing until it is
+	// gone, then release the slot and scratch.
+	private awaitQuarantinedGroup(id: string, live: LiveTask): void {
+		if (this.live.get(id) !== live) return;
+		if (this.groupExists(live)) {
+			live.cancelGrace = this.deps.schedule(() => this.awaitQuarantinedGroup(id, live), QUARANTINE_PROBE_MS);
 			return;
 		}
 		this.completeExit(id, live);
 	}
 
 	private completeExit(id: string, live: LiveTask): void {
-		this.cleanupLive(live);
+		this.cleanupLive(live, true);
 		this.live.delete(id);
 		// Quarantine already notified completion, but its retained slot is now free.
 		if (live.quarantined) {

package/lib/agents-view.ts

@@ -143,7 +143,9 @@ function sameItemValue(a: unknown, b: unknown): boolean {
 }
 
 export function taskHeader(task: TaskRecord, now: number): string {
-	const parts = [task.agent, task.status, task.model, task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? formatCost(task.cost) : "", task.startedAt === null ? "" : formatElapsed((task.endedAt ?? now) - task.startedAt)];
+	// #2180: the winning profile layer is shown right after the model it supplied;
+	// records without one render exactly as before.
+	const parts = [task.agent, task.status, task.model, ...(task.modelSource === undefined ? [] : [task.modelSource]), task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? formatCost(task.cost) : "", task.startedAt === null ? "" : formatElapsed((task.endedAt ?? now) - task.startedAt)];
 	return parts.filter((part) => part.length > 0).join(" · ");
 }
 

package/lib/bounded-writer-admission.ts

@@ -1,6 +1,7 @@
 import { realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, parse, relative, resolve } from "node:path";
+import { contextBackstopReached, type MeasuredContext } from "./context-backstop.ts";
 import { resolveSessionWorktree, type WorktreeResolver } from "./session-worktree-registry.ts";
 
 const WRITER_NAMES = ["gentle-ai-worker", "worker", "jd-fix-agent"];
@@ -79,6 +80,56 @@ export function rejectUnscopedBoundedWriterDispatch(input: unknown): { block: tr
 	return { block: true, reason: `${WRITER_EDIT_SURFACE_REJECTION} ${parsed.problem} Resend the same task text unchanged except for that section; never shorten or re-summarize it.` };
 }
 
+// Pain-point iteration S16: prompt rules alone did not stop small-task delegation (a two-feature request still
+// started two writers for ~35-line units). A generic writer launch is admitted only for a task of an existing ODD
+// feature document, or when the parent's measured context reaches the context backstop (the same threshold as the
+// runtime notice, lib/context-backstop.ts). Judgment Day fix agents and continuations keep their own protocols.
+// A line that starts with `Spec:` (optionally as a list item), names an odd/tasks document, and names a task
+// `T<n>` later on the same line: covers the canon (`, T2, S3-S4`), the delegation card (`(read until "## Log").
+// Do T2; S3.`), and comma-free forms (`.md T1 S1;`). A mention inside prose does not start the line.
+const FEATURE_DOCUMENT_TASK = /^[ \t]*(?:[-*+][ \t]+)?Spec:[ \t]*`?(odd\/tasks\/[^\s,`()]+\.md)`?[^\n]*?\bT\d+\b/gm;
+export const WRITER_FEATURE_DOCUMENT_REJECTION =
+	"Writers run only for a task of an existing ODD feature document (`Spec: odd/tasks/<feature>.md, T<n>` in the task) or when your measured context reaches the context backstop. This unit has neither: write this unit inline yourself now; do not retry the launch, and never create a feature document only to launch writers.";
+
+function featureDocumentExists(root: string, relativePath: string): boolean {
+	// Resolve symlinks on both sides so a document linked from outside the root, or an odd/tasks directory linked
+	// elsewhere, never admits a writer; the document must be a regular file under <root>/odd/tasks.
+	try {
+		const realRoot = realpathSync(resolve(root));
+		const tasksDir = realpathSync(resolve(realRoot, "odd", "tasks"));
+		const target = realpathSync(resolve(realRoot, relativePath));
+		const inTasks = relative(tasksDir, target);
+		if (relative(realRoot, tasksDir).startsWith("..") || !inTasks || inTasks.startsWith("..") || isAbsolute(inTasks)) return false;
+		return statSync(target).isFile();
+	} catch {
+		return false;
+	}
+}
+
+// True when a string value has a `Spec:` task line naming an existing feature document under `root`. Shared by
+// writer and verifier admission so both accept exactly the same task lines.
+export function namesExistingFeatureDocumentTask(values: readonly unknown[], root: string): boolean {
+	for (const value of values) {
+		if (typeof value !== "string") continue;
+		for (const match of value.matchAll(FEATURE_DOCUMENT_TASK)) {
+			if (featureDocumentExists(root, match[1])) return true;
+		}
+	}
+	return false;
+}
+
+export function rejectUndocumentedWriterLaunch(
+	input: unknown,
+	options: { root: string; contextUsage: MeasuredContext | undefined; env?: Readonly<Record<string, string | undefined>> },
+): { block: true; reason: string } | undefined {
+	if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+	const record = input as Record<string, unknown>;
+	if (typeof record.agent !== "string" || !isGenericBoundedWriter(record.agent)) return undefined;
+	if (namesExistingFeatureDocumentTask([record.task, record.context], options.root)) return undefined;
+	if (contextBackstopReached(options.contextUsage, options.env)) return undefined;
+	return { block: true, reason: WRITER_FEATURE_DOCUMENT_REJECTION };
+}
+
 // A continuation resumes the same delegated task, so a writer follow-up that
 // carries no section of its own inherits the surfaces its original launch was
 // admitted with. A follow-up that carries the heading is validated as written,

package/lib/command-palette-catalog.ts

@@ -30,10 +30,6 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 			{ command: "gentle:animations", label: "Animation mode" },
 			{ command: "gentle:vim", label: "Vim opt-in · Pi slash commands" },
 			{ command: "gentle:telemetry", label: "Telemetry" },
-			{ command: "gentle:banner", label: "Startup banner" },
-			{ command: "gentle:banner-color", label: "Banner color" },
-			{ command: "gentle:toggle-rose", label: "Toggle banner rose" },
-			{ command: "gentle:toggle-text-logo", label: "Toggle banner text logo" },
 			{ command: "gentle:dev-binary", label: "Gentle AI dev binary" },
 		],
 	},

package/lib/commit-slice-signal.ts

@@ -0,0 +1,100 @@
+import { execFile } from "node:child_process";
+import type { ToolResultEvent, ToolResultEventResult } from "@earendil-works/pi-coding-agent";
+import { resolve } from "node:path";
+
+// Harness roadmap T4 (R1): ODD slices delivery at about 400 authored changed
+// lines, but the model had to estimate the count. After each parent commit the
+// runtime reports it from Git, so the slicing decision reads a number.
+
+export const SLICE_LINES = 400;
+
+// Generated files that do not count as authored lines.
+const GENERATED = [/(^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock|go\.sum|poetry\.lock|composer\.lock|Gemfile\.lock)$/, /\.min\.(js|css)$/];
+
+// `git [-C dir | -c key=value]... commit` at the start of a segment, after any variable assignments.
+const COMMIT = /^\s*(\w+=\S*\s+)*git(\s+-[Cc]\s+\S+)*\s+commit(\s|$)/;
+
+/** A commit is a git invocation that starts a shell segment; text that only mentions one (echo, a message) is not. */
+export function isGitCommitCommand(command: string): boolean {
+	return command.split(/[;&|(\n]/).some((segment) => COMMIT.test(segment));
+}
+
+/** Shell segments joined by `;`, `&&`, `||`, or a newline. */
+export const SHELL_SEGMENT_SEPARATOR = /;|&&|\|\||\n/;
+
+const unquote = (value: string) => value.replace(/^["']|["']$/g, "");
+
+/** The directory after a shell segment: `cd <dir>` resolved against `base`, else `base`. */
+export function directoryAfterSegment(segment: string, base: string): string {
+	const cdDir = /^\s*cd\s+("[^"]+"|'[^']+'|\S+)\s*$/.exec(segment)?.[1];
+	return cdDir ? resolve(base, unquote(cdDir)) : base;
+}
+
+/** The directory the commit runs in: `git -C <dir>` under every `cd <dir>` segment before the commit (joined by `;`, `&&`, `||`, or a newline), else the session cwd. */
+export function commitTargetDirectory(command: string, cwd: string): string {
+	const gitDir = /\bgit\s+-C\s+("[^"]+"|'[^']+'|\S+)\s+(?:-[Cc]\s+\S+\s+)*commit\b/.exec(command)?.[1];
+	let base = cwd;
+	for (const segment of command.split(SHELL_SEGMENT_SEPARATOR)) {
+		if (COMMIT.test(segment)) break;
+		base = directoryAfterSegment(segment, base);
+	}
+	return gitDir ? resolve(base, unquote(gitDir)) : base;
+}
+
+type Git = (args: string[], cwd: string) => Promise<string | undefined>;
+
+// Asynchronous, so the parent stays responsive while git answers.
+const runGit: Git = (args, cwd) => new Promise((resolve) => {
+	execFile("git", args, { cwd, encoding: "utf8", timeout: 2_000 }, (error, stdout) => resolve(error ? undefined : stdout.trim()));
+});
+
+async function defaultBranch(cwd: string, git: Git): Promise<string | undefined> {
+	const remote = await git(["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"], cwd);
+	if (remote) return remote;
+	for (const name of ["main", "master"]) {
+		if (await git(["rev-parse", "--verify", "-q", `refs/heads/${name}`], cwd) !== undefined) return name;
+	}
+	return undefined;
+}
+
+/** One line for the parent after a commit on a feature branch, or undefined when there is no slice to report. */
+export async function commitSliceReport(cwd: string, git: Git = runGit): Promise<string | undefined> {
+	const branch = await git(["symbolic-ref", "-q", "--short", "HEAD"], cwd);
+	const target = branch === undefined ? undefined : await defaultBranch(cwd, git);
+	if (!branch || !target || branch === target || `origin/${branch}` === target) return undefined;
+	const base = await git(["merge-base", "HEAD", target], cwd);
+	const commits = base ? Number(await git(["rev-list", "--count", `${base}..HEAD`], cwd)) : 0;
+	if (!base || !(commits > 0)) return undefined;
+	// A failed or timed-out diff is not an empty one: report nothing rather than 0.
+	// `-M` counts a move by what it changed; `-z` keeps paths unquoted for the generated-file filter.
+	const numstat = await git(["diff", "--numstat", "-z", "-M", base, "HEAD"], cwd);
+	if (numstat === undefined) return undefined;
+	let lines = 0;
+	const fields = numstat.split("\0");
+	for (let i = 0; i < fields.length; i++) {
+		const [added, deleted, inline] = fields[i].split("\t");
+		// A rename leaves the inline path empty and is followed by its old and new paths.
+		const path = inline === "" ? fields[i += 2] : inline;
+		if (!path || added === "-" || GENERATED.some((pattern) => pattern.test(path))) continue;
+		lines += Number(added) + Number(deleted);
+	}
+	const head = `Commit slice: ${lines} authored changed lines in ${commits} commit${commits === 1 ? "" : "s"} on ${branch} since ${target} (lock files excluded).`;
+	return lines > SLICE_LINES
+		? `${head} Past the ~${SLICE_LINES}-line slice: apply the feature's delivery strategy before the next commit (record the slice boundary in the feature document).`
+		: `${head} ${SLICE_LINES - lines} lines left before the ~${SLICE_LINES}-line slice.`;
+}
+
+/**
+ * tool_result patch for a successful parent `git commit`: the slice line appended, structured content kept.
+ * Only foreground `bash`: a background job's result arrives before its commit exists.
+ */
+export async function commitSliceToolResult(event: Pick<ToolResultEvent, "toolName" | "input" | "isError" | "content" | "structuredContent">, cwd: string, git: Git = runGit): Promise<ToolResultEventResult | undefined> {
+	const command = (event.input as { command?: unknown } | undefined)?.command;
+	if (event.toolName !== "bash" || event.isError !== false || typeof command !== "string" || !isGitCommitCommand(command)) return undefined;
+	const report = await commitSliceReport(commitTargetDirectory(command, cwd), git);
+	if (!report) return undefined;
+	return {
+		content: [...event.content, { type: "text", text: `\n${report}` }],
+		...(event.structuredContent === undefined ? {} : { structuredContent: event.structuredContent }),
+	};
+}

package/lib/context-backstop.ts

@@ -0,0 +1,84 @@
+import type { ToolResultEvent, ToolResultEventResult } from "@earendil-works/pi-coding-agent";
+
+// Harness roadmap R1: the parent-context backstop was a fixed "~150k tokens" in
+// prompt text, so the model had to estimate its own context. The runtime now
+// measures it with one threshold for every model: carried context is paid on
+// every remaining turn whatever the provider (absolute cap), and quality and
+// headroom depend on how full the window is (fraction of the window).
+
+export const CONTEXT_BACKSTOP_TOKENS = 150_000;
+// Bench gate (harness roadmap T12): on the wide five-feature task, delegating at ~15% of a 272k window cost about
+// 20-40% less and ran ~30% faster than never reaching the backstop, while small tasks never reached it.
+export const CONTEXT_BACKSTOP_FRACTION = 0.15;
+export const CONTEXT_BACKSTOP_TOKENS_ENV = "GENTLE_PI_CONTEXT_BACKSTOP_TOKENS";
+export const CONTEXT_BACKSTOP_FRACTION_ENV = "GENTLE_PI_CONTEXT_BACKSTOP_FRACTION";
+
+/** The part of Pi's `ctx.getContextUsage()` the backstop reads; null tokens are unknown (e.g. right after compaction). */
+export interface MeasuredContext {
+	tokens: number | null | undefined;
+	contextWindow?: number | null;
+}
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+function positive(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function envNumber(env: Env, name: string, valid: (value: number) => boolean, fallback: number): number {
+	const raw = env[name]?.trim();
+	const value = raw ? Number(raw) : Number.NaN;
+	return valid(value) ? value : fallback;
+}
+
+/** min(absolute cap, fraction x context window); an unknown window leaves the cap alone. Never 0: an empty context is not past it. */
+export function contextBackstopThreshold(contextWindow: number | null | undefined, env: Env = process.env): number {
+	const cap = envNumber(env, CONTEXT_BACKSTOP_TOKENS_ENV, positive, CONTEXT_BACKSTOP_TOKENS);
+	const fraction = envNumber(env, CONTEXT_BACKSTOP_FRACTION_ENV, (value) => positive(value) && value <= 1, CONTEXT_BACKSTOP_FRACTION);
+	return positive(contextWindow) ? Math.min(cap, Math.max(1, Math.floor(fraction * contextWindow))) : cap;
+}
+
+/** Unknown tokens never count as reached. */
+export function contextBackstopReached(usage: MeasuredContext | undefined, env: Env = process.env): boolean {
+	return typeof usage?.tokens === "number" && usage.tokens >= contextBackstopThreshold(usage.contextWindow, env);
+}
+
+const count = (value: number) => Math.round(value).toLocaleString("en-US");
+
+function contextBackstopNotice(tokens: number, contextWindow: number | null | undefined, threshold: number): string {
+	const share = positive(contextWindow) ? ` (${Math.round((tokens / contextWindow) * 100)}% of the ${count(contextWindow)}-token context window)` : "";
+	return `Context backstop: the parent context measures ${count(tokens)} tokens${share}, at or past the ${count(threshold)}-token backstop: delegate the next bounded unit that needs several steps (its reads, edits, and checks) with a short handoff, while single small edits and state checks stay inline.`;
+}
+
+/**
+ * One notice per crossing for each session: the first measurement at or past the backstop returns it, and a
+ * measurement below the backstop re-arms it (for example after compaction). Unknown tokens change nothing.
+ */
+export function createContextBackstopSignal(env: Env = process.env): (session: unknown, usage: MeasuredContext | undefined) => string | undefined {
+	const notified = new Set<unknown>();
+	return (session, usage) => {
+		if (typeof usage?.tokens !== "number") return undefined;
+		const threshold = contextBackstopThreshold(usage.contextWindow, env);
+		if (usage.tokens < threshold) {
+			notified.delete(session);
+			return undefined;
+		}
+		if (notified.has(session)) return undefined;
+		notified.add(session);
+		return contextBackstopNotice(usage.tokens, usage.contextWindow, threshold);
+	};
+}
+
+/** Appends the notice after the (possibly already patched) tool output, keeping structured content and the error flag. */
+export function appendContextBackstopNotice(
+	event: Pick<ToolResultEvent, "content" | "structuredContent">,
+	patch: ToolResultEventResult | undefined,
+	notice: string,
+): ToolResultEventResult {
+	const structuredContent = patch?.structuredContent ?? event.structuredContent;
+	return {
+		...patch,
+		content: [...(patch?.content ?? event.content), { type: "text", text: `\n${notice}` }],
+		...(structuredContent === undefined ? {} : { structuredContent }),
+	};
+}

package/lib/delivered-test-lint.ts

@@ -0,0 +1,80 @@
+import { isAbsolute, relative } from "node:path";
+import type { ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+
+// Harness roadmap T5 (R1): a delivered test must pass in any clone. Blind review
+// found tests that read a fixed commit from git history (a differential check
+// leaked into the suite) and orchestrators that pointed TMPDIR into the
+// repository. The prompt rule did not hold, so the runtime blocks the write.
+// Deliberately narrow: git used inside a throwaway repository (`git init`,
+// `git stash`, `HEAD:`) stays allowed; only a literal commit id is history the
+// test cannot own. Content written through bash is not seen here.
+
+const TEST_PATH_PATTERNS = [
+	/(^|[\\/])(tests?|__tests__|spec)[\\/]/,
+	/\.(test|spec)\.[cm]?[jt]sx?$/,
+	/_test\.go$/,
+	/(^|[\\/])test_[^\\/]*\.py$/,
+];
+
+const HISTORY_COMMAND = /\bgit\b[^\n]{0,40}?\b(show|checkout|diff|cat-file|archive)\b([^\n]{0,80})/g;
+const COMMIT_ID = /\b[0-9a-f]{7,40}\b/g;
+// `=` but not `==`/`===`: a comparison with the working directory is not an assignment.
+const TMPDIR_ASSIGNMENT = /\bTMPDIR["']?\]?\s*(?::|=(?!=))\s*([^\n;,}]*)/g;
+const WORKING_DIRECTORY = /\$PWD|\$\{PWD\}|\$\(pwd\)|process\.cwd\(\)|__dirname|import\.meta\.dirname|os\.getcwd\(\)/;
+// A relative path resolves against the working directory too: `.tmp`, `./x`, `../x` or `tmp/x`, quoted or not.
+// Absolute, `~`, `$` or `%` based values and a bare word (`scratch`, `os.tmpdir()`, a fixture value) stay allowed.
+const RELATIVE_PATH = /^\s*["'`]?(?:\.{1,2}[\/\\\w-]|[\w.-]+[\/\\])/;
+
+export function isTestFilePath(path: string): boolean {
+	return TEST_PATH_PATTERNS.some((pattern) => pattern.test(path));
+}
+
+/** A literal commit id mixes digits and letters; all-letter or all-digit words are not treated as one. */
+function isCommitId(token: string): boolean {
+	return /[0-9]/.test(token) && /[a-f]/.test(token);
+}
+
+/** Why this test content cannot be delivered, or undefined when it can. */
+export function deliveredTestViolation(content: string): string | undefined {
+	for (const match of content.matchAll(HISTORY_COMMAND)) {
+		const commit = [...match[2].matchAll(COMMIT_ID)].map((m) => m[0]).find(isCommitId);
+		if (commit) return `reads git history at a fixed commit (\`git ${match[1]} ${commit}\`), which fails in another clone`;
+	}
+	for (const match of content.matchAll(TMPDIR_ASSIGNMENT)) {
+		if (WORKING_DIRECTORY.test(match[1]) || RELATIVE_PATH.test(match[1])) return `points TMPDIR inside the working directory (\`TMPDIR${match[0].slice(6).trim()}\`), so test scratch enters the diff`;
+	}
+	return undefined;
+}
+
+function writtenText(toolName: string, input: Record<string, unknown>): string | undefined {
+	if (toolName === "write") return typeof input.content === "string" ? input.content : undefined;
+	const parts: string[] = [];
+	if (typeof input.newText === "string") parts.push(input.newText);
+	if (Array.isArray(input.edits)) {
+		for (const edit of input.edits) {
+			if (edit && typeof edit === "object" && typeof (edit as { newText?: unknown }).newText === "string") parts.push((edit as { newText: string }).newText);
+		}
+	}
+	return parts.length > 0 ? parts.join("\n") : undefined;
+}
+
+/** An absolute path inside the session cwd is judged by its repository-relative part. */
+function judgedPath(path: string, cwd: string | undefined): string {
+	if (!cwd || !isAbsolute(path)) return path;
+	const inside = relative(cwd, path);
+	return inside && !inside.startsWith("..") && !isAbsolute(inside) ? inside : path;
+}
+
+/** tool_call guard for write and edit, shared by the parent session and every child. */
+export function evaluateDeliveredTestTool(toolName: string, input: unknown, cwd?: string): ToolCallEventResult | undefined {
+	if ((toolName !== "write" && toolName !== "edit") || !input || typeof input !== "object") return undefined;
+	const record = input as Record<string, unknown>;
+	if (typeof record.path !== "string" || !isTestFilePath(judgedPath(record.path, cwd))) return undefined;
+	const text = writtenText(toolName, record);
+	const violation = text === undefined ? undefined : deliveredTestViolation(text);
+	if (!violation) return undefined;
+	return {
+		block: true,
+		reason: `Gentle AI blocked this test write: ${record.path} ${violation}. Delivered tests must pass in any clone: build the previous behavior from a fixture instead of git history, and create scratch with mktemp outside the repository. Run differential checks against a scratch copy of the base and do not commit them as tests.`,
+	};
+}