canary-test-cli 6.8.1 → 7.1.0

package/dist/engine/mcp-server.js

@@ -34,7 +34,7 @@
  *     default for `_WORKING_DIR` uses `??` to mirror `os.environ.get(k, cwd)`
  *     (an explicitly-empty env var stays `""`).
  *   - **ensure_ascii.** Hand-built JSON returned to the MCP host is escaped via
- *     {@link ensureAscii} (the reporter.ts pattern) so non-ASCII code points
+ *     the shared {@link ensureAscii} (`util/ensure-ascii.ts`) so non-ASCII units
  *     emit `\uXXXX`, matching Python's default `json.dumps`.
  *   - **splitlines.** `context_snippets` uses {@link pySplitlines}, which drops
  *     a single trailing-newline empty tail exactly as `str.splitlines()` does.
@@ -46,12 +46,14 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod';
 import { DomainScanner } from './core/domain-scanner.js';
-import { detectEnvironment } from './core/environment-detect.js';
+import { detectEnvironment, detectUserLevel, } from './core/environment-detect.js';
+import { effectivePersonaRegistry, personaToDict, resolvePersona, } from './core/persona.js';
 import { CanaryTestExecutor } from './core/executor.js';
 import { FrameworkRegistry } from './core/framework-registry.js';
 import { HarnessMigrator } from './core/migrator.js';
 import { findTestFiles, PatternMatcher } from './core/pattern-matcher.js';
 import { Scaffolder } from './core/scaffolder.js';
+import { ensureAscii } from './util/ensure-ascii.js';
 // ---------------------------------------------------------------------------
 // Module constants (mirror agent/mcp_server.py)
 // ---------------------------------------------------------------------------
@@ -99,15 +101,6 @@ const MAX_FILE_FUNCTIONS = 20;
 // ---------------------------------------------------------------------------
 // Python-compatibility helpers
 // ---------------------------------------------------------------------------
