neurastream 0.1.1 → 0.1.4

package/README.md

@@ -23,8 +23,36 @@ neurastream config --json
 
 Compatibility bins keep today's names (`agent-score`, `agent-ledger`, `brief-lint`, `oc-run`, `wip-check`, `wip-backup`, `wip-snapshot`, `pm-fail-facts`, `main-health`, `queue-check`, `queue-close`, `queue-cancel`, `main-start`, `machine-guard`, `glm-reset`, `priority-watch`, `resource-alerts`, `tmp-snapshot`, `heavy-run`). They are the same program, selected by the bin name.
 
+Scoring: `agent-score accept` records accepted work by commit; `agent-score validate <Agent> --plan <plan.md> --phase <P> --evidence <report.md> --section "<heading prefix>"` records a validation phase (checks/tests ran, report section written, no commits) with proof Main cannot fake by typing: the plan line must be ticked `- [x]`, the cited section body must name a heavy-run label run by that agent (from `paths.heavy_log`), and the phase must not be scored already. The ranking board counts it in `Accepted (diag/val)` as `N (d/v)`.
+
 Green is `bun run typecheck` and `bun test`, both exit 0.
 
+## Main reads the code for its plans
+
+Owner rule: never write a plan when another agent is doing the research or reading for you. When Main writes a plan, Main reads the relevant code itself and lists those files in the plan.
+
+- Logged: every non-`task` call Main makes adds the paths it touches to `main-reads.json` in the queue state dir (`paths.queue_state`), with the time. A `grep -n` result adds each file it names (`path:line:` at a line start), resolved against the call's directory.
+- Window: `guards.plan_read_max_hours` (default 24, `docs/config.md`). Every file listed under `## Code read by Main` must exist and have a logged read within that many hours. A backticked path cited elsewhere in the plan, outside `docs/plans/`, must also be listed there.
+- Cutoff: plans whose filename stamp is `20261021_0100` or later must carry a non-empty `## Code read by Main` section. Older plans are grandfathered.
+- Retention: entries older than 7 days are dropped on each write.
+- Spawn briefs: a brief must name an unticked phase id of the plan (for example `P4`). A brief that asks for research for a plan to be written is refused, quoting the owner rule.
+
+## Queue holds
+
+A plan parked for the owner has one line: `WAITING on owner: <what>`. That line is the only hold, and only Main writes it (plan-guard refuses subagents). The queue summary shows it as a flag on the plan, cut at 80 characters. Compaction and the rollover handoff read the same lines through `ownerHolds`: the compaction context lists each `<plan file>: WAITING on owner: <text>` line (or `none`) and says any other "needs the owner" or "paused" claim is unverified; the handoff's generated state carries the same lines. Main does not keep holds in a handoff note.
+
+## Session rollover
+
+Main's session file grows with every turn. When it reaches `rollover.max_session_mb` (default 10, `docs/config.md`), Main is asked once per session file to write a handoff note to `<queue_state>/rollover/<session id>.md`. The note covers the work in progress and its state, the decisions made and why, the next step, and the files involved.
+
+The switch is never automatic:
+
+- A note counts only if it was written after the threshold was crossed and is at most one hour old.
+- The owner's next plain message then closes the session and starts a fresh one. The fresh session opens with the note verbatim, the generated `main-start` state (including the owner holds), and then the owner's message. The previous session file stays where it is.
+- While own jobs (subagents included) are still running, the switch waits: a rollover would cancel them, so the owner's message stays in the current session until they finish.
+- `/main-rollover <message>` does the same by hand. It refuses below the threshold, without a fresh note, or while jobs run.
+- `rollover.enabled: false` turns the feature off.
+
 ## Changing a script
 
 Edit the script in this repo. Green is `bun run typecheck` and `bun test`, both exit 0. Main tags the release. The publish workflow puts that tag on npm. Then:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neurastream",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Harness-agnostic agent orchestration: queue, guards, blockers, scoring, ledger.",
   "type": "module",
   "license": "MIT",

package/src/adapters/omp/index.ts

@@ -16,17 +16,21 @@
 // Harness payloads are untyped at the boundary: every field read goes through a runtime check.
 
 import { execFileSync, spawn } from "node:child_process";
