@platformos/platformos-mcp-supervisor 0.1.0 → 0.2.0

package/dist/result/response-budget.js

@@ -17,9 +17,11 @@
  * Within a file and bucket, entries are taken from the FRONT, so what survives is the head
  * of a list already ordered by line and column — where the root cause of a cascade is.
  *
- * A STREAM THAT CANNOT FIT IS CLOSED, not skipped: once a bucket's next entry does not fit
- * it takes nothing further, so the returned list stays a contiguous head rather than a
- * scattered sample.
+ * A STREAM THAT CANNOT FIT TAKES NOTHING FURTHER, so the returned list stays a contiguous
+ * head rather than a scattered sample. That comes from `taken` not advancing — a retried
+ * entry costs the same and `spent` only grows, so it can never fit later. Closing the
+ * stream only saves the retry, and earns its keep there: 1.9 ms against 61 ms on a batch of
+ * blocked files, same output.
  *
  * ONE ERROR PER FILE IS GUARANTEED, budget or not — a blocked write with an empty `errors`
  * list names a problem and then declines to say what it is. Bounded: one entry per file,

package/dist/result/types.d.ts

@@ -134,53 +134,56 @@ export interface ValidateCodeDiagnostic {
     see_also?: string;
 }
 /**
- * Applicability of the blast-radius answer. Distinguishes a real "nothing depends on this"
- * (`computed`, total 0 — safe to change) from "we could not find out" (`unavailable`) and
- * from "this file type has no dependency graph" (`not_applicable`), so a failed lookup can
- * never be misread as a green light.
+ * Whether the cross-file comparison ran. `computed` means this file's dependants were linted
+ * with the change applied and without it; `unavailable` means that could not be done (a
+ * failure, or the deadline); `not_applicable` means the file has no dependants this stage
+ * can find — the graph holds no edges pointing at it, or it has no logical name.
  *
- * `not_applicable` covers files that are not graph-trackable edge targets (schema /
- * custom-model-type / translation YAML): they are wired by model/table NAME, not by file
- * reference (see ADR 004), so `total: 0` would falsely read as "safe to change". It also
- * covers a source in no platformOS directory, which has no logical name to reference.
+ * `disabled` means this SERVER was started with cross-file impact turned off (`--no-impact`),
+ * so nothing was attempted and retrying will not change that — which is the whole reason it
+ * is not folded into `unavailable`.
+ *
+ * NONE OF THE FOUR IS A CLEARANCE, including `computed`. See {@link ValidateCodeImpact}.
  */
-export type ValidateCodeImpactStatus = 'computed' | 'unavailable' | 'not_applicable';
+export type ValidateCodeImpactStatus = 'computed' | 'unavailable' | 'not_applicable' | 'disabled';
 /**
- * Cross-file "blast radius" of editing the file: who DEPENDS ON it, which lint cannot see
- * (lint is per-file, forward-looking). Derived per request from the project's own text
- * with the changeset's buffers overlaid.
+ * What this change BREAKS in files the request is not editing — the question lint cannot
+ * answer, being per-file and forward-looking. Derived per request by linting the edited
+ * file's dependants twice, with the changeset applied and without it, and reporting only the
+ * difference. The findings are the check engine's own, so they carry its message, severity
+ * and documentation link rather than a second opinion invented here.
  *
- * `scope` is always `direct` (immediate callers only — transitive closure is noise).
- * `dependents` is meaningful ONLY when `status` is `computed`; otherwise it is zeroed and
- * the status says why.
+ * IT DOES NOT ANSWER "WHO DEPENDS ON THIS FILE", and never will: `{% render var %}` names its
+ * target at runtime, so no static analysis can enumerate a file's dependants, and a count
+ * that omits the ones it cannot see reads as a licence to delete. Only findings are
+ * published; their absence claims nothing.
  */
 export interface ValidateCodeImpact {
-    scope: 'direct';
     status: ValidateCodeImpactStatus;
-    dependents: {
-        /** Number of distinct files that reference the edited file. */
-        total: number;
-        /** Distinct referencing files per edge kind (render/include/function/…); a file using two kinds counts in both. */
-        by_kind: Record<string, number>;
-        /** Up to 10 distinct referencing files, project-relative, sorted. */
-        sample: string[];
-    };
     /**
-     * Dependent callers whose arguments do NOT match the edited file's `{% doc %}`
-     * signature — the cross-file counterpart to the `PartialCallArguments` lint check.
-     * Present ONLY when the edited buffer declares a `{% doc %}` block: an empty array means
-     * "checked, every caller matches", absent means "no contract to check against".
+     * Files the change broke, each with the findings it GAINED. A finding already present
+     * before the change is not reported, however severe: it is not this edit's doing.
+     *
+     * PRESENT ONLY WHEN NON-EMPTY, and absence is not a clearance — it means no break was
+     * found among the dependants that are visible, which is not the same as none existing.
+     */
+    breaks?: ValidateCodeImpactBreak[];
+    /**
+     * Present only when more dependants were found than the bound allows: `returned` were
+     * linted, `total` were found.
+     *
+     * NOT the same kind of truncation as the result-level `truncated`, which withholds
+     * findings that WERE computed. The difference here was never checked at all, so an
+     * otherwise-clean answer carrying this field is a PARTIAL one.
      */
-    signature_risk?: ValidateCodeSignatureRisk[];
+    unchecked_dependants?: ValidateCodeBucketTruncation;
 }
