gentle-pi 4.0.0 → 4.2.0

package/tests/background-jobs.test.ts

@@ -0,0 +1,227 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+import { createJobRegistry, createOutputTail, MAX_RUNNING_JOBS, MAX_TAIL_LINE_CHARS, TAIL_LINES, type JobExecOperations, type JobRecord } from "../lib/background-jobs.ts";
+
+// Background jobs run a shell command while the parent keeps working or stays
+// idle; the registry reports each job's own exit exactly once.
+
+test("output tail keeps the last TAIL_LINES lines, joins partial chunks, and strips CR", () => {
+	const tail = createOutputTail();
+	const lines = Array.from({ length: TAIL_LINES + 5 }, (_, i) => `line ${i}`);
+	tail.push(`${lines.join("\r\n")}\r\n`);
+	assert.deepEqual(tail.lines(), lines.slice(5));
+	tail.push("par");
+	tail.push("tial");
+	assert.deepEqual(tail.lines().at(-1), "partial");
+	assert.equal(tail.lines().length, TAIL_LINES);
+});
+
+test("output tail bounds a line that never ends, keeping its newest characters", () => {
+	const tail = createOutputTail();
+	for (let i = 0; i < 50; i++) tail.push(`${"x".repeat(MAX_TAIL_LINE_CHARS)}`);
+	tail.push("END");
+	const [line] = tail.lines();
+	assert.ok(line!.length <= MAX_TAIL_LINE_CHARS + 1, `kept ${line!.length} characters`);
+	assert.ok(line!.startsWith("…") && line!.endsWith("xEND"));
+	tail.push(`\n${"y".repeat(MAX_TAIL_LINE_CHARS * 3)}\nshort\n`);
+	assert.ok(tail.lines().every((entry) => entry.length <= MAX_TAIL_LINE_CHARS + 1));
+	assert.equal(tail.lines().at(-1), "short");
+});
+
+interface FakeRun {
+	command: string;
+	cwd: string;
+	onData: (data: Buffer) => void;
+	signal?: AbortSignal;
+	resolve: (exitCode: number | null) => void;
+	reject: (error: Error) => void;
+}
+
+function fakeOperations() {
+	const runs: FakeRun[] = [];
+	const operations: JobExecOperations = {
+		exec: (command, cwd, options) => new Promise((resolve, reject) => {
+			const run: FakeRun = { command, cwd, onData: options.onData, signal: options.signal, resolve: (exitCode) => resolve({ exitCode }), reject };
+			options.signal?.addEventListener("abort", () => reject(new Error("aborted")), { once: true });
+			runs.push(run);
+		}),
+	};
+	return { runs, operations };
+}
+
+function setup(commandPrefix?: string) {
+	const dir = mkdtempSync(join(tmpdir(), "gentle-jobs-test-"));
+	const fake = fakeOperations();
+	const settled: JobRecord[] = [];
+	let clock = 1000;
+	const registry = createJobRegistry({
+		outputDir: () => dir,
+		now: () => clock,
+		shell: () => ({ operations: fake.operations, commandPrefix }),
+		onSettled: (job) => settled.push(job),
+	});
+	const tick = (ms: number) => { clock += ms; };
+	return { dir, fake, settled, registry, tick, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+// Settling closes the job's log file first, which takes real I/O turns.
+const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
+
+test("start returns a running job at once and its exit settles it exactly once with output on disk", async () => {
+	const { fake, settled, registry, tick, cleanup } = setup();
+	try {
+		const job = registry.start({ command: "make ci", cwd: "/repo", label: "ci", ownerSessionId: "s1" });
+		assert.equal(job.status, "running");
+		assert.equal(job.id, "job-1");
+		assert.equal(fake.runs[0]!.command, "make ci");
+		assert.equal(fake.runs[0]!.cwd, "/repo");
+		fake.runs[0]!.onData(Buffer.from("building\nok\n"));
+		tick(4200);
+		fake.runs[0]!.resolve(2);
+		await settle();
+		assert.equal(settled.length, 1);
+		const done = settled[0]!;
+		assert.equal(done.status, "exited");
+		assert.equal(done.exitCode, 2);
+		assert.equal(done.endedAt! - done.startedAt, 4200);
+		assert.deepEqual(done.tail, ["building", "ok"]);
+		assert.equal(readFileSync(done.outputPath, "utf8"), "building\nok\n");
+		assert.equal(registry.get("job-1")?.status, "exited");
+	} finally { cleanup(); }
+});
+
+test("a multibyte character split across output chunks reaches the tail intact", async () => {
+	const { fake, settled, registry, cleanup } = setup();
+	try {
+		registry.start({ command: "echo", cwd: "/repo", ownerSessionId: "s1" });
+		const bytes = Buffer.from("ñandú listo\n");
+		fake.runs[0]!.onData(bytes.subarray(0, 1));
+		fake.runs[0]!.onData(bytes.subarray(1, 5));
+		fake.runs[0]!.onData(bytes.subarray(5));
+		fake.runs[0]!.resolve(0);
+		await settle();
+		assert.deepEqual(settled[0]!.tail, ["ñandú listo"]);
+	} finally { cleanup(); }
+});
+
+test("onLine receives each complete output line across chunks, and the last partial line at exit", async () => {
+	const { fake, registry, cleanup } = setup();
+	try {
+		const lines: string[] = [];
+		const job = registry.start({ command: "watch", cwd: "/repo", ownerSessionId: "s1", kind: "monitor", onLine: (line) => lines.push(line) });
+		assert.equal(job.kind, "monitor");
+		fake.runs[0]!.onData(Buffer.from("check lint: pa"));
+		fake.runs[0]!.onData(Buffer.from("ss\r\ncheck test: fail\nlast"));
+		assert.deepEqual(lines, ["check lint: pass", "check test: fail"]);
+		fake.runs[0]!.resolve(0);
+		await settle();
+		assert.deepEqual(lines, ["check lint: pass", "check test: fail", "last"]);
+		assert.equal(registry.start({ command: "x", cwd: "/repo", ownerSessionId: "s1" }).kind, "command");
+	} finally { cleanup(); }
+});
+
+test("onLine bounds an endless line to its newest MAX_TAIL_LINE_CHARS characters", async () => {
+	const { fake, registry, cleanup } = setup();
+	try {
+		const lines: string[] = [];
+		registry.start({ command: "watch", cwd: "/repo", ownerSessionId: "s1", kind: "monitor", onLine: (line) => lines.push(line) });
+		fake.runs[0]!.onData(Buffer.from(`${"x".repeat(MAX_TAIL_LINE_CHARS * 5)}END\nshort\n`));
+		assert.equal(lines.length, 2);
+		assert.ok(lines[0]!.length <= MAX_TAIL_LINE_CHARS + 1 && lines[0]!.startsWith("…") && lines[0]!.endsWith("xEND"));
+		assert.equal(lines[1], "short");
+		fake.runs[0]!.onData(Buffer.from("y".repeat(MAX_TAIL_LINE_CHARS * 5)));
+		fake.runs[0]!.onData(Buffer.from("TAIL\n"));
+		assert.ok(lines[2]!.length <= MAX_TAIL_LINE_CHARS + 1 && lines[2]!.startsWith("…") && lines[2]!.endsWith("yTAIL"));
+	} finally { cleanup(); }
+});
+
+test("stopAll resolves only after every job's log file is closed", async () => {
+	const { registry, cleanup } = setup();
+	try {
+		const job = registry.start({ command: "sleep 100", cwd: "/repo", ownerSessionId: "s1" });
+		await registry.stopAll();
+		assert.equal(job.status, "stopped");
+		assert.equal(registry.pending(), 0);
+	} finally { cleanup(); }
+});
+
+test("the shell command prefix runs before the command, but the job keeps the original command", () => {
+	const { fake, registry, cleanup } = setup("shopt -s expand_aliases");
+	try {
+		const job = registry.start({ command: "ll", cwd: "/repo", ownerSessionId: "s1" });
+		assert.equal(fake.runs[0]!.command, "shopt -s expand_aliases\nll");
+		assert.equal(job.command, "ll");
+		assert.equal(job.label, "ll");
+	} finally { cleanup(); }
+});
+
+test("stop aborts a running job and sends no exit notice; stopping again or an unknown id is a no-op", async () => {
+	const { fake, settled, registry, cleanup } = setup();
+	try {
+		registry.start({ command: "sleep 100", cwd: "/repo", ownerSessionId: "s1" });
+		const stopped = registry.stop("job-1");
+		assert.equal(stopped?.status, "stopped");
+		assert.equal(fake.runs[0]!.signal?.aborted, true);
+		await settle();
+		assert.equal(settled.length, 0);
+		assert.equal(registry.get("job-1")?.status, "stopped");
+		assert.equal(registry.stop("job-1")?.status, "stopped");
+		assert.equal(registry.stop("job-404"), undefined);
+	} finally { cleanup(); }
+});
+
+test("a job that fails to run settles as failed with the error", async () => {
+	const { fake, settled, registry, cleanup } = setup();
+	try {
+		registry.start({ command: "x", cwd: "/missing", ownerSessionId: "s1" });
+		fake.runs[0]!.reject(new Error("Working directory does not exist: /missing"));
+		await settle();
+		assert.equal(settled[0]?.status, "failed");
+		assert.match(settled[0]!.error!, /Working directory does not exist/);
+	} finally { cleanup(); }
+});
+
+test("at most MAX_RUNNING_JOBS run at once; a finished job frees its slot", async () => {
+	const { fake, registry, cleanup } = setup();
+	try {
+		for (let i = 0; i < MAX_RUNNING_JOBS; i++) registry.start({ command: `c${i}`, cwd: "/repo", ownerSessionId: "s1" });
+		assert.throws(() => registry.start({ command: "one more", cwd: "/repo", ownerSessionId: "s1" }), /25 background jobs are already running/);
+		assert.equal(fake.runs.length, MAX_RUNNING_JOBS);
+		fake.runs[0]!.resolve(0);
+		await settle();
+		assert.equal(registry.start({ command: "one more", cwd: "/repo", ownerSessionId: "s1" }).status, "running");
+	} finally { cleanup(); }
+});
+
+test("list filters by owner session and stopAll stops every running job without notices", async () => {
+	const { settled, registry, cleanup } = setup();
+	try {
+		registry.start({ command: "a", cwd: "/repo", ownerSessionId: "s1" });
+		registry.start({ command: "b", cwd: "/repo", ownerSessionId: "s2" });
+		assert.deepEqual(registry.list("s1").map((job) => job.command), ["a"]);
+		assert.equal(registry.list().length, 2);
+		registry.stopAll();
+		await settle();
+		assert.deepEqual(registry.list().map((job) => job.status), ["stopped", "stopped"]);
+		assert.equal(settled.length, 0);
+	} finally { cleanup(); }
+});
+
+test("a real shell job runs through Pi's bash operations and reports its exit code", { skip: process.platform === "win32" }, async () => {
+	const dir = mkdtempSync(join(tmpdir(), "gentle-jobs-real-"));
+	try {
+		const done = new Promise<JobRecord>((resolve) => {
+			const registry = createJobRegistry({ outputDir: () => dir, now: Date.now, shell: () => ({ operations: createLocalBashOperations() }), onSettled: resolve });
+			registry.start({ command: "echo one; echo two >&2; exit 3", cwd: dir, ownerSessionId: "s1" });
+		});
+		const job = await done;
+		assert.equal(job.status, "exited");
+		assert.equal(job.exitCode, 3);
+		assert.deepEqual([...job.tail].sort(), ["one", "two"]);
+		assert.deepEqual(readFileSync(job.outputPath, "utf8").split("\n").filter(Boolean).sort(), ["one", "two"]);
+	} finally { rmSync(dir, { recursive: true, force: true }); }
+});

package/tests/background-monitor.test.ts

@@ -0,0 +1,195 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	createEventBatcher, MONITOR_FLOOD_LINES, MONITOR_FLOOD_WINDOW_MS, MONITOR_LINES_PER_NOTICE, mergeMonitorBatches,
+} from "../lib/background-monitor.ts";
+
+// The batcher turns a monitor's stdout lines into bounded notices. It owns no
+// timers: the caller flushes MONITOR_BATCH_MS after a line opens a batch.
+
+test("the first line of a batch asks the caller to schedule a flush; later lines join it", () => {
+	const batcher = createEventBatcher();
+	assert.deepEqual(batcher.pushLine("check lint: pass", 0), { opensBatch: true, flood: false });
+	assert.deepEqual(batcher.pushLine("check test: fail", 50), { opensBatch: false, flood: false });
+	assert.deepEqual(batcher.flush(), { lines: ["check lint: pass", "check test: fail"], omitted: 0 });
+	assert.equal(batcher.flush(), undefined, "an empty batch is never delivered");
+	assert.equal(batcher.pushLine("check e2e: pass", 300).opensBatch, true, "after a flush the next line opens a new batch");
+	assert.equal(batcher.total(), 3);
+});
+
+test("a batch keeps at most MONITOR_LINES_PER_NOTICE lines and counts the rest", () => {
+	const batcher = createEventBatcher();
+	for (let i = 0; i < MONITOR_LINES_PER_NOTICE + 7; i++) batcher.pushLine(`line ${i}`, i);
+	const batch = batcher.flush()!;
+	assert.equal(batch.lines.length, MONITOR_LINES_PER_NOTICE);
+	assert.equal(batch.lines[0], "line 0");
+	assert.equal(batch.omitted, 7);
+	assert.equal(batcher.total(), MONITOR_LINES_PER_NOTICE + 7);
+});
+
+test("more than MONITOR_FLOOD_LINES lines within the flood window is a flood; a slower stream is not", () => {
+	const slow = createEventBatcher();
+	const spacing = Math.ceil(MONITOR_FLOOD_WINDOW_MS / MONITOR_FLOOD_LINES) + 1;
+	for (let i = 0; i < MONITOR_FLOOD_LINES * 3; i++) assert.equal(slow.pushLine("tick", i * spacing).flood, false);
+	const fast = createEventBatcher();
+	for (let i = 0; i < MONITOR_FLOOD_LINES; i++) assert.equal(fast.pushLine("spam", i).flood, false);
+	assert.equal(fast.pushLine("spam", MONITOR_FLOOD_LINES).flood, true);
+});
+
+test("blank lines are not events", () => {
+	const batcher = createEventBatcher();
+	assert.deepEqual(batcher.pushLine("   ", 0), { opensBatch: false, flood: false });
+	assert.equal(batcher.total(), 0);
+	assert.equal(batcher.flush(), undefined);
+});
+
+test("pending batches for one monitor coalesce within the same line bound", () => {
+	assert.deepEqual(mergeMonitorBatches({ lines: ["a", "b"], omitted: 1 }, { lines: ["c"], omitted: 2 }), { lines: ["a", "b", "c"], omitted: 3 });
+	const full = { lines: Array.from({ length: MONITOR_LINES_PER_NOTICE }, (_, i) => `x${i}`), omitted: 0 };
+	assert.deepEqual(mergeMonitorBatches(full, { lines: ["late", "later"], omitted: 4 }), { lines: full.lines, omitted: 6 });
+});
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createJobRegistry, type JobExecOperations, type JobRecord } from "../lib/background-jobs.ts";
+import { createMonitorController, MONITOR_BATCH_MS, type MonitorNotice } from "../lib/background-monitor.ts";
+
+// A fake clock and scheduler drive the controller; a fake shell feeds lines.
+function monitorHarness() {
+	const dir = mkdtempSync(join(tmpdir(), "gentle-monitor-test-"));
+	let clock = 0;
+	const timers: Array<{ at: number; fn: () => void; live: boolean }> = [];
+	const schedule = (fn: () => void, ms: number) => {
+		const timer = { at: clock + ms, fn, live: true };
+		timers.push(timer);
+		return () => { timer.live = false; };
+	};
+	const advance = (ms: number) => {
+		clock += ms;
+		for (const timer of timers.filter((entry) => entry.live && entry.at <= clock)) { timer.live = false; timer.fn(); }
+	};
+	const runs: Array<{ onData(data: Buffer): void; signal?: AbortSignal; exit(code: number): void }> = [];
+	const operations: JobExecOperations = {
+		exec: (_command, _cwd, options) => new Promise((done, fail) => {
+			options.signal?.addEventListener("abort", () => fail(new Error("aborted")), { once: true });
+			runs.push({ onData: options.onData, signal: options.signal, exit: (code) => done({ exitCode: code }) });
+		}),
+	};
+	const settled: JobRecord[] = [];
+	let notifySettled!: () => void;
+	const completion = new Promise<void>((resolve) => { notifySettled = resolve; });
+	const registry = createJobRegistry({ outputDir: () => dir, now: () => clock, shell: () => ({ operations }), onSettled: (job) => { settled.push(job); notifySettled(); } });
+	const notices: MonitorNotice[] = [];
+	const controller = createMonitorController({ registry, schedule, now: () => clock, deliver: (notice) => notices.push(notice) });
+	const line = (text: string) => runs.at(-1)!.onData(Buffer.from(`${text}\n`));
+	return { controller, registry, runs, notices, settled, completion, advance, line, cleanup: () => rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }) };
+}
+
+test("a monitor delivers lines within one batch window as one events notice, and keeps running", () => {
+	const h = monitorHarness();
+	try {
+		const job = h.controller.start({ command: "gh run watch", cwd: "/repo", ownerSessionId: "s1", label: "CI", timeoutSeconds: 600 });
+		assert.equal(job.kind, "monitor");
+		h.line("lint: pass");
+		h.advance(50);
+		h.line("unit: fail");
+		assert.equal(h.notices.length, 0, "nothing is delivered before the batch window closes");
+		h.advance(MONITOR_BATCH_MS);
+		assert.deepEqual(h.notices, [{ job, kind: "events", batch: { lines: ["lint: pass", "unit: fail"], omitted: 0 } }]);
+		assert.equal(job.status, "running");
+		assert.equal(job.events, 2);
+	} finally { h.controller.cancelAll(); h.cleanup(); }
+});
+
+test("the mandatory timeout stops a monitor after delivering its pending lines", () => {
+	const h = monitorHarness();
+	try {
+		const job = h.controller.start({ command: "tail -f log", cwd: "/repo", ownerSessionId: "s1", timeoutSeconds: 30 });
+		h.advance(29_900);
+		h.line("ERROR one");
+		h.advance(100);
+		assert.deepEqual(h.notices.map((notice) => notice.kind), ["events", "stopped"]);
+		assert.deepEqual(h.notices[1], { job, kind: "stopped", reason: "timeout" });
+		assert.equal(job.status, "stopped");
+		assert.equal(h.runs[0]!.signal?.aborted, true);
+	} finally { h.controller.cancelAll(); h.cleanup(); }
+});
+
+test("a flooding monitor is stopped and reported once; later lines are ignored", () => {
+	const h = monitorHarness();
+	try {
+		const job = h.controller.start({ command: "yes", cwd: "/repo", ownerSessionId: "s1", timeoutSeconds: 600 });
+		for (let i = 0; i < 200; i++) h.line(`spam ${i}`);
+		const kinds = h.notices.map((notice) => notice.kind);
+		assert.deepEqual(kinds, ["events", "stopped"]);
+		assert.deepEqual(h.notices[1], { job, kind: "stopped", reason: "flood" });
+		assert.equal(job.status, "stopped");
+		h.advance(MONITOR_BATCH_MS * 10);
+		assert.equal(h.notices.length, 2, "a stopped monitor delivers nothing more");
+	} finally { h.controller.cancelAll(); h.cleanup(); }
+});
+
+test("finish flushes pending lines before the exit notice; cancel drops timers without notices", async () => {
+	const h = monitorHarness();
+	try {
+		const job = h.controller.start({ command: "watch", cwd: "/repo", ownerSessionId: "s1", timeoutSeconds: 60 });
+		h.line("last check: pass");
+		h.runs[0]!.exit(0);
+		await h.completion;
+		assert.equal(h.settled[0], job);
+		h.controller.finish(job);
+		assert.deepEqual(h.notices.map((notice) => notice.kind), ["events"]);
+		h.advance(120_000);
+		assert.equal(h.notices.length, 1, "a finished monitor has no timeout left");
+
+		const other = h.controller.start({ command: "watch", cwd: "/repo", ownerSessionId: "s1", timeoutSeconds: 60 });
+		h.line("pending");
+		h.controller.cancel(other.id);
+		h.advance(120_000);
+		assert.equal(h.notices.length, 1, "a cancelled monitor delivers nothing more");
+	} finally { h.controller.cancelAll(); h.cleanup(); }
+});
+
+test("timeout_seconds is mandatory and capped at 30 minutes", () => {
+	const h = monitorHarness();
+	try {
+		for (const timeoutSeconds of [0, -1, 1801, Number.NaN, 1.5]) {
+			assert.throws(() => h.controller.start({ command: "x", cwd: "/repo", ownerSessionId: "s1", timeoutSeconds }), /timeout_seconds must be a whole number from 1 to 1800/);
+		}
+		assert.equal(h.runs.length, 0, "an invalid monitor never starts a process");
+	} finally { h.controller.cancelAll(); h.cleanup(); }
+});
+
+test("a timeout that fires after the command already exited reports nothing; the exit wins", async () => {
+	const h = monitorHarness();
+	try {
+		const job = h.controller.start({ command: "watch", cwd: "/repo", ownerSessionId: "s1", timeoutSeconds: 1 });
+		h.advance(900);
+		h.line("last line");
+		h.runs[0]!.exit(0);
+		await Promise.resolve();
+		await Promise.resolve();
+		assert.equal(job.status, "exited", "the exit is recorded before its log closes");
+		h.advance(100);
+		assert.deepEqual(h.notices, [], "no stopped notice for a monitor that ended on its own");
+		await h.completion;
+		assert.equal(h.settled[0], job);
+		h.controller.finish(job);
+		assert.deepEqual(h.notices, [{ job, kind: "events", batch: { lines: ["last line"], omitted: 0 } }], "its pending line still arrives");
+	} finally { h.controller.cancelAll(); h.cleanup(); }
+});
+
+test("stopped notices name the timeout or flood limit and where the full output is", async () => {
+	const { monitorStoppedText } = await import("../lib/background-jobs-tools.ts");
+	const h = monitorHarness();
+	try {
+		const job = h.controller.start({ command: "tail -f log", cwd: "/repo", ownerSessionId: "s1", label: "log", timeoutSeconds: 30 });
+		h.advance(30_000);
+		const timeout = monitorStoppedText(job, "timeout");
+		assert.match(timeout, /reached its 30s timeout after 0 events/);
+		assert.ok(timeout.includes(`Full output: ${job.outputPath}`));
+		const flood = monitorStoppedText(job, "flood");
+		assert.ok(flood.includes(`Full output: ${job.outputPath}`));
+	} finally { h.controller.cancelAll(); h.cleanup(); }
+});

