@redue/cli 0.0.0-stage → 0.1.0-alpha.2

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0-alpha.2 — 2026-10-06
+
+Install: `npm install --global @redue/cli@alpha`.
+
+- npm distribution moved to the product-owned `@redue/cli` package.
+- The executable remains `redue`; verification semantics and runtime code are unchanged.
+- Alpha.1 (`@msiric/redue`) remains available but is superseded by the canonical package.
+
+## 0.1.0-alpha.1 — 2026-10-06
+
+Install: `npm install --global @msiric/redue@alpha`. The command remains `redue`.
+
+- Persistent execution evidence with independent CURRENT, STALE, and UNVERIFIED applicability.
+- Node/TypeScript onboarding for npm, supported Yarn node-modules workspaces, and pnpm 12 isolated/hoisted layouts.
+- macOS, Linux, and Windows observation with conservative deterministic recovery.
+- Human status/explain output, JSON integration contract, and recording-only checks.
+- Standard npm tarball installation and scoped state cleanup.
+
+Known limitations include incomplete test/lint/build contracts, uncaptured direct
+commands, and synchronized decisions that can cost more than cheap checks. See README.

package/LICENSE

@@ -0,0 +1,180 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# REDUE
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Know what still holds. Redo what's due.**
+
+You ran the checks. Then the code changed—or a new coding agent started with no
+conversation history. Which results can you still use?
+
+REDUE keeps persistent verification state for your codebase so developers and
+coding agents can see which previous checks still apply to the code they have now.
+It records evidence, not proofs of correctness.
+
+```text
+$ redue status --sync
+✓ typecheck  CURRENT / PASS
+? test  UNVERIFIED / PASS
+  Recording-only: test runtime, transforms and cache inputs need review
+
+# Later, after a relevant edit:
+$ redue explain typecheck
+typecheck: STALE / PASS
+src/main.ts changed
+Relevant inputs changed:
+  src/main.ts
+Due again when verification is needed: redue run "typecheck"
+```
+
+Agent A verifies and exits. Agent B starts fresh. The receipt is still there;
+REDUE checks whether it still applies. Unrelated documentation edits can preserve
+it; relevant source edits make it stale. [Run the reproducible demo](docs/contributor/demo.md).
+
+## Install the alpha
+
+REDUE is published on npm as `@redue/cli`. The installed command is `redue`.
+
+```sh
+npm install --global @redue/cli@alpha
+```
+
+To test a source candidate, run `npm ci` and `npm pack --json`, then install the
+reported tarball filename with `npm install --global ./<filename>`.
+
+Use a Node installation you own; REDUE does not need administrator privileges.
+If a global prefix is not writable, use a user-owned `--prefix` or run the
+installed CLI with Node. [Installation and removal](docs/user/getting-started.md)
+includes PowerShell and isolated-prefix instructions.
+
+Inside an existing, trusted Git project with dependencies already installed:
+
+```sh
+cd my-project
+redue init
+redue start
+redue run typecheck  # use a check name printed by init
+redue status
+```
+
+`init` discovers existing scripts, explains which can qualify and which are
+recording-only, and writes a small `redue.config.json`. It never runs your checks
+or changes your package manager, source, scripts, or dependencies. Commit the
+reviewed project config; local evidence stays outside the checkout.
+
+Start with ordinary `status`. When it cannot establish caller context, use
+`redue status --sync` if that is worthwhile—or just rerun an inexpensive check.
+**Synchronization can cost more than rerunning a cheap check, particularly on
+Windows.** REDUE does not choose or execute that tradeoff for you.
+
+## What the states mean
+
+| State | Meaning | Normal next step |
+| --- | --- | --- |
+| CURRENT | The recorded result applies to the declared inputs. | Reuse a passing result; do not rerun merely for freshness. |
+| STALE | Relevant inputs changed since the recorded result. | Rerun when verification is needed. |
+| UNVERIFIED | Applicability is unknown: no receipt, incomplete coverage, pending observation, or missing context. | Read the reason; synchronize if worthwhile, or run the check. |
+| FAILED | The invocation failed. Its applicability is tracked separately. | Keep the failure visible; it is not green evidence. |
+
+A historical PASS remains PASS when stale or unverified. A historical failure
+never becomes a successful check. CURRENT does not mean every product behavior
+has been verified.
+
+## Supported alpha path
+
+- 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 supported TypeScript invocations; 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.
+
+The [supported-project boundary](docs/user/supported-projects.md) is deliberately
+narrow. A script named `test` is not automatically a complete test contract.
+
+## Alpha limitations
+
+- REDUE records evidence; it does not prove correctness.
+- Direct commands outside `redue run` do not create receipts.
+- Some tests, lints, and builds remain UNVERIFIED/PASS because their input contract is incomplete.
+- Synchronized applicability has nontrivial cost and can lose to an inexpensive rerun.
+- Unsupported/exotic install layouts and filesystems remain conservative; they do not become green through guesses.
+- No cloud/team synchronization, IDE extension, or automatic background check execution.
+- Alpha configuration and APIs may evolve. Neither cached nor synchronized status is an atomic snapshot against concurrent edits.
+
+## Humans, shells, and agents
+
+```sh
+redue explain typecheck          # synchronized explanation; may run read-only probes
+redue status --json              # conservative cached data
+redue status --sync --json       # caller-aware decision
+redue status --short             # small cached indicator; never synchronizes
+redue stop                      # retains historical receipts
+redue remove-state              # removes only this config's owned local state
+```
+
+Agents should use [the documented JSON interface](docs/user/json.md), not parse
+terminal prose. [The canonical agent loop](docs/user/agents.md) keeps the
+sync-versus-rerun choice explicit. [Shell usage](docs/user/shell.md) does not put
+synchronized work in a prompt.
+
+[User docs](docs/README.md) · [Contributing](CONTRIBUTING.md) ·
+[Architecture](docs/contributor/architecture.md) · [Acceptance evidence](docs/acceptance/README.md)
+
+## License
+
+REDUE is licensed under [Apache-2.0](LICENSE). Dependencies retain their own licenses.

