@hydraharness/harness-plan-mode 0.1.1-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @hydraharness/harness-plan-mode
+
+Logged, per-agent plan collaboration state with deployment-owned guidance, direct `/plan [message]` entry and `/plan off` exit commands, and the reviewed `exit_plan_mode` exit. Plan mode is soft guidance; sandbox mode and approval policy enforce restrictions independently and do not read or write plan state.
+
+Plan state follows the selected transcript version; selecting a version clears uncommitted local plan intents.
+
+## Durable state
+
+`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace `SessionEventMap` member. `foldPlanMode(events)` returns the last logged value or `false`, so resume, fork, and compaction recover plan state directly from the session log. UIs observe committed flips through `session/event`.
+
+`ctx.planMode.set(agent, active)` appends the standalone `plan/mode` event immediately when the agent is idle, because no in-turn pre-step runs before the next prompt. While the agent is running, it holds a pending selection for the next accepted in-turn pre-step. It returns which happened (`committed`/`queued`), a `cancelled` reversal, or a `noop`. `get(agent)` returns `{ active, pending? }`, separating the logged state used to assemble the current step from a user's mid-turn selection. Initial and continuation pre-steps both apply pending selections; a same-step request-recovery retry reuses its frozen assembly and leaves the selection pending for the next pre-step. A changed user selection contributes one plugin-sourced `user/message` notice when the last logged request header described the other state (both commit paths).
+
+## Model and human interactions
+
+While active, `plan:policy` renders the configured `section`. The plugin always registers `exit_plan_mode`, keeping tool schemas stable across the transition; its execute path accepts only active plan mode and leaves it only after an exact user approval through `ctx.userQuestions`.
+
+The review question declares the `plan-review` presentation intent, naming `Approve` as the label that approves it, so a capable UI presents the plan as a decision instead of a generic question; the answer the tool reads is the same either way. A dismissed review — the user closing the request to speak instead — is reported to the model as such, telling it to stay in plan mode and wait for the message; every other review failure keeps the seam's own message.
+
+When `ctx.commands` is composed, the package registers `/plan [message]` and reserves the exact argument `off` for direct exit. Bare `/plan` selects plan mode; any other non-empty argument selects it first and is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance. `/plan off` selects inactive without sending model input; it also cancels a pending entry before plan mode reaches a request. The command declares `input.images`: composer image attachments ride the steered message ahead of its text block. Bare `/plan` with images steers an image-only user message, while `/plan off` with images returns a direct error before any mode change so the composer keeps them.
+
+The Web client consumes the plugin-owned `/plan` command; other entry points may drive the same service directly without defining a second mode vocabulary.
+
+## Session projection
+
+When the composition mounts `ctx.sessionProjections` ([`@hydraharness/harness-session-projection`](../../session/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. A `command/run` record named `plan` with recorded `args` starts a candidate target (`off` → inactive, anything else → active); its paired `command/done` retains a successful selection and drops an error; `plan/mode` commits the logged state and clears the retained selection. Every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an unsettled or successful selection differs from the logged state. This remains a pure replay quantity, so host restarts, other tabs, and cold reads recover it from the log alone, and a rejected `/plan off` with images cannot leave a pending exit. The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
+
+## Configuration
+
+```yaml
+- id: plan-mode
+  name: '@hydraharness/harness-plan-mode'
+  config:
+    section: |
+      You are in plan mode. Explore and design before presenting the complete
+      plan through exit_plan_mode.
+```
+
+`section` is required and non-empty. Unknown keys fail at load. The package does not accept arbitrary named modes, tool filters, sandbox settings, or approval policy.
+
+Design: [plan-specific collaboration state](../../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).
+
+## Model Experience
+
+### Plan policy system prompt
+
+#### What the model sees
+
+While plan mode is active, the model sees the deployment's exact `section` text at prompt order 50; inactive mode contributes no text.
+
+##### Configuration example
+
+```markdown
+You are in plan mode. Explore and design before presenting the complete plan through exit_plan_mode.
+```
+
+#### Token effect
+
+Inactive mode adds no tokens; active mode adds the configured section to every request.
+
+#### KV Cache effect
+
+The section is stable within plan mode, but entering or leaving changes the system prompt from order 50 onward.
+
+### Human command
+
+#### What the model sees
+
+`/plan`, `/plan off`, and their terminal results stay outside model history. A non-empty suffix other than the exact `off` argument becomes one user message through `agent.steer()` after plan mode is selected: any admitted image attachments as leading image blocks, then the trimmed text block. Bare `/plan` with admitted images steers one user message containing only those image blocks. An active `/plan off` selection contributes the standard logged user-switch notice only when the last request header described plan mode; cancelling a pending entry contributes none because no request observed it.
+
+#### Token effect
+
+The optional message costs the same history tokens as submitting that content separately. Bare `/plan` without images and `/plan off` add none; bare `/plan` with images has the normal image-prompt cost. A narrated active exit adds the small retained switch notice.
+
+#### KV Cache effect
+
+The user block is append-only conversation growth. Entering or leaving plan mode changes the earlier policy section; a narrated exit notice is appended after the reusable request prefix.
+
+### Exit tool schema and review exchange
+
+#### What the model sees
+
+The [`exit_plan_mode` schema](../../../docs/tool-catalog.md#hydraharness-plan-mode) remains available in both states; execution outside plan mode fails, while an approved in-mode review returns the canonical `{ approved: true }` value and renders the existing confirmation text. Rejection remains a failed call carrying review feedback, and a dismissed review a failed call naming the user's takeover.
+
+#### Token effect
+
+The stable schema is paid according to ToolRuntime mode, and each plan argument and review result remains in conversation history.
+
+#### KV Cache effect
+
+Mode transitions do not change the tool catalog; plan arguments and review results extend the conversation normally.
+
+## Known Limitations and Deferred Work
+
+- Plan mode guides rather than enforces; deployments that need enforced restrictions must configure sandbox and approval controls independently.
+- A selection made after the turn's final accepted pre-step is lost if the process exits before another accepted in-turn pre-step, so the UI must reapply it.
+- Forked agents inherit logged plan state, while newly spawned agents begin inactive; there is no creation-time plan option.
+- A live child owned by another agent cannot open the `exit_plan_mode` review. The failed call tells the child to include the unresolved decision in its final result; durable fork lineage alone does not prevent a session resumed as a runtime root from opening the review.
+- Only the Web UI has a specialized `plan-review` renderer; another interaction provider may present the same request through its generic option flow.

package/lib/index.js

@@ -0,0 +1,429 @@
+import { Service } from "@hydraharness/cordis";
+import { z } from "zod";
+import { createUserMessage } from "@hydraharness/harness-llm";
+import { defineTool } from "@hydraharness/harness-tools";
+import { UserQuestionError } from "@hydraharness/harness-user-questions";
+//#region lib/types/index.js
+/**
+* Plan mode is logged per-agent collaboration state: while active, a
+* deployment-owned guidance section is included in each model request, and
+* `exit_plan_mode` presents the completed plan for user review, while the
+* `/plan off` command lets a user leave directly. Sandbox mode and approval
+* policy enforce restrictions independently and do not read or write plan
+* state.
+*
+* The state in force is folded from the session log (`plan/mode`, last one
+* wins), so resume and fork restore it without a live mirror. User selections
+* remain pending until the next accepted in-turn pre-step. The service includes
+* the selected state in the proposed step assembly, then appends `plan/mode`
+* from `agent/pre-step` only when the step is accepted. Same-step request
+* retries reuse their assembly.
+*
+* The exit tool remains registered while plan mode is inactive, so entering
+* or leaving plan mode changes only the prompt section, not the request tool
+* catalog.
+*
+* Agent Note:
+* - .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
+*
+* @module @hydraharness/harness-plan-mode
+*/
+/**
+* The model-facing exit tool's name. It stays registered while plan mode is
+* inactive so the request tool catalog is stable across transitions.
+*/
+const EXIT_PLAN_MODE = "exit_plan_mode";
+/** The review question's id, echoed in the answer this tool reads. */
+const REVIEW_ID = "plan-review";
+/** The review question's approve option label. */
+const APPROVE_LABEL = "Approve";
+/** The review question's keep-planning option label. */
+const KEEP_PLANNING_LABEL = "Keep planning";
+const EXIT_DESCRIPTION = "Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again.";
+/** The plan's first markdown heading (any level), or `undefined` when it has none. */
+function firstHeading(plan) {
+	for (const line of plan.split("\n")) {
+		const match = /^#{1,6}\s+(.+?)\s*$/.exec(line);
+		if (match) return match[1];
+	}
+}
+/**
+* Validate deployment-owned plan guidance. Missing, blank, non-string, or
+* unknown fields fail at plugin load rather than being ignored.
+*
+* @param config Raw plugin config.
+* @returns A detached validated config.
+*/
+function resolveConfig(config) {
+	const section = config.section;
+	if (typeof section !== "string") throw new Error("PlanModeConfig needs a string `section`");
+	if (section.trim() === "") throw new Error("PlanModeConfig needs a non-empty `section`");
+	const unknown = Object.keys(config).filter((key) => key !== "section");
+	if (unknown.length > 0) throw new Error(`PlanModeConfig has unknown key(s) ${unknown.join(", ")} — config is { section }`);
+	return { section };
+}
+/**
+* Whether plan mode is active after the first `end` events. The last
+* `plan/mode` wins; a prefix with none is inactive.
+*
+* @param events The session log or any prefix of it.
+* @param end Fold `events[0, end)`; defaults to the whole log.
+* @returns Whether plan mode is active.
+*/
+function foldPlanMode(events, end = events.length) {
+	let active = false;
+	let index = 0;
+	for (const event of events) {
+		if (index >= end) break;
+		index++;
+		if (event.type === "plan/mode") active = event.data.active;
+	}
+	return active;
+}
+const planUnitStateSchema = z.object({
+	active: z.boolean(),
+	wanted: z.boolean().nullable(),
+	running: z.object({
+		commandId: z.string(),
+		wanted: z.boolean()
+	}).strict().nullable()
+}).strict();
+/** Wire payload schema of the `plan` projection. */
+const planProjectionSchema = z.object({
+	active: z.boolean(),
+	pending: z.boolean()
+});
+/** Whether the log holds an opened turn without its closing `turn/end`. */
+function hasOpenTurn(events) {
+	let open = false;
+	for (const event of events) if (event.type === "turn/start") open = true;
+	else if (event.type === "turn/end") open = false;
+	return open;
+}
+/** Plan state at the last logged request header, or `undefined` before the first header. */
+function planModeAtLastHeader(events) {
+	let lastHeader = -1;
+	let index = 0;
+	for (const event of events) {
+		if (event.type === "request/header") lastHeader = index;
+		index++;
+	}
+	if (lastHeader < 0) return void 0;
+	return foldPlanMode(events, lastHeader + 1);
+}
+/**
+* `ctx.planMode`: owns logged plan state, applies and narrates selected state at step start,
+* the `plan:policy` section, the `/plan` command, and the stable exit tool.
+* UIs observe committed flips through `session/event`; there is no live mirror.
+*/
+var PlanModeController = class extends Service {
+	static inject = ["tools", "systemPrompt"];
+	/** Validated deployment-owned guidance. */
+	section;
+	/**
+	* Latest selection per session awaiting the next accepted in-turn pre-step.
+	* `narrate` is true for user selections and false for the exit tool, whose
+	* result already narrates the transition.
+	*/
+	pendingIntents = /* @__PURE__ */ new WeakMap();
+	constructor(ctx, config = { section: "" }) {
+		super(ctx, "planMode");
+		this.section = resolveConfig(config).section;
+		ctx.on("session/event", (session, event) => {
+			if (event.type === "session/version" || event.type === "session/version-selected") this.pendingIntents.delete(session);
+		});
+		let disposed = false;
+		ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
+			const decision = await next();
+			const pending = this.pendingIntents.get(agent.session);
+			if (decision.kind === "reject" || signal.aborted || pending === void 0) return decision;
+			const narration = this.narration(agent.session, pending.active);
+			try {
+				this.onBoundary(agent.session);
+			} catch (error) {
+				ctx.logger.warn("hydra-plan-mode: failed to append selected plan mode at step start: %o", error);
+				return decision;
+			}
+			return !pending.narrate || narration === void 0 ? decision : {
+				...decision,
+				messages: [...decision.messages, narration]
+			};
+		});
+		ctx.effect(() => () => {
+			disposed = true;
+		}, "hydra-plan-mode: close service lifetime");
+		ctx.systemPrompt.section({
+			name: "plan:policy",
+			order: 50,
+			text: (context) => {
+				if (context.agent === void 0) return "";
+				return this.pendingIntents.get(context.agent.session)?.active ?? foldPlanMode(context.agent.session.activeEvents) ? this.section : "";
+			}
+		});
+		ctx.inject(["sessionProjections"], (projectionCtx) => {
+			projectionCtx.sessionProjections.register({
+				key: "plan",
+				history: "active-version",
+				stateSchema: planUnitStateSchema,
+				init: () => ({
+					active: false,
+					wanted: null,
+					running: null
+				}),
+				apply: (state, event) => {
+					if (event.type === "command/run" && event.data.name === "plan") {
+						if (event.data.args === void 0) return state;
+						const wanted = event.data.args.trim() !== "off";
+						return {
+							...state,
+							running: {
+								commandId: event.data.commandId,
+								wanted
+							}
+						};
+					}
+					if (event.type === "command/done" && event.data.commandId === state.running?.commandId) {
+						const wanted = event.data.kind === "success" && state.running.wanted !== state.active ? state.running.wanted : null;
+						return {
+							...state,
+							wanted,
+							running: null
+						};
+					}
+					if (event.type === "plan/mode") return {
+						...state,
+						active: event.data.active,
+						wanted: null
+					};
+					return state;
+				},
+				wire: {
+					viewSchema: planProjectionSchema,
+					view: (state) => {
+						const wanted = state.running?.wanted ?? state.wanted;
+						return {
+							active: state.active,
+							pending: wanted !== null && wanted !== state.active
+						};
+					}
+				},
+				stateVersion: 3
+			});
+		});
+		ctx.inject(["commands"], (commandCtx) => {
+			commandCtx.commands.register({
+				name: "plan",
+				description: "Enter or leave plan mode",
+				input: {
+					hint: "[off|message]",
+					images: true
+				},
+				handler: ({ agent, rawInput, attachments }) => {
+					const message = rawInput.trim();
+					if (message === "off" && attachments.length > 0) return {
+						kind: "error",
+						text: "Image attachments cannot accompany /plan off."
+					};
+					if (message === "off") switch (this.set(agent, false)) {
+						case "committed": return {
+							kind: "success",
+							text: "Plan mode off."
+						};
+						case "queued": return {
+							kind: "success",
+							text: "Leaving plan mode (applies from the next step)."
+						};
+						case "cancelled": return {
+							kind: "success",
+							text: "Plan mode entry cancelled."
+						};
+						case "noop": return foldPlanMode(agent.session.activeEvents) ? {
+							kind: "success",
+							text: "Leaving plan mode (applies from the next step)."
+						} : {
+							kind: "success",
+							text: "Plan mode is already inactive."
+						};
+					}
+					const outcome = this.set(agent, true);
+					if (message !== "" || attachments.length > 0) agent.steer(createUserMessage({
+						content: [...attachments, ...message === "" ? [] : [{
+							type: "text",
+							text: message
+						}]],
+						source: { kind: "user" }
+					}));
+					return {
+						kind: "success",
+						text: outcome === "committed" ? "Plan mode on. Use /plan off to leave." : "Entering plan mode (applies from the next step). Use /plan off to leave."
+					};
+				}
+			});
+		});
+		ctx.tools.register(defineTool({
+			name: EXIT_PLAN_MODE,
+			description: EXIT_DESCRIPTION,
+			parameters: { plan: {
+				type: "string",
+				required: true,
+				description: "The complete plan, as markdown, starting with a # heading that names it."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { approved: {
+						type: "boolean",
+						const: true,
+						required: true
+					} }
+				},
+				render: () => [{
+					type: "text",
+					text: "Plan approved — plan mode exited; carry out the plan starting with your next step."
+				}]
+			},
+			execute: async (args, exec) => {
+				const agent = exec.agent;
+				if (agent === void 0) throw new Error(`${EXIT_PLAN_MODE} requires a calling agent (no session to switch)`);
+				if (!foldPlanMode(agent.session.activeEvents)) throw new Error(`${EXIT_PLAN_MODE} is only available in plan mode`);
+				if (!/^#\s+\S/.test(args.plan.trim())) throw new Error(`${EXIT_PLAN_MODE} requires a non-empty markdown plan starting with a # heading`);
+				const interaction = ctx.get("userQuestions");
+				if (interaction === void 0) throw new Error("no user-questions channel is available to review the plan; ask the user to switch the session mode instead");
+				const answer = await interaction.ask({
+					questions: [{
+						id: REVIEW_ID,
+						header: "Plan review",
+						question: "Approve this plan and leave plan mode?",
+						detail: args.plan,
+						options: [{
+							label: APPROVE_LABEL,
+							description: "Leave plan mode; the plan is carried out from the next step."
+						}, {
+							label: KEEP_PLANNING_LABEL,
+							description: "Stay in plan mode; feedback goes back to the model."
+						}],
+						intent: {
+							kind: "plan-review",
+							approve: APPROVE_LABEL
+						}
+					}],
+					agent,
+					signal: exec.signal
+				}).catch((cause) => {
+					if (cause instanceof UserQuestionError && cause.code === "ASK_CANCELLED") throw new Error("The user dismissed the plan review to speak instead; stay in plan mode, stop here, and wait for their message.");
+					throw cause;
+				});
+				if (disposed) throw new Error("the plan-mode service was reloaded while the plan was under review; present the plan again");
+				const reviewItems = answer.answers.filter((entry) => entry.id === REVIEW_ID);
+				const item = reviewItems.length === 1 ? reviewItems[0] : void 0;
+				if (item?.selected.length !== 1 || item.selected[0] !== APPROVE_LABEL || item.custom !== void 0) {
+					const feedback = item?.custom ?? "";
+					throw new Error(feedback === "" ? "The user chose to keep planning; revise the plan and present it again." : `The user chose to keep planning; their feedback: ${feedback}`);
+				}
+				this.pendingIntents.set(agent.session, {
+					active: false,
+					narrate: false
+				});
+				return { approved: true };
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: firstHeading(args.plan) ?? "Plan",
+				kind: "other",
+				content: [{
+					type: "text",
+					text: args.plan
+				}]
+			}),
+			presentResult: (_args, result) => ({
+				card: "generic",
+				title: "Plan review",
+				content: result.content
+			})
+		}));
+	}
+	/**
+	* Read the logged plan state and any selected state awaiting the next
+	* accepted in-turn pre-step.
+	*
+	* @param agent The agent to read.
+	* @returns Current logged state plus a pending selection, when present.
+	*/
+	get(agent) {
+		const active = foldPlanMode(agent.session.activeEvents);
+		const pending = this.pendingIntents.get(agent.session);
+		return pending === void 0 ? { active } : {
+			active,
+			pending: pending.active
+		};
+	}
+	/**
+	* Select whether plan mode should be active. Between turns the method
+	* appends the change immediately because no in-turn pre-step will run until
+	* another prompt starts a turn. The open-turn fold is the idle signal:
+	* agent status stays `running` through post-turn checkpointing, when no
+	* further in-turn pre-step runs. During an open turn the selection remains
+	* pending until the next accepted in-turn pre-step. Repeated selection of
+	* the current or already-pending state is a no-op.
+	*
+	* @param agent The agent to switch.
+	* @param active Whether plan mode should be active.
+	* @returns what happened: `committed` (logged now), `queued` (awaiting the
+	* next accepted in-turn pre-step), `cancelled` (an opposite pending selection
+	* was cleared; the logged state already matches), or `noop` (already in that
+	* state).
+	*/
+	set(agent, active) {
+		const session = agent.session;
+		if (active === (this.pendingIntents.get(session)?.active ?? foldPlanMode(session.activeEvents))) return "noop";
+		if (hasOpenTurn(session.activeEvents)) {
+			this.pendingIntents.set(session, {
+				active,
+				narrate: true
+			});
+			return foldPlanMode(session.activeEvents) === active ? "cancelled" : "queued";
+		}
+		if (active === foldPlanMode(session.activeEvents)) {
+			this.pendingIntents.delete(session);
+			return "cancelled";
+		}
+		session.append("plan/mode", { active });
+		this.pendingIntents.delete(session);
+		const narration = this.narration(session, active);
+		if (narration !== void 0) agent.inject(narration);
+		return "committed";
+	}
+	/** Append one pending selection before the next request assembly. */
+	onBoundary(session) {
+		const pending = this.pendingIntents.get(session);
+		if (pending === void 0) return;
+		const target = pending.active;
+		if (target === foldPlanMode(session.activeEvents)) {
+			this.pendingIntents.delete(session);
+			return;
+		}
+		session.append("plan/mode", { active: target });
+		this.pendingIntents.delete(session);
+	}
+	/** Build a user-switch notice when the last logged header described the other mode. */
+	narration(session, target) {
+		const told = planModeAtLastHeader(session.activeEvents);
+		if (told === void 0 || told === target) return;
+		const text = target ? "The user switched this session to plan mode." : "The user switched this session back to the default mode.";
+		return createUserMessage({
+			content: [{
+				type: "text",
+				text
+			}],
+			source: {
+				kind: "plugin",
+				plugin: "plan-mode",
+				form: "notice",
+				summary: text
+			}
+		});
+	}
+};
+//#endregion
+export { EXIT_PLAN_MODE, PlanModeController, PlanModeController as default, foldPlanMode, resolveConfig };

