canary-test-cli 6.8.0 → 7.0.0

package/dist/engine/guardian/diff-coverage/report-tier.js

@@ -0,0 +1,153 @@
+/**
+ * Tier 1 — coverage resolved from an explicit report (`COVERAGE_VERIFIED`).
+ *
+ * Owns the lcov reader, the format dispatch (which report shape is this file?),
+ * and the per-unit matching that turns a report index into verdicts.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { parseCobertura } from './formats/cobertura.js';
+import { parseCoverageJson } from './formats/coverage-json.js';
+import { expandRanges, makeResult, matchFile, rangesStr, selfDescribing, splitLines, pyInt, Fidelity, } from './types.js';
+/**
+ * Parse `lcov.info` into `{path: {line: hits}}`.
+ *
+ * Every `DA:` record is a line the instrumenter measured, so the recorded lines
+ * are exactly the coverable set — see `FileCoverage`.
+ */
+function parseLcov(text) {
+    const byPath = {};
+    let current = null;
+    for (const line of splitLines(text)) {
+        if (line.startsWith('SF:')) {
+            current = line.slice(3).trim();
+            if (!(current in byPath))
+                byPath[current] = {};
+        }
+        else if (line.startsWith('DA:') && current !== null) {
+            recordDa(byPath[current], line.slice(3).trim());
+        }
+        else if (line.trim() === 'end_of_record') {
+            current = null;
+        }
+    }
+    const index = {};
+    for (const [path, hits] of Object.entries(byPath)) {
+        index[path] = selfDescribing(hits);
+    }
+    return index;
+}
+/** Fold one `DA:<line>,<hits>` body into a file's hit map, skipping junk. */
+function recordDa(hits, body) {
+    const parts = body.split(',');
+    if (parts.length < 2)
+        return;
+    const lineno = pyInt(parts[0]);
+    const count = pyInt(parts[1]);
+    if (lineno === null || count === null)
+        return;
+    hits[lineno] = count;
+}
+/** Read a report file as UTF-8, returning `null` on any read/decode failure. */
+function readReportText(reportPath) {
+    try {
+        const buf = readFileSync(reportPath);
+        // Fatal decode: a non-UTF-8 report must fall through, never raise out of
+        // the guardian gate (mirrors Python's UnicodeDecodeError → None).
+        return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Tier 1: resolve coverage from an explicit report (`COVERAGE_VERIFIED`).
+ *
+ * Supports `lcov.info` (`DA:<line>,<hits>`), the canary coverage-json shape,
+ * and Cobertura `coverage.xml` (line-level). Unrecognized/empty/unreadable →
+ * `null` (caller falls through to a lower fidelity tier — absence never
+ * blocks).
+ */
+export function resolveFromReport(units, reportPath) {
+    const { index } = readReportIndex(reportPath);
+    if (index === null)
+        return null;
+    return matchUnitsToIndex(units, index);
+}
+/** Read + parse a coverage report, reporting each step's outcome separately. */
+export function readReportIndex(reportPath) {
+    const unusable = (found) => ({ found, index: null });
+    if (!existsSync(reportPath))
+        return unusable(false);
+    const text = readReportText(reportPath);
+    // Present but unreadable/non-UTF-8 counts as found-and-unusable, not absent.
+    if (text === null)
+        return unusable(true);
+    const index = parseByFormat(basename(reportPath).toLowerCase(), text);
+    if (index === null || Object.keys(index).length === 0)
+        return unusable(true);
+    return { found: true, index };
+}
+/** Pick the reader by report filename; `null` for a format we don't know. */
+function parseByFormat(name, text) {
+    if (name.endsWith('.json')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        return parseCoverageJson(parsed);
+    }
+    if (name.endsWith('.info') || name.includes('lcov'))
+        return parseLcov(text);
+    if (name.endsWith('.xml'))
+        return parseCobertura(text);
+    // Unrecognized format → fall through to a lower fidelity tier.
+    return null;
+}
+/** Resolve every unit the report index can speak to (COVERAGE_VERIFIED). */
+export function matchUnitsToIndex(units, index) {
+    const results = [];
+    for (const unit of units) {
+        const file = matchFile(unit.path, index);
+        if (file === null) {
+            // Unit path is nowhere in the report index → "not instrumented", which is
+            // NOT the same as "instrumented and unhit". Emit no COVERAGE_VERIFIED
+            // result so the orchestrator falls through to a lower-fidelity tier for
+            // this unit (FIX 2).
+            continue;
+        }
+        const { hits, coverable: measured } = file;
+        const added = expandRanges(unit.added_ranges);
+        // The per-line form of the check above (#655/#657): where the report says
+        // which lines it instrumented, a changed line outside that set could not
+        // have been executed and is scored by neither side. Where it does not say,
+        // every changed line counts and absence means uncovered.
+        const coverable = measured === null ? added : added.filter((ln) => measured.has(ln));
+        if (coverable.length === 0) {
+            // Every changed line is non-coverable, so this report has nothing to say
+            // about the unit. An abstention — never a clean pass, never a finding.
+            // Falls through to the graph/heuristic tier exactly as an absent path does.
+            continue;
+        }
+        const uncovered = coverable.filter((ln) => (hits[ln] ?? 0) <= 0);
+        const covered = uncovered.length === 0;
+        // State the denominator: "all covered" over 20 changed lines and over the 3
+        // of them that were coverable are very different claims (#508).
+        const evidence = covered
+            ? `lines ${rangesStr(unit.added_ranges)}: all ${coverable.length} coverable line(s) covered`
+            : `lines ${rangesStr(unit.added_ranges)}: ${uncovered.length} of ${coverable.length} coverable line(s) uncovered`;
+        results.push(makeResult({
+            unit,
+            covered,
+            fidelity: Fidelity.CoverageVerified,
+            evidence,
+            uncovered_lines: uncovered,
+            coverable_lines: coverable.length,
+        }));
+    }
+    return results;
+}
+//# sourceMappingURL=report-tier.js.map

package/dist/engine/guardian/diff-coverage/type-only.js

@@ -0,0 +1,150 @@
+/**
+ * Proof that a module has no runtime content at all (#562) — the one
+ * suppression that is about the FILE rather than the fidelity tier.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { splitLines } from './types.js';
+/**
+ * Filenames/paths that plausibly hold nothing but type declarations (#562).
+ *
+ * A NAME GATE ONLY -- it decides which files are worth reading, never which
+ * are suppressed. {@link isTypeOnlyModule} always confirms against content,
+ * because a `types.ts` that also exports an enum or a const map is ordinary
+ * TypeScript and its findings are real.
+ */
+function isTypeModuleCandidate(path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    if (base.endsWith('.d.ts'))
+        return true;
+    if (!/\.(ts|tsx|mts|cts)$/.test(base))
+        return false;
+    if (base === 'types.ts' || base.endsWith('.types.ts'))
+        return true;
+    return path.split('/').slice(0, -1).includes('types');
+}
+/**
+ * True if `path` is a module with no runtime content at all (#562).
+ *
+ * The false-positive class this closes is the one the heuristic-tier fix
+ * (#413) structurally cannot reach. `filterHeuristicNoise` is gated on
+ * `fidelity === HEURISTIC` on purpose -- a coverage-verified verdict rests on
+ * a real lcov row, so suppressing by path at that tier would discard
+ * evidence. A type-only module is the case that breaks the symmetry: the lcov
+ * row is accurate (39 lines, genuinely never executed) and the finding is
+ * still unsatisfiable, because an interface has no runtime existence for a
+ * test to reach. The evidence needed is therefore about the FILE, not the
+ * tier: prove there is nothing executable in it.
+ *
+ * Conservative in one direction on purpose. Every uncertainty -- an
+ * unreadable file, an unrecognised construct -- resolves to `false`, keeping
+ * the finding. A missed suppression costs one noisy finding; a wrong
+ * suppression hides untested code, which is the thing the guardian exists to
+ * catch.
+ */
+export function isTypeOnlyModule(path, repoRoot) {
+    if (!isTypeModuleCandidate(path))
+        return false;
+    let source;
+    try {
+        source = readFileSync(join(repoRoot, path), 'utf-8');
+    }
+    catch {
+        return false; // unreadable -> unproven -> keep the finding
+    }
+    return isTypeOnlySource(source);
+}
+/** Drop `//` and `/* *\/` comments so keywords inside prose never count. */
+function stripComments(source) {
+    const out = [];
+    let inBlock = false;
+    for (const line of splitLines(source)) {
+        let text = line;
+        if (inBlock) {
+            const end = text.indexOf('*/');
+            if (end === -1) {
+                out.push('');
+                continue;
+            }
+            text = text.slice(end + 2);
+            inBlock = false;
+        }
+        for (;;) {
+            const start = text.indexOf('/*');
+            if (start === -1)
+                break;
+            const end = text.indexOf('*/', start + 2);
+            if (end === -1) {
+                text = text.slice(0, start);
+                inBlock = true;
+                break;
+            }
+            text = text.slice(0, start) + text.slice(end + 2);
+        }
+        const line2 = text.indexOf('//');
+        out.push(line2 === -1 ? text : text.slice(0, line2));
+    }
+    return out.join('\n');
+}
+/**
+ * Top-level constructs TypeScript erases entirely at compile time (#562).
+ *
+ * An ALLOWLIST, not a denylist, and that is the load-bearing choice. A
+ * denylist of runtime keywords misses everything it did not enumerate -- a
+ * bare `register('widget')` declares nothing and still runs -- and every gap
+ * in it suppresses a real finding. An allowlist fails the other way: an
+ * unrecognised construct reads as runtime and the finding survives.
+ *
+ * Plain `import { X } from '...'` is allowed because TypeScript elides an
+ * import whose bindings are only used in type positions; if a binding were
+ * used as a value, the using statement itself would appear at top level and
+ * be rejected. A side-effect `import './x'` carries no binding, is never
+ * elided, and is therefore not matched.
+ */
+function isErasableTopLevelLine(line) {
+    if (line === '')
+        return true;
+    if (/^[})\];,]+$/.test(line))
+        return true;
+    if (/^import\s+type\b/.test(line))
+        return true;
+    if (/^import\b.*\sfrom\s/.test(line))
+        return true;
+    if (/^export\s+type\b/.test(line))
+        return true;
+    const bare = line.replace(/^(?:export\s+default\s+|export\s+|declare\s+)+/, '');
+    return /^(?:interface|type)\s/.test(bare);
+}
+/**
+ * True if every TOP-LEVEL statement in `source` is compile-time-only.
+ *
+ * Brace depth is tracked so an interface body is never mistaken for
+ * statements: only depth-0 lines are judged. An unbalanced file (depth does
+ * not return to zero) is treated as unproven rather than type-only -- brace
+ * counting is lexical, so a `{` inside a string literal could otherwise hide
+ * the rest of the file from inspection.
+ */
+function isTypeOnlySource(source) {
+    let depth = 0;
+    for (const raw of splitLines(stripComments(source))) {
+        const line = raw.trim();
+        if (depth === 0 && !isErasableTopLevelLine(line))
+            return false;
+        depth += bracketDelta(line);
+        if (depth < 0)
+            return false;
+    }
+    return depth === 0;
+}
+/** Net nesting change across one line: openers minus closers. */
+function bracketDelta(line) {
+    let delta = 0;
+    for (const ch of line) {
+        if (ch === '{' || ch === '(' || ch === '[')
+            delta += 1;
+        else if (ch === '}' || ch === ')' || ch === ']')
+            delta -= 1;
+    }
+    return delta;
+}
+//# sourceMappingURL=type-only.js.map

