@underactive/pi-topping-moa-fusion 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [0.3.0]
+
+### Added
+
+- Added `/mf-spec`, an in-process requirements-clarification flow that asks up to five focused questions, reviews and saves approved `__spec.md` planning briefs, and prepares a `/mf-plan` handoff without exposing specs to `/mf-plan-implement`.
+- A hidden `mf-plan-verification-pending` session marker now records when an approved implementation is expected to enter independent verification. Resuming before a verifier result is recorded warns that the implementation is still unverified.
+
+### Changed
+
+- Updated all four pi development dependencies from 0.86.0 to 0.87.0.
+- The pi 0.87 settle-boundary context-edit and verification-marker integrations are capability-gated and remain inert on older hosts, which retain the existing request-time filtering and verification dispatch behavior.
+
+### Fixed
+
+- An assigned slot in the MoA Fusion Pre-flight overview can now be cleared back to `(none)` with Backspace or Delete. Previously a slot could only be reassigned to another model, never emptied.
+- Reusable `[PLAN MODE ACTIVE]` and `[PLAN MODE RE-ENTRY]` instruction entries are now durably omitted with settle-boundary null context edits after plan-mode exit, preventing later compaction from carrying stale plan instructions into implementation.
+- Custom OpenAI-compatible endpoints used by proposers and verifiers now benefit from pi 0.87's upstream strict-schema capability fix: unknown endpoints no longer receive strict tool schemas unless they explicitly advertise support.
+- Saving or deleting an agent roster now takes effect immediately, without requiring a second save from the main settings overlay.
+- A failed agent's error is now readable in full without widening the terminal. Provider failures were cut to 80 characters before reaching the progress table and then truncated again at the ACTIVITY column edge, hiding the part naming the cause. The message is now kept whole and word-wrapped beneath its row — breaking the JSON payload mid-token when it has no spaces to break on — while a short error stays inline as before.
+
 ## [0.2.0]
 
 ### Added

package/README.md

