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

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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.
+- Preserve ordinary npm execution as a separate, recording-only obligation.
+  Direct compilation requires explicit selection and a fresh baseline receipt.
+- Initial direct recipe supports reviewed TypeScript 5.6.3/5.9.3 in single-package
+  npm projects, with documented Node/environment restrictions.
+- Claude integration mechanics are tested; Claude behavior and cross-host reuse
+  remain untested. No universal compliance or inexpensive-check speedup is claimed.
+
 ## 0.1.0-alpha.4 — 2026-10-07
 
 - Withdraw automatic npm-launcher applicability because update notifications consume

package/README.md

@@ -37,6 +37,11 @@ it; relevant source edits make it stale. [Run the reproducible demo](docs/contri
 
 ## Install the alpha
 
+This branch prepares **alpha.5**, not yet published. Its opt-in agent activation
+and npm direct-compiler recipe require the candidate tarball; public alpha.4
+contains only the applicability correction.
+
+
 REDUE is published on npm as `@redue/cli`. The installed command is `redue`.
 
 ```sh
@@ -71,6 +76,30 @@ Start with ordinary `status`. When it cannot establish caller context, use
 **Synchronization can cost more than rerunning a cheap check, particularly on
 Windows.** REDUE does not choose or execute that tradeoff for you.
 
+Since alpha.4, ordinary npm scripts are recording-only after
+[an npm launcher applicability gap](docs/acceptance/npm-launcher-boundary.md).
+A separate explicit [direct compiler recipe](docs/user/direct-typescript.md) can
+qualify supported npm typechecks. It does not claim that npm/lifecycle scripts ran.
+
+## Connect your agent (candidate)
+
+```sh
+redue agent setup codex --dry-run
+redue agent setup codex --apply  # or claude
+redue agent doctor
+```
+
+Start a fresh agent session and give it an ordinary task. Project-local guidance
+teaches it to inspect evidence before deciding whether verification needs repeating.
+Setup is explicit, reversible, and does not change tool permissions or run checks.
+[Activation, removal, and generic-agent guidance](docs/user/agents.md).
+
+Alpha.5's claim is **opt-in project-local agent activation and direct TypeScript
+evidence, with fresh-session reuse demonstrated in the tested Codex/macOS
+configuration**. Claude setup/removal mechanics are tested; Claude behavior and
+cross-host reuse are not. This is experimental guidance, not guaranteed agent
+compliance, general sandbox compatibility, or a promise of time savings.
+
 ## What the states mean
 
 | State | Meaning | Normal next step |
@@ -89,8 +118,10 @@ has been verified.
 - macOS, Linux, and Windows on supported local filesystems; Node 22+.
 - Linux also requires Python 3 for observation. No WSL or Git Bash needed on Windows.
 - npm, pinned Yarn `node-modules`, and pinned pnpm 12 isolated/hoisted layouts.
-- Automatic qualification for the supported Yarn/pnpm TypeScript invocations; npm
-  launcher checks are recording-only in alpha.4. Workspace
+- Automatic qualification for supported Yarn/pnpm TypeScript invocations; ordinary npm
+  launcher checks remain recording-only. The alpha.5 candidate adds an explicit
+  [direct local compiler recipe](docs/user/direct-typescript.md) for the reviewed
+  npm/TypeScript boundary. Workspace
   boundaries follow the files actually consumed, including built declarations.
 - Existing test/lint/build and arbitrary commands can record results while
   their applicability remains unqualified.

package/bin/redue.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
+import {directCompiler,directQualification,directEnvironment,directInterpretation} from '../src/direct-typescript.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
@@ -9,7 +10,8 @@ import {fileURLToPath} from 'node:url';
 import {discoverNodeProject} from '../src/node-onboarding.mjs';
 import {processAlive} from '../src/process-liveness.mjs';
 import {samePath,withinPath,realObservedPath} from '../src/path-identity.mjs';
-import {stateIdentity,userStateBase} from '../src/platform-state.mjs';
+import {discoverConfig,projectState,canonicalConfig} from '../src/project-location.mjs';
+import {agentCommand} from '../src/agent-integration.mjs';
 import {findExecutable} from '../src/executable-lookup.mjs';
 import {readCachedStatus} from '../src/cached-state.mjs';
 import {assertOwnedStatePlacement} from '../src/owned-state.mjs';
@@ -22,8 +24,12 @@ const help=`REDUE ${version}
 Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
 
 Commands:
-  init [--dry-run] [--workspace NAME] [--check KIND]
+  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct]
                        Discover existing scripts; optionally select one workspace/check
