@platformos/platformos-mcp-supervisor 0.1.0 → 0.2.1

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

@@ -25,6 +25,7 @@
  * every session.
  */
 import { allChecks } from '@platformos/platformos-check-common';
+import { MAX_BATCH_BYTES, MAX_BATCH_FILES } from '../validate/batch-bounds.js';
 /**
  * The coverage line, DERIVED so it cannot describe a build that no longer exists.
  *
@@ -35,98 +36,64 @@ import { allChecks } from '@platformos/platformos-check-common';
 function coverage() {
     return `${allChecks.length} checks`;
 }
-export const SERVER_INSTRUCTIONS = `platformOS code validator.
-
-WHEN TO USE
-Call validate_code BEFORE writing or editing any platformOS Liquid, GraphQL or
-YAML file — it validates an in-memory buffer, so call it with the content you are
-about to write, not after writing. This is the primary quality gate. If you are changing several files as one coherent change,
-send them together in a single call (see the tool's \`files\` parameter): files in
-one call can reference each other, so a partial you are creating alongside its
-caller resolves correctly. Sent one at a time, that same edit is reported broken.
-List each file at most once — a changeset cannot hold two versions of one file, so a
-request that names the same file twice is refused rather than guessed at.
-Skipping this tool is the #1 cause of broken platformOS code.
-
-HOW TO READ THE RESULT
-
-must_fix_before_write
-  true  -> Do NOT write the file. It will not parse, it will raise at runtime, or
-           the deploy converter will reject it — and a converter rejection fails the
-           WHOLE changeset, not just this file.
-  false -> Nothing BLOCKING was found. This is not a statement that the code is
-           correct, only that no known-fatal problem was detected. Keep your own
-           judgement.
-
-status
-  ok | warning | error  -> the file WAS checked; these describe what was found.
-  not_applicable        -> the file was NOT checked at all. This is neither
-                           approval nor refusal — it carries no opinion about the
-                           file. Read not_applicable_reason before deciding:
-    outside_project  - not inside the project this server serves
-    unsupported_type - not a file type platformOS lints
-    misplaced_source - a platformOS source outside every deployed subtree; nothing
-                       checked it and nothing will load it either
-    ignored          - excluded by the project's .platformos-check.yml
-    too_large        - one buffer, or the request as a whole, is above its size
-                       limit. Split the file, or send fewer files per call — the
-                       reason text says which bound was hit
-    timed_out        - validation was abandoned; retrying may work
-    internal_error   - your REQUEST was malformed, or the validator hit a bug; the
-                       reason text says which. A malformed request — both input
-                       forms at once, neither, or one file listed twice — is yours
-                       to fix and worth retrying once fixed.
+/**
+ * The request caps, DERIVED for the same reason as the count above.
+ *
+ * `MAX_BATCH_FILES` already reaches the model as `maxItems` on the tool's schema, but
+ * `MAX_BATCH_BYTES` is computed from the cost model and appears in no schema and no prose —
+ * so a caller could only learn it by being refused. Stated together because a batch is
+ * planned against both at once, and derived so that moving the cost model moves this too.
+ */
+function bounds() {
+    return `${MAX_BATCH_FILES} files and ${Math.floor(MAX_BATCH_BYTES / 1024)} KiB`;
+}
+export const SERVER_INSTRUCTIONS = `Tool Purpose: Validates platformOS Liquid, GraphQL and YAML files in-memory to prevent broken deployments.
 
-errors / warnings / infos
-  Each list is ordered by line then column WITHIN ITSELF; the three are not one
-  ordered sequence, so concatenating them does not walk the file in order. Columns
-  count UTF-16 code units, so an emoji advances the column by 2.
-  Note that errors[] can be non-empty while must_fix_before_write is false: some
-  errors are real problems that do not stop the file working (an argument a partial
-  ignores, a missing asset, a missing image dimension). Fix them when you can; they
-  do not block the write.
-  Each finding names the check that produced it, and where see_also is present it links
-  that check's documentation — read it there rather than guessing at the rule.
-  A finding may carry fix (edits that are safe to apply as given) or suggestions
-  (alternatives to choose between). Their start_index / end_index are 0-based offsets
-  into the buffer you sent — NOT the 1-based line/column on the same finding. Apply
-  several edits from the end backwards, or account for the drift.
+CRITICAL USAGE RULES
+- Validate BEFORE writing: always pass the proposed in-memory buffer. NEVER write to disk first. This is the primary quality gate. Skipping this tool is the #1 cause of broken platformOS code.
+- Audit existing code with the same call: pass a file's current contents to learn whether what is on disk is already broken. Its own findings are real, but impact is not — impact lints the dependants with your buffer and again without it and reports the difference, so an unchanged buffer yields an empty impact by construction, not by safety.
+- Batch interdependent files: if one change touches several referencing files, send them together in the files array so cross-references resolve. Sent one at a time, a partial you are creating alongside its caller is reported missing. Up to ${bounds()} per request.
+- No duplicates: List each file at most once per request. A changeset cannot hold two versions of one file, so a request naming one twice is refused.
 
-truncated
-  Present ONLY when a file had so many findings that the lists were shortened to
-  keep the answer a reasonable size; absent means the lists are complete. It gives
-  the true total per affected list, so "returned: 40, total: 900" means 860 more
-  exist. The lists keep the TOP of the file, where a cascade's root cause usually
-  is. status and must_fix_before_write are always computed from ALL findings, never
-  from the shortened list, so a truncated answer is never a softer verdict — fix
-  what is listed and validate again to see the rest.
+RESPONSE SCHEMA & ACTION DIRECTIVES
 
-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.
+must_fix_before_write (Boolean)
+- true: FATAL. Do NOT write the file. The deploy converter refuses the WHOLE changeset, not just this file.
+- false: nothing blocking was found. This is NOT a statement that the code is correct, only that no known-fatal problem was detected. Keep your own judgement.
 
-WHAT IS NOT CHECKED
-${coverage()} run against your buffer. Where a finding exists it explains itself and links
-its documentation, so what follows is only the SILENCES — the places where finding nothing is not the same
-as finding it correct, and where no diagnostic can tell you so.
+status (String)
+- ok | warning | error: the file WAS checked; these describe what was found.
+- not_applicable: the file was NOT checked. Neither approval nor refusal — it carries no opinion about the file.
+  - not_applicable_reason: outside_project, unsupported_type, misplaced_source, ignored, too_large, timed_out, internal_error.
+  - next_step: the one to act on. It names the path, limit or deadline actually hit, and what to do about it.
+  - too_large: one buffer, or the request as a whole, is above its size limit. next_step says which, so shrink a file or send fewer per call accordingly.
+  - Retry: timed_out is worth another call. internal_error is two cases — a malformed request (both input forms at once, neither, or one file listed twice) is yours to fix and worth retrying once fixed; a validator bug is not, and no retry will change it.
 
-  Argument types are checked only where the platformOS documentation publishes a type.
-  An argument the documentation leaves untyped accepts more than one type and is never
-  reported — which is every argument of every core Liquid filter, because those coerce
-  rather than refuse. {{ 5 | upcase }} renders and is not reported. That silence is the
-  documentation's answer, not a guarantee the value is right.
+errors, warnings, infos (Arrays)
+- Each array is ordered by line then column WITHIN ITSELF. The three are not one sequence, so concatenating them does not walk the file in order. Columns count UTF-16 code units, so an emoji advances the column by 2.
+- errors[] can be non-empty while must_fix_before_write is false: an argument a partial ignores, a missing asset, a missing image dimension are real but do not stop the file working.
+- Fixes and suggestions carry start_index / end_index: 0-based offsets into the buffer you sent, NOT the 1-based line/column on the same finding.
+- Action: to avoid offset drift, apply multiple edits from the bottom of the file upwards.
+- Action: where see_also is present, read that check's documentation rather than guessing at the rule.
 
-  The SHAPE of a model schema is not checked. An unknown property is not reported,
-  because the platform accepts it.
+truncated (Object)
+- Present only when a file produced too many findings to return in full. The lists keep the TOP of the file, where a cascade's root cause usually is.
+- Constraint: status and must_fix_before_write are ALWAYS computed from the true total of findings, never from the shortened list. Fix what is listed and re-validate to see the rest.
 
-  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
-  is NOT exhaustive — a few spellings collide on the platform and are not reported — so
-  silence there does not prove two keys are distinct.
+impact (Object)
+- What this change BREAKS in files you are NOT editing — the one thing a per-file lint cannot see, since it only looks at the buffers you sent.
+- It reports only what your change INTRODUCED. A problem the file already had is never listed, however severe.
+- Constraint: a dependant break does NOT set must_fix_before_write. Your buffer may be perfectly correct; fix the callers or decide not to.
+- impact.status:
+  - computed: the dependants were linted with your change and without it.
+  - not_applicable: no dependant the graph can find names this file. That is not a clearance.
+  - unavailable | disabled: the comparison never ran. An empty impact under either is NOT a finding of safety.
+- unchecked_dependants: present when a file has more dependants than one request will lint, so an otherwise-clean answer carrying it is a PARTIAL one.
+- NOTHING HERE IS A CLEARANCE. 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 — before renaming or deleting one, search the project yourself.
 
-  Coverage is per project: checks can be enabled, disabled or ignored in the project's
-  .platformos-check.yml, so a clean result reflects that project's configuration rather
-  than a fixed universal standard.`;
+LIMITATIONS (what a clean result does NOT prove)
+${coverage()} run against your buffer. Coverage is per project: checks can be enabled, disabled or ignored in .platformos-check.yml, so a clean result reflects that configuration rather than a fixed universal standard. Where a finding exists it explains itself and links its documentation, so what follows is only the SILENCES.
+- An argument the documentation leaves untyped accepts more than one type and is never reported — which is every argument of every core Liquid filter, because those coerce rather than refuse. {{ 5 | upcase }} renders and is not reported.
+- A model schema's property TYPE is checked and an unknown one is reported. The rest of the shape is not: an unrecognised top-level key is rejected on deploy and nothing reports it.
+- Duplicate YAML keys are compared the way the platform's own parser resolves them, but NOT exhaustively — a few spellings collide on the platform and are not reported, so silence there does not prove two keys are distinct.`;
 //# sourceMappingURL=instructions.js.map

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

@@ -16,13 +16,34 @@
  * This module owns only the MCP surface: schema, description, registration, and mapping
  * input shape to output shape. All logic lives in `validate/`.
  */
-import { type ZodRawShape } from 'zod';
+import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 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';
-export declare const VALIDATE_CODE_INPUT: ZodRawShape;
+/**
+ * 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.
+ */
+export declare const VALIDATE_CODE_INPUT: {
+    file_path: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file_path: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>>>;
+};
 /**
  * The agent-facing prose, exported so tests can pin claims that must not rot. The
  * description is the agent's whole understanding of this tool; a stale sentence

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,33 @@ 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.
+ */
 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 +162,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',