package/bin/redue.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawn,spawnSync} from 'node:child_process';
+import {createRequire} from 'node:module';
+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 {findExecutable} from '../src/executable-lookup.mjs';
+import {readCachedStatus} from '../src/cached-state.mjs';
+import {assertOwnedStatePlacement} from '../src/owned-state.mjs';
+import {renderStatus,renderExplain} from '../src/presentation.mjs';
+
+const productRoot=path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const engine=path.join(productRoot,'src','cli.mjs');
+const version=JSON.parse(fs.readFileSync(path.join(productRoot,'package.json'))).version;
+const help=`REDUE ${version}
+Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
+
+Commands:
+  init [--dry-run] [--workspace NAME] [--check KIND]
+                       Discover existing scripts; optionally select one workspace/check
+  start                Start the local observer
+  stop                 Stop this observer
+  status [--json|--short] Read conservative cached status
+  status --sync        Reconcile inputs and caller context before answering
+  explain [CHECK] [--json] Explain applicability (synchronized; may cost more than a rerun)
+  detail [CHECK] [--json]  Alias for explain
+  run CHECK            Execute one configured check and record its outcome
+  remove-state         Stop and remove only this configuration's owned local state
+
+No checks run in the background. Direct commands outside redue create no receipts.`;
+
+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;
+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`);
+    if(flag==='--config')configFile=path.resolve(value);else stateOverride=path.resolve(value);
+    args.splice(i,2);
+  }else i++;
+}
+const command=args.shift();
+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;
+if(command==='init')for(let i=0;i<args.length;){
+  if(args[i]==='--workspace'||args[i]==='--check'){
+    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;
+    args.splice(i,2);
+  }else i++;
+}
+const check=['run','detail','explain'].includes(command)&&args[0]&&!args[0].startsWith('--')?args.shift():null;
+if(command==='run'&&!check)error('run requires a check name');
+if(args.some(value=>!['--json','--sync','--dry-run','--short'].includes(value)))error('unknown option; use --help');
+if(sync&&!['status','detail','explain'].includes(command))error('--sync is for status or detail');
+if(short&&(command!=='status'||json||sync))error('--short is a cached status option; do not combine it with --sync or --json');
+if(dryRun&&command!=='init')error('--dry-run is for init');
+
+if(command==='init'){
+  let discovery;try{discovery=discoverNodeProject(process.cwd());}
+  catch(e){error(e.message);}
+  if(workspaceSelection||checkSelection){
+    const chosen=discovery.checks.filter(row=>
+      (!workspaceSelection||row.config.workspace===workspaceSelection||
+        row.config.command?.[2]===workspaceSelection)&&
+      (!checkSelection||row.config.kind===checkSelection));
+    if(!chosen.length)error('no discovered check matches the selected workspace and kind');
+    discovery.checks=chosen;discovery.config.checks=chosen.map(row=>row.config);
+  }
+  const configured=fs.existsSync(configFile),unsupported=Boolean(discovery.observationIssue||
+    discovery.manager.issue&&!['npm','yarn','pnpm'].includes(discovery.manager.name)||
+    discovery.manager.name==='yarn'&&!discovery.manager.version);
+  const willWrite=!dryRun&&!configured&&!unsupported&&discovery.checks.length>0;
+  const summary={schema:1,repository:discovery.root,node:discovery.node,
+    package_manager:discovery.manager.name,version:discovery.manager.version,
+    installation_layout:discovery.manager.layout,
+    issue:discovery.observationIssue||discovery.manager.issue,workspaces:discovery.workspaces,
+    ambiguous:discovery.ambiguous,
+    checks:discovery.checks.map(({config:check,level,reason})=>({name:check.name,
+      script:check.script||null,command:check.command||null,
+      workspace:check.workspace||null,level,reason})),config:configFile,
+    written:willWrite,existing:configured};
+  if(!json) {
+    console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
+      `${summary.version?' '+summary.version:''}; ${summary.installation_layout} installation.`);
+    if(summary.issue)console.log(`Boundary: ${summary.issue}`);
+    for(const row of summary.checks){
+      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:')?
+          `[installed TypeScript in ${value.slice('@typescript-bin:'.length)}]`:value).join(' ')}`);
+    }
+    for(const row of summary.ambiguous)
+      console.log(`  ${row.kind}: ambiguous scripts (${row.scripts.join(', ')}); choose one explicitly`);
+    if(!summary.checks.length)console.log('No useful existing verification scripts found.');
+    console.log(configured?`Existing ${configFile} left unchanged.`:
+      dryRun?`Preview only; ${configFile} was not written.`:
+        willWrite?`Writing ${configFile}; inspect it before running checks.`:'No configuration will be written.');
+  }
+  if(willWrite){
+    if(!samePath(realObservedPath(path.dirname(configFile)),discovery.root))
+      error('init writes only at the repository root; use --config there or --dry-run');
+    fs.writeFileSync(configFile,JSON.stringify(discovery.config,null,2)+'\n',{flag:'wx'});
+    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('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}));
+  process.exit(0);
+}
+function printLifecycle(output,action,machine){
+  if(machine){process.stdout.write(output);return;}
+  let value;try{value=JSON.parse(output);}catch{process.stdout.write(output);return;}
+  if(action==='start'){
+    console.log(value.ready?'Observer ready.':'Observer started; checking inputs. Applicability stays UNVERIFIED until ready.');
+    console.log('Use redue status. Stop with redue stop.');
+  }else if(action==='remove-state')console.log(`Removed only REDUE-owned state: ${value.removed}`);
+  else console.log(value.ok?'Observer stopped. Historical evidence is retained.':
+    `Observer unavailable: ${value.reason||'not running'}. Previous evidence is not CURRENT.`);
+}
+// Owned-state maintenance must not need the checkout, its package manager,
+// or installed compiler to remain present. No command is run from this path.
+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);}
+  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);
+  if(result.stdout)printLifecycle(result.stdout,command,json);
+  process.exit(result.status??2);
+}
+let publicConfig;
+try{publicConfig=JSON.parse(fs.readFileSync(configFile,'utf8'));}
+catch(e){error(e.code==='ENOENT'?`no configuration at ${configFile}; run redue init from the project root, or use --config FILE`:`cannot read ${configFile}: ${e.message}`);}
+if(publicConfig.schema!==1)error('config schema must be 1');
+if(!Array.isArray(publicConfig.checks)||!publicConfig.checks.length)
+  error('config needs at least one explicitly defined check');
+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)}`);
+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');
+function which(name){
+  const found=findExecutable(name);
+  if(found)return found;
+  error(`cannot resolve executable ${name} on PATH`);
+}
+function token(value){
+  if(value==='@node')return process.execPath;
+  if(value==='@project')return root;
+  if(value.startsWith('@typescript-bin:')){
+    const dir=value.slice('@typescript-bin:'.length);
+    if(!dir||path.isAbsolute(dir)||dir.split('/').includes('..'))
+      error('TypeScript executable workspace path is unsafe');
+    const manifest=path.join(root,dir,'package.json');
+    let resolved;try{resolved=createRequire(manifest).resolve('typescript/package.json');}
+    catch{error('installed TypeScript compiler cannot be resolved');}
+    const compiler=path.join(path.dirname(realObservedPath(resolved)),'bin','tsc');
+    if(!withinPath(compiler,root)||!fs.existsSync(compiler))
+      error('TypeScript executable is outside the observed project');
+    return compiler;
+  }
+  if(value==='@vstate/npm-typecheck-probe')return path.join(productRoot,'src','npm-typecheck-probe.mjs');
+  if(value==='@vstate/typescript-contract-probe')return path.join(productRoot,'src','typescript-contract-probe.mjs');
+  if(value==='@vstate/yarn-workspace-typecheck-probe')return path.join(productRoot,'src','yarn-workspace-typecheck-probe.mjs');
+  if(value==='@vstate/pnpm-typecheck-probe')return path.join(productRoot,'src','pnpm-typecheck-probe.mjs');
+  if(value==='@vstate/toolchain-probe')return path.join(productRoot,'src','toolchain-probe.mjs');
+  if(value.startsWith('@which:'))return which(value.slice(7));
+  return value;
+}
+function argv(values,label){
+  if(!Array.isArray(values)||!values.length||values.some(v=>typeof v!=='string'||!v))
+    error(`${label} must be nonempty exact argv`);
+  return values.map(token);
+}
+const categories=['source','generated','installedDependencies','environment','toolchain','runtime',
+  'probeContinuity'];
+const checks=publicConfig.checks.map(check=>{
+  const allowed=['name','command','cwd','inputs','generatedInputs','installedInputs',
+    'allowedExternalRoots','probes','environment','coverage','coverageReview','coverageReasons',
+    'script','kind','qualification','workspace'];
+  for(const key of Object.keys(check))if(!allowed.includes(key))
+    error(`unsupported check field ${check.name}.${key}`);
+  for(const category of categories)if(check.coverage?.[category]&&
+    typeof check.coverageReview?.[category]!=='string')
+    error(`${check.name}: reviewed coverage ${category} needs a rationale`);
+  const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
+  if(check.script&&check.command&&!pnpmTypecheck)
+    error(`${check.name}: choose script or command, not both`);
+  const manager=publicConfig.packageManager;
+  if(check.script&&!['npm','yarn','pnpm'].includes(manager))
+    error(`${check.name}: script checks need supported npm, Yarn or pnpm packageManager`);
+  const scriptCommand=check.script&&!check.command?
+    [`@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)
+    error(`${check.name}: unknown qualification contract`);
+  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!=='.'||
+    check.command?.length!==5||check.command[0]!=='@which:yarn'||
+    check.command[1]!=='workspace'||check.command[2]!==check.workspace||
+    check.command[3]!=='run'))
+    error(`${check.name}: Yarn workspace qualification needs its discovered workspace command`);
+  if(pnpmTypecheck&&(manager!=='pnpm'||!check.script||!check.command||
+    check.command[0]!=='@node'||
+    check.command[1]!==`@typescript-bin:${check.cwd||'.'}`||
+    check.workspace&&check.cwd==='.'||
+    !check.command.slice(2).every(value=>typeof value==='string'&&value)))
+    error(`${check.name}: pnpm qualification needs its discovered standalone TypeScript command`);
+  const reason=check.kind==='test'?'test runtime, transforms and cache inputs need review':
+    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',
+    '@project',check.script,'@which:npm']]:yarnWorkspace?
+    [['@node','@vstate/yarn-workspace-typecheck-probe','@project',
+      check.workspace,check.command[4],'@which:yarn']]:pnpmTypecheck?
+    [['@node','@vstate/pnpm-typecheck-probe','@project',
+      check.workspace||'.',check.script]]:[];
+  const windowsContext=process.platform==='win32'?
+    ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
+  const autoEnvironment=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],
+      prefixes:['YARN_','COREPACK_','npm_config_','DYLD_','TSGO_'],
+      pathExecutables:['node','yarn'],executableIdentity:true}:pnpmTypecheck?
+    {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
+      prefixes:['PNPM_','COREPACK_','npm_config_','DYLD_','TSGO_'],
+      pathExecutables:['node'],executableIdentity:true}:{};
+  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/**']:[]),
+    allowedExternalRoots:check.allowedExternalRoots||[],
+    probes:[...(check.probes||[]),...autoProbes]
+      .map((p,i)=>argv(p,`${check.name}.probes[${i}]`)),
+    environment:check.environment||autoEnvironment,coverage:check.coverage||{},
+    coverageReview:check.coverageReview||{},
+    coverageReasons:check.coverageReasons||Object.fromEntries(
+      categories.map(category=>[category,reason])),
+    qualification:check.qualification||null,script:check.script||null,
+    workspace:check.workspace||null,kind:check.kind||null};
+});
+const runtime={schema:1,provider:'declared-project@1',root,state,checks};
+try{assertOwnedStatePlacement(runtime);}catch(e){error(e.message);}
+const serialized=JSON.stringify(runtime,null,2)+'\n';
+const maintenance=command==='stop'||command==='remove-state';
+if(maintenance&&!fs.existsSync(runtimeFile)){
+  console.log(`No REDUE state exists for ${configFile}.`);
+  process.exit(0);
+}
+if(!maintenance)fs.mkdirSync(state,{recursive:true,mode:0o700});
+if(!maintenance&&fs.existsSync(runtimeFile)){
+  const previous=fs.readFileSync(runtimeFile,'utf8');
+  if(previous!==serialized){
+    const pidFile=path.join(state,'observer.lock','pid');
+    if(fs.existsSync(pidFile)){
+      const pid=Number(fs.readFileSync(pidFile));
+      if(processAlive(pid))error('config changed while observer is running; stop it before restarting with the new plan');
+    }
+    fs.writeFileSync(runtimeFile,serialized,{mode:0o600});
+  }
+}else if(!maintenance)fs.writeFileSync(runtimeFile,serialized,{flag:'wx',mode:0o600});
+
+if(command==='status'&&!sync){
+  const value=readCachedStatus(state,publicConfig.checks);
+  console.log(json?JSON.stringify(value):renderStatus(value,{short}));
+  process.exit(0);
+}
+
+const details=command==='detail'||command==='explain';
+const internal=command==='remove-state'?'uninstall':
+  details?'sync':command==='status'&&sync?'sync':command;
+if(command==='run'){
+  const child=spawn(process.execPath,[engine,runtimeFile,internal,check,...(!json?['--human']:[])],
+    {stdio:['inherit','inherit','inherit','ipc'],env:process.env});
+  const forward=signal=>{if(child.exitCode!==null)return;
+    if(process.platform==='win32'&&child.connected)child.send({action:'cancel',signal});
+    else child.kill(signal);};
+  const interrupt=()=>forward('SIGINT'),terminate=()=>forward('SIGTERM');
+  process.on('SIGINT',interrupt);process.on('SIGTERM',terminate);
+  const outcome=await new Promise(resolve=>{
+    child.once('error',error=>resolve({error}));
+    child.once('close',(status,signal)=>resolve({status,signal}));
+  });
+  process.off('SIGINT',interrupt);process.off('SIGTERM',terminate);
+  if(outcome.error)error(outcome.error.message);
+  process.exit(outcome.status??(outcome.signal?128+os.constants.signals[outcome.signal]:1));
+}
+const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
+  {stdio:['inherit','pipe','inherit'],
+    encoding:'utf8',env:process.env});
+if(result.error)error(result.error.message);
+if(result.stdout){
+  if(['status','detail','explain'].includes(command)){
+    let value;try{value=JSON.parse(result.stdout);}catch{error('status response could not be read; applicability is unknown');}
+    if(details&&check)value={...value,checks:value.checks.filter(row=>row.name===check)};
+    if(json)console.log(JSON.stringify(value));
+    else console.log(details?renderExplain(value,check):renderStatus(value,{short}));
+  }else printLifecycle(result.stdout,command,json);
+}
+process.exit(result.status??1);