pi-plans 0.3.1 → 0.3.3

package/README.md

@@ -119,10 +119,10 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 | VCC compact | Active planning/execution compaction uses deterministic, no-LLM VCC-style summaries when Pi core emits manual `/compact`, threshold, or overflow events. Summaries use five bracket sections plus a brief transcript, keep a smart recent tail, support `keep:N`, and write VCC details/stats without adding `/pi-vcc` commands. |
 | Visible Refiner overlay | Delegated reviewer/criticizer subagents surface as a named public overlay in the TUI — one `Reviewer`/`Criticizer` panel with per-lane tool progress, full streaming transcript with follow-bottom scroll, Tab-pane focus, retention until the user presses `Esc` after completion, and clean cancelled/timed-out vs completed states. `reviewers: 3` renders three equal-height panes inside the same overlay |
 | Tracked execution | Checklist injected each turn; `[DONE:VC-xxx]` markers drive completion; implementation items report progress with `[I-xxx:implemented]` / `[I-xxx:validating]` markers; the bottom status bar shows lifecycle, `x/y` progress, elapsed time, and input/output token usage in real time |
-| Goal-wait continuation | While execution is active, a turn that ends with unpassed VCs gets an automatic light follow-up (`🔁 goal-wait` in the status bar) — the worker keeps going, and rounds blocked on an external event poll via the taught `waiting for` backoff instead of stopping. Guard rails: 3 consecutive no-progress rounds, or 6 waiting rounds, pause the continuation (`⏸ goal-wait paused (reason)` in the status bar); any new input or `/plans-execute` re-kicks it, and `/plans-stop` always terminates |
+| Goal-wait continuation | In TUI/RPC, only a fully settled agent with unpassed VCs and no pending input or compaction gets one hidden wake carrying the latest checklist. Tool turns never queue reminders or consume guard rounds. The status bar shows progress; 3 no-progress cycles or 6 waiting cycles pause continuation. User interruption and final model errors also pause it. Only genuine user input or `/plans-execute` resumes; extension messages cannot. Print/JSON single-shot sessions track progress without automatic wakes. `/plans-stop` terminates execution |
 | Execution handoff | The accepted plan resumes in the current session model; no separate model selection is performed. |
 | Execution-phase compaction | Pi core owns scheduling; pi-plans maps the active plan path, current `I-###`, implementation IDs, and remaining `VC-###` checklist into the VCC sections. The old current-I proactive trigger and model-generated summary path are removed. |
-| Planning-phase compaction | During `run.status=planning` with no active execution, pi-plans maps active run, artifact directory, latest plan path from session entries, and observed current-I markers into the VCC sections. Without an active planning run, compaction returns to Pi core. |
+| Planning-phase compaction | During `run.status=planning` with no active execution, pi-plans maps active run, artifact directory, latest plan path from session entries, and observed current-I markers into the VCC sections. Without an active planning run, compaction returns to Pi core. Additionally, creating a new run (`plans start-run`) proactively requests one pre-plan VCC compaction and resumes planning with a hidden message (default on; `prePlanCompact:false` disables). |
 | Efficient executor prompt | Each turn, the executor is steered by a fused rule set — Marcos Hernanz's AGENTS.md principles × Ponytail minimalism: layered growth, simplest implementation, long-term architecture (no stopgaps), library discipline — so plans finish in fewer tokens and fewer detours |
 | Write guard | `edit`/`write` blocked outside planning artifacts while a run is active |
 
@@ -130,14 +130,15 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 
 | Tool / Command | Purpose |
 |---|---|
-| `plans` | State CLI: `init`, `show`, `set-language`, `set-artifact-root`, `set-refs-root`, `set-role`, `start-run`, `set-status`, `record-decision`, `record-ref`, `record-subagent` |
+| `plans` | State CLI: `init`, `show`, `set-language`, `set-artifact-root`, `set-refs-root`, `set-role`, `start-run`, `set-status`, `record-decision`, `record-ref`, `record-subagent`, `record-checkpoint` (state-machine-validated workflow transitions) |
 | `ask_choice` | Numbered choice prompt; `autoComplete: false` for the merged accept/execute question and external-state questions |
 | `refine` | Reviewer/criticizer round via standalone read-only subagents (`--mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` for both roles when the workspace has the code graph enabled); `target: "plan"` (default) reviews the plan, `target: "implementation"` reviews the implemented worktree against the plan; delegated TUI runs show one `Reviewer`/`Criticizer` overlay (78% width × 78% height, top-center, ≥72 cols) with per-lane transcript, follow-bottom scroll, Tab focus, and retention until `Esc`; `reviewers: 3` renders three equal-height panes; enforces role/model confirmation gates |
 | `analyze_refs` | plan-with-refs reference analysis: one independent read-only subagent per downloaded reference (cwd = the ref directory), reusing the reviewer role gates and the concurrent overlay (titled `Refs`); batches of at most 3 lanes run sequentially; returns structured per-reference sections for `REF_ANALYSIS.md` |
 | `execute_plan` | Execution handoff: re-confirms with the user and enters extension-managed execution mode |
 | `/plans` | Show config, active run, and execution progress |
 | `/config-pi-plans` | Re-ask workspace defaults for language, artifact root, refs root, code graph, reviewer mode/model, and criticizer mode/model |