package/lib/invariant.js

@@ -0,0 +1,41 @@
+//#region lib/types/invariant.js
+/** Package-owned durable plan-mode invariants. @module @hydraharness/harness-plan-mode/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-plan-mode";
+/** Cordis companion plugin name. */
+const name = "plan-mode-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Validate one `plan/mode` event before it reaches the durable log.
+* `plan/mode` is a standalone whole-value event: an idle selection commits
+* between turns and a mid-turn selection commits at the step boundary, so
+* no turn-enclosure relation exists — only the payload shape is checkable.
+*/
+function validateEvent(event, fail) {
+	if (event.type !== "plan/mode") return;
+	const active = event.data.active;
+	if (typeof active !== "boolean") fail(`plan/mode carries invalid active state ${JSON.stringify(active)}; expected a boolean`);
+}
+/** Install validation for loaded and newly appended plan-mode state. */
+const install = Object.assign((ctx, fail) => {
+	const seed = (session) => {
+		for (const event of session.events) validateEvent(event, fail);
+	};
+	for (const session of ctx.sessions.list()) seed(session);
+	ctx.on("session/created", (session) => {
+		seed(session);
+	}, { global: true });
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [, event] = args;
+		validateEvent(event, fail);
+	}, { global: true });
+}, { inject: ["sessions"] });
+/**
+* Register the plan-mode invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the plan domain: a pure re-export of the package's
+ * types outlet. Client code imports ONLY the client namespace (repo
+ * discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ *
+ * @module @hydraharness/harness-plan-mode/client
+ */
+export type * from './types.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the plan domain: a pure re-export of the package's
+ * types outlet. Client code imports ONLY the client namespace (repo
+ * discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ *
+ * @module @hydraharness/harness-plan-mode/client
+ */
+export {};
+//# sourceMappingURL=client.js.map