pi-ui-extend 0.1.36 → 0.1.37

package/external/pi-tools-suite/src/antigravity-auth/index.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ignoreStaleExtensionContextError } from "../context-usage";
 import { decodeApiKey, getEffectiveProjectId } from "./auth-store";
 import { formatAddAccountResult, parseAddAccountCommandArgs } from "./commands";
 import { API_ID, DEFAULT_PROJECT_ID, ENDPOINT_DAILY, PROVIDER_ID } from "./constants";
@@ -10,6 +11,14 @@ import { streamAntigravity } from "./stream";
 export { addAntigravityAccount } from "./oauth";
 export type { AntigravityAddAccountResult } from "./types";
 
+async function staleSafe(action: () => void | Promise<void>): Promise<void> {
+	try {
+		await action();
+	} catch (error) {
+		ignoreStaleExtensionContextError(error);
+	}
+}
+
 export default async function antigravityAuth(pi: ExtensionAPI): Promise<void> {
 	rememberAntigravityApi(pi);
 	await publishAntigravityAuthStartupSection();
@@ -40,7 +49,9 @@ export default async function antigravityAuth(pi: ExtensionAPI): Promise<void> {
 					{
 						onAuth: ({ url }) => {
 							authUrl = url;
-							ctx.ui?.notify?.(`Open this Antigravity OAuth URL, then paste the callback URL:\n${url}`, "info");
+							void staleSafe(() => {
+								ctx.ui?.notify?.(`Open this Antigravity OAuth URL, then paste the callback URL:\n${url}`, "info");
+							});
 						},
 						onPrompt: async ({ message }) => {
 							if (typeof ctx.ui?.input !== "function") {
@@ -53,7 +64,9 @@ export default async function antigravityAuth(pi: ExtensionAPI): Promise<void> {
 					},
 					options,
 				);
-				ctx.ui?.notify?.(formatAddAccountResult(result), "info");
+				await staleSafe(() => {
+					ctx.ui?.notify?.(formatAddAccountResult(result), "info");
+				});
 				emitAntigravityStatus(await getCurrentAntigravityStatus());
 			} catch (error) {
 				notifyAntigravityLoginFailure(error);

package/external/pi-tools-suite/src/antigravity-auth/status.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { ignoreStaleExtensionContextError } from "../context-usage";
 import { publishStartupSection } from "../startup-section";
 import { LEGACY_STATUS_KEY, PROVIDER_ID, STATUS_KEY } from "./constants";
 import { accountFromCredential, clampAccountIndex, decodeApiKey, getAccountProjectId, getEffectiveProjectId, getPiAuthPath, getStoredAccounts, readJsonFile } from "./auth-store";
@@ -23,6 +24,14 @@ function errorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+function staleSafe(action: () => void): void {
+	try {
+		action();
+	} catch (error) {
+		ignoreStaleExtensionContextError(error);
+	}
+}
+
 export function formatAntigravityLoginFailure(error: unknown): string {
 	return `Antigravity login failed: ${errorMessage(error)}. Auth file: ${getPiAuthPath()}`;
 }
@@ -34,18 +43,22 @@ export function formatAntigravityProviderFailure(error: unknown): string {
 function notifyAntigravityFailure(message: string, details: Record<string, unknown>, options: { ui?: ExtensionUIContext; sendSessionMessage?: boolean } = {}): void {
 	const { ui, sendSessionMessage = true } = options;
 	const targetUi = ui ?? extensionUi;
-	if (typeof targetUi?.notify === "function") {
-		targetUi.notify(message, "error");
-	} else if (typeof (targetUi as any)?.toast?.error === "function") {
-		(targetUi as any).toast.error(message);
-	}
+	staleSafe(() => {
+		if (typeof targetUi?.notify === "function") {
+			targetUi.notify(message, "error");
+		} else if (typeof (targetUi as any)?.toast?.error === "function") {
+			(targetUi as any).toast.error(message);
+		}
+	});
 	if (!sendSessionMessage) return;
-	(extensionApi as any)?.sendMessage?.({
-		customType: "antigravity-auth-status",
-		content: message,
-		display: true,
-		details,
-	}, { triggerTurn: false });
+	staleSafe(() => {
+		(extensionApi as any)?.sendMessage?.({
+			customType: "antigravity-auth-status",
+			content: message,
+			display: true,
+			details,
+		}, { triggerTurn: false });
+	});
 }
 
 function shouldNotifyProviderFailure(message: string, model?: string): boolean {
@@ -145,13 +158,17 @@ export async function publishAntigravityAuthStartupSection(): Promise<void> {
 }
 
 export function emitAntigravityStatus(details: AntigravityStatusDetails): void {
-	if (typeof extensionUi?.setStatus === "function") {
-		extensionUi.setStatus(LEGACY_STATUS_KEY, undefined);
-		extensionUi.setStatus(STATUS_KEY, formatAntigravityStatus(details));
-	}
-	(extensionApi as any)?.sendMessage?.({
-		role: "system",
-		content: formatAntigravityStatus(details),
-		details,
+	staleSafe(() => {
+		if (typeof extensionUi?.setStatus === "function") {
+			extensionUi.setStatus(LEGACY_STATUS_KEY, undefined);
+			extensionUi.setStatus(STATUS_KEY, formatAntigravityStatus(details));
+		}
+	});
+	staleSafe(() => {
+		(extensionApi as any)?.sendMessage?.({
+			role: "system",
+			content: formatAntigravityStatus(details),
+			details,
+		});
 	});
 }

package/external/pi-tools-suite/src/async-subagents/async-subagents.sample.jsonc

@@ -55,10 +55,13 @@
   "routing": {
     "enabled": true,
     "model": "zai/glm-4.5-air",
+    // Ordered router model fallbacks tried when the primary routing model is
+    // unavailable or fails. The current parent model is always tried last.
+    "fallbackModels": ["openai-codex/gpt-5.3-codex-spark"],
     "maxTaskChars": 1200,
     "maxTokens": 512,
-    "maxRetries": 1,
-    "timeoutMs": 12000,
+    "maxRetries": 3,
+    "timeoutMs": 10000,
     "debug": false
   },
 

package/external/pi-tools-suite/src/async-subagents/commands.ts

@@ -415,7 +415,12 @@ function registerSessionCommands(pi: ExtensionAPI): void {
 				});
 				if (result.cancelled) ctx.ui.notify("Sub-agent session switch cancelled.", "warning");
 			} catch (error) {
-				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				try {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				} catch (notifyError) {
+					// If switchSession succeeded before a later callback threw, the old ctx is stale.
+					ignoreStaleExtensionContextError(notifyError);
+				}
 			}
 		},
 	});
@@ -452,7 +457,12 @@ function registerSessionCommands(pi: ExtensionAPI): void {
 				});
 				if (result.cancelled) ctx.ui.notify("Return session switch cancelled.", "warning");
 			} catch (error) {
-				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				try {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				} catch (notifyError) {
+					// If switchSession succeeded before a later callback threw, the old ctx is stale.
+					ignoreStaleExtensionContextError(notifyError);
+				}
 			}
 		},
 	});

