@redue/cli 0.1.0-alpha.27 → 0.1.0-alpha.29

package/src/sandbox.mjs

@@ -29,9 +29,37 @@ export const sandboxInterpretation='sandbox@1';
 export const hiddenQualification='sandbox-v2';
 export const hiddenInterpretation='sandbox@2';
 export const hiddenListIssue='git cannot list the ignored files';
-export const isSandboxed=qualification=>qualification===sandboxQualification||qualification===hiddenQualification;
-export const sandboxInterpretationOf=qualification=>qualification===hiddenQualification?hiddenInterpretation:sandboxInterpretation;
-export const sandboxKinds=['typecheck','lint'];
+// And the project's documentation hidden too (docPatterns): an agent edits it
+// often, and a typecheck, lint or test suite seldom reads it.
+export const docsQualification='sandbox-v3';
+export const docsInterpretation='sandbox@3';
+// Under docs/, only documentation files: code there (examples a typecheck
+// includes) stays visible.
+const docsFolderTypes=['txt','adoc','png','jpg','jpeg','gif','svg','webp','pdf'];
+export const docPatterns=['**/*.md','**/*.mdx','**/*.rst','**/LICENSE*','**/CHANGELOG*',...docsFolderTypes.map(type=>`docs/**/*.${type}`)];
+export const hiddenDocsIssue='git cannot list the documentation';
+// What macOS refuses by path pattern: the extensions, in any case (Seatbelt
+// matches regexes without regard to case). Every other listed file
+// (LICENSE*, CHANGELOG*) it refuses by its path; a pattern would refuse
+// license-check.ts too.
+const docsByPattern=rel=>/^(.+\/)?[^/]*\.(md|mdx|rst)$/i.test(rel)||new RegExp(`^docs/(.+/)?[^/]*\\.(${docsFolderTypes.join('|')})$`,'i').test(rel);
+// One path each makes the profile larger and slower to compile (1,000 add
+// about 190 ms to a run; a few thousand do not compile). Past this many,
+// those files stay visible and count as inputs, on every platform.
+export const namedDocsLimit=100;
+export const isSandboxed=qualification=>[sandboxQualification,hiddenQualification,docsQualification].includes(qualification);
+// Whether the recipe hides the checkout's git-ignored entries (v2 and v3).
+export const hidesIgnored=qualification=>qualification===hiddenQualification||qualification===docsQualification;
+// A macOS test run has had no TCP since alpha.29: its own interpretation, so a
+// result recorded with loopback is not the same plan.
+export const sandboxInterpretationOf=(qualification,kind=null,platform=process.platform)=>
+  (qualification===docsQualification?docsInterpretation:qualification===hiddenQualification?hiddenInterpretation:sandboxInterpretation)+
+  (kind==='test'&&platform==='darwin'?'+no-tcp':'');
+export const sandboxKinds=['typecheck','lint','test'];
+// A test run gets a private /tmp (sandboxArgv's `writes`) and, on Linux,
+// supervised loopback networking (`network`); a typecheck or lint, and a
+// test run on macOS, get no network but Unix sockets.
+export const testRun=check=>check?.kind==='test';
 const fail=code=>{throw Object.assign(Error(code),{code});};
 const digest=value=>createHash('sha256').update(value).digest('hex');
 const real=file=>{try{return fs.realpathSync(file);}catch{return null;}};