@@ -16,6 +16,7 @@ A Pi extension built around **Mixture of Agents (MoA)** planning: several models
   - [The MoA Fusion table](#the-moa-fusion-table)
   - [Opinions (`/mf-opinion`)](#opinions-mf-opinion)
   - [Debates (`/mf-debate`)](#debates-mf-debate)
+  - [Specs (`/mf-spec`)](#specs-mf-spec)
 - [Commands](#commands)
   - [Cancelling running subagents](#cancelling-running-subagents)
 - [Plan Mode](#plan-mode)
@@ -74,7 +75,7 @@ Fanning out a coding task and merging the resulting token streams does not work
 ### How a run works
 
 1. After you submit your plan prompt, a picker opens on a mode screen (**Mixture of Agents** or **Single model**). Single model — or Esc — runs the 5-phase workflow on the current model.
-2. MoA opens the **MoA Fusion Pre-flight** overview with all eight slots — five proposer slots plus a synthesizer, an implementer, and a verifier — starting empty at `(none)`, plus a **Load Roster** row above **Start fan-out** that applies a saved agent roster to every slot at once (see [Agent rosters](#agent-rosters)). Selecting any slot row opens a two-pane model/thinking picker for that one slot and returns to the overview; cancelling leaves the slot unchanged. **Start fan-out** stays disabled until you assign at least two proposer slots and all three required roles (the minimum roster; the same model may fill several slots, and the extra proposer slots are optional). Thinking levels come from the model's pi registry metadata, which is authoritative for every model the registry lists; the generic `off`/`low`/`medium`/`high` list applies only to models it doesn't. Your saved choices and active model only pre-highlight a slot's picker — they never count as assignments until you confirm them — and confirmed selections are remembered in `~/.pi/agent/mf-plan/settings.json`.
+2. MoA opens the **MoA Fusion Pre-flight** overview with all eight slots — five proposer slots plus a synthesizer, an implementer, and a verifier — starting empty at `(none)`, plus a **Load Roster** row above **Start fan-out** that applies a saved agent roster to every slot at once (see [Agent rosters](#agent-rosters)). Selecting any slot row opens a two-pane model/thinking picker for that one slot and returns to the overview; cancelling leaves the slot unchanged, and Backspace (or Delete) on a slot row clears it back to `(none)`. **Start fan-out** stays disabled until you assign at least two proposer slots and all three required roles (the minimum roster; the same model may fill several slots, and the extra proposer slots are optional). Thinking levels come from the model's pi registry metadata, which is authoritative for every model the registry lists; the generic `off`/`low`/`medium`/`high` list applies only to models it doesn't. Your saved choices and active model only pre-highlight a slot's picker — they never count as assignments until you confirm them — and confirmed selections are remembered in `~/.pi/agent/mf-plan/settings.json`.
 3. Proposers run in parallel as isolated `moa-proposer` subprocesses. Each ends with an "Open Questions / Assumptions" section rather than pausing — proposers never block waiting on input.
 4. `moa-synthesizer` reads every successful proposal (at least 1 must succeed) plus the original request, and writes one merged plan.
 5. If the proposers substantively disagreed, a conflict-review overlay opens first: one tab per conflict, plain-language options, the synthesized pick tagged **(Recommended)**, and a **Chat about this** box for free-text feedback. Your resolutions are fed back for re-synthesis. Esc cancels the whole run.
@@ -152,6 +153,19 @@ During the run, `F3` opens the live observer and `Esc` or `F4` opens cancellatio
 
 During the run, `F3` opens the live observer and `Esc` or `F4` opens cancellation controls. The prompt and combined transcript are saved under `.pi/mf-debate/` as `<slug>__debate-prompt.md` and `<slug>__debate.md`.
 
+### Specs (`/mf-spec`)
+
+`/mf-spec` follows a separate requirements workflow: rough request → clarification → approved planning brief → a user-started `/mf-plan`.
+
+1. Enter a request directly (`/mf-spec add dark mode`) or use the prompt editor.
+2. It asks up to five adaptive clarifying questions, stopping early when it has enough context. Each question names the area it affects: scope, UX, architecture, acceptance criteria, or testing.
+3. Press **Esc** during clarification to choose whether to draft from the answers so far or cancel; cancelling saves nothing.
+4. Review the draft and approve and save it, edit it directly, or revise it with feedback. Nothing is written before approval.
+5. The approved brief is saved as `.pi/mf-plan/<slug>__spec.md`. `/mf-plan-implement` ignores these files because they are specifications, not approved `__plan.md` implementation plans.
+6. After saving, a ready-to-run `/mf-plan …` handoff is placed in the input box when it is empty; review it and press Enter to start planning. Existing input is never overwritten, and `/mf-spec` refuses to run while plan mode is active.
+
+Clarification and drafting run in-process on the active session model with no tools or repository access. Repo-grounded planning begins only when you run the prepared `/mf-plan` command.
+
 ## Commands
 
 | Command | Shortcut | Description |
@@ -159,6 +173,7 @@ During the run, `F3` opens the live observer and `Esc` or `F4` opens cancellatio
 | `/mf-plan` | — | Toggle plan mode on/off |
 | `/mf-opinion` | — | Ask 1–5 models for independent read-only opinions about the repository |
 | `/mf-debate` | — | Run a read-only multi-round debate between up to 5 models |
+| `/mf-spec` | — | Clarify a rough request into an approved planning brief and prepare a `/mf-plan` handoff |
 | `/mf-preview` | — | Toggle the inline/live preview of streamed agent output |
 | `/mf-plan-settings` | — | Configure the explore and cheap/fast agents, named agent rosters for the MoA roles, plan options, and max concurrent agents |
 | `/mf-plan-implement` | — | Retry implementation of the last approved MoA plan, optionally with a different model |
@@ -272,7 +287,7 @@ Rosters persist in `~/.pi/agent/mf-plan/settings.json`:
 }
 ```
 
-Names are 1–24 alphanumeric characters, unique case-insensitively, up to 20 rosters. The roster manager stages every edit in memory — nothing is written until the settings overlay's **Save and Close**.
+Names are 1–24 alphanumeric characters, unique case-insensitively, up to 20 rosters. Slot edits remain drafts until **Save roster** is selected; that action persists the completed roster immediately, without requiring **Save and Close** in the parent settings overlay.
 
 #### Max concurrent agents
 
@@ -328,7 +343,7 @@ The slug is a generated adjective-adjective-noun triple (e.g. `happy-mellifluous
 
 ## Non-Interactive Behavior
 
-In non-interactive modes (`pi -p`, `--mode json`), `exit_plan_mode` is rejected unless `MOA_PLAN_AUTO_APPROVE=1` is set. With that explicit opt-in, it exits plan mode and hands the plan back without prompting. The plan file is still written to disk.
+In non-interactive modes (`pi -p`, `--mode json`), `exit_plan_mode` is rejected unless `MOA_PLAN_AUTO_APPROVE=1` is set. With that explicit opt-in, it exits plan mode and hands the plan back without prompting. The plan file is still written to disk. `/mf-spec <request>` likewise requires `MOA_PLAN_AUTO_APPROVE=1`; with it, the command skips questions and review, generates and saves the brief, and prints the `/mf-plan` handoff, while without it no model call or file write occurs.
 
 ## How It Works (Architecture)
 
@@ -370,6 +385,9 @@ src/
 │   ├── debateRounds.ts      # Survivor/early-stop/next-round bookkeeping
 │   ├── debateResults.ts     # Outcome collection and debate transcript markdown
 │   └── debateFile.ts        # Repo-local debate artifacts
+├── spec/
+│   ├── specContract.ts      # Clarification/brief contracts, parsing, and handoff helpers
+│   └── runSpec.ts           # Interactive/headless /mf-spec state machine
 ├── planning/
 │   ├── planMode.ts          # Plan-mode state transitions and lifecycle handlers
 │   ├── modeState.ts         # Persisted state shape, byte cap, append deduplication
@@ -437,7 +455,7 @@ agents/                      # Shipped agent definitions
 - **Custom `write_plan` tool** instead of path-guarded `edit`/`write` — guarantees the single-writable-file invariant.
 - **Subprocess subagents** (not in-process) — each agent runs in an isolated `pi --mode json -p --no-session` subprocess with an enforced read-only tool allowlist.
 - **State via `appendEntry`** — plan mode state (enabled, slug, tools snapshot) persists in the session for `/resume` and `/reload`.
-- **Context injection via `before_agent_start`** — the 5-phase instructions are injected as a user message every turn while plan mode is active; the `context` hook strips stale plan-mode messages once it is off.
+- **Context injection and lifecycle cleanup via `before_agent_start` + `context`** — the 5-phase instructions are injected as a user message every turn while plan mode is active, and the `context` hook strips stale plan-mode messages once it is off. On pi 0.87+, the settle boundary also persists null context edits for reusable plan-instruction entries once plan mode is off, so later compaction cannot carry those instructions forward. When an approved implementation is expected to enter verification, the same boundary persists a hidden `mf-plan-verification-pending` marker so a resumed session can warn that verification is still outstanding.
 - **MoA proposers never pause mid-run** — subprocess subagents are one-shot, so a proposer that hits an ambiguity records it as an assumption and keeps going. Only the synthesizer, which sees every proposal, asks the user anything — keeping fan-out fully parallel.
 
 ## Porting Notes
@@ -453,6 +471,7 @@ Ported from Claude Code's plan mode, adapted to pi's extension primitives:
 | `FileEditTool`/`FileWriteTool` guarded | Custom `write_plan` tool | Safer single-writable-file invariant |
 | Subscription-tier agent counts | Hardcoded constants (3/1) | Bumpable via code change |
 | Plan-length A/B experiment | Standard Phase 4 | Experiment noise skipped |
+| Spec Kit / brainstorming | `/mf-spec` | Requirements clarification only |
 | Interview phase variant | Standard 5-phase workflow | Variant skipped |
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@underactive/pi-topping-moa-fusion",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pi extension implementing /mf-plan — Claude Code-style 5-phase plan mode with a Mixture-of-Agents proposer/synthesizer pipeline.",
   "keywords": [
     "pi-package",
@@ -50,10 +50,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.86.0",
-    "@earendil-works/pi-ai": "0.86.0",
-    "@earendil-works/pi-coding-agent": "0.86.0",
-    "@earendil-works/pi-tui": "0.86.0",
+    "@earendil-works/pi-agent-core": "0.87.0",
+    "@earendil-works/pi-ai": "0.87.0",
+    "@earendil-works/pi-coding-agent": "0.87.0",
+    "@earendil-works/pi-tui": "0.87.0",
     "@types/node": "^24.0.0",
     "typebox": "^1.3.3",
     "typescript": "^5.8.0"

package/src/debate/debateFanout.ts

@@ -4,7 +4,7 @@ import type { AgentConfig } from "../agents/discovery.ts";
 import { modelExtensionOptions, resolveContextWindow, resolveModelCost } from "../moa/modelRuntime.ts";
 import type { CancelSession } from "../runtime/cancelRun.ts";
 import { CancelRun } from "../runtime/cancelRun.ts";
-import { getFinalOutput, getResultOutput, isFailedResult, type SingleResult } from "../runtime/results.ts";
+import { getFinalOutput, getResultOutput, isFailedResult, statusDetail, type SingleResult } from "../runtime/results.ts";
 import { runParallelAgentsWithModels, type ModelParallelAgentTask } from "../runtime/runner.ts";
 import { modelRefLabel, type ModelRef, type ThinkingLevel } from "../shared/modelRefs.ts";
 import { activityLoopCount } from "../ui/agentStatus.ts";
@@ -117,7 +117,7 @@ export async function runDebateRounds(options: DebateFanoutOptions): Promise<Deb
 							if (observed) observed.state = "cancelled";
 						} else if (isFailedResult(result)) {
 							currentRun.settle(batchIndex, "error");
-							widget.update(debateIndex, "error", getResultOutput(result).slice(0, 80));
+							widget.update(debateIndex, "error", statusDetail(getResultOutput(result)));
 							if (observed) observed.state = "error";
 						} else {
 							currentRun.settle(batchIndex, "done");

package/src/index.ts

@@ -12,7 +12,7 @@ import {
 } from "./moa/implementationRetry.ts";
 import { modelRefLabel, TRIGGER_TURN } from "./shared/modelRefs.ts";
 import { loadMoaConfig } from "./config/settings.ts";
-import { getPlanFilePath, getRepoPlanDirectory, isValidPlanSlug, readRepoPlanFile, saveRepoPlanFile } from "./planning/planFile.ts";
+import { getPlanFilePath, getRepoPlanDirectory, isApprovedRepoPlanFilename, isValidPlanSlug, readRepoPlanFile, saveRepoPlanFile } from "./planning/planFile.ts";
 import { showImplementingModelPicker } from "./ui/moaModelPicker.ts";
 import { showPlanReview } from "./ui/planReviewOverlay.ts";
 import { showMoaSetup } from "./ui/moaSetupOverlay.ts";
@@ -20,6 +20,7 @@ import { runCriteriaGeneration } from "./moa/verificationCriteria.ts";
 import { stripSynthSections } from "./moa/verdicts.ts";
 import { runInteractiveOpinion, type OpinionHost } from "./opinion/runOpinion.ts";
 import { runInteractiveDebate } from "./debate/runDebate.ts";
+import { createSpecRunner } from "./spec/runSpec.ts";
 import { createPlanModeController } from "./planning/planMode.ts";
 import { registerEnterPlanModeTool, runInteractivePlanMode } from "./planning/tools/enterPlanMode.ts";
 import { registerExitPlanModeTool } from "./planning/tools/exitPlanMode.ts";
@@ -38,6 +39,7 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 		setRunningProgressWidget: controller.moaRunHost.setRunningProgressWidget,
 	};
 	const debateHost = opinionHost;
+	const runSpec = createSpecRunner(controller);
 	const togglePlanMode = async (ctx: Parameters<typeof controller.exitPlanMode>[0], prompt?: string): Promise<void> => {
 		if (controller.questionnaireBusy(ctx)) return;
 		if (controller.getActiveCancelSession()?.run) {
@@ -69,6 +71,10 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 		description: "Run a read-only multi-round debate between up to 5 models — append a topic (e.g. /mf-debate is X sound?) to skip the editor",
 		handler: async (args, ctx) => { if (controller.questionnaireBusy(ctx)) return; await runInteractiveDebate(pi, debateHost, ctx, args.trim() || undefined); },
 	});
+	pi.registerCommand("mf-spec", {
+		description: "Clarify a rough request into an approved planning brief for /mf-plan — append the request (e.g. /mf-spec add dark mode) to skip the editor",
+		handler: async (args, ctx) => runSpec(ctx, args.trim() || undefined),
+	});
 	pi.registerCommand("mf-plan-clear", {
 		description: "Clear the completed plan state so /mf-plan starts a fresh planning round (approved plans stay in .pi/mf-plan/)",
 		handler: async (_args, ctx) => { if (controller.questionnaireBusy(ctx)) return; await controller.clearCompletedPlan(ctx); },
@@ -104,7 +110,7 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 					if (fs.existsSync(repoDir)) {
 						const entries = fs.readdirSync(repoDir);
 						planFiles = entries
-							.filter((file) => file.endsWith("__plan.md") && !file.endsWith("__plan-prompt.md"))
+							.filter(isApprovedRepoPlanFilename)
 							.map((file) => {
 								const slug = file.slice(0, -"__plan.md".length);
 								const fullPath = path.join(repoDir, file);
@@ -270,6 +276,10 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 	registerMfPlanSubagentTool(pi, controller);
 	registerExitPlanModeTool(pi, controller);
 
+	// Deliberately not context_with_system (pi 0.87.0): its result is sent
+	// verbatim, so a filtering mistake could drop pi's prompt and tool declarations.
+	// Keep injection in before_agent_start, filtering in context, and durable
+	// omissions in agent_before_settle so pi continues to own prompt/tool state.
 	pi.on("context", controller.onContext);
 	pi.on("before_agent_start", controller.onBeforeAgentStart);
 	pi.on("agent_start", controller.onAgentStart);
@@ -277,6 +287,7 @@ export default function mfPlanExtension(pi: ExtensionAPI): void {
 	pi.on("message_update", controller.onMessageUpdate);
 	pi.on("tool_execution_start", controller.onToolExecutionStart);
 	pi.on("message_end", controller.onMessageEnd);
+	pi.on("agent_before_settle", controller.onAgentBeforeSettle);
 	pi.on("agent_settled", controller.onAgentSettled);
 	pi.on("session_start", controller.onSessionStart);
 	pi.on("session_shutdown", controller.onSessionShutdown);

package/src/moa/fanoutWiring.ts

@@ -2,7 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import type { AgentConfig } from "../agents/discovery.ts";
 import type { CancelRun, CancelSession } from "../runtime/cancelRun.ts";
-import { getResultOutput, isFailedResult, type SingleResult } from "../runtime/results.ts";
+import { getResultOutput, isFailedResult, statusDetail, type SingleResult } from "../runtime/results.ts";
 import { runParallelAgentsWithModels, type ModelParallelAgentTask } from "../runtime/runner.ts";
 import type { ModelRef } from "../shared/modelRefs.ts";
 import type { MoaProgressWidget } from "../ui/moaProgressWidget.ts";
@@ -55,7 +55,7 @@ export async function runWidgetFanout(options: WidgetFanoutOptions): Promise<Sin
 					if (observed) observed.state = "cancelled";
 				} else if (isFailedResult(result)) {
 					run.settle(index, "error");
-					widget.update(widgetIndex, "error", getResultOutput(result).slice(0, 80));
+					widget.update(widgetIndex, "error", statusDetail(getResultOutput(result)));
 					if (observed) observed.state = "error";
 				} else {
 					run.settle(index, "done");

package/src/moa/verification.ts

@@ -24,13 +24,13 @@
  * by hand.
  */
 
-import { CONFIG_DIR_NAME, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import { loadMoaConfig } from "../config/settings.ts";
 import { installShippedAgents, shippedAgentsDir, withAuthoritativeMoaAgents } from "../agents/authoritative.ts";
 import { discoverAgents } from "../agents/discovery.ts";
-import { readRepoPlanFile, saveRepoPlanFile } from "../planning/planFile.ts";
+import { readRepoPlanFile, repoPlanDisplayPath, saveRepoPlanFile } from "../planning/planFile.ts";
 import { CancelRun, type CancelSession } from "../runtime/cancelRun.ts";
 import { formatMutationWarning, MutationTripwire } from "../runtime/mutationTripwire.ts";
 import { getFinalOutput, getResultOutput, isFailedResult, type SingleResult } from "../runtime/results.ts";
@@ -762,7 +762,7 @@ export async function runImplementationVerification(
 				: outcome.output;
 			try {
 				saveRepoPlanFile(verificationOutput, ctx.cwd, host.getPlanRepoSlug()!, "verification");
-				verificationReportPath = `${CONFIG_DIR_NAME}/mf-plan/${host.getPlanRepoSlug()!}__verification.md`;
+				verificationReportPath = repoPlanDisplayPath(host.getPlanRepoSlug()!, "verification");
 			} catch {
 				// Persisting the report is best-effort; verification proceeds regardless.
 			}
@@ -861,14 +861,14 @@ export async function runImplementationVerification(
 					// Only point at the checklist file when one is actually on disk;
 					// criteria can come from the handoff alone.
 					criteriaFilePath: readRepoPlanFile(ctx.cwd, repoPlanSlug, "criteria")
-						? `${CONFIG_DIR_NAME}/mf-plan/${repoPlanSlug}__criteria.md`
+						? repoPlanDisplayPath(repoPlanSlug, "criteria")
 						: undefined,
 				}),
 				ctx.cwd,
 				repoPlanSlug,
 				"verification-handoff",
 			);
-			handoffPath = `${CONFIG_DIR_NAME}/mf-plan/${repoPlanSlug}__verification-handoff.md`;
+			handoffPath = repoPlanDisplayPath(repoPlanSlug, "verification-handoff");
 		} catch {
 			// Persisting the handoff is best-effort; the exhaustion notification still fires.
 		}

package/src/planning/contextEdits.ts

@@ -0,0 +1,62 @@
+import type { ContextEditEntryDraft } from "@earendil-works/pi-coding-agent";
+
+import { PLAN_MODE_CONTEXT_TYPE, VERIFICATION_PENDING_CONTEXT_TYPE } from "./tools/shared.ts";
+
+/** Structural entry shape containing only fields read while scanning a branch. */
+export interface ScannedEntry {
+	id?: string;
+	type: string;
+	customType?: string;
+	message?: { role?: string; content?: unknown };
+	targetId?: string;
+	replacement?: unknown;
+}
+
+export function isPlanModeInstructionText(content: unknown): boolean {
+	const isInstruction = (text: string): boolean =>
+		text.startsWith("[PLAN MODE ACTIVE]") || text.startsWith("[PLAN MODE RE-ENTRY]");
+	if (typeof content === "string") return isInstruction(content);
+	if (!Array.isArray(content)) return false;
+	return content.some((part) =>
+		part !== null
+		&& typeof part === "object"
+		&& "type" in part
+		&& part.type === "text"
+		&& "text" in part
+		&& typeof part.text === "string"
+		&& isInstruction(part.text));
+}
+
+export function isPlanInstructionEntry(entry: ScannedEntry): boolean {
+	if (entry.type === "custom_message") return entry.customType === PLAN_MODE_CONTEXT_TYPE;
+	if (entry.type !== "message" || entry.message?.role !== "user") return false;
+	// The one-shot mf-plan-exit reminder remains governed by the per-request
+	// context filter; only reusable plan-mode instructions are omitted durably.
+	return isPlanModeInstructionText(entry.message.content);
+}
+
+export function isVerificationPendingEntry(entry: ScannedEntry): boolean {
+	return entry.type === "custom_message" && entry.customType === VERIFICATION_PENDING_CONTEXT_TYPE;
+}
+
+export function collectOmissionDrafts(
+	entries: readonly ScannedEntry[],
+	predicate: (entry: ScannedEntry) => boolean,
+	alreadyOmitted: ReadonlySet<string>,
+): ContextEditEntryDraft[] {
+	const omitted = new Set(alreadyOmitted);
+	for (const entry of entries) {
+		if (entry.type === "context_edit" && entry.replacement === null && typeof entry.targetId === "string") {
+			omitted.add(entry.targetId);
+		}
+	}
+	return entries.flatMap((entry): ContextEditEntryDraft[] => {
+		if (typeof entry.id !== "string" || omitted.has(entry.id) || !predicate(entry)) return [];
+		return [{ type: "context_edit", targetId: entry.id, replacement: null }];
+	});
+}
+
+export function buildVerificationPendingMessage(planFilePath: string | undefined): string {
+	const target = planFilePath ? ` for ${planFilePath}` : "";
+	return `The implementation turn for the approved plan${target} has finished. Independent read-only verification is pending and runs out of band. Treat the implementation as unverified until the verifier reports.`;
+}

package/src/planning/planFile.ts

@@ -131,21 +131,38 @@ export function slugifyPlanName(text: string): string {
 	return trySlugifyPlanName(text) ?? generateWordSlug();
 }
 
-/** Fallback slug when LLM summarization is unavailable. */
-export function fallbackPlanName(): string {
-	return generateWordSlug();
+export type RepoPlanFileKind = "plan-prompt" | "plan" | "spec" | "verification" | "criteria" | "verification-handoff";
+
+function repoPlanSuffix(kind: RepoPlanFileKind): string {
+	return `__${kind}`;
 }
 
-export type RepoPlanFileKind = "plan-prompt" | "plan" | "verification" | "criteria" | "verification-handoff";
+export function isApprovedRepoPlanFilename(file: string): boolean {
+	return file.endsWith("__plan.md");
+}
 
-function repoPlanSuffix(kind: RepoPlanFileKind): string {
-	// `__verification` and `__criteria` never collide with the `/mf-plan-implement`
-	// scan, which matches `__plan.md` while excluding `__plan-prompt.md`.
-	if (kind === "plan-prompt") return "__plan-prompt";
-	if (kind === "verification") return "__verification";
-	if (kind === "criteria") return "__criteria";
-	if (kind === "verification-handoff") return "__verification-handoff";
-	return "__plan";
+export function repoPlanDisplayPath(baseSlug: string, kind: RepoPlanFileKind): string {
+	if (!isValidPlanSlug(baseSlug)) throw new Error("Invalid repository plan slug");
+	return `${CONFIG_DIR_NAME}/mf-plan/${baseSlug}${repoPlanSuffix(kind)}.md`;
+}
+
+export function nextFreeRepoPlanSlug(repoCwd: string, baseSlug: string, kind: RepoPlanFileKind): string {
+	if (!isValidPlanSlug(baseSlug)) throw new Error("Invalid repository plan slug");
+	const planDir = getRepoPlanDirectory(repoCwd);
+	if (!fs.existsSync(path.join(planDir, `${baseSlug}${repoPlanSuffix(kind)}.md`))) return baseSlug;
+
+	for (let suffix = 2; suffix <= 20; suffix++) {
+		const suffixText = `-${suffix}`;
+		const trimmedBase = baseSlug
+			.slice(0, MAX_PLAN_SLUG_LENGTH - suffixText.length)
+			.replace(/-+$/g, "");
+		const candidate = `${trimmedBase}${suffixText}`;
+		if (
+			isValidPlanSlug(candidate)
+			&& !fs.existsSync(path.join(planDir, `${candidate}${repoPlanSuffix(kind)}.md`))
+		) return candidate;
+	}
+	return generateWordSlug();
 }
 
 /** Ensure `<CONFIG_DIR_NAME>/mf-plan/` exists in the given repo directory. */
@@ -159,7 +176,7 @@ export function getRepoPlanDirectory(repoCwd: string): string {
 	return planDir;
 }
 
-/** Save content to `<CONFIG_DIR_NAME>/mf-plan/<slug>__plan-prompt.md` or `<slug>__plan.md`. Returns the file path. */
+/** Save content to `<CONFIG_DIR_NAME>/mf-plan/<slug>__<kind>.md` for the given kind. Returns the file path. */
 export function saveRepoPlanFile(
 	content: string,
 	repoCwd: string,

package/src/planning/planMode.ts

@@ -1,7 +1,8 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { Message, TextContent } from "@earendil-works/pi-ai";
+import type { Message } from "@earendil-works/pi-ai";
 import { Key } from "@earendil-works/pi-tui";
 import type {
+	AgentBeforeSettleEvent,
 	AgentSettledEvent,
 	AgentStartEvent,
 	ExtensionAPI,
@@ -9,6 +10,7 @@ import type {
 	MessageEndEvent,
 	MessageStartEvent,
 	MessageUpdateEvent,
+	SessionBoundaryDraft,
 	ThemeColor,
 	ToolExecutionStartEvent,
 } from "@earendil-works/pi-coding-agent";
@@ -39,10 +41,18 @@ import { MoaProgressWidget } from "../ui/moaProgressWidget.ts";
 import { showObserveOverlay, type ObserveSession } from "../ui/observeOverlay.ts";
 import { planNamingOverlay, withWorkingOverlay } from "../ui/workingOverlay.ts";
 import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTracker, isAskUserQuestionInstalled } from "./askUserQuestion.ts";
+import {
+	buildVerificationPendingMessage,
+	collectOmissionDrafts,
+	isPlanInstructionEntry,
+	isPlanModeInstructionText,
+	isVerificationPendingEntry,
+	type ScannedEntry,
+} from "./contextEdits.ts";
 import { buildPlanModeExitInstructions, buildPlanModeInstructions, buildPlanModeReentryInstructions } from "./instructions.ts";
 import { latestPlanModeStateEntry, PlanModeStatePersistence, validateToolLoadoutSnapshot } from "./modeState.ts";
 import { getPlan, getPlanSlug, isValidPlanSlug, resetPlanSlug, saveRepoPlanFile, setPlanSlug, slugifyPlanName } from "./planFile.ts";
-import { PLAN_EXIT_CONTEXT_TYPE, PLAN_MODE_CONTEXT_TYPE, PLAN_MODE_CUSTOM_TOOLS, PLAN_MODE_READ_ONLY_TOOLS, PLAN_ONLY_REGISTERED_TOOLS } from "./tools/shared.ts";
+import { PLAN_EXIT_CONTEXT_TYPE, PLAN_MODE_CONTEXT_TYPE, PLAN_MODE_CUSTOM_TOOLS, PLAN_MODE_READ_ONLY_TOOLS, PLAN_ONLY_REGISTERED_TOOLS, VERIFICATION_PENDING_CONTEXT_TYPE } from "./tools/shared.ts";
 
 /** Trailing chars of the implementer report kept for the verifier's evidence. */
 const IMPLEMENTATION_REPORT_MAX_CHARS = 8000;
@@ -86,6 +96,17 @@ function extractAssistantText(content: unknown): string {
 	return "";
 }
 
+// Existing tests and stale post-reload contexts may not expose getBranch;
+// boundary handlers should become inert rather than throw in that case.
+function readBranchEntries(ctx: ExtensionContext): readonly ScannedEntry[] {
+	try {
+		const manager = ctx.sessionManager as { getBranch?: () => readonly ScannedEntry[] };
+		return typeof manager.getBranch === "function" ? manager.getBranch() : [];
+	} catch {
+		return [];
+	}
+}
+
 export function createPlanModeController(pi: ExtensionAPI) {
 	let planModeEnabled = false;
 	let toolsBeforePlanMode: string[] | undefined;
@@ -99,6 +120,8 @@ export function createPlanModeController(pi: ExtensionAPI) {
 	let activeRunMoaInfo: MfPlanInfo | undefined;
 	let implementationHandoff: ImplementationHandoff | undefined;
 	let implementationPending = false;
+	let verificationInFlight = false;
+	const omittedEntryIds = new Set<string>();
 	let lastImplementationStopReason: string | undefined;
 	// The implementer's final assistant text, captured while pending so the
 	// verifier can be handed the implementer's own (untrusted) report. Capped to
@@ -548,6 +571,63 @@ export function createPlanModeController(pi: ExtensionAPI) {
 				activeProgressWidget?.updateRoleTranscript("Implement", implementationMessages);
 			}
 		},
+		onAgentBeforeSettle: (event: AgentBeforeSettleEvent, ctx: ExtensionContext) => {
+			try {
+				const branch = readBranchEntries(ctx);
+				const persistedOmissions = new Set(
+					branch
+						.filter((entry) => entry.type === "context_edit" && entry.replacement === null && typeof entry.targetId === "string")
+						.map((entry) => entry.targetId as string),
+				);
+				// A different extension can invalidate the combined boundary proposal.
+				// Forget locally proposed edits that did not reach the branch so they are
+				// retried rather than suppressed for the rest of this process.
+				for (const id of omittedEntryIds) {
+					if (!persistedOmissions.has(id)) omittedEntryIds.delete(id);
+				}
+				const drafts: SessionBoundaryDraft[] = [];
+
+				// Persist plan-instruction omissions after plan mode exits. This is
+				// additive to onContext's per-request filter and repairs older sessions.
+				if (!planModeEnabled) {
+					drafts.push(...collectOmissionDrafts(branch, isPlanInstructionEntry, omittedEntryIds));
+				}
+				if (!verificationInFlight) {
+					drafts.push(...collectOmissionDrafts(branch, isVerificationPendingEntry, omittedEntryIds));
+				}
+
+				const stopReason = lastImplementationStopReason;
+				// KEEP IN LOCKSTEP with onAgentSettled's verification branch below.
+				// exit_plan_mode marks implementation pending before the follow-up has
+				// run, so implementationTurns distinguishes that planning boundary.
+				const verificationWillDispatch = implementationPending
+					&& implementationTurns > 0
+					&& event.context.pendingMessages.length === 0
+					&& event.outcome !== "aborted"
+					&& event.outcome !== "error"
+					&& !implementationTurnFailed(stopReason)
+					&& stopReason !== "aborted"
+					&& implementationHandoff !== undefined
+					&& (implementationHandoff.verifier ?? loadMoaConfig().verifier) !== undefined;
+				if (verificationWillDispatch) {
+					drafts.push({
+						type: "custom_message",
+						customType: VERIFICATION_PENDING_CONTEXT_TYPE,
+						content: buildVerificationPendingMessage(implementationHandoff?.planFilePath),
+						display: false,
+					});
+				}
+
+				if (drafts.length === 0) return undefined;
+				for (const draft of drafts) {
+					if (draft.type === "context_edit") omittedEntryIds.add(draft.targetId);
+				}
+				return { entries: [...event.entries, ...drafts] };
+			} catch {
+				// A thrown boundary handler could reject every proposed entry.
+				return undefined;
+			}
+		},
 		onAgentSettled: (_event: AgentSettledEvent, ctx: ExtensionContext) => {
 			updateStatus(ctx);
 			if (!implementationPending) return;
@@ -595,10 +675,13 @@ export function createPlanModeController(pi: ExtensionAPI) {
 			// explicit guard is required before the verification branch.
 			if (stopReason === "aborted") return;
 			if (!implementationHandoff) return;
+			// KEEP IN LOCKSTEP with verificationWillDispatch in onAgentBeforeSettle.
 			const verifier = implementationHandoff.verifier ?? loadMoaConfig().verifier;
 			if (verifier) {
+				verificationInFlight = true;
 				void runImplementationVerification(ctx, moaRunHost, { ...implementationHandoff, verifier }, report)
-					.catch(reportFlowFailure("Verification"));
+					.catch(reportFlowFailure("Verification"))
+					.finally(() => { verificationInFlight = false; });
 			}
 		},
 		onContext: async (event: { messages: AgentMessage[] }) => {
@@ -607,9 +690,7 @@ export function createPlanModeController(pi: ExtensionAPI) {
 				const msg = message as AgentMessage & { customType?: string };
 				if (msg.customType === PLAN_MODE_CONTEXT_TYPE || msg.customType === PLAN_EXIT_CONTEXT_TYPE) return false;
 				if (msg.role !== "user") return true;
-				if (typeof msg.content === "string") return !msg.content.startsWith("[PLAN MODE ACTIVE]") && !msg.content.startsWith("[PLAN MODE RE-ENTRY]");
-				if (Array.isArray(msg.content)) return !msg.content.some((part) => part.type === "text" && ((part as TextContent).text?.startsWith("[PLAN MODE ACTIVE]") || (part as TextContent).text?.startsWith("[PLAN MODE RE-ENTRY]")));
-				return true;
+				return !isPlanModeInstructionText(msg.content);
 			}) };
 		},
 		onBeforeAgentStart: async () => {
@@ -641,6 +722,8 @@ export function createPlanModeController(pi: ExtensionAPI) {
 			activeCancelSession = undefined;
 			activeObserveSession = undefined;
 			implementationHandoff = undefined;
+			verificationInFlight = false;
+			omittedEntryIds.clear();
 			footerError = undefined;
 			lastRenderedFooter = undefined;
 			lastFooterCtx = undefined;
@@ -680,6 +763,13 @@ export function createPlanModeController(pi: ExtensionAPI) {
 			} else {
 				deactivatePlanOnlyTools();
 			}
+			try {
+				if (collectOmissionDrafts(readBranchEntries(ctx), isVerificationPendingEntry, new Set()).length > 0) {
+					ctx.ui.notify("The previous session ended before plan verification finished — the last implementation is unverified. Run /mf-plan-implement to verify it.", "warning");
+				}
+			} catch {
+				// A stale session-start context cannot be notified safely.
+			}
 			updateStatus(ctx);
 			startFooterTicker(ctx);
 			if (ctx.mode === "tui" && typeof ctx.ui.onTerminalInput === "function") {
@@ -694,6 +784,8 @@ export function createPlanModeController(pi: ExtensionAPI) {
 		},
 		onSessionShutdown: (_event: { reason: string }) => {
 			implementationPending = false;
+			verificationInFlight = false;
+			omittedEntryIds.clear();
 			lastImplementationStopReason = undefined;
 			lastImplementationReport = undefined;
 			resetImplementationTranscript();

package/src/planning/tools/shared.ts

@@ -17,3 +17,4 @@ export const PLAN_ONLY_REGISTERED_TOOLS = ["write_plan", "exit_plan_mode", "mf_p
 export const PLAN_SUBAGENT_NAMES = new Set(["moa-explore", "mf-plan"]);
 export const PLAN_MODE_CONTEXT_TYPE = "mf-plan-context";
 export const PLAN_EXIT_CONTEXT_TYPE = "mf-plan-exit";
+export const VERIFICATION_PENDING_CONTEXT_TYPE = "mf-plan-verification-pending";

package/src/runtime/results.ts

@@ -92,6 +92,24 @@ export function getResultOutput(result: { exitCode: number; stopReason?: string;
 	return getFinalOutput(result.messages) || "(no output)";
 }
 
+/**
+ * Longest failure message kept for a status row. Generous enough that a
+ * provider's JSON error payload survives whole for a progress table to wrap
+ * across several lines, bounded so a multi-KB stderr dump cannot crowd out the
+ * table it renders in.
+ */
+const MAX_STATUS_DETAIL_CHARS = 500;
+
+/**
+ * Collapse an agent failure into one bounded line for a progress row. Runs of
+ * whitespace — newlines included — are flattened because the row is laid out as
+ * a single line before its surface wraps it to the available width.
+ */
+export function statusDetail(output: string): string {
+	const collapsed = output.replace(/\s+/g, " ").trim();
+	return collapsed.length <= MAX_STATUS_DETAIL_CHARS ? collapsed : `${collapsed.slice(0, MAX_STATUS_DETAIL_CHARS - 1)}…`;
+}
+
 export function truncateOutput(output: string): string {
 	const maxBytes = 50 * 1024;
 	const bytes = Buffer.from(output, "utf8");