package/tests/background-subagents-default-mode.test.ts

@@ -8,10 +8,11 @@ import { resolveDefaultSubagentMode } from "../extensions/gentle-agents.ts";
 // neither an explicit params.mode nor an agent-defined mode was given.
 //
 // Background is a runtime default only when the background-subagents policy
-// is "on" AND the parent can receive background results. Print mode exits
-// before a parent session exists to deliver a background result to, so it
-// must keep the configured default even when the policy is on (see the
-// `ctx.mode === "print"` guard in gentle-agents.ts `launch`).
+// is "on" AND the parent can receive background results. The single-shot
+// modes (`pi -p` and `pi --mode json`) dispose the runtime once the prompt
+// returns, before a background result can be delivered, so they must keep
+// the configured default even when the policy is on (see the single-shot
+// guard in gentle-agents.ts `launch`).
 // ---------------------------------------------------------------------------
 
 test("policy on + interactive parent -> background", () => {
@@ -25,6 +26,28 @@ test("policy on + interactive parent -> background", () => {
 	);
 });
 
+test("policy on + tui parent -> background", () => {
+	assert.equal(
+		resolveDefaultSubagentMode({
+			configuredDefault: AGENT_MODE.TASK,
+			policy: "on",
+			parentMode: "tui",
+		}),
+		AGENT_MODE.BACKGROUND,
+	);
+});
+
+test("policy on + json parent -> configured default (task), never background", () => {
+	assert.equal(
+		resolveDefaultSubagentMode({
+			configuredDefault: AGENT_MODE.TASK,
+			policy: "on",
+			parentMode: "json",
+		}),
+		AGENT_MODE.TASK,
+	);
+});
+
 test("policy on + rpc parent -> background", () => {
 	assert.equal(
 		resolveDefaultSubagentMode({
@@ -48,7 +71,7 @@ test("policy on + print parent -> configured default (task), never background",
 });
 
 test("policy off -> configured default regardless of parent mode", () => {
-	for (const parentMode of ["interactive", "rpc", "print", undefined]) {
+	for (const parentMode of ["interactive", "tui", "rpc", "print", "json", undefined]) {
 		assert.equal(
 			resolveDefaultSubagentMode({
 				configuredDefault: AGENT_MODE.TASK,

package/tests/bounded-stop-contract.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+
+// gentle-shell#1731 T23 (G1 audit L48): port the gentle-ai Native Checking
+// Contract bounded stop. Partial, blocked, unavailable, or exhausted proof
+// becomes one **Needs your decision** result instead of more verification; the
+// close gate accepts that result as a stop; writer self-review and worker
+// validation stop after a bounded correction; a quick check runs once; an
+// unavailable verifier is reported, never retried or escalated.
+// These are instruction-delivery contracts, not proof of model adherence.
+
+const read = (relative: string): string => readFileSync(join(import.meta.dirname, "..", relative), "utf8");
+const verification = read("assets/orchestrator-verification.md");
+const tracking = read("assets/orchestrator-tracking.md");
+const worker = read("assets/agents/gentle-ai-worker.md");
+const verify = read("assets/agents/gentle-ai-verify.md");
+const personas = ["gentleman", "neutral"] as const;
+
+function lineStarting(text: string, prefix: string): string {
+	const line = text.split("\n").find((entry) => entry.startsWith(prefix));
+	assert.ok(line, `missing line starting with: ${prefix}`);
+	return line;
+}
+
+function containsAll(text: string, clauses: readonly string[], label: string): void {
+	for (const clause of clauses) assert.ok(text.includes(clause), `${label} is missing: ${clause}`);
+}
+
+function closeStep(persona: (typeof personas)[number]): string {
+	return lineStarting(__testing.buildGentlePrompt(persona), "7. **Close.**");
+}
+
+test("T23(a): a partial or blocked writer gets the one correction, then Needs your decision, never more verify", () => {
+	containsAll(lineStarting(verification, "5. **One correction**"), [
+		"A `partial` or `blocked` writer report gets only this correction, never an extra verify run beyond the risk tier's verifier",
+		"partial, blocked, unavailable, or exhausted proof left after it becomes that one **Needs your decision**",
+	], "verification correction bound");
+	for (const persona of personas) {
+		containsAll(closeStep(persona), [
+			"Partial, blocked, unavailable, or exhausted proof becomes one **Needs your decision** result naming the open blockers or missing proof, never more verification",
+		], `${persona} harness Close step`);
+	}
+});
+
+test("T23(b): the close gate accepts one Needs your decision result as a stop, hedged wording still is not", () => {
+	for (const persona of personas) {
+		containsAll(closeStep(persona), [
+			"Never end with a tracked task pending unless you quote the user's explicit stop.",
+			"that result is a valid stop, hedged wording is not",
+		], `${persona} harness Close step`);
+	}
+	containsAll(tracking, [
+		"continue it or quote the exact user sentence that orders the stop. One **Needs your decision** result naming the open blockers or missing proof is also a valid stop.",
+		"Hedged delivery wording (the user may stop you, review commits one at a time, or pick the work up later) asks for resumable notes and separate commits, not a stop",
+	], "tracking Close gate");
+});
+
+test("T23(c): writer self-review and worker validation stop after a bounded correction", () => {
+	containsAll(lineStarting(verification, "1. **Self-review**"), [
+		"fixes and continues (one correction per failing check, a second only if the same check still fails, then `partial`)",
+	], "self-review item");
+	containsAll(worker, [
+		"Do not claim completion while required validation is failing.",
+		"Make one correction attempt per failing check, and a second only if the same check still fails after a real fix; then stop and return `status: partial` with the failing command and its output, never looping.",
+	], "worker Test discipline");
+});
+
+test("T23(d)(e): a quick check runs once and an unavailable verifier is reported, never retried", () => {
+	for (const persona of personas) {
+		containsAll(closeStep(persona), [
+			"An applicable quick check runs once",
+			"an unavailable verifier or subagent is reported as unavailable, never retried or escalated into extra ceremony",
+		], `${persona} harness Close step`);
+	}
+});
+
+test("T23(f): the verify agent allows a second correction only for the same blocker still failing", () => {
+	containsAll(lineStarting(verify, "5. **Every item.**"), [
+		"one correction batch and one recheck limited to the reported blockers",
+		"a second correction only when the recheck shows the same blocker still failing, never for a new finding",
+	], "verify item 5");
+});

package/tests/bounded-writer-admission.test.ts

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { __testing } from "../extensions/gentle-ai.ts";
-import { bindSessionRepositoryPreparation, boundSessionRepositoryAuthorityCurrent, captureBoundSessionRepositoryAuthority, isDevelopmentSurface, prepareBoundSessionRepository, sessionRepositoryAuthority } from "../lib/bounded-writer-admission.ts";
+import { allowedEditSurfaces, inheritAllowedEditSurfaces, isBoundedWriter, bindSessionRepositoryPreparation, boundSessionRepositoryAuthorityCurrent, captureBoundSessionRepositoryAuthority, isDevelopmentSurface, prepareBoundSessionRepository, safeBootstrapDirectory, sessionRepositoryAuthority } from "../lib/bounded-writer-admission.ts";
 import type { NativeReviewCli } from "../lib/native-review-cli.ts";
 
 test("development admission excludes sensitive, config and bookkeeping surfaces structurally", () => {
@@ -93,3 +93,54 @@ test("explicit review protects canonical HOME aliases, filesystem root and sensi
 	}
 	assert.equal(calls, 0, "no native STATUS against protected directories");
 });
+
+// A Git repository created in HOME, an ancestor of it, or a broad user folder
+// turns every later Git call in the user's tree into a scan of everything
+// below it (a Windows user measured ~47s startups). Bootstrap refuses them.
+test("native bootstrap refuses HOME ancestors and broad user folders but keeps project folders", t => {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "bootstrap-broad-")));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const home = join(root, "home");
+	const broad = ["Documents", "Desktop", "Downloads", "OneDrive", "OneDrive - Contoso", join("OneDrive", "Documents")];
+	for (const folder of [...broad, join("Documents", "project"), "project"]) mkdirSync(join(home, folder), { recursive: true });
+	for (const target of [root, home, ...broad.map(folder => join(home, folder))]) assert.equal(safeBootstrapDirectory(target, { home }), undefined, target);
+	for (const target of [join(home, "project"), join(home, "Documents", "project")]) assert.equal(safeBootstrapDirectory(target, { home }), target, target);
+});
+
+test("native bootstrap compares HOME case-insensitively on Windows only", t => {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "bootstrap-case-")));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const home = join(root, "home");
+	mkdirSync(join(home, "project"), { recursive: true });
+	const differentlyCasedHome = home.toUpperCase();
+	assert.equal(safeBootstrapDirectory(home, { home: differentlyCasedHome, platform: "win32" }), undefined);
+	assert.equal(safeBootstrapDirectory(home, { home: differentlyCasedHome, platform: "linux" }), home);
+	assert.equal(safeBootstrapDirectory(join(home, "project"), { home: differentlyCasedHome, platform: "win32" }), join(home, "project"));
+});
+
+// gentle-shell#1713: a writer continuation without its own section was
+// rejected, and every retry shortened the follow-up. A continuation resumes
+// the same delegated task, so it inherits the surfaces that launch admitted.
+test("writer continuations inherit the original surfaces only when they carry none", () => {
+	const original = "Implement it.\n\n## Allowed edit surfaces\n- src/model.ts\n- `docs/with space.md`\n\n## Return\nReport";
+	const inherited = inheritAllowedEditSurfaces("gentle-ai-worker", "Continue with the remaining specs.", undefined, original);
+	assert.deepEqual(allowedEditSurfaces(inherited), ["docs/with space.md", "src/model.ts"]);
+	assert.ok(inherited.startsWith("Continue with the remaining specs."));
+	const own = "Continue.\n## Allowed edit surfaces\nsrc/other.ts";
+	assert.equal(inheritAllowedEditSurfaces("gentle-ai-worker", own, undefined, original), own, "a follow-up section is validated as written, never merged");
+	const viaContext = "## Allowed edit surfaces\nsrc/other.ts";
+	assert.equal(inheritAllowedEditSurfaces("worker", "Continue.", viaContext, original), "Continue.");
+	assert.equal(inheritAllowedEditSurfaces("gentle-ai-explore", "Continue.", undefined, original), "Continue.", "non-writers are untouched");
+	assert.equal(inheritAllowedEditSurfaces("jd-fix-agent", "Continue.", undefined, original), "Continue.", "Judgment Day fix batches keep their exact protocol");
+	assert.equal(inheritAllowedEditSurfaces("gentle-ai-worker", "Continue.", undefined, "No surfaces here."), "Continue.", "nothing to inherit stays rejectable");
+	// Review R3-002: an entry admitted only when quoted must round-trip quoted.
+	const quotedOnly = "## Allowed edit surfaces\n- `-`\n- src/model.ts";
+	assert.deepEqual(allowedEditSurfaces(quotedOnly), ["-", "src/model.ts"]);
+	assert.deepEqual(allowedEditSurfaces(inheritAllowedEditSurfaces("worker", "Continue.", undefined, quotedOnly)), ["-", "src/model.ts"]);
+});
+
+// gentle-shell#1731: only agents behind the surfaces guard claim surfaces at runtime.
+test("bounded writers are exactly the agents behind the Allowed edit surfaces guard", () => {
+	for (const name of ["gentle-ai-worker", "worker", "jd-fix-agent"]) assert.equal(isBoundedWriter(name), true, name);
+	for (const name of ["explore", "gentle-ai-explore", "gentle-ai-verify", "reviewer", ""]) assert.equal(isBoundedWriter(name), false, name);
+});