+  agent setup codex|claude [--dry-run|--apply] [--json]
+  agent doctor [codex|claude] [--json]
+  agent remove codex|claude [--dry-run|--apply] [--json]
+                       Connect project instructions; explicit setup only
   start                Start the local observer
   stop                 Stop this observer
   status [--json|--short] Read conservative cached status
@@ -39,10 +45,7 @@ function error(message){console.error(`redue: ${message}`);process.exit(2);}
 const args=process.argv.slice(2);
 if(args.length===1&&args[0]==='--version'){console.log(version);process.exit(0);}
 if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);process.exit(0);}
-const preferredConfig=path.resolve('redue.config.json');
-const legacyConfig=path.resolve('vstate.config.json');
-let configFile=fs.existsSync(preferredConfig)||!fs.existsSync(legacyConfig)?
-  preferredConfig:legacyConfig,stateOverride=null;
+let configFile=null,stateOverride=null;
 for(let i=0;i<args.length;){
   if(args[i]==='--config'||args[i]==='--state-dir'){
     const flag=args[i],value=args[i+1];if(!value)error(`${flag} requires a path`);
@@ -51,17 +54,26 @@ for(let i=0;i<args.length;){
   }else i++;
 }
 const command=args.shift();
+try{configFile??=command==='init'||stateOverride&&['stop','remove-state'].includes(command)?
+  path.resolve(fs.existsSync('redue.config.json')||!fs.existsSync('vstate.config.json')?'redue.config.json':'vstate.config.json'):discoverConfig();}
+catch(e){error(e.message);}
+if(fs.existsSync(path.dirname(configFile)))configFile=canonicalConfig(configFile);
+if(command==='agent'){
+  try{await agentCommand(args,{configFile,stateOverride,entry:fileURLToPath(import.meta.url)});}
+  catch(e){error(e.message);}
+  process.exit(0);
+}
 if(!['init','start','stop','status','detail','explain','run','remove-state'].includes(command))
   error(`unknown command ${command||'<none>'}; use --help`);
 const json=args.includes('--json');
 const sync=args.includes('--sync');
 const dryRun=args.includes('--dry-run');
 const short=args.includes('--short');
-let workspaceSelection=null,checkSelection=null;
+let workspaceSelection=null,checkSelection=null,recipeSelection=null;
 if(command==='init')for(let i=0;i<args.length;){
-  if(args[i]==='--workspace'||args[i]==='--check'){
+  if(args[i]==='--workspace'||args[i]==='--check'||args[i]==='--recipe'){
     const flag=args[i],value=args[i+1];if(!value||value.startsWith('--'))error(`${flag} requires a name`);
-    if(flag==='--workspace')workspaceSelection=value;else checkSelection=value;
+    if(flag==='--workspace')workspaceSelection=value;else if(flag==='--recipe')recipeSelection=value;else checkSelection=value;
     args.splice(i,2);
   }else i++;
 }
@@ -73,7 +85,7 @@ if(short&&(command!=='status'||json||sync))error('--short is a cached status opt
 if(dryRun&&command!=='init')error('--dry-run is for init');
 
 if(command==='init'){
-  let discovery;try{discovery=discoverNodeProject(process.cwd());}
+  let discovery;try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
   catch(e){error(e.message);}
   if(workspaceSelection||checkSelection){
     const chosen=discovery.checks.filter(row=>
@@ -104,7 +116,7 @@ if(command==='init'){
       console.log(`  ${row.name} (${row.script||row.command?.join(' ')}) — `+
         `${{ready:'ready to qualify',recording:'recording-only',unsupported:'unsupported'}[row.level]||row.level}: ${row.reason}`);
       if(row.script&&row.command)console.log(`    Recorded invocation: ${row.command.map(value=>
-        value==='@node'?'node':value.startsWith('@typescript-bin:')?
+        value==='@node'?'node':value==='@typescript-compiler:.'?'[reviewed local TypeScript compiler implementation]':value.startsWith('@typescript-bin:')?
           `[installed TypeScript in ${value.slice('@typescript-bin:'.length)}]`:value).join(' ')}`);
     }
     for(const row of summary.ambiguous)
@@ -121,6 +133,7 @@ if(command==='init'){
     if(!json){console.log(`Created ${configFile}. No checks were executed.`);
       console.log('Ready to qualify means the supported contract will be validated; it is not verification evidence.');
       console.log(`Next: review the config, then redue start and redue run ${JSON.stringify(discovery.checks[0].config.name)}.`);
+      console.log('Connect your agent: redue agent setup codex (or claude). Preview with --dry-run.');
       console.log('Use redue status first. --sync can establish applicability, but may cost more than rerunning a cheap check.');}
   } else if(unsupported&&!json)console.log(`No config written: ${summary.issue||'unsupported discovery boundary'}.`);
   if(json)console.log(JSON.stringify({...summary,proposed_config:discovery.config}));
@@ -157,10 +170,7 @@ for(const key of Object.keys(publicConfig))
   if(!['schema','root','checks','packageManager'].includes(key))error(`unsupported config field ${key}`);
 if(check&&!publicConfig.checks.some(row=>row.name===check))error(`unknown check ${check}; use redue status to list configured checks`);
 const root=realObservedPath(path.resolve(path.dirname(configFile),publicConfig.root||'.'));
-const stateBase=userStateBase(process.platform,process.env,os.homedir());
-const state=stateOverride||path.join(stateBase,'vstate',
-  `vstate-${createHash('sha256').update(stateIdentity(root)+'\0'+
-    stateIdentity(configFile)).digest('hex').slice(0,16)}`);
+const state=stateOverride||projectState(root,configFile);
 if(!/^(?:vstate|redue)-/.test(path.basename(state)))
   error('--state-dir must name a dedicated redue-* directory outside the checkout (legacy vstate-* is also supported)');
 const runtimeFile=path.join(state,'project-runtime-v1.json');
@@ -172,6 +182,10 @@ function which(name){
 function token(value){
   if(value==='@node')return process.execPath;
   if(value==='@project')return root;
+  if(value==='@typescript-compiler:.'){
+    try{return directCompiler(root,{verify:false}).entry;}catch(e){error(`direct compiler unavailable: ${e.code||e.message}`);}
+  }
+  if(value==='@vstate/direct-typescript-probe')return path.join(productRoot,'src','direct-typescript-probe.mjs');
   if(value.startsWith('@typescript-bin:')){
     const dir=value.slice('@typescript-bin:'.length);
     if(!dir||path.isAbsolute(dir)||dir.split('/').includes('..'))
@@ -208,8 +222,9 @@ const checks=publicConfig.checks.map(check=>{
   for(const category of categories)if(check.coverage?.[category]&&
     typeof check.coverageReview?.[category]!=='string')
     error(`${check.name}: reviewed coverage ${category} needs a rationale`);
+  const npmDirect=check.qualification===directQualification;
   const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
-  if(check.script&&check.command&&!pnpmTypecheck)
+  if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect)
     error(`${check.name}: choose script or command, not both`);
   const manager=publicConfig.packageManager;
   if(check.script&&!['npm','yarn','pnpm'].includes(manager))
@@ -218,8 +233,11 @@ const checks=publicConfig.checks.map(check=>{
     [`@which:${manager}`,'run',check.script]:null;
   const npmAutomatic=check.qualification==='typescript-noemit-v1';
   const yarnWorkspace=check.qualification==='yarn-workspace-tsc-v1';
-  if(check.qualification&&!npmAutomatic&&!yarnWorkspace&&!pnpmTypecheck)
+  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck)
     error(`${check.name}: unknown qualification contract`);
+  if(npmDirect&&(manager!=='npm'||!check.script||check.cwd&&check.cwd!=='.'||
+    JSON.stringify(check.command)!==JSON.stringify(['@node','@typescript-compiler:.','--noEmit'])))
+    error(`${check.name}: direct recipe requires its explicit local compiler command`);
   if(npmAutomatic&&(manager!=='npm'||check.cwd&&check.cwd!=='.'))
     error(`${check.name}: automatic TypeScript qualification currently needs root npm script`);
   if(yarnWorkspace&&(manager!=='yarn'||!check.workspace||check.cwd&&check.cwd!=='.'||
@@ -237,7 +255,7 @@ const checks=publicConfig.checks.map(check=>{
     check.kind==='lint'?'lint plugins, config and resolver inputs need review':
     check.kind==='build'?'build environment and generated inputs need review':
     'check inputs need review';
-  const autoProbes=npmAutomatic?[['@node','@vstate/typescript-contract-probe',
+  const autoProbes=npmDirect?[['@node','@vstate/direct-typescript-probe','@project',check.script]]:npmAutomatic?[['@node','@vstate/typescript-contract-probe',
     '@project',check.script,'@which:npm']]:yarnWorkspace?
     [['@node','@vstate/yarn-workspace-typecheck-probe','@project',
       check.workspace,check.command[4],'@which:yarn']]:pnpmTypecheck?
@@ -245,7 +263,7 @@ const checks=publicConfig.checks.map(check=>{
       check.workspace||'.',check.script]]:[];
   const windowsContext=process.platform==='win32'?
     ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
-  const autoEnvironment=npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+  const autoEnvironment=npmDirect?directEnvironment:npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
     'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
     pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
@@ -257,7 +275,7 @@ const checks=publicConfig.checks.map(check=>{
   return {name:check.name,command:argv(scriptCommand||check.command,`${check.name}.command`),
     cwd:check.cwd,inputs:check.inputs||[],generatedInputs:check.generatedInputs||[],
     installedInputs:check.installedInputs||(
-      npmAutomatic?['node_modules/**']:[]),
+      npmAutomatic||npmDirect?['node_modules/**']:[]),
     allowedExternalRoots:check.allowedExternalRoots||[],
     probes:[...(check.probes||[]),...autoProbes]
       .map((p,i)=>argv(p,`${check.name}.probes[${i}]`)),
@@ -267,6 +285,7 @@ const checks=publicConfig.checks.map(check=>{
       categories.map(category=>[category,reason])),
     qualification:check.qualification||null,script:check.script||null,
     ...(npmAutomatic?{qualificationInterpretation:'npm-launcher-withheld@1'}:{}),
+    ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
     workspace:check.workspace||null,kind:check.kind||null};
 });
 const runtime={schema:1,provider:'declared-project@1',root,state,checks};

package/docs/README.md

@@ -5,7 +5,7 @@ For users:
 - [Install, initialize, run, and remove](user/getting-started.md)
 - [Supported projects and conservative boundaries](user/supported-projects.md)
 - [Configuration](user/configuration.md)
-- [Coding-agent decision policy](user/agents.md)
+- [Connect coding agents and apply the decision policy](user/agents.md)
 - [JSON contract](user/json.md)
 - [Shell usage](user/shell.md)
 

package/docs/user/agents.md

@@ -1,11 +1,11 @@
 # Agent decision policy
 
-Use the CLI; no SDK or bespoke agent integration is required. Add these
-instructions to a session or project only with its owner's permission.
+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. If a check has `freshness: "CURRENT"`, `result: "PASS"`, and
-   `reuse_eligible: true`, reuse it. Do not rerun merely for freshness.
+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.
@@ -25,8 +25,138 @@ check is not universal product correctness. Report additional uncaptured checks
 separately. Do not infer that an outer invocation's success proves a specific
 check ran or that an upstream cache was hit; inspect `target_provenance`.
 
+Reassess at the decision point after edits or context changes; previous CURRENT is
+not continuing authorization. A status exit code of zero is not proof of CURRENT.
+An empty changed-input list does not prove nothing changed. `run CHECK --json`
+streams check output; use a subsequent status/explain query for structured evidence.
+Explicit fresh-execution requests still require execution.
+
 On a CLI error, unhealthy observation, or unavailable context, do not infer
 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)
+
+The alpha.5 candidate supports 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
+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:
+
+```sh
+redue agent setup codex --dry-run
+redue agent setup codex --apply
+# Or: redue agent setup claude --apply
+redue agent doctor
+```
+
+Start a fresh agent session in this checkout, then give it your ordinary task.
+Interactive setup shows the changes and asks before applying; noninteractive
+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.
+
+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
+policy source; detailed guidance is loaded when verification is relevant. Small
+ownership records in `.redue/agents/` support safe updates/removal. These are
+portable project files, not receipts; review and commit them if the team wants
+this integration. Do not ignore just the ownership records while committing the
+managed files.
+
+Existing instruction text is retained. Review it in the preview: setup cannot
+prove arbitrary natural-language policies are consistent. Conflicts such as a
+root `AGENTS.override.md` or an alternative `.claude/CLAUDE.md` are reported
+instead of silently outranked. Global/managed policies, nested instructions,
+Codex instruction-size limits, skill disabling, and host-specific exclusions
+still apply. Complete the host's ordinary trust/permission prompts yourself;
+REDUE never grants tool permission. Sandboxed hosts may need owner-approved access
+to the checkout, owned state directory and local observer socket. A healthy daemon
+does not establish that the agent can reach it; doctor reports control access
+separately. Do not disable sandbox protections to make this work. Do not use a mode that disables project
+instructions and expect automatic activation.
+
+Control access is not simply file-read permission. The observer can reconcile and
+write its owned index, run the trusted configuration's probes in its own process
+context, reload receipts, and stop. Approve only the intended checkout/state and
+endpoint, accounting for that authority. Doctor sends only a bounded metrics
+request; it does not synchronize or run these probes.
+
+`agent doctor [codex|claude] --json` is read-only. It distinguishes command lookup,
+config resolution, cached observer health, a bounded read-only control-access probe,
+managed-file integrity, detected host
+version, and loading guidance. `behavior_verified: false` is deliberate: intact
+files do not prove the agent followed them. No hooks are installed. Doctor neither
+executes checks nor starts observers, reconciles inputs, or installs a host.
+
+Doctor separates missing/unreadable state, a missing or refused endpoint, an
+explicit EPERM/EACCES access denial, and timeout/invalid response. A denial does
+not identify whether OS permissions or host policy caused it. A live PID and
+healthy cached observation do not prove control access. An older cached response
+without receipt-selection validation gets stop/start guidance. Windows command
+shims whose target has not been established are reported as unknown, not a
+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
+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
+run npm. Its reviewed compiler implementation does not consume npm/proxy settings;
+a digest preserves their observed provenance without treating them as compiler
+inputs. Other execution context remains strict, and cached status still cannot
+assert caller eligibility. An explicit user request for `npm run typecheck` still
+requires npm execution; direct compiler evidence is not a substitute.
+
+Before model trials, run `redue agent doctor --json` and
+`redue status --sync --json` inside the agent's actual command boundary. The
+contributor helper `test/acceptance/codex-preflight.mjs --config FILE --check CHECK`
+performs the same bounded, read-only decision check and exits 2 when reuse is not
+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
+content idempotently. Changed skill text or a changed managed block causes a
+conflict instead of an overwrite. Review your edits before retrying.
+
+```sh
+redue agent remove codex --dry-run
+redue agent remove codex --apply
+redue agent remove claude --apply
+```
+
+Removal deletes only intact REDUE-owned content for that host. Unrelated text,
+other integrations, project config, receipts and installed dependencies remain.
+User edits outside the managed section survive. Modified managed content is left
+intact with a diagnostic; compare it with a preview and resolve manually. Empty
+parent directories may remain. If the selected config has been deleted, restore
+it or manually remove only the marked REDUE section, that host's skill, and its
+`.redue/agents/HOST.json` ownership record after review. Do not delete an entire
+instruction file containing user content.
+
+## Project identity and generic agents
+
+Commands from nested directories search toward the nearest Git root. If more than
+one configuration applies, select one with `--config FILE`; REDUE refuses to guess.
+The generated instruction names its project-relative configuration and applies it
+to status/run/explain. External configs or custom machine-local `--state-dir`
+setups should use a reviewed generic instruction instead of committing absolute
+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
+[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,
+dependencies and state. There is no cloud/team receipt synchronization.

package/docs/user/configuration.md

@@ -1,7 +1,7 @@
 # Configuration
 
-Prefer `redue init` over hand-authoring a qualified contract. A typical generated
-npm configuration is concise and portable:
+Prefer `redue init` over hand-authoring a contract. An ordinary generated npm script (recording-only in this candidate)
+configuration is concise and portable:
 
 ```json
 {
@@ -28,6 +28,9 @@ Use `--config FILE` to select an external configuration. `root` is relative to
 that file. Runtime paths, resolved executables, local evidence, and sockets stay
 out of version-controlled configuration.
 
+For the explicit direct compiler choice and generated exact argv, see
+[direct TypeScript](direct-typescript.md). Existing script receipts cannot satisfy it.
+
 ## Arbitrary commands
 
 An unrecognized ecosystem can still record ordinary execution:

package/docs/user/direct-typescript.md

@@ -0,0 +1,96 @@
+# Explicit local TypeScript verification (unreleased candidate)
+
+This check means: the reviewed local TypeScript compiler completed the configured
+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:
+
+```sh
+redue init --recipe typescript-direct --check typecheck --dry-run
+redue init --recipe typescript-direct --check typecheck
+redue start
+redue run typecheck
+redue status --sync
+```
+
+The preview shows the discovered script and recorded direct invocation. Nothing
+executes during init. package.json, environment and dependencies remain unchanged.
+A generated check contains:
+
+```json
+{
+  "name": "typecheck",
+  "script": "typecheck",
+  "kind": "typecheck",
+  "command": ["@node", "@typescript-compiler:.", "--noEmit"],
+  "cwd": ".",
+  "qualification": "npm-typescript-direct-v1",
+  "inputs": ["package.json", "package-lock.json", "tsconfig.json", "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,jsonc}", "!node_modules/**", "!.git/**"]
+}
+```
+
+`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,
+without its outer compile-cache-enabling shim. No compiler is fetched or bundled.
+The entire installed package must match reviewed official distribution bytes.
+
+Existing configs are never overwritten. To compare choices, use a new project-local
+`--config redue.direct.config.json` with init; this explicitly selects separate
+state. To replace an existing check deliberately, preview JSON, stop its observer,
+review/edit that check's config, and restart using the same config/state. Existing
+npm receipts remain historical; the new command/interpretation needs a fresh run.
+Do not delete receipts. `redue run` always executes the configured command.
+
+## Existing npm configuration: deliberate replacement
+
+First upgrade through the [alpha.4 containment](npm-launcher-notice.md), stopping
+observers before the installation change and restarting with the same config/state.
+The old npm check becomes recording-only; its receipts remain historical.
+To opt into this candidate afterward:
+
+1. Stop the observer, install the reviewed candidate tarball into the same prefix,
+   and keep the original `redue.config.json` and any explicit `--state-dir` selection.
+2. Run `redue init --recipe typescript-direct --check typecheck --dry-run --json`
+   using that config selection. Inspect `proposed_config.checks` and the recorded
+   invocation. This does not write anything, even when the config already exists.
+3. In your editor, replace only the intended check object with the reviewed proposed
+   object. Preserve its name, the top-level project configuration, and every other
+   check. Do not replace the whole config with a one-check preview. Keep a local
+   backup outside observed inputs if desired.
+4. Run `redue start` with the same config/state. `redue status --sync --json` must
+   not treat the old npm receipt as eligible compiler evidence.
+5. Run `redue run typecheck`, then `redue status --sync --json`. A qualified success
+   now records the direct compiler recipe with a new run ID. Old npm runs remain
+   immutable history. Other check definitions are unchanged.
+
+Substitute the actual selected check name throughout. Repeating plain `init`
+does **not** migrate an existing config. A deliberately separate `--config` file
+is useful for comparison, but has separate state by design. Do not create one
+accidentally when intending to preserve the original selection.
+
+Pre/post scripts, compound commands, wrappers, environment assignments, workspace
+projects and unsupported compiler versions are not automatically converted.
+Init retains the original script with a reason. Development-mode source-map helpers,
+Node preloads/loaders/compile-cache settings, unsupported compiler plugins or
+incremental/composite configuration, outside-root inputs and uncertain observation
+withhold applicability. Extra custom probes cannot inherit this recipe's context
+exception. Relevant source, declaration, config, membership and installed-content
+changes invalidate or withdraw applicability normally.
+
+The versioned `npm-direct-typescript@1` interpretation retains relevant Node context
+and identity. Reviewed compiler code does not parse npm settings or proxy variables;
+these remain untouched in the child environment and are recorded only as a digest
+of observed provenance. This is not an environment ignore option for arbitrary
+commands or other providers. No remote service equivalence is claimed. Ordinary
+cached status remains conservative; synchronize deliberately when worth the cost.
+
+Explain/JSON report `verification_recipe: "npm-direct-typescript@1"` for receipts
+recorded with this recipe. Report compiler evidence as compiler evidence. A user's
+explicit request for `npm run typecheck` is not satisfied by this different command.
+
+The injected `NODE_USE_ENV_PROXY=1` setting is admitted only on Node 22.13.0,
+where it is inert; it remains strictly tracked. Other Node versions with this
+setting need review and stay unqualified. REDUE does not alter the setting.

package/docs/user/getting-started.md

@@ -90,7 +90,10 @@ 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; other scripts run through the package manager.
+compiler invocation it selects. In this candidate, 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.
 Only use configs and probes from trusted repositories: these execute local code.
 
 `status` is cached and conservative. `status --sync` and `explain` revalidate caller
@@ -133,3 +136,11 @@ all observed roots; its basename must start with `redue-` or legacy `vstate-`.
 For a removed checkout, `redue --state-dir /your/owned/redue-project-state remove-state`
 still works without rebuilding its compiler/configuration. Ownership/active-run conflicts
 are actionable errors, never resolved merely by deleting an old lock.
+
+## Connect an agent explicitly
+
+After initialization, use `redue agent setup codex --dry-run` (or `claude`) to
+review project-local instructions, then repeat with `--apply`. Start a fresh host
+session. `redue agent doctor` checks prerequisites without running verification.
+See [agent activation](agents.md) for loading rules, generic agents, and removal.
+The released alpha.2 does not contain these candidate commands yet.

package/docs/user/supported-projects.md

@@ -15,13 +15,15 @@ At the repository root, `init` looks for existing typecheck, test, lint, and
 build scripts. It prefers familiar script names, then unique recognizable
 `tsc`, Vitest/Jest, ESLint, or Vite commands under other names. Multiple
 matches are reported as ambiguous rather than guessed. It never creates a new
-project script. Canonical `tsc --noEmit` npm scripts are discovered and recorded, but their
-automatic applicability is withdrawn in alpha.4: npm's update notification uses
-remote/cache/time inputs outside the observed contract. Even a successful run
-remains UNVERIFIED/PASS. Historical receipts are retained. See the
-[maintainer notice](npm-launcher-notice.md). A separately selected verification
-obligation would require an explicit configuration and fresh evidence; alpha.4
-does not provide the unreleased npm direct-compiler recipe. Root and package-level npm/Yarn workspace scripts are discovered from
+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,
+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,
+configuration or outside-root inputs remain UNVERIFIED. Root and package-level npm/Yarn workspace scripts are discovered from
 `package.json` workspace declarations. Pinned Yarn 4 `node-modules`/classic
 workspaces with a standalone `tsc -p .` script, local TypeScript, a conventional
 `src` include, and Node module resolution can qualify automatically. For one

package/package.json

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