diffing 0.10.3 → 0.10.5

package/dist/github-attachments-Cf17YWp4.mjs

@@ -0,0 +1,351 @@
+import { d as getProjectStorageDir, w as toSafeRelativePath } from "./git-Czo96ymM.mjs";
+import { _ as isGithubDotCom, g as githubApiBase, m as ghHostnameArgs, o as detectGhCli, s as execWithInput, x as readGithubToken } from "./github-CEjtGd41.mjs";
+import { createHash } from "node:crypto";
+import { extname, join } from "node:path";
+import { readFile, stat } from "node:fs/promises";
+//#region src/lib/github-attachments.ts
+/**
+* Publish-time rewrite of local `/api/attachments/…` markdown into
+* repo-ACL-bound GitHub raw blob URLs (hidden orphan ref via Git Data API).
+*
+* Private repos / GHE: URLs inherit repository visibility. Never uses
+* release assets (always public) or cookie-based user-attachments upload.
+*/
+const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+const ALLOWED_EXT = new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".svg"
+]);
+/** Markdown image/link targets that point at local diffing attachments. */
+const LOCAL_ATTACHMENT_RE = /(?:!?\[[^\]]*\]\()(\/api\/attachments\/([^)\s]+))\)|(?:src=["'])(\/api\/attachments\/([^"'\s]+))["']/gi;
+/** Public web origin for markdown image URLs (not the REST API host). */
+function githubWebOrigin(host) {
+	if (isGithubDotCom(host)) return "https://github.com";
+	return (host.includes("://") ? host : `https://${host}`).replace(/\/$/, "");
+}
+/** Build a private-repo-safe raw content URL for a blob at a commit. */
+function githubRawBlobUrl(resolved, commitSha, treePath) {
+	const origin = githubWebOrigin(resolved.host);
+	const segments = treePath.split("/").map((s) => encodeURIComponent(s)).join("/");
+	return `${origin}/${resolved.owner}/${resolved.repo}/raw/${commitSha}/${segments}`;
+}
+function attachmentRefName(pullNumber) {
+	return `refs/diffing/attachments/pr-${pullNumber}`;
+}
+/**
+* Extract safe local attachment filenames from markdown. Rejects traversal,
+* absolute paths, and empty names.
+*/
+function extractLocalAttachmentRefs(markdown) {
+	const found = /* @__PURE__ */ new Map();
+	LOCAL_ATTACHMENT_RE.lastIndex = 0;
+	let match;
+	while ((match = LOCAL_ATTACHMENT_RE.exec(markdown)) !== null) {
+		const url = match[1] ?? match[3];
+		const filename = match[2] ?? match[4];
+		if (!url || !filename) continue;
+		const safe = sanitizeAttachmentFilename(filename);
+		if (!safe) continue;
+		found.set(url, {
+			url,
+			filename: safe
+		});
+	}
+	return [...found.values()];
+}
+/** Returns basename if safe; null if traversal / bad extension / weird chars. */
+function sanitizeAttachmentFilename(filename) {
+	let decoded = filename;
+	try {
+		decoded = decodeURIComponent(filename);
+	} catch {}
+	if (!decoded || decoded.includes("\0") || decoded.includes("/") || decoded.includes("\\")) return null;
+	if (decoded.includes("..") || decoded.startsWith(".") || decoded !== decoded.trim()) return null;
+	if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(decoded)) return null;
+	const ext = extname(decoded).toLowerCase();
+	if (!ALLOWED_EXT.has(ext)) return null;
+	return decoded;
+}
+function rewriteAttachmentUrls(markdown, urlMap) {
+	if (Object.keys(urlMap).length === 0) return markdown;
+	let out = markdown;
+	for (const [local, remote] of Object.entries(urlMap)) out = out.split(local).join(remote);
+	return out;
+}
+function attachmentsDir(custom) {
+	return custom ?? join(getProjectStorageDir(), "attachments");
+}
+async function loadAttachmentFile(dir, filename) {
+	const safeRel = toSafeRelativePath(filename, dir);
+	if (!safeRel || safeRel.includes("..") || safeRel.includes("/") || safeRel.includes("\\")) return {
+		bytes: Buffer.alloc(0),
+		error: `Refusing unsafe attachment path: ${filename}`
+	};
+	const absolute = join(dir, safeRel);
+	try {
+		const st = await stat(absolute);
+		if (!st.isFile()) return {
+			bytes: Buffer.alloc(0),
+			error: `Attachment is not a file: ${filename}`
+		};
+		if (st.size > 10485760) return {
+			bytes: Buffer.alloc(0),
+			error: `Attachment ${filename} exceeds ${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MB limit`
+		};
+		return { bytes: await readFile(absolute) };
+	} catch {
+		return {
+			bytes: Buffer.alloc(0),
+			error: `Missing local attachment: ${filename}`
+		};
+	}
+}
+async function planAttachmentUploads(markdownBodies, opts) {
+	const refs = /* @__PURE__ */ new Map();
+	for (const body of markdownBodies) for (const ref of extractLocalAttachmentRefs(body)) refs.set(ref.url, ref);
+	if (refs.size === 0) return { plans: [] };
+	const dir = attachmentsDir(opts?.attachmentsDir);
+	const plans = [];
+	const hashToTreePath = /* @__PURE__ */ new Map();
+	for (const ref of refs.values()) {
+		const loaded = await loadAttachmentFile(dir, ref.filename);
+		if (loaded.error) return {
+			plans: [],
+			error: loaded.error
+		};
+		const contentHash = createHash("sha256").update(loaded.bytes).digest("hex");
+		let treePath = hashToTreePath.get(contentHash);
+		if (!treePath) {
+			const ext = extname(ref.filename).toLowerCase() || ".bin";
+			treePath = `${contentHash.slice(0, 16)}${ext}`;
+			hashToTreePath.set(contentHash, treePath);
+		}
+		plans.push({
+			filename: ref.filename,
+			localUrl: ref.url,
+			bytes: loaded.bytes.length,
+			contentHash,
+			treePath
+		});
+	}
+	return { plans };
+}
+function contentsWriteHint(message) {
+	const lower = message.toLowerCase();
+	if (lower.includes("resource not accessible") || lower.includes("not found") || lower.includes("403") || lower.includes("forbidden") || lower.includes("permission") || lower.includes("scopes")) return `${message} — Image upload needs contents:write (re-auth \`gh\` with the repo scope, or use a token with Contents: Write).`;
+	return message;
+}
+async function createGhApiCaller(resolved) {
+	const gh = await detectGhCli();
+	if (gh.available && gh.authenticated) {
+		const caller = async (method, path, body) => {
+			const args = [
+				"api",
+				...ghHostnameArgs(resolved),
+				"--method",
+				method,
+				path,
+				"-H",
+				"Accept: application/vnd.github+json"
+			];
+			try {
+				let stdout;
+				if (body !== void 0) {
+					args.push("--input", "-");
+					({stdout} = await execWithInput("gh", args, JSON.stringify(body)));
+				} else ({stdout} = await execWithInput("gh", args, ""));
+				return {
+					ok: true,
+					status: 200,
+					json: stdout.trim() ? JSON.parse(stdout) : null,
+					text: stdout
+				};
+			} catch (err) {
+				const stdout = String(err?.stdout || "");
+				const stderr = String(err?.stderr || err?.message || "");
+				let json = null;
+				try {
+					json = stdout ? JSON.parse(stdout) : null;
+				} catch {}
+				return {
+					ok: false,
+					status: typeof err?.code === "number" ? err.code : 500,
+					json,
+					text: json?.message || stderr || stdout || "gh api failed"
+				};
+			}
+		};
+		return {
+			caller,
+			authSource: "gh"
+		};
+	}
+	const token = readGithubToken();
+	if (!token) return { error: "Cannot upload images: no `gh` CLI on $PATH (or not authenticated) and no $GITHUB_TOKEN. Run `gh auth login` or set $GITHUB_TOKEN." };
+	const base = githubApiBase(resolved.host);
+	const caller = async (method, path, body) => {
+		const res = await fetch(`${base}/${path.replace(/^\//, "")}`, {
+			method,
+			headers: {
+				Authorization: `Bearer ${token}`,
+				Accept: "application/vnd.github+json",
+				"X-GitHub-Api-Version": "2022-11-28",
+				"Content-Type": "application/json",
+				"User-Agent": "diffing-cli"
+			},
+			body: body !== void 0 ? JSON.stringify(body) : void 0,
+			signal: AbortSignal.timeout(45e3)
+		});
+		const text = await res.text().catch(() => "");
+		let json = null;
+		try {
+			json = text ? JSON.parse(text) : null;
+		} catch {}
+		return {
+			ok: res.ok,
+			status: res.status,
+			json,
+			text: json?.message || text
+		};
+	};
+	return {
+		caller,
+		authSource: "token"
+	};
+}
+async function readFileBytes(dir, filename) {
+	return readFile(join(dir, filename));
+}
+/**
+* Upload unique attachment blobs to `refs/diffing/attachments/pr-<N>` and
+* rewrite every local `/api/attachments/…` URL in the given bodies.
+*
+* On `dryRun: true`, builds placeholder URLs (`…/raw/<pending>/…`) without
+* calling GitHub.
+*/
+async function rewriteLocalAttachmentsInBodies(resolved, bodies, opts) {
+	const dryRun = opts?.dryRun === true;
+	const planned = await planAttachmentUploads(bodies, { attachmentsDir: opts?.attachmentsDir });
+	if (planned.error) return {
+		bodies,
+		urlMap: {},
+		uploaded: 0,
+		dryRun,
+		error: planned.error
+	};
+	if (planned.plans.length === 0) return {
+		bodies,
+		urlMap: {},
+		uploaded: 0,
+		dryRun
+	};
+	if (dryRun) {
+		const urlMap = {};
+		for (const p of planned.plans) urlMap[p.localUrl] = githubRawBlobUrl(resolved, "<pending>", p.treePath);
+		return {
+			bodies: bodies.map((b) => rewriteAttachmentUrls(b, urlMap)),
+			urlMap,
+			uploaded: 0,
+			dryRun: true
+		};
+	}
+	const api = await createGhApiCaller(resolved);
+	if ("error" in api) return {
+		bodies,
+		urlMap: {},
+		uploaded: 0,
+		dryRun,
+		error: api.error
+	};
+	const { caller } = api;
+	const repoPath = `repos/${resolved.owner}/${resolved.repo}`;
+	const dir = attachmentsDir(opts?.attachmentsDir);
+	const hashToBlobSha = /* @__PURE__ */ new Map();
+	const uniqueByHash = /* @__PURE__ */ new Map();
+	for (const p of planned.plans) if (!uniqueByHash.has(p.contentHash)) uniqueByHash.set(p.contentHash, p);
+	for (const p of uniqueByHash.values()) {
+		const bytes = await readFileBytes(dir, p.filename);
+		const res = await caller("POST", `${repoPath}/git/blobs`, {
+			content: bytes.toString("base64"),
+			encoding: "base64"
+		});
+		if (!res.ok || !res.json?.sha) return {
+			bodies,
+			urlMap: {},
+			uploaded: 0,
+			dryRun,
+			error: contentsWriteHint(res.text || `Failed to create blob for ${p.filename}`)
+		};
+		hashToBlobSha.set(p.contentHash, res.json.sha);
+	}
+	const tree = [...uniqueByHash.values()].map((p) => ({
+		path: p.treePath,
+		mode: "100644",
+		type: "blob",
+		sha: hashToBlobSha.get(p.contentHash)
+	}));
+	const treeRes = await caller("POST", `${repoPath}/git/trees`, { tree });
+	if (!treeRes.ok || !treeRes.json?.sha) return {
+		bodies,
+		urlMap: {},
+		uploaded: 0,
+		dryRun,
+		error: contentsWriteHint(treeRes.text || "Failed to create git tree for attachments")
+	};
+	const refName = attachmentRefName(resolved.pullNumber);
+	const refSuffix = refName.replace(/^refs\//, "");
+	const existing = await caller("GET", `${repoPath}/git/ref/${refSuffix}`);
+	const parents = existing.ok && existing.json?.object?.sha ? [existing.json.object.sha] : [];
+	const commitRes = await caller("POST", `${repoPath}/git/commits`, {
+		message: `diffing: attach review images for PR #${resolved.pullNumber}`,
+		tree: treeRes.json.sha,
+		parents
+	});
+	if (!commitRes.ok || !commitRes.json?.sha) return {
+		bodies,
+		urlMap: {},
+		uploaded: 0,
+		dryRun,
+		error: contentsWriteHint(commitRes.text || "Failed to create attachment commit")
+	};
+	const commitSha = commitRes.json.sha;
+	if (parents.length === 0) {
+		const createRef = await caller("POST", `${repoPath}/git/refs`, {
+			ref: refName,
+			sha: commitSha
+		});
+		if (!createRef.ok) return {
+			bodies,
+			urlMap: {},
+			uploaded: 0,
+			dryRun,
+			error: contentsWriteHint(createRef.text || `Failed to create ${refName}`)
+		};
+	} else {
+		const updateRef = await caller("PATCH", `${repoPath}/git/refs/${refSuffix}`, {
+			sha: commitSha,
+			force: false
+		});
+		if (!updateRef.ok) return {
+			bodies,
+			urlMap: {},
+			uploaded: 0,
+			dryRun,
+			error: contentsWriteHint(updateRef.text || `Failed to update ${refName}`)
+		};
+	}
+	const urlMap = {};
+	for (const p of planned.plans) urlMap[p.localUrl] = githubRawBlobUrl(resolved, commitSha, p.treePath);
+	return {
+		bodies: bodies.map((b) => rewriteAttachmentUrls(b, urlMap)),
+		urlMap,
+		uploaded: uniqueByHash.size,
+		dryRun: false
+	};
+}
+//#endregion
+export { rewriteLocalAttachmentsInBodies };

package/dist/handoff-DPoIyeWn.mjs

@@ -0,0 +1,11 @@
+//#region src/lib/handoff.ts
+const PLAN_SUBMIT_NEXT_ACTION = "Share the plan review URL with the human and end your turn (async handoff). Call await_plan_review only when the human is reviewing now or explicitly asked you to wait.";
+const AWAIT_REVIEW_TIMEOUT_NEXT_ACTION = "Wait budget elapsed — expected, not a failure. Park: tell the human the review UI is waiting and end your turn. Call await_review again only if they asked you to keep waiting (at most once more unless they repeat that ask). Do not retry in a silent loop. When they say the review is ready, call await_review once (or list_comments with openOnly) to resume; a prior Send-to-agent handoff is replayed.";
+const AWAIT_PLAN_TIMEOUT_NEXT_ACTION = "Wait budget elapsed — expected, not a failure. Park: tell the human the plan URL is waiting for Submit review and end your turn. Call await_plan_review again only if they asked you to keep waiting (at most once more unless they repeat that ask). Do not retry in a silent loop. When they say a verdict is ready, call await_plan_review once (or get_plan / list_plans) to resume; a prior verdict is replayed.";
+const CLI_AWAIT_REVIEW_TIMEOUT_HINT = "Wait budget elapsed (expected). Prefer parking until the human is ready; re-run `diffing await-review` only if they asked you to keep waiting.";
+const CLI_AWAIT_PLAN_TIMEOUT_HINT = "Wait budget elapsed (expected). Prefer parking until the human is ready; re-run `diffing plan await` only if they asked you to keep waiting.";
+const CLI_PLAN_SUBMIT_PARK_HINT = "Async handoff: share the URL above. Use --wait / `diffing plan await` only when the human is reviewing now or asked you to block.";
+/** Compact MCP / skill preamble for wait tools. */
+const AWAIT_TOOL_DESCRIPTION_SUFFIX = "Timeout means the wait budget elapsed (expected). Park and end the turn unless the human asked you to keep waiting; never silent-loop. Progress notifications are sent between long polls.";
+//#endregion
+export { CLI_AWAIT_REVIEW_TIMEOUT_HINT as a, CLI_AWAIT_PLAN_TIMEOUT_HINT as i, AWAIT_REVIEW_TIMEOUT_NEXT_ACTION as n, CLI_PLAN_SUBMIT_PARK_HINT as o, AWAIT_TOOL_DESCRIPTION_SUFFIX as r, PLAN_SUBMIT_NEXT_ACTION as s, AWAIT_PLAN_TIMEOUT_NEXT_ACTION as t };

package/dist/{mcp-DOqu6S64.mjs → mcp-Dq7J5QOP.mjs}

@@ -1,7 +1,8 @@
-import { i as buildGitDiffArgs, o as parseDiffOptions, t as startServer } from "./server-Bjzyb6NG.mjs";
+import { i as buildGitDiffArgs, o as parseDiffOptions, t as startServer } from "./server-C9i4V36o.mjs";
 import { t as formatComments } from "./comment-format-B5AcGcR-.mjs";
 import { n as formatPlanReview } from "./plan-format-BQyx--mp.mjs";
-import { a as removeServerLock, i as readServerLock, n as diffScopeKey, o as removeServerLockIfOwned, r as isLockAlive, s as writeServerLock, t as acquireServerStartupLease } from "./server-lock-uqSdDYeR.mjs";
+import { a as removeServerLock, i as readServerLock, n as diffScopeKey, o as removeServerLockIfOwned, r as isLockAlive, s as writeServerLock, t as acquireServerStartupLease } from "./server-lock-Dd_ss_Il.mjs";
+import { n as AWAIT_REVIEW_TIMEOUT_NEXT_ACTION, r as AWAIT_TOOL_DESCRIPTION_SUFFIX, s as PLAN_SUBMIT_NEXT_ACTION, t as AWAIT_PLAN_TIMEOUT_NEXT_ACTION } from "./handoff-DPoIyeWn.mjs";
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
@@ -345,7 +346,7 @@ function createMcpServer(options) {
 	const ownerId = options.ownerId ?? randomUUID();
 	const defaultClientDir = existsSync(resolve(moduleDirectory, "client")) ? resolve(moduleDirectory, "client") : resolve(repoRoot, "dist/client");
 	const clientDir = options.clientDir ?? defaultClientDir;
-	const instructions = `diffing is bound to ${repoRoot} for this connection. First call review_session_status. If no web session is running, call start_review_session; it is safe to retry and never replaces a user session. For code review, prefer diff_summary then paged diff_files/diff_hunks/diff_slice over get_diff; create_comment as needed, then await_review for the human handoff. For a GitHub PR session, call gh_overview and bounded diff tools; use gh_list_threads/reviews for discussion, and mutate GitHub only with explicit user authorization. For plan review, call submit_plan then await_plan_review. A changes-requested verdict means revise and resubmit the same planId; rejected means stop; approved means proceed. Wait tools return released or timeout with a mode; timeout is not failure and the same wait tool may be called again. MCP connects only to the loopback diffing server; explicitly authorized GitHub tools may make the server call GitHub.`;
+	const instructions = `diffing is bound to ${repoRoot} for this connection. First call review_session_status. If no web session is running, call start_review_session; it is safe to retry and never replaces a user session. For code review, prefer diff_summary then paged diff_files/diff_hunks/diff_slice over get_diff; create_comment as needed. Handoff: default is async — share the UI URL and end your turn; use await_review only when the human is reviewing now or asked you to wait. For a GitHub PR session, call gh_overview and bounded diff tools; use gh_list_threads/reviews for discussion, and mutate GitHub only with explicit user authorization. For plan review, call submit_plan, share the plan URL, and park unless asked to wait; then await_plan_review when sync waiting. A changes-requested verdict means revise and resubmit the same planId; rejected means stop; approved means proceed. Wait tools return released or timeout with disposition/nextAction; timeout means park (do not silent-loop). MCP connects only to the loopback diffing server; explicitly authorized GitHub tools may make the server call GitHub.`;
 	const server = new McpServer({
 		name: "diffing",
 		version: MCP_VERSION
@@ -915,10 +916,11 @@ function createMcpServer(options) {
 	});
 	server.registerTool("await_review", {
 		title: "Wait for code review handoff",
-		description: "Wait for the human to send a code-review round. Returns status=released or status=timeout and always includes mode. Timeout is expected and safe to retry; progress notifications are sent between long polls.",
-		inputSchema: { timeoutSeconds: z.number().positive().max(3600).optional().describe("Total wait budget in seconds; defaults to 570.") },
+		description: "Sync wait for the human to click Send to agent. Prefer async handoff (share the UI URL and end the turn) unless they are reviewing now or asked you to wait. Returns status=released or status=timeout; timeout includes disposition=park. " + AWAIT_TOOL_DESCRIPTION_SUFFIX,
+		inputSchema: { timeoutSeconds: z.number().positive().max(3600).optional().describe(`Total wait budget in seconds; defaults to 570.`) },
 		outputSchema: {
 			status: z.enum(["released", "timeout"]),
+			disposition: z.enum(["park"]).optional(),
 			mode: z.enum(["standard", "comment-only"]),
 			round: z.number(),
 			openCount: z.number().optional(),
@@ -978,9 +980,10 @@ function createMcpServer(options) {
 		}
 		const structured = {
 			status: "timeout",
+			disposition: "park",
 			mode: "standard",
 			round: sinceRound,
-			nextAction: "No review was sent within the wait budget. Call await_review again to keep waiting."
+			nextAction: AWAIT_REVIEW_TIMEOUT_NEXT_ACTION
 		};
 		return textResult(structured.nextAction, structured);
 	});
@@ -1226,7 +1229,7 @@ function createMcpServer(options) {
 	});
 	server.registerTool("submit_plan", {
 		title: "Submit or resubmit a plan",
-		description: "Submit Markdown for human plan review. To revise after changes-requested, pass the same planId so a new version is created.",
+		description: "Submit Markdown for human plan review. Default handoff is async: return the URL and park. Call await_plan_review only when the human is reviewing now or asked you to wait. To revise after changes-requested, pass the same planId so a new version is created.",
 		inputSchema: {
 			title: z.string().optional().describe("Human-readable plan title."),
 			body: z.string().min(1).describe("Complete Markdown plan body."),
@@ -1238,7 +1241,8 @@ function createMcpServer(options) {
 			status: z.literal("submitted"),
 			planId: z.string(),
 			version: z.number(),
-			url: z.string()
+			url: z.string(),
+			nextAction: z.string()
 		},
 		annotations: MUTATING
 	}, async ({ title, body, source, model, planId }) => {
@@ -1257,19 +1261,21 @@ function createMcpServer(options) {
 			})
 		});
 		const url = `${base}/plan/${plan.id}`;
-		return textResult(`Submitted plan ${plan.id} (v${plan.version}) at ${url}. Call await_plan_review.`, {
+		return textResult(`Submitted plan ${plan.id} (v${plan.version}) at ${url}. ${PLAN_SUBMIT_NEXT_ACTION}`, {
 			status: "submitted",
 			planId: plan.id,
 			version: plan.version,
-			url
+			url,
+			nextAction: PLAN_SUBMIT_NEXT_ACTION
 		});
 	});
 	server.registerTool("await_plan_review", {
 		title: "Wait for plan review verdict",
-		description: "Wait for a plan verdict. Returns status=released or status=timeout and always includes mode. Timeout is expected and safe to retry; progress notifications are sent between long polls.",
-		inputSchema: { timeoutSeconds: z.number().positive().max(3600).optional().describe("Total wait budget in seconds; defaults to 570.") },
+		description: "Sync wait for a plan verdict (Submit review). Prefer async handoff after submit_plan unless the human is reviewing now or asked you to wait. Returns status=released or status=timeout; timeout includes disposition=park. " + AWAIT_TOOL_DESCRIPTION_SUFFIX,
+		inputSchema: { timeoutSeconds: z.number().positive().max(3600).optional().describe(`Total wait budget in seconds; defaults to 570.`) },
 		outputSchema: {
 			status: z.enum(["released", "timeout"]),
+			disposition: z.enum(["park"]).optional(),
 			mode: z.enum(["standard", "comment-only"]),
 			round: z.number(),
 			planId: z.string().optional(),
@@ -1335,9 +1341,10 @@ function createMcpServer(options) {
 		}
 		const structured = {
 			status: "timeout",
+			disposition: "park",
 			mode: "standard",
 			round: sinceRound,
-			nextAction: "No plan verdict arrived within the wait budget. Call await_plan_review again to keep waiting."
+			nextAction: AWAIT_PLAN_TIMEOUT_NEXT_ACTION
 		};
 		return textResult(structured.nextAction, structured);
 	});
@@ -1471,18 +1478,24 @@ function createMcpServer(options) {
 
 This MCP connection is immutably bound to \`${repoRoot}\`.
 
+## Handoff (sync vs async)
+- **Async (default):** share the UI/plan URL and end the turn. Resume when the human says the review or verdict is ready.
+- **Sync:** call \`await_review\` / \`await_plan_review\` only when the human is reviewing now or asked you to wait.
+- \`status=timeout\` + \`disposition=park\` means the wait budget elapsed — park; do not silent-loop. At most one extra await if they asked you to keep waiting.
+
 ## Code review
 1. Call \`review_session_status\`; call \`start_review_session\` if needed.
 2. Prefer \`diff_summary\` → paged \`diff_files\` → \`diff_hunks\` / bounded \`diff_slice\`; use \`get_diff\` only as an escape hatch.
 3. Use \`create_comment\` for actionable inline findings.
-4. Use \`await_review\` for a human handoff; a timeout is safe to retry.
+4. Prefer async handoff; use \`await_review\` for sync waits. On resume, one \`await_review\` (or \`list_comments\`) replays a prior Send-to-agent.
 5. In \`comment-only\` mode, reply without editing files.
 
 ## Plan review
 1. Start or reuse a review session.
-2. Call \`submit_plan\`, then \`await_plan_review\`.
-3. On \`changes-requested\`, revise and resubmit with the same \`planId\`.
-4. On \`approved\`, proceed; on \`rejected\`, stop.
+2. Call \`submit_plan\`, share the URL, and park unless asked to wait.
+3. On resume or sync wait, call \`await_plan_review\` (or \`get_plan\` / \`list_plans\`).
+4. On \`changes-requested\`, revise and resubmit with the same \`planId\`.
+5. On \`approved\`, proceed; on \`rejected\`, stop.
 
 ## GitHub PR
 1. In \`gh-pr\` mode call \`gh_overview\`, then the bounded diff tools.
@@ -1510,7 +1523,7 @@ MCP connects only to the loopback diffing server and never terminates a user-own
 		role: "user",
 		content: {
 			type: "text",
-			text: `Use diffing for plan review in ${repoRoot}. Start or reuse a review session, submit this plan, and await the verdict. On changes-requested revise and resubmit the same planId; on rejected stop; on approved proceed.
+			text: `Use diffing for plan review in ${repoRoot}. Start or reuse a review session, submit this plan, share the plan URL, and park (async handoff) unless the human asked you to wait. When they are ready or asked you to block, call await_plan_review. On changes-requested revise and resubmit the same planId; on rejected stop; on approved proceed. Timeout means park — do not silent-loop.
 
 ` + plan
 		}