package/external/pi-tools-suite/src/async-subagents/core/config.ts

@@ -29,8 +29,10 @@ export interface SubagentTypeConfig {
 export interface SubagentRoutingConfig {
 	/** Ask a lightweight model to choose subagentType when a task omits it. */
 	enabled?: boolean;
-	/** Router model in provider/model form. Falls back to the current parent model if unavailable. */
+	/** Router model in provider/model form. Falls back to fallbackModels, then the current parent model, if unavailable. */
 	model?: string;
+	/** Ordered router model fallbacks tried when the primary routing model is unavailable or fails. */
+	fallbackModels?: string[];
 	/** Maximum task/scope characters sent to the router per task. */
 	maxTaskChars?: number;
 	/** Maximum router response tokens. */
@@ -145,10 +147,11 @@ export const DEFAULT_MAX_CONCURRENT = 5;
 export const DEFAULT_ROUTING_CONFIG: ResolvedSubagentRoutingConfig = {
 	enabled: true,
 	model: "zai/glm-4.5-air",
+	fallbackModels: ["openai-codex/gpt-5.3-codex-spark"],
 	maxTaskChars: 1200,
 	maxTokens: 512,
-	maxRetries: 1,
-	timeoutMs: 12_000,
+	maxRetries: 3,
+	timeoutMs: 10_000,
 	debug: false,
 };
 
@@ -512,6 +515,8 @@ function normalizeRoutingConfig(value: Record<string, unknown>): SubagentRouting
 	const routing: SubagentRoutingConfig = {};
 	if (typeof value.enabled === "boolean") routing.enabled = value.enabled;
 	if (typeof value.model === "string" && value.model.trim()) routing.model = value.model.trim();
+	const fallbackModels = modelList(value.fallbackModels, value.fallbackModel);
+	if (fallbackModels) routing.fallbackModels = fallbackModels;
 	if (typeof value.debug === "boolean") routing.debug = value.debug;
 	const maxTaskChars = finiteNumber(value.maxTaskChars);
 	if (maxTaskChars !== undefined) routing.maxTaskChars = Math.max(100, Math.round(maxTaskChars));

package/external/pi-tools-suite/src/async-subagents/core/routing.ts

@@ -54,35 +54,54 @@ export async function routeSubagentTasks(
 	if (signal?.aborted) throw new Error("Aborted");
 
 	try {
-		const resolved = await resolveRoutingModel(ctx, routing);
-		if (!resolved) {
+		const candidates = await resolveRoutingModels(ctx, routing);
+		if (candidates.length === 0) {
 			const warning = `LLM sub-agent routing model unavailable (${routing.model}); used defaultType fallback.`;
 			notifyRoutingWarning(ctx, routing, warning);
 			return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: [warning] };
 		}
 
-		const response = await complete(
-			resolved.model,
-			{
-				systemPrompt: ROUTER_SYSTEM_PROMPT,
-				messages: [
+		const prompt = buildRoutingPrompt(autoTasks, config, routing);
+		const failures: string[] = [];
+		let response: RoutingResponse | undefined;
+		for (const candidate of candidates) {
+			if (signal?.aborted) throw new Error("Aborted");
+			try {
+				response = await complete(
+					candidate.model,
 					{
-						role: "user" as const,
-						content: [{ type: "text" as const, text: buildRoutingPrompt(autoTasks, config, routing) }],
-						timestamp: Date.now(),
+						systemPrompt: ROUTER_SYSTEM_PROMPT,
+						messages: [
+							{
+								role: "user" as const,
+								content: [{ type: "text" as const, text: prompt }],
+								timestamp: Date.now(),
+							},
+						],
 					},
-				],
-			},
-			{
-				apiKey: resolved.apiKey,
-				headers: resolved.headers,
-				cacheRetention: "none",
-				maxRetries: routing.maxRetries,
-				maxTokens: routing.maxTokens,
-				signal,
-				timeoutMs: routing.timeoutMs,
-			},
-		);
+					{
+						apiKey: candidate.apiKey,
+						headers: candidate.headers,
+						cacheRetention: "none",
+						maxRetries: routing.maxRetries,
+						maxTokens: routing.maxTokens,
+						signal,
+						timeoutMs: routing.timeoutMs,
+					},
+				);
+				break;
+			} catch (error) {
+				if (signal?.aborted || isAbortError(error)) throw error;
+				failures.push(`${currentModelRef(candidate.model) ?? "(unknown)"}: ${errorMessage(error)}`);
+			}
+		}
+
+		if (!response) {
+			const warning = `LLM sub-agent routing failed (${failures.join("; ")}); used defaultType fallback.`;
+			notifyRoutingWarning(ctx, routing, warning);
+			return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: [warning] };
+		}
+
 		const routes = parseRoutingResponse(responseText(response), config, autoTasks);
 		const warnings = Object.keys(routes).length === autoTasks.length
 			? []
@@ -137,17 +156,33 @@ function buildRoutingPrompt(tasks: AgentTask[], config: SubagentConfig, routing:
 	].join("\n");
 }
 
-async function resolveRoutingModel(ctx: SubagentRoutingContext, routing: ResolvedSubagentRoutingConfig): Promise<{
+async function resolveRoutingModels(
+	ctx: SubagentRoutingContext,
+	routing: ResolvedSubagentRoutingConfig,
+): Promise<RoutingCandidate[]> {
+	const candidates: RoutingCandidate[] = [];
+	const seen = new Set<string>();
+	const refs = [routing.model, ...routing.fallbackModels];
+	const parentModel = currentModelRef(ctx.model);
+	if (parentModel) refs.push(parentModel);
+	for (const ref of refs) {
+		const trimmed = ref?.trim();
+		if (!trimmed || seen.has(trimmed)) continue;
+		seen.add(trimmed);
+		const resolved = await resolveModelRef(ctx, trimmed);
+		if (resolved) candidates.push(resolved);
+	}
+	return candidates;
+}
+
+interface RoutingCandidate {
 	model: Model<Api>;
 	apiKey?: string;
 	headers?: Record<string, string>;
-} | undefined> {
-	const configured = await resolveModelRef(ctx, routing.model);
-	if (configured) return configured;
-	const parentModel = currentModelRef(ctx.model);
-	return parentModel && parentModel !== routing.model ? resolveModelRef(ctx, parentModel) : undefined;
 }
 
+type RoutingResponse = Awaited<ReturnType<typeof complete>>;
+
 async function resolveModelRef(ctx: SubagentRoutingContext, modelRef: string): Promise<{
 	model: Model<Api>;
 	apiKey?: string;

package/external/pi-tools-suite/src/async-subagents/core/tool-guard.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ignoreStaleExtensionContextError } from "../../context-usage";
 
 export const SUBAGENT_DENIED_TOOLS = new Set([
 	"question",
@@ -23,10 +24,14 @@ export default function subagentToolGuard(pi: ExtensionAPI): void {
 	};
 
 	const applyGuard = () => {
-		const activeTools = toolApi.getActiveTools?.() ?? [];
-		const filtered = filterSubagentTools(activeTools) ?? [];
-		if (filtered.length === activeTools.length) return;
-		toolApi.setActiveTools?.(filtered);
+		try {
+			const activeTools = toolApi.getActiveTools?.() ?? [];
+			const filtered = filterSubagentTools(activeTools) ?? [];
+			if (filtered.length === activeTools.length) return;
+			toolApi.setActiveTools?.(filtered);
+		} catch (error) {
+			ignoreStaleExtensionContextError(error);
+		}
 	};
 
 	pi.on("session_start", applyGuard);

package/external/pi-tools-suite/src/comment-checker/config.ts

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse, resolve } from "node:path";
+import { parse as parseJsonc } from "jsonc-parser";
+import { getPiToolsSuiteUserConfigPath } from "../config.js";
+import type { Strictness } from "./detect.js";
+
+export interface CommentCheckerConfig {
+	enabled: boolean;
+	strictness: Strictness;
+}
+
+const DEFAULT_STRICTNESS: Strictness = "balanced";
+const TRUE_VALUES = new Set(["1", "true", "on", "yes"]);
+const FALSE_VALUES = new Set(["0", "false", "off", "no"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function readJsonc(filePath: string): Record<string, unknown> {
+	if (!existsSync(filePath)) return {};
+	try {
+		const parsed = parseJsonc(readFileSync(filePath, "utf8"));
+		return isRecord(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+function findProjectConfig(startDir: string): string | undefined {
+	let dir = resolve(startDir);
+	const root = parse(dir).root;
+	while (true) {
+		const candidate = join(dir, ".pi", "pi-tools-suite.jsonc");
+		if (existsSync(candidate)) return candidate;
+		if (dir === root) return undefined;
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
+}
+
+function normalizeStrictness(value: unknown, fallback: Strictness): Strictness {
+	if (value === "conservative" || value === "balanced" || value === "aggressive") return value;
+	return fallback;
+}
+
+function boolFromEnv(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	const normalized = value.trim().toLowerCase();
+	if (TRUE_VALUES.has(normalized)) return true;
+	if (FALSE_VALUES.has(normalized)) return false;
+	return undefined;
+}
+
+let cachedConfig: CommentCheckerConfig | undefined;
+
+/**
+ * Load the `commentChecker` section from the same layered config files as the
+ * rest of the suite (user shared config, $PI_CONFIG_DIR, nearest project
+ * `.pi/pi-tools-suite.jsonc`), then apply env overrides.
+ *
+ * Module disabling is handled by the top-level `disabledModules` loader in
+ * `config.ts`; this loader only reads the per-module `commentChecker` section
+ * (enabled toggle + strictness).
+ *
+ * Cached after the first read for the lifetime of the process.
+ */
+export function loadCommentCheckerConfig(cwd: string = process.cwd(), env: NodeJS.ProcessEnv = process.env, homeDir: string = env.HOME ?? process.env.HOME ?? ""): CommentCheckerConfig {
+	if (cachedConfig) return cachedConfig;
+
+	let enabled = true;
+	let strictness: Strictness = DEFAULT_STRICTNESS;
+
+	const layers: string[] = [getPiToolsSuiteUserConfigPath(homeDir)];
+	if (env.PI_CONFIG_DIR) layers.push(join(env.PI_CONFIG_DIR, "pi-tools-suite.jsonc"));
+	const projectConfig = findProjectConfig(cwd);
+	if (projectConfig) layers.push(projectConfig);
+
+	for (const filePath of layers) {
+		const root = readJsonc(filePath);
+		const section = root.commentChecker;
+		if (!isRecord(section)) continue;
+		if (typeof section.enabled === "boolean") enabled = section.enabled;
+		if (section.strictness !== undefined) strictness = normalizeStrictness(section.strictness, strictness);
+	}
+
+	const envEnabled = boolFromEnv(env.PI_COMMENT_CHECKER_ENABLED);
+	if (envEnabled !== undefined) enabled = envEnabled;
+	if (env.PI_COMMENT_CHECKER_STRICTNESS) strictness = normalizeStrictness(env.PI_COMMENT_CHECKER_STRICTNESS, strictness);
+
+	cachedConfig = { enabled, strictness };
+	return cachedConfig;
+}
+
+export function __resetCommentCheckerConfigCache(): void {
+	cachedConfig = undefined;
+}

package/external/pi-tools-suite/src/comment-checker/detect.ts

@@ -0,0 +1,215 @@
+/**
+ * Pure-TypeScript comment-slop detector.
+ *
+ * No external binary, no network, no fs. Given the added/removed lines of a
+ * file edit, it finds net-new code comments (present in the added lines but
+ * not in the removed lines) that look unnecessary, while leaving genuinely
+ * valuable comments (TODO/FIXME, license headers, docstrings, pragmas, linter
+ * directives, shebangs, decorators) untouched.
+ *
+ * The mechanism mirrors oh-my-opencode comment-checker hook (the
+ * hasNewCommentsOnly heuristic) but replaces its external binary with an
+ * in-process classifier so the suite stays headless and pure-TS.
+ *
+ * Language-agnostic: recognizes comment markers from many languages:
+ *   // /* *   (C/C++/Java/C#/JS/TS/Rust/Go/Swift/Scala/Kotlin, JSDoc continuation)
+ *   #          (Python, Ruby, Shell, Perl, YAML, TOML, Makefile, PowerShell, R)
+ *   --         (SQL, Lua, Haskell, Ada, Elm)
+ *   <!-- -->   (HTML, XML, SVG, Markdown)
+ *   triple quotes (Python docstrings)
+ *   :          (some config/scripting dialects)
+ */
+
+export type Strictness = "conservative" | "balanced" | "aggressive";
+
+export interface CommentFinding {
+	filePath: string;
+	/** Absolute 1-based line number when resolvable from the written file. */
+	line?: number;
+	/** Full original comment line. */
+	text: string;
+	/** Classifier reason: restate-code | filler | decorative | generic-explanation | non-essential-comment. */
+	reason: string;
+}
+
+/**
+ * An extracted edit. removedLines are the lines being replaced (old text),
+ * addedLines are the new lines. For full-file writes, removedLines is empty
+ * because every comment in the new content is by definition newly added.
+ */
+export interface Edit {
+	filePath: string;
+	removedLines: readonly string[];
+	addedLines: readonly string[];
+	/**
+	 * Absolute 1-based line number of the FIRST line in `addedLines` within the
+	 * target file, when known. Used to report accurate finding line numbers.
+	 * For full-file writes this is 1; for edits/apply_patch it is resolved by
+	 * locating the block in the already-written file; when unknown, undefined.
+	 */
+	baseLineNumber?: number;
+}
+
+const MARKER_RE = /^\s*(\/\/+|\/\*+|\*+|#+|--+|<!--|:\s*)/;
+const PY_STRING_OPEN_RE = /^\s*("""|''')/;
+
+/**
+ * Strip the comment marker and surrounding whitespace from a line.
+ * Returns the comment body, or null when the line is not a comment.
+ */
+export function commentBody(line: string): string | null {
+	const pyString = line.match(PY_STRING_OPEN_RE);
+	if (pyString) {
+		const body = line.slice(pyString[0].length).replace(/("""|''')\s*$/, "").trim();
+		return body.length > 0 ? body : null;
+	}
+
+	const match = line.match(MARKER_RE);
+	if (!match) return null;
+
+	const body = line.slice(match[0].length).replace(/\*\/\s*$/, "").trim();
+	return body.length > 0 ? body : null;
+}
+
+const VALUABLE_RE: readonly RegExp[] = [
+	// Task / review markers with optional context.
+	/\b(TODO|FIXME|XXX|HACK|NOTE|WARNING|WARN|BUG|OPTIMIZE|OPTIMISE|REFACTOR|DEPRECATED|SAFETY|SECURITY|PERF|PERFORMANCE|CHANGED|REVIEW|QUESTION|IDEA)\b[:\s()]/i,
+	// License / copyright headers.
+	/\bspdx-license-identifier\b/i,
+	/\b(copyright|\(c\))\b/i,
+	/\blicensed under\b/i,
+	/\blicense(d)?\b.*\b(MIT|Apache|GPL|LGPL|AGPL|BSD|MPL|ISC|Unlicense)\b/i,
+	// Linter / formatter directives.
+	/\b(eslint|tslint|biome|prettier|stylelint|jshint|jscs|cspell|spellcheck)\b[-:]/i,
+	/@typescript-eslint\//i,
+	// Hash-prefixed directives: C/C++ preprocessor, Python/SQL pragmas, tool ignores.
+	/^\s*#\s*(include|define|undef|ifdef|ifndef|if|elif|else|endif|error|warning|pragma|import|line|region|endregion|type:\s*ignore|noqa|nosec|pyright|mypy|isort|ruff|flake8|bandit|safety)\b/i,
+	// Shebang.
+	/^\s*#!/,
+	// Decorators and JSDoc/annotation tags.
+	/^\s*@/,
+	/\b@(param|returns?|throws?|see|example|deprecated|internal|public|private|protected|readonly|override|ts-ignore|ts-expect-error|ts-check|ts-nocheck|abstract|generic|type|template|hidden|alpha|beta|experimental|since|version|author|license|category|remarks)\b/i,
+	// File-disable / allow bypass markers.
+	/comment-checker-disable-file/i,
+	/^\s*@allow\b/i,
+	// JSDoc / block docstring openers and rust doc.
+	/^\s*(\/\*\*|\/\/!|\/\/\/)/,
+	// Editor modelines and schema hints.
+	/\bvim:|\bex: set|\bmodeline\b|\bsts=|\bts=\d/i,
+	/\$schema\b/i,
+	/@type\b/i,
+	// Region / folding markers.
+	/{#[^}]*#}|^\s*#?(end )?region\b/i,
+];
+
+function isValuable(body: string, rawLine: string): boolean {
+	if (body.length === 0) return true;
+	for (const re of VALUABLE_RE) {
+		if (re.test(rawLine) || re.test(body)) return true;
+	}
+	return false;
+}
+
+const SYMBOL_RUN_RE = /[-=*_~#]{3,}/;
+const SYMBOLS_ONLY_RE = /^[=\-*_~#|<>.,:;\s]+$/;
+
+function decorativeReason(body: string): "decorative" | null {
+	if (body.length < 3) return null;
+	if (SYMBOLS_ONLY_RE.test(body) && SYMBOL_RUN_RE.test(body)) return "decorative";
+	return null;
+}
+
+const FILLER_RE =
+	/^(simply|obviously|clearly|just|basically|note that|please note|as you can see|as mentioned|as discussed|as shown|needless to say|of course|it goes without saying|important to note|worth noting|keep in mind|bear in mind|this (is|was|will|should|does|has|had))\b/i;
+
+const RESTATE_RE =
+	/^(returns?|creates?|sets?|gets?|fetches?|checks? if|checks? whether|loops? (over|through|around)|iterates? (over|through)|increments?|decrements?|initializes?|initialises?|defines?|declares?|calls?|invokes?|imports?|exports?|logs?|prints?|assigns?|updates?|removes?|adds?|deletes?|handles?|processes?|computes?|calculates?|reads?|writes?|opens?|closes?|starts?|stops?|begins?|ends?|stores?|saves?|loads?|parses?|validates?|verifies?)\b/i;
+
+const GENERIC_RE =
+	/^(this (function|method|code|line|block|class|module|file|variable|constant|loop|statement|section|part|snippet|component|hook|handler|guard|helper|util|utility|wrapper|factory)|here we|here i|now we|now let'?s|let'?s|in this|the (above|following|next|previous|code|function|method|loop|block|statement)|with this|using this|first|then|finally|next|after that|step \d|a (helper|utility|wrapper|factory) (that|to|for)|workaround|hack:|note:|caveat:|disclaimer:)/i;
+
+function classifySlop(body: string, strictness: Strictness): string | null {
+	const decorative = decorativeReason(body);
+	if (decorative) return decorative;
+
+	if (FILLER_RE.test(body)) return "filler";
+
+	if (strictness === "conservative") return null;
+
+	if (RESTATE_RE.test(body)) return "restate-code";
+
+	if (strictness === "balanced") {
+		if (GENERIC_RE.test(body)) return "generic-explanation";
+		return null;
+	}
+
+	// aggressive: any remaining non-valuable comment is flagged.
+	return "non-essential-comment";
+}
+
+function removedCommentSignatures(removedLines: readonly string[]): Set<string> {
+	const set = new Set<string>();
+	for (const line of removedLines) {
+		const body = commentBody(line);
+		if (body !== null) set.add(line.trim());
+	}
+	return set;
+}
+
+/**
+ * Detect net-new unnecessary comments across a set of edits.
+ * Returns at most maxFindings findings (per file, then overall) to keep the
+ * tool-result nudge concise.
+ */
+export function detectSlopComments(edits: readonly Edit[], strictness: Strictness, maxFindings = 8): CommentFinding[] {
+	const findings: CommentFinding[] = [];
+
+	for (const edit of edits) {
+		if (!edit.filePath) continue;
+		const removed = removedCommentSignatures(edit.removedLines);
+
+		// Track /* ... */ block comments (including /** JSDoc/docstrings) so that
+		// interior continuation lines (e.g. ` * Adds two numbers.`) are not
+		// individually flagged. Block-comment content is evaluated as a whole;
+		// only single-line `/* foo */` inline comments fall through to classification.
+		let inBlockComment = false;
+
+		let indexInBlock = 0;
+		for (const line of edit.addedLines) {
+			if (findings.length >= maxFindings) break;
+
+			const hasOpen = line.includes("/*");
+			const hasClose = line.includes("*/");
+
+			if (inBlockComment) {
+				if (hasClose) inBlockComment = false;
+				indexInBlock++;
+				continue;
+			}
+
+			if (hasOpen && !hasClose) {
+				// Opener of a multi-line block comment / docstring. Skip it and the
+				// following continuation lines until the matching `*/`.
+				inBlockComment = true;
+				indexInBlock++;
+				continue;
+			}
+
+			const body = commentBody(line);
+			const lineOffset = indexInBlock;
+			indexInBlock++;
+			if (body === null) continue;
+			if (removed.has(line.trim())) continue;
+			if (isValuable(body, line)) continue;
+			const reason = classifySlop(body, strictness);
+			if (!reason) continue;
+
+			const absoluteLine = edit.baseLineNumber !== undefined ? edit.baseLineNumber + lineOffset : undefined;
+			findings.push({ filePath: edit.filePath, line: absoluteLine, text: line.trim(), reason });
+		}
+
+		if (findings.length >= maxFindings) break;
+	}
+
+	return findings;
+}