@redue/cli 0.1.0-alpha.6 → 0.1.0-alpha.8

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.1.0-alpha.8 — 2026-10-08
+
+- Consume compiler-certificate input asynchronously while preserving the input-size
+  limit, parent deadline, complete-input validation and conservative fallbacks.
+- Support the exact reviewed TypeScript 5.5.2 distribution in the explicitly selected
+  single-package npm direct-compiler recipe. Enforce implementation membership and
+  reject ETW module overrides before compiler API loading.
+- Real independent Codex/macOS sessions reused compiler evidence on the pinned
+  vscode-js-debug project. Cross-platform CLI/package acceptance is separate;
+  Claude behavior and cross-host handoff remain untested.
+- The measured eight-case workflow avoided four compiler executions but cost
+  20.01 seconds versus 16.97 seconds for eight ordinary compiler runs. No net
+  workflow or whole-agent speedup is claimed. This verifies compiler inputs only,
+  not npm lifecycle behavior or application correctness.
+- Stop observers before upgrading, retain the same configuration/state, then
+  restart. Do not delete receipts or automatically convert existing checks.
+
+## 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

package/bin/redue.mjs

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
+import {mark,traceBase,traceContext,traceEnvironment,traceId} from '../src/decision-profile.mjs';
+traceBase({...traceContext(),request:traceId(),work:'client'});
+mark('client.loaded');
 import {directCompiler,directQualification,directEnvironment,directInterpretation} from '../src/direct-typescript.mjs';
 import os from 'node:os';
 import path from 'node:path';