package/dist/engine/guardian/diff-coverage/types.js

@@ -0,0 +1,115 @@
+/**
+ * The coverage resolver's shared shapes, plus the small primitives every tier
+ * needs to speak about them (line arithmetic, Python-parity parsing, path
+ * matching). Leaf module: it imports nothing from the rest of the resolver.
+ */
+import { basename, extname } from 'node:path';
+/** Confidence tier of a coverage signal (lower rank == higher fidelity). */
+export var Fidelity;
+(function (Fidelity) {
+    Fidelity["CoverageVerified"] = "coverage-verified";
+    Fidelity["GraphVerified"] = "graph-verified";
+    Fidelity["Heuristic"] = "heuristic";
+})(Fidelity || (Fidelity = {}));
+const FIDELITY_RANK = {
+    [Fidelity.CoverageVerified]: 0,
+    [Fidelity.GraphVerified]: 1,
+    [Fidelity.Heuristic]: 2,
+};
+/** 0=coverage, 1=graph, 2=heuristic. Lower means higher fidelity. */
+export function fidelityRank(fidelity) {
+    return FIDELITY_RANK[fidelity];
+}
+/**
+ * Build a {@link CoverageResult}, defaulting `uncovered_lines` to `[]`. Stands
+ * in for the Python dataclass's `field(default_factory=list)` — the graph and
+ * heuristic tiers never populate uncovered lines and rely on that default.
+ */
+export function makeResult(fields) {
+    return { ...fields, uncovered_lines: fields.uncovered_lines ?? [] };
+}
+/** Every line the report recorded is a line it could measure (lcov/Cobertura). */
+export function selfDescribing(hits) {
+    return { hits, coverable: recordedLines(hits) };
+}
+/** The line numbers a hit map has records for. */
+export function recordedLines(hits) {
+    return new Set(Object.keys(hits).map(Number));
+}
+/** Split like Python's `str.splitlines()` for the common line endings. */
+export function splitLines(text) {
+    return text.split(/\r\n|\r|\n/);
+}
+/**
+ * Parse an integer the way Python's `int(str)` does for our inputs: optional
+ * surrounding whitespace and sign, digits only. Returns `null` on failure
+ * (Python would raise `ValueError`, which the callers catch-and-skip).
+ */
+export function pyInt(value) {
+    const trimmed = value.trim();
+    if (!/^[+-]?\d+$/.test(trimmed))
+        return null;
+    return Number.parseInt(trimmed, 10);
+}
+/** bool is excluded (a JSON true/false is not a valid line/hit count). */
+export function isInt(value) {
+    // typeof boolean !== 'number', so booleans are already excluded here — the
+    // JS analog of Python's explicit `not isinstance(value, bool)` guard.
+    return typeof value === 'number' && Number.isInteger(value);
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Flatten inclusive `[start, end]` ranges into a sorted, de-duped line list. */
+export function expandRanges(ranges) {
+    const lines = new Set();
+    for (const [start, end] of ranges) {
+        for (let ln = start; ln <= end; ln++)
+            lines.add(ln);
+    }
+    return [...lines].sort((a, b) => a - b);
+}
+/** Python's `Path(p).stem`: basename minus its final extension. */
+export function stem(path) {
+    const base = basename(path);
+    const ext = extname(base);
+    return ext ? base.slice(0, -ext.length) : base;
+}
+/**
+ * True iff `candidate` and `target` name the same file path suffix.
+ *
+ * Exact match, or one is a suffix of the other on a **path-separator boundary**
+ * (`a/b/foo.py` vs `foo.py`). Rejects loose substring collisions such as
+ * `foobar.py` vs `bar.py` and `usermodels.py` vs `models.py` (FIX 6).
+ */
+export function pathBoundaryMatch(candidate, target) {
+    return (candidate === target ||
+        candidate.endsWith('/' + target) ||
+        target.endsWith('/' + candidate));
+}
+/**
+ * Look up one file's coverage for `path` in a report index.
+ *
+ * Prefers an EXACT path match. Otherwise falls back to a **boundary** suffix
+ * match (report paths may be absolute, `./`-prefixed, or repo-relative). On
+ * multiple boundary matches (duplicate basenames) the lookup is ambiguous and
+ * returns `null` — the unit is then skipped and falls through rather than
+ * binding to an arbitrary first match (FIX 6).
+ */
+export function matchFile(path, index) {
+    if (path in index)
+        return index[path];
+    const matches = [];
+    for (const [reportPath, file] of Object.entries(index)) {
+        if (pathBoundaryMatch(reportPath, path))
+            matches.push(file);
+    }
+    return matches.length === 1 ? matches[0] : null;
+}
+/** Render ranges compactly, e.g. `[[12, 28], [30, 30]]` → `"12-28, 30"`. */
+export function rangesStr(ranges) {
+    return ranges
+        .map(([start, end]) => (start === end ? `${start}` : `${start}-${end}`))
+        .join(', ');
+}
+//# sourceMappingURL=types.js.map

package/dist/engine/guardian/pr-check.js

@@ -470,7 +470,7 @@ export function filterHeuristicNoise(results, excludeGlobs) {
  * concern). `severity` reuses {@link Severity}; `fidelity` carries the
  * confidence tier from the underlying coverage signal.
  */
-export class Finding {
+export class GuardianFinding {
     path;
     unit;
     kind;
@@ -565,11 +565,27 @@ const HIGH_UNCOVERED_SHARE = 0.5;
 function addedLineCount(ranges) {
     return ranges.reduce((total, [start, end]) => total + (end - start + 1), 0);
 }
+/**
+ * The fraction of what the report could speak to that came back unhit (#655).
+ *
+ * The denominator is the unit's **coverable** lines — added lines overstate it,
+ * because on a new file that is largely imports, types and blanks most changed
+ * lines were never instrumented at all, and dividing by them drives every share
+ * toward zero. Where the count is unknown (the graph and heuristic tiers, which
+ * are not graded by share anyway) it falls back to the added-line count, so
+ * grades predating that field are unchanged. An unknown denominator yields a
+ * full share rather than a low one — an absent measurement must never read as a
+ * good score (ADR 0010).
+ */
+function uncoveredShare(result, uncovered) {
+    const denominator = result.coverable_lines ?? addedLineCount(result.unit.added_ranges);
+    return denominator > 0 ? uncovered / denominator : 1;
+}
 /**
  * Severity for an uncovered **coverage-verified** result (#553).
  *
  * Only this tier can be graded, because only this tier knows *which* lines ran
- * (see the `uncovered_lines` comment on {@link Finding}). The grade combines
+ * (see the `uncovered_lines` comment on {@link GuardianFinding}). The grade combines
  * how much is unhit with how much of the change that represents:
  *
  *   - `CRITICAL` — a large block (>= 20 lines) that is essentially untouched
@@ -589,8 +605,7 @@ function coverageVerifiedSeverity(result) {
     const uncovered = result.uncovered_lines?.length ?? 0;
     if (uncovered === 0)
         return Severity.HIGH;
-    const added = addedLineCount(result.unit.added_ranges);
-    const share = added > 0 ? uncovered / added : 1;
+    const share = uncoveredShare(result, uncovered);
     if (uncovered >= CRITICAL_UNCOVERED_LINES &&
         share >= CRITICAL_UNCOVERED_SHARE)
         return Severity.CRITICAL;
@@ -627,7 +642,7 @@ export function buildFindings(results) {
             severity = Severity.HIGH;
         const unit = result.unit;
         const uncovered = [...(result.uncovered_lines ?? [])];
-        findings.push(new Finding({
+        findings.push(new GuardianFinding({
             path: unit.path,
             unit: unit.symbol || unit.path,
             fidelity: result.fidelity,
@@ -709,7 +724,7 @@ export function buildWeakTestFindings(testUnits, diffText) {
         const code = added.join('\n');
         const framework = frameworkForTestPath(unit.path);
         if (isAssertionFreeTest(code, framework)) {
-            findings.push(new Finding({
+            findings.push(new GuardianFinding({
                 path: unit.path,
                 unit: unit.path,
                 kind: 'weak-test',
@@ -889,7 +904,7 @@ const SEVERITY_ICON = {
 function ensureAscii(json) {
     return json.replace(/[€-￿]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
 }
-/** Serialize a {@link Finding} to a stable JSON-friendly object. */
+/** Serialize a {@link GuardianFinding} to a stable JSON-friendly object. */
 function findingDict(finding) {
     return {
         path: finding.path,

package/dist/engine-checks.d.ts

@@ -20,6 +20,21 @@ export declare function parseRegistryVersion(rawBody: string): string | null;
 export declare function isOlder(a: string, b: string): boolean;
 /** CLI version vs latest release. Offline degrades to info, never a failure. */
 export declare function checkVersion(deps?: EngineCheckDeps): Promise<CheckResult>;
+/**
+ * Installed Claude Code plugin vs the marketplace clone (#522).
+ *
+ * Canary ships through two independent version streams and only the CLI had
+ * staleness detection, so `canary upgrade` would report everything current
+ * while leaving the plugin — the way Canary is actually used in-editor —
+ * arbitrarily far behind. A real consuming project ran 4.0.0 for six weeks
+ * against a 6.x CLI, during which six of Canary's agents did not exist in the
+ * version being loaded, with nothing anywhere surfacing it.
+ *
+ * Purely local file reads: no network, so this cannot fail offline. Both files
+ * are untrusted input — a hand-edited manifest degrades to info or skip rather
+ * than throwing out of `doctor`.
+ */
+export declare function checkPluginVersion(deps?: EngineCheckDeps): CheckResult;
 /** git present on PATH. */
 export declare function checkGit(deps?: EngineCheckDeps): CheckResult;
 /** Registered overlays present, fresh, and free of local modifications. */

package/dist/engine-checks.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseRegistryVersion = parseRegistryVersion;
 exports.isOlder = isOlder;
 exports.checkVersion = checkVersion;
+exports.checkPluginVersion = checkPluginVersion;
 exports.checkGit = checkGit;
 exports.checkOverlays = checkOverlays;
 exports.checkProjectConfig = checkProjectConfig;
@@ -160,6 +161,92 @@ async function checkVersion(deps = {}) {
         label: `CLI ${current} (latest)`,
     };
 }
+/** Marketplace that carries the Claude Code plugin, and the plugin's key in it. */
+const MARKETPLACE = 'bop-clocktower';
+const PLUGIN_KEY = `canary@${MARKETPLACE}`;
+/** Parse JSON from disk; null on missing file, unreadable path, or bad syntax. */
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Newest version among the installs recorded for {@link PLUGIN_KEY}.
+ *
+ * Claude Code stores an array per plugin key because user- and project-scoped
+ * installs coexist. Taking the first would report a stale plugin whenever the
+ * older scope happened to be listed first, so take the newest and let the
+ * comparison speak for the one actually in charge.
+ */
+function installedPluginVersion(manifest) {
+    const plugins = manifest
+        ?.plugins;
+    const entries = plugins?.[PLUGIN_KEY];
+    if (!Array.isArray(entries))
+        return null;
+    const versions = entries
+        .map((e) => e?.version)
+        .filter((v) => typeof v === 'string');
+    if (versions.length === 0)
+        return null;
+    return versions.reduce((best, v) => (isOlder(best, v) ? v : best));
+}
+/**
+ * Installed Claude Code plugin vs the marketplace clone (#522).
+ *
+ * Canary ships through two independent version streams and only the CLI had
+ * staleness detection, so `canary upgrade` would report everything current
+ * while leaving the plugin — the way Canary is actually used in-editor —
+ * arbitrarily far behind. A real consuming project ran 4.0.0 for six weeks
+ * against a 6.x CLI, during which six of Canary's agents did not exist in the
+ * version being loaded, with nothing anywhere surfacing it.
+ *
+ * Purely local file reads: no network, so this cannot fail offline. Both files
+ * are untrusted input — a hand-edited manifest degrades to info or skip rather
+ * than throwing out of `doctor`.
+ */
+function checkPluginVersion(deps = {}) {
+    const home = deps.homeDir ?? os.homedir();
+    const pluginsDir = path.join(home, '.claude', 'plugins');
+    const installed = installedPluginVersion(readJson(path.join(pluginsDir, 'installed_plugins.json')));
+    if (!installed) {
+        // CLI-only users have no plugin to be stale; not a finding.
+        return {
+            id: 'engine:plugin-version',
+            status: 'skip',
+            label: 'Claude Code plugin: not installed',
+        };
+    }
+    const marketplace = readJson(path.join(pluginsDir, 'marketplaces', MARKETPLACE, '.claude-plugin', 'plugin.json'))?.version;
+    if (typeof marketplace !== 'string') {
+        return {
+            id: 'engine:plugin-version',
+            status: 'info',
+            label: `Claude Code plugin ${installed} (could not read the ${MARKETPLACE} marketplace to compare)`,
+            remedy: `Refresh it with: /plugin marketplace update ${MARKETPLACE}`,
+        };
+    }
+    if (isOlder(installed, marketplace)) {
+        return {
+            id: 'engine:plugin-version',
+            status: 'fail',
+            label: `Claude Code plugin ${installed} is behind marketplace ${marketplace}`,
+            // Both commands, in order, always. `/plugin marketplace update` refreshes
+            // the clone but leaves the cached plugin in place, and `/plugin install`
+            // without it reinstalls whatever the stale clone holds — each alone
+            // reports success and changes nothing the user cares about.
+            remedy: `Update both — either alone is a no-op:\n  /plugin marketplace update ${MARKETPLACE}\n  /plugin install ${PLUGIN_KEY}`,
+        };
+    }
+    return {
+        id: 'engine:plugin-version',
+        status: 'pass',
+        label: `Claude Code plugin ${installed} (marketplace ${marketplace})`,
+    };
+}
 /** git present on PATH. */
 function checkGit(deps = {}) {
     const git = deps.git ?? realGit;
@@ -245,7 +332,10 @@ function checkOverlays(deps = {}) {
                 id: `overlay:${o.name}:clean`,
                 status: 'fail',
                 label: `overlay "${o.name}": ${clean === 'dirty' ? 'local modifications' : 'git status unreadable'}`,
-                remedy: `Commit/stash changes in ${o.path}, or canary overlay remove ${o.name} and re-add.`,
+                // `--force` is part of the remedy on purpose: since #675 a plain
+                // `overlay remove` refuses on a dirty clone, so the old advice was a
+                // dead end for exactly the user this check fires on.
+                remedy: `Commit/stash changes in ${o.path}, or discard them with canary overlay remove ${o.name} --force and re-add.`,
             });
         }
     }
@@ -527,6 +617,7 @@ function checkSkillRequirements(deps = {}) {
 async function runEngineChecks(deps = {}) {
     return [
         await checkVersion(deps),
+        checkPluginVersion(deps),
         checkGit(deps),
         ...checkOverlays(deps),
         checkOverlayConflicts(deps),

package/dist/overlay-commands.d.ts

@@ -72,8 +72,19 @@ export declare function lint(nameOrPath: string | undefined, deps?: CommandDeps,
  * updates all; refuses on local modifications or a non-fast-forward.
  */
 export declare function update(name: string | null, deps?: CommandDeps): number;
+/** Options for {@link remove}. */
+export interface RemoveOptions {
+    /** `--force`: delete even when the clone has local modifications (#675). */
+    force?: boolean;
+}
 /**
  * `canary overlay remove <name>` — deregister an overlay and delete its clone.
  * Unknown name is an error; the registry is left unchanged in that case.
+ *
+ * Removal is destructive and irreversible, so it takes the same posture as
+ * `overlay update` (#675): a clone with local modifications — or one whose git
+ * status cannot be read, which is no safer to delete blind — is refused, and
+ * `--force` is the explicit opt-in. A clone that is already gone is not a
+ * refusal: there is nothing left to lose, so the stale registry row is dropped.
  */
-export declare function remove(name: string, deps?: CommandDeps): number;
+export declare function remove(name: string, deps?: CommandDeps, opts?: RemoveOptions): number;