-/**
- * Reproduce Python's `json.dumps(..., ensure_ascii=True)` (the library default):
- * escape every code point >= 0x80 as `\uXXXX`. Copied per-module, matching the
- * reporter.ts / guardian pattern (the regex range is written with `\u....`
- * escapes so this source stays ASCII).
- */
-function ensureAscii(json) {
-    return json.replace(/[\u0080-\uffff]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
-}
 /**
  * Split like Python's `str.splitlines()` for the common line endings: splits on
  * `\r\n` / `\r` / `\n` and drops the single empty tail a trailing separator
@@ -436,9 +429,37 @@ export function analyzeFileImpl(filePath) {
     // Context-aware persona & environment detection (#341): attach the detected
     // BASE_URL, suite type, and SDET-vs-manual user level. The file under
     // analysis is itself an "open file" signal for the user-level heuristic.
-    const environment = detectEnvironment(projectRoot, {
+    const detected = detectEnvironment(projectRoot, {
         openFiles: [filePath],
-    }).toDict();
+    });
+    // Personas (#462) — and the consumer #341 never had. Detection shipped and
+    // was read by nobody: the level was computed, attached here, and dropped.
+    // Resolving it into a persona is what turns the signal into something a
+    // skill can consult instead of re-inventing its own audience rules.
+    //
+    // The persona re-derives the user level WITHOUT the analyzed file, and that
+    // is the whole point of the second call. `filePath` is this tool's argument,
+    // not an observation of what the caller is working on, so counting it as
+    // evidence about the person would let any `.ts` file in any project with a
+    // package.json clear the two-independent-signal floor and declare the reader
+    // a senior SDET. `environment` above keeps reporting it — that contract is
+    // unchanged — and only the persona declines to count it.
+    const [personaLevel, personaSignals, personaConfidence] = detectUserLevel(projectRoot, []);
+    // Both I/O decisions are made *here* rather than inside the resolver, which
+    // is pure by design: reading the environment variable, and loading the
+    // registry (shipped personas folded with every overlay's). `CANARY_PERSONA`
+    // is the audience-depth axis and is unrelated to `canary doctor --audience`,
+    // which tags which overlay checks run.
+    const persona = personaToDict(resolvePersona({
+        explicit: process.env['CANARY_PERSONA'] ?? null,
+        detected: {
+            level: personaLevel,
+            confidence: personaConfidence,
+            signals: personaSignals,
+        },
+        registry: effectivePersonaRegistry(),
+    }));
+    const environment = detected.toDict();
     return {
         framework,
         framework_source: frameworkSource,
@@ -452,6 +473,7 @@ export function analyzeFileImpl(filePath) {
         existing_tests: findExistingTests(projectRoot, framework),
         context_snippets: contextSnippets,
         environment,
+        persona,
     };
 }
 /** Python: `_write_test_file_impl`. */

package/dist/engine/skills-cli.js

@@ -10,9 +10,14 @@
  * load/attr failure -> 6) over a dynamic `import()`, which will not resolve a
  * Python module. No Python test exercises the cli/entry execution branches.
  */
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { CliExit, normalizeUsageExit } from './cli-common.js';
+import { CliExitError, jsonIndent2, normalizeUsageExit } from './cli-common.js';
+import { gateOutcome } from './core/gate-result.js';
+import { checkExamples, spawnRunner, } from './core/skill-examples.js';
+import { SurfaceFindingKind, checkSurfaces, collectSurfaces, } from './core/skill-surfaces.js';
 import { isExecutableSkillAllowed, resolveCliPath, } from './core/skill-registry.js';
 import { CROSS, EM_DASH } from './main-deps.js';
 function overlayName(skill) {
@@ -88,19 +93,19 @@ async function runCmd(name, args, opts, deps) {
     const skill = deps.makeSkillRegistry().find(name);
     if (skill === null) {
         deps.out(`${pc.red(CROSS)} No skill named ${pc.bold(name)} found.`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     if (skill.error) {
         deps.out(`${pc.red(CROSS)} Skill ${pc.bold(name)}: ${skill.error}`);
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     if (!skill.isExecutable) {
         deps.out(pc.yellow(`Skill ${pc.bold(name)} is markdown-only ${EM_DASH} no cli: or entry: field to run.`));
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     if (!isExecutableSkillAllowed(opts.allowExecutableSkills ?? false)) {
         deps.out(`${pc.red(CROSS)} Refusing to invoke executable skill in non-interactive context. Pass ${pc.bold('--allow-executable-skills')} to opt in (e.g. in trusted CI configurations).`);
-        throw new CliExit(3);
+        throw new CliExitError(3);
     }
     const forwarded = args;
     if (skill.cli) {
@@ -110,7 +115,7 @@ async function runCmd(name, args, opts, deps) {
         }
         catch (exc) {
             deps.out(`${pc.red(CROSS)} ${exc instanceof Error ? exc.message : String(exc)}`);
-            throw new CliExit(4);
+            throw new CliExitError(4);
         }
         const cmd = target.endsWith('.py') ? [deps.pythonExe(), target] : [target];
         const res = deps.runSubprocess(cmd[0], [...cmd.slice(1), ...forwarded], {
@@ -120,14 +125,14 @@ async function runCmd(name, args, opts, deps) {
         // A spawn failure (missing interpreter/binary) yields status=null; Python's
         // subprocess.run raises FileNotFoundError -> nonzero exit. Map null -> 1, not
         // a silent 0. A normal run passes its real exit code through.
-        throw new CliExit(res.status ?? 1);
+        throw new CliExitError(res.status ?? 1);
     }
     // entry: branch -- see module docstring (Python-module semantics are not
     // portable; the exit-code ladder is preserved).
     const [moduleName, sep, attr] = partition(skill.entry, ':');
     if (!moduleName || !attr || !sep) {
         deps.out(`${pc.red(CROSS)} Skill ${pc.bold(name)} entry must be 'module:callable', got '${skill.entry}'`);
-        throw new CliExit(5);
+        throw new CliExitError(5);
     }
     try {
         const mod = (await import(moduleName));
@@ -135,15 +140,122 @@ async function runCmd(name, args, opts, deps) {
         if (typeof target !== 'function')
             throw new Error('not callable');
         const rc = target();
-        throw new CliExit(typeof rc === 'number' ? rc : 0);
+        throw new CliExitError(typeof rc === 'number' ? rc : 0);
     }
     catch (exc) {
-        if (exc instanceof CliExit)
+        if (exc instanceof CliExitError)
             throw exc;
         deps.out(`${pc.red(CROSS)} Skill ${pc.bold(name)} entry '${skill.entry}': ${exc instanceof Error ? exc.message : String(exc)}`);
-        throw new CliExit(6);
+        throw new CliExitError(6);
     }
 }
+/**
+ * `skills verify` -- cross-surface consistency (#452) plus execution of the
+ * commands the docs promise (#487).
+ *
+ * **Two checks, two summary lines, deliberately.** Folding them into one
+ * denominator is the trap: 80 surfaces checked and 0 examples executed would
+ * render as a single healthy number while the half that actually executes
+ * something had abstained. Each check therefore reports its own denominator
+ * through `gateOutcome`, and the reader sees both.
+ *
+ * Classified **advisory** (exit 0): both checks are landing on a corpus nothing
+ * has ever swept, so their precision is unknown and ADR 0010 says promotion
+ * waits for the triage. Abstention is still printed loudly -- that is what the
+ * classification does *not* soften.
+ */
+/**
+ * Run the examples half, or explain why it could not run.
+ *
+ * The examples half spawns a CLI. When there is no built one, the honest result
+ * is a zero denominator carrying the reason -- an unrunnable runner must never
+ * look like a clean corpus.
+ */
+function exampleHalf(opts, surfaces, root) {
+    const bin = opts.canaryBin ?? join(root, 'ts', 'bin', 'canary.js');
+    if ((opts.runExamples ?? true) && existsSync(bin)) {
+        return checkExamples(surfaces, spawnRunner(bin), root);
+    }
+    return {
+        checked: 0,
+        findings: [],
+        skipped: [
+            {
+                name: 'every documented example',
+                reason: opts.runExamples === false
+                    ? '--no-run-examples was passed'
+                    : `no built CLI at ${bin} (run \`npm --prefix ts run build\`)`,
+            },
+        ],
+    };
+}
+/**
+ * Per-kind tally over the FULL enum, including kinds that scored zero.
+ *
+ * A triage backlog is read by category, and `cli-not-executable=0` is the line
+ * that says the rule ran. An absent line is indistinguishable from a rule that
+ * was never evaluated -- the reading trap this whole check exists to close.
+ */
+function tallyByKind(findings) {
+    return Object.values(SurfaceFindingKind)
+        .map((kind) => `${kind}=${findings.filter((f) => f.kind === kind).length}`)
+        .join(' ');
+}
+/** Both halves as JSON, each carrying its own `checked` and `abstained`. */
+function verifyJson(root, surfaceResult, exampleResult) {
+    return jsonIndent2({
+        root,
+        surfaces: {
+            checked: surfaceResult.checked,
+            abstained: !(surfaceResult.checked > 0),
+            findings: surfaceResult.findings,
+        },
+        examples: {
+            checked: exampleResult.checked,
+            abstained: !(exampleResult.checked > 0),
+            findings: exampleResult.findings,
+            skipped: exampleResult.skipped ?? [],
+        },
+    });
+}
+/** One summary line per half, plus the remediation text on an abstention. */
+function verifyReport(root, surfaceResult, exampleResult, deps) {
+    for (const f of surfaceResult.findings) {
+        deps.err(`${pc.yellow(CROSS)} [${f.kind}] ${f.name}: ${f.detail}`);
+    }
+    for (const f of exampleResult.findings) {
+        deps.err(`${pc.yellow(CROSS)} [${f.kind}] ${f.skill}: ${f.detail}`);
+    }
+    const surfaceOutcome = gateOutcome(surfaceResult, 'advisory', {
+        noun: 'surface declaration(s)',
+    });
+    deps.out(`surfaces: ${surfaceOutcome.summaryLine}`);
+    deps.out(`  by kind: ${tallyByKind(surfaceResult.findings)}`);
+    if (surfaceOutcome.abstained) {
+        deps.out(`  no skill surface was found under ${root} ${EM_DASH} check the path, ` +
+            'or that `agents/skills/` has not been renamed.');
+    }
+    const exampleOutcome = gateOutcome(exampleResult, 'advisory', {
+        noun: 'documented example(s)',
+    });
+    deps.out(`examples: ${exampleOutcome.summaryLine}`);
+    if (exampleOutcome.abstained) {
+        deps.out(`  zero documented commands were executed ${EM_DASH} nothing here is ` +
+            'proven. Add a help-shaped example in a shell fence to a SKILL.md, or ' +
+            'build the engine so the runner has a CLI to spawn.');
+    }
+}
+function verifyCmd(opts, deps) {
+    const root = resolve(opts.root ?? deps.cwd());
+    const surfaces = collectSurfaces(root);
+    const surfaceResult = checkSurfaces(root);
+    const exampleResult = exampleHalf(opts, surfaces, root);
+    if (opts.json) {
+        deps.out(verifyJson(root, surfaceResult, exampleResult));
+        return;
+    }
+    verifyReport(root, surfaceResult, exampleResult, deps);
+}
 /** Python `str.partition(sep)` -> `[before, sep, after]`. */
 function partition(s, sep) {
     const i = s.indexOf(sep);
@@ -173,6 +285,16 @@ export function buildSkillsCommand(deps) {
         .action(async (name, args, opts) => {
         await runCmd(name, args ?? [], opts, deps);
     });
+    program
+        .command('verify')
+        .description('Check that skill surfaces agree and that documented examples still run.')
+        .option('--root <path>', 'Repository root to inspect (default: cwd).')
+        .option('--json', 'Emit both denominators and every finding as JSON.')
+        .option('--no-run-examples', 'Inspect declarations only; do not execute documented examples.')
+        .option('--canary-bin <path>', 'CLI to spawn for documented examples.')
+        .action((opts) => {
+        verifyCmd(opts, deps);
+    });
     for (const sub of program.commands) {
         sub.exitOverride(normalizeUsageExit);
     }

package/dist/engine/util/ensure-ascii.js

@@ -0,0 +1,37 @@
+/**
+ * The one `ensure_ascii=True` implementation (#710).
+ *
+ * Python's `json.dumps` escapes every non-ASCII character to `\uXXXX` by
+ * default; `JSON.stringify` emits raw UTF-8. Every module that reproduces a
+ * Python payload byte-for-byte therefore has to post-process its stringify
+ * output, and eight of them used to do it with a private copy of this function.
+ *
+ * It lives under `util/` rather than in `cli-common.ts` (which documented it
+ * first) because the copies were spread across the `core`, `guardian`, and
+ * entry layers, and the layer model in `harness.config.json` lets nothing
+ * depend on `cli`. `util` is the one leaf every layer is allowed to reach.
+ *
+ * `ts/test/shared-helper-single-source.test.ts` fails if a ninth copy appears.
+ */
+/**
+ * Escape every non-ASCII UTF-16 code UNIT to `\uXXXX`, matching Python
+ * `json.dumps(ensure_ascii=True)`.
+ *
+ * Iterating by code unit rather than code point is the load-bearing detail: an
+ * astral character's surrogate pair emits `\udXXX\udXXX`, exactly as CPython
+ * writes it. A code-point walk (`for (const ch of json)`) would instead reach
+ * a value above `0xffff`, which does not fit a four-hex-digit `\uXXXX` escape
+ * at all -- so it would either truncate or leave the character raw.
+ *
+ * Only the `>= 0x80` range is touched, so the ASCII escapes `JSON.stringify`
+ * already produced (`\"`, `\\`, control characters) pass through intact.
+ */
+export function ensureAscii(json) {
+    let out = '';
+    for (let i = 0; i < json.length; i++) {
+        const c = json.charCodeAt(i);
+        out += c >= 0x80 ? '\\u' + c.toString(16).padStart(4, '0') : json[i];
+    }
+    return out;
+}
+//# sourceMappingURL=ensure-ascii.js.map

package/dist/engine/workflow-cli.js

@@ -12,7 +12,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { CliExit, jsonIndent2, normalizeUsageExit } from './cli-common.js';
+import { CliExitError, jsonIndent2, normalizeUsageExit } from './cli-common.js';
 import { SemanticRole, WorkflowDiscoveryError, WorkflowMapping, } from './core/workflow-discovery.js';
 import { CHECK, CROSS, MAGNIFIER, WARN, ELLIPSIS, } from './main-deps.js';
 /** ISO-8601 UTC timestamp truncated to seconds (Python `isoformat(timespec)`). */
@@ -38,7 +38,7 @@ async function discoverCmd(opts, deps) {
         }
         if (keys.length === 0) {
             deps.out(`${pc.yellow('No project keys found.')} Pass ${pc.bold('--project <key>')} or add keys to ${pc.bold('.canary/company.json')} ${'\u{2192}'} ${pc.bold('jira_projects')}.`);
-            throw new CliExit(1);
+            throw new CliExitError(1);
         }
     }
     const errors = [];
@@ -76,7 +76,7 @@ async function discoverCmd(opts, deps) {
     }
     if (errors.length) {
         deps.out(`\n${pc.red(`Discovery failed for: ${errors.join(', ')}`)}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
 }
 function showCmd(opts, deps) {
@@ -99,7 +99,7 @@ function showCmd(opts, deps) {
         }
         if (keys.length === 0) {
             deps.out(pc.yellow('No cached workflow mappings found.'));
-            throw new CliExit(0);
+            throw new CliExitError(0);
         }
     }
     let anyFound = false;
@@ -162,7 +162,7 @@ function showCmd(opts, deps) {
         }
     }
     if (!anyFound) {
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
 }
 function initCmd(opts, deps) {
@@ -170,7 +170,7 @@ function initCmd(opts, deps) {
     const mappingPath = wd.mappingPath(opts.project);
     if (existsSync(mappingPath) && !opts.force) {
         deps.out(`${pc.yellow(WARN)}  Mapping already exists at ${mappingPath}.\nUse ${pc.bold('--force')} to overwrite.`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     const resolvedUrl = (opts.atlassianUrl || deps.env['ATLASSIAN_URL'] || '').replace(/\/+$/, '') || null;
     const semanticRoles = {

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/gate-result.d.ts

@@ -48,6 +48,17 @@ export interface GateOutcomeOptions {
     /** Unit noun for the clean-pass line. Default: `'check(s)'`. */
     noun?: string;
 }
+/**
+ * The errno code `e` carries, or `null` when it carries none.
+ *
+ * Load-bearing wherever a read failure is absorbed into a {@link SkipEntry}:
+ * only "the filesystem said no" may become a skip. Node PROGRAMMER errors carry
+ * a string `code` too, so keying off `typeof code === 'string'` reports a
+ * genuine defect inside the scanner as a tidy abstention with a misleading
+ * reason -- which is how a scanner learns to go quiet. Anything this returns
+ * `null` for must still throw.
+ */
+export declare function errnoCode(e: unknown): string | null;
 /**
  * D7: skipped entries render in EVERY summary line.
  *

package/dist/gate-result.js

@@ -7,6 +7,7 @@
 // `npm test` verifies this copy has not drifted (--check runs as pretest).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EXIT_ABSTAINED = void 0;
+exports.errnoCode = errnoCode;
 exports.skippedSuffix = skippedSuffix;
 exports.gateOutcome = gateOutcome;
 /**
@@ -19,6 +20,23 @@ const EMDASH = '\u{2014}'; // em dash
 // C0 controls (incl. \n, ESC) and DEL: a skip name must never be able to
 // forge output lines or smuggle ANSI sequences into the summary.
 const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
+// A libuv/POSIX errno code (`ENOENT`, `EACCES`, `EISDIR`), as opposed to a Node
+// programmer-error code (`ERR_INVALID_ARG_TYPE`).
+const ERRNO = /^E[A-Z0-9]+$/;
+/**
+ * The errno code `e` carries, or `null` when it carries none.
+ *
+ * Load-bearing wherever a read failure is absorbed into a {@link SkipEntry}:
+ * only "the filesystem said no" may become a skip. Node PROGRAMMER errors carry
+ * a string `code` too, so keying off `typeof code === 'string'` reports a
+ * genuine defect inside the scanner as a tidy abstention with a misleading
+ * reason -- which is how a scanner learns to go quiet. Anything this returns
+ * `null` for must still throw.
+ */
+function errnoCode(e) {
+    const code = e?.code;
+    return typeof code === 'string' && ERRNO.test(code) ? code : null;
+}
 /**
  * D7: skipped entries render in EVERY summary line.
  *

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;

package/dist/overlay-commands.js

@@ -446,7 +446,10 @@ function updateOne(o, git, out, err) {
     }
     if (clean === 'dirty') {
         err.write(`overlay "${o.name}": local modifications in ${o.path} — refusing to update. ` +
-            `Commit/stash them, or 'canary overlay remove ${o.name}' and re-add.\n`);
+            `Commit/stash them, or discard them with ` +
+            `'canary overlay remove ${o.name} --force' and re-add. ` +
+            `(Plain 'overlay remove' refuses on a dirty clone too, so it will not ` +
+            `throw the edits away by accident.)\n`);
         return 1;
     }
     if (o.ref) {
@@ -520,8 +523,15 @@ function update(name, deps = {}) {
 /**
  * `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.
  */
-function remove(name, deps = {}) {
+function remove(name, deps = {}, opts = {}) {
+    const git = deps.git ?? defaultGit;
     const homeDir = deps.homeDir ?? os.homedir();
     const out = deps.out ?? process.stdout;
     const err = deps.err ?? process.stderr;
@@ -538,6 +548,22 @@ function remove(name, deps = {}) {
         err.write(`canary overlay remove: no overlay named "${name}".\n`);
         return 1;
     }
+    if (!opts.force && fs.existsSync(entry.path)) {
+        const clean = workingTreeStatus(entry.path, git);
+        if (clean === 'unreadable') {
+            err.write(`canary overlay remove: cannot read git status at ${entry.path} — ` +
+                `refusing to delete it. Inspect the directory, then re-run with ` +
+                `--force to remove it anyway.\n`);
+            return 1;
+        }
+        if (clean === 'dirty') {
+            err.write(`canary overlay remove: local modifications in ${entry.path} — ` +
+                `refusing to delete them. Commit or discard the changes ` +
+                `(git -C ${entry.path} status), then re-run; or re-run with ` +
+                `--force to delete the clone and the changes.\n`);
+            return 1;
+        }
+    }
     fs.rmSync(entry.path, { recursive: true, force: true });
     const { registry: next } = registry.remove(reg, name);
     registry.write(next, homeDir);