-/** One dependent caller at risk from the edited file's current `{% doc %}` signature. */
-export interface ValidateCodeSignatureRisk {
-    /** The referencing file, project-relative. */
-    caller: string;
-    /** Required `@param`s the caller does not pass. */
-    missing_required: string[];
-    /** Arguments the caller passes that the `{% doc %}` block does not declare. */
-    unexpected_args: string[];
+/** One file the change broke, and what it broke in it. */
+export interface ValidateCodeImpactBreak {
+    /** The broken file, project-relative. NOT a file the request asked about. */
+    file: string;
+    /** The findings this change introduced there, in reading order. */
+    diagnostics: ValidateCodeDiagnostic[];
 }
 /** How many entries of one bucket were returned, against how many were found. */
 export interface ValidateCodeBucketTruncation {
@@ -215,9 +218,8 @@ export interface ValidateCodeResult {
     warnings: ValidateCodeDiagnostic[];
     infos: ValidateCodeDiagnostic[];
     /**
-     * Cross-file blast radius: who depends on the edited file. Always present; `status`
-     * distinguishes a real "nothing depends on this" from "not computed".
-     * See {@link ValidateCodeImpact}.
+     * Cross-file consequence of the edit: what it breaks in files you are not editing.
+     * Always present, and never a clearance. See {@link ValidateCodeImpact}.
      */
     impact: ValidateCodeImpact;
     /** Deterministic prose telling the agent what to do next. */

package/dist/transport/instructions.js

@@ -102,10 +102,26 @@ truncated
   what is listed and validate again to see the rest.
 
 impact
-  Which other files depend on this one, worked out from the project as it stands at the
-  moment of the call. \`status: unavailable\` means it could not be worked out — a failure,
-  or it ran out of time — and its zeroed counts are NOT a claim that nothing depends on
-  the file. Only \`status: computed\` with \`total: 0\` says that.
+  What this change BREAKS in files you are NOT editing — the one thing a per-file lint cannot
+  see, since it only ever looks at the buffers you sent. Each entry names the file and
+  carries the check's own findings: same message, same severity, same documentation link, and
+  the same fixes, exactly as if you had validated that file yourself.
+  It reports only what your change INTRODUCED. A problem that file already had is never
+  listed, however severe — it is not this edit's doing, and it would bury the one that is.
+  A break in someone else's file does NOT set must_fix_before_write: your buffer may be
+  perfectly correct. Fix the callers, or decide not to; that is yours to weigh.
+  status  computed        the dependants were linted with your change and without it
+          not_applicable  nothing can reference this file by name
+          unavailable     could not be run: a failure, a deadline, or a file referenced from
+                          more text than can be examined in time
+          disabled        this server runs with --no-impact, so nothing was attempted
+  unchecked_dependants appears when a file has more dependants than one request will lint.
+  Those were never checked, so an otherwise-clean answer carrying it is a PARTIAL one.
+  NOTHING HERE IS A CLEARANCE. An empty impact means no break was found among the dependants
+  that are VISIBLE, and a dependant can be invisible: {% render partial_name %} picks its
+  target at runtime, so no analysis can resolve it.
+  This server never tells you nothing depends on a file — if you are about to delete or
+  rename one, search the project yourself.
 
 WHAT IS NOT CHECKED
 ${coverage()} run against your buffer. Where a finding exists it explains itself and links
@@ -118,8 +134,10 @@ as finding it correct, and where no diagnostic can tell you so.
   rather than refuse. {{ 5 | upcase }} renders and is not reported. That silence is the
   documentation's answer, not a guarantee the value is right.
 
-  The SHAPE of a model schema is not checked. An unknown property is not reported,
-  because the platform accepts it.
+  A model schema's property TYPE is checked and an unknown one is reported. The rest of a
+  schema's shape is not: an unrecognised top-level key is rejected on deploy and nothing
+  reports it, so silence there is not a claim the key is valid. A duplicated property name
+  IS accepted by the platform.
 
   Duplicate YAML keys are compared the way the platform's own parser resolves them, so
   yes: and true: in one mapping are reported as the one key they become. That comparison

package/dist/transport/server.d.ts

@@ -16,6 +16,11 @@ export interface ServerOptions {
     log?: Logger;
     /** Advertised server version. */
     version?: string;
+    /**
+     * Whether cross-file impact runs. Defaults to ON — only an explicit `false`, from
+     * `--no-impact` or `POS_SUPERVISOR_NO_IMPACT`, turns it off.
+     */
+    impactEnabled?: boolean;
 }
 export interface ServerHandle {
     server: McpServer;

package/dist/transport/server.js

@@ -17,10 +17,14 @@ const DEFAULT_VERSION = '0.0.1';
 export async function startServer(opts) {
     const log = opts.log ?? createLogger(SERVER_NAME);
     // NOTHING IS BUILT OR WARMED HERE, by design. check-node owns one lazy `App` per project
-    // at process level and reconciles it per call, and the blast radius is derived per
-    // request from the project's text (`impact/project-scan.ts`) — so there is no graph to
-    // build at boot, nothing to keep fresh, and no "still computing" answer.
-    const context = { projectDir: opts.projectDir, log };
+    // at process level and reconciles it per call, and impact is derived per request from
+    // the project's text (`impact/project-scan.ts`) — so there is no graph to build at boot,
+    // nothing to keep fresh, and no "still computing" answer.
+    const context = {
+        projectDir: opts.projectDir,
+        log,
+        impactEnabled: opts.impactEnabled,
+    };
     // `instructions` reaches the model with the tool list; without them an agent has only the
     // tool description to go on and invents a reading of the result (see instructions.ts).
     const server = new McpServer({ name: SERVER_NAME, version: opts.version ?? DEFAULT_VERSION }, { instructions: SERVER_INSTRUCTIONS });

package/dist/transport/validate-code.d.ts

@@ -22,6 +22,23 @@ import type { SupervisorContext } from '../context.js';
 import type { ValidateCodeParams, ValidateCodeResult, ValidateFilesResult } from '../result/types.js';
 import { type ValidateAdapters } from '../validate/validate-buffers.js';
 import { MAX_BATCH_BYTES, MAX_BATCH_FILES } from '../validate/batch-bounds.js';
+/**
+ * zod raw shape for the tool input (validated by the MCP SDK before dispatch).
+ *
+ * Both forms are optional at the schema level and the handler requires exactly one,
+ * because a zod union of two object shapes defeats the SDK's JSON-Schema conversion
+ * — it emits `anyOf`, which several MCP clients do not surface to the model at all.
+ * Two optional fields with a documented rule converts cleanly and reads clearly.
+ *
+ * WHAT THE MODEL SEES IS THE CONVERSION, NOT THIS. Everything an agent knows about
+ * the arguments arrives as the JSON Schema this shape converts to, so a constraint
+ * that does not convert may as well not be advertised at all. Prefer a zod builtin
+ * over a `.refine` wherever one expresses the rule; `transport/validate-code.spec.ts`
+ * pins the emitted document end to end.
+ *
+ * Typed as `ZodRawShape` (not the inferred literal shape) so `registerTool` does not
+ * instantiate excessively deeply over the schema (TS2589 under zod 3.25).
+ */
 export declare const VALIDATE_CODE_INPUT: ZodRawShape;
 /**
  * The agent-facing prose, exported so tests can pin claims that must not rot. The

package/dist/transport/validate-code.js

@@ -22,22 +22,29 @@ import { validateBuffers, } from '../validate/validate-buffers.js';
 import { MAX_BATCH_BYTES, MAX_BATCH_FILES, batchTooLarge } from '../validate/batch-bounds.js';
 import { collidingBufferPaths } from '../validate/batch-coherence.js';
 import { assembleNotApplicableResult } from '../result/assemble.js';
-/** A non-blank path. Blank is malformed input, refused at the protocol boundary. */
-const filePath = z
-    .string()
-    .refine((value) => value.trim().length > 0, { message: 'file_path must not be empty' });
-const content = z.string();
 /**
- * zod raw shape for the tool input (validated by the MCP SDK before dispatch).
+ * A non-blank path. Blank is malformed input, refused at the protocol boundary.
  *
- * Both forms are optional at the schema level and the handler requires exactly one,
- * because a zod union of two object shapes defeats the SDK's JSON-Schema conversion
- * — it emits `anyOf`, which several MCP clients do not surface to the model at all.
- * Two optional fields with a documented rule converts cleanly and reads clearly.
+ * BOTH halves are load-bearing and neither is redundant. The refinement is what
+ * refuses a whitespace-only path; `.min(1)` is the half that SURVIVES conversion to
+ * JSON Schema, as `minLength`. A refinement converts to nothing at all, so with the
+ * refinement alone the rule exists only on this side of the wire — the model is
+ * never told, sends `""`, and learns the rule from a rejection. Drop either half and
+ * a test fails: the emitted schema loses `minLength`, or `'   '` starts being accepted.
  *
- * Typed as `ZodRawShape` (not the inferred literal shape) so `registerTool` does not
- * instantiate excessively deeply over the schema (TS2589 under zod 3.25).
+ * A FUNCTION, not a shared constant, for the same wire-level reason: the SDK's
+ * converter dedupes by schema IDENTITY, so one instance reused across both input
+ * forms emits `{ $ref: '#/properties/file_path' }` for the second use. That drags the
+ * single-file description into the batch entries, where "Pair with `content`" is
+ * wrong, and puts a `$ref` in a tool inputSchema — which not every MCP client
+ * resolves. A fresh instance per use costs nothing and emits in full.
  */
+const filePath = () => z
+    .string()
+    .min(1)
+    .refine((value) => value.trim().length > 0, { message: 'file_path must not be empty' });
+/** File contents. Empty is legal — an empty file is a file. Fresh per use, as above. */
+const content = () => z.string();
 /**
  * An example path of each kind, for the agent-facing prose below.
  *
@@ -52,16 +59,36 @@ const exampleOf = (type, name) => `${getAppPaths(type)[0]}/${name}.liquid`;
 const EXAMPLE_PARTIAL = exampleOf(PlatformOSFileType.Partial, 'card');
 const EXAMPLE_PAGE = exampleOf(PlatformOSFileType.Page, 'home');
 const EXAMPLE_PROMO = exampleOf(PlatformOSFileType.Partial, 'promo');
+/**
+ * zod raw shape for the tool input (validated by the MCP SDK before dispatch).
+ *
+ * Both forms are optional at the schema level and the handler requires exactly one,
+ * because a zod union of two object shapes defeats the SDK's JSON-Schema conversion
+ * — it emits `anyOf`, which several MCP clients do not surface to the model at all.
+ * Two optional fields with a documented rule converts cleanly and reads clearly.
+ *
+ * WHAT THE MODEL SEES IS THE CONVERSION, NOT THIS. Everything an agent knows about
+ * the arguments arrives as the JSON Schema this shape converts to, so a constraint
+ * that does not convert may as well not be advertised at all. Prefer a zod builtin
+ * over a `.refine` wherever one expresses the rule; `transport/validate-code.spec.ts`
+ * pins the emitted document end to end.
+ *
+ * Typed as `ZodRawShape` (not the inferred literal shape) so `registerTool` does not
+ * instantiate excessively deeply over the schema (TS2589 under zod 3.25).
+ */
 export const VALIDATE_CODE_INPUT = {
-    file_path: filePath
+    file_path: filePath()
         .optional()
         .describe('Path of the file to validate, absolute or relative to the project root ' +
         `(e.g. "${EXAMPLE_PARTIAL}"). Pair with \`content\`.`),
-    content: content
+    content: content()
         .optional()
         .describe('The exact file contents you are about to write. Pair with `file_path`.'),
     files: z
-        .array(z.object({ file_path: filePath, content }))
+        .array(z.object({
+        file_path: filePath().describe('Path of THIS file, absolute or relative to the project root.'),
+        content: content().describe('The exact contents you are about to write to THIS file.'),
+    }))
         .min(1)
         .max(MAX_BATCH_FILES)
         .optional()
@@ -138,9 +165,20 @@ export async function runValidateCode(ctx, params, overrides = {}) {
     }
     const { buffers, isBatch } = requested;
     ctx.log(isBatch ? `validate_code: ${buffers.length} file(s)` : `validate_code: ${buffers[0].filePath}`);
-    // Both refusals are request-level and impossible with a single buffer, so they are
-    // decided here, before any work starts. First refusal wins; the cheaper check runs first.
-    const refusal = isBatch
+    // Request-level refusals, decided before any work starts. First refusal wins; the cheaper
+    // check runs first.
+    //
+    // GATED ON MORE THAN ONE BUFFER, not on which form carried it. One file is one file, and
+    // the two forms must answer identically — the shape an agent happened to reach for cannot
+    // change a verdict. Both refusals ask a question a lone buffer cannot answer YES to:
+    // collision needs two entries naming one file, and the caps exist because a batch can hand
+    // the server work no single buffer could. Collision was already a no-op at one buffer; the
+    // total-byte cap was NOT, and it fired FIRST — so a 300 KiB file sent as a one-file batch
+    // was refused with "split it into smaller batches", advice its caller cannot follow, and
+    // was never told MAX_BUFFER_BYTES, the bound it actually had to get under. Whether ONE
+    // buffer is admissible is `bufferTooLarge`'s question, asked per buffer inside
+    // `validateBuffers` for both forms alike.
+    const refusal = buffers.length > 1
         ? (batchTooLarge(buffers) ?? collidingBufferPaths(ctx.projectDir, buffers))
         : undefined;
     if (refusal) {

package/dist/validate/batch-bounds.js

@@ -39,6 +39,11 @@ export const MAX_BATCH_BYTES = maxBytesWithin(MAX_LINT_DEADLINE_MS);
  * validating a subset would report a changeset as checked when it was not.
  */
 export function batchTooLarge(buffers) {
+    // UNREACHABLE OVER MCP — `VALIDATE_CODE_INPUT.files` caps the array with
+    // `.max(MAX_BATCH_FILES)` first, and `runValidateCode` is not on the package's public
+    // surface — so zero coverage here is the schema working, not a gap. Kept as defence-in-depth
+    // because only this bound lives inside the function that promises it, and asked FIRST
+    // because splitting a request by bytes can still leave too many files.
     if (buffers.length > MAX_BATCH_FILES) {
         return {
             code: 'too_large',

package/dist/validate/validate-buffers.js

@@ -17,11 +17,12 @@ import { enrichDiagnostics } from '../enrich/enrich.js';
 import { lintDeadlineMs } from '../cost-model.js';
 import { TIMED_OUT, withDeadline } from '../deadline.js';
 import { runImpact } from '../impact/impact.js';
+import { canHaveDependants } from '../impact/dependants.js';
 import { createProjectScan } from '../impact/project-scan.js';
 import { runBatchLint, } from '../lint/lint-batch.js';
 import { assembleNotApplicableResult, assembleResult } from '../result/assemble.js';
 import { capToBudget } from '../result/response-budget.js';
-import { UNAVAILABLE_IMPACT } from '../result/impact-states.js';
+import { DISABLED_IMPACT, UNAVAILABLE_IMPACT } from '../result/impact-states.js';
 /** Read the process-wide docset and flatten it to the arrays enrichment takes. */
 async function resolveDocset() {
     const docset = getPlatformOSDocset();
@@ -65,11 +66,26 @@ export async function validateBuffers(ctx, buffers, overrides = {}) {
     // Computed ONCE and threaded to both the timer and the message that reports it, so the
     // two cannot disagree about the deadline a caller was held to.
     const lintDeadline = lintDeadlineMs(admittedBytes(lintable));
-    // Concurrently: the lint is the long pole and impact must hide behind it.
-    const [lint, impacts] = await Promise.all([
+    // The project SCAN overlaps the primary lint; the impact LINT PASSES cannot.
+    //
+    // `lintBuffers` overlays buffers into check-node's process-shared `App` and reverts them
+    // on the way out, and that App has no lock — so two lint passes running at once would
+    // corrupt each other. The scan is pure filesystem I/O and touches no App, which is what
+    // lets the expensive half of impact hide behind the lint anyway.
+    const scan = projectScan(ctx, lintable);
+    const [lint] = await Promise.all([
         lintWithDeadline(ctx, adapters, lintable, lintDeadline),
-        impactWithDeadline(ctx, adapters, lintable),
+        scan.warm(),
     ]);
+    // AFTER the primary lint, and never allowed to break it: the write gate is already
+    // decided by this point, so impact can only add to the answer or fail quietly.
+    //
+    // Turned off for this SERVER (`--no-impact`) it costs NOTHING: `projectScan` declines to
+    // read, and the two extra lint passes never start. `disabled` is its own status precisely
+    // so an agent does not read it as a failure worth retrying.
+    const impacts = ctx.impactEnabled === false
+        ? new Map(lintable.map((buffer) => [buffer.filePath, DISABLED_IMPACT()]))
+        : await impactWithDeadline(ctx, adapters, lintable, scan.scan);
     // The lint pass is what knows which buffers were not checked and why — it holds the
     // config AND the classifier. Folding its answer in here keeps ONE source of truth for
     // "is this file part of the app".
@@ -187,45 +203,83 @@ function admittedBytes(lintable) {
     return lintable.reduce((total, buffer) => total + Buffer.byteLength(buffer.content, 'utf8'), 0);
 }
 /**
- * Blast radius per lintable buffer.
+ * Impact per lintable buffer.
  *
- * ONE scan serves the whole batch: `createProjectScan` reads the project's edge sources
- * once, lazily and memoized, so N buffers cost one project read and N name filters. The
- * batch's own buffers are overlaid into it, so a caller a buffer has just added counts.
+ * ONE scan serves the whole batch: `createProjectScan` reads the project's edge sources once,
+ * LAZILY and memoized, so a batch whose buffers can have no dependants never reads the project
+ * at all, and one where some can pays a single read. The batch's own buffers are overlaid into
+ * it, so a call a buffer has just added counts.
  *
  * The set shares one tight deadline because impact is discardable enrichment —
  * `unavailable` already means "we don't know".
  */
-async function impactWithDeadline(ctx, adapters, lintable) {
+async function impactWithDeadline(ctx, adapters, lintable, scan) {
     const byFile = new Map();
     if (lintable.length === 0)
         return byFile;
-    const rootUri = pathUtils.normalize(pathUtils.toUri(ctx.projectDir));
-    const scan = createProjectScan(rootUri, NodeFileSystem, new Map(lintable.map((buffer) => [
-        pathUtils.normalize(pathUtils.toUri(toAbsoluteFilePath(ctx.projectDir, buffer.filePath))),
-        buffer.content,
-    ])));
-    const work = Promise.all(lintable.map(async (buffer) => {
-        const impact = await adapters
-            .impact({ projectDir: ctx.projectDir, filePath: buffer.filePath, content: buffer.content }, scan)
-            .catch((error) => {
-            ctx.log(`validate_code: blast-radius failed for ${buffer.filePath}: ${describe(error)}`);
-            return UNAVAILABLE_IMPACT();
-        });
-        return [buffer.filePath, impact];
-    }));
+    const work = adapters
+        .impact({
+        projectDir: ctx.projectDir,
+        buffers: lintable,
+        scan,
+        lint: adapters.lint,
+        docset: adapters.docset,
+        log: (message) => ctx.log(`validate_code: ${message}`),
+    })
+        .catch((error) => {
+        // ONE failure covers the whole changeset: the passes are shared, so a failure says
+        // nothing about any individual buffer.
+        ctx.log(`validate_code: impact failed: ${describe(error)}`);
+        return new Map();
+    });
     const outcome = await withDeadline(work, IMPACT_DEADLINE_MS);
     if (outcome === TIMED_OUT) {
-        observeAbandoned(ctx, work, 'blast-radius');
-        ctx.log(`validate_code: blast-radius exceeded ${IMPACT_DEADLINE_MS} ms, continuing without it`);
+        observeAbandoned(ctx, work, 'impact');
+        ctx.log(`validate_code: impact exceeded ${IMPACT_DEADLINE_MS} ms, continuing without it`);
         for (const buffer of lintable)
             byFile.set(buffer.filePath, UNAVAILABLE_IMPACT());
         return byFile;
     }
-    for (const [filePath, impact] of outcome)
-        byFile.set(filePath, impact);
+    // A buffer the pass did not answer for gets `unavailable` rather than a silent absence:
+    // `resultFor` would otherwise default it, and "we did not look" must not read as "we
+    // looked and found nothing".
+    for (const buffer of lintable) {
+        byFile.set(buffer.filePath, outcome.get(buffer.filePath) ?? UNAVAILABLE_IMPACT());
+    }
     return byFile;
 }
+/**
+ * The request's project scan, plus a handle to start reading it.
+ *
+ * Split so the read can be STARTED alongside the primary lint and awaited later: it is the
+ * expensive half of impact (~235 ms on a 2,615-file project) and pure filesystem I/O, so
+ * overlapping it with the lint's CPU costs nothing and races nothing.
+ */
+function projectScan(ctx, lintable) {
+    const rootUri = pathUtils.normalize(pathUtils.toUri(ctx.projectDir));
+    const scan = createProjectScan(rootUri, NodeFileSystem, new Map(lintable.map((buffer) => [
+        pathUtils.normalize(pathUtils.toUri(toAbsoluteFilePath(ctx.projectDir, buffer.filePath))),
+        buffer.content,
+    ])));
+    // Nothing in this changeset can HAVE dependants — every buffer is a YAML file, or sits in
+    // no platformOS directory — so impact will never consult the scan and reading the project
+    // would be pure waste. Decidable from the paths alone, before any I/O.
+    //
+    // A PERFORMANCE GUARD, NOT A CORRECTNESS ONE, which is why six mutants survive on it.
+    // `warm()` only PRE-warms: `scan.sources()` memoizes its promise and impact awaits that
+    // same promise itself, so inverting this buys a wasted read or a colder path, never a
+    // different answer. Nothing pins it — nor the `--no-impact` claim above, where what is
+    // tested is that the impact ADAPTER goes uncalled, not that the project read is skipped.
+    const worthReading = ctx.impactEnabled !== false &&
+        lintable.some((buffer) => canHaveDependants(pathUtils.normalize(pathUtils.toUri(toAbsoluteFilePath(ctx.projectDir, buffer.filePath))), rootUri));
+    return {
+        scan,
+        // A failed read is impact's problem, not the lint's: swallowed here so it cannot reject
+        // the `Promise.all` that the primary lint is riding in, and surfaced when impact awaits
+        // the same memoized promise itself.
+        warm: () => (worthReading ? scan.sources().catch(() => undefined) : Promise.resolve()),
+    };
+}
 /**
  * Attach a handler to work the deadline abandoned.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformos/platformos-mcp-supervisor",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "platformOS Model Context Protocol (MCP) server exposing validate_code for LLM agents.",
   "type": "module",
   "main": "dist/index.js",
@@ -43,12 +43,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@platformos/liquid-html-parser": "0.1.0",
-    "@platformos/platformos-check-common": "1.0.0",
-    "@platformos/platformos-check-node": "1.0.0",
-    "@platformos/platformos-common": "0.1.0",
-    "@platformos/platformos-graph": "0.1.0",
-    "@platformos/platformos-language-server-common": "0.1.0",
+    "@platformos/liquid-html-parser": "0.2.0",
+    "@platformos/platformos-check-common": "1.1.0",
+    "@platformos/platformos-check-node": "1.1.0",
+    "@platformos/platformos-common": "0.2.0",
+    "@platformos/platformos-graph": "0.2.0",
+    "@platformos/platformos-language-server-common": "0.1.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {}