candor-ts 0.33.1 → 0.34.0

package/AGENTS.md

@@ -21,7 +21,7 @@ the TypeScript-specific production + query surface.
 > **Already installed? Report the version and ask before upgrading — before you scan.** If this
 > project already has candor (a `.candor/` report directory, or `candor-ts` reachable via `npx`/a
 > global install), do this *first*: run `npx -y candor-ts --version` (offline) and **tell the user
-> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.33)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.34)."*
 > On a build too old for the flag, read `candor.version` / `candor.spec` from an existing
 > `.candor/report*.json`, or `npm ls -g candor-ts`.
 >

package/README.md

@@ -198,7 +198,7 @@ pure-vs-Unknown ruling (PART 16) — the engines must answer identically, on eve
 | A call resolving to a *type* (function-typed field/param) → `Unknown`, never silent-pure | SPEC §4 |
 | Unmatched external calls contribute nothing (curated-classifier caveat) | SEMANTICS §8 C1 |
 | The literal surfaces `hosts`/`cmds`/`paths`/`tables`, literal-read only | SPEC §2 |
-| `{ candor: { version, toolchain, spec: "0.33" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.34" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
 | Call-graph sidecar with **every** analyzed function a key | SPEC §2.2 |
 | The gate: AS-EFF-006 / 008 / 009, loud on an unreadable policy | SPEC §6.2 |
 
@@ -216,7 +216,7 @@ read the Rust source".
 
 ## Status
 
-0.30.0, speaking candor-spec 0.33: the analysis core, the gate (`--policy` / `--gate-json` /
+0.30.0, speaking candor-spec 0.34: the analysis core, the gate (`--policy` / `--gate-json` /
 `.candor/config`), the full §3.1 query surface (including `containment`, `blindspots`, the
 `--include-unknown` dispatch frontier, and ⟨0.24⟩ `gate --report` — the gate applied to an EXISTING
 report, byte-equivalent to `scan --policy`'s verdict), the MCP server, the LSP server, and the watch loop are

package/contract.mjs

@@ -113,3 +113,57 @@ export function writeStdoutSync(out, what = "output", fd = 1, budgetMs = 5000) {
   }
   return true;
 }
+
+// ── SPEC §3.3.1 ⟨0.28⟩ THE SINK WRITER, AND THE ONE SHAPE THAT IS NEVER A SINK ────────────────────
+//
+// ONE IMPLEMENTATION, for the same reason `printAgents` and `writeStdoutSync` live here: scan.mjs and
+// query.mjs are two entry points that must not import from each other, and until 2026-08-30 each
+// carried its own byte-identical copy of these two functions plus its own spelling of the
+// `.candor/config` shape check. That duplication is not theoretical drift — it is the measured
+// SIBLING-ROUTE pattern: three guard-deletion findings were closed on query.mjs's copies on
+// 2026-08-30, and scan.mjs's copies were still unprotected hours later (neutering all three left the
+// full 1702-row battery green, while three hand repros destroyed a `.candor/config`, severed a symlink
+// and stranded a hard-linked sink). Both routes now have watched-RED rows; keeping ONE implementation
+// is what stops the third route from starting out with none.
+//
+// RESOLVE THE SINK TO ITS FINAL ARTIFACT BEFORE WRITING, and preserve the operator's layout.
+// `renameSync` REPLACES a symlink rather than following it, so an `artifacts/verdict.json` linked into a
+// shared directory kept a previous run's `{"ok": true}` while this run's document landed on the link — a
+// stale green with a single `--gate-json` and no operator mistake. And rename gives the destination a NEW
+// inode, so a multiply-linked target strands its other name with the previous document; there the write
+// goes in place, trading the atomicity window for not publishing a stale verdict at a name the operator
+// wired up. SPEC §3.3.1 states identity about ARTIFACTS; this family had it in the comparison only.
+export function resolveSinkArtifact(p) {
+  let cur = p;
+  for (let i = 0; i < 32; i++) {
+    let st;
+    try { st = fs.lstatSync(cur); } catch { return cur; }
+    if (!st.isSymbolicLink()) return cur;
+    let t;
+    try { t = fs.readlinkSync(cur); } catch { return cur; }
+    cur = path.isAbsolute(t) ? t : path.join(path.dirname(cur), t);
+  }
+  return cur;
+}
+
+export function writeSinkAtomic(p, text) {
+  const target = resolveSinkArtifact(p);
+  try {
+    if (fs.statSync(target).nlink > 1) { fs.writeFileSync(target, text); return; }
+  } catch { /* not there yet — the ordinary temp+rename path is right */ }
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, target);
+}
+
+/** `.candor/config` is never a verdict sink, wherever it is — the SHAPE, not a discovered path.
+ *  The per-input collision checks can only name inputs a run was TOLD about; the config is DISCOVERED
+ *  by walking up from the target, so by the time its path is known the arming has already destroyed it.
+ *  A check on the shape needs no discovery, so it runs before the first write and covers a config found
+ *  anywhere up the tree. The PREDICATE is shared; each route keeps its own diagnostic and its own
+ *  refusal plumbing (scan.mjs also feeds the ⟨0.28⟩ report stream through `refuseEarly`). */
+export function isCandorConfigSink(p) {
+  if (!p || p === "-") return false;
+  const abs = path.resolve(p);
+  return path.basename(abs) === "config" && path.basename(path.dirname(abs)) === ".candor";
+}

package/lsp.mjs

@@ -209,6 +209,103 @@ function entriesInDoc(docPath, fns = null) {
   return out;
 }
 
+/**
+ * A report FILE FOUND but UNREADABLE (corrupt, mid-write, or a permissions error) — `Q.loadReport` tags
+ * its result with the non-enumerable `hardFail` the CLI's `loadReportOrDie` and the MCP `loadReportLoud`
+ * both consult, but until now nothing in this file read it: `diagnosticsFor`, `hoverAt` and `codeLenses`
+ * called `Q.loadReport` bare, so a corrupt report degraded to an EMPTY `functions` array and every one of
+ * the three read that as "no effects" — the live gate published `[]` (clean), hover answered `null`
+ * (nothing to show), codeLens answered `[]` (nothing effectful) — on the ONE surface a developer watches
+ * continuously (`integrations/vscode` and the JetBrains plugin both bundle this exact server). The CLI
+ * exits 2 over exactly this ("refusing to report an empty (all-clear) answer over a corrupt report"); the
+ * MCP tools throw. This server has neither an exit code nor a safe throw-and-crash option — killing the
+ * connection over one bad report would cost the developer every OTHER file and language feature the
+ * editor provides, for a fault a re-scan clears in seconds. So: never silent, never fatal — the invariant
+ * this closes is "the engine declined to answer must never be presentable as the engine answered clean",
+ * not "an unreadable report must end the session".
+ *
+ * FULL vs PARTIAL, the CLI/MCP distinction carried here because the repair text and the right amount of
+ * caution differ: `fns.length === 0` is every report file at the prefix failing (a single corrupt
+ * `<prefix>.json`, or a multi-report prefix whose every sibling is unreadable) — nothing loaded, not even
+ * a partial claim. `fns.length > 0` with `hardFail` still set is the multi-report (Rust/workspace) form
+ * with ONE corrupt sibling among healthy ones — MEASURED to be the quieter failure: `reportJudgedNothing`
+ * ANDs `analyzed.count<=0` across every sibling, so ONE healthy sibling with real entries makes it return
+ * FALSE and the corrupt sibling's absence gets no disclosure of ANY kind (repro: a `.good.scan.json`
+ * sibling with one pure fn beside a `.bad.scan.json` garbage sibling — diagnostics/log/show all silent).
+ *
+ * `full` decides what each caller does with it: `diagnosticsFor` (the live GATE — squiggles ARE this
+ * surface's whole verdict, per `discloseIncompleteness`'s own framing) refuses to draw ANY ordinary
+ * squiggle on either kind of hardFail, mirroring `candor_gate`, which takes the strict bar at its OWN
+ * `g.hardFail` throw off `Q.loadGateReport` — the same reader `gate --report` uses. A partial signature
+ * makes a green verdict meaningless FOR THE SAME REASON on all three routes: the effects that failed to
+ * load are exactly the ones a violation would come from. `hoverAt`/`codeLenses` are read-only
+ * per-function/per-line surfaces, the LSP analogue of `Q.show`/`Q.map` — MCP keeps THOSE tolerant of a
+ * partial load (plain `loadReportLoud`, whose bar is "NOTHING parsed") because a partial answer is a
+ * smaller claim than a green gate, and the same argument holds here:
+ *
+ * NAMED FOR A MECHANISM THAT EXISTS, since 2026-08-30 (panel finding 22). This paragraph, the one at
+ * `diagnosticsFor` and two lines in test-lsp.mjs — one of them an assertion NAME — all cited a
+ * `partialIsFatal:true` argument to `loadReportLoud`. NO CALLER EVER PASSED IT; it was a dead knob, and
+ * `ee82d38` deleted it hours after those comments were written, leaving five citations of a mechanism
+ * with no code. The BEHAVIOUR they describe was and is real — `candor_gate` does take the strict bar —
+ * so this is not a defect, it is the failure mode where an explanation goes on reading as considered
+ * after the thing it explains is gone, and the next reader checks the wrong function for the guarantee.
+ * only a FULL failure gets the visible marker in place of the answer; a partial one still returns
+ * whatever loaded, `warnLoudOnce` having already said the signature may be incomplete.
+ */
+/** ⟨0.32⟩ SPEC §3.3.1 — THE REFUSAL MARKER, ON THE EDITOR ROUTE. The reader and the sentence come from
+ *  query-core (`Q.refusalMarkerFor` / `Q.refusalSentence`), the same two the CLI's `requireReport` and the
+ *  MCP `resolvePrefix` use, so all three routes make the SAME claim about the same bytes. It reached only
+ *  the CLI until 2026-08-30 (panel finding 3): over one directory with unchanged bytes, `gate --report`
+ *  exited 2 naming the refusal while this server drew its ordinary squiggles and `candor_gate` returned
+ *  `{"ok":true,"violations":[]}`. This surface is where that costs the most — a developer reads the ABSENCE
+ *  of a squiggle as "clean" continuously, and a refused scan means nobody checked.
+ *
+ *  It is folded into `hardFailDetail` rather than added beside it because a refusal and an unreadable
+ *  report are the same instruction to this file — "do not present this as an answer" — and its three
+ *  callers (diagnostics, hover, lenses) already implement exactly that for `full`. A fourth predicate
+ *  would have been a fourth thing to remember at each call site, which is the shape of the finding above. */
+function refusalDetail(prefix) {
+  const m = Q.refusalMarkerFor(prefix);
+  if (!m) return null;
+  return {
+    full: true,
+    log: `candor-lsp: ${Q.refusalSentence(m)} No diagnostics, hovers or lenses are drawn from these `
+       + `reports — their ABSENCE here is the refusal, not an all-clear.`,
+    brief: `candor: the last scan REFUSED — these reports are stale and UNVERIFIED (see the candor log)`,
+    doc: `candor: the last scan over this project REFUSED (${m.reason}) — the effects shown here are from `
+       + `an earlier run and are UNVERIFIED, not clean. Re-scan.`,
+    // The marker a refusal shows is NOT the unreadable-report one: these bytes parse perfectly, and an
+    // operator told "report unreadable" goes looking for a corrupt file that isn't there. A refusal's own
+    // words, and its own diagnostic `code`, so a client filtering or counting them can tell the two apart.
+    lens: "⚠ candor: the last scan REFUSED — these effects are stale, re-scan",
+    code: "report-refused",
+  };
+}
+
+function hardFailDetail(fns, prefix) {
+  const refused = refusalDetail(prefix);
+  if (refused) return refused;
+  if (!fns.hardFail) return null;
+  const full = fns.length === 0;
+  const log = full
+    ? `candor-lsp: every report found at \`${prefix}\` failed to load (corrupt or mid-write) — refusing `
+      + `to treat the empty result as an all-clear. Every file's effects are UNVERIFIED, not clean — `
+      + `re-run the scan (candor-ts <src> --out ${prefix}).`
+    : `candor-lsp: a report found at \`${prefix}\` failed to load alongside sibling report(s) that did — `
+      + `a partial signature makes any verdict meaningless (the effects that failed to load are exactly `
+      + `the ones a violation would come from). Diagnostics/hover/lenses drawn from the reports that DID `
+      + `load may be missing functions that live in the one that didn't — re-run the scan `
+      + `(candor-ts <src> --out ${prefix}).`;
+  const brief = full
+    ? `candor: the report could not be read — effects are UNVERIFIED, not clean (see the candor log)`
+    : `candor: part of the report could not be read — some effects may be missing (see the candor log)`;
+  const doc = full
+    ? "candor: the report could not be read (corrupt or mid-write) — effects here are UNVERIFIED, not clean. Re-run the scan."
+    : "candor: part of the report could not be read (corrupt or mid-write) — some effects across this project may be missing. Re-run the scan.";
+  return { full, log, brief, doc, lens: "⚠ candor: report unreadable — re-run the scan", code: "report-unreadable" };
+}
+
 // The transitive-caller COUNT for an exact fn name over an already-inverted graph. The lenses used
 // Q.callers per entry, and every callers() call rebuilt reverseGraph from scratch — a 50-fn document
 // over a JVM-scale callgraph did 50 full graph inversions PER codeLens request (review find). One
