@redue/cli 0.1.0-alpha.5 → 0.1.0-alpha.7

package/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
-## 0.1.0-alpha.5 — unreleased candidate
+## 0.1.0-alpha.7 — 2026-10-07
+
+- Guide explicitly configured direct-compiler reuse through one caller-aware
+  synchronized query; skip reuse queries when fresh execution is already required.
+- Update intact project-local agent instructions safely; installation alone does
+  not update them. See the [existing-user procedure](docs/user/agents.md#update-an-existing-connection).
+- In the finite Codex/macOS comparison, revised guidance reached eligible evidence
+  and reused it in 4/4 opportunities versus 1/4; verification tool calls fell
+  from 28 to 14. Evidence semantics are unchanged. No universal compliance,
+  tail-latency or causal agent-task speedup is claimed. Claude behavior and
+  cross-host handoff remain untested.
+
+## 0.1.0-alpha.6 — 2026-10-07
+
+- Reuse guarded compiler discovery for warm direct-TypeScript decisions on macOS
+  with healthy historical observation. Membership, absence, compiler bytes,
+  caller context and receipt selection remain validated independently.
+- Keep full discovery/reconciliation fallbacks and existing platform boundaries.
+- On one measured project, complete warm decision median fell from roughly
+  791 to 474 ms. This is not a universal speedup, agent-task acceleration,
+  memory improvement, or a faster relevant-edit/rebuild claim.
+- Stop observers before upgrading and restart with the same config/state.
+  Preserve receipts; no configuration migration is performed.
+
+## 0.1.0-alpha.5 — 2026-10-07
 
 - Add opt-in project-local agent activation and direct TypeScript evidence, with
   fresh-session reuse demonstrated in the tested Codex/macOS configuration.

package/docs/user/agents.md

@@ -3,18 +3,27 @@
 Use the CLI with explicit project-local activation below, or add this policy to a
 generic agent's instructions with the project owner's permission.
 
-1. Query ordinary `redue status --json` first.
-2. Require schema 1 and healthy observation. If a check has `freshness: "CURRENT"`, `result: "PASS"`, and
-   `reuse_eligible: true`, reuse it. Missing eligibility means false. Do not rerun merely for freshness.
-3. If STALE, run `redue run CHECK` when that verification is needed.
-4. If the historical `result` is FAIL, report it honestly. The human CLI calls
-   this FAILED; applicability is a separate field, never an excuse to call it green.
-5. If UNVERIFIED, inspect its reason. Use `status --sync --json` when establishing
-   applicability is worthwhile, or rerun the underlying check when cheaper/simpler.
-   Use `redue run CHECK` if a new receipt is wanted. Incomplete coverage can remain
-   UNVERIFIED even after success.
-6. Do not assume synchronization is cheaper than execution. There are no universal
-   package-manager or OS thresholds. Inexpensive checks may be cheaper to rerun.
+1. If fresh execution is already required, execute it; do not synchronize merely
+   to confirm an irrelevant reuse opportunity. Use `redue run CHECK` when recording
+   the configured check. An explicit npm-script request still requires npm.
+2. For reuse of the explicitly configured direct compiler recipe
+   (`qualification: "npm-typescript-direct-v1"`, direct compiler command; receipt
+   `verification_recipe: "npm-direct-typescript@1"`), query once:
+   `redue --config CONFIG status --sync --json`. Do not infer a recipe from its name.
+   Cached status cannot establish its caller context. In mixed configurations,
+   assess each check's contract separately; this is not a global sync-first policy.
+3. For other/unknown recipes, query ordinary `status --json` first and decide whether
+   synchronization is worthwhile. Ordinary status and `--short` remain cheap inspection.
+4. Reuse only schema 1, healthy observation and the selected check's CURRENT/PASS
+   with `reuse_eligible: true`. Missing eligibility means false. A historical FAIL
+   is never green evidence. Do not rerun eligible evidence merely for freshness.
+5. STALE requires execution when verification is needed. UNVERIFIED requires an
+   honest choice of synchronization, permitted execution or reporting the limitation.
+   Recording-only success can remain UNVERIFIED. A deliberate cheap-check rerun is
+   permitted; there are no universal platform/package-manager timing thresholds.
+6. Use a successful synchronized response for the current decision without repeated
+   sync/explain calls unless edits, context changes or missing information require it.
+   Do not loop until green or use an earlier response after a later query fails.
 
 `redue explain CHECK --json` gives synchronized detail, including a known changed
 input when available. It has the same cost caveat as synchronized status.
@@ -37,9 +46,9 @@ CURRENT. Do not delete state or reset receipts to make the output green.
 REDUE tells you what evidence exists and whether it still applies. It does not
 promise that establishing applicability is cheaper than every possible check.
 
-## Connect once (candidate)
+## Connect once (experimental)
 
-The alpha.5 candidate supports opt-in project-local activation and direct
+Alpha.5 and later support opt-in project-local activation and direct
 TypeScript evidence, with fresh-session reuse demonstrated for Codex CLI 0.160.1
 on macOS under the documented owner-approved checkout/state/socket route. CLI
 mechanics are tested on macOS/Linux/Windows; model behavior is not claimed for
@@ -47,7 +56,7 @@ every host/platform or sandbox policy. Claude setup/removal mechanics are tested
 but Claude behavior and cross-host reuse remain untested. Reuse is not guaranteed,
 and the existing subsecond example establishes no meaningful net time saving.
 
-After installing this candidate and running `redue init` in a trusted project:
+After installing REDUE and running `redue init` in a trusted project:
 
 ```sh
 redue agent setup codex --dry-run
@@ -62,6 +71,42 @@ setup requires `--apply`. `--dry-run` never writes. Installing REDUE or running
 `init` does not connect an agent automatically. Setup does not start an observer
 or execute verification. Use `redue start` when you want observation.
 
+## Update an existing connection
+
+Installing a newer package does **not** rewrite project instructions. From the
+same project and installation, stop every observer using that installation before
+replacing it. Keep the original config and state selection; do not create a second
+config or delete receipts. Example for a default npm installation/config:
+
+```sh
+redue --config redue.config.json stop
+npm install --global @redue/cli@alpha
+redue --config redue.config.json agent setup codex --dry-run
+redue --config redue.config.json agent setup codex --apply
+redue --config redue.config.json start
+redue --config redue.config.json status --sync --json
+```
+
+Use the **same `--prefix`** as the existing npm installation when it has a custom
+prefix, and invoke its corresponding `redue` binary. Keep your actual config path
+on every command. For Claude, select `claude` in both setup commands. Preserve any
+existing `--state-dir` on lifecycle/status commands; setup does not embed custom
+state locations, so retain the documented generic instruction path if your agent
+workflow needs an explicit custom state. PowerShell may use the existing
+`npm.cmd`/`redue.cmd` shims without changing script policy.
+
+Review the preview before applying. Intact owned content updates; unrelated text
+is preserved. Edited managed content is refused, not overwritten. If refused,
+review/reconcile those edits deliberately; do not remove ownership records to force
+an update. Restart the observer with its original selection even if you postpone
+updating instructions, then start a **fresh agent session** after a successful
+update. Setup creates no verification receipt.
+
+Managed project metadata can itself be an observed input. Prior receipts remain
+historical evidence, but setup may make them STALE or UNVERIFIED. Reassess normally
+and run required checks; an upgrade is not a promise that existing receipts remain
+CURRENT. Do not suppress that invalidation or reset state.
+
 Codex gets a short managed section in project `AGENTS.md` and
 `.agents/skills/redue-verification/SKILL.md`. Claude Code gets a managed section
 in `CLAUDE.md` and `.claude/skills/redue-verification/SKILL.md`. Each uses the same
@@ -107,7 +152,7 @@ proven installation mismatch.
 Codex CLI 0.160.1 on macOS can use the approved exact observer-socket route while
 other sockets and direct network access remain denied. Its independent sessions
 receive different proxy values. Ordinary npm invocation is **not** equivalent
-across arbitrary notifier state: this candidate withholds automatic npm-launcher
+across arbitrary notifier state: REDUE withholds automatic npm-launcher
 reuse. Do not change proxy settings or permissions to get green evidence.
 
 The separate opt-in [direct local compiler recipe](direct-typescript.md) does not
@@ -124,7 +169,7 @@ performs the same bounded, read-only decision check and exits 2 when reuse is no
 eligible. It neither executes verification nor grants access; synchronization
 may run configured probes. A successful outside-shell result is insufficient.
 
-Use the same setup command after a candidate upgrade; it updates intact managed
+Use the same setup command after an upgrade; it updates intact managed
 content idempotently. Changed skill text or a changed managed block causes a
 conflict instead of an overwrite. Review your edits before retrying.
 
@@ -154,8 +199,8 @@ paths. Other worktrees and remote containers have separate local evidence.
 
 For another agent, put a short instruction in its documented project mechanism:
 “Before deciding whether configured verification needs repeating, read REDUE's
-agent policy, query ordinary `redue status --json` for the intended config, and
-apply the schema/health/reuse rules.” Supply this document and the
+agent policy, identify the selected recipe and use its decision query for the intended config.
+Apply the schema/health/reuse rules.” Supply this document and the
 [JSON contract](json.md) as the detailed policy. Review the agent's actual tool
 trace before calling activation verified. A local npm installation does not install
 REDUE in a remote container; that environment needs its own CLI, checkout,

package/docs/user/getting-started.md

@@ -57,11 +57,13 @@ prefix. Uninstalling the package does not remove local verification evidence;
 `redue remove-state` is a separate, explicit action. Alpha.1 remains available as
 historical software and is superseded for package identity, not a runtime defect.
 
-## Upgrading to alpha.4
+## Upgrading REDUE
 
 Stop every observer using the installation before upgrading, then restart each
 with the same config/state selection. See [the npm launcher notice](npm-launcher-notice.md)
-for exact commands. Do not remove state or delete receipts.
+for exact commands. Do not remove state or delete receipts. Existing agent connections require a separate
+[preview/apply policy update](agents.md#update-an-existing-connection); installing
+the package alone does not update project instructions.
 
 ## First project
 
@@ -90,7 +92,7 @@ reusability. Qualification can change when configuration or installation changes
 
 `run` streams normal output and preserves execution environment and cancellation.
 For the narrow pnpm TypeScript contract, `init` explicitly shows the direct installed
-compiler invocation it selects. In this candidate, npm scripts remain recording-only;
+compiler invocation it selects. Npm scripts remain recording-only;
 use `redue init --recipe typescript-direct --dry-run` to preview a distinct,
 explicit [local compiler recipe](direct-typescript.md). Other scripts run through
 the package manager. No existing configuration is silently migrated.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"

package/src/agent-integration.mjs

@@ -45,15 +45,19 @@ function saved(root,host){const text=read(root,marker(host));if(text===null)retu
   const value=JSON.parse(text),h=hosts[host];
   if(value.schema!==1||value.host!==host||value.instruction!==h.instruction||value.skill!==h.skill||
     typeof value.config!=='string'||path.isAbsolute(value.config)||value.config.includes('/')||value.config.includes('\\')||
-    value.block!==blockFor(host,value.config)||
+    (value.block!==blockFor(host,value.config)&&value.block!==blockFor(host,value.config,true))||
     typeof value.skillHash!=='string'||typeof value.instructionCreated!=='boolean')
     throw Error('unrecognized agent ownership record; inspect it without deleting user content');
   return value;
 }
-function blockFor(host,relative){return `\n\n<!-- REDUE:${host}:begin -->\n`+
+// Accept only these exact owned template versions; never arbitrary stored text.
+function blockFor(host,relative,legacy=false){return `\n\n<!-- REDUE:${host}:begin -->\n`+
   `Before deciding whether configured verification needs repeating, use REDUE.\n`+
-  `Read ${hosts[host].skill} for the decision policy, then query ordinary status\n`+
-  `before choosing reuse or execution. Only healthy schema-1 CURRENT/PASS with\n`+
+  (legacy?`Read ${hosts[host].skill} for the decision policy, then query ordinary status\n`+
+    `before choosing reuse or execution. Only healthy schema-1 CURRENT/PASS with\n`:
+    `Read ${hosts[host].skill}: verify the selected recipe, use caller-aware sync\n`+
+    `for direct-compiler reuse, and execute fresh obligations without a reuse query.\n`+
+    `Only healthy schema-1 CURRENT/PASS with\n`)+
   `explicit reuse_eligible=true permits reuse; honor fresh-run requests and other\n`+
   `project verification obligations. Reassess after edits or failed queries.\n`+
   `Selected config (JSON path relative to this file's directory): ${JSON.stringify(relative)}.\n`+
@@ -63,7 +67,7 @@ function blockFor(host,relative){return `\n\n<!-- REDUE:${host}:begin -->\n`+
 function skillFor(relative){return policy+`\nSelected configuration\n\n`+
   `The configuration path, relative to the project instruction file's directory, is\n`+
   `${JSON.stringify(relative)} (a JSON string, not shell code). From that directory use\n`+
-  `\`redue --config CONFIG status --json\`, replacing CONFIG with that single quoted\n`+
+  `the policy-selected \`redue --config CONFIG ...\` command, replacing CONFIG with one quoted\n`+
   `path argument. Apply the same --config to run, explain, start and stop. From a\n`+
   `nested directory use the corresponding relative config path. Do not guess among\n`+
   `multiple configs. Receipts are local to the selected checkout/configuration.\n`;}

package/src/agent-policy.md

@@ -3,11 +3,30 @@ name: redue-verification
 description: Decide whether configured verification needs running, using REDUE evidence before verification and completion decisions.
 ---
 
-Query ordinary `redue status --json` before deciding whether configured checks need
-repeating. Apply the selected configuration described below to every command.
-Recheck at the decision point after edits; an earlier CURRENT is not continuing
-authorization after changes, context changes, observation loss, or a failed query.
-There is no atomic guarantee against concurrent edits.
+Apply the selected configuration below to every command. First distinguish an
+execution obligation from a reuse decision:
+
+- If fresh execution is explicitly requested or independently required, execute
+  it without a reuse query that cannot change that decision. Use `redue run CHECK`
+  to record the configured check. An explicit npm-script request requires npm,
+  not a direct compiler substitute.
+- To evaluate reuse for a check whose selected config has
+  `qualification: "npm-typescript-direct-v1"` and the direct compiler command
+  (or whose receipt metadata has `verification_recipe: "npm-direct-typescript@1"`
+  consistent with that config), use one `redue --config CONFIG status --sync --json`
+  directly. Cached status cannot establish this recipe's caller eligibility.
+  Do not infer the recipe from a check's name or precede sync with cached status
+  solely as a ritual. Evaluate each check separately in mixed configurations.
+- For other or unidentified recipes, start with ordinary `status --json` and
+  choose sync or execution from its evidence. Cached status and `--short` remain
+  cheap inspection, not caller-aware proof. A deliberate inexpensive rerun is
+  still permitted; there are no universal OS/package-manager cost thresholds.
+
+Use one successful, still-applicable synchronized response for the current
+decision; do not repeat sync/explain without edits, context changes or missing
+information. Do not loop until green. Reassess after changes, observation loss or
+a later failed query; earlier CURRENT is not continuing authority. There is no
+time-based authorization or atomic guarantee against concurrent edits.
 
 Read schema 1 JSON. Reuse only when the read succeeds, `schema` is 1,
 `observation.healthy` is true, and the selected check has all three:
@@ -29,8 +48,7 @@ checks merely for freshness.
   lifecycle scripts. Inspect the configuration/verification_recipe before claiming
   what ran. An explicit request for `npm run typecheck` requires that npm invocation;
   direct compiler evidence does not satisfy it.
-- Explicit user requests for fresh execution and independent task-specific
-  verification obligations still apply. REDUE covers only configured checks.
+- REDUE covers only configured checks, not every task-specific verification obligation.
 
 Use `redue explain CHECK --json` for synchronized detail (also potentially costly).
 `changed_inputs` can be incomplete; an empty list does not establish no changes.

package/src/daemon.mjs

@@ -16,7 +16,7 @@ import {permittedRoots} from './installed-inputs.mjs';
 import {assertOwnedStatePlacement} from './owned-state.mjs';
 import {atomicJson,readReceipts,readReceiptSnapshot,receiptRevision} from './state-store.mjs';
 import {history} from './observation.mjs';
-import {inputKey} from './decision-validation.mjs';
+import {inputKey,planGuard} from './decision-validation.mjs';
 import {timing} from './decision-profile.mjs';
 
 const configFile=path.resolve(process.argv[2]);
@@ -110,6 +110,11 @@ function persistedPlan(bundle) {
       return [name,safe];
     }))};
 }
+function macProbeBarrier() {
+  return process.platform==='darwin'&&hasHistory&&!historyDisabled&&healthy&&
+    watcher&&!planning&&!recovering&&!planDirty&&!index?.unavailable&&
+    !pending.size&&!pendingChecks.size&&!external.size&&verifyRoot();
+}
 function probe(row,allowReuse=false) {
   const started=performance.now();
   const supported=new Map([
@@ -118,24 +123,45 @@ function probe(row,allowReuse=false) {
     ['yarn-workspace-tsc-v1','yarn-workspace-typecheck-probe.mjs'],
     ['pnpm-tsc-v1','pnpm-typecheck-probe.mjs']]);
   const expected=supported.get(row.plan.qualification);
-  const cacheable=process.platform==='win32'&&row.plan.probes.length===1&&expected&&
+  const macDirect=process.platform==='darwin'&&row.plan.qualification==='npm-typescript-direct-v1';
+  const cacheable=(process.platform==='win32'||macDirect)&&row.plan.probes.length===1&&expected&&
     row.plan.probes[0][1]===fileURLToPath(new URL(expected,import.meta.url));
   const key=inputKey(row);
-  if(cacheable&&allowReuse&&row.probeCache?.input===key){
+  let guard=null,guardReason=null;
+  if(macDirect&&cacheable)try{guard=planGuard(index.bundle);}catch{guardReason='plan_guard_unavailable';}
+  const cache=row.probeCache;
+  const macGuarded=!macDirect||(macProbeBarrier()&&!row.plan.unresolved.length&&
+    guard!==null&&cache?.schema===1&&cache.guard===guard&&
+    Array.isArray(cache.queries)&&cache.queries.length>0);
+  const forceFull=process.env.VSTATE_TEST_FAULTS==='1'&&process.env.VSTATE_TEST_FULL_PROBES==='1';
+  if(cacheable&&allowReuse&&macGuarded&&!forceFull&&cache?.input===key){
     const argv=row.plan.probes[0];
-    const out=spawnSync(argv[0],[...argv.slice(1),'--redue-context'],{
-      cwd:row.plan.cwd,timeout:10000,maxBuffer:1024*1024,stdio:['ignore','pipe','pipe']});
+    const out=spawnSync(argv[0],[...argv.slice(1),macDirect?'--redue-validate-queries':'--redue-context'],{
+      cwd:row.plan.cwd,timeout:10000,maxBuffer:1024*1024,
+      ...(macDirect?{input:JSON.stringify({schema:cache.schema,context:cache.context,queries:cache.queries})}:
+        {stdio:['ignore','pipe','pipe']})});
+    metrics.probeContextProcesses=(metrics.probeContextProcesses||0)+1;
+    let stillValid=!macDirect;
+    if(macDirect)try{stillValid=macProbeBarrier()&&inputKey(row)===key&&planGuard(index.bundle)===guard;}catch{}
     if(!out.error&&!out.signal&&out.status===0&&
-      out.stdout.toString()===row.probeCache.context){
+      out.stdout.toString()===cache.context&&stillValid){
       row.probeHash=row.probeCache.hash;row.probeAt=Date.now();row.probeError=null;
       metrics.probeReuses=(metrics.probeReuses||0)+1;
       timing('daemon.probe_context_validation',started,{outcome:'reused',reason:'content_and_context_unchanged'});
       return;
     }
+    guardReason='context_or_compiler_queries_changed';
     timing('daemon.probe_context_validation',started,{outcome:'changed_or_unavailable'});
   }
-  timing('daemon.probe_reason',started,{reason:!cacheable?'generic_probe':
-    !row.probeCache?'no_validated_result':row.probeCache.input!==key?'inputs_changed':'context_changed'});
+  if(macDirect&&cache?.guard&&guard!==cache.guard)planDirty=true;
+  const fullReason=forceFull?'forced_full_reference':guardReason||
+    (macDirect&&!macGuarded?'mac_validation_basis_unavailable':!cacheable?'generic_probe':
+    !row.probeCache?'no_validated_result':row.probeCache.input!==key?'inputs_changed':'context_changed');
+  timing('daemon.probe_reason',started,{reason:fullReason});
+  metrics.fullProbeReasons??={};metrics.fullProbeReasons[fullReason]=(metrics.fullProbeReasons[fullReason]||0)+1;
+  metrics.fullProbes=(metrics.fullProbes||0)+1;
+  // A failed or incomplete full probe must not leave an older certificate usable.
+  if(macDirect)row.probeCache=null;
   const values=[];let checkpoint=null;
   for(const argv of row.plan.probes) {
     // Supported TypeScript probes perform bounded input/toolchain hashing.
@@ -207,7 +233,7 @@ function probe(row,allowReuse=false) {
     row.revision++;row.lastReason='declared state probe changed or recovered';}
   row.probeHash=value;row.probeAt=Date.now();row.probeError=null;
   if(checkpoint)row.probeCache=checkpoint.queries?{input:key,context:checkpoint.context,
-    hash:value,queries:checkpoint.queries}:null;
+    hash:value,queries:checkpoint.queries,...(macDirect?{schema:1,guard}: {})}:null;
   timing('daemon.probe',started,{outcome:'ok',commands:values.length,
     reusable:row.probeCache?1:0,queries:row.probeCache?.queries.length||0});
 }
@@ -820,7 +846,7 @@ async function request(message) {
     timing('daemon.decision_reason',totalStarted,{decision,action:message.action,
       plan:process.platform==='win32'?'validate_dependencies_before_reuse':'existing_plan',
       probe:'reuse_only_with_identical_content_and_context',installed:'current_content_required',
-      phase:metrics.planPhase||'initializing',pending:pending.size,
+      planPhase:metrics.planPhase||'initializing',pending:pending.size,
       notifications:metrics.notifications,planRebuilds:metrics.planRebuilds});
     if(process.platform==='win32'&&process.env.VSTATE_TEST_FAULTS==='1'&&
       process.env.VSTATE_TEST_WINDOWS_GAP_FILE&&
@@ -872,8 +898,18 @@ async function request(message) {
       }catch(e){installedRecheck=null;observationGap('installed_recheck',e);}
     }
     const probeStarted=performance.now();
-    if(index&&healthy&&!validatedColdIndex&&message.action!=='prelaunch')
-      for(const row of index.checks.values())probe(row);
+    if(index&&healthy&&!validatedColdIndex&&message.action!=='prelaunch'){
+      const macReuse=macProbeBarrier();
+      for(const row of index.checks.values())probe(row,macReuse);
+      if(macReuse&&process.env.VSTATE_TEST_FAULTS==='1'&&process.env.VSTATE_TEST_MAC_PROBE_SIGNAL){
+        fs.writeFileSync(process.env.VSTATE_TEST_MAC_PROBE_SIGNAL,'validated');
+        await new Promise(resolve=>setTimeout(resolve,200));
+      }
+      // Child validation blocks JS event delivery. Finish with another continuity
+      // barrier so queued edits/gaps cannot be published using the pre-probe index.
+      if(macReuse)try{await catchUp();if(planDirty||pending.size||flushTimer)flush();}
+        catch(e){observationGap('post_probe_history',e);}
+    }
     timing('daemon.request_probes',probeStarted,{checks:index?.checks.size||0});
     lastObservation=Date.now();publish();
     const applicabilityStarted=performance.now();
@@ -1002,7 +1038,12 @@ const probeTimer=setInterval(async()=>{
   // but can block control requests behind several seconds of child work.
   if(process.platform==='win32')return;
   if(healthy&&index&&!planning&&!decisionRequests){
-  try{await catchUp();for(const row of index.checks.values())probe(row);publish();}
+  try{await catchUp();
+    if(healthy&&!planning&&!recovering){const macReuse=macProbeBarrier();
+      for(const row of index.checks.values())probe(row,macReuse);
+      if(macReuse){await catchUp();if(planDirty||pending.size||flushTimer)flush();}
+    }
+    publish();}
   catch(e){observationGap('periodic_query',e);}
 }},5000);
 process.on('uncaughtExceptionMonitor',error=>{

package/src/direct-typescript-probe.mjs

@@ -4,15 +4,42 @@ import {directProject,directInterpretation} from './direct-typescript.mjs';
 import {typeScriptInputFacts} from './typescript-input-facts.mjs';
 import {contextOnly,probeResult} from './probe-result.mjs';
 import {realObservedPath} from './path-identity.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import {queriesMatch} from './typescript-list.mjs';
+import {timing} from './decision-profile.mjs';
 const hash=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
 try{
   const [rootArg,script]=process.argv.slice(2),root=realObservedPath(rootArg);
   // Verify all installed implementation bytes before loading compiler API/code,
   // including the optimized context-only path. A version label is insufficient.
+  const implementationStarted=performance.now();
   const compiler=directProject(root,script);
+  timing('direct_probe.implementation',implementationStarted,{version:compiler.version});
   const context={interpretation:directInterpretation,compiler:compiler.digest,
     entry:compiler.entry,node:[realObservedPath(process.execPath),process.version]};
   const contextHash=hash(context);
+  if(process.argv.includes('--redue-validate-queries')){
+    // Internal, process-local discovery certificate; never a verification receipt.
+    // Verify the current implementation above before queryAnswer can load its API.
+    const started=performance.now(),raw=fs.readFileSync(0,'utf8');
+    if(Buffer.byteLength(raw)>8*1024*1024)throw Error('certificate too large');
+    const certificate=JSON.parse(raw),kinds=new Set(['readDirectory','readFile',
+      'fileExists','directoryExists','realpath','directories','entries']);
+    if(certificate.schema!==1||certificate.context!==contextHash||
+      !Array.isArray(certificate.queries)||!certificate.queries.length||
+      certificate.queries.some(q=>!Array.isArray(q)||q.length<3||q.length>4||
+        !kinds.has(q[0])||typeof q[1]!=='string'||!path.isAbsolute(q[1])||
+        q[0]==='readDirectory'&&(q[3]?.tsRoot!==compiler.tsRoot||!Array.isArray(q[3]?.args)||
+          q[3]?.argsVersion!==1||!Array.isArray(q[3]?.undefinedArguments)||
+          q[3].undefinedArguments.some(i=>!Number.isInteger(i)||i<0||i>=q[3].args.length))))
+      throw Error('certificate unavailable');
+    const matched=queriesMatch(certificate.queries);
+    timing('direct_probe.query_validation',started,{queries:certificate.queries.length,matched:matched?1:0});
+    if(!matched)throw Error('compiler queries changed');
+    process.stdout.write(contextHash);
+    process.exit(0);
+  }
   if(!contextOnly(contextHash)){
     const {queries,...inputs}=typeScriptInputFacts(root,compiler.tsRoot,compiler.entry);
     probeResult(hash({root,script,...inputs,...context}),contextHash,queries);

package/src/typescript-list.mjs

@@ -9,7 +9,8 @@ const require=createRequire(import.meta.url);
 const hash=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
 export function queryAnswer(kind,file,options) {
   try{
-    if(kind==='readDirectory')return require(options.tsRoot).sys.readDirectory(file,...options.args).sort();
+    if(kind==='readDirectory')return require(options.tsRoot).sys.readDirectory(file,
+      ...options.args.map((value,i)=>options.undefinedArguments?.includes(i)?undefined:value)).sort();
     if(kind==='readFile')return hash(fs.readFileSync(file,'utf8'));
     if(kind==='fileExists')return fs.statSync(file).isFile();
     if(kind==='directoryExists')return fs.statSync(file).isDirectory();
@@ -42,7 +43,10 @@ export function compilerFiles(tsRoot,cwd) {
   const getDirectories=file=>{remember('directories',file);return ts.sys.getDirectories(file);};
   const readDirectory=(dir,...args)=>{
     const result=ts.sys.readDirectory(dir,...args);
-    const full=path.resolve(dir),options={tsRoot,args};
+    // JSON turns undefined array entries into null. TypeScript distinguishes
+    // them (an omitted exclude list is not a null list), so retain that fact.
+    const full=path.resolve(dir),options={tsRoot,args,argsVersion:1,
+      undefinedArguments:args.flatMap((value,i)=>value===undefined?[i]:[])};
     queries.set('readDirectory\0'+full+JSON.stringify(args),
       ['readDirectory',full,[...result].sort(),options]);
     return result;

package/src/typescript-qualification.mjs

@@ -4,8 +4,9 @@ import path from 'node:path';
 import {realObservedPath} from './path-identity.mjs';
 
 // This is a machine-enforced contract, not a claim inferred from a script name.
-// The read-only runtime probe separately checks the effective TypeScript file
-// list, config graph, npm toolchain and caller context on every sync/run.
+// Runtime validation checks effective compiler membership, configuration and
+// toolchain identity. Supported discovery certificates still validate those
+// filesystem queries; caller context is independently compared at the decision.
 export function qualifyTypeScript(root,selected,discovered={}) {
   if(selected.qualification===directQualification){
     const issues=[];