@henryqw/pi-pr 4.0.5 → 4.0.7

package/README.md

@@ -70,7 +70,7 @@ Each footer entry is one linked `PR #number` plus one plain-language status: `N
 | Base update required or merge conflict | Update from the base branch's current target when the tree is clean and local HEAD equals the PR head. |
 | GitHub Actions job failed | Run the CI fix workflow when the same local prerequisite holds. |
 | External check or commit status failed | Show `CI failed` as a no-action blocker. |
-| Changes requested or unresolved review threads | Run the package comment sweep when the same local prerequisite holds. |
+| Changes requested or unresolved review threads | Start or resume the package comment sweep when the same local prerequisite holds. |
 | No-action state | Report the state without taking action. |
 | Merge-ready pull request | Ask for final confirmation, recheck fresh state, and squash-merge if confirmed. |
 
@@ -90,6 +90,10 @@ The creation workflow repeats destination, remote OID, PR, and configuration che
 
 Each helper workflow receives a random run ID and its first action. The run stays bound to one session, canonical worktree, route, and fresh authority. Helper calls from another run, session, worktree, or route fail.
 
+For comment sweeps, `/pr` checks the package recovery file without changing it. It selects `start` when recovery is absent. It selects `resume` only when valid recovery matches the fresh route authority. Invalid recovery stays unchanged and blocks dispatch with its path and reason.
+
+Direct skill or `pi_pr_*` tool calls cannot create route authority. Run `/pr` to reserve a fresh route.
+
 Only one helper run can exist at a time. Most runs expire when the agent settles. A create or branch-update conflict stays available for one user-guided continuation, then expires after that continuation settles. Session replacement and shutdown forget the run without aborting or cleaning a pending merge.
 
 After a `/pr` create workflow settles, the extension waits for a refresh that finds a configured current PR. It then prefixes the Herdr workspace label with `#<number> • `.
@@ -129,17 +133,17 @@ The sweep runs existing non-destructive checks on the clean committed `HEAD` bef
 
 ### Refresh
 
-The footer and widget load at session start. A directory outside a Git worktree stays silent and does not start polling. The UI shows `PR · status unavailable` for other discovery failures and reports only a generic error.
+The footer and widget load once at session start. A directory outside a Git worktree stays silent. The UI shows `PR · status unavailable` for other discovery failures and reports only a generic error.
 
-They refresh after local commits, PR creation, pushes, and each dispatched workflow settles. During creation, intermediate refreshes wait until the workflow settles. They also refresh after any successful delegated task settles. Active Git worktrees poll every 30 seconds. Polling updates presentation only and may be stale.
+They refresh after local commits, PR creation, pushes, and each dispatched workflow settles. During creation, intermediate refreshes wait until the workflow settles. They also refresh after any successful delegated task settles. There is no periodic presentation refresh, so external changes may leave the footer and widget stale indefinitely. `/pr` reads fresh state before routing or acting and remains authoritative.
 
-The create widget stays hidden until the local branch has a commit beyond its creation point. `/pr` replaces any hint with routing feedback while it selects a route. The feedback clears before route interaction. A dispatched workflow keeps the widget hidden until the agent settles. Direct and no-action routes refresh it after completion. A failed command restores the prior hint and schedules a refresh.
+The create widget stays hidden until the local branch has a commit beyond its creation point. `/pr` replaces any hint with routing feedback while it selects a route. The feedback clears before route interaction. A dispatched workflow keeps the widget hidden until the agent settles. Direct and no-action routes refresh it after completion. A failed command restores the prior hint and schedules a refresh, except when fresh lookup hits the GitHub API quota: it shows the sanitized message `GitHub API rate limit exhausted; retry after GitHub resets it` and does not immediately retry.
 
 Presentation uses route priority, so draft appears before running CI. `/pr` reads fresh state before routing or merging. The command is authoritative for actions.
 
 ### Session identity
 
-The extension records one configured PR identity in the Pi session. It stores only the PR URL, number, host, head identity, and configured target identity. It does not store lifecycle, CI, review, readiness, or base state. Repeated polling does not add duplicate entries, and no repository cache file is created.
+The extension records one configured PR identity in the Pi session. It stores only the PR URL, number, host, head identity, and configured target identity. It does not store lifecycle, CI, review, readiness, or base state. Event-driven refreshes do not add duplicate entries, and no repository cache file is created.
 
 Normal discovery always runs first. If the configured remote ref was deleted, the footer and `/pr` may reload the exact observed PR URL. The current host, repository, branch, remote, ref, and local HEAD must still match the observation. Repository names use case-insensitive GitHub matching.
 
