neurastream 0.1.2 → 0.1.5

package/README.md

@@ -27,6 +27,32 @@ Scoring: `agent-score accept` records accepted work by commit; `agent-score vali
 
 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.2",
+  "version": "0.1.5",
   "description": "Harness-agnostic agent orchestration: queue, guards, blockers, scoring, ledger.",
   "type": "module",
   "license": "MIT",

package/src/adapters/omp/doctor.ts

@@ -36,9 +36,13 @@ export function adapterLiveFiles(home: string, root: string = PACKAGE_ROOT): Liv
 	for (const bin of packageBins(root)) {
 		files.push({ live: join(home, ".local/bin", bin.name), source: bin.source });
 	}
+	// P9: the extension symlink is gone (ONE load route — the plugin below);
+	// what the adapter installs under the agent dir is the omp plugin link,
+	// whose realpath is an installed neurastream package root. `omp plugin
+	// link` owns this file; install must never ensureLink it.
 	files.push({
-		live: join(home, ".omp/agent/extensions/neurastream.ts"),
-		source: join(root, "src/adapters/omp/index.ts"),
+		live: join(home, ".omp/plugins/node_modules/neurastream"),
+		source: root,
 	});
 	files.push({
 		live: join(home, ".omp/agent/queue/lib.ts"),
@@ -68,8 +72,10 @@ function bunLiveFiles(home: string, root: string): LiveFile[] {
 }
 
 function packageRootOf(file: string): string | null {
-	let dir = dirname(file);
-	for (let i = 0; i < 8; i++) {
+	// `file` itself may be the package root (the omp plugin link's realpath is
+	// an installed neurastream root), so the self dir is checked first.
+	let dir = file;
+	for (let i = 0; i < 9; i++) {
 		const manifest = join(dir, "package.json");
 		if (existsSync(manifest)) {
 			try {

package/src/adapters/omp/index.ts

@@ -16,17 +16,23 @@
 // 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, MAIN_PLAN_FILE, 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";
+// Registers the plugin-command matcher into core's writeTargets (side effect).
+import "./package-ops.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. */
@@ -82,11 +88,14 @@ function adapterLog(cfg: Config, line: string): void {
 // Background queue-close for every plan Main marked complete (owner 2026-10-15). Ported from the
 // original autoClose: same filter, same "--- auto-close attempt" log line, detached child with
 // stdio on the per-plan close log. QUEUE_CLOSE_BIN overrides the binary (tests); without it the
-// package's own CLI runs via the current bun binary, so no PATH lookup is needed.
+// package's own executable bin/queue-close runs (its `#!/usr/bin/env bun` shebang picks bun).
+// Never process.execPath: inside the harness that is the harness binary itself, so the child was
+// a new agent session that loaded this plugin and auto-closed again — a process fork bomb
+// (2026-10-21 OOMs, ~175 processes).
 function closeChildArgs(plan: string): [string, string[]] {
 	const bin = process.env.QUEUE_CLOSE_BIN;
 	if (bin) return [bin, [plan]];
-	return [process.execPath, [join(import.meta.dir, "..", "..", "cli", "main.ts"), "queue-close", plan]];
+	return [join(import.meta.dir, "..", "..", "..", "bin", "queue-close"), [plan]];
 }
 
 export function autoClose(cfg: Config): string[] {
@@ -130,11 +139,21 @@ 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 {
+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_FILE.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 +161,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 +250,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 +287,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 +300,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 +312,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 +325,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 +341,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/adapters/omp/install.ts

@@ -2,13 +2,15 @@
 // Does not read or write the real user's agent directory: every path is under `home`.
 
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, symlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { configFile } from "../../core/config.ts";
 
 import { adapterLiveFiles } from "./doctor.ts";
+// Registers the plugin-command matcher into core's writeTargets (side effect).
+import "./package-ops.ts";
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
 
 const OVERLAY = `adapter:
@@ -18,11 +20,14 @@ const OVERLAY = `adapter:
   extensions: "~/.omp/agent/extensions"
 `;
 
-const PROTECTED = ["~/.omp/agent/agents/", "~/.omp/agent/extensions/"];
+// P8: the plugin dir is adapter surface and lands in the config's
+// guards.protected, so core's protected check covers it without naming a
+// harness path. installOmp writes it via the same overlay pass.
+const PROTECTED = ["~/.omp/agent/agents/", "~/.omp/agent/extensions/", "~/.omp/plugins/"];
 
 export interface InstallResult {
-	extension: string;
 	plugin: string;
+	removedStaleLink: string | null;
 	pinsCopied: string[];
 	pinsKept: string[];
 	overlay: "written" | "unchanged";
@@ -46,7 +51,9 @@ function ensureLink(link: string, target: string): void {
 
 function linkInstalled(home: string): void {
 	for (const file of adapterLiveFiles(home)) {
-		if (file.live.includes("/.omp/agent/agents/")) continue;
+		// agents/ are copied, not linked; the plugin link is `omp plugin link`'s
+		// own output (linkPlugin below), never ours to ensureLink.
+		if (file.live.includes("/.omp/agent/agents/") || file.live.includes("/.omp/plugins/")) continue;
 		ensureLink(file.live, file.source);
 	}
 }
@@ -109,24 +116,37 @@ function linkPlugin(home: string): string {
 	return join(home, ".omp/plugins/node_modules/neurastream");
 }
 
-/** Link the extension, copy missing pins, write the overlay. HOME is the sandbox or the caller's home. */
+/** Link the plugin, copy missing pins, write the overlay. HOME is the sandbox or the caller's home. */
 export function installOmp(home: string): InstallResult {
 	const file = configFile(home);
 	if (!existsSync(file)) throw new Error(`no config at ${file}; run neurastream init first`);
+	// P9: ONE load route. omp loads extensions-dir files AND a plugin package's
+	// package.json#omp.extensions, so an extensions/neurastream.ts link beside
+	// `omp plugin link` runs every hook twice. Only the plugin route remains —
+	// the one guard parity locks (~/.omp/plugins/ + the package root). A stale
+	// link an older install made is removed, but only when it is a symlink: a
+	// real file there is never ours to delete.
 	const extension = join(home, ".omp/agent/extensions/neurastream.ts");
-	const target = join(PACKAGE_ROOT, "src/adapters/omp/index.ts");
-	ensureLink(extension, target);
+	let removedStaleLink: string | null = null;
+	try {
+		if (lstatSync(extension).isSymbolicLink()) {
+			unlinkSync(extension);
+			removedStaleLink = extension;
+		}
+	} catch {
+		// absent: nothing stale to remove
+	}
 	mkdirSync(join(home, ".omp/agent/sessions"), { recursive: true });
 	const pins = copyPins(join(home, ".omp/agent/agents"));
 	linkInstalled(home);
 	const plugin = linkPlugin(home);
 	const overlay = writeOverlay(file);
-	return { extension, plugin, pinsCopied: pins.copied, pinsKept: pins.kept, overlay };
+	return { plugin, removedStaleLink, pinsCopied: pins.copied, pinsKept: pins.kept, overlay };
 }
 
 export function printInstall(result: InstallResult): void {
-	console.log(`neurastream adapter install omp: linked ${result.extension}`);
 	console.log(`neurastream adapter install omp: plugin ${result.plugin}`);
+	if (result.removedStaleLink) console.log(`neurastream adapter install omp: removed stale extension link ${result.removedStaleLink}`);
 	console.log(
 		`neurastream adapter install omp: pins copied ${result.pinsCopied.length}, kept ${result.pinsKept.length}; overlay ${result.overlay}`,
 	);

package/src/adapters/omp/package-ops.ts

@@ -0,0 +1,28 @@
+// Adapter-owned package-operation shapes for the P8 guard parity: core's
+// writeTargets never names a harness, so the plugin-command matcher lives here
+// and registers itself into core at module load. Every plugin command writes
+// under the plugin directory, which src/adapters/omp/install.ts lists in the
+// config's guards.protected — so mapping the commands onto that directory puts
+// them behind the owner's unlock like every other guard file.
+
+import { homedir } from "node:os";
+import { registerPackageOpTarget, type PackageOpMatcher } from "../../core/queue/lib.ts";
+
+const PLUGIN_ACTIONS = ["install", "uninstall", "link", "unlink", "update"];
+
+/** Target for `<harness> plugin <action>` segments; null when none matches. */
+export const pluginCommandTarget: PackageOpMatcher = (code: string): string | null => {
+	for (const seg of code.split(/&&|\|\||;|\n|\|/)) {
+		const toks = seg.trim().split(/\s+/).filter(Boolean);
+		let i = 0;
+		while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i] ?? "")) i++;
+		const cmd = (toks[i] ?? "").replace(/^["']|["']$/g, "").replace(/^.*\//, "");
+		if (cmd !== "omp") continue;
+		const sub = (toks[i + 1] ?? "").replace(/^["']+|["']+$/g, "");
+		if (sub === "plugin" && PLUGIN_ACTIONS.includes((toks[i + 2] ?? "").replace(/^["']+|["']+$/g, "")))
+			return `${homedir()}/.omp/plugins/`;
+	}
+	return null;
+};
+
+registerPackageOpTarget(pluginCommandTarget);

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/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)];
 }
@@ -320,6 +338,9 @@ function mainTool(e: ToolEvent, input: Record<string, unknown>, cfg: Config): De
 	return editWindow(e, input, cfg);
 }
 
+/** A live plan file (archived plans excluded); Main's plan-text checks run on these. */
+export const MAIN_PLAN_FILE = /\/docs\/plans\/(?!archive\/)[^/]+\.md$/;
+
 /**
  * pre-tool: plan-guard checkCall for subs (protected files, budget, plan-edit rules, blockers)
  * plus, for Main, the spawn gates and the project-file edit window.
@@ -339,7 +360,19 @@ 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") {
+		// The plan-text checks (checkPlanEdit) see only edit/write results; a shell redirect,
+		// sed -i or heredoc into a plan would skip them, so plans change through edit/write only.
+		const shellPlan = e.tool !== "write" && e.tool !== "edit" ? writes.find(p => MAIN_PLAN_FILE.test(p)) : undefined;
+		if (shellPlan) {
+			log(cfg.paths.plan_guard_log, `BLOCK main tool=${e.tool} shell write to plan ${shellPlan}`);
+			return deny(`plan-guard: ${shellPlan} is a plan file: change it with the edit or write tool (close or cancel it with queue-close / queue-cancel).`);
+		}
+		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 +388,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.
@@ -399,23 +472,28 @@ export function flagCancel(text: string, cfg: Config): string {
 
 /**
  * prompt/owner message: inject the queue summary, flag cancel wording, reset Main's edit window
- * and the stop counters (the original resets them at every user message).
+ * and the stop counters (the original resets them at every user message). A turn the harness
+ * starts from this guard's own stop continuation ("main-guard: …") is not an owner message: it
+ * keeps the counters and the edit window, else every continuation reset the idle streak and a
+ * model that only answers text was nudged again forever (2026-10-21 OOM: ~205 agent starts in one
+ * non-interactive session).
  */
 export function checkInject(e: InjectEvent, cfg: Config): Decision {
 	if (e.agent !== "main") return ALLOW;
-	writeWindow({ used: [], windowStart: 0 });
+	const continuation = e.inject.trimStart().startsWith("main-guard:");
+	if (!continuation) writeWindow({ used: [], windowStart: 0 });
 	let summary: string;
 	try {
 		summary = q.queueSummary();
 	} catch (err) {
 		summary = `Queue unreadable (${q.INDEX}): ${err}`;
 	}
-	const cancel = flagCancel(e.inject, cfg);
+	const cancel = continuation ? "" : flagCancel(e.inject, cfg);
 	return {
 		allow: true,
 		reason: "",
 		inject: `${summary}\n(main-guard: read ${q.INDEX} and the listed repo INDEX.md files are summarised above; work the open plans, close finished ones with queue-close.)${cancel}`,
-		state: { callsSinceStop: 0, idleStops: 0 },
+		...(continuation ? {} : { state: { callsSinceStop: 0, idleStops: 0 } }),
 	};
 }
 
@@ -433,7 +511,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 +523,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,58 @@ 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");
+	// The CLI file itself (shebang `#!/usr/bin/env bun`), never process.execPath: inside a host
+	// harness that is the harness binary, which would start a new agent session instead.
 	const cli = join(dirname(fileURLToPath(import.meta.url)), "../cli/main.ts");
-	const doctor = spawnSync(process.execPath, [cli, "doctor"], { encoding: "utf8", env: process.env });
+	const doctor = spawnSync(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

@@ -1,7 +1,7 @@
 // Queue model: main index, repo INDEX.md, plan shape (templates/queue/TEMPLATE.md).
 
 import { createHash } from "node:crypto";
-import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
@@ -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];
 }
@@ -279,6 +306,60 @@ export function changesFiles(toolName: string, input: Record<string, unknown>):
 	return SHELL_TOOLS.has(toolName) && MUTATING.test(String(input?.command ?? input?.code ?? ""));
 }
 
+// P8: package-manager and cutover commands change the running guard package.
+// Their write target is the protected root they touch, so the ordinary
+// protected-path check refuses them without the owner's unlock. Matched per
+// shell segment, with leading KEY=VALUE assignments stripped; the cutover
+// scripts stay free when the same segment pins HOME to /tmp (how every sandbox
+// test and the P9 session test run them). Harness-owned command shapes are NOT
+// matched here: the adapter registers them through registerPackageOpTarget,
+// because core never names a harness.
+function isNeurastreamSpec(t: string): boolean {
+	const base = t.replace(/^["']|["']$/g, "").replace(/^\.?\//, "").replace(/^.*\//, "");
+	return base === "neurastream" || base.startsWith("neurastream@") || /^neurastream-[^/]*\.tgz$/.test(base);
+}
+
+// Adapter-registered matcher for harness package operations (plugin install,
+// link, ...). Returns the protected root the command writes, or null.
+export type PackageOpMatcher = (code: string) => string | null;
+export let packageOpMatcher: PackageOpMatcher | null = null;
+
+export function registerPackageOpTarget(fn: PackageOpMatcher): void {
+	packageOpMatcher = fn;
+}
+
+function packageOpTarget(code: string): string | null {
+	for (const seg of code.split(/&&|\|\||;|\n|\|/)) {
+		const toks = seg.trim().split(/\s+/).filter(Boolean);
+		let i = 0;
+		while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i] ?? "")) i++;
+		const cmd = (toks[i] ?? "").replace(/^["']|["']$/g, "").replace(/^.*\//, "");
+		const rest = toks.slice(i + 1).map(t => t.replace(/^["']+|["']+$/g, ""));
+		const sub = rest[0] ?? "";
+		const hasGlobal = rest.some(t => t === "-g" || t === "--global");
+		const names = rest.slice(1).filter(t => !t.startsWith("-"));
+		if (cmd === "bun" && ["add", "install", "remove", "rm", "update", "link", "unlink"].includes(sub) && hasGlobal) {
+			if (!names.length || names.some(isNeurastreamSpec)) return `${bunGlobalRoot()}/install/global/node_modules/neurastream`;
+			continue;
+		}
+		if (cmd === "npm" && ["install", "i", "uninstall", "update", "link"].includes(sub) && hasGlobal) {
+			if (!names.length || names.some(isNeurastreamSpec)) return `${bunGlobalRoot()}/install/global/node_modules/neurastream`;
+			continue;
+		}
+		if (cmd === "neurastream" && sub === "adapter" && ["install", "uninstall"].includes(rest[1] ?? ""))
+			return `${bunGlobalRoot()}/install/global/node_modules/neurastream`;
+		if ((cmd === "bash" || cmd === "sh") && rest.some(t => {
+			const base = t.replace(/^.*\//, "");
+			return base === "cutover.sh" || base === "rollback.sh";
+		})) {
+			const envHome = toks.slice(0, i).find(t => t.startsWith("HOME="));
+			if (envHome && envHome.slice("HOME=".length).replace(/^["']|["']$/g, "").startsWith("/tmp/")) continue;
+			return `${agentDir()}/extensions/`;
+		}
+	}
+	return packageOpMatcher?.(code) ?? null;
+}
+
 export function writeTargets(toolName: string, input: Record<string, unknown>, cwd: string): string[] {
 	const out = new Set<string>();
 	const add = (raw: string, from: string) => {
@@ -307,7 +388,10 @@ export function writeTargets(toolName: string, input: Record<string, unknown>, c
 	}
 	if (!SHELL_TOOLS.has(toolName)) return [];
 	const code = String(input?.command ?? input?.code ?? "");
-	if (!MUTATING.test(code)) return [];
+	// A package/plugin/cutover command is a write even though none of the
+	// generic mutating heuristics fire on its text.
+	const pkgOp = packageOpTarget(code);
+	if (!MUTATING.test(code) && !pkgOp) return [];
 	let dir = typeof input?.cwd === "string" ? path.resolve(cwd, expandHome(input.cwd)) : cwd;
 	for (const seg of code.split(/&&|\|\||;|\n|\|/)) {
 		const s = seg.trim();
@@ -337,6 +421,7 @@ export function writeTargets(toolName: string, input: Record<string, unknown>, c
 		/\bshutil\.\w+\(\s*["'][^"']+["']\s*,\s*(["'][^"']+["'])/g,
 	])
 		for (const m of code.matchAll(re)) add((m[1] ?? "").replace(/`/g, ""), dir);
+	if (pkgOp) out.add(pkgOp);
 	return [...out];
 }
 
@@ -345,9 +430,29 @@ export function unlockPath(): string {
 }
 export let UNLOCK = unlockPath();
 export const UNLOCK_MINUTES = 30;
+// P8 (2026-10-21): after the npm cutover the running guards load from the
+// installed package, so the package itself is guard surface. The package root
+// is only claimed when this file really is part of a published neurastream
+// package (package.json name check): the pre-cutover standalone copy under
+// <agent>/queue/ has no package.json above it and must not protect the home.
+function packageManifest(): { root: string; bins: string[] } | null {
+	try {
+		const root = realpathSync(path.resolve(path.dirname(import.meta.path), "..", "..", ".."));
+		const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")) as { name?: string; bin?: Record<string, string> };
+		if (pkg.name !== "neurastream") return null;
+		return { root, bins: Object.keys(pkg.bin ?? {}) };
+	} catch {
+		return null;
+	}
+}
+
+function bunGlobalRoot(): string {
+	return process.env.BUN_INSTALL ? path.resolve(expandHome(process.env.BUN_INSTALL)) : `${HOME}/.bun`;
+}
+
 function protectedPaths(): string[] {
 	const agent = agentDir();
-	return [
+	const paths = [
 		`${agent}/extensions/`,
 		`${agent}/queue/`,
 		`${agent}/blockers/`,
@@ -368,7 +473,18 @@ function protectedPaths(): string[] {
 		`${HOME}/.local/bin/git`,
 		`${HOME}/.local/bin/git-secret-gate`,
 		`${HOME}/.config/git-secret-gate/`,
+		// Where `bun add -g neurastream` lands; writeTargets points package
+		// operations here so they need the owner's unlock like any guard edit.
+		// The plugin dir is adapter surface: the installer lists it in the
+		// config's guards.protected (core never names a harness path).
+		`${bunGlobalRoot()}/install/global/node_modules/neurastream/`,
 	];
+	const pkg = packageManifest();
+	if (pkg) {
+		paths.push(`${pkg.root}/`);
+		for (const name of pkg.bins) paths.push(`${HOME}/.bun/bin/${name}`);
+	}
+	return paths;
 }
 export let PROTECTED = protectedPaths();
 
@@ -552,7 +668,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/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 +