dsh-plugin-inspector 0.1.0 → 0.2.1

package/README.md

@@ -2,13 +2,13 @@
 
 **Know what a plugin does before you install it.**
 
-`dsh-inspect` reads a DeepSeek Harness plugin — a directory or an npm tarball — and tells you
-what it declares and what its code is capable of. It does not install it, build it, import it,
-spawn it, or evaluate any part of it.
+`dsh-inspect` reads a DeepSeek Harness plugin — a directory, an npm tarball, or a published
+package fetched by name and checked against the hash the registry published — and tells you what it
+declares and what its code is capable of. It does not install it, build it, import it, spawn it, or
+evaluate any part of it.
 
 ```console
-$ npm pack some-dsh-plugin@1.4.0 --pack-destination /tmp
-$ dsh-inspect /tmp/some-dsh-plugin-1.4.0.tgz
+$ dsh-inspect --from-npm some-dsh-plugin@1.4.0
 ```
 
 ## Install
@@ -53,7 +53,7 @@ dsh: warning: <pkg> declares no dsh.bundle — installed as a plain dependency,
 
 The dangerous case prints nothing.
 
-There are over 4,000 repos tagged `dsh-plugin` — 4,813 when this was last counted, in August
+There are over 5,000 repos tagged `dsh-plugin` — 5,071 when this was last counted, on 16 August
 2026 — and no registry, no review, and no signing between any of them and your process. This tool
 exists so that the moment before you install one is not a blank.
 
@@ -68,15 +68,6 @@ commands it puts on your PATH, its dependencies, what model-visible text it ship
 it could be read. A well-behaved plugin has a full facts section and an empty findings section.
 That is a useful answer, not an empty one.
 
-That is also the bar the tool is held to. Across twelve real targets — four plugins read both as a
-directory and as their published tarball, the three bundles the harness itself ships, and a
-scratch plugin — the current build reports **49 findings: none critical, two high, and exactly one
-target exiting non-zero.** Both high findings are true statements about `@deepseek-ai/dsh-web-app`'s
-own shipped code, which does contribute to the system prompt and does mount further plugins. The
-upstream plugin template reports three findings, all `node:fs` and `dshHomePath` facts about what
-it genuinely does; the base and headless bundles report three and one. Every packable target's
-directory reading and tarball reading are byte-identical.
-
 **Findings** — ranked, in three tiers:
 
 | Tier | What it reads | What it can say |
@@ -89,14 +80,67 @@ Every Tier B and Tier C finding carries a `bypass` field naming the one-line eva
 specific check. It is inside the finding, not in a footnote, so a report cannot be rendered
 without its caveat.
 
+A finding is **per package, not per syntax site**. A package importing `node:fs` from eleven files
+gets one finding with `occurrences: 11` and three example locations, because the eleventh import
+warrants no decision the first did not. Findings are grouped by check and `subject` — the module
+specifier, the row id, the seam name, the matched rule — so `node:child_process` and
+`node:worker_threads` stay two findings, and a gate can accept `B13`/`node:fs` without accepting
+every `B13`.
+
+## What it reports on the real ecosystem
+
+Measured **2026-08-16** against the 40 most-starred GitHub repositories tagged `dsh-plugin` that
+publish a resolvable npm package, each pinned to the version current that day. Re-run it with
+`pnpm run sweep`; the corpus is `scripts/ecosystem-corpus.json` and the recorded measurement is
+`tests/ecosystem-baseline.json`.
+
+Both columns come from the same corpus and the same pinned versions, so the difference is this
+tool's doing and not the ecosystem's. "0.1" is the published `dsh-plugin-inspector@0.1.0`; "0.2" is
+this tree, which still reports version `0.1.0` because the release is not published yet.
+
+| | 0.1 | 0.2 |
+|---|---|---|
+| Findings | 1,420 | **295** |
+| Critical | 252 | **3** |
+| Median findings per package | 10.5 | **5.5** |
+| Packages with a high or critical | 27 of 40 (68 %) | **21 of 40 (53 %)** |
+| Packages failing `--fail-on critical` | 40 of 40 | **1 of 40** |
+| Clean packages | 0 of 40 | **0 of 40** |
+
+**The 0.1 README quoted "49 findings, 0 critical" and that number was worthless.** It was measured
+on twelve targets — the harness's own bundles and our own sibling plugins — which is a sample
+selected for being trusted already. Against published third-party plugins the same build produced
+1,420 findings and 252 criticals, and no package came out clean.
+
+Read the 0.2 column honestly:
+
+- **`--fail-on critical` is now a usable gate.** It stops one package in forty. That package,
+  `@struktoai/mirage-dsh`, ships a patch layer that switches off `fs-sandbox`, `bash-sandbox` and
+  `pwsh-sandbox`, and its three findings lead the report. Under 0.1 the same three sat somewhere in
+  a list of 252.
+- **The default `--fail-on high` still stops a majority of the ecosystem**, and that is not a
+  finished job. The largest remaining driver is `C2` — the analyzer saying it could not read the
+  package, on 33 % of the corpus. That is a true statement rather than a false positive, but a gate
+  that fires on a third of npm for reasons about the *tool* is not yet a gate.
+- **No package is clean, and that is expected rather than alarming.** `C3` alone — "ships built
+  output and no source" — fires on 65 % of published packages, because that is what publishing a
+  package is. It is `low`, it does not degrade the analysis, and it is not a defect.
+
+A readable report is not yet an installable gate.
+
 ## Usage
 
 ```
 dsh-inspect <target> [options]
+dsh-inspect --from-npm <name>[@<version>] [options]
 
   <target>                A plugin directory, or an npm tarball (.tgz / .tar.gz).
 
 Options
+  --from-npm <spec>       Fetch a published package from the registry, verify its
+                          dist.integrity hash, and analyse it in memory.
+  --registry <url>        Registry base URL for --from-npm.
+                          (default: https://registry.npmjs.org)
   --json                  Emit the machine-readable JSON document on stdout.
   --fail-on <severity>    Exit 1 at or above this severity.
                           critical | high | medium | low | none    (default: high)
@@ -117,13 +161,12 @@ plugin is clean" is the failure this split exists to prevent.
 
 ### Getting a package without installing it
 
-Never `pnpm add` a package you have not read. Two safe ways to get the bytes:
+Never `pnpm add` a package you have not read.
 
 ```console
-# From the registry. `npm pack` on a registry spec downloads and repacks; it does not install
-# and does not run the package's scripts.
-npm pack <name>@<version> --pack-destination /tmp
-dsh-inspect /tmp/<name>-<version>.tgz
+# From the registry, in one step. Reads the ~3 KB version document, downloads the tarball into
+# memory, verifies dist.integrity BEFORE anything parses it, and analyses it there.
+dsh-inspect --from-npm <name>@<version>
 
 # From git. Clone shallow and point the tool at the directory — do NOT use `npm pack` on a git
 # spec, which runs the package's `prepare` script.
@@ -131,10 +174,21 @@ git clone --depth 1 https://github.com/… /tmp/plugin
 dsh-inspect /tmp/plugin
 ```
 
-A tarball is decoded **entirely in memory**. Nothing is written to disk, which makes tar path
-traversal structurally impossible rather than something a filter has to catch. Every read ceiling
-is applied to the arriving stream rather than to a finished buffer, so a 28 MB archive holding one
-8 GB member is a refusal in under two seconds, not an out-of-memory kill.
+`--from-npm` is the only mode that opens a socket, and it is one flag per invocation: it cannot be
+combined with a local target, and a directory or tarball scan can never reach it — the fetch lives
+in a module the analysis path does not import. **A network fetch is not execution.** No subprocess,
+no disk write, no lifecycle script, and no `npm pack`. The report records the tarball URL, the
+digest that matched, and the registry's own `hasInstallScript` flag under `target.registry`.
+
+If the hash does not match what the registry published, the tool refuses and parses nothing. If the
+package predates `dist.integrity` entirely, the weaker `dist.shasum` is used and the report says
+`sha1` rather than claiming more. If neither is published, that is a refusal too.
+
+A tarball is decoded **entirely in memory**, from a file or from a fetch alike. Nothing is written
+to disk, which makes tar path traversal structurally impossible rather than something a filter has
+to catch. Every read ceiling is applied to the arriving stream rather than to a finished buffer, so
+a 28 MB archive holding one 8 GB member is a refusal in under two seconds, not an out-of-memory
+kill.
 
 ### Directory mode reads the working tree, not "the package"
 
@@ -154,30 +208,137 @@ a verdict.
 
 ## What it looks for
 
-Full catalogue with detection methods in [`PLAN.md`](./PLAN.md) §6. The short version:
-
-**Tier A** — install lifecycle scripts; a patch row disabling, re-enabling, or rewriting a core row
-(with `approval`, `permission`, `sandbox`, `sandbox-policy`, `fs-sandbox`, `fs-observation-policy`,
-`subprocess`, `credentials` and friends called out by name); the `!!js` inventory, classified by
-what each expression reaches; `!!js` in a field the loader never interpolates; `!js`, which is a
-hard parse error and proves the layer has never loaded anywhere; inserted rows naming modules the
-manifest does not declare; rows that re-map a service for their subtree with `isolate` or
-`intercept`; MCP server rows; `dsh.bundle.patch` paths that climb out of the package;
-skill-root redirection; a `dsh.profile.bundles` list, which makes the package a profile that mounts
-other packages; commands installed on your PATH; non-registry dependency specifiers; and injection
-phrasing in shipped instruction markdown, which is Tier A because the shipped bytes *are* the
-prompt.
-
-**Tier B** — capability-seam replacement via `ctx.provide` / `ctx.set`; system-prompt mutation;
-credential reads; network egress; the two of those together; `node:child_process`,
-`node:worker_threads`, `node:vm`; filesystem access outside `ctx.fs`; code built at runtime **and
-called**; nested plugin mounting; injection phrasing in registered tool `description` strings,
-which code assembles and which is therefore evadable.
-
-**Tier C** — minified source; computed member access, specifiers, and names; binaries and files
-over the read caps; a patch layer whose structure hit a walk ceiling; and build output with no
-source beside it, which is the one Tier C finding that does *not* degrade the analysis — the bytes
-were read exactly as they will run, and only their provenance is unverifiable.
+### Facts — no severity, always emitted
+
+| Fact | Source |
+|---|---|
+| `package.name`, `package.version`, `license`, `private` | `package.json` |
+| `mountsAsBundle` + patch file path | `dsh.bundle.patch` |
+| `shipsClientBundle` | `dsh.client` and `exports["./client"]` |
+| `insertedRows` — ids and plugin names this layer adds | patch YAML `insert[]` |
+| `targetedRows` — ids of existing rows this layer modifies | patch YAML top-level rows with `id` |
+| `dependencies`, `peerDependencies`, `optionalDependencies` counts and names | `package.json` |
+| `modelVisibleFiles` — shipped `SKILL.md` / skills / `AGENTS.md` / `CLAUDE.md` | file walk |
+| `filesRead`, `bytesRead`, `sourceFilesParsed` | analysis run |
+
+### Tier A — decidable, structured declaration, a real verdict
+
+Tier A reads declarations, not code. It is *much* harder to hide from than Tier B, because the
+harness itself must be able to read these fields literally in order to act on them: an attacker
+cannot obfuscate `disabled: true` and still have it disable anything. Every Tier A finding has
+confidence `certain`.
+
+| id | Check | Severity | Method |
+|---|---|---|---|
+| A1 | Install lifecycle script (`preinstall`, `install`, `postinstall`, `prepare`, `prepublish`, `preprepare`, `postprepare`) | medium | `package.json.scripts` key set. `dsh plugin add` forwards to pnpm verbatim and adds no `--ignore-scripts`, but pnpm ≥ 10 blocks a dependency's lifecycle scripts by default until the package is listed under `allowBuilds`, and `apps/cli/src/plugin.ts` prints that instruction when a build is blocked. The script is one approval away from running, not already running |
+| A2 | Patch row sets `disabled` **truthily** on a **security-relevant** core row (`approval`, `permission`, `sandbox`, `sandbox-policy`, `bash-sandbox`, `pwsh-sandbox`, `fs-sandbox`, `fs-observation-policy`, `subprocess`, `credentials`, `timeout-policy`, `spill-policy`, `session-persistence-jsonl`) | **critical** | patch YAML row with `id ∈ SECURITY_ROWS`. The loader coerces — `disabledOf` is `Boolean(options.disabled)` (`vendor/loader/src/config/entry.ts`) — so `null`, `0` and `""` leave the row **running** and are not this finding. A `!!js` node is an object and stays truthy, so an expression is judged by what it can evaluate to |
+| A3 | Patch row disables any other known core row | high for a `@deepseek-ai/dsh-base` row, medium for one only a surface bundle inserts | same, `id ∈ CORE_ROWS`. The row inventory records which of the three shipped bundles inserts each row, because they are not one profile: a `ui-*` row exists only where the web bundle is mounted. Suppressed entirely when the package under analysis *is* one of the three bundles — `@deepseek-ai/dsh-web-app` disabling two dozen rows `@deepseek-ai/dsh-base` inserted is what composing a surface bundle is |
+| A4 | Patch row carries a `name` that does not match the targeted row's `name` | medium | `applyEntryPatches` treats `name` on a non-insert patch as an **assertion guard**, not an override: on mismatch it warns and `continue`s, skipping the whole patch. So this row does nothing at all. Either the author is targeting a row that has been renamed, or the patch is stale — in both cases what the user reads and what mounts disagree |
+| A5 | Patch row overrides `config` / `inject` / `isolate` / `intercept` / `group` / any other key of an existing core row | medium (high for a security row) | patch YAML. Override is a **shallow whole-value replacement** (`target[key] = value`), never a deep merge, so overriding `config` discards the core row's entire configuration. `PatchOptions` carries a `[key: string]: any` index signature, so *any* key that is not `id`/`insert`/`name` is copied onto the target verbatim |
+| A6 | `!!js` expression inventory, with AST sub-classification (see the `!!js` table below) | low → critical by class | dialect parse + `new Function` parse-compile, never evaluated |
+| A7 | `!!js` in a field where the loader never interpolates it (`id`, `name`, `group`, `inject`, `intercept`, `isolate`) | medium | mirrors `metadataExpressionErrors`. Signal: the author believes it is live when it is inert — the plugin was very likely never validated |
+| A8 | `!js` (single bang) anywhere in the patch YAML | medium | `!js` is a **hard YAML parse error**, verified. Its presence proves the plugin has never been successfully loaded by any harness |
+| A9 | `insert` row naming a module that is neither this package nor any of its declared dependencies | high | set difference against `dependencies` ∪ `peerDependencies` ∪ own name. The layer mounts code whose provenance the manifest does not admit to |
+| A10 | MCP server row — an `insert`ed row whose `name` is `@deepseek-ai/dsh-mcp-client`. `transport: stdio` → **critical**; `transport: streamable-http` → high | **critical** / high | The stdio config is `{ command, args, env, cwd }` and it spawns that executable directly — **not** through `ctx.subprocess` or `ctx.sandbox`, with no approval and no tool gate. Every tool the server advertises is then registered as `mcp__<serverName>__<tool>` with model-visible descriptions this package does not control. `streamable-http` does not spawn but still imports an untrusted remote tool catalogue. Structured declaration, so Tier A |
+| A11 | Non-registry dependency specifier (`git+`, `github:`, `http(s):`, `file:`, `link:`) | high | the referenced code can change under a fixed version string |
+| A12 | Shipped model-visible instruction text (`SKILL.md`, `**/skills/*/SKILL.md`, `**/skills/*.md`, `AGENTS.md`, `CLAUDE.md`) | low as presence; escalated by B10 | file walk. See the reach note below |
+| A13 | No `files` allowlist in `package.json` | low | the published tarball is whatever happened to be in the working tree |
+| A14 | `dsh.bundle.patch` climbs out of the package directory — contains a `..` that escapes | **critical** | `loadProfile` computes the patch path as `join(packageDir, declared)` with **no sanitization** of `declared`, and `..` segments survive that join. An **absolute** path does not escape and is not this finding: `join('/…/pkg', '/etc/passwd')` is `/…/pkg/etc/passwd`, which is inside the package and simply does not exist — that is A16 |
+| A15 | Patch row redirects skill discovery into this package — sets `customSkillDirs` or `bundledSkillDir` on the `skill-filesystem` row | high | this is the declaration that turns shipped markdown into model-visible instructions. `bundledSkillDir` additionally carries `trustedHost: true`, which reads through raw Node `fs` and **bypasses the `ctx.fs` sandbox** |
+| A16 | `dsh.bundle.patch` names a file the package does not ship | medium | commonly a `files` allowlist that forgets it. Mounting the bundle fails the profile boot |
+| A17 | The declared patch layer does not parse | medium | the layer cannot load, and nothing inside it could be analysed |
+| A18 | `package.json` field of the wrong shape | low | the field was ignored. A manifest that npm and the harness read differently is worth knowing about |
+| A19 | Patch row sets `disabled` **falsily** on a core row | medium | the inverse of A2 and A3, and the one the coercion rule makes visible. Bundle layers apply after the profile's own, so a row the user deliberately switched off is switched back on by this one while the user's file still reads `disabled: true` |
+| A20 | `dsh.profile.bundles` names packages to mount as bundles | high | the launcher resolves each named package, reads its `dsh.bundle.patch`, and mounts that layer (`packages/boot/app-boot/src/profile.ts`). This package is then a profile, and everything those packages declare composes into it — none of which is in this analysis |
+| A21 | Injection phrasing in shipped instruction markdown | high | **Tier A rather than Tier B, and exempt from the Tier C downgrade.** There is no syntax between a `SKILL.md` and the model: the shipped bytes *are* the prompt, so there is nothing to obfuscate and nothing for a degraded parse to have made unreliable. What is heuristic is the reading of the sentence, not the reading of the file. Tool `description` hits stay Tier B (B10), because code assembles those |
+| A22 | `bin` installs a command on the user's PATH | low | linked into the profile's `node_modules/.bin` at install time. The harness never runs it; the user, a script, or an agent shell tool can |
+| A23 | Inserted row carries `isolate` or `intercept` on a catalogued service | **critical** for a security seam, high otherwise | `vendor/loader/src/config/isolate.ts` re-maps the named service to a fresh symbol realm for the row and every row beneath it, so a descendant injecting that name receives this subtree's implementation instead of the profile's. The same substitution as replacing the service in code, declared in YAML |
+
+**Reach note for A12, stated because getting this wrong would be dishonest.** Shipping a `SKILL.md`
+inside an npm package does **not** by itself put it in front of the model. There is no
+`dsh.skills` manifest field. The filesystem provider scans a fixed root set —
+`<project>/.dsh/skills`, `<project>/.agents/skills`, `$DSH_HOME/skills`,
+`$DSH_AGENTS_HOME/skills`, `bundledSkillDir` — at depth 1 only (`<root>/<name>/SKILL.md` or `<root>/<name>.md`), and a plugin's own `node_modules`
+directory is none of those. The three ways shipped text actually reaches the model are: the plugin
+calls `ctx.skills.register()` / `ctx.skills.registerProvider()` (→ B10 on the registered body), a
+patch row redirects a skill root into the package (→ A15), or the file is copied into the user's
+workspace by something else. `AGENTS.md` / `CLAUDE.md` are a separate subsystem again — discovered
+by walking the *workspace*, not the profile. So A12 on its own is `low` and its text says
+"shipped, reaches the model only if registered or redirected"; it escalates to `high` only when
+A15 or a `ctx.skills.register*` call is also present, or when B10's injection heuristics fire.
+
+### Tier B — AST capability detection, "this plugin CAN do X"
+
+Tier B parses shipped `.ts`/`.mts`/`.cts`/`.js`/`.mjs`/`.cjs` with the `typescript` compiler API —
+`ts.createSourceFile`, syntax only, **no program, no type checker, no module resolution, no
+transpilation, no execution**. Default confidence `high`, dropped to `moderate` when any Tier C
+readability finding fires.
+
+| id | Check | Severity | Method |
+|---|---|---|---|
+| B1 | Replaces a core capability seam — `ctx.provide(<seam>, …)` / `ctx.set(<seam>, …)` where `<seam>` is a key from `api-catalog.ts` | **critical** | call expression, literal first argument matched against the seam key set |
+| B2 | Auto-approves — a listener on `approval/request` that returns an approving verdict with no user interaction | **critical** | listener body return analysis |
+| B3 | `tools/pre-execute` listener returning `allow` | high | same |
+| B4 | Waterfall listener that never references `next` | high | The waterfall set is exactly 13 events: `agent/pre-step`, `agent/request`, `agent/request-error`, `approval/request`, `fs/edit-intent`, `fs/write-intent`, `llm/stream`, `session-telemetry/record`, `system-prompt/assemble`, `tools/code-dispatch-log`, `tools/execute`, `tools/post-execute`, `tools/pre-execute`. Per the harness's own rule, returning without calling `next()` short-circuits the chain **including the built-in behavior**, silently disabling the default for everyone downstream. Note there is **no** `fs/read-intent` — the intent family is write and edit only |
+| B5 | System-prompt mutation — `system-prompt/assemble` listener, or `ctx.systemPrompt.{section,context,variable,tools,suppressRuntimeContext}` | high | call matching |
+| B6 | Credential read — `process.env.*(TOKEN\|KEY\|SECRET\|PASSWORD\|CREDENTIAL)*`, `~/.dsh/credentials`, `~/.npmrc`, `~/.aws`, `~/.ssh`, `ctx.credentials.*` | medium alone | identifier + literal matching |
+| B7 | Network egress — `fetch`, `node:http(s).request`, `node:net`, `WebSocket`, `undici` | medium alone | import + call matching |
+| B8 | **Exfiltration pair** — B6 ∧ B7 in the same package | high | set intersection. Reported explicitly as *capability, not dataflow*: the tool cannot prove the credential value reaches the socket. `high` rather than critical because it fires on 18 % of published plugins |
+| B9 | Direct `node:child_process` / `node:worker_threads` / `node:vm` | medium alone, high paired with B8's two halves | import specifier. Bypasses `ctx.subprocess` and `ctx.sandbox` entirely. `medium` alone because a bare import fires on half the published ecosystem |
+| B10 | Prompt-injection heuristics on **model-visible text only** — registered tool `description` string literals, and shipped skill/instruction files | high | imperative-override phrasing, role reassignment, exfiltration instructions, hidden-text markers. Run on *exactly* the text that reaches the model, never on ordinary source comments |
+| B11 | Nested plugin mounting — `ctx.plugin(…)`, loader manipulation | high | call matching. A layer that mounts further layers moves the analysis target |
+| B12 | Dynamic code construction — `eval`, `new Function`, `vm.runInNewContext`, `module._load` | high | call matching |
+| B13 | Filesystem access outside `ctx.fs` — imports `node:fs` or `node:fs/promises` | medium | Reads and writes through the Node API are invisible to `fs/write-intent`, `fs/edit-intent`, `fs/observed`, and the `fs-sandbox` row, so no policy in the profile sees them and nothing appears in the session log |
+
+**The framing B7, B9, and B13 share.** The harness's own dynamic-package sandbox
+(`cordis-host-runner/src/sandbox.ts`) traps exactly `require`, `setTimeout`, `setInterval`,
+`setImmediate`, `clearTimeout`, `clearInterval`, and `fetch`, redirecting each to a `ctx` service;
+it leaves `process` `undefined` and exposes only the seven `HOST_BUILTIN_INSPECTION` globals.
+**An installed npm bundle layer gets none of that** — it is a plain ESM import into the harness
+process. So these three checks report a gap the harness itself defines: *the harness denies
+untrusted code this capability, and this package uses it from a position where nothing denies it.*
+That is the harness's reckoning, not a rule invented here.
+
+### Tier C — heuristic; "we cannot read this" is itself the finding
+
+| id | Check | Severity | Effect |
+|---|---|---|---|
+| C1 | Minified or obfuscated source — long lines that are **most of the file**, or a dense file of under five lines. One long line is an embedded prompt or a base64 asset, not minification, and the harness's own web bundle has one | medium | **degrades** |
+| C2 | Dynamic dispatch — computed member access on `ctx` (`ctx[expr]`), non-literal `import()`/`require()`, `atob`/`Buffer.from(…, 'base64')`, an assembled name passed to `.on`/`.set`/`.emit` **on a known context binding**. The receiver guard is the whole check: `.set` and `.get` are `Map`'s names too, and ``this.steps.set(`${turn}:${step}`, t)`` is a composite key, not evasion | high | **degrades** |
+| C3 | Ships built output with no corresponding source (`lib/` without `src/`) | low | **does not degrade** — the bytes were read exactly as written and exactly as they will run; what cannot be checked is whether they match the repository. Treating that as an unreadable package marks every ordinary published tarball degraded, because shipping built output and no source is what publishing *is* |
+| C4 | Unreadable payload — `.node`, `.wasm`, binaries, files over the size cap | medium | **degrades** |
+| C5 | The mounted layer hit a walk ceiling — nesting depth or node count | high | **degrades**. Rows past the ceiling were not read |
+| C6 | A `.min.js` artifact | low | **degrades** |
+
+### `!!js` sub-classification (A6)
+
+Every `!!js` node is inventoried with its YAML path and text, then parse-compiled with
+`new Function('return (' + expr + ')')` — compilation only; the constructor never executes the
+body — and the resulting AST is classified.
+
+Classification is by **reach**, not by syntactic form. `dshHomePath('sessions')` and `steal()` are
+both `CallExpression`s; the first is a helper `dsh-app-boot` puts in scope with
+`ctx.provide('dshHomePath', dshHomePath)` before any entry mounts, documented as such in that
+package's README, and used by the base bundle's own `session-persistence-jsonl` row.
+
+| Class | Example | Severity | Finding |
+|---|---|---|---|
+| `literal` | `true`, `3` | — | fact only |
+| `inert-read` | `process.env.DSH_TOOLS_MODE`, `process.platform === 'win32'`, `ctx.webStartup.host` | — | fact only |
+| `harness-call` | `dshHomePath('sessions')`, `process.cwd()` | low | A6 |
+| `call` | a call this tool cannot resolve | medium | A6 |
+| `mutation` | `process.env.X = …` | high | A6 |
+| `module-access` | `require(…)`, `import(…)`, `globalThis[…]` | **critical** | A6 |
+| `unparseable` | syntax error | medium — and it means the plugin cannot boot | A6 |
+
+The two classes with no reach are counted in `facts.jsExpressions` and never raised: a constant, or
+a read of a service the profile already handed the row, warrants no decision, and the shipped
+bundles are mostly made of them.
+
+The escalation of the rest is justified: the evaluator is
+`new Function('ctx', 'expr', 'with (ctx) { return eval(expr) }')` — unrestricted eval, with `ctx`
+in scope. And `disabled` re-evaluates at **every mount decision**, so a `!!js` there is not a
+one-shot: it is a recurring execution point that user patch layers HMR-reload live.
 
 ## The ceiling
 
@@ -187,6 +348,12 @@ The tool does not run in the harness process, does not gate installation, and ca
 anything. It raises the cost of shipping a hostile plugin and gives you something to read where
 today you see nothing. That is the whole claim.
 
+A seam at which an install *could* be stopped does exist — `dsh plugin add` runs pnpm in the
+profile directory, pnpm honours a `.pnpmfile.cjs` there, and throwing from its async `readPackage`
+hook aborts the install with nothing written to `node_modules`. Nothing in 0.2 uses it.
+[`ADR.md`](./ADR.md) §11 records the seam and why shipping a gate on this release's calibration
+would have burned the idea.
+
 ### What is not statically decidable
 
 1. **`!!js` semantics.** The loader evaluates these with
@@ -207,13 +374,20 @@ today you see nothing. That is the whole claim.
 6. **Intent.** Tier B's `B8` is the sharpest case: the tool proves a package *can* read a
    credential and *can* open a socket. It has not shown that the value flows between them, and it
    cannot — that needs value tracking this tool does not do. Any telemetry library or
-   authenticated API client trips `B8` legitimately.
+   authenticated API client trips `B8` legitimately. It fires on 18 % of published plugins, which
+   is why it is `high` and not `critical`.
+7. **Injection phrasing that is not spelled in ASCII.** The injection heuristics are Latin-alphabet
+   regexes. Substituting Cyrillic homoglyphs — `о` U+043E for `o`, `е` U+0435 for `e` — defeats
+   **every one of the ten rules**, including the zero-width-character rule, which looks for
+   invisible characters and not for visible ones that are the wrong letter. Verified against the
+   rule table, not assumed. Normalisation is not in 0.2; do not read a clean `A21`/`B10` as
+   evidence that shipped markdown carries no instructions.
 
 ### Every Tier B check has a one-line bypass
 
 `ctx['pro' + 'vide']('approval', …)` defeats seam detection. A computed specifier defeats every
 import check. A base64 event name defeats every listener check. Splitting a credential read and a
-network call across two packages defeats `B8`.
+network call across two packages defeats `B8`. A Cyrillic `о` defeats every injection rule.
 
 **Tier A is much harder to hide from, because it is structured declaration rather than code.**
 The harness must read `disabled: true` literally in order to disable anything, so there is no
@@ -232,8 +406,9 @@ that could be read.*
 
 ## Development
 
-Node `^22.19.0 || >=24` and pnpm are the only requirements; there is no network and no harness
-checkout in any test.
+Node `^22.19.0 || >=24` and pnpm are the only requirements. No test reaches a network or a harness
+checkout: every registry case injects its own `fetch`, and one of them replaces the global with a
+throwing stub to prove a directory or tarball scan never calls it.
 
 ```console
 pnpm install
@@ -242,8 +417,17 @@ pnpm run test               # unit suite
 pnpm run test:coverage      # same suite, with the coverage ratchet
 pnpm run test:e2e           # builds, then runs the real binary as a subprocess
 pnpm run inspect <target>   # run from source without building
+pnpm run sweep -- --check   # the one thing here that DOES use a network
 ```
 
+`pnpm run sweep` is the ecosystem measurement. It fetches the pinned corpus in
+`scripts/ecosystem-corpus.json` through the same verified in-memory path as `--from-npm`, prints the
+distribution, and with `--check` exits non-zero when a fresh run is worse than
+`tests/ecosystem-baseline.json`. `--discover` rebuilds the corpus from the most-starred repositories
+carrying the topic; `--pin` moves every entry to the version current now; `--record` rewrites the
+baseline. It runs from its own weekly workflow, never from CI — every other workflow here runs
+without a network, and a unit suite that cannot reach one is easier to trust.
+
 Hostile fixtures live in `tests/fixtures/` and are authored here — a plugin that disables the
 approval row, one whose `!!js` calls `child_process`, one with a `postinstall`, one pairing a
 credential read with `fetch`, one shipping a `SKILL.md` full of injection text, one declaring an
@@ -257,8 +441,8 @@ expressions, and its module top level all write a sentinel file, and the test as
 does not exist after a full analysis. `node:child_process` and the write half of `node:fs` are
 mocked to throw for the whole suite, so a stray call fails the tests rather than passing quietly.
 
-Design decisions are in [`ADR.md`](./ADR.md); the scope, catalogue, and phasing are in
-[`PLAN.md`](./PLAN.md).
+Design decisions are in [`ADR.md`](./ADR.md); the check catalogue is under
+[What it looks for](#what-it-looks-for).
 
 ## Reporting a problem
 

package/lib/checks/tier-a.js

@@ -69,7 +69,7 @@ const INERT_CLASSES = new Set(['literal', 'inert-read']);
  * @returns the complete finding.
  */
 function tierA(finding) {
-    return { ...finding, tier: 'A', confidence: 'certain', bypass: null };
+    return { ...finding, tier: 'A', confidence: 'certain', bypass: null, examples: [finding.evidence], occurrences: 1 };
 }
 /**
  * Whether the package under analysis is itself one of the harness's shipped
@@ -131,6 +131,7 @@ function checkDisabledRows(input) {
                 findings.push(tierA({
                     checkId: 'A19',
                     name: 'core-row-force-enabled',
+                    subject: override.id,
                     severity: 'medium',
                     title: `Patch layer re-enables the core row "${override.id}"`,
                     detail: 'The loader coerces `disabled` with `Boolean()`, so this value leaves the row running. Because '
@@ -145,6 +146,7 @@ function checkDisabledRows(input) {
                 findings.push(tierA({
                     checkId: 'A2',
                     name: 'security-row-disabled',
+                    subject: override.id,
                     severity: 'critical',
                     title: `Patch layer disables the core row "${override.id}"`,
                     detail: `Bundle patches apply after @deepseek-ai/dsh-base, so this layer switches off ${stops}. `
@@ -161,6 +163,7 @@ function checkDisabledRows(input) {
             findings.push(tierA({
                 checkId: 'A3',
                 name: 'core-row-disabled',
+                subject: override.id,
                 severity,
                 title: `Patch layer disables the core row "${override.id}"`,
                 detail: `The row comes from ${coreRowOrigin(override.id)}, and this layer applies after it, so the row `
@@ -189,6 +192,7 @@ function checkOverriddenRows(input) {
                 findings.push(tierA({
                     checkId: 'A4',
                     name: 'patch-name-guard-mismatch',
+                    subject: override.id,
                     severity: 'medium',
                     title: `Patch for "${override.id}" names ${override.nameGuard}, but that row is ${coreName}`,
                     detail: 'applyEntryPatches treats `name` on a non-insert patch as an assertion guard: on mismatch it '
@@ -205,6 +209,7 @@ function checkOverriddenRows(input) {
             findings.push(tierA({
                 checkId: 'A5',
                 name: 'core-row-overridden',
+                subject: `${override.id}:${rewritten.join(',')}`,
                 severity: isSecurity ? 'high' : 'medium',
                 title: `Patch layer rewrites ${rewritten.map(key => `\`${key}\``).join(', ')} on the core row "${override.id}"`,
                 detail: `The row is ${coreName}. Patch overrides are shallow whole-value replacements, not merges, so `
@@ -249,6 +254,7 @@ function liveExpression(file, site) {
     return tierA({
         checkId: 'A6',
         name: 'js-expression',
+        subject: `${site.slot}:${site.classification}`,
         severity: EXPRESSION_SEVERITY[site.classification],
         title: `\`!!js\` expression in a row's \`${site.slot}\` ${EXPRESSION_MEANING[site.classification]}`,
         detail: `The loader evaluates this with new Function('ctx', 'expr', 'with (ctx) { return eval(expr) }') — `
@@ -270,6 +276,7 @@ function inertExpression(file, site) {
     return tierA({
         checkId: 'A7',
         name: 'js-expression-inert',
+        subject: 'inert-slot',
         severity: 'medium',
         title: '`!!js` in a field the loader never interpolates',
         detail: 'The loader interpolates only a row\'s `config` (recursively) and the top-level node of its `disabled`. '
@@ -285,6 +292,7 @@ function checkPatchFailures(input) {
         ? tierA({
             checkId: 'A8',
             name: 'single-bang-js-tag',
+            subject: failure.file,
             severity: 'medium',
             title: 'Patch layer uses the `!js` tag, which no harness accepts',
             detail: 'The dialect registers exactly one custom tag, `tag:yaml.org,2002:js`, whose shorthand is `!!js`. '
@@ -295,6 +303,7 @@ function checkPatchFailures(input) {
         : tierA({
             checkId: 'A17',
             name: 'patch-parse-error',
+            subject: failure.file,
             severity: 'medium',
             title: 'Patch layer does not parse',
             detail: 'The declared patch layer cannot be read as a Cordis entry list, so mounting this package fails the '
@@ -321,6 +330,7 @@ function checkInsertedModules(input) {
             findings.push(tierA({
                 checkId: 'A9',
                 name: 'insert-undeclared-module',
+                subject: name,
                 severity: isCore ? 'medium' : 'high',
                 title: `Inserted row "${row.id ?? '(unnamed)'}" mounts ${name}, which this package does not declare`,
                 detail: isCore
@@ -352,6 +362,7 @@ function checkMcpRows(input) {
             findings.push(tierA({
                 checkId: 'A10',
                 name: 'mcp-server-row',
+                subject: shown,
                 severity: stdio ? 'critical' : 'high',
                 title: stdio
                     ? `Patch layer starts a local MCP server by running \`${shown}\``
@@ -389,6 +400,7 @@ function checkSkillRootRedirect(input) {
         findings.push(tierA({
             checkId: 'A15',
             name: 'skill-root-redirected',
+            subject: keys.join(','),
             severity: 'high',
             title: `Patch layer redirects skill discovery via ${keys.map(key => `\`${key}\``).join(', ')}`,
             detail: 'Skill files reach the model verbatim, unescaped and uncapped. This row changes which directories '
@@ -412,6 +424,7 @@ function checkManifest(input) {
         findings.push(tierA({
             checkId: 'A1',
             name: 'install-lifecycle-script',
+            subject: name,
             severity: 'medium',
             title: `Declares a \`${name}\` script, which runs at install time once allowed`,
             detail: 'This command would run at the user\'s uid as part of `dsh plugin add`, before the user has read a '
@@ -427,6 +440,7 @@ function checkManifest(input) {
         findings.push(tierA({
             checkId: 'A22',
             name: 'installs-command',
+            subject: command,
             severity: 'low',
             title: `Installs the command \`${command}\` on the user's PATH`,
             detail: 'A `bin` entry is linked into the profile\'s `node_modules/.bin` at install time. It is not run by '
@@ -440,6 +454,7 @@ function checkManifest(input) {
         findings.push(tierA({
             checkId: 'A20',
             name: 'profile-mounts-bundles',
+            subject: 'dsh.profile.bundles',
             severity: 'high',
             title: `Declares a profile that mounts ${profileBundles.length} bundle(s)`,
             detail: 'A `dsh.profile.bundles` list makes this package a profile rather than a layer: the launcher resolves '
@@ -459,6 +474,7 @@ function checkManifest(input) {
         findings.push(tierA({
             checkId: 'A11',
             name: 'non-registry-dependency',
+            subject: `${field}.${name}`,
             severity: 'high',
             title: `Depends on ${name} through a non-registry specifier`,
             detail: 'The code behind this specifier can change without the version of this package changing, so nothing '
@@ -471,6 +487,7 @@ function checkManifest(input) {
         findings.push(tierA({
             checkId: 'A13',
             name: 'no-files-allowlist',
+            subject: 'files',
             severity: 'low',
             title: 'No `files` allowlist in package.json',
             detail: 'Without an allowlist the published tarball is whatever was in the working tree minus npm\'s default '
@@ -485,6 +502,7 @@ function checkManifest(input) {
             findings.push(tierA({
                 checkId: 'A14',
                 name: 'bundle-patch-escapes-package',
+                subject: 'dsh.bundle.patch',
                 severity: 'critical',
                 title: 'The declared `dsh.bundle.patch` path climbs out of the package directory',
                 detail: 'The launcher resolves the patch as join(packageDir, declared) with no sanitisation, and `..` '
@@ -497,6 +515,7 @@ function checkManifest(input) {
             findings.push(tierA({
                 checkId: 'A16',
                 name: 'bundle-patch-missing',
+                subject: 'dsh.bundle.patch',
                 severity: 'medium',
                 title: 'The declared `dsh.bundle.patch` file is not in the package',
                 detail: 'The package declares a mounted patch layer whose file is absent — commonly a `files` allowlist '
@@ -511,6 +530,7 @@ function checkManifest(input) {
         findings.push(tierA({
             checkId: 'A18',
             name: 'manifest-defect',
+            subject: defect,
             severity: 'low',
             title: `Malformed package.json field: ${defect}`,
             detail: 'The field was ignored. A manifest that npm and the harness read differently is worth knowing about.',
@@ -526,6 +546,7 @@ function checkModelVisibleText(input) {
     return [tierA({
             checkId: 'A12',
             name: 'model-visible-text-shipped',
+            subject: 'shipped-instructions',
             severity: 'low',
             title: `Ships ${input.modelVisibleFiles.length} model-visible instruction file(s)`,
             detail: 'Skill and agent-instruction markdown reaches the model verbatim, unescaped and uncapped. Shipping it '
@@ -548,6 +569,7 @@ function checkServiceRemapping(input) {
                 findings.push(tierA({
                     checkId: 'A23',
                     name: 'row-service-remapping',
+                    subject: `${field}:${seams.join(',')}`,
                     severity: critical ? 'critical' : 'high',
                     title: `Inserted row "${row.id ?? '(unnamed)'}" re-maps ${seams.map(name => `\`${name}\``).join(', ')} via \`${field}\``,
                     detail: field === 'isolate'
@@ -583,9 +605,11 @@ function checkInjectionText(input) {
         if (text === undefined)
             continue;
         for (const match of scanInjection(text)) {
+            const evidence = { file: path, path: lineColumn(text, match.index), snippet: snippet(match.excerpt) };
             findings.push({
                 checkId: 'A21',
                 name: 'model-visible-injection',
+                subject: match.ruleId,
                 tier: 'A',
                 severity: 'high',
                 confidence: 'certain',
@@ -595,7 +619,9 @@ function checkInjectionText(input) {
                     + 'model, which is why this is a verdict about the text rather than a capability report. Whether the '
                     + 'sentence is an instruction or a discussion of one is a judgement this tool cannot make: the pattern '
                     + 'will miss a rephrasing, and it can fire on a document that legitimately quotes an attack.',
-                evidence: { file: path, path: lineColumn(text, match.index), snippet: snippet(match.excerpt) },
+                evidence,
+                examples: [evidence],
+                occurrences: 1,
                 bypass: null,
             });
         }