@@ -149,7 +153,7 @@ The GitHub response must match the observed URL, host, repository, head ref, hea
 
 - `/pr` accepts creation syntax only as a leading `--base BRANCH`, followed by optional creation guidance. It does not open a browser.
 - It does not run `/done` or `/sweep`.
-- Polling does not auto-triage comments or start a workflow. The package comment sweep runs only when an explicit `/pr` selects it.
+- Presentation refreshes do not auto-triage comments or start a workflow. The package comment sweep starts or resumes only when an explicit `/pr` selects it.
 - It does not enable auto-merge or add a merge queue.
 - It does not rebase the local branch, overwrite concurrent remote updates, delete branches, or clean up worktrees. Creation uses exact leases plus ancestry checks; an empty lease is only an atomic absence check.
 - Creation, discovery, and comment-sweep pushes require one unambiguous push URL for the configured destination.

package/extensions/pr-command.ts

@@ -17,15 +17,17 @@ import {
 
 export type WorkflowNextStep = Extract<NextStep, "create" | "update-branch" | "sweep" | "fix-ci">;
 
-const WORKFLOWS: Record<WorkflowNextStep, { command: string; action: string }> = {
-	create: { command: "skill:pi-pr-create", action: "prepare" },
-	"update-branch": { command: "skill:pi-pr-update-branch", action: "merge" },
-	sweep: { command: "skill:pi-pr-comment-sweep", action: "start" },
-	"fix-ci": { command: "skill:pi-pr-fix-ci", action: "collect" },
+const WORKFLOWS: Record<WorkflowNextStep, { command: string }> = {
+	create: { command: "skill:pi-pr-create" },
+	"update-branch": { command: "skill:pi-pr-update-branch" },
+	sweep: { command: "skill:pi-pr-comment-sweep" },
+	"fix-ci": { command: "skill:pi-pr-fix-ci" },
 };
 export type WorkflowReservation =
 	| { route: "create"; target: PullRequestTarget; base?: string }
 	| { route: Exclude<WorkflowNextStep, "create">; pullRequest: CurrentPullRequest };
+export type WorkflowLaunchAction = "prepare" | "merge" | "start" | "resume" | "collect";
+export type WorkflowReservationResult = { runId: string; action: WorkflowLaunchAction };
 
 type PrCommandPi = Pick<ExtensionAPI, "exec" | "getCommands" | "sendUserMessage">;
 export type PrCommandInvocation = ((nextStep: NextStep) => void) & {
@@ -42,7 +44,7 @@ export type WorkflowPromptIdentity = Readonly<{
 	route: WorkflowNextStep;
 	skill: string;
 	runId: string;
-	action: string;
+	action: WorkflowLaunchAction;
 }>;
 
 export type PrCommandDependencies = {
@@ -52,7 +54,7 @@ export type PrCommandDependencies = {
 		reservation: WorkflowReservation,
 		ctx: ExtensionCommandContext,
 		invocation?: PrCommandInvocation,
-	) => Promise<string>;
+	) => Promise<WorkflowReservationResult>;
 	markWorkflowPromptQueued?: (identity: WorkflowPromptIdentity, queued: boolean) => void;
 	releaseWorkflow?: (runId: string, invocation?: PrCommandInvocation) => void;
 };
@@ -96,7 +98,7 @@ function packageWorkflowCommand(pi: PrCommandPi, route: WorkflowNextStep) {
 		candidate.sourceInfo.origin === "package"
 	);
 	if (!command) throw new Error(`${workflow.command} failed: bundled workflow is unavailable`);
-	return { command, action: workflow.action };
+	return command;
 }
 
 async function dispatchWorkflow(
@@ -113,10 +115,11 @@ async function dispatchWorkflow(
 	const workflow = packageWorkflowCommand(pi, route);
 	let runId: string | undefined;
 	try {
-		runId = await reserve(reservation, ctx, invocation);
+		const reserved = await reserve(reservation, ctx, invocation);
+		runId = reserved.runId;
 		invocation?.assertCurrent();
 		const queued = !ctx.isIdle();
-		const identity = { route, skill: workflow.command.name, runId, action: workflow.action };
+		const identity = { route, skill: workflow.name, runId, action: reserved.action };
 		markPromptQueued(identity, queued);
 		const options = queued
 			? { deliverAs: "followUp" as const, expandPromptTemplates: true }

package/extensions/pr-comment-sweep.ts

@@ -231,6 +231,16 @@ function sameLinkage(expected: SweepAuthority, current: SweepAuthority, remoteHe
 		current.target.remoteOid === remoteHead;
 }
 
+function recoveryMatchesRouteAuthority(state: SweepState, suppliedAuthority: SweepAuthority): boolean {
+	const permittedHeads = new Set<string>();
+	if (state.attempts.push.state !== "applied") permittedHeads.add(state.original.lease);
+	if (
+		(state.attempts.push.state === "attempting" || state.attempts.push.state === "unknown" || state.attempts.push.state === "applied") &&
+		state.publicationHead
+	) permittedHeads.add(state.publicationHead);
+	return [...permittedHeads].some((head) => sameLinkage(state.authority, suppliedAuthority, head));
+}
+
 function feedbackMatchesAuthority(snapshot: FeedbackSnapshot, authority: SweepAuthority, head: string): boolean {
 	const current = snapshot.pullRequest;
 	return current.id === authority.id && current.number === authority.number && current.url === authority.url &&
@@ -575,6 +585,17 @@ export class PullRequestCommentSweep {
 		return (await this.location()).path;
 	}
 
+	async recoveryLaunchAction(): Promise<"start" | "resume"> {
+		if (!this.suppliedAuthority) throw new Error("Comment sweep recovery inspection requires route authority");
+		const location = await this.location();
+		const state = await this.loadIfPresent(location);
+		if (!state) return "start";
+		if (!recoveryMatchesRouteAuthority(state, this.suppliedAuthority)) {
+			throw new Error(`Comment sweep recovery is preserved at ${location.path}: recovery does not match freshly discovered route authority`);
+		}
+		return "resume";
+	}
+
 	private async loadState(location: Awaited<ReturnType<PullRequestCommentSweep["location"]>>): Promise<SweepState> {
 		const raw = await readTextFileBounded(location.path, SWEEP_RECOVERY_MAX_BYTES, { signal: this.signal });
 		let value: unknown;
@@ -789,17 +810,10 @@ export class PullRequestCommentSweep {
 	async resume(): Promise<SweepStatus> {
 		return await withWorktreeLock(this.cwd, async () => {
 			if (!this.suppliedAuthority) throw new Error("Comment sweep resume requires route authority");
-			const suppliedAuthority = this.suppliedAuthority;
 			const location = await this.location();
 			const state = await this.loadState(location);
-			const permittedHeads = new Set<string>();
-			if (state.attempts.push.state !== "applied") permittedHeads.add(state.original.lease);
-			if (
-				(state.attempts.push.state === "attempting" || state.attempts.push.state === "unknown" || state.attempts.push.state === "applied") &&
-				state.publicationHead
-			) permittedHeads.add(state.publicationHead);
-			if (![...permittedHeads].some((head) => sameLinkage(state.authority, suppliedAuthority, head))) {
-				throw new Error("Comment sweep recovery does not match supplied route authority");
+			if (!recoveryMatchesRouteAuthority(state, this.suppliedAuthority)) {
+				throw new Error(`Comment sweep recovery is preserved at ${location.path}: recovery does not match supplied route authority`);
 			}
 			await this.reconcile(state);
 			state.attempts.resolutions = state.attempts.resolutions.filter(({ state: attempt }) => attempt !== "blocked");

package/extensions/pr-github.ts

@@ -66,6 +66,13 @@ export class PullRequestLoadError extends Error {
 	}
 }
 
+export class GitHubRateLimitError extends PullRequestLoadError {
+	constructor() {
+		super("GitHub API rate limit exhausted; retry after GitHub resets it");
+		this.name = "GitHubRateLimitError";
+	}
+}
+
 export type PullRequestRef = {
 	repository: string;
 	ref: string;
@@ -369,7 +376,11 @@ async function invoke(
 	return parseCommandOutput(result, action);
 }
 
-function commandFailure(action: string, result: CommandOutput): never {
+function commandFailure(action: string, result: CommandOutput, command?: string): never {
+	if (
+		command === "gh" && !result.killed && result.code !== 0 &&
+		result.stderr.includes("GraphQL: API rate limit exceeded")
+	) throw new GitHubRateLimitError();
 	fail(action, result.killed ? "command was cancelled" : `exit code ${result.code}`);
 }
 
@@ -381,7 +392,7 @@ async function execute(
 	args: string[],
 ): Promise<CommandOutput> {
 	const result = await invoke(pi, context, action, command, args);
-	if (result.killed || result.code !== 0) commandFailure(action, result);
+	if (result.killed || result.code !== 0) commandFailure(action, result, command);
 	return result;
 }
 
@@ -1265,6 +1276,7 @@ async function readRemoteAuthority(
 		) fail("Read fetch repository", "fetch and push repositories do not match");
 		return { fetchSource: pushUrl.fetchSource, repository: pushRepository };
 	} catch (error) {
+		if (error instanceof GitHubRateLimitError) throw error;
 		if (!strict && error instanceof PullRequestLoadError) return null;
 		throw error;
 	}

package/extensions/pr.ts

@@ -19,6 +19,7 @@ import {
 } from "./pr-command.ts";
 import { PullRequestCreator, type CreatePullRequestOptions } from "./pr-create.ts";
 import {
+	GitHubRateLimitError,
 	loadCurrentPullRequest,
 	parsePullRequestObservation,
 	pullRequestObservation,
@@ -37,7 +38,6 @@ import {
 } from "./pr-ui.ts";
 import { PullRequestBranchUpdater, type UpdateBranchOptions } from "./pr-update-branch.ts";
 
-const POLL_INTERVAL_MS = 30_000;
 const ROUTING_SPINNER_INTERVAL_MS = 80;
 const ROUTING_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const ROUTING_WIDGET_TEXT = "Checking pull request…";
@@ -140,7 +140,7 @@ const FixCiParameters = Type.Union([
 
 type UpdateBranchWorkflow = Pick<PullRequestBranchUpdater, "state" | "merge" | "continue" | "publish">;
 type CreateWorkflow = Pick<PullRequestCreator, "state" | "prepare" | "merge" | "continue" | "push" | "publish">;
-type SweepWorkflow = Pick<PullRequestCommentSweep, "start" | "resume" | "show" | "record" | "publish" | "refresh" | "resolve" | "finalize">;
+type SweepWorkflow = Pick<PullRequestCommentSweep, "recoveryLaunchAction" | "start" | "resume" | "show" | "record" | "publish" | "refresh" | "resolve" | "finalize">;
 type FixCiWorkflow = Pick<PullRequestCiFixer, "collect" | "publish">;
 
 type WorkflowContextBase = {
@@ -282,10 +282,9 @@ export default function pullRequestExtension(
 		return discovery;
 	};
 	let sessionGeneration = 0;
-	let timer: ReturnType<typeof setInterval> | undefined;
 	let active: AbortController | undefined;
 	let queued = false;
-	let refreshFailureReported = false;
+	let reportedRefreshFailure: "generic" | "quota" | undefined;
 	let displayEstablished = false;
 	let lastDiscovery: "configured" | "inferred" | "absent" | "blocked" | "inactive" | undefined;
 	let lastBlockedIssueKey: string | undefined;
@@ -338,7 +337,7 @@ export default function pullRequestExtension(
 						loadCurrentPullRequest: load,
 					}),
 				};
-				break;
+				return { runId, action: "merge" };
 			case "create":
 				workflowContext = {
 					...common,
@@ -351,9 +350,9 @@ export default function pullRequestExtension(
 						loadCurrentPullRequest: load,
 					}),
 				};
-				break;
-			case "sweep":
-				workflowContext = {
+				return { runId, action: "prepare" };
+			case "sweep": {
+				const selected: Extract<WorkflowContext, { route: "sweep" }> = {
 					...common,
 					route: "sweep",
 					workflow: createCommentSweep({
@@ -363,7 +362,17 @@ export default function pullRequestExtension(
 						loadCurrentPullRequest: load,
 					}),
 				};
-				break;
+				workflowContext = selected;
+				try {
+					const action = await selected.workflow.recoveryLaunchAction();
+					invocation.assertCurrent();
+					if (workflowContext !== selected) throw new Error("PR workflow session changed during recovery inspection");
+					return { runId, action };
+				} catch (error) {
+					clearWorkflow(selected);
+					throw error;
+				}
+			}
 			case "fix-ci":
 				workflowContext = {
 					...common,
@@ -375,9 +384,8 @@ export default function pullRequestExtension(
 						loadCurrentPullRequest: load,
 					}),
 				};
-				break;
+				return { runId, action: "collect" };
 		}
-		return common.runId;
 	};
 
 	const markWorkflowPromptQueued: NonNullable<PrCommandDependencies["markWorkflowPromptQueued"]> = (identity, queued) => {
@@ -404,7 +412,7 @@ export default function pullRequestExtension(
 	) => {
 		signal?.throwIfAborted();
 		const selected = workflowContext;
-		if (!selected) throw new Error("No PR workflow is active");
+		if (!selected) throw new Error("No PR workflow is active; run /pr to discover and reserve the current route");
 		if (selected.runId !== runId) throw new Error("PR workflow runId is wrong or stale");
 		if (selected.sessionGeneration !== sessionGeneration) throw new Error("PR workflow session is stale");
 		if (selected.route !== route) throw new Error(`PR workflow route is ${selected.route}, not ${route}`);
@@ -561,8 +569,6 @@ export default function pullRequestExtension(
 		discovery: Awaited<ReturnType<typeof loadCurrentPullRequest>>,
 	): void => {
 		if (discovery.kind === "inactive") {
-			if (timer !== undefined) clearInterval(timer);
-			timer = undefined;
 			displayEstablished = true;
 			lastDiscovery = "inactive";
 			displayedWidget = undefined;
@@ -600,7 +606,7 @@ export default function pullRequestExtension(
 		context = undefined;
 		observation = undefined;
 		queued = false;
-		refreshFailureReported = false;
+		reportedRefreshFailure = undefined;
 		displayEstablished = false;
 		lastDiscovery = undefined;
 		lastBlockedIssueKey = undefined;
@@ -612,18 +618,22 @@ export default function pullRequestExtension(
 		activeInvocations.clear();
 		stopRoutingSpinner();
 		widgetKind = "presentation";
-		if (timer !== undefined) clearInterval(timer);
-		timer = undefined;
 		active?.abort();
 		active = undefined;
 	};
 
-	const reportRefreshFailure = (): void => {
+	const reportRefreshFailure = (error: unknown): void => {
 		const ctx = context;
-		if (!ctx || refreshFailureReported) return;
-		refreshFailureReported = true;
+		const category = error instanceof GitHubRateLimitError ? "quota" : "generic";
+		if (!ctx || reportedRefreshFailure === category || reportedRefreshFailure === "quota") return;
+		reportedRefreshFailure = category;
 		try {
-			ctx.ui.notify("PR status refresh failed: status unavailable", "error");
+			ctx.ui.notify(
+				error instanceof GitHubRateLimitError
+					? error.message
+					: "PR status refresh failed: status unavailable",
+				"error",
+			);
 		} catch {
 			console.error("PR status refresh failed and could not be reported");
 		}
@@ -655,7 +665,7 @@ export default function pullRequestExtension(
 			try {
 				discovery = await load(pi, loadContext);
 				if (controller.signal.aborted || sessionGeneration !== generation) return;
-			} catch {
+			} catch (error) {
 				// Keep an established footer. A refresh failure must not leave a stale action hint.
 				if (!controller.signal.aborted && sessionGeneration === generation) {
 					displayedWidget = undefined;
@@ -665,13 +675,13 @@ export default function pullRequestExtension(
 						ctx.ui.setStatus(UI_KEY, formatPrFooter(unavailable, ctx.ui.theme));
 						displayEstablished = true;
 					}
-					reportRefreshFailure();
+					reportRefreshFailure(error);
 				}
 				return;
 			}
 			if (controller.signal.aborted || sessionGeneration !== generation) return;
 			render(ctx, discovery);
-			refreshFailureReported = false;
+			reportedRefreshFailure = undefined;
 
 			const pullRequest = discovery.kind === "current" ? discovery.pullRequest : undefined;
 			if (pendingWorkspaceRename && pullRequest?.target.provenance === "configured") {
@@ -716,14 +726,10 @@ export default function pullRequestExtension(
 
 	pi.on("session_start", async (_event, ctx) => {
 		stop();
-		const generation = sessionGeneration;
 		observation = latestObservation(ctx);
 		if (!ctx.hasUI) return;
 		context = ctx;
 		await refresh();
-		if (sessionGeneration === generation && lastDiscovery !== "inactive") {
-			timer = setInterval(refreshInBackground, POLL_INTERVAL_MS);
-		}
 	});
 
 	pi.on("session_shutdown", stop);
@@ -805,8 +811,14 @@ export default function pullRequestExtension(
 				if (sessionGeneration === generation) {
 					cancelRefresh();
 					activeInvocations.delete(invocation);
-					reconcileWidget(ctx);
-					refreshInBackground();
+					if (error instanceof GitHubRateLimitError) {
+						displayedWidget = undefined;
+						reconcileWidget(ctx);
+						reportRefreshFailure(error);
+					} else {
+						reconcileWidget(ctx);
+						refreshInBackground();
+					}
 				}
 				throw error;
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-pr",
-  "version": "4.0.5",
+  "version": "4.0.7",
   "description": "Run /pr to safely discover or link the current pull request, then create, update, address feedback, fix CI, or merge when ready.",
   "keywords": [
     "pi-package",

package/skills/pi-pr-comment-sweep/SKILL.md

@@ -9,9 +9,10 @@ Use the package-owned comment-sweep workflow. It exposes these closed actions:
 `start`, `resume`, `show`, `record`, `publish`, `refresh`, `resolve`, and
 `finalize`.
 
-1. Call `start` for a fresh current-branch pull request. Call `resume` only for
-   saved work. Never replace or delete blocked recovery state by hand. See
-   [Sweep recovery](references/recovery.md).
+1. Use the `start` or `resume` action supplied by `/pr`. `/pr` checks saved work
+   and chooses the action. Do not change it. Direct skill or tool calls cannot
+   create route authority; run `/pr` instead. Never replace or delete blocked
+   recovery state by hand. See [Sweep recovery](references/recovery.md).
 2. Use `show` for one feedback ID at a time. Inspect every conversation
    comment, review, thread, and thread comment. Follow
    [Thread triage](references/thread-triage.md).

package/skills/pi-pr-comment-sweep/references/recovery.md

@@ -10,10 +10,14 @@ The file is private, bounded to 1 MiB, and replaced atomically. It contains the
 frozen PR authority, original head and lease, complete feedback, exact ledger,
 owned paths, and mutation attempts.
 
-Use `resume` when this file exists. Resume checks the canonical worktree, local
-changes, PR linkage, and remote head. It reconciles an attempted push or thread
-resolution before issuing a new epoch and run ID. Calls from the old run then
-fail.
+Run `/pr` to enter recovery. After fresh route discovery, `/pr` checks this file
+without changing it. It selects `start` when the file is absent. It selects
+`resume` only when valid recovery matches the fresh route authority.
+
+Resume checks the canonical worktree, local changes, PR linkage, and remote
+head again under its lock. It reconciles an attempted push or thread resolution
+before issuing a new epoch and run ID. Calls from the old run then fail. Direct
+skill or tool calls cannot create route authority.
 
 A completed post-publish `refresh` stores the new complete snapshot before any
 replacement ledger. Recovery keeps that snapshot in `refresh-pending`, with its
@@ -22,7 +26,9 @@ Use `show` with the resumed guard to inspect each frozen item. Then use `record`
 without `ownedPaths` to supply exact complete coverage for that snapshot.
 Resolution and finalization remain blocked until this record succeeds.
 
-Malformed or oversized recovery is preserved and blocks the workflow. Never
-repair, move, replace, or delete it automatically. An unknown mutation is never
-replayed. If reconciliation cannot prove its exact result, stop and report the
-state path and blocker.
+Malformed, oversized, obsolete, wrong-worktree, or route-mismatched recovery is
+preserved and blocks dispatch. Never repair, move, replace, or delete it
+automatically. Report the state path and exact blocker.
+
+An unknown mutation is never replayed. If reconciliation cannot prove its exact
+result, stop and report the state path and blocker.