@os-eco/overstory-cli 0.10.3 → 0.11.0

package/src/agents/turn-runner.test.ts

@@ -534,6 +534,108 @@ describe("runTurn", () => {
 		expect(after?.state).toBe("completed");
 	});
 
+	test("turn that runs but does not complete settles to between_turns, not working (overstory-3087)", async () => {
+		// Spawn-per-turn substate split: a turn that produced events but did
+		// not deliver the terminal mail nor abort must end in `between_turns`
+		// so the UI can tell a worker waiting for its next mail batch from
+		// one mid-execution. Pre-3087 this settled to `working`.
+		seedSession(ctx.sessionsDbPath, { agentName: "settler", state: "booting" });
+		const { runtime } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			// Force is_error=true so the runner does NOT classify this as a
+			// clean exit (which would settle to `completed` via the
+			// terminal-mail-missing path). is_error=true keeps cleanResult
+			// false, sending us into the observedAnyEvent → between_turns
+			// branch we want to test.
+			emitFakeTurn(fake, { sessionId: "settler-sid", isError: true });
+			fake._exit(0);
+			return fake;
+		};
+
+		const result = await runTurn(makeRunOpts(ctx, "settler", { runtime, _spawnFn: spawnFn }));
+
+		expect(result.cleanResult).toBe(false);
+		expect(result.terminalMailObserved).toBe(false);
+		expect(result.terminalMailMissing).toBe(false);
+		expect(result.finalState).toBe("between_turns");
+
+		const after = readSession(ctx.sessionsDbPath, "settler");
+		expect(after?.state).toBe("between_turns");
+	});
+
+	test("first parser event transitions booting → in_turn (overstory-3087)", async () => {
+		// The mid-turn "first event" hook must flip the row out of `booting`
+		// (or `between_turns`/`working`) into `in_turn` so observers see the
+		// agent as actively executing, distinct from the idle waiting state.
+		seedSession(ctx.sessionsDbPath, { agentName: "boots", state: "booting" });
+		const { runtime } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		// Mutable ref so the IIFE assignment is visible to the type checker.
+		const captured: { state: string | null } = { state: null };
+		const spawnFn: TurnSpawnFn = () => {
+			(async () => {
+				// Push the init event, then sample the row before result.
+				fake._pushLine(
+					JSON.stringify({
+						type: "system",
+						subtype: "init",
+						session_id: "boots-sid",
+						model: "claude-test",
+					}),
+				);
+				// Yield the event loop so the parser drains the init event
+				// and updates the session row before we read it.
+				await Bun.sleep(20);
+				captured.state = readSession(ctx.sessionsDbPath, "boots")?.state ?? null;
+				// Send is_error=true so we settle to between_turns rather than
+				// the contract-violation completed path — this test is about
+				// the mid-turn transition, not the terminal classification.
+				emitFakeTurn(fake, { sessionId: "boots-sid", isError: true });
+				fake._exit(0);
+			})();
+			return fake;
+		};
+
+		await runTurn(makeRunOpts(ctx, "boots", { runtime, _spawnFn: spawnFn }));
+
+		expect(captured.state).toBe("in_turn");
+	});
+
+	test("between_turns → in_turn → between_turns cycle on a follow-up batch (overstory-3087)", async () => {
+		// A spawn-per-turn worker that finished its first turn (state=
+		// between_turns) must flip back to in_turn when the next mail batch
+		// fires its first parser event, and settle back to between_turns
+		// when the turn ends without a terminal mail.
+		seedSession(ctx.sessionsDbPath, { agentName: "cycle", state: "between_turns" });
+		const { runtime } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const captured: { midTurnState: string | null } = { midTurnState: null };
+		const spawnFn: TurnSpawnFn = () => {
+			(async () => {
+				fake._pushLine(
+					JSON.stringify({
+						type: "system",
+						subtype: "init",
+						session_id: "cycle-sid",
+						model: "claude-test",
+					}),
+				);
+				await Bun.sleep(20);
+				captured.midTurnState = readSession(ctx.sessionsDbPath, "cycle")?.state ?? null;
+				emitFakeTurn(fake, { sessionId: "cycle-sid", isError: true });
+				fake._exit(0);
+			})();
+			return fake;
+		};
+
+		const result = await runTurn(makeRunOpts(ctx, "cycle", { runtime, _spawnFn: spawnFn }));
+
+		expect(captured.midTurnState).toBe("in_turn");
+		expect(result.initialState).toBe("between_turns");
+		expect(result.finalState).toBe("between_turns");
+	});
+
 	test("clean exit but no worker_done → contract violation, completed + error log (overstory-6071)", async () => {
 		// Pre-fix: claude exiting cleanly without sending the capability's
 		// terminal mail left the session at `working` forever — the process is
@@ -1006,6 +1108,169 @@ describe("runTurn", () => {
 		}
 	});
 
+	// --- Resume-path parent-notify (overstory-de3c) ---
+	//
+	// The witnessed bug: a spawn-per-turn worker that survived a first-turn
+	// parser stall (worker_died emitted, state→zombie) was re-dispatched by its
+	// parent via `ov sling --recover`. The resumed turn ran, then transitioned
+	// to zombie SILENTLY — no second worker_died mail was ever sent. The lead
+	// blocked forever.
+	//
+	// These tests pin down whether the runner itself is responsible. Each seeds
+	// `claudeSessionId` so the runner exercises the --resume code path, and
+	// asserts that worker_died is still emitted on stall / abort / clean-exit-
+	// without-terminal-mail. If these PASS the runner is exonerated and the
+	// fix is upstream (sling.ts re-spawn upsert dropping parentAgent — H1).
+
+	test("resume-stall: parser stall on a resumed session still emits worker_died (overstory-de3c)", async () => {
+		seedSession(ctx.sessionsDbPath, {
+			agentName: "child-resume-stall",
+			state: "working",
+			parentAgent: "lead-r",
+			taskId: "task-de3c-stall",
+			claudeSessionId: "prior-session",
+		});
+		const { runtime, spawnCalls } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			// Emit nothing — the resumed turn parser-stalls.
+			return fake;
+		};
+
+		const sharedMail = createMailStore(ctx.mailDbPath);
+		try {
+			const result = await runTurn({
+				...makeRunOpts(ctx, "child-resume-stall", {
+					runtime,
+					_spawnFn: spawnFn,
+				}),
+				_mailStore: sharedMail,
+				eventStallTimeoutMs: 50,
+				sigkillDelayMs: 25,
+			});
+
+			expect(result.stallAborted).toBe(true);
+			expect(result.finalState).toBe("zombie");
+
+			// The runtime received the prior session id (resume path exercised).
+			expect(spawnCalls[0]?.resumeSessionId).toBe("prior-session");
+
+			const inbox = sharedMail.getAll({ to: "lead-r", type: "worker_died" });
+			expect(inbox.length).toBe(1);
+			const payload = JSON.parse(inbox[0]?.payload ?? "{}") as {
+				terminatedBy?: string;
+				reason?: string;
+				agentName?: string;
+			};
+			expect(payload.terminatedBy).toBe("runner");
+			expect(payload.reason).toContain("stalled");
+			expect(payload.agentName).toBe("child-resume-stall");
+		} finally {
+			sharedMail.close();
+		}
+	});
+
+	test("resume-abort: operator abort on a resumed session still emits worker_died (overstory-de3c)", async () => {
+		seedSession(ctx.sessionsDbPath, {
+			agentName: "child-resume-abort",
+			state: "working",
+			parentAgent: "lead-r",
+			taskId: "task-de3c-abort",
+			claudeSessionId: "prior-session",
+		});
+		const { runtime, spawnCalls } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const ac = new AbortController();
+		const spawnFn: TurnSpawnFn = () => {
+			fake._pushLine(
+				JSON.stringify({
+					type: "system",
+					subtype: "init",
+					session_id: "prior-session",
+				}),
+			);
+			return fake;
+		};
+
+		const sharedMail = createMailStore(ctx.mailDbPath);
+		try {
+			const runPromise = runTurn({
+				...makeRunOpts(ctx, "child-resume-abort", {
+					runtime,
+					_spawnFn: spawnFn,
+					abortSignal: ac.signal,
+					sigkillDelayMs: 25,
+				}),
+				_mailStore: sharedMail,
+			});
+			await Bun.sleep(60);
+			ac.abort();
+			const result = await runPromise;
+
+			expect(result.finalState).toBe("zombie");
+			expect(spawnCalls[0]?.resumeSessionId).toBe("prior-session");
+
+			const inbox = sharedMail.getAll({ to: "lead-r", type: "worker_died" });
+			expect(inbox.length).toBe(1);
+			const payload = JSON.parse(inbox[0]?.payload ?? "{}") as {
+				terminatedBy?: string;
+				reason?: string;
+				agentName?: string;
+			};
+			expect(payload.terminatedBy).toBe("runner");
+			expect(payload.reason).toContain("Aborted");
+			expect(payload.agentName).toBe("child-resume-abort");
+		} finally {
+			sharedMail.close();
+		}
+	});
+
+	test("resume-terminalMailMissing: clean exit on a resumed session still emits worker_died (overstory-de3c)", async () => {
+		seedSession(ctx.sessionsDbPath, {
+			agentName: "child-resume-noop",
+			state: "working",
+			parentAgent: "lead-r",
+			taskId: "task-de3c-noop",
+			claudeSessionId: "prior-session",
+		});
+		const { runtime, spawnCalls } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			emitFakeTurn(fake, { sessionId: "prior-session", isError: false });
+			fake._exit(0);
+			return fake;
+		};
+
+		const sharedMail = createMailStore(ctx.mailDbPath);
+		try {
+			const result = await runTurn({
+				...makeRunOpts(ctx, "child-resume-noop", {
+					runtime,
+					_spawnFn: spawnFn,
+				}),
+				_mailStore: sharedMail,
+			});
+
+			expect(result.cleanResult).toBe(true);
+			expect(result.terminalMailMissing).toBe(true);
+			expect(result.finalState).toBe("completed");
+			expect(spawnCalls[0]?.resumeSessionId).toBe("prior-session");
+
+			const inbox = sharedMail.getAll({ to: "lead-r", type: "worker_died" });
+			expect(inbox.length).toBe(1);
+			const payload = JSON.parse(inbox[0]?.payload ?? "{}") as {
+				terminatedBy?: string;
+				reason?: string;
+				agentName?: string;
+			};
+			expect(payload.terminatedBy).toBe("runner");
+			expect(payload.reason).toContain("Clean exit without terminal mail");
+			expect(payload.agentName).toBe("child-resume-noop");
+		} finally {
+			sharedMail.close();
+		}
+	});
+
 	test("terminalMailMissing: emits worker_died to parent (overstory-4159)", async () => {
 		// Silent-no-op: claude exits cleanly but never sends worker_done. The
 		// lead would otherwise block forever waiting for a terminal mail.
@@ -1447,4 +1712,601 @@ describe("runTurn", () => {
 		// turn.pid must still be cleaned up regardless.
 		expect(existsSync(turnPidPathFor(ctx, "ss-fail"))).toBe(false);
 	});
+
+	// ---------- mid-turn lastActivity refresh (overstory-8e61) ----------
+	//
+	// The watchdog's design (src/watchdog/health.ts:242-243) documents that the
+	// runner advances `session.lastActivity` per parser event during a turn.
+	// Without that, a long-running turn looks stalled to the watchdog and the
+	// agent gets zombified mid-flight. These tests pin the per-event refresh
+	// behavior added inside the parser loop.
+
+	test("mid-turn refresh: lastActivity advances when interval=0 forces per-event refresh", async () => {
+		const startedAt = new Date(Date.now() - 60_000).toISOString();
+		seedSession(ctx.sessionsDbPath, {
+			agentName: "midturn-A",
+			state: "working",
+			startedAt,
+			lastActivity: startedAt,
+		});
+		const { runtime } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			emitFakeTurn(fake, { sessionId: "midturn-A-session" });
+			fake._exit(0);
+			return fake;
+		};
+
+		await runTurn({
+			...makeRunOpts(ctx, "midturn-A", { runtime, _spawnFn: spawnFn }),
+			lastActivityRefreshIntervalMs: 0,
+		});
+
+		const after = readSession(ctx.sessionsDbPath, "midturn-A");
+		expect(after?.lastActivity).not.toBe(startedAt);
+		expect(new Date(after?.lastActivity ?? 0).getTime()).toBeGreaterThan(
+			new Date(startedAt).getTime(),
+		);
+	});
+
+	test("mid-turn refresh: throttle gates updates by simulated time", async () => {
+		seedSession(ctx.sessionsDbPath, { agentName: "midturn-B", state: "working" });
+		const { runtime } = makeSpyRuntime();
+
+		// Controlled sim clock. `_now` is invoked many times during a turn (for
+		// startedAtMs, log timestamps, durationMs) — only the in-loop calls
+		// matter for the throttle. We advance simTime synchronously between
+		// pushes and yield to the parser between each push so the runner reads
+		// the simTime we set just prior. simTime starts well above the throttle
+		// interval so the first event fires (initial lastActivityRefreshMs=0).
+		let simTime = 5000;
+		const _now = (): Date => new Date(simTime);
+
+		let refreshes = 0;
+		const _onLastActivityRefresh = (): void => {
+			refreshes++;
+		};
+
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			(async () => {
+				const sessionId = "midturn-B-session";
+				// Use `system` lines because the claude parser does not batch
+				// them — every system line yields exactly one status event,
+				// driving one runner-loop iteration each. Assistant text would
+				// coalesce inside a flush window and defeat the per-event count.
+				const stamps = [5000, 5500, 6000, 6500, 7000, 7500];
+				for (let i = 0; i < stamps.length; i++) {
+					simTime = stamps[i] ?? 0;
+					fake._pushLine(
+						JSON.stringify({
+							type: "system",
+							subtype: i === 0 ? "init" : "progress",
+							session_id: sessionId,
+						}),
+					);
+					// Yield so the for-await loop body runs to completion against
+					// the simTime value we just set.
+					await Bun.sleep(20);
+				}
+				// Trailing result at the same simTime as the last chunk; with a
+				// 1000ms throttle and last refresh at simTime=7000, this event
+				// at simTime=7500 (delta=500) does not fire.
+				fake._pushLine(
+					JSON.stringify({
+						type: "result",
+						subtype: "success",
+						session_id: sessionId,
+						result: "done",
+						is_error: false,
+						duration_ms: 50,
+						num_turns: 1,
+					}),
+				);
+				await Bun.sleep(20);
+				fake._exit(0);
+			})();
+			return fake;
+		};
+
+		await runTurn({
+			...makeRunOpts(ctx, "midturn-B", { runtime, _spawnFn: spawnFn }),
+			lastActivityRefreshIntervalMs: 1000,
+			_now,
+			_onLastActivityRefresh,
+		});
+
+		// Stamps 5000, 6000, 7000 fire (gap >= 1000). Stamps 5500, 6500, 7500
+		// are throttled (gap = 500). The trailing result event at 7500 also
+		// throttles. Total expected = 3.
+		expect(refreshes).toBe(3);
+	});
+
+	test("mid-turn refresh: parser throw still leaves lastActivity advanced (overstory-8e61)", async () => {
+		// The end-of-turn `updateSessionLastActivity` (around turn-runner.ts:1112)
+		// does NOT fire when the parser iteration throws — the catch path
+		// rethrows before reaching the cleanup write. The mid-turn refresh
+		// covers this gap so a parser-error turn still leaves lastActivity
+		// fresh, mirroring the documented design at src/watchdog/health.ts:242-243.
+		const startedAt = new Date(Date.now() - 60_000).toISOString();
+		seedSession(ctx.sessionsDbPath, {
+			agentName: "midturn-C",
+			state: "working",
+			startedAt,
+			lastActivity: startedAt,
+		});
+
+		// Custom runtime: yield two valid events, then throw on the next read.
+		// Mirrors a malformed stream-json line arriving after some good events.
+		const base = new ClaudeRuntime();
+		let yielded = 0;
+		const yieldThenThrow: AsyncIterable<unknown> = {
+			[Symbol.asyncIterator]() {
+				return {
+					next(): Promise<IteratorResult<unknown>> {
+						if (yielded++ < 2) {
+							return Promise.resolve({
+								value: {
+									type: "assistant_message",
+									timestamp: new Date().toISOString(),
+								},
+								done: false,
+							});
+						}
+						return Promise.reject(new Error("synthetic stream-json parse error"));
+					},
+				};
+			},
+		};
+		const broken: AgentRuntime = {
+			...base,
+			id: base.id,
+			stability: base.stability,
+			instructionPath: base.instructionPath,
+			buildSpawnCommand: base.buildSpawnCommand.bind(base),
+			buildPrintCommand: base.buildPrintCommand.bind(base),
+			deployConfig: base.deployConfig.bind(base),
+			detectReady: base.detectReady.bind(base),
+			parseTranscript: base.parseTranscript.bind(base),
+			getTranscriptDir: base.getTranscriptDir.bind(base),
+			buildEnv: base.buildEnv.bind(base),
+			buildDirectSpawn: base.buildDirectSpawn.bind(base),
+			parseEvents: (() => yieldThenThrow) as unknown as AgentRuntime["parseEvents"],
+		};
+
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => fake;
+
+		let refreshes = 0;
+		await expect(
+			runTurn({
+				...makeRunOpts(ctx, "midturn-C", { runtime: broken, _spawnFn: spawnFn }),
+				lastActivityRefreshIntervalMs: 0,
+				_onLastActivityRefresh: () => {
+					refreshes++;
+				},
+			}),
+		).rejects.toThrow(/synthetic stream-json/);
+
+		// Mid-turn refresh fired for at least one of the two pre-throw events.
+		expect(refreshes).toBeGreaterThanOrEqual(1);
+
+		// And the persisted lastActivity reflects the mid-turn write — the
+		// end-of-turn write at line ~1112 was skipped by the parser-throw path.
+		const after = readSession(ctx.sessionsDbPath, "midturn-C");
+		expect(after?.lastActivity).not.toBe(startedAt);
+		expect(new Date(after?.lastActivity ?? 0).getTime()).toBeGreaterThan(
+			new Date(startedAt).getTime(),
+		);
+	});
+
+	test("Bash mail-poll detector: warns + records custom event without suppressing tool_use (overstory-c92c)", async () => {
+		// Defense-in-depth: the lead.md prompt forbids Bash mail polling
+		// (overstory-fa84). When a future overlay or contributed agent
+		// reintroduces the pattern, the runner must surface it via the
+		// runner diagnostic sink AND a `mail_poll_detected` event in
+		// events.db, while still recording the original tool_use event
+		// so downstream observability is unaffected.
+		seedSession(ctx.sessionsDbPath, { agentName: "polled", state: "working" });
+		const { runtime } = makeSpyRuntime();
+
+		const fake = makeFakeProc();
+		const sessionId = "polled-session";
+		const pollCommand = "until ov mail list; do sleep 1; done";
+		const spawnFn: TurnSpawnFn = () => {
+			fake._pushLine(
+				JSON.stringify({
+					type: "system",
+					subtype: "init",
+					session_id: sessionId,
+					model: "claude-test",
+				}),
+			);
+			fake._pushLine(
+				JSON.stringify({
+					type: "assistant",
+					session_id: sessionId,
+					message: {
+						role: "assistant",
+						model: "claude-test",
+						content: [
+							{
+								type: "tool_use",
+								id: "toolu_poll_1",
+								name: "Bash",
+								input: { command: pollCommand },
+							},
+						],
+					},
+				}),
+			);
+			emitFakeTurn(fake, { sessionId });
+			fake._exit(0);
+			return fake;
+		};
+
+		const logs: Array<{ level: string; message: string }> = [];
+		const logger: RunnerLogger = (level, message) => {
+			logs.push({ level, message });
+		};
+
+		const result = await runTurn(
+			makeRunOpts(ctx, "polled", { runtime, _spawnFn: spawnFn, _logWarning: logger }),
+		);
+
+		expect(result.exitCode).toBe(0);
+
+		// Warning was emitted via the runner diagnostic sink (warn level,
+		// message includes "mail-poll").
+		const pollWarn = logs.find((l) => l.level === "warn" && l.message.includes("mail-poll"));
+		expect(pollWarn).toBeDefined();
+
+		const eventStore = createEventStore(ctx.eventsDbPath);
+		try {
+			const events = eventStore.getByAgent("polled");
+
+			// `mail_poll_detected` custom event landed in events.db with the
+			// full (untruncated) command and the matched reason.
+			const detectedEvent = events.find((e) => {
+				if (e.eventType !== "custom" || e.level !== "warn" || !e.data) return false;
+				try {
+					const parsed = JSON.parse(e.data) as { type?: string };
+					return parsed.type === "mail_poll_detected";
+				} catch {
+					return false;
+				}
+			});
+			expect(detectedEvent).toBeDefined();
+			const payload = JSON.parse(detectedEvent?.data ?? "{}") as {
+				type: string;
+				reason: string;
+				command: string;
+			};
+			expect(payload.reason).toBe("until ov mail loop");
+			expect(payload.command).toBe(pollCommand);
+
+			// Regression guard: the original Bash tool_use event MUST still
+			// be recorded — the warning emits IN ADDITION to (not in place
+			// of) the normal recordAgentEvent call.
+			const toolUseEvent = events.find(
+				(e) => e.eventType === "tool_start" && e.toolName === "Bash",
+			);
+			expect(toolUseEvent).toBeDefined();
+		} finally {
+			eventStore.close();
+		}
+	});
+});
+
+describe("runTurn scope-violation observability (overstory-9f4d)", () => {
+	let ctx: Ctx;
+
+	beforeEach(async () => {
+		const overstoryDir = await mkdtemp(join(tmpdir(), "overstory-scope-test-"));
+		ctx = {
+			overstoryDir,
+			worktreePath: overstoryDir,
+			projectRoot: overstoryDir,
+			mailDbPath: join(overstoryDir, "mail.db"),
+			eventsDbPath: join(overstoryDir, "events.db"),
+			sessionsDbPath: join(overstoryDir, "sessions.db"),
+		};
+		_resetInProcessLocks();
+	});
+
+	afterEach(async () => {
+		_resetInProcessLocks();
+		await rm(ctx.overstoryDir, { recursive: true, force: true });
+	});
+
+	async function writeOverlayWithScope(scope: string[]): Promise<void> {
+		const dir = join(ctx.worktreePath, ".claude");
+		const { mkdir: mkdirP, writeFile } = await import("node:fs/promises");
+		await mkdirP(dir, { recursive: true });
+		const body = [
+			"## File Scope (exclusive ownership)",
+			"",
+			...scope.map((p) => `- \`${p}\``),
+			"",
+			"## Expertise",
+			"",
+			"none",
+		].join("\n");
+		await writeFile(join(dir, "CLAUDE.md"), body);
+	}
+
+	test("builder scope violation without justification emits warn log + scope_violation event", async () => {
+		seedSession(ctx.sessionsDbPath, { agentName: "violator", state: "working" });
+		await writeOverlayWithScope(["src/agents/in-scope.ts"]);
+
+		const { runtime } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			(async () => {
+				await Bun.sleep(20);
+				const s = createMailStore(ctx.mailDbPath);
+				try {
+					createMailClient(s).sendProtocol({
+						from: "violator",
+						to: "lead",
+						subject: "Worker done",
+						body: "ok",
+						type: "worker_done",
+						priority: "normal",
+						payload: {
+							taskId: "t",
+							branch: "b",
+							exitCode: 0,
+							filesModified: ["src/other.ts"],
+						},
+					});
+				} finally {
+					s.close();
+				}
+				emitFakeTurn(fake, { sessionId: "violator-session" });
+				fake._exit(0);
+			})();
+			return fake;
+		};
+
+		const logs: Array<{ level: string; message: string }> = [];
+		const logger: RunnerLogger = (level, message) => {
+			logs.push({ level, message });
+		};
+
+		const result = await runTurn({
+			...makeRunOpts(ctx, "violator", {
+				runtime,
+				_spawnFn: spawnFn,
+				_logWarning: logger,
+			}),
+			_scopeDetect: () => ({
+				violations: ["src/other.ts"],
+				expansionReasons: [],
+			}),
+		});
+
+		expect(result.terminalMailObserved).toBe(true);
+		expect(result.finalState).toBe("completed");
+
+		const warnLog = logs.find(
+			(l) => l.level === "warn" && l.message.includes("outside declared FILE_SCOPE"),
+		);
+		expect(warnLog).toBeDefined();
+		expect(warnLog?.message).toContain("src/other.ts");
+
+		const eventStore = createEventStore(ctx.eventsDbPath);
+		try {
+			const events = eventStore.getByAgent("violator");
+			const violationEvent = events.find((e) => {
+				if (e.eventType !== "custom" || e.level !== "warn" || !e.data) return false;
+				try {
+					const parsed = JSON.parse(e.data) as { type?: string };
+					return parsed.type === "scope_violation";
+				} catch {
+					return false;
+				}
+			});
+			expect(violationEvent).toBeDefined();
+			const payload = JSON.parse(violationEvent?.data ?? "{}") as {
+				type: string;
+				violations: string[];
+				fileScope: string[];
+			};
+			expect(payload.violations).toEqual(["src/other.ts"]);
+			expect(payload.fileScope).toEqual(["src/agents/in-scope.ts"]);
+		} finally {
+			eventStore.close();
+		}
+	});
+
+	test("expansion_reason in commit log suppresses the warning", async () => {
+		seedSession(ctx.sessionsDbPath, { agentName: "justified", state: "working" });
+		await writeOverlayWithScope(["src/agents/in-scope.ts"]);
+
+		const { runtime } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			(async () => {
+				await Bun.sleep(20);
+				const s = createMailStore(ctx.mailDbPath);
+				try {
+					createMailClient(s).sendProtocol({
+						from: "justified",
+						to: "lead",
+						subject: "Worker done",
+						body: "ok",
+						type: "worker_done",
+						priority: "normal",
+						payload: {
+							taskId: "t",
+							branch: "b",
+							exitCode: 0,
+							filesModified: ["src/other.ts"],
+						},
+					});
+				} finally {
+					s.close();
+				}
+				emitFakeTurn(fake, { sessionId: "justified-session" });
+				fake._exit(0);
+			})();
+			return fake;
+		};
+
+		const logs: Array<{ level: string; message: string }> = [];
+		const logger: RunnerLogger = (level, message) => {
+			logs.push({ level, message });
+		};
+
+		const result = await runTurn({
+			...makeRunOpts(ctx, "justified", {
+				runtime,
+				_spawnFn: spawnFn,
+				_logWarning: logger,
+			}),
+			_scopeDetect: () => ({
+				violations: ["src/other.ts"],
+				expansionReasons: ["needed shared type"],
+			}),
+		});
+
+		expect(result.terminalMailObserved).toBe(true);
+
+		const warnLog = logs.find(
+			(l) => l.level === "warn" && l.message.includes("outside declared FILE_SCOPE"),
+		);
+		expect(warnLog).toBeUndefined();
+
+		const eventStore = createEventStore(ctx.eventsDbPath);
+		try {
+			const events = eventStore.getByAgent("justified");
+			const violationEvent = events.find((e) => e.data?.includes("scope_violation") ?? false);
+			expect(violationEvent).toBeUndefined();
+		} finally {
+			eventStore.close();
+		}
+	});
+
+	test("prior scope_expansion mail suppresses the warning", async () => {
+		seedSession(ctx.sessionsDbPath, { agentName: "premail", state: "working" });
+		await writeOverlayWithScope(["src/agents/in-scope.ts"]);
+
+		// Pre-seed: a scope_expansion-prefixed mail from this agent.
+		{
+			const s = createMailStore(ctx.mailDbPath);
+			try {
+				createMailClient(s).send({
+					from: "premail",
+					to: "lead",
+					subject: "scope_expansion: needed shared type",
+					body: "heads up",
+					type: "status",
+					priority: "normal",
+				});
+			} finally {
+				s.close();
+			}
+		}
+
+		const { runtime } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			(async () => {
+				await Bun.sleep(20);
+				const s = createMailStore(ctx.mailDbPath);
+				try {
+					createMailClient(s).sendProtocol({
+						from: "premail",
+						to: "lead",
+						subject: "Worker done",
+						body: "ok",
+						type: "worker_done",
+						priority: "normal",
+						payload: {
+							taskId: "t",
+							branch: "b",
+							exitCode: 0,
+							filesModified: ["src/other.ts"],
+						},
+					});
+				} finally {
+					s.close();
+				}
+				emitFakeTurn(fake, { sessionId: "premail-session" });
+				fake._exit(0);
+			})();
+			return fake;
+		};
+
+		const logs: Array<{ level: string; message: string }> = [];
+		const logger: RunnerLogger = (level, message) => {
+			logs.push({ level, message });
+		};
+
+		await runTurn({
+			...makeRunOpts(ctx, "premail", {
+				runtime,
+				_spawnFn: spawnFn,
+				_logWarning: logger,
+			}),
+			_scopeDetect: () => ({
+				violations: ["src/other.ts"],
+				expansionReasons: [],
+			}),
+		});
+
+		const warnLog = logs.find(
+			(l) => l.level === "warn" && l.message.includes("outside declared FILE_SCOPE"),
+		);
+		expect(warnLog).toBeUndefined();
+	});
+
+	test("scout capability skips scope detection", async () => {
+		seedSession(ctx.sessionsDbPath, {
+			agentName: "scout-x",
+			capability: "scout",
+			state: "working",
+		});
+		await writeOverlayWithScope(["src/agents/in-scope.ts"]);
+
+		const { runtime } = makeSpyRuntime();
+		const fake = makeFakeProc();
+		const spawnFn: TurnSpawnFn = () => {
+			(async () => {
+				await Bun.sleep(20);
+				const s = createMailStore(ctx.mailDbPath);
+				try {
+					createMailClient(s).send({
+						from: "scout-x",
+						to: "lead",
+						subject: "Done",
+						body: "ok",
+						type: "result",
+						priority: "normal",
+					});
+				} finally {
+					s.close();
+				}
+				emitFakeTurn(fake, { sessionId: "scout-x-session" });
+				fake._exit(0);
+			})();
+			return fake;
+		};
+
+		let detectCalled = false;
+		await runTurn({
+			...makeRunOpts(ctx, "scout-x", {
+				runtime,
+				_spawnFn: spawnFn,
+				capability: "scout",
+			}),
+			_scopeDetect: () => {
+				detectCalled = true;
+				return { violations: [], expansionReasons: [] };
+			},
+		});
+
+		expect(detectCalled).toBe(false);
+	});
 });