-import { appendFileSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { Decision } from "../../core/adapter.ts";
 import { loadConfig, type Config } from "../../core/config.ts";
-import { checkInject, checkPlanEdit, checkStop, checkTool } from "../../core/guards.ts";
+import { checkInject, checkPlanEdit, checkStop, checkTool, recordMainResult } from "../../core/guards.ts";
 import { applyQueueEnv } from "../../core/queue/env.ts";
+import { mainStartText } from "../../core/main-start.ts";
+import { buildHandoff, holdsBlock, notePath, noteRequest, type RolloverState, rolloverState } from "../../core/rollover.ts";
 import * as q from "../../core/queue/lib.ts";
 
 /** Subset of the harness extension host the adapter needs (pi.on; herdr also uses pi.events). */
 export interface ExtensionHost {
 	on(event: string, cb: (...args: unknown[]) => unknown): void;
+	registerCommand(name: string, opts: { description?: string; handler: (args: unknown, ctx: unknown) => unknown }): void;
+	sendUserMessage(content: string): void;
 }
 
 /** The parts of a harness call context the handlers look at. */
@@ -130,11 +134,22 @@ function ledgerText(cfg: Config): string {
 
 // Plan files a subagent write/edit may touch: snapshot before the call so tool_result can verify
 // and restore (the original snapshotted inside checkCall; core returns pure decisions now).
-function snapshotPlans(tool: string, input: Record<string, unknown>, cwd: string, snap: Map<string, string>): void {
+const MAIN_PLAN = /\/docs\/plans\/(?!archive\/)[^/]+\.md$/;
+function snapshotPlans(tool: string, input: Record<string, unknown>, cwd: string, snap: Map<string, string>, main: boolean): void {
 	if (tool !== "write" && tool !== "edit") return;
 	const plans = q.activePlans();
 	for (const p of q.writeTargets(tool, input, cwd)) {
 		if (snap.has(p)) continue;
+		if (main) {
+			// Main's own plan text is checked too; a plan that did not exist yet snapshots as "".
+			if (!MAIN_PLAN.test(p)) continue;
+			try {
+				snap.set(p, readFileSync(p, "utf8"));
+			} catch {
+				snap.set(p, "");
+			}
+			continue;
+		}
 		if (!q.isOrchestrationPath(p, plans) || !q.planAt(p, plans)) continue;
 		try {
 			snap.set(p, readFileSync(p, "utf8"));
@@ -142,6 +157,65 @@ function snapshotPlans(tool: string, input: Record<string, unknown>, cwd: string
 	}
 }
 
+// Session rollover helpers: the harness context read through runtime checks, and the file size and
+// mtime reads. The decisions are in src/core/rollover.ts.
+const WAIT_NOTICE_MS = 15 * 60_000;
+
+interface RolloverCtx {
+	sessionId: string;
+	sessionFile: string;
+	runningJobs(): string[];
+	waitForIdle(): unknown;
+	newSession(opts: { parentSession: string }): unknown;
+	notify(message: string): void;
+}
+
+/** Call a method on a harness object by name; undefined when it is not a function. */
+function call(obj: Record<string, unknown>, key: string, args: unknown[] = []): unknown {
+	const fn = obj[key];
+	return typeof fn === "function" ? Reflect.apply(fn, obj, args) : undefined;
+}
+
+function asRolloverCtx(v: unknown): RolloverCtx | null {
+	const r = asRecord(v);
+	const sm = asRecord(r.sessionManager);
+	const sessionId = call(sm, "getSessionId");
+	const sessionFile = call(sm, "getSessionFile");
+	if (typeof sessionId !== "string" || typeof sessionFile !== "string") return null;
+	return {
+		sessionId,
+		sessionFile,
+		runningJobs: () => {
+			const running = asRecord(call(r, "getAsyncJobSnapshot")).running;
+			return Array.isArray(running) ? running.map(j => asString(asRecord(j).label, "job")) : [];
+		},
+		waitForIdle: () => call(r, "waitForIdle"),
+		newSession: opts => call(r, "newSession", [opts]),
+		notify: message => call(asRecord(r.ui), "notify", [message]),
+	};
+}
+
+function isMain(ctx: unknown): boolean {
+	const c = asCtx(ctx);
+	return !c.hasAgent || c.kind === "main";
+}
+
+function mtimeOf(path: string): number | null {
+	try {
+		return statSync(path).mtimeMs;
+	} catch {
+		return null;
+	}
+}
+
+function sizeOf(path: string): number {
+	try {
+		return statSync(path).size;
+	} catch {
+		return 0;
+	}
+}
+
 /** Register the guard handlers on one extension host. `cfg` is injectable for tests. */
 export function createOmpAdapter(pi: ExtensionHost, cfg: Config): void {
 	// The queue library resolves its paths from env snapshots; point them at this config first.
@@ -172,10 +246,11 @@ export function createOmpAdapter(pi: ExtensionHost, cfg: Config): void {
 		const d = checkInject({ inject: asString(asRecord(event).prompt), agent: "main" }, cfg);
 		callsSinceStop = d.state?.callsSinceStop ?? callsSinceStop;
 		idleStops = d.state?.idleStops ?? idleStops;
+		const notice = rolloverNotice(ctx);
 		return {
 			message: {
 				customType: "main-guard.queue",
-				content: d.inject ?? "",
+				content: [d.inject, notice].filter(Boolean).join("\n\n"),
 				display: false,
 			},
 		};
@@ -208,7 +283,7 @@ export function createOmpAdapter(pi: ExtensionHost, cfg: Config): void {
 		if (!isSub) callsSinceStop++;
 		const cwd = c.cwd ?? process.cwd();
 		const snap = new Map<string, string>();
-		if (isSub) snapshotPlans(tool, input, cwd, snap);
+		snapshotPlans(tool, input, cwd, snap, !isSub);
 		const d = checkTool(
 			{ tool, input, cwd, agent, agentId: id, calls: n - 1, paths: [], writes: [], command: asString(input.command) },
 			cfg,
@@ -221,6 +296,7 @@ export function createOmpAdapter(pi: ExtensionHost, cfg: Config): void {
 	});
 
 	pi.on("tool_result", (event, ctx) => {
+		onSizeCheck(event, ctx);
 		const e = asRecord(event);
 		const c = asCtx(ctx);
 		const id = asString(e.toolCallId);
@@ -232,10 +308,11 @@ export function createOmpAdapter(pi: ExtensionHost, cfg: Config): void {
 				try {
 					after = readFileSync(file, "utf8");
 				} catch {}
-				const d = checkPlanEdit({ path: file, before, after, agent: "sub" }, cfg);
+				const d = checkPlanEdit({ path: file, before, after, agent: c.kind === "sub" ? "sub" : "main" }, cfg);
 				if (!d.allow && d.restore) {
 					try {
-						writeFileSync(d.restore.path, d.restore.text);
+						if (d.restore.text === null) rmSync(d.restore.path, { force: true });
+						else writeFileSync(d.restore.path, d.restore.text);
 					} catch {}
 					return { isError: true, content: [{ type: "text", text: d.reason }] };
 				}
@@ -244,6 +321,11 @@ export function createOmpAdapter(pi: ExtensionHost, cfg: Config): void {
 		if ((!c.hasAgent || c.kind === "main") && asString(e.toolName) === "bash" && !e.isError) {
 			if (PUSH_MERGE.test(asString(asRecord(e.input).command))) autoClose(cfg);
 		}
+		if ((!c.hasAgent || c.kind === "main") && !e.isError) {
+			const content = Array.isArray(e.content) ? e.content : [];
+			const text = content.map(p => asString(asRecord(p).text)).join("\n");
+			recordMainResult(asString(e.toolName), asRecord(e.input), c.cwd ?? process.cwd(), text);
+		}
 		return undefined;
 	});
 
@@ -255,6 +337,111 @@ export function createOmpAdapter(pi: ExtensionHost, cfg: Config): void {
 		idleStops = d.state?.idleStops ?? idleStops;
 		return d.allow ? undefined : { decision: "block", reason: d.reason };
 	});
+
+	// Session rollover (src/core/rollover.ts). Main's session size decides when a handoff note is
+	// asked for; the owner's next message then starts a fresh session from that note. The size is
+	// re-read at every turn end and tool result; the note instruction goes out once per session file.
+	let crossed: { file: string; atMs: number } | null = null;
+	let asked: string | null = null;
+	let waitNoticeMs = 0;
+
+	const stateOf = (c: RolloverCtx): RolloverState => {
+		const nowMs = Date.now();
+		const bytes = sizeOf(c.sessionFile);
+		const maxMb = cfg.rollover.max_session_mb;
+		if (bytes < maxMb * 1024 * 1024) crossed = null;
+		else if (crossed?.file !== c.sessionFile) crossed = { file: c.sessionFile, atMs: nowMs };
+		return rolloverState({
+			sessionBytes: bytes,
+			maxMb,
+			runningJobs: c.runningJobs(),
+			crossedAtMs: crossed?.atMs ?? null,
+			noteMtimeMs: mtimeOf(notePath(c.sessionId)),
+			nowMs,
+		});
+	};
+
+	const onSizeCheck = (_e: unknown, ctx: unknown): void => {
+		const c = asRolloverCtx(ctx);
+		if (!cfg.rollover.enabled || !c || !isMain(ctx)) return;
+		stateOf(c);
+	};
+	pi.on("agent_end", onSizeCheck);
+
+	// Compaction keeps the owner's holds true: a summary may state a hold only as a plans' WAITING on owner line says it.
+	pi.on("session.compacting", (_e, ctx) => {
+		if (!isMain(ctx)) return undefined;
+		const holds = q.ownerHolds();
+		return {
+			context: [
+				"Owner holds/blockers: only plans' WAITING on owner lines are real:",
+				...(holds.length > 0 ? holds : ["none"]),
+				"Any other hold, 'needs the owner' or 'paused' claim carried in this summary is unverified: re-read the plan before repeating it to the owner.",
+			],
+		};
+	});
+
+	/** Rollover notice for Main's next turn, or null. Asks for the note once per session file; throttles the wait-jobs notice. */
+	const rolloverNotice = (ctx: unknown): string | null => {
+		const c = asRolloverCtx(ctx);
+		if (!cfg.rollover.enabled || !c) return null;
+		const state = stateOf(c);
+		if (state === "need-note" && asked !== c.sessionFile) {
+			asked = c.sessionFile;
+			return noteRequest(notePath(c.sessionId));
+		}
+		if (state === "wait-jobs" && Date.now() - waitNoticeMs >= WAIT_NOTICE_MS) {
+			waitNoticeMs = Date.now();
+			const jobs = c.runningJobs().join(", ");
+			return `Session rollover: the handoff note is ready, but own jobs are still running (${jobs}). A rollover would cancel them, so the owner's messages stay in this session until they finish.`;
+		}
+		return null;
+	};
+
+	// A plain interactive message in the ready state becomes the owner's first message of the new session.
+	pi.on("input", (event, ctx) => {
+		const e = asRecord(event);
+		const c = asRolloverCtx(ctx);
+		const text = asString(e.text);
+		if (!cfg.rollover.enabled || !c || !isMain(ctx)) return undefined;
+		if (asString(e.source) !== "interactive" || text === "" || text.startsWith("/")) return undefined;
+		if (stateOf(c) !== "ready") return undefined;
+		return { text: `/main-rollover ${text}` };
+	});
+
+	pi.registerCommand("main-rollover", {
+		description: "Start a fresh session from Main's handoff note; the rest of the message is the owner's first message",
+		handler: async (args: unknown, ctx: unknown) => {
+			const c = asRolloverCtx(ctx);
+			if (!c) return;
+			const path = notePath(c.sessionId);
+			const state = stateOf(c);
+			if (state === "below") {
+				c.notify("main-rollover: this session is below rollover.max_session_mb; nothing to roll over.");
+				return;
+			}
+			if (state === "need-note") {
+				c.notify(`main-rollover: no fresh handoff note at ${path}; Main must write it first.`);
+				return;
+			}
+			if (state === "wait-jobs") {
+				c.notify(`main-rollover: own jobs are still running (${c.runningJobs().join(", ")}); a rollover would cancel them.`);
+				return;
+			}
+			const generated = [await mainStartText([], cfg), holdsBlock(q.ownerHolds())].join("\n");
+			const handoff = buildHandoff({
+				generated,
+				note: readFileSync(path, "utf8"),
+				previousSessionFile: c.sessionFile,
+				ownerMessage: asString(args),
+			});
+			adapterLog(cfg, `rollover: new session from ${c.sessionFile}; note ${path}`);
+			await c.waitForIdle();
+			const r = asRecord(await c.newSession({ parentSession: c.sessionFile }));
+			if (r.cancelled === true) return;
+			pi.sendUserMessage(handoff);
+		},
+	});
 }
 
 /** package.json omp.extensions entry. */

package/src/core/adapter.ts

@@ -46,7 +46,7 @@ export interface Decision {
 	allow: boolean;
 	reason: string;
 	inject?: string;
-	restore?: { path: string; text: string };
+	restore?: { path: string; text: string | null }; // null: the file did not exist before; delete it
 	/** Next keep-working counters for the caller to feed back into later StopEvents. */
 	state?: { callsSinceStop: number; idleStops: number };
 }

package/src/core/agent-score.ts

@@ -88,6 +88,55 @@ function phaseDifficulty(plan: string, phase: string): number | null {
 	throw new Error("stop");
 }
 
+/** True when the plan's phase line exists and is ticked `- [x]`/`- [X]` (ticking = reviewed by Main). */
+function phaseTicked(plan: string, phase: string): boolean {
+	if (!existsSync(plan)) {
+		exitText(`plan not found: ${plan}`);
+		throw new Error("stop");
+	}
+	const re = new RegExp(`^- \\[[ xX]\\] ${phase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+	for (const line of readFileSync(plan, "utf8").split("\n")) {
+		if (re.test(line)) return /^- \[[xX]\]/.test(line);
+	}
+	return false;
+}
+
+/**
+ * Body of the first heading whose text starts with `section` and ends at end-of-line, space or `(`,
+ * so `## CP` matches `## CP (P5, ...)` but not `## CPX`. The body runs to the next heading of the
+ * same or higher level. Null when no heading matches.
+ */
+function sectionBody(text: string, section: string): string | null {
+	const lines = text.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!;
+		if (!/^#{1,6} /.test(line)) continue;
+		if (!(line === section || line.startsWith(`${section} `) || line.startsWith(`${section}(`))) continue;
+		const level = (line.match(/^#+/) ?? ["#"])[0]!.length;
+		const body: string[] = [];
+		for (let j = i + 1; j < lines.length; j++) {
+			const next = lines[j]!;
+			const m = next.match(/^#+(?= )/);
+			if (m && m[0].length <= level) break;
+			body.push(next);
+		}
+		return body.join("\n");
+	}
+	return null;
+}
+
+/** Labels from the heavy-run log's `END   <agent> | <label> | exit <n>` lines (START lines never match). */
+function heavyEndLabels(log: string, agent: string): string[] {
+	if (!existsSync(log)) return [];
+	const re = new RegExp(`END\\s+${agent.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")} \\| (.*) \\| exit \\d+$`);
+	const out: string[] = [];
+	for (const line of readFileSync(log, "utf8").split("\n")) {
+		const m = line.match(re);
+		if (m) out.push(m[1]!);
+	}
+	return out;
+}
+
 function weightFor(args: string[], plan: string, phase: string, cfg: Config, fallback: number | null): { w: number; src: string } {
 	if (args.includes("--weight")) return { w: Number(needOpt(args, "--weight")), src: "flag" };
 	const d = phaseDifficulty(plan, phase);
@@ -110,6 +159,7 @@ interface Row {
 	first: number;
 	pen: number;
 	diag: number;
+	val: number;
 	net: number;
 	total: number;
 	ppd: number | null;
@@ -183,7 +233,7 @@ function table(days: number, cfg: Config, source: RunSource): { rows: Row[]; byA
 	for (const [n, r] of byAgent) agentModel.set(n, r.model);
 	const rows = new Map<string, Row>();
 	const blank = (model: string): Row => ({
-		model, runs: 0, done: 0, running: 0, cost: 0, steer: 0, hours: 0, pts: 0, acc: 0, first: 0, pen: 0, diag: 0,
+		model, runs: 0, done: 0, running: 0, cost: 0, steer: 0, hours: 0, pts: 0, acc: 0, first: 0, pen: 0, diag: 0, val: 0,
 		net: 0, total: 0, ppd: null, pph: null, surv: null, fp: null,
 	});
 	for (const r of byAgent.values()) {
@@ -203,11 +253,12 @@ function table(days: number, cfg: Config, source: RunSource): { rows: Row[]; byA
 		const agent = String(e.agent ?? "");
 		const model = (typeof e.model === "string" && e.model) || agentModel.get(agent) || "?";
 		const m = rows.get(model) ?? blank(model);
-		if (e.type === "accept" || e.type === "diagnose") {
+		if (e.type === "accept" || e.type === "diagnose" || e.type === "validate") {
 			m.pts += Number(e.weight);
 			m.acc += 1;
 			m.first += e.rework ? 0 : 1;
 			m.diag += e.type === "diagnose" ? 1 : 0;
+			m.val += e.type === "validate" ? 1 : 0;
 		} else if (e.type === "penalty") {
 			m.pen += cfg.score.penalties[String(e.kind)] ?? 0;
 		}
@@ -247,12 +298,12 @@ function board(days: number, cfg: Config, source: RunSource): void {
 			+ "(false-claim 5, rule-break 2, escaped-defect 8). Survival = finished runs that ended with a final result. Steering is approximate "
 			+ "(Main turns naming the agent).",
 		"",
-		"| # | Worker model | Runs (live) | Survival | Accepted (diag) | First-pass | Net pts | $ worker | $ steering | pts/$ | pts/h |",
+		"| # | Worker model | Runs (live) | Survival | Accepted (diag/val) | First-pass | Net pts | $ worker | $ steering | pts/$ | pts/h |",
 		"|---|---|---|---|---|---|---|---|---|---|---|",
 	];
 	rows.forEach((r, i) => {
 		lines.push(
-			`| ${i + 1} | ${r.model} | ${r.runs} (${r.running}) | ${fmt(r.surv, "pct")} | ${r.acc} (${r.diag}) | ${fmt(r.fp, "pct")} | ${r.net} | ${pyFixed(r.cost, 2)} | ${pyFixed(r.steer, 2)} | ${fmt(r.ppd, "1f")} | ${fmt(r.pph, "1f")} |`,
+			`| ${i + 1} | ${r.model} | ${r.runs} (${r.running}) | ${fmt(r.surv, "pct")} | ${r.acc} (${r.diag}/${r.val}) | ${fmt(r.fp, "pct")} | ${r.net} | ${pyFixed(r.cost, 2)} | ${pyFixed(r.steer, 2)} | ${fmt(r.ppd, "1f")} | ${fmt(r.pph, "1f")} |`,
 		);
 	});
 	const text = `${lines.join("\n")}\n`;
@@ -301,6 +352,29 @@ export function agentScore(args: string[], cfg: Config, source: RunSource): numb
 			}, cfg);
 			return 0;
 		}
+		if (cmd === "validate") {
+			const agent = rest[0];
+			const plan = opt(rest, "--plan");
+			const phase = opt(rest, "--phase");
+			const ev = opt(rest, "--evidence");
+			const section = opt(rest, "--section");
+			if (!agent || !plan || !phase || !ev || !section) return exitText("validate needs --plan, --phase, --evidence and --section");
+			if (!phaseTicked(plan, phase)) return exitText(`refused: ${phase} not ticked in ${plan}`);
+			const { w, src } = weightFor(rest, plan, phase, cfg, null);
+			if (!existsSync(ev)) return exitText(`refused: evidence file not found: ${ev}`);
+			const body = sectionBody(readFileSync(ev, "utf8"), section);
+			if (body === null) return exitText(`refused: no heading starting with ${section} in ${ev}`);
+			if (!body.split("\n").some(l => l.trim())) return exitText(`refused: section ${section} has no body in ${ev}`);
+			const labels = heavyEndLabels(cfg.paths.heavy_log, agent).filter(l => body.includes(l));
+			if (labels.length === 0) return exitText(`refused: section cites no heavy-run label run by ${agent}`);
+			const scored = readEvents(cfg).some(e => (e.type === "accept" || e.type === "validate") && e.agent === agent && e.plan === plan && e.phase === phase);
+			if (scored) return exitText("refused: already scored");
+			record({
+				type: "validate", agent, plan, phase, weight: w, weight_src: src, evidence: ev, section,
+				labels, rework: rest.includes("--rework"), note: opt(rest, "--note") ?? "",
+			}, cfg);
+			return 0;
+		}
 		if (cmd === "penalty") {
 			const kind = opt(rest, "--kind");
 			const note = opt(rest, "--note");

package/src/core/config.ts

@@ -98,6 +98,7 @@ export interface Config {
 		main_edit_limit: number;
 		main_window_min: number;
 		unlock_minutes: number;
+		plan_read_max_hours: number;
 		idle_stops: number;
 		blocker_timeout_ms: number;
 		skip_tools: string[];
@@ -110,6 +111,7 @@ export interface Config {
 		protected: string[];
 		ledger_command: string;
 	};
+	rollover: { enabled: boolean; max_session_mb: number };
 	machine: {
 		load_over_cores: number;
 		load_max: number;
@@ -257,6 +259,7 @@ function check(cfg: Config): void {
 	if (cfg.guards.sub_warn_calls > cfg.guards.sub_max_calls) {
 		throw new ConfigError("guards.sub_warn_calls must be <= guards.sub_max_calls");
 	}
+	if (!(cfg.rollover.max_session_mb > 0)) throw new ConfigError("rollover.max_session_mb must be > 0");
 	for (const [key, value] of Object.entries(cfg.paths)) {
 		if (key === "work_roots") {
 			if (!Array.isArray(value) || value.some(v => typeof v !== "string")) {

package/src/core/guards.ts

@@ -157,6 +157,15 @@ export function bypassRegExp(entry: string): RegExp {
 	return new RegExp(`\\b${head}\\b[^\\n]*\\b${tail}\\b`);
 }
 
+const RESEARCH_ASK = /\b(research|investigate|find where|map the code|read the code for)\b/i;
+const PLAN_WRITE = /\b(write|writing|draft|drafting|author)\b[^\n]*\bplan\b/i;
+
+// Phase ids (P1, P2 ...) in the plan's Phases section that are not ticked yet.
+function unticked(p: Plan): string[] {
+	const phases = q.sections(p.text).get("phases") ?? "";
+	return [...phases.matchAll(/^\s*[-*]\s+\[ \]\s+(P\d+)\b/gm)].map(m => m[1]!);
+}
+
 // Plans an implementer brief may run on; returns [reason, null] or [null, plan files].
 export function planGate(text: string, label: string): [string | null, string[]] {
 	const plans = q.activePlans();
@@ -172,6 +181,11 @@ export function planGate(text: string, label: string): [string | null, string[]]
 			`${label}: an implementer needs an open plan. Name the plan's absolute path in the brief; the plan must be listed in <repo>/INDEX.md and the repo in ${q.INDEX}.`,
 			[],
 		];
+	if (RESEARCH_ASK.test(text) && PLAN_WRITE.test(text))
+		return [
+			`${label}: a brief must not ask for research for a plan to be written. Please never ever ever write a plan when another agent is doing the research or reading for you. Main reads the code for its plans itself.`,
+			[],
+		];
 	const spawns = readSpawns();
 	for (const p of named) {
 		if (p.errors.length) return [`${label}: plan ${p.file} is not ready (${p.errors.join("; ")}).`, []];
@@ -185,6 +199,10 @@ export function planGate(text: string, label: string): [string | null, string[]]
 				`${label}: plan ${p.file} has no new "## Progress" entry since the last agent ran on it. Write that run's progress (from its report) into the plan first.`,
 				[],
 			];
+		const open = unticked(p);
+		if (!open.length) return [`${label}: plan ${p.file} has no unticked phase left.`, []];
+		if (!open.some(id => new RegExp(`\\b${id}\\b`).test(text)))
+			return [`${label}: the brief must name an unticked phase of ${p.file} (${open.join(", ")}).`, []];
 	}
 	return [null, named.map(p => p.file)];
 }
@@ -339,7 +357,12 @@ export function checkTool(e: ToolEvent, cfg: Config): Decision {
 			`plan-guard: ${hit} is a protected guard file. Only the owner changes it (unlock: \`touch ${q.UNLOCK}\` in a terminal, valid ${cfg.guards.unlock_minutes} min).`,
 		);
 	}
-	if (e.agent === "main") return mainTool(e, input, cfg);
+	if (e.agent === "main") {
+		const d = mainTool(e, input, cfg);
+		// A task brief names paths it does not read; only the other tools' paths count as reads.
+		if (d.allow && e.tool !== "task") recordMainReads(paths.filter(p => !writes.includes(p)));
+		return d;
+	}
 	const why = subRules(e, input, paths, writes, cfg);
 	if (why) {
 		log(cfg.paths.plan_guard_log, `BLOCK sub:${e.agentId} tool=${e.tool} ${why}`);
@@ -355,6 +378,46 @@ export function checkTool(e: ToolEvent, cfg: Config): Decision {
 	return ALLOW;
 }
 
+// --- Main's read log (`main-reads.json` in the queue state dir): files Main has read itself ---
+
+const MAIN_READ_KEEP_MS = 7 * 86_400_000;
+const GREP_LINE = /^([^\s:]+):\d+:/gm;
+/** Logs existing files as read now; entries older than 7 days are dropped on each write. */
+function recordMainReads(files: string[], now = Date.now()): void {
+	const file = path.join(q.STATE_DIR, "main-reads.json");
+	const existing = files.filter(f => {
+		try {
+			return statSync(f).isFile();
+		} catch {
+			return false;
+		}
+	});
+	if (existing.length === 0) return;
+	let reads: Record<string, string> = {};
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8")) as unknown;
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) reads = parsed as Record<string, string>;
+	} catch {}
+	const stamp = new Date(now).toISOString();
+	for (const f of existing) reads[f] = stamp;
+	const cutoff = now - MAIN_READ_KEEP_MS;
+	for (const [f, t] of Object.entries(reads)) if (!(Date.parse(t) >= cutoff)) delete reads[f];
+	try {
+		mkdirSync(q.STATE_DIR, { recursive: true });
+		writeFileSync(file, JSON.stringify(reads, null, 2));
+	} catch {}
+}
+
+/**
+ * Main's tool result: each `path:line:` at a line start (grep -n / grep -rn output) names a file
+ * Main read. Paths resolve against the directory the call ran in (its `cwd`, then any `cd`).
+ */
+export function recordMainResult(tool: string, input: Record<string, unknown>, cwd: string, text: string): void {
+	const base = typeof input.cwd === "string" ? path.resolve(cwd, q.expandHome(input.cwd)) : cwd;
+	const dir = q.shellCwd(String(input.command ?? input.code ?? ""), base);
+	recordMainReads([...text.matchAll(GREP_LINE)].map(m => path.resolve(dir, m[1] ?? "")));
+}
+
 /**
  * spawn: the allow-list, task-only and open-plan gates for one implementer launch. Covers both
  * original paths (the extension spawn event and a `task` tool call); the brief names the plan.
@@ -433,7 +496,7 @@ function mainOnlyLines(text: string): string {
  * write (the original restored the file itself before reporting).
  */
 export function checkPlanEdit(e: PlanEditEvent, cfg: Config): Decision {
-	if (e.agent === "main") return ALLOW;
+	if (e.agent === "main") return checkMainPlan(e, cfg);
 	if (q.outsideProgress(e.after) !== q.outsideProgress(e.before) || mainOnlyLines(e.after) !== mainOnlyLines(e.before)) {
 		log(cfg.paths.plan_guard_log, `RESTORE ${e.path}`);
 		return {
@@ -445,6 +508,74 @@ export function checkPlanEdit(e: PlanEditEvent, cfg: Config): Decision {
 	return ALLOW;
 }
 
+// Main's plan text outside "## Progress" must rest on files Main read itself (planReadProblems).
+// An empty `before` means the plan file did not exist yet; a refusal then deletes it.
+function checkMainPlan(e: PlanEditEvent, cfg: Config): Decision {
+	if (q.outsideProgress(e.after) === q.outsideProgress(e.before)) return ALLOW;
+	const problems = planReadProblems(e.after, e.path, cfg);
+	if (!problems.length) return ALLOW;
+	log(cfg.paths.plan_guard_log, `REFUSE-READ ${e.path}: ${problems.join("; ")}`);
+	return {
+		allow: false,
+		reason: `plan-guard: ${e.path} cites code Main has not read for this plan:\n- ${problems.join("\n- ")}\nRead each file (read or grep it), list it under "## Code read by Main", then edit again. ${e.before ? "The file was restored." : "The new file was removed."}`,
+		restore: { path: e.path, text: e.before || null },
+	};
+}
+
+const READ_SECTION = /^## Code read by Main[^\n]*\n([\s\S]*?)(?=^## |(?![\s\S]))/m;
+const LISTED_PATH = /`([^`\s]+)`/g;
+const CITED_PATH = /((?:~\/|\/|\.{1,2}\/)?[\w@.-]+(?:\/[\w@.-]+)*\.[A-Za-z0-9]+):\d+/g;
+
+/** Read evidence behind a plan edit: section present, each listed path read within the window, no unlisted cited path. */
+function planReadProblems(text: string, planPath: string, cfg: Config): string[] {
+	const section = READ_SECTION.exec(text)?.[1] ?? "";
+	const listed = [...section.matchAll(LISTED_PATH)].map(m => (m[1] ?? "").replace(/:[\d,+\- ]+$/, ""));
+	if (!listed.length) return [`no "## Code read by Main" section lists a file (list each file you read for this plan as a backticked path)`];
+	const reads = readMainReads();
+	const maxMs = cfg.guards.plan_read_max_hours * 3_600_000;
+	const problems: string[] = [];
+	const named = new Set<string>();
+	for (const p of listed) {
+		const abs = planFile(p, planPath, text);
+		named.add(abs);
+		if (!isFile(abs)) problems.push(`${p} does not exist`);
+		else if (!(Date.parse(reads[abs] ?? "") >= Date.now() - maxMs)) problems.push(`${p} was not read by Main within ${cfg.guards.plan_read_max_hours} h`);
+	}
+	for (const [, cited = ""] of text.matchAll(CITED_PATH)) {
+		const abs = planFile(cited, planPath, text);
+		if (abs.includes("/docs/plans/") || named.has(abs) || !isFile(abs)) continue;
+		problems.push(`${cited} is cited but not listed under "## Code read by Main"`);
+	}
+	return problems;
+}
+
+/** A plan-cited path: absolute, else under the plan's Worktree (when set) or its repo root. */
+function planFile(p: string, planPath: string, text: string): string {
+	const home = q.expandHome(p);
+	if (path.isAbsolute(home)) return home;
+	const wt = /^Worktree:\s*(\S+)/m.exec(text)?.[1];
+	const repo = path.dirname(path.dirname(path.dirname(planPath)));
+	const roots = wt && wt !== "-" ? [wt, repo] : [repo];
+	const root = roots.find(r => isFile(path.join(r, home))) ?? repo;
+	return path.join(root, home);
+}
+
+function isFile(file: string): boolean {
+	try {
+		return statSync(file).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function readMainReads(): Record<string, string> {
+	try {
+		return JSON.parse(readFileSync(path.join(q.STATE_DIR, "main-reads.json"), "utf8")) as Record<string, string>;
+	} catch {
+		return {};
+	}
+}
+
 // Plans still responsible for: open plans (parked "WAITING on owner" excluded) plus queue problems.
 export function openQueue(): string[] {
 	const open = q

package/src/core/main-start.ts

@@ -8,44 +8,56 @@ function bin(name: string, cfg: Config): string {
 	return join(cfg.paths.home, ".local/bin", name);
 }
 
-export function mainStart(args: string[], cfg: Config): number {
+// Main's session-start preflight as one text. The CLI prints it; the session rollover handoff
+// (src/core/rollover.ts) carries the same text into the new session. Children's stdout is
+// collected in order, so the printed output matches the original script line for line.
+export function mainStartText(args: string[], cfg: Config): string {
+	const out: string[] = [];
+	const say = (line: string) => out.push(`${line}\n`);
 	const h = args[0] ?? String(cfg.health.default_hours);
-	console.log("=== machine");
+	say("=== machine");
 	const mg = spawnSync(bin("machine-guard", cfg), [], { encoding: "utf8", env: process.env });
 	const mgLines = (mg.stdout ?? "").trim().split("\n");
-	console.log(mgLines.at(-1) ?? "");
-	console.log(readFileSync("/proc/loadavg", "utf8").trim());
-	console.log("");
-	console.log(`=== agents (last ${h}h; DIED = check its worktree, relaunch FRESH with its progress file)`);
+	say(mgLines.at(-1) ?? "");
+	say(readFileSync("/proc/loadavg", "utf8").trim());
+	say("");
+	say(`=== agents (last ${h}h; DIED = check its worktree, relaunch FRESH with its progress file)`);
 	const ledger = spawnSync(bin("agent-ledger", cfg), ["--hours", h], { encoding: "utf8", env: process.env });
 	const awk = spawnSync(
 		"awk",
 		["NR==1 || /DIED/ {print; next} {ok[++n]=$0} END {for (i=1;i<=n;i++) print ok[i]}"],
 		{ input: ledger.stdout ?? "", encoding: "utf8" },
 	);
-	process.stdout.write(awk.stdout ?? "");
+	out.push(awk.stdout ?? "");
 	const cap = spawnSync(bin("agent-ledger", cfg), ["--cap"], { encoding: "utf8", env: process.env, stdio: ["ignore", "pipe", "ignore"] });
 	for (const line of (cap.stdout ?? "").split("\n")) {
-		if (/^(PRIORITY IDLE|FULL)/.test(line)) console.log(line);
+		if (/^(PRIORITY IDLE|FULL)/.test(line)) say(line);
 	}
-	console.log("");
-	console.log("=== main thread");
-	spawnSync(bin("main-health", cfg), [], { stdio: "inherit", env: process.env });
-	console.log("");
-	console.log("=== queue");
-	spawnSync(bin("queue-check", cfg), [], { stdio: "inherit", env: process.env });
-	console.log("");
-	console.log("=== heavy-run lock");
+	say("");
+	say("=== main thread");
+	const health = spawnSync(bin("main-health", cfg), [], { encoding: "utf8", env: process.env, stdio: ["inherit", "pipe", "inherit"] });
+	out.push(health.stdout ?? "");
+	say("");
+	say("=== queue");
+	const check = spawnSync(bin("queue-check", cfg), [], { encoding: "utf8", env: process.env, stdio: ["inherit", "pipe", "inherit"] });
+	out.push(check.stdout ?? "");
+	say("");
+	say("=== heavy-run lock");
 	try {
 		const lines = readFileSync(cfg.paths.heavy_lock, "utf8").split("\n").slice(0, 2);
 		while (lines.length && lines.at(-1) === "") lines.pop();
-		if (lines.length) console.log(lines.join("\n"));
+		if (lines.length) say(lines.join("\n"));
 	} catch {}
-	console.log("=== doctor");
+	say("=== doctor");
 	const cli = join(dirname(fileURLToPath(import.meta.url)), "../cli/main.ts");
 	const doctor = spawnSync(process.execPath, [cli, "doctor"], { encoding: "utf8", env: process.env });
 	const text = `${doctor.stdout ?? ""}${doctor.stderr ?? ""}`;
-	process.stdout.write(text.endsWith("\n") || text === "" ? text : `${text}\n`);
-	if (doctor.error) console.log(doctor.error.message);
+	out.push(text.endsWith("\n") || text === "" ? text : `${text}\n`);
+	if (doctor.error) say(doctor.error.message);
+	return out.join("");
+}
+
+export function mainStart(args: string[], cfg: Config): number {
+	process.stdout.write(mainStartText(args, cfg));
 	return 0;
 }

package/src/core/queue/lib.ts

@@ -29,6 +29,8 @@ export const BACKGROUND_MAX_LINES = 40;
 export const SUB_WARN_CALLS = 90;
 export const SUB_MAX_CALLS = 100;
 const REQUIRED = ["goal", "forbidden", "blockers", "phases", "done check", "progress"] as const;
+// Plans stamped at or after this must carry a "## Code read by Main" section; older plans are grandfathered.
+const READ_CUTOVER = "20261021_0100";
 
 export interface Blocker {
 	script: string;
@@ -46,6 +48,7 @@ export interface Plan {
 	branch: string | null;
 	appliesTo: string[];
 	waiting: boolean;
+	waitingLine: string | null;
 	priorityId: string | null;
 	errors: string[];
 }
@@ -128,7 +131,7 @@ function headerField(text: string, name: string): string | null {
 }
 
 export function parsePlan(repo: string, file: string, text: string | null, blockersDir = blockersDirPath()): Plan {
-	const empty = { repo, file, text: "", status: null, blockers: [], doneCheck: null, worktree: null, branch: null, appliesTo: [], waiting: false, priorityId: null };
+	const empty = { repo, file, text: "", status: null, blockers: [], doneCheck: null, worktree: null, branch: null, appliesTo: [], waiting: false, waitingLine: null, priorityId: null };
 	if (text === null) return { ...empty, errors: ["plan file listed in INDEX.md does not exist"] };
 	const errors: string[] = [];
 	const secs = sections(text);
@@ -136,7 +139,10 @@ export function parsePlan(repo: string, file: string, text: string | null, block
 		if (s === "progress" ? !secs.has(s) : !items(secs.get(s) ?? "").length)
 			errors.push(`missing or empty "## ${s.replace(/^\w/, c => c.toUpperCase())}" section (template: ${agentDir()}/queue/TEMPLATE.md)`);
 	}
-	const known = new Set([...REQUIRED, "applies to", "background"]);
+	const stamp = /^(\d{8}_\d{4})/.exec(path.basename(file))?.[1] ?? "";
+	if (stamp >= READ_CUTOVER && !items(secs.get("code read by main") ?? "").length)
+		errors.push(`missing or empty "## Code read by Main" section (plans stamped ${READ_CUTOVER} or later list each file they cite)`);
+	const known = new Set([...REQUIRED, "applies to", "background", "code read by main"]);
 	for (const s of secs.keys()) if (!known.has(s)) errors.push(`unknown section "## ${s}" (allowed: ${[...known].join(", ")})`);
 	const status = statusOf(text);
 	if (!status) errors.push('"## Progress" must start with a line "Status: open", "Status: complete" or "Status: cancelled"');
@@ -169,6 +175,7 @@ export function parsePlan(repo: string, file: string, text: string | null, block
 		branch: headerField(text, "Branch")?.replace(/^-$/, "") || null,
 		appliesTo: items(secs.get("applies to") ?? "").map(p => path.resolve(repo, expandHome(p.replace(/`/g, "")))),
 		waiting: /^WAITING on owner:/m.test(text),
+		waitingLine: text.match(/^WAITING on owner:[ \t]*(.*)$/m)?.[1] ?? null,
 		priorityId: text.match(/^PRIORITY-ID:\s*`?([A-Z]{2}[0-9]{2})`?/m)?.[1] ?? null,
 		errors,
 	};
@@ -188,6 +195,11 @@ export function activePlans(index = indexPath(), blockersDir = blockersDirPath()
 	return readIndex(index).flatMap(r => readPlans(r, blockersDir));
 }
 
+/** Owner holds: one line per plan with a WAITING on owner line. The only real holds; the summary, the rollover context and the handoff all read them here. */
+export function ownerHolds(index = INDEX): string[] {
+	return readIndex(index).flatMap(r => readPlans(r)).filter(p => p.waiting).map(p => `${p.file}: WAITING on owner: ${p.waitingLine ?? ""}`);
+}
+
 export function gitTop(p: string): { top: string; repo: string } | null {
 	let dir = path.resolve(p);
 	for (;;) {
@@ -238,6 +250,19 @@ export function isOrchestrationPath(p: string, plans: Plan[] = activePlans()): b
 }
 
 const SHELL_TOOLS = new Set(["bash", "eval"]);
+// A shell command is a list of segments; each `cd` segment moves the directory for the ones after it.
+const SHELL_SEGMENT = /&&|\|\||[;|\n]/;
+const CD_SEGMENT = /^\s*cd\s+(\S+)/;
+
+/** The directory a shell command leaves in effect: `base`, moved by each `cd` segment in order. */
+export function shellCwd(command: string, base: string): string {
+	let dir = base;
+	for (const seg of command.split(SHELL_SEGMENT)) {
+		const cd = CD_SEGMENT.exec(seg);
+		if (cd) dir = path.resolve(dir, expandHome(cd[1] ?? ""));
+	}
+	return dir;
+}
 export function touchedPaths(toolName: string, input: Record<string, unknown>, cwd: string): string[] {
 	const out = new Set<string>();
 	const base = typeof input?.cwd === "string" ? path.resolve(cwd, expandHome(input.cwd)) : cwd;
@@ -258,14 +283,16 @@ export function touchedPaths(toolName: string, input: Record<string, unknown>, c
 	}
 	if (SHELL_TOOLS.has(toolName)) {
 		out.add(base);
-		const cmd = String(input?.command ?? input?.code ?? "");
 		let dir = base;
-		for (const word of cmd.split(/[\s;&|<>()'"`,=]+/)) {
-			const w = word.trim();
-			if (!w || w.startsWith("-") || w.includes("://") || !/[./]/.test(w) || /^\d+(\.\d+)*$/.test(w)) continue;
-			add(w, dir);
+		for (const seg of String(input?.command ?? input?.code ?? "").split(SHELL_SEGMENT)) {
+			for (const word of seg.split(/[\s<>()'"`,=]+/)) {
+				const w = word.trim();
+				if (!w || w.startsWith("-") || w.includes("://") || !/[./]/.test(w) || /^\d+(\.\d+)*$/.test(w)) continue;
+				add(w, dir);
+			}
+			const cd = CD_SEGMENT.exec(seg);
+			if (cd) dir = path.resolve(dir, expandHome(cd[1] ?? ""));
 		}
-		for (const m of cmd.matchAll(/(?:^|&&|;|\|\|)\s*cd\s+(\S+)/g)) dir = path.resolve(dir, expandHome(m[1] ?? ""));
 	}
 	return [...out];
 }
@@ -552,7 +579,8 @@ export function queueSummary(index = INDEX): string {
 		lines.push(`- ${repo}${nCancelled ? ` (${nCancelled} cancelled)` : ""}`);
 		for (const p of readPlans(repo)) {
 			const status = awaitingMerge(p) ? "complete, awaiting merge" : (p.status ?? "INVALID");
-			const flags = [status, p.waiting ? "WAITING on owner" : "", p.priorityId ?? ""].filter(Boolean).join(", ");
+			const hold = p.waiting ? `WAITING on owner: ${(p.waitingLine ?? "").slice(0, 80)}` : "";
+			const flags = [status, hold, p.priorityId ?? ""].filter(Boolean).join(", ");
 			const goal = items(sections(p.text).get("goal") ?? "")[0]?.slice(0, 100) ?? "";
 			lines.push(`  - ${p.file} [${flags}] ${goal}`);
 		}

package/src/core/rollover.ts

@@ -0,0 +1,86 @@
+// Session rollover, pure core: when Main's session file has grown past `rollover.max_session_mb`,
+// Main writes a handoff note first; the owner's next message then opens a fresh session that
+// starts from the note plus the generated state. Decisions only: the adapter reads the file size,
+// the jobs and the note mtime, and performs the switch. No harness names here.
+
+import { join } from "node:path";
+import { stateDirPath } from "./queue/lib.ts";
+
+export type RolloverState = "below" | "need-note" | "wait-jobs" | "ready";
+
+/** A note counts only if it is at most this old. */
+export const MAX_NOTE_AGE_MS = 60 * 60_000;
+
+export interface RolloverInput {
+	sessionBytes: number;
+	maxMb: number;
+	/** Labels of the own async jobs (subagents included) that are still running. */
+	runningJobs: readonly string[];
+	/** When the session file was first seen at or over the threshold; null if never. */
+	crossedAtMs: number | null;
+	/** Mtime of the handoff note; null when the note does not exist. */
+	noteMtimeMs: number | null;
+	nowMs: number;
+}
+
+/**
+ * below: under the threshold. need-note: over it and no fresh note (written after the crossing,
+ * at most MAX_NOTE_AGE_MS old). wait-jobs: note is fresh but own jobs still run (rolling over
+ * would cancel them). ready: the next owner message may roll over.
+ */
+export function rolloverState(p: RolloverInput): RolloverState {
+	if (p.sessionBytes < p.maxMb * 1024 * 1024) return "below";
+	const noteFresh =
+		p.noteMtimeMs !== null &&
+		p.crossedAtMs !== null &&
+		p.noteMtimeMs > p.crossedAtMs &&
+		p.nowMs - p.noteMtimeMs <= MAX_NOTE_AGE_MS;
+	if (!noteFresh) return "need-note";
+	return p.runningJobs.length > 0 ? "wait-jobs" : "ready";
+}
+
+export interface HandoffInput {
+	/** Output of main-start (the generated state). */
+	generated: string;
+	/** Main's handoff note, inserted as written (trailing newlines dropped). */
+	note: string;
+	previousSessionFile: string;
+	/** The owner's message exactly as typed; it is the last thing in the handoff. */
+	ownerMessage: string;
+}
+
+/** The first user message of the new session: header, Main's note, generated state, owner message. */
+export function buildHandoff(p: HandoffInput): string {
+	return [
+		`Previous session file: ${p.previousSessionFile}. Its full history stays there; this session continues from the handoff below.`,
+		"",
+		"## Main's handoff note (verbatim)",
+		p.note.trimEnd(),
+		"",
+		"## Generated state (main-start)",
+		p.generated.trimEnd(),
+		"",
+		"Owner's message:",
+		p.ownerMessage,
+	].join("\n");
+}
+
+/** The owner-holds part of the generated state: each WAITING on owner line verbatim, or none. */
+export function holdsBlock(holds: readonly string[]): string {
+	return ["=== owner holds (plans' WAITING on owner lines)", ...(holds.length > 0 ? holds : ["none"]), ""].join("\n");
+}
+
+/** The one-time note instruction for Main's next turn. */
+export function noteRequest(path: string): string {
+	return [
+		"Session rollover: this session has grown past rollover.max_session_mb.",
+		`Write a handoff note to ${path} (overwrite it). Cover the work in progress and its state, the decisions made and why, the next step, and the files involved.`,
+		"Do not list holds or owner blockers in the note; they come from the plans' WAITING on owner lines.",
+		"When the owner's next message arrives, this session closes and a fresh one starts from that note verbatim plus the generated main-start state.",
+	].join("\n");
+}
+
+/** Where Main writes the handoff note for one session. */
+export function notePath(sessionId: string, stateDir = stateDirPath()): string {
+	return join(stateDir, "rollover", `${sessionId}.md`);
+}

package/templates/config.yml

@@ -101,6 +101,7 @@ guards:
   main_edit_limit: 5
   main_window_min: 15
   unlock_minutes: 30
+  plan_read_max_hours: 24
   idle_stops: 3
   blocker_timeout_ms: 10000
   skip_tools: [todo, wait, ask, web_search, job, cancel_job]
@@ -113,6 +114,10 @@ guards:
   protected: []
   ledger_command: "agent-ledger --hours 12"
 
+rollover:
+  enabled: true
+  max_session_mb: 10
+
 machine:
   load_over_cores: 4
   load_max: 0

package/templates/help/agent-score.txt

@@ -7,6 +7,8 @@ Cost = the worker's own list cost + Main's steering cost (Main tokens spent on t
         commits must be ancestors of --branch (default pm/pr01-counts in ~/Work/pm-counts); --rework = needed fixes by Main/another agent
   agent-score diagnose <Agent> --plan <plan.md> --phase P --evidence <file> [--weight N]
         a real product bug found and recorded (no commit needed); default weight 4
+  agent-score validate <Agent> --plan <plan.md> --phase P --evidence <report.md> --section "## Heading" [--weight N] [--rework] [--note T]
+        validation phase with proof, no commits: phase ticked in the plan, the section body cites a heavy-run label run by <Agent>
   agent-score penalty <Agent> --kind false-claim|rule-break|escaped-defect --note T [--plan <plan.md>]
   agent-score exempt <sha,...> --note T [--repo R]          commits that are Main's own (merges, rebuilds), not a worker's
   agent-score check [--repo R] [--branch B]                 exit 1 = commits on the branch since the base with no accept/exempt record

package/templates/queue/TEMPLATE.md

@@ -22,6 +22,10 @@ PRIORITY-ID: <optional, e.g. PR01>
 ## Done check
 `<one command, run in the worktree; exit 0 = the Goal is met and the work is landed>`
 
+## Code read by Main
+<!-- Main lists each file it read to write this plan's code claims, as backticked paths. Required for plans stamped 20261021_0100 or later. -->
+- `<path/to/file.ts>`
+
 ## Progress
 Status: open
 <!-- The implementer may only append dated entries here: what was done, what was verified (command +