@@ -62,10 +90,12 @@ export const pythonTool=check=>Array.isArray(check?.command)&&/^\.venv\/bin\/[A-
 // script check names its package manager first among the executables, as the
 // general recipe does.
 const managers=['npm','pnpm','yarn','corepack'];
-export function sandboxEnvironment(python=false,manager=null){
+export function sandboxEnvironment(python=false,manager=null,kind=null){
   return {variables:['TZ','LANG','LANGUAGE','CI','USER','LOGNAME'],
     prefixes:['LC_','DYLD_','LD_',...python?['PYTHON','MYPY','RUFF_','PYRIGHT','TY_']:
-      ['NODE_','npm_config_','PNPM_','YARN_','COREPACK_','TSGO_']],
+      ['NODE_','npm_config_','PNPM_','YARN_','COREPACK_','TSGO_'],
+      // A test runner's own variables.
+      ...kind==='test'?python?['PYTEST_']:['VITEST_','JEST_']:[]],
     ...manager?{pathExecutables:['node',manager,...managers.filter(name=>name!==manager)]}:{}};
 }
 
@@ -247,6 +277,24 @@ export function hiddenEntries(root){
     !runnerCache(rel)&&!runnerCache(rel.replace(/\/$/,'')+'/x'));
 }
 
+// The documentation files docPatterns names among the files git lists and
+// does not ignore (git-ignored ones are hidden as such), as regular files:
+// a link is not hidden. Files, never folders, so a folder stays listable.
+// Relative; null when git cannot tell. git filters by pathspec, so a large
+// checkout is not listed whole.
+const docMatch=picomatch(docPatterns,{dot:true});
+export function hiddenDocs(root){
+  const r=spawnSync('git',[...projectGit,'ls-files','-z','--cached','--others','--exclude-standard','--',...docPatterns.map(pattern=>`:(glob)${pattern}`)],
+    {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:60000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
+  if(r.status!==0)return null;
+  const out=new Set();
+  for(const rel of r.stdout.split('\0'))if(rel&&!out.has(rel)&&docMatch(rel))
+    try{if(fs.lstatSync(path.join(root,rel)).isFile())out.add(rel);}catch{}
+  const named=[...out].filter(rel=>!docsByPattern(rel));
+  if(named.length>namedDocsLimit)for(const rel of named)out.delete(rel);
+  return [...out].sort();
+}
+
 // What git lists now as ignored at or beneath `paths` (relative files, or
 // directories ending in /), as hiddenEntries would: nested repositories are
 // not entered, and an entry that is an installed tree is not ignored (one
@@ -273,6 +321,39 @@ export function trackedBeneath(root,entries){
     {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:10000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
   return r.status===0?new Set(r.stdout.split('\0').filter(Boolean)):null;
 }
+// For a run that hid `hidden` (relative entries), the first path of `paths`
+// that changes its inputs, between `before` and `current` ({rel: identity}),
+// or null. A file the run saw always counts. A file beneath a hidden entry
+// counts only once git tracks it, and a new file only when git does not list
+// it as ignored now, as the next run's hidden entries would not. When git
+// cannot tell, every change counts. `external:` paths always count. With
+// `during` (changes while the run ran), a new file outside the hidden
+// entries counts too: the run could read it.
+// With `docs` (sandbox@3: the documentation files the run hid, relative), a
+// later change to one of those files does not count. A new documentation
+// file does, and so does any change while the run ran: the run is not shown
+// to have been kept from it.
+export function visibleChange(root,hidden,before,current,paths,{during=false,docs=null}={}){
+  const entries=hidden.map(entry=>entry.replace(/\/$/,''));
+  const beneath=file=>entries.some(entry=>file===entry||file.startsWith(entry+'/'));
+  const hiddenDoc=new Set(during?[]:docs||[]);
+  const changed=[...new Set(paths)].filter(file=>before[file]!==current[file]&&!hiddenDoc.has(file)).sort();
+  const seen=changed.filter(file=>file in before&&!beneath(file));
+  if(seen.length)return seen[0];
+  const covered=changed.filter(beneath),fresh=changed.filter(file=>!(file in before)&&!beneath(file));
+  if(covered.length){
+    const tracked=trackedBeneath(root,entries.filter(entry=>covered.some(file=>file===entry||file.startsWith(entry+'/'))));
+    const found=covered.find(file=>!tracked||tracked.has(file));
+    if(found)return found;
+  }
+  if(!fresh.length)return null;
+  if(during)return fresh[0];
+  // Asked once per directory the run had no file in, then the files outside one.
+  const dirs=new Set(Object.keys(before).flatMap(file=>file.split('/').slice(0,-1).map((_,i,parts)=>parts.slice(0,i+1).join('/'))));
+  const newDir=file=>{const parts=file.split('/');for(let i=1;i<parts.length;i++){const dir=parts.slice(0,i).join('/');if(!dirs.has(dir))return dir+'/';}return null;};
+  const ignored=ignoredNow(root,[...new Set(fresh.filter(file=>!file.startsWith('external:')).map(file=>newDir(file)??file))]);
+  return fresh.find(file=>file.startsWith('external:')||!ignored||!ignored.has(file))??null;
+}
 // A refusal line that names a hidden entry (relative): a refusal by the
 // sandbox, or a missing file, which Linux tools report for an unreadable one.
 export function hiddenRefusal(text,hidden){
@@ -288,29 +369,78 @@ const ancestors=list=>[...new Set(list.flatMap(dir=>{const out=[];for(let at=pat
 // metadata of their parent directories, and no network but Unix sockets in
 // the run's own temporary directory (`own`), which is new for each run: a
 // daemon an earlier run left behind cannot answer a later one. `hidden`:
-// absolute paths it may not read at all, not even their metadata.
-export function seatbeltProfile(reads,own=null,hidden=[]){
+// absolute paths whose contents it may not read or execute.
+// A test run gets no TCP either: Seatbelt cannot refuse one loopback port
+// while allowing the others (a per-port deny under a loopback allow is not
+// applied; an allow list of 65,000 ports does not compile), so a suite could
+// reach a database started outside the run. A suite that needs loopback
+// fails init's trial and runs plainly. With `writes`, a test run writes
+// nothing beneath /tmp and /var/tmp but beneath those places (its checkout,
+// home and own temporary directory).
+// `docs` ({root, entries}): the checkout's documentation it may not read,
+// regular files only, so folders stay listable. Extensions go by path
+// pattern, so the profile stays small however many files match: every file
+// hiddenDocs lists, and more (one in node_modules, README.MD). Seatbelt
+// matches a regex without regard to case, so LICENSE* and CHANGELOG* go by
+// the files hiddenDocs listed: a pattern would hide license-check.ts too.
+export function seatbeltProfile(reads,own=null,hidden=[],{writes=null,docs=null}={}){
   const quote=value=>JSON.stringify(value);
+  const both=list=>[...new Set(list.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
   const all=[...new Set(reads.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
   return ['(version 1)','(allow default)','(deny file-read* process-exec*)',
     `(allow file-read* process-exec* ${all.map(dir=>`(subpath ${quote(dir)})`).join(' ')} (literal "/") (literal "/etc") (literal "/var") (literal "/tmp"))`,
     `(allow file-read-metadata ${ancestors(all).map(dir=>`(literal ${quote(dir)})`).join(' ')})`,
     // The entry's own path, by its directory's real path: a hidden link's target is not hidden.
-    ...hidden.length?[`(deny file-read* process-exec* ${[...new Set(hidden.flatMap(file=>[file,path.join(real(path.dirname(file))??path.dirname(file),path.basename(file))]))]
+    // Its contents only, as on Linux: a run may still see that it exists, and write beneath it.
+    ...hidden.length?[`(deny file-read-data process-exec* ${[...new Set(hidden.flatMap(file=>[file,path.join(real(path.dirname(file))??path.dirname(file),path.basename(file))]))]
       .map(file=>`(subpath ${quote(file)})`).join(' ')})`]:[],
-    '(deny network*)',...own?[`(allow network* ${[own,real(own)].filter(Boolean).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[]].join('\n');
+    ...docs?[docsRule(docs,both([docs.root]))]:[],
+    '(deny network*)',...own?[`(allow network* ${[own,real(own)].filter(Boolean).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[],
+    ...writes?['(deny file-write* (subpath "/tmp") (subpath "/private/tmp") (subpath "/var/tmp") (subpath "/private/var/tmp"))',
+      `(allow file-write* ${both(writes).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[]].join('\n');
+}
+// docsByPattern's patterns for each root, and each listed file they do not cover by its path.
+function docsRule(docs,roots){
+  const named=docs.entries.filter(rel=>!docsByPattern(rel));
+  const patterns=roots.map(dir=>escape(dir)).flatMap(dir=>[`^${dir}/(.+/)?[^/]*\\.(md|mdx|rst)$`,`^${dir}/docs/(.+/)?[^/]*\\.(${docsFolderTypes.join('|')})$`])
+    .map(pattern=>`(regex #"${pattern.replace(/"/g,'\\"')}")`);
+  const files=roots.flatMap(dir=>named.map(rel=>`(literal ${JSON.stringify(path.join(dir,rel))})`));
+  return `(deny file-read-data process-exec* (require-all (vnode-type REGULAR-FILE) (require-any ${[...patterns,...files].join(' ')})))`;
 }
 // The argv that runs `argv` sandboxed: reads beneath `reads`, no network but
 // Unix sockets beneath `tmp` on macOS, nothing beneath `hidden` (absolute).
 // On Linux a hidden directory can still be listed and its entries stat'ed:
 // Landlock restricts neither beneath a listable parent.
-export function sandboxArgv(mode,argv,{reads,tmp=null,python,hidden=[],stats=null}){
-  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp,hidden),...argv];
+// `network` "loopback" and `writes`: a test run's. Only Linux gives it a
+// network (seatbeltProfile says why macOS does not), supervised: `stats`
+// then says whether the supervisor served the whole run (supervisorIssue).
+// `docs` ({root, entries}): the checkout's documentation, hidden too.
+export function sandboxArgv(mode,argv,{reads,tmp=null,python,hidden=[],stats=null,network='none',writes=null,fault=null,docs=null}){
+  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp,hidden,{writes,docs}),...argv];
+  if(docs)hidden=[...hidden,...docs.entries.map(rel=>path.join(docs.root,rel.replace(/\/$/,'')))];
   // The launcher's own warnings would become the check's output.
   if(mode==='landlock')return [python,'-I','-W','ignore',landlockScript,...reads.flatMap(dir=>['--read',dir]),
-    ...hidden.flatMap(file=>['--hide',file]),...stats?['--stats',stats]:[],'--no-tcp','--',...argv];
+    ...hidden.flatMap(file=>['--hide',file]),...stats?['--stats',stats]:[],
+    ...network==='loopback'?['--loopback']:['--no-tcp'],
+    ...writes?['--deny-write','/tmp','--deny-write','/var/tmp',...writes.flatMap(dir=>['--write',dir])]:[],
+    ...fault?['--test-fault',fault]:[],'--',...argv];
   throw Error(`unknown sandbox ${mode}`);
 }
+// Why a supervised run's network was not supervised throughout, from the
+// launcher's stats file, or null when it was.
+export function supervisorIssue(stats){
+  let value=null;try{value=JSON.parse(fs.readFileSync(stats,'utf8'));}catch{}
+  return value?.supervisor==='ok'?null:`the network supervisor ${value?.supervisor?`reported: ${value.supervisor}`:'left no report'}`;
+}
+// The counts a test runner's summary gives, the last of each: pytest, Vitest,
+// Jest, Mocha, node --test.
+const ansi=/\u001b\[[0-9;]*m/g;
+export function testCounts(text){
+  const plain=String(text).replace(ansi,'');
+  const last=(...patterns)=>{for(const re of patterns){let m,v=null;const g=new RegExp(re,'gim');while((m=g.exec(plain)))v=Number(m[1]);if(v!==null)return v;}return null;};
+  return {passed:last('(\\d+) (?:tests? )?(?:passed|passing)\\b','^(?:#|ℹ) pass (\\d+)'),failed:last('(\\d+) (?:tests? )?(?:failed|failing)\\b','^(?:#|ℹ) fail (\\d+)'),
+    skipped:last('(\\d+) (?:tests? )?(?:skipped|pending|todo)\\b','^(?:#|ℹ) (?:skip|skipped) (\\d+)')};
+}
 // A line of a failed run's output that looks like the sandbox refused
 // something: a refused read or write, or the network unreachable. Such a
 // failure is run again outside the sandbox to tell a denial from a real one.
@@ -454,6 +584,7 @@ export function runToEnd(argv,{cwd,env,timeout=0,echo=false,started=null}){
   });
 }
 // {same, plain, sandboxed, line} or {issue} when the sandbox cannot run here.
+// With `hide` 'docs', the documentation (hiddenDocs) is hidden too.
 // With `hide`, the git-ignored entries hiddenEntries lists are kept from the
 // sandboxed run, and it also returns them, their count, the run times and, on
 // Linux, the launcher's rule count and setup time.
@@ -463,18 +594,27 @@ export async function sandboxTrial(root,check,{timeout=300000,hide=false,plain:e
   if(supported.issue)return {issue:supported.issue};
   const python=Boolean(pythonTool(check));
   const command=python?check.command:[lookup(scriptProject(root,check.script).manager,process.env.PATH,root)||'npm','run',check.script];
-  const selected={...check,command,environment:sandboxEnvironment(python,python?null:scriptProject(root,check.script).manager)};
-  const scratch=fs.mkdtempSync(path.join(os.tmpdir(),'redue-trial-')),home=path.join(scratch,'home'),tmp=path.join(scratch,'tmp');
-  fs.mkdirSync(home);fs.mkdirSync(tmp);
+  const selected={...check,command,environment:sandboxEnvironment(python,python?null:scriptProject(root,check.script).manager,check.kind)};
+  const tests=testRun(check);
+  // A test run's home is beneath its temporary directory, as in cli.mjs: on
+  // macOS that is where its Unix sockets may be.
+  const scratch=fs.mkdtempSync(path.join(os.tmpdir(),'redue-trial-')),tmp=path.join(scratch,'tmp'),home=tests?path.join(tmp,'home'):path.join(scratch,'home');
+  fs.mkdirSync(tmp);fs.mkdirSync(home);
   try{
-    const entries=hide?hiddenEntries(root):[];
-    if(!entries)return {issue:hiddenListIssue};
-    const hidden=entries.map(rel=>path.join(root,rel.replace(/\/$/,""))),stats=hide&&supported.mode==='landlock'?path.join(scratch,'stats.json'):null;
+    const ignored=hide?hiddenEntries(root):[],docEntries=hide==='docs'?hiddenDocs(root):[];
+    if(!ignored)return {issue:hiddenListIssue};
+    if(!docEntries)return {issue:hiddenDocsIssue};
+    const entries=[...ignored,...docEntries];
+    const hidden=ignored.map(rel=>path.join(root,rel.replace(/\/$/,""))),stats=(hide||tests)&&supported.mode==='landlock'?path.join(scratch,'stats.json'):null;
     const run=async(argv,env)=>{const started=Date.now(),r=await runToEnd(argv,{cwd:root,env,timeout});
       return {status:r.timedOut?'timeout':r.status??r.signal??r.error?.code,output:`${r.stdout}\n${r.stderr}`,ms:Date.now()-started};};
     const plain=earlier??await run(command,{...process.env,...python?{}:{npm_config_update_notifier:'false'}});
     const reads=[root,home,tmp,...sandboxPlaces(selected,process.env,root),...systemPlaces];
-    const sandboxed=await run(sandboxArgv(supported.mode,command,{reads,tmp,python:supported.python,hidden,stats}),sandboxEnv(selected,process.env,{root,home,tmp}));
+    const sandboxed=await run(sandboxArgv(supported.mode,command,{reads,tmp,python:supported.python,hidden,stats,
+      ...hide==='docs'?{docs:{root,entries:docEntries}}:{},
+      ...tests?{...supported.mode==='landlock'?{network:'loopback'}:{},writes:[root,home,tmp]}:{}}),sandboxEnv(selected,process.env,{root,home,tmp}));
+    // A test run's network was supervised throughout, on Linux.
+    const supervisor=tests&&stats?supervisorIssue(stats):null;
     // A failure both ways counts as the same only without a sign of a refusal.
     const denied=sandboxed.status===0?null:denialLine(sandboxed.output,entries);
     const realOf=dir=>{try{return fs.realpathSync(dir);}catch{return null;}},plainTmp=process.env.TMPDIR||os.tmpdir();
@@ -486,8 +626,14 @@ export async function sandboxTrial(root,check,{timeout=300000,hide=false,plain:e
     if(at<0&&b.length>a.length)at=a.length;
     const output=at<0?null:{plain:(a[at]??'(no more output)').slice(0,160),sandboxed:(b[at]??'(no more output)').slice(0,160)};
     let launcher=null;if(stats)try{launcher=JSON.parse(fs.readFileSync(stats,'utf8'));}catch{}
-    return {same:plain.status===sandboxed.status&&!denied&&!output,plain:plain.status,sandboxed:sandboxed.status,output,plainRun:plain,
-      line:denied||(plain.status===sandboxed.status?null:sandboxed.output.trim().split('\n').at(-1)?.slice(0,200)||null),
-      ...hide?{hidden:entries.length,entries,plainMs:plain.ms,sandboxedMs:sandboxed.ms,...launcher?{rules:launcher.rules,setupMs:launcher.ms}:{}}:{}};
+    // Tests print in an order their workers decide: the counts their summary
+    // gives are compared, not every line.
+    // When neither summary can be read, every line is compared, as for a typecheck.
+    const counts=tests?[plain,sandboxed].map(r=>testCounts(r.output)):null;
+    const read=counts?.some(c=>Object.values(c).some(value=>value!==null));
+    const differs=tests&&read?(JSON.stringify(counts[0])===JSON.stringify(counts[1])?null:{plain:JSON.stringify(counts[0]),sandboxed:JSON.stringify(counts[1])}):output;
+    return {same:plain.status===sandboxed.status&&!denied&&!differs&&!supervisor,plain:plain.status,sandboxed:sandboxed.status,output:differs,plainRun:plain,
+      line:supervisor||denied||(plain.status===sandboxed.status?null:sandboxed.output.trim().split('\n').at(-1)?.slice(0,200)||null),
+      ...hide?{hidden:entries.length,entries,docs:docEntries.length,plainMs:plain.ms,sandboxedMs:sandboxed.ms,...launcher?{rules:launcher.rules,setupMs:launcher.ms}:{}}:{}};
   }finally{fs.rmSync(scratch,{recursive:true,force:true});}
 }

package/src/setup.mjs

@@ -12,6 +12,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {spawnSync} from 'node:child_process';
+import {testCounts} from './sandbox.mjs';
 import {createInterface} from 'node:readline/promises';
 import {projectState} from './project-location.mjs';
 import {claudeHooksInstalled,removeClaudeHooks,removeIntegration} from './agent-integration.mjs';
@@ -80,7 +81,19 @@ async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
   const names=configExisted?JSON.parse(readText(configPath)).checks.map(check=>check.name):found.checks.map(check=>check.name);
   const ready=names.filter(name=>levels.get(name)==='ready');
   console.log(`Setting up REDUE for Claude Code in ${root}`);
-  console.log(configExisted?`  keep ${configName} (exists)`:`  create ${configName}: ${names.map(name=>`${name} (${levels.get(name)==='ready'?'can qualify':'recording-only'})`).join(', ')}`);
+  console.log(configExisted?`  keep ${configName} (exists)`:`  create ${configName}: ${names.map(name=>`${name} (${levels.get(name)==='ready'?'can qualify':'recording only'})`).join(', ')}`);
+  // What the checks setup does not make reusable are, and why.
+  if(!configExisted){
+    const recording=found.checks.filter(check=>check.level!=='ready');
+    if(recording.length)console.log('  recording only: REDUE records these runs but never reports one CURRENT, because it cannot tell what the result depends on:');
+    for(const check of recording)console.log(`    ${check.name}: ${check.reason}`);
+    const out=[...found.skipped||[]].filter(row=>row.reason);
+    const kinds=new Set([...found.checks.map(check=>check.kind??check.name.split(':')[0]),...out.map(row=>String(row.kind).split(':')[0])]);
+    for(const kind of ['typecheck','lint','test'])if(!kinds.has(kind)&&!found.checks.some(check=>check.name===kind))
+      out.push({kind,reason:`${kind}: none found (no script or tool REDUE recognizes)`});
+    if(out.length)console.log('  left out:');
+    for(const row of out)console.log(`    ${row.reason.startsWith(String(row.kind))?row.reason:`${row.kind}: ${row.reason}`}`);
+  }
   console.log(`  write the Claude Code integration: CLAUDE.md section, .claude/skills/redue-verification/SKILL.md, ${localSettings} hooks, ${agentRecord}`);
   console.log(`  start the observer and record ${ready.length?ready.join(', '):'no check'} once, unless already CURRENT`);
   if(!await confirm('Proceed?',yes,{defaultYes:true})){console.log('Nothing written.');return {applied:false};}
@@ -121,7 +134,7 @@ async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
   // recorded as reusable. Wait while it plans and indexes; once its plan is
   // ready, an observer that is still unhealthy says why in the status below.
   // Nothing to wait for when no check can qualify.
-  const observation=()=>{const out=redue(['status','--json'],{capture:true});try{return JSON.parse(out.stdout).observation??null;}catch{return null;}};
+  const observation=()=>{const out=redue(['status','--cached','--json'],{capture:true});try{return JSON.parse(out.stdout).observation??null;}catch{return null;}};
   // An answer without a phase (a stopped observer) for 10 s in a row ends the
   // wait too.
   const begun=Date.now();let told=-1,unread=0,phaseless=0;
@@ -136,9 +149,18 @@ async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
   // One recorded run of each check that can qualify and is not CURRENT.
   const statusOf=()=>{const out=redue(['status','--sync','--json'],{capture:true,timeout:600_000});try{return JSON.parse(out.stdout).checks;}catch{return [];}};
   const rows=statusOf(),due=ready.filter(name=>rows.find(row=>row.name===name)?.freshness!=='CURRENT');
-  for(const name of due){console.log(`Recording ${name} once:`);redue(['run',name]);}
+  // One line per check; the run's own output only when it fails.
+  for(const name of due){
+    console.log(`Recording ${name} once (running it)...`);
+    const started=Date.now(),run=redue(['run',name],{capture:true});
+    const output=`${run.stdout??''}\n${run.stderr??''}`,counts=testCounts(output),seconds=((Date.now()-started)/1000).toFixed(1);
+    const tally=Object.entries(counts).filter(([,value])=>value!==null).map(([key,value])=>`${value} ${key}`).join(', ');
+    console.log(`  ${name}: ${run.status===0?'PASS':`FAIL (exit ${run.status??run.signal})`} in ${seconds} s${tally?`, ${tally}`:''}`);
+    if(run.status!==0)console.log(output.trim().split('\n').slice(-15).map(line=>`    ${line}`).join('\n'));
+  }
   if(ready.length&&!due.length)console.log(`Already CURRENT: ${ready.join(', ')}.`);
-  for(const row of statusOf())console.log(`  ${row.name}: ${row.freshness}${row.result?' / '+row.result:''}${row.freshness==='CURRENT'?'':' — '+row.reason}`);
+  for(const row of statusOf())console.log(`  ${row.name}: ${row.freshness}${row.result?' / '+row.result:''}${row.freshness==='CURRENT'?'':
+    levels.get(row.name)!=='ready'?' — recording only':' — '+row.reason}`);
   console.log('Done. Start a new Claude Code session in this project. Undo with redue remove.');
   return {applied:true};
 }