@@ -225,7 +322,18 @@ function transitiveCallerCount(rev, fn) {
 
 // ---- CodeLens ---------------------------------------------------------------------------------------
 function codeLenses(docPath) {
-  const found = entriesInDoc(docPath);
+  if (!hasReport(reportPrefix)) return [];
+  const fns = Q.loadReport(reportPrefix);          // ONE load per request — see hardFailDetail
+  const hf = hardFailDetail(fns, reportPrefix);
+  if (hf) {
+    warnLoudOnce(hf.log, hf.brief);
+    if (hf.full) return [{
+      range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+      command: { title: hf.lens, command: "" },
+    }];
+    // partial: fall through and lens whatever DID load, per hardFailDetail's read-only tolerance
+  }
+  const found = entriesInDoc(docPath, fns);
   if (found === null) return [];
   let rev = null;
   try { rev = Q.reverseGraph(Q.loadCallgraph(reportPrefix)); } catch { /* no callgraph — effects-only lens */ }
@@ -254,6 +362,15 @@ function enclosingEntry(docPath, line, fns = null) {
 function hoverAt(docPath, line) {
   if (!hasReport(reportPrefix)) return null;
   const fns = Q.loadReport(reportPrefix);          // ONE load per request (enclosingEntry reuses it)
+  const hf = hardFailDetail(fns, reportPrefix);
+  if (hf) {
+    warnLoudOnce(hf.log, hf.brief);
+    if (hf.full) return {
+      contents: { kind: "markdown", value: `**${hf.doc}**` },
+      range: { start: { line, character: 0 }, end: { line, character: 200 } },
+    };
+    // partial: fall through and hover whatever DID load, per hardFailDetail's read-only tolerance
+  }
   const at = enclosingEntry(docPath, line, fns);
   if (!at) return null;
   const { entry } = at;
@@ -409,7 +526,7 @@ const zeroRulePolicyWarn = (what) =>
 // 2 (INCOMPLETE)" / "CI exits 2 over these bytes" is a wrong, checkable claim in exactly that case. Two
 // fixtures with the identical unread-file cause differ only in whether a violation coexists, and only the
 // violation-free one made this text true.
-function discloseIncompleteness(unanalyzed, outOfScope, unread, unaskedRules, certainViolation) {
+function discloseIncompleteness(unanalyzed, outOfScope, unread, unaskedRules, unaskedRulesPredates033, certainViolation) {
   const causes = [];
   // The CLI's order (`unanalyzed` → `outOfScope` → `unread` → `unaskedRules`), so a report tripping two
   // of them reads the same way here as it does in CI. The repairs genuinely differ — a parse to fix, a
@@ -433,12 +550,28 @@ function discloseIncompleteness(unanalyzed, outOfScope, unread, unaskedRules, ce
   // policy's own. Distinct from `unread` above: that is "nothing looked", this is "something looked, for
   // a narrower question than the one this editor is asking now" — the peek is bounded to the PRODUCER's
   // denied effects (⟨0.29⟩), so an empty finding there answers nothing about a rule it was never put.
-  if (unaskedRules?.length)
-    causes.push(`this report's peek was bounded by the deny set its producing scan held, and that set `
-      + `does not cover ${unaskedRules.length} rule(s) of this policy: ${unaskedRules.join(", ")}. The `
-      + `excluded files it reports as read were searched for OTHER effects, so nothing in them can be `
-      + `squiggled here — re-run the producing scan under THE SAME policy this editor is applying `
-      + `(candor-ts <dir> --policy <file>), not merely under a policy.`);
+  //
+  // ⟨0.34⟩ TWO SENTENCES, chosen by `unaskedRulesPredates033` (SAME wire shape either way — this function
+  // only ever writes to the log/showMessage channel, never a document). The ⟨0.33⟩ text is misleading of a
+  // report that predates ⟨0.33⟩ entirely: such a producer never had a `scannedUnder` key to hold ANY deny
+  // set in, so "does not cover" reads as "chose a different policy" where the truth is "could not yet
+  // record one". See `specPredates`'s doc in query-core.mjs for the full argument; the `else` arm here is
+  // character-for-character the pre-⟨0.34⟩ text.
+  if (unaskedRules?.length) {
+    if (unaskedRulesPredates033)
+      causes.push(`this report was produced before ⟨0.33⟩, when a producing scan did not yet record the `
+        + `deny set its peek ran under (\`scannedUnder\`), so it cannot say whether ${unaskedRules.length} `
+        + `rule(s) of this policy were ever asked: ${unaskedRules.join(", ")}. There is no way to tell from `
+        + `a report this old what the excluded files it reports as read were searched for, so nothing in `
+        + `them can be squiggled here — re-scan with a 0.33+ engine under THE SAME policy this editor is `
+        + `applying (candor-ts <dir> --policy <file>), not merely under a policy.`);
+    else
+      causes.push(`this report's peek was bounded by the deny set its producing scan held, and that set `
+        + `does not cover ${unaskedRules.length} rule(s) of this policy: ${unaskedRules.join(", ")}. The `
+        + `excluded files it reports as read were searched for OTHER effects, so nothing in them can be `
+        + `squiggled here — re-run the producing scan under THE SAME policy this editor is applying `
+        + `(candor-ts <dir> --policy <file>), not merely under a policy.`);
+  }
   if (!causes.length) return;
   // ⟨lsp-precedence⟩ the exit-code claim is conditional on whether a certain violation ALSO fires: if one
   // does, Lemma 2 makes it dominate (exit 1), and the incompleteness below is true but not what CI is red
@@ -468,6 +601,23 @@ function diagnosticsFor(docPath) {
   const text = activePolicy();
   if (text === null || !hasReport(reportPrefix)) return [];
   const fns = Q.loadReport(reportPrefix);
+  // A report FOUND but UNREADABLE (hardFail — see hardFailDetail): this is the live GATE, so it takes
+  // the STRICT `candor_gate` bar (its `g.hardFail` throw off `Q.loadGateReport`) on EITHER kind, full or partial — a
+  // partial signature makes a green verdict meaningless for the identical reason on both routes (the
+  // effects that failed to load are exactly the ones a violation would come from). Refuses to draw ANY
+  // ordinary squiggle from fns that may be missing exactly the function a rule would have fired on; the
+  // marker diagnostic below is drawn INSTEAD, on every open document, because the corruption is a fact
+  // about the REPORT and not about any one file — there is no "innocent file" to misattribute it to the
+  // way the ⟨0.30⟩/⟨0.32⟩ scope causes below have one, since a report that cannot be read says nothing
+  // about ANY function in ANY document, this one included.
+  const hf = hardFailDetail(fns, reportPrefix);
+  if (hf) {
+    warnLoudOnce(hf.log, hf.brief);
+    return [{
+      range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+      severity: 2, source: "candor", code: hf.code, message: hf.doc,
+    }];
+  }
   // ⟨0.24⟩ A report that JUDGED NOTHING is not a clean bill of health, and this surface is where that is
   // hardest to notice: the live gate's whole vocabulary is squiggles, and a report with `analyzed.count: 0`
   // has no entries, so it produces none — an empty editor reads as "the gate is green" when the truth is
@@ -523,7 +673,8 @@ function diagnosticsFor(docPath) {
   const certainViolation = evaluatePolicy(dwp0.answerable, fns, Q.loadCallgraph(reportPrefix),
     new Map(), new Set(), dnet0, dwithhold0, dunits0).length > 0;
   discloseIncompleteness(dcomp.unanalyzed ?? [], dcomp.outOfScope ?? [],
-                         dpol.deny.length ? (dcomp.unread ?? []) : [], dcomp.unaskedRules ?? [], certainViolation);
+                         dpol.deny.length ? (dcomp.unread ?? []) : [], dcomp.unaskedRules ?? [],
+                         dcomp.unaskedRulesPredates033 ?? false, certainViolation);
   // ⟨0.24⟩ THE ANSWERABILITY WITHHOLD, which this surface ran WITHOUT — `evaluatePolicy` was called with no
   // `withhold` predicate and the DEFAULT netClass mode, so both directions of the §3.1 harm were live in the
   // editor. Measured against the CLI on one report and one policy: `deny Unknown[reflect]` drew NO squiggle
@@ -673,6 +824,19 @@ function runWhatif(a) {
     logMessage(`candor-lsp: ${WHATIF_COMMAND} called with malformed arguments (expected [{ fn, effect, uri?, line? }]) — ignored`);
     return null;
   }
+  // ⟨0.32⟩ DID THE LAST SCAN REFUSE? The three passive surfaces get this through `hardFailDetail`;
+  // these two COMMAND endpoints resolve the report themselves and gate only on `hasReport`, so the rule
+  // has to be said here too or the executeCommand route is the one that still certifies refused bytes —
+  // which is the finding this closes, one route over. `showMessage(2, …)` is this surface's refusal
+  // envelope (the CLI's exit 2, the MCP tool's isError), and the sentence is query-core's.
+  {
+    const rm = Q.refusalMarkerFor(reportPrefix);
+    if (rm) {
+      warnLoudOnce(`candor-lsp: ${Q.refusalSentence(rm)}`, `candor: the last scan REFUSED — no pre-edit verdict over stale, UNVERIFIED reports`);
+      showMessage(2, `candor: the last scan over this project REFUSED (${rm.reason}) — no pre-edit verdict is computed from reports it would not certify. Re-scan.`);
+      return null;
+    }
+  }
   if (!hasReport(reportPrefix)) {
     showMessage(2, "candor: no report found — scan first (candor-ts <dir> --out .candor/report)");
     return null;
@@ -707,7 +871,8 @@ function runWhatif(a) {
   const wcomp = Q.reportCompleteness(reportPrefix, wpol?.deny ?? []);
   const wUnread = wpol?.deny?.length ? (wcomp.unread ?? []) : [];
   const wUnasked = wcomp.unaskedRules ?? [];
-  discloseIncompleteness(wcomp.unanalyzed ?? [], wcomp.outOfScope ?? [], wUnread, wUnasked);
+  discloseIncompleteness(wcomp.unanalyzed ?? [], wcomp.outOfScope ?? [], wUnread, wUnasked,
+                         wcomp.unaskedRulesPredates033 ?? false);
   const callers = r.affected.filter((f) => !r.of.includes(f));   // affected minus the target(s) themselves
   const rules = [...new Set(r.violations.map((v) => v.rule))];
   // ⟨0.24⟩ THE EDITOR IS A CHANNEL THIS VERB ANSWERS ON, so the `conditional` has to reach it or this
@@ -759,6 +924,19 @@ function runFix(a) {
     logMessage(`candor-lsp: ${FIX_COMMAND} called with malformed arguments (expected [{ fn, effect, uri?, line? }]) — ignored`);
     return null;
   }
+  // ⟨0.32⟩ DID THE LAST SCAN REFUSE? The three passive surfaces get this through `hardFailDetail`;
+  // these two COMMAND endpoints resolve the report themselves and gate only on `hasReport`, so the rule
+  // has to be said here too or the executeCommand route is the one that still certifies refused bytes —
+  // which is the finding this closes, one route over. `showMessage(2, …)` is this surface's refusal
+  // envelope (the CLI's exit 2, the MCP tool's isError), and the sentence is query-core's.
+  {
+    const rm = Q.refusalMarkerFor(reportPrefix);
+    if (rm) {
+      warnLoudOnce(`candor-lsp: ${Q.refusalSentence(rm)}`, `candor: the last scan REFUSED — no boundary fix over stale, UNVERIFIED reports`);
+      showMessage(2, `candor: the last scan over this project REFUSED (${rm.reason}) — no boundary fix is computed from reports it would not certify. Re-scan.`);
+      return null;
+    }
+  }
   if (!hasReport(reportPrefix)) {
     showMessage(2, "candor: no report found — scan first (candor-ts <dir> --out .candor/report)");
     return null;

package/mcp.mjs

@@ -48,6 +48,26 @@ function resolvePrefix(args) {
   if (!p) throw new Error("no report prefix: pass `report`, set $CANDOR_REPORT, or give one as the CLI arg");
   if (WORKSPACE_ROOT && !within(nodePath.resolve(p), WORKSPACE_ROOT))
     throw new Error(`report prefix \`${clip(p)}\` is outside the served workspace (--root ${WORKSPACE_ROOT}) — refusing`);
+  // ⟨0.32⟩ SPEC §3.3.1 — DID THE MOST RECENT SCAN OVER THESE BYTES REFUSE? This is the CLI's
+  // `requireReport` check on the agent route, reading the SAME marker through the SAME query-core helper
+  // and saying the SAME sentence. It was CLI-only until 2026-08-30 (panel finding 3): over one directory
+  // and unchanged bytes, `gate --report`/`where` exited 2 naming the refusal while `candor_gate` returned
+  // `{"ok":true,"violations":[]}`, `candor_unverified` `{"ok":true,"unverified":[]}` and `candor_where` a
+  // clean effect surface — the CI route refusing and the route an agent actually asks certifying, which is
+  // the divergence §3.1 exists to forbid, in the silent direction, on the surface with no exit code to read.
+  //
+  // IT SITS AT THE PREFIX, NOT IN A VERB: every report-reading tool resolves through here (and so does
+  // `resources/read`), so this cannot be the route that has the rule while its sibling does not — the
+  // failure mode this very finding is. The ENVELOPE is this surface's own: a thrown error becomes the
+  // `isError` tool result every other refusal here uses, the agent-transport spelling of the CLI's exit 2.
+  //
+  // BEFORE the existence check, which is the order `requireReport` uses and the order MATTERS: a project
+  // whose FIRST scan refused has the marker and NO reports, and existence-first answered `no report at
+  // \`…\` — run a candor scan first` — advice to do the thing the operator just did, with the recorded
+  // cause of the refusal sitting unread one file away. Neither order is a false all-clear; only one tells
+  // the truth about which of the two situations this is.
+  const m = Q.refusalMarkerFor(p);
+  if (m) throw new Error(Q.refusalSentence(m));
   if (!Q.hasReport(p)) throw new Error(`no report at \`${p}\` (.json or .<crate>.scan.json) — run a candor scan first`);
   return p;
 }
@@ -71,19 +91,25 @@ const clip = (s, n = 120) => { s = String(s); return s.length > n ? s.slice(0, n
 // corrupt report — the §4 cardinal sin, exactly what the CLI's loadReportOrDie exits 2 on. The throw
 // surfaces as the same isError result shape every other tool failure uses. EVERY tool that loads a
 // report (main prefix or baseline) goes through this — never bare Q.loadReport.
-// `partialIsFatal` raises the bar from "NOTHING parsed" to "not EVERYTHING parsed", and `candor_gate`
-// passes it because that tool emits a VERDICT: `{ok: true, violations: []}` over a multi-report prefix
-// with one clean sibling and one truncated one is a green document over a package half of whose signature
-// never loaded, and the disclosure Q.loadReport writes goes to the SERVER's stderr — a channel the calling
-// agent never reads. Same rule, same argument as the CLI `gate --report` (see query.mjs). The read-only
-// tools keep the looser bar deliberately: they return what they found rather than asserting a clean bill
-// of health, so the partial answer is a smaller claim than a green gate.
-function loadReportLoud(p, { partialIsFatal = false } = {}) {
+// THE BAR HERE IS "NOTHING PARSED", deliberately: these are the read-only tools, and they return what
+// they found rather than asserting a clean bill of health, so a partial answer is a smaller claim than a
+// green gate (`warnLoudOnce`/Q.loadReport has already disclosed the dropped file).
+//
+// THE STRICTER BAR — "not EVERYTHING parsed" — BELONGS TO `candor_gate`, WHICH EMITS A VERDICT: `{ok:
+// true, violations: []}` over a multi-report prefix with one clean sibling and one truncated one is a
+// green document over a package half of whose signature never loaded, and Q.loadReport's disclosure goes
+// to the SERVER's stderr, a channel the calling agent never reads. That rule lives at `candor_gate`'s own
+// `g.hardFail` throw, off `Q.loadGateReport` — the SAME reader `gate --report` uses, which is what keeps
+// the two routes from drifting. It is NOT reached through this helper.
+//
+// This function used to carry a `partialIsFatal` option whose comment said "`candor_gate` passes it".
+// No caller ever passed it — a dead knob documented as load-bearing, found by the guard-deletion sweep
+// (2026-08-30): neutering it left the suite green AND left `candor_gate`'s behaviour byte-identical,
+// because the tool had never routed through it. Removed rather than left reading as coverage.
+function loadReportLoud(p) {
   const fns = Q.loadReport(p);
-  if (fns.hardFail && (partialIsFatal || fns.length === 0))
-    throw new Error(fns.length === 0
-      ? `every report found at prefix \`${clip(p)}\` failed to load — refusing to report an empty (all-clear) answer over a corrupt report; re-run the scan`
-      : `a report found at prefix \`${clip(p)}\` failed to load — refusing to gate over a report that did not load cleanly; a partial signature makes a green verdict meaningless (the effects of the report that did not load are exactly the ones a violation would come from). Re-run the scan`);
+  if (fns.hardFail && fns.length === 0)
+    throw new Error(`every report found at prefix \`${clip(p)}\` failed to load — refusing to report an empty (all-clear) answer over a corrupt report; re-run the scan`);
   return fns;
 }
 // The confinement root for a caller-supplied policy path: the repo the report belongs to — the
@@ -105,8 +131,17 @@ function policyRoot(prefix) {
 // (the gateless-green shape the CLI's whatif exits 2 on).
 function confinedPolicyRead(policyPath, prefix, root = policyRoot(prefix)) {
   const abs = nodePath.resolve(policyPath);
-  if (!within(abs, root) || (WORKSPACE_ROOT && !within(abs, WORKSPACE_ROOT)))
+  if (!within(abs, root))
     throw new Error(`policy must be within the report's repo (${root}) — refusing to read \`${clip(policyPath)}\``);
+  // …AND WITHIN THE SERVED WORKSPACE — a SEPARATE arm with its own sentence, because the repo root above
+  // is DERIVED FROM THE CLIENT-CHOSEN REPORT (a `.candor/config` discovered ABOVE `--root` widens it past
+  // the workspace) and is therefore exactly the case this arm exists for. Sharing one sentence named a
+  // directory the path IS inside — a refusal whose stated reason its own evidence contradicts, which
+  // reads as a broken checker rather than as the confinement working. GUARD-DELETION SWEEP, 2026-08-30.
+  if (WORKSPACE_ROOT && !within(abs, WORKSPACE_ROOT))
+    throw new Error(`policy \`${clip(policyPath)}\` is outside the served workspace (--root ${WORKSPACE_ROOT}) `
+      + `— refusing to read it. The report's repo root (${root}) is WIDER than the served workspace (it is `
+      + `discovered from the report, which the client names), so the workspace bound is the one that holds here.`);
   try { return fs.readFileSync(abs, "utf8"); }
   catch { throw new Error(`policy \`${clip(policyPath)}\` could not be read — NOT evaluated (a missing gate source must be loud, never a clean verdict)`); }
 }
@@ -839,6 +874,22 @@ function handle(msg) {
       const missing = (t.schema.required || []).filter((k) => args[k] === undefined || args[k] === "");
       if (missing.length)
         return result(id, { content: [{ type: "text", text: `candor: missing required argument(s): ${missing.join(", ")}` }], isError: true });
+      // ⟨0.34⟩ BACKLOG "`--policy` accept-and-drop is THREE engines, not one" — the CLI half of this fix
+      // (query.mjs, DESCRIPTIVE_NO_POLICY) closes a grammar-level promise: `--policy <file>` is a token
+      // the CLI parser accepts for EVERY verb, so silently dropping it on a descriptive one breaks that
+      // promise. This tool surface makes no such blanket promise (each tool's OWN schema is what a caller
+      // reads to learn its inputs) — but `candor_where`/`candor_show`/… never DECLARED a `policy`
+      // property and their `run` never reads `args.policy`, so a caller who reasons "the sibling tools
+      // (`candor_whatif`/`candor_fix`/`candor_gate`/`candor_unverified`) take `policy`, this one probably
+      // does too" gets the identical hazard: a policy is passed, an answer comes back computed WITHOUT
+      // it, and nothing discloses the difference. MEASURED 2026-08-28: `candor_where`/`candor_show` (this
+      // fix's CLI siblings) AND `candor_gains` (which the CLI already protects — `37c9b10`'s pattern —
+      // but this surface never did) all returned BYTE-IDENTICAL results with and without a `policy`
+      // argument. Derived from the SCHEMA rather than a maintained name list, so a future tool needs no
+      // entry here: if it wants `policy` to do something, it lists `policy` among its own properties and
+      // reads `args.policy`, and this check gets out of its way for free.
+      if (args.policy !== undefined && !("policy" in (t.schema.properties || {})))
+        return result(id, { content: [{ type: "text", text: `candor: ${params.name} has no policy-relative verdict — its schema declares no \`policy\` property, and it never reads one; apply a policy to an existing report with \`candor_gate\`, or use \`candor_whatif\`/\`candor_fix\`/\`candor_unverified\` for a policy-relative pre-edit check.` }], isError: true });
       // A log-only tool (candor_activity) needs no report — resolving one would wrongly demand a
       // scan before the gate's own activity can be read.
       const prefix = t.noReport ? null : resolvePrefix(args);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.33.1",
-  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.33)",
+  "version": "0.34.0",
+  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.34)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",