-| `/plans-execute [plan.md]` | Manual execution handoff (defaults to highest `PLAN_vN.md`) |
+| `/resume-plans` | Resume the repository's working plan in the CURRENT session across restarts: unfinished planning (pending question + answered decisions), reviewing (round/lane state, successful outputs reused), execution (approval digest + HEAD + verified VCs), and implementation review (termination condition + round count). The unfinished active run wins; otherwise a unique candidate resumes directly and multiple candidates get a chooser. Linked worktrees share candidates; a cross-worktree resume confirms, copies artifacts without overwriting, and resets approval + VC validity (the termination condition survives, rounds restart at 0). An unchanged plan digest with a changed HEAD keeps the authorization but re-verifies old VCs first. Busy sessions and runs actively owned by a live process only notify — no queueing, no takeover. Interactive (TUI/RPC) only |
+| `/plans-execute [plan.md]` | Resume a paused active execution without losing verified progress; otherwise enter the explicit execution handoff (defaults to highest `PLAN_vN.md`) |
 | `/update-plan [plan.md] [reason…]` | Interrupt-and-refine: stops execution (if any), returns the run to planning, and directs the agent to revise the plan into `PLAN_vN+1.md` while preserving verified work |
 | `/plans-autocomplete-stop` | Stop the current run's Auto-complete mode and return later planning questions to normal interaction |
 | `/plans-stop` | Stop execution mode |
@@ -153,7 +154,8 @@ Pi core remains the owner of compaction scheduling: manual `/compact`, threshold
 - **Tail policy.** The default keep is one recent user turn; smart keep may retain more turns when the tail is still small. Explicit `keep:N` is honored, while no-anchor and oversized-tail cases use a deterministic token-budget cut that avoids starting retained context with an orphan tool result.
 - **Manual matrix.** Plain `/compact` and `/compact keep:N` compact and show stats without continuing. `/compact <text>` and `/compact keep:N <text>` compact, then send the text once as the follow-up prompt. Internal pi-plans compaction markers are never reused as user follow-up prompts.
 - **Fallbacks and stats.** Unsafe manual/threshold cuts cancel with a warning; overflow or retrying unsafe cuts return control to Pi core. Successful VCC compactions notify with kept-tail and summarized-message stats. Threshold/overflow compactions may queue one hidden continuation only when the running Pi version still needs it and `continueAfterThresholdCompact` is enabled.
-- **Repo-private config.** Defaults are scaffolded in `.git/pi_plans/pi-vcc-config.json` under the resolved git common dir: `overrideDefaultCompaction:true`, `smartKeepTail:true`, `continueAfterThresholdCompact:true`, `debug:false`. Global pi-vcc config and `PI_VCC_CONFIG_PATH` are intentionally ignored.
+- **Pre-plan compaction.** When `plans start-run` creates a new planning run, pi-plans proactively requests one VCC compaction (internal hint `pi-plans planning pre-plan compact`) right after the run is created and before the first planning question, then resumes the planning turn with a hidden message — so each new plan starts on a lean context (LLM reasoning degrades with longer input). Small sessions, already-compacted sessions, and failures skip silently and still resume. `prePlanCompact:false` in the repo-private config restores the old behavior.
+- **Repo-private config.** Defaults are scaffolded in `.git/pi_plans/pi-vcc-config.json` under the resolved git common dir: `overrideDefaultCompaction:true`, `smartKeepTail:true`, `continueAfterThresholdCompact:true`, `prePlanCompact:true`, `debug:false`. Global pi-vcc config and `PI_VCC_CONFIG_PATH` are intentionally ignored.
 
 ## Visible Refiner overlay
 

package/index.ts

@@ -20,9 +20,11 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
 	consumePlanningCompactionResumeGuard,
+	consumePrePlanCompactPending,
 	drainExecutionFlush,
 	executionContextMessage,
 	filterExecutionResumeMessages,
+	filterGoalWaitMessages,
 	filterPlanningResumeMessages,
 	getExecution,
 	handleExecutionBeforeCompact,
@@ -35,12 +37,12 @@ import {
 	noteCompactionEnded,
 	noteCompactionStarted,
 	PLANNING_PLAN_WRITTEN_CUSTOM_TYPE,
+	PLANNING_PREPLAN_COMPACT_HINT,
+	sendPrePlanCompactResume,
 	registerExecutionTurnHandlers,
 	refreshPlanningCompactionCooldown,
 	requestPlanningCompaction,
 	restoreFromSession,
-	resetGoalWaitTurnFlags,
-	resumeGoalWaitIfPaused,
 	stopExecution,
 	updateStatusWidget,
 	shouldTriggerPlanningCompaction,
@@ -67,9 +69,12 @@ import {
 } from "./src/code-graph/commands.ts";
 import { latestPlanVersion, nextPlanVersionPath } from "./src/plan.ts";
 import { configPiPlansCommand } from "./src/config-command.ts";
+import { resumePlansCommand } from "./src/resume-command.ts";
 import { getRun, loadConfig, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.ts";
+import { boundRunId, resolveActiveRun, restoreRunBindingFromSession } from "./src/run-context.ts";
+import { applyPlanWritten, mutateCheckpoint, planIdentityOf } from "./src/workflow-state.ts";
 import { registerAskChoiceTool } from "./tools/ask-choice.ts";
-import { executeHandoff, registerExecutePlanTool } from "./tools/execute-plan.ts";
+import { executeCommand, registerExecutePlanTool } from "./tools/execute-plan.ts";
 import { registerPlansTool } from "./tools/plans.ts";
 import { registerRefineTool } from "./tools/refine.ts";
 import { registerAnalyzeRefsTool } from "./tools/analyze-refs.ts";
@@ -108,7 +113,7 @@ function extensionStalenessLine(): string {
 
 function hasActivePlanningWorkflow(ctx: Parameters<typeof updateStatusWidget>[0]): boolean {
 	if (getExecution()) return true;
-	const active = readActive(ctx.cwd);
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 	if (!active) return false;
 	const status = getRun(ctx.cwd, active.run_id)?.status;
 	return status === "planning" || status === "accepted" || status === "executing";
@@ -167,12 +172,17 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		if (getExecution()) return;
 		const rawPath = String((event.input as { path?: string }).path ?? "");
 		if (!rawPath) return;
-		const reason = planningWriteBlockReason({ workdir: ctx.cwd, toolName: event.toolName, rawPath });
+		const reason = planningWriteBlockReason({
+			workdir: ctx.cwd,
+			toolName: event.toolName,
+			rawPath,
+			activeRunId: boundRunId(ctx.sessionManager, ctx.cwd),
+		});
 		if (reason) return { block: true, reason };
 		// Allowed write: if it lands exactly on the run's latest plan file, drop a
 		// marker entry so planning-phase compaction can anchor its cut point there.
 		if (event.toolName === "write" || event.toolName === "edit") {
-			const active = readActive(ctx.cwd);
+			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 			if (active) {
 				const latest = latestPlanVersion(active.artifact_dir);
 				if (latest && path.resolve(ctx.cwd, rawPath) === path.resolve(ctx.cwd, latest.path)) {
@@ -187,6 +197,63 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		return;
 	});
 
+	// I-003: a successful write/edit that lands on the run's latest plan
+	// records the plan identity in the run checkpoint (post-execution, so the
+	// digest covers the NEW file bytes — unlike the pre-execution marker above).
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.isError) return;
+		if (getExecution()) return;
+		if (event.toolName !== "write" && event.toolName !== "edit") return;
+		const rawPath = String((event.input as { path?: string }).path ?? "");
+		if (!rawPath) return;
+		const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
+		if (!active) return;
+		const latest = latestPlanVersion(active.artifact_dir);
+		if (!latest) return;
+		if (path.resolve(ctx.cwd, rawPath.replace(/^@/, "")) !== path.resolve(ctx.cwd, latest.path)) return;
+		try {
+			const identity = planIdentityOf(path.resolve(ctx.cwd, latest.path), latest.version);
+			mutateCheckpoint(ctx.cwd, active.run_id, (cp) => applyPlanWritten(cp, identity));
+		} catch {
+			/* best-effort; the model can also call plans record-checkpoint explicitly */
+		}
+	});
+
+	// Pre-plan compaction: right after `plans start-run` creates a new planning
+	// run, trigger one VCC compaction (PLANNING_PREPLAN_COMPACT_HINT routes it
+	// through the planning session_before_compact path) so the new plan starts
+	// on a lean context. ctx.compact() aborts the current agent operation
+	// first, so it must fire here — after the tool result is appended, never
+	// inside the tool execute stack. Pi's manual compaction never continues the
+	// aborted turn, so resume planning exactly once on success AND failure.
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.isError) return;
+		if (event.toolName !== "plans") return;
+		if (!consumePrePlanCompactPending(ctx)) return;
+		if (typeof ctx.compact !== "function") {
+			sendPrePlanCompactResume(pi);
+			return;
+		}
+		let resumed = false;
+		const resumeOnce = () => {
+			if (resumed) return;
+			resumed = true;
+			sendPrePlanCompactResume(pi);
+		};
+		ctx.compact({
+			customInstructions: PLANNING_PREPLAN_COMPACT_HINT,
+			onComplete: () => resumeOnce(),
+			onError: () => {
+				try {
+					ctx.ui?.notify?.("pi-plans: pre-plan compaction skipped; continuing planning.", "info");
+				} catch {
+					/* notify is best-effort */
+				}
+				resumeOnce();
+			},
+		});
+	});
+
 	// Bidirectional code-graph reminder hook: separate from the planning guard
 	// above (which early-returns during execution). Fires only when the graph
 	// is enabled and an execution is active. Reminders are best-effort notifies.
@@ -215,7 +282,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 
 	pi.on("context", (event) => {
 		const filteredExecution = filterExecutionResumeMessages(event.messages as Array<{ customType?: string }>);
-		const messages = filterPlanningResumeMessages(filteredExecution);
+		const messages = filterGoalWaitMessages(filterPlanningResumeMessages(filteredExecution));
 		if (messages.length !== event.messages.length) {
 			return { messages };
 		}
@@ -238,21 +305,11 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		noteCompactionEnded(ctx, event.customInstructions);
 	});
 
-	// Flush points for deferred execution-loop writes: primary drain when the
-	// agent run fully settles, backstop drain at the next run's start (covers
-	// continuation paths that might not emit agent_settled), plus the forced
-	// synchronous flush inside stop/complete.
-	pi.on("agent_settled", async (_event, ctx) => {
-		drainExecutionFlush(pi, ctx);
-	});
-
 	// -----------------------------------------------------------------------
 	// Execution loop: inject remaining checklist each turn, track markers.
 	// -----------------------------------------------------------------------
 	pi.on("before_agent_start", async (_event, ctx) => {
 		drainExecutionFlush(pi, ctx);
-		resetGoalWaitTurnFlags();
-		resumeGoalWaitIfPaused(pi, ctx);
 		const content = executionContextMessage(ctx);
 		if (!content) {
 			if (!getExecution() && shouldTriggerPlanningCompaction(ctx)) {
@@ -344,7 +401,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		description: "Show pi-plans state: config, active run, and execution progress",
 		handler: async (_args, ctx) => {
 			const lines: string[] = [];
-			const active = readActive(ctx.cwd);
+			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 			const run = active ? getRun(ctx.cwd, active.run_id) : null;
 			if (!run) {
 				lines.push("No active planning run.");
@@ -388,7 +445,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		description: "Execute handoff: enter tracked execution mode for an accepted plan",
 		handler: async (args, ctx) => {
 			const planPath = args.trim() || undefined;
-			const outcome = await executeHandoff(ctx, planPath);
+			const outcome = await executeCommand(ctx, planPath);
 			ctx.ui.notify(outcome.message, outcome.status === "error" ? "error" : "info");
 		},
 	});
@@ -415,7 +472,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 				}
 			}
 
-			const active = readActive(ctx.cwd);
+			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 			const execution = getExecution();
 			disableAutoComplete(ctx, "plan update");
 
@@ -512,10 +569,18 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("resume-plans", {
+		description:
+			"Resume the working plan in this repository: unfinished planning / reviewing / execution / implementation review, across sessions and linked worktrees, in the current session.",
+		handler: async (_args, ctx) => {
+			await resumePlansCommand(pi, ctx, baseDir);
+		},
+	});
+
 	pi.registerCommand("plans-abandon", {
 		description: "Abandon the active planning run (lifts the read-only guard; artifacts are kept)",
 		handler: async (_args, ctx) => {
-			const active = readActive(ctx.cwd);
+			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 			if (!active) {
 				ctx.ui.notify("No active planning run.", "info");
 				return;
@@ -543,8 +608,21 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// -----------------------------------------------------------------------
 	// Session lifecycle
 	// -----------------------------------------------------------------------
+	pi.on("session_tree", async (_event, ctx) => {
+		await restoreFromSession(pi, ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[2]);
+		restoreRunBindingFromSession(
+			ctx.sessionManager,
+			ctx.cwd,
+			ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreRunBindingFromSession>[2],
+		);
+	});
 	pi.on("session_start", async (_event, ctx) => {
-		await restoreFromSession(pi, ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreFromSession>[2]);
+		await restoreFromSession(pi, ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[2]);
 		restoreAutoCompleteFromSession(ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreAutoCompleteFromSession>[1]);
+		restoreRunBindingFromSession(
+			ctx.sessionManager,
+			ctx.cwd,
+			ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreRunBindingFromSession>[2],
+		);
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-plans",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Human-in-the-loop planning extension for the Pi coding agent: researched, refined Markdown plans before any code changes.",
   "license": "MIT",
   "type": "module",

package/references/pi-planning-workflow.md

@@ -12,7 +12,7 @@ This skill set is written for the Pi coding agent's documented behavior:
 - `refine` spawns read-only Pi subagents (`pi --mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` for both roles when workspace `graph_enabled` is true) with isolated context; delegated Reviewer/Criticizer runs show a standalone aggregate overlay titled `Reviewer` or `Criticizer` (78% × 78% top-center, ≥72 cols, no input row), stream assistant/thinking/tool events into per-lane transcripts with follow-bottom scroll, dismiss on `Esc` (close-only — the refiner child keeps running and its result still flows back as tool output), replace any retained finished overlay when a new round begins, and return conclusions to the main session as tool output; `analyze_refs` spawns one read-only subagent per downloaded reference (cwd = that ref's directory) reusing the reviewer role gates, shows the same overlay titled `Refs` in batches of at most 3 lanes, and returns structured per-reference sections for `REF_ANALYSIS.md`;
 - when graph mode is enabled, graph-aware `read`/`edit` overrides are active for indexed source files: `read` returns a capped function digest (≤50 lines, synthetic anonymous entries folded) by default — drill in via `offset/limit` or `code_graph get-function`, and `full: true` is the only whole-file exit (small/zero-function files return full text; safety truncation matches native read); `write`/`edit` stage DB-first mutations until materialized via the `code_graph` tool's `apply` action (same planning/accepted gate as /apply-graph; refused for read-only refiner subagents via the PI_PLANS_REFINER marker; returns a per-file report with counts and a post-apply drift summary, and never changes run status); unexpected fallbacks (`not indexed` / `runtime unavailable` / `config read failed`) are marked at the top of the result while flag-off fallbacks stay unmarked;
 - the execution loop is extension-managed: remaining verifier items are injected each turn, implementation items emit `[I-###:current]`/`[I-###:implemented|validating]`, and `[DONE:VC-xxx]` markers are tracked with a bottom status bar;
-- execution and planning compaction keep Pi's SessionManager as the history owner; during active pi-plans runs, `session_before_compact` uses a deterministic no-LLM VCC-style summary with `[Session Goal]`, `[Files And Changes]`, `[Commits]`, `[Outstanding Context]`, `[User Preferences]`, and a ranked brief transcript; Pi core owns manual `/compact`, threshold, and overflow scheduling, while pi-plans handles smart tail keep, `keep:N`, stats, and phase-specific run/plan/current-I/checklist context;
+- execution and planning compaction keep Pi's SessionManager as the history owner; during active pi-plans runs, `session_before_compact` uses a deterministic no-LLM VCC-style summary with `[Session Goal]`, `[Files And Changes]`, `[Commits]`, `[Outstanding Context]`, `[User Preferences]`, and a ranked brief transcript; Pi core owns manual `/compact`, threshold, and overflow scheduling, while pi-plans handles smart tail keep, `keep:N`, stats, and phase-specific run/plan/current-I/checklist context; in addition, creating a new planning run (`plans start-run`) proactively requests one pre-plan VCC compaction before the first planning question and resumes the planning turn with a hidden message (default on, `prePlanCompact` in `pi-vcc-config.json`);
 
 ## Planning Boundary
 
@@ -137,6 +137,27 @@ When the user picks `✓ Accept PLAN_vN and execute it now` in the merged questi
 
 If the user declines, stay in planning (or stop, per their choice). Never start implementation without the approved handoff.
 
+### Execution Goal-Wait
+
+In TUI/RPC, automatic goal-wait is evaluated only at `agent_settled`, after
+Pi has finished natural tool continuation, retries, and compaction. The
+extension rechecks that the same execution is active and incomplete, the
+session is idle, and neither pending input nor compaction owns continuation.
+Each eligible settled cycle can send at most one hidden custom message with
+the current execution rules and remaining VC checklist. Tool `turn_end`
+events only update progress; they never prequeue goal-wait reminders.
+
+No-progress and literal `waiting for` counters advance only on eligible
+settled cycles. Real marker progress resets both; thresholds remain 3 and 6.
+User interruption and final model errors also pause continuation. Genuine
+interactive/RPC user input or `/plans-execute` can resume a paused active
+execution without losing verified VCs; extension input cannot unpause it.
+New-plan handoffs and the `execute_plan` tool still require explicit approval.
+Completion, stop, and session replacement invalidate the extension's wake
+identity without clearing user or other-extension queues. Print/JSON
+single-shot sessions keep VC tracking and completion but never auto-wake;
+use RPC for persistent headless execution.
+
 ### Post-Execution Continuation
 
 When execution completes in an interactive session, the completion message attaches a goal-running continuation block and triggers a new agent turn so the model can enter the implementation-review loop immediately. The interactive-only trigger keeps headless sessions silent (no unconsented subagent cost). The same behavior applies on both completion call sites (the normal `turn_end` completion and the `restoreFromSession` recovery path).
@@ -149,6 +170,12 @@ The agent then asks one `ask_choice` question for the termination condition of t
 - Round audit trail: `decisions.jsonl`, `subagents.jsonl`, and `pi-plans-ameliorate` entries (one at goal start, then one per round) carry `currentRound` for post-hoc verification.
 - Headless sessions skip the prompt entirely; no `pi-plans-ameliorate` entry is appended.
 
+`refine` records each round and lane outcome durably (successful outputs are persisted to run-state files before the tool result returns) and accepts `resumeRoundId` to resume an interrupted round lane-by-lane: completed lanes are reused from their persisted outputs and never re-run; a round id is never reused across plan versions.
+
+## Resuming (`/resume-plans`)
+
+After a restart or in a fresh session, `/resume-plans` (interactive only) restores the repository's working plan in the current session: the unfinished active run wins; otherwise a unique candidate resumes directly and multiple candidates get a chooser. It resumes unfinished planning (re-asks the pending question with the same `questionId`, never re-asks answered decisions), reviewing (resumes interrupted rounds via `refine resumeRoundId`, consolidates completed ones), execution (durable approval: unchanged plan digest keeps the authorization — a changed HEAD re-verifies old VCs first; legacy runs without checkpoints must re-approve), and the implementation-review loop (asks the termination condition only when it was never chosen). Linked worktrees share candidates; cross-worktree resumes confirm, copy artifacts without overwriting, reset approval and VC validity, and restart round counts. Record semantic boundaries with `plans record-checkpoint` (`plan-written`, `review-consolidated`, `implementation-review-configured`, `implementation-round-finished`, `completed` with evidence).
+
 `refine` accepts a `target` parameter (`"plan"` default, `"implementation"` for the post-execution loop). The implementation brief anchors findings to the plan's goals and acceptance criteria, explicitly assesses delivery maturity (MVP-only vs. long-term refinement: stopgaps, missing tests, technical debt, production readiness), and tags out-of-scope improvements as low severity.
 
 ## Red Flags

package/references/plan-artifact-template.md

@@ -72,6 +72,10 @@ Summarize the user's request in one paragraph.
 
 State anything the executor should know, including order of work, files to avoid, and verification commands. The merged accept/execute question still requires explicit user approval (ask_choice with `autoComplete: false`, then the `execute_plan` tool) and must never be auto-completed. Once approved, the extension-managed execution loop injects the remaining checklist every turn and completes when every `[DONE:VC-xxx]` marker has landed — keep this section concise enough to serve as the executor's brief.
 
+## Termination Recording (implementation review)
+
+When the post-execution implementation-review loop starts, the termination question is asked with `ask_choice` using `questionId: "termination-condition"` and persisted via `plans record-checkpoint` (`transition: "implementation-review-configured"`). Each disposed round records `implementation-round-finished`; the loop closes with `completed` plus evidence. These records make `/resume-plans` continue the loop with its original condition and round count.
+
 ## Revision Ledger
 
 - `PLAN_v1`: Initial plan from resolved questions and evidence.

package/references/state-and-config.md

@@ -92,6 +92,7 @@ Default values:
   "overrideDefaultCompaction": true,
   "smartKeepTail": true,
   "continueAfterThresholdCompact": true,
+  "prePlanCompact": true,
   "debug": false
 }
 ```
@@ -103,6 +104,7 @@ Rules:
 - `overrideDefaultCompaction:false` returns ordinary Pi manual/threshold/overflow compactions to Pi core. Explicit pi-plans internal compact hints can still use the VCC path.
 - `smartKeepTail:true` starts from the requested/default keep count and may retain more recent user turns when the retained tail remains within the safe token budget. Explicit `keep:N` is honored.
 - `continueAfterThresholdCompact:true` permits one hidden continuation after successful threshold/overflow compaction only on Pi versions that still need extension-driven resume behavior. Plain manual `/compact` never auto-continues, and `/compact <text>` sends the text once as the follow-up prompt.
+- `prePlanCompact:true` requests one VCC planning compaction (internal hint `pi-plans planning pre-plan compact`) from the `plans` `tool_result` hook right after `plans start-run` creates a new run, before the first planning question, and resumes the planning turn with one hidden message on success and failure alike. Small sessions, already-compacted sessions, and aborts skip silently with an info notice. The trigger is disabled while an execution is active. `prePlanCompact:false` restores the old behavior.
 - `debug:false` writes no diagnostics; `debug:true` writes a best-effort `/tmp/pi-vcc-debug.json` snapshot for local troubleshooting.
 
 ## Language Setting
@@ -182,3 +184,20 @@ One run directory per planning request: `<git-common-dir>/pi_plans/runs/<YYYYMMD
 `run.json` includes: run ID; skill name; original request; target workspace; artifact directory; language tag; status (`planning` → `accepted` → `executing` → `done`, with `stopped`/`abandoned` as exits); timestamps.
 
 `decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/criticizer/ref-analyst spawns. `refs.jsonl` records reference metadata via `plans` (`record-ref`).
+
+## Workflow Checkpoints (`/resume-plans`)
+
+Each run may carry a `checkpoint.json` — the durable, cross-session workflow state that `/resume-plans` restores in the current session. It records: logical `phase` (`planning | reviewing | executing | implementation-review | completed`), `nextAction`, the exact plan identity (path + version + SHA-256), pending/answered questions (stable `questionId`), review rounds with per-lane status and result-file references, execution approval evidence (plan digest, worktree, `git rev-parse HEAD` at approval, verified VC/I set, usage), the implementation-review termination condition and completed-round count, and ownership metadata. Full review outputs live in separate `reviews/` files; the checkpoint keeps only validated references.
+
+Rules:
+
+- Validation is explicit: unknown schema versions, malformed shapes, and unexpected keys are rejected; missing and corrupt checkpoints are distinct, and corrupt files are never silently overwritten.
+- Writes are atomic with monotonic revisions; writers may require ownership (token + generation) or an expected revision.
+- Model-driven boundaries (plan written, review consolidated, termination condition recorded, implementation round finished, completed) go through the whitelisted `plans record-checkpoint` action, which enforces state-machine preconditions — it cannot set execution approval, mark VCs passed, or forge terminal states.
+- `ask_choice` accepts `questionId`/`purpose`; a pending question is durable before the panel opens and the answer before it returns. When a crash leaves a question both answered (ledger) and pending (checkpoint), the answered entry wins.
+- On execution resume, an unchanged plan digest with a changed HEAD keeps the authorization but re-verifies previously verified VCs first; loading execution from a checkpoint writes an immediate session snapshot so session restore cannot clear it.
+- Cross-worktree resumes copy artifacts without overwriting, reset approval and VC validity, keep the termination condition, and restart completed-round counts at 0 for the target worktree.
+
+## Run Ownership
+
+A run may be held by at most one live owner (`owner.json`: host, pid, process start time via `ps -o lstart=`, session id, random process token, generation). Acquisition is an atomic exclusive create; takeovers require proof the previous owner is dead (process gone, or pid alive with a different start time — PID reuse). Foreign hosts, corrupt records, and unverifiable liveness are conservatively refused; `/resume-plans` never queues or interrupts. Sessions bind to the run they start/execute/resume (restored from `pi-plans-run-start` entries on the current branch), and attribution (tools, write guard, autocomplete, execution bookkeeping, code-graph apply gate) prefers the binding over the shared `active.json` pointer.

package/src/autocomplete.ts

@@ -2,6 +2,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getRun, readActive } from "./state.ts";
+import { resolveActiveRun } from "./run-context.ts";
 
 export const AUTOCOMPLETE_ENTRY = "pi-plans-autocomplete";
 const AUTOCOMPLETE_CONTINUE = "Continue the current planning workflow. Raise the next relevant question with ask_choice; do not stop after an auto-completed answer.";
@@ -32,7 +33,7 @@ function sessionState(ctx: ExtensionContext): AutoCompleteState | undefined {
 }
 
 function activePlanningRun(ctx: ExtensionContext): { runId: string } | null {
-	const active = readActive(ctx.cwd);
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 	if (!active) return null;
 	const run = getRun(ctx.cwd, active.run_id);
 	return run?.status === "planning" ? { runId: run.run_id } : null;

package/src/code-graph/commands.ts

@@ -19,7 +19,8 @@ import type { ParserBackend } from "./parser.ts";
 import type { Language } from "./types.ts";
 import { materialize, type MaterializeReport } from "./materialize.ts";
 import { generateSummaries, type CompletionHandle, type SummaryReport } from "./summary.ts";
-import { readActive, getRun, setRunStatus } from "../state.ts";
+import { readActive, getRun, setRunStatus, type ActiveInfo } from "../state.ts";
+import { boundRunId, resolveActiveRun } from "../run-context.ts";
 
 interface CommandContext {
 	cwd: string;
@@ -84,7 +85,15 @@ async function bootstrap(ctx: CommandContext, opts: { reindex?: boolean }): Prom
 	return { store, paths, parsers, runtimeStatus: status };
 }
 
-function activePlanningRun(workdir: string): ActiveInfo | null {
+function activePlanningRun(workdir: string, sessionRunId?: string | null): ActiveInfo | null {
+	// The session-bound run gates first: a planning run in THIS session must
+	// refuse apply even when the shared pointer moved to another run (I-002).
+	if (sessionRunId) {
+		const boundRun = getRun(workdir, sessionRunId);
+		if (boundRun && (boundRun.status === "planning" || boundRun.status === "accepted")) {
+			return { run_id: sessionRunId, run_dir: "", artifact_dir: boundRun.artifact_dir };
+		}
+	}
 	const active = readActive(workdir);
 	if (!active) return null;
 	const run = getRun(workdir, active.run_id);
@@ -189,8 +198,11 @@ export interface ApplyGraphCoreResult {
  * No notifications and no run-status side effects; callers own presentation
  * and lifecycle transitions.
  */
-export async function applyGraphCore(workdir: string, opts: { force?: boolean } = {}): Promise<ApplyGraphCoreResult> {
-	const planned = activePlanningRun(workdir);
+export async function applyGraphCore(
+	workdir: string,
+	opts: { force?: boolean; sessionRunId?: string | null } = {},
+): Promise<ApplyGraphCoreResult> {
+	const planned = activePlanningRun(workdir, opts.sessionRunId);
 	if (planned) {
 		return { refused: `code-graph apply refused: a planning run is currently planning or accepted (run ${planned.run_id}).` };
 	}
@@ -224,7 +236,10 @@ export async function applyGraphCommand(args: string, ctx: CommandContext): Prom
 		return;
 	}
 	const flags = parseCommandArgs(args).flags;
-	const core = await applyGraphCore(ctx.cwd, { force: flags.has("force") });
+	const core = await applyGraphCore(ctx.cwd, {
+		force: flags.has("force"),
+		sessionRunId: boundRunId(ctx.sessionManager, ctx.cwd),
+	});
 	if (core.refused) {
 		ctx.ui.notify(core.refused, "error");
 		return;
@@ -243,7 +258,7 @@ export async function applyGraphCommand(args: string, ctx: CommandContext): Prom
 		`code-graph apply: ${ok} ok, ${deleted} deleted, ${stale} stale, ${skipped} skipped-missing, ${errors} error`,
 		errors > 0 ? "error" : "info",
 	);
-	const active = readActive(ctx.cwd);
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 	if (active) setRunStatus(ctx.cwd, active.run_id, "executing");
 }
 

package/src/compaction.ts

@@ -14,6 +14,8 @@ export interface PiPlansVccSettings {
 	overrideDefaultCompaction: boolean;
 	smartKeepTail: boolean;
 	continueAfterThresholdCompact: boolean;
+	/** Pre-plan compaction: trigger a VCC compaction right after `plans start-run`. */
+	prePlanCompact: boolean;
 	debug: boolean;
 }
 
@@ -21,6 +23,7 @@ export const DEFAULT_VCC_SETTINGS: PiPlansVccSettings = {
 	overrideDefaultCompaction: true,
 	smartKeepTail: true,
 	continueAfterThresholdCompact: true,
+	prePlanCompact: true,
 	debug: false,
 };
 
@@ -34,9 +37,15 @@ export const MAX_CHARS_PER_TOKEN = 6;
 export const PI_SELF_RESUME_VERSION: readonly [number, number, number] = [0, 84, 4];
 export const PI_VCC_COMPACT_INSTRUCTION = "__pi_vcc__";
 
+/** Internal hint for the pre-plan compaction requested right after start-run
+ *  (tools/plans.ts marks pending; index.ts requests the compact action).
+ *  Single source of truth: also referenced by exec.ts and the tests. */
+export const PLANNING_PREPLAN_COMPACT_HINT = "pi-plans planning pre-plan compact";
+
 const INTERNAL_COMPACT_INSTRUCTIONS = new Set([
 	"pi-plans execution auto compact",
 	"pi-plans planning auto compact",
+	PLANNING_PREPLAN_COMPACT_HINT,
 ]);
 
 export function vccSettingsPath(stateRoot: string): string {
@@ -95,6 +104,7 @@ export function loadVccSettings(stateRoot: string): PiPlansVccSettings {
 		overrideDefaultCompaction: typeof parsed.overrideDefaultCompaction === "boolean" ? parsed.overrideDefaultCompaction : DEFAULT_VCC_SETTINGS.overrideDefaultCompaction,
 		smartKeepTail: typeof parsed.smartKeepTail === "boolean" ? parsed.smartKeepTail : DEFAULT_VCC_SETTINGS.smartKeepTail,
 		continueAfterThresholdCompact: typeof parsed.continueAfterThresholdCompact === "boolean" ? parsed.continueAfterThresholdCompact : DEFAULT_VCC_SETTINGS.continueAfterThresholdCompact,
+		prePlanCompact: typeof parsed.prePlanCompact === "boolean" ? parsed.prePlanCompact : DEFAULT_VCC_SETTINGS.prePlanCompact,
 		debug: typeof parsed.debug === "boolean" ? parsed.debug : DEFAULT_VCC_SETTINGS.debug,
 	};
 }

package/src/config-command.ts

@@ -349,6 +349,8 @@ export async function configPiPlansCommand(_args: string, ctx: ConfigCommandCont
 			return config;
 		});
 
+		// Display-only consumer (F-006): deliberately keeps the shared active
+		// pointer — the wizard summarizes repo state, not session attribution.
 		const active = readActive(workdir);
 		const lines = summarizeConfig(updated.config);
 		if (active) {