@@ -154,6 +157,7 @@ function printLifecycle(output,action,machine){
 if(stateOverride&&['stop','remove-state'].includes(command)){
   const runtime=path.join(stateOverride,'project-runtime-v1.json');
   if(!fs.existsSync(runtime)){console.log('No REDUE state exists at this path.');process.exit(0);}
+  mark('client.engine_submit');
   const result=spawnSync(process.execPath,[engine,runtime,command==='stop'?'stop':'uninstall'],
     {cwd:os.tmpdir(),stdio:['inherit','pipe','inherit'],encoding:'utf8',env:process.env});
   if(result.error)error(result.error.message);
@@ -334,9 +338,11 @@ if(command==='run'){
   if(outcome.error)error(outcome.error.message);
   process.exit(outcome.status??(outcome.signal?128+os.constants.signals[outcome.signal]:1));
 }
+mark('client.engine_submit');
 const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
   {stdio:['inherit','pipe','inherit'],
-    encoding:'utf8',env:process.env});
+    encoding:'utf8',env:traceEnvironment()});
+mark('client.engine_complete',{exit:result.status,signal:result.signal});
 if(result.error)error(result.error.message);
 if(result.stdout){
   if(['status','detail','explain'].includes(command)){

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/direct-typescript.md

@@ -5,7 +5,7 @@ check against declared, observed inputs and relevant execution context. It does
 not mean npm or npm lifecycle scripts completed.
 
 For a supported single-package npm project with an existing standalone
-`tsc --noEmit` script, installed dependencies, Node 22/24 and TypeScript 5.6.3/5.9.3:
+`tsc --noEmit` script, installed dependencies, Node 22/24 and TypeScript 5.5.2/5.6.3/5.9.3:
 
 ```sh
 redue init --recipe typescript-direct --check typecheck --dry-run
@@ -33,7 +33,7 @@ A generated check contains:
 
 `script` identifies the reviewed source recipe; `command` is what actually runs:
 the resolved Node executable and local TypeScript implementation, with exact argv
-and no shell. TypeScript 5.6.3 uses `lib/tsc.js`; 5.9.3 uses `lib/_tsc.js` directly,
+and no shell. TypeScript 5.5.2 and 5.6.3 use `lib/tsc.js`; 5.9.3 uses `lib/_tsc.js` directly,
 without its outer compile-cache-enabling shim. No compiler is fetched or bundled.
 The entire installed package must match reviewed official distribution bytes.
 

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/docs/user/supported-projects.md

@@ -19,7 +19,7 @@ project script. Automatic npm-launcher applicability was withdrawn in alpha.4;
 ordinary npm scripts remain recording-only. See the [maintainer notice](npm-launcher-notice.md).
 The following direct recipe is opt-in and new in the alpha.5 candidate. The opt-in `init --recipe typescript-direct` supports
 a standalone `tsc --noEmit` script in a single-package npm installation using
-reviewed TypeScript 5.6.3/5.9.3 and Node 22/24. It executes the local compiler,
+reviewed TypeScript 5.5.2/5.6.3/5.9.3 and Node 22/24. It executes the local compiler,
 not npm. Full installed compiler identity, config/membership, installed inputs
 and relevant Node environment are checked before reuse. See the
 [exact direct boundary](direct-typescript.md). Unsupported plugins, preloads,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"
@@ -13,7 +13,8 @@
   "scripts": {
     "test": "node --test --test-concurrency=1 test/*.test.mjs",
     "test:package": "node test/acceptance/package-smoke.mjs",
-    "demo": "node test/acceptance/package-smoke.mjs --demo"
+    "demo": "node test/acceptance/package-smoke.mjs --demo",
+    "pretest": "npm --prefix test/fixtures/typescript-5-5-2 ci --no-audit --no-fund"
   },
   "dependencies": {
     "@parcel/watcher": "2.5.6",

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/cli.mjs

@@ -17,10 +17,11 @@ import {assertOwnedStatePlacement} from './owned-state.mjs';
 import {permittedRoots} from './installed-inputs.mjs';
 import {acquireRunLock,inspectRunLock,recoverRunLock} from './run-lock.mjs';
 import {atomicJson,commitReceipt,receiptRevision} from './state-store.mjs';
-import {timing,profiling} from './decision-profile.mjs';
+import {timing,profiling,mark,traceContext} from './decision-profile.mjs';
 import {readCachedStatus,unavailableCached} from './cached-state.mjs';
 import {renderRun} from './presentation.mjs';
 
+mark('cli.loaded');
 const here=path.dirname(fileURLToPath(import.meta.url));
 const [configArg,action,name]=process.argv.slice(2);
 if(!configArg||!action)throw Error('internal usage: cli.mjs CONFIG ACTION [check]');
@@ -93,13 +94,13 @@ function owner(){
 }
 function call(message,timeout=5000) {
   return new Promise((resolve,reject)=>{
-    let data='',done=false;const client=net.createConnection(socket);
-    const timer=setTimeout(()=>{client.destroy();reject(Error('observer synchronization timeout'));},timeout);
-    client.on('connect',()=>client.write(JSON.stringify(message)+'\n'));
+    let data='',done=false;mark('client.control_connect',{deadlineMs:timeout});const client=net.createConnection(socket);
+    const timer=setTimeout(()=>{mark('client.control_timeout');client.destroy();reject(Error('observer synchronization timeout'));},timeout);
+    client.on('connect',()=>{mark('client.control_submit');client.write(JSON.stringify({...message,...(profiling?{diagnostic:traceContext()}: {})})+'\n');});
     client.on('data',chunk=>data+=chunk);
-    client.on('end',()=>{clearTimeout(timer);if(done)return;done=true;
+    client.on('end',()=>{mark('client.control_complete',{bytes:data.length});clearTimeout(timer);if(done)return;done=true;
       try{resolve(JSON.parse(data));}catch(e){reject(e);}});
-    client.on('error',e=>{clearTimeout(timer);reject(e);});
+    client.on('error',e=>{mark('client.control_error',{code:e.code});clearTimeout(timer);reject(e);});
   });
 }
 async function decisionCall(message,timeout) {

package/src/daemon.mjs

@@ -17,7 +17,7 @@ import {assertOwnedStatePlacement} from './owned-state.mjs';
 import {atomicJson,readReceipts,readReceiptSnapshot,receiptRevision} from './state-store.mjs';
 import {history} from './observation.mjs';
 import {inputKey,planGuard} from './decision-validation.mjs';
-import {timing} from './decision-profile.mjs';
+import {timing,mark,traceBase,traceContext,traceScope,traceEnvironment,traceId} from './decision-profile.mjs';
 
 const configFile=path.resolve(process.argv[2]);
 const config=JSON.parse(fs.readFileSync(configFile));
@@ -31,6 +31,7 @@ const endpoint=controlEndpoint(state),socket=endpoint.address,
 fs.mkdirSync(lock); // Existing lock requires operator inspection; never steal it.
 fs.writeFileSync(path.join(lock,'pid'),String(process.pid),{mode:0o600});
 const generation=randomUUID(), startedAt=Date.now();
+traceBase({generation,work:'startup'});
 let index, receipts={}, watcher, healthy=false, reason='initial reconciliation', stopping=false;
 let receiptStateError=null;
 let receiptStateRevision=null;
@@ -136,10 +137,12 @@ function probe(row,allowReuse=false) {
   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];
+    mark('daemon.probe_launch',{mode:'certificate',deadlineMs:10000});
     const out=spawnSync(argv[0],[...argv.slice(1),macDirect?'--redue-validate-queries':'--redue-context'],{
-      cwd:row.plan.cwd,timeout:10000,maxBuffer:1024*1024,
+      cwd:row.plan.cwd,timeout:10000,maxBuffer:1024*1024,env:traceEnvironment(),
       ...(macDirect?{input:JSON.stringify({schema:cache.schema,context:cache.context,queries:cache.queries})}:
         {stdio:['ignore','pipe','pipe']})});
+    mark('daemon.probe_complete',{mode:'certificate',childPid:out.pid,exit:out.status,signal:out.signal,code:out.error?.code});
     metrics.probeContextProcesses=(metrics.probeContextProcesses||0)+1;
     let stillValid=!macDirect;
     if(macDirect)try{stillValid=macProbeBarrier()&&inputKey(row)===key&&planGuard(index.bundle)===guard;}catch{}
@@ -170,8 +173,10 @@ function probe(row,allowReuse=false) {
     const timeout=row.plan.qualification==='pnpm-tsc-v1'||
       (process.platform==='win32'&&['typescript-noemit-v1','npm-typescript-direct-v1','yarn-workspace-tsc-v1']
         .includes(row.plan.qualification))?10000:5000;
+    mark('daemon.probe_launch',{mode:'full',reason:fullReason,deadlineMs:timeout});
     const out=spawnSync(argv[0],[...argv.slice(1),...(cacheable?['--redue-checkpoint']:[])],{cwd:row.plan.cwd,
-      timeout,maxBuffer:1024*1024,stdio:['ignore','pipe','pipe']});
+      timeout,maxBuffer:1024*1024,stdio:['ignore','pipe','pipe'],env:traceEnvironment()});
+    mark('daemon.probe_complete',{mode:'full',childPid:out.pid,exit:out.status,signal:out.signal,code:out.error?.code});
     if(out.error||out.signal||out.status!==0) {
       if(!row.probeError){row.revision++;row.lastReason='declared state probe became unavailable';}
       row.probeHash=null;row.probeAt=0;
@@ -180,7 +185,7 @@ function probe(row,allowReuse=false) {
         /VSTATE_REASON:([a-z-]+)/.exec(out.stderr?.toString()||'')?.[1]:null;
       const explanations={
         'direct-typescript-implementation-unreviewed':'installed TypeScript bytes or membership differ from the reviewed compiler',
-        'direct-typescript-version-unsupported':'direct compiler recipe supports reviewed TypeScript 5.6.3 and 5.9.3 only',
+        'direct-typescript-version-unsupported':'direct compiler recipe supports reviewed TypeScript 5.5.2, 5.6.3 and 5.9.3 only',
         'direct-execution-environment-unsupported':'direct compiler rejects development helpers, Node cache/preloads, and unreviewed runtime overrides',
         'direct-node-version-unsupported':'direct compiler recipe supports Node 22 and 24',
         'npm-launcher-unobserved-inputs':'npm launcher uses unobserved notifier inputs; execution is recording-only',
@@ -420,7 +425,7 @@ function buildInWorker(forceCold=false,reuse=null) {
   return new Promise((resolve,reject)=>{
     const workerStarted=performance.now();
     const file=path.join(path.dirname(fileURLToPath(import.meta.url)),'plan-worker.mjs');
-    const worker=new Worker(file,{workerData:{config:configFile,state,forceCold,reuse,
+    const worker=new Worker(file,{workerData:{config:configFile,state,forceCold,reuse,diagnostic:traceContext(),
       reconcileFaultFile:process.env.VSTATE_TEST_RECONCILE_FAULT_FILE}});
     planningWorker=worker;let settled=false;
     const deadline=setTimeout(()=>{
@@ -794,7 +799,7 @@ async function catchUp() {
     lastObservation=Date.now();return;
   }
   if(historyDisabled)return;
-  if(synchronizing)return synchronizing;
+  if(synchronizing){mark('daemon.catch_up_join');return synchronizing;}
   synchronizing=(async()=>{
     if(!verifyRoot())throw Error('checkout identity changed');
     if(!watcher)throw Error('subscription unavailable');
@@ -825,7 +830,8 @@ async function catchUp() {
 function respond(client,value) {
   if(client.destroyed){event('control_reply_unavailable',{classification:'client_destroyed'});return;}
   try{const payload=JSON.stringify(value)+'\n';
-    client.end(payload);client.vstateReplied=true;
+    mark('server.response_constructed',{bytes:payload.length});
+    client.end(payload,()=>mark('server.response_delivered'));client.vstateReplied=true;
     if(process.env.VSTATE_DEBUG_CONTROL==='1')event('control_reply_sent',{bytes:payload.length});}
   catch(e){event('control_reply_unavailable',{classification:e.name||'serialization_error'});
     if(!client.destroyed)client.end('{"error":"control response unavailable"}\n');}
@@ -843,6 +849,7 @@ async function request(message) {
   if(message.action==='sync'||message.action==='snapshot'||message.action==='prelaunch') {
     const totalStarted=performance.now();
     const decision=++decisionSequence;
+    mark('server.decision_start',{decision,pending:pending.size,planDirty,planning,recovering,healthy,historyDisabled,decisionRequests,historyDeadlineMs,reconciliationDeadlineMs});
     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',
@@ -970,9 +977,11 @@ const server=net.createServer(client=>{
     try{const message=JSON.parse(text);
       const decision=message.action==='sync'||message.action==='snapshot';
       if(decision)decisionRequests++;
-      Promise.resolve(request(message)).then(v=>respond(client,v))
-        .catch(e=>respond(client,{error:e.message}))
-        .finally(()=>{if(decision)decisionRequests--;});}
+      traceScope({request:message.diagnostic?.request||traceId(),work:'request'},()=>{
+        mark('server.request_received',{activeDecisions:decisionRequests});
+        Promise.resolve(request(message)).then(v=>respond(client,v))
+          .catch(e=>respond(client,{error:e.message}))
+          .finally(()=>{mark('server.request_complete');if(decision)decisionRequests--;});});}
     catch(e){respond(client,{error:e.message});}
   });
 });
@@ -1032,7 +1041,8 @@ const heartbeat=setInterval(()=>{
   }
   publish();
 },1000);
-const probeTimer=setInterval(async()=>{
+const probeTimer=setInterval(()=>traceScope({request:traceId(),work:'periodic'},async()=>{
+  mark('server.periodic_start',{pending:pending.size,planDirty,planning,decisionRequests});
   // Windows cached reads are conservatively UNVERIFIED until a full decision
   // reconciliation. Periodic synchronous probes cannot strengthen that cache,
   // but can block control requests behind several seconds of child work.
@@ -1045,7 +1055,9 @@ const probeTimer=setInterval(async()=>{
     }
     publish();}
   catch(e){observationGap('periodic_query',e);}
-}},5000);
+}
+  mark('server.periodic_complete');
+}),5000);
 process.on('uncaughtExceptionMonitor',error=>{
   try{event('observer_uncaught_exception',{pid:process.pid,code:error.code||null,
     message:error.message,stack:error.stack});}catch{}

package/src/decision-profile.mjs

@@ -1,15 +1,29 @@
 // Opt-in, bounded local diagnostics. Never include paths, command arguments,
 // environment values, source, or probe output in a timing record.
 import fs from 'node:fs';
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {randomUUID} from 'node:crypto';
 
 const file=process.env.REDUE_DECISION_PROFILE_FILE;
 export const profiling=process.env.REDUE_DECISION_PROFILE==='1'&&!!file;
 
+const traces=new AsyncLocalStorage();
+const safe=value=>typeof value==='string'&&/^[a-zA-Z0-9_-]{1,64}$/.test(value)?value:undefined;
+const clean=value=>Object.fromEntries(['request','generation','work'].map(key=>[key,safe(value?.[key])]).filter(([,v])=>v));
+let base={};
+try{base=clean(JSON.parse(process.env.REDUE_PROFILE_CONTEXT||'{}'));}catch{}
+export const traceContext=()=>profiling?{...base,...traces.getStore()}:{};
+export function traceBase(value){if(profiling)base=clean(value);}
+export const traceId=()=>randomUUID();
+export const traceScope=(value,fn)=>profiling?traces.run({...traceContext(),...clean(value)},fn):fn();
+export const traceEnvironment=()=>profiling?{...process.env,REDUE_PROFILE_CONTEXT:JSON.stringify(traceContext())}:process.env;
+export function mark(phase,fields={}){timing(phase,performance.now(),fields);}
+
 export function timing(phase,started,counts={}) {
   if(!profiling)return;
   const memory=process.memoryUsage();
   try{fs.appendFileSync(file,'REDUE_TIMING '+JSON.stringify({
-      at:Date.now(),pid:process.pid,phase,
+      at:Date.now(),monoNs:process.hrtime.bigint().toString(),pid:process.pid,phase,...traceContext(),
       ms:Math.round((performance.now()-started)*10)/10,
       rssMiB:Math.round(memory.rss/1048576*10)/10,
       ...counts

package/src/direct-typescript-probe.mjs

@@ -4,10 +4,9 @@ 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';
+import {timing,mark} 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);
@@ -22,8 +21,16 @@ try{
   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 started=performance.now();mark('certificate.input_start');
+    // A synchronous fd-0 read can stall with spawnSync's piped input on macOS
+    // Node 22.13.0. Drain the stream without blocking its input delivery. The
+    // parent's existing deadline and the same size limit remain authoritative.
+    const chunks=[];let bytes=0;
+    for await(const chunk of process.stdin){
+      bytes+=chunk.length;if(bytes>8*1024*1024)throw Error('certificate too large');
+      chunks.push(chunk);
+    }
+    const raw=Buffer.concat(chunks).toString('utf8');mark('certificate.input_complete',{bytes});
     const certificate=JSON.parse(raw),kinds=new Set(['readDirectory','readFile',
       'fileExists','directoryExists','realpath','directories','entries']);
     if(certificate.schema!==1||certificate.context!==contextHash||
@@ -34,7 +41,9 @@ try{
           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');
+    mark('certificate.queries_start',{queries:certificate.queries.length});
     const matched=queriesMatch(certificate.queries);
+    mark('certificate.queries_complete',{matched});
     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);

package/src/direct-typescript.mjs

@@ -7,17 +7,21 @@ import {realObservedPath,withinPath} from './path-identity.mjs';
 export const directInterpretation='npm-direct-typescript@1';
 export const directQualification='npm-typescript-direct-v1';
 const reviewed={
+  '5.5.2':{entry:'lib/tsc.js',digest:'953b4844b5f6edc745be844b6c367c227b59029b73c4182f508f90cc47e21816'},
   '5.6.3':{entry:'lib/tsc.js',digest:'e674b5dc4dac50f6e91be30094aeea983a1f340231717e62b0b6199ae3049eb2'},
   '5.9.3':{entry:'lib/_tsc.js',digest:'d1b32e75475710fdc85102b1365254d84ceb192d3639d962c53fe1355ce274ca'},
 };
 const fail=code=>{throw Object.assign(Error(code),{code});};
 const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
 export const directEnvironment={variables:['NODE_ENV','NODE_OPTIONS','NODE_PATH','NODE_COMPILE_CACHE','VSCODE_INSPECTOR_OPTIONS'],
-  prefixes:['NODE_','DYLD_','LD_','TSGO_','TSC_'],executableIdentity:true};
+  prefixes:['NODE_','DYLD_','LD_','TSGO_','TSC_','TS_ETW_'],executableIdentity:true};
 export function directEnvironmentIssue(env=process.env){
   if(![22,24].includes(Number(process.versions.node.split('.')[0])))return 'direct-node-version-unsupported';
   if(env.VSCODE_INSPECTOR_OPTIONS)return 'direct-execution-environment-unsupported';
   for(const [key,value] of Object.entries(env)){
+    // The 5.5.2 API can require this unreviewed module during probe loading.
+    // Reject even empty/case aliases; do not mutate the caller's environment.
+    if(/^TS_ETW_MODULE_PATH$/i.test(key))return 'direct-execution-environment-unsupported';
     if(/^NODE_/i.test(key)){
       // Node 22.13.0 predates env-proxy initialization. This injected flag is
       // inert there, but remains strictly fingerprinted as NODE_ context.

package/src/history-worker.mjs

@@ -1,6 +1,8 @@
 // Native history is an optional acceleration. Keep its operations off the
 // control thread so a wedged native call cannot block status or shutdown.
 import fs from 'node:fs';
+import {mark} from './decision-profile.mjs';
+mark('history.worker_loaded');
 import watcher from '@parcel/watcher';
 
 try {
@@ -10,8 +12,11 @@ try {
   catch(e){if(e.code!=='ENOENT')throw e;}
   if(fault==='hang')Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0);
   if(fault==='fail')throw Error('injected history failure');
+  mark('history.snapshot_start');
   await watcher.writeSnapshot(root,next,{backend});
+  mark('history.snapshot_complete');
   const changes=previous?await watcher.getEventsSince(root,previous,{backend}):[];
+  mark('history.events_complete',{events:changes.length});
   process.send({ok:true,changes});
 } catch(error) {
   process.send({ok:false,error:error.message,code:error.code||error.name});

package/src/observation.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import {mark,traceEnvironment} from './decision-profile.mjs';
 import path from 'node:path';
 import {randomUUID} from 'node:crypto';
 import {fork} from 'node:child_process';
@@ -11,11 +12,12 @@ const workerFile=path.join(path.dirname(fileURLToPath(import.meta.url)),'history
 export function history(root,cursor,backend,deadlineMs,faultFile) {
   const next=cursor+'.'+randomUUID()+'.next';
   return new Promise((resolve,reject)=>{
+    mark('history.submit',{deadlineMs});
     const worker=fork(workerFile,[root,fs.existsSync(cursor)?cursor:'',next,backend,
-      faultFile||''],{stdio:['ignore','ignore','ignore','ipc']});
+      faultFile||''],{stdio:['ignore','ignore','ignore','ipc'],env:traceEnvironment()});
     let settled=false,abandoned=false;
     const finish=(error,value)=>{
-      if(settled)return;settled=true;clearTimeout(timer);
+      if(settled)return;settled=true;mark('history.complete',{childPid:worker.pid,outcome:error?.code||error?.name||'ok',events:value?.length});clearTimeout(timer);
       worker.kill('SIGKILL');
       if(error){abandoned=true;try{fs.unlinkSync(next);}catch{}
         reject(error);return;}

package/src/plan-worker.mjs

@@ -7,8 +7,9 @@ import {InputIndex} from './index.mjs';
 import {directProject,directQualification} from './direct-typescript.mjs';
 import {queriesMatch} from './typescript-list.mjs';
 import {planGuard,inputKey} from './decision-validation.mjs';
-import {timing} from './decision-profile.mjs';
+import {timing,traceBase} from './decision-profile.mjs';
 
+traceBase(workerData.diagnostic);
 try {
   const totalStarted=performance.now();
   const configStarted=performance.now();