@awebai/oats 0.27.2 → 0.29.0

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { randomUUID } from 'node:crypto';
-import { fs, join, dirname, resolve, readJSON, save, safePath, cliPath, oats, fail, unlock } from '../lib/io.mjs';
-import { loadBindings, declaration, splitRef } from '../lib/config.mjs';
-import { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, settleRetiredSchedule, service, markerPath, views } from '../lib/sources.mjs';
+import { fs, join, resolve, readJSON, safePath, oats, fail, unlock } from '../lib/io.mjs';
+import { loadBindings } from '../lib/config.mjs';
+import { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, settleRetiredSchedule, service, markerPath, harvestOffRecord } from '../lib/sources.mjs';
+import { harvestStatus, setupHarvest } from '../lib/harvest-status.mjs';
+import { settings } from '../lib/config.mjs';
+import { CONSULT } from '../lib/consult.mjs';
 import { runSource, complete, retry, readRun, requireQualifiedHelper } from '../lib/worker.mjs';
 import { initBase, migrate, deliverMigration, cutoverMigration, migrateSource, forgetMigration } from '../lib/migration.mjs';
 import { inspect } from '../lib/inspection.mjs';
@@ -13,9 +15,18 @@ oats okf harvest [--home PATH] [--no-launch] [--json]
 oats okf run-source --source FILE [--manual] [--no-launch] [--json]
 oats okf complete --source FILE --run ID --judgment FILE [--json]
 oats okf retry --source FILE [--run ID --rejudge | --rejudge | --launch | --adopt-home PATH] [--json]
-oats okf read [--home PATH | --source FILE] --base ALIAS [--path node/index.md] [--json]
-oats okf refresh [--home PATH | --source FILE] [--json]
+oats okf bases [--fresh] [--json]
+oats okf index [--base ALIAS] [NODE | ALIAS/NODE] [--fresh] [--json]
+oats okf cat --base ALIAS PATH [--from PATH] [--fresh] [--json]
+oats okf ls --base ALIAS [DIR] [--fresh] [--json]
+oats okf links --base ALIAS PATH [--fresh] [--json]
+oats okf search [--base ALIAS | --all] [--node NODE] [--regex] [--case-sensitive] TEXT [--fresh] [--json]
+Consult commands read the accepted state remotely (host cache, no local copy);
+also accept --home PATH | --source FILE. PATH is /node/x.md from the base root,
+relative to --from's directory, or bare node/x.md from the root.
 oats okf setup --source FILE [--enable | --disable] [--install-host] [--json]
+oats okf setup --harvest on|off [--json]      (writes oats-local.yaml settings.oats.okf.harvest)
+oats okf harvest-status [--soul NAME] [--json]  (the effective harvest switch, why, and the registered sources)
 oats okf init --base ALIAS --nodes FILE [--output PATH | --confirm] [--json]
 oats okf migrate --legacy PATH --base ALIAS --node NODE --output PATH [--json]
 oats okf migrate --deliver FILE | --cutover FILE --soul-dir PATH [--json]
@@ -36,11 +47,13 @@ if(args.includes('--help') || args.includes('-h')) {process.stdout.write(HELP);}
 else {
   const event=process.env.OATS_EVENT || args[0];
   const hook=['spawn','retire','soul-scaffold'].includes(event);
-  let exit=0,answer;
+  const consult=Object.hasOwn(CONSULT,event);
+  let exit=0,answer,text,textMode=consult && !args.includes('--json');
   try {
-    const flags={}; const boolean=new Set(['json','no-launch','manual','rejudge','launch','enable','disable','install-host','confirm']);
+    const flags={},positionals=[]; const boolean=new Set(['json','no-launch','manual','rejudge','launch','enable','disable','install-host','confirm','fresh','all','regex','case-sensitive']);
     for(let i=1;i<args.length;i++) {
-      if(!args[i].startsWith('--')) fail('E_USAGE',`unexpected argument ${args[i]}`);
+      if(consult && args[i]==='--') {positionals.push(...args.slice(i+1));break;}
+      if(!args[i].startsWith('--')) {if(!consult) fail('E_USAGE',`unexpected argument ${args[i]}`);positionals.push(args[i]);continue;}
       const k=args[i].slice(2);if(k in flags) fail('E_USAGE',`duplicate --${k}`);
       if(boolean.has(k)) flags[k]=true;
       else {if(!args[i+1] || args[i+1].startsWith('--')) fail('E_USAGE',`--${k} needs a value`);flags[k]=args[++i];}
@@ -49,8 +62,10 @@ else {
       spawn:[],retire:['home'], 'soul-scaffold':[],
       harvest:['home','no-launch','native-request','worker-mode'],inspect:['home','source'],
       'run-source':['source','manual','no-launch'],complete:['source','run','judgment'],
-      retry:['source','run','rejudge','launch','adopt-home'],read:['home','source','base','path'],refresh:['home','source'],
-      setup:['source','enable','disable','install-host'],init:['base','nodes','output','confirm'],
+      retry:['source','run','rejudge','launch','adopt-home'],read:['home','source','base','path','fresh'],refresh:['home','source'],'harvest-status':['home'],
+      bases:['home','source','fresh'],index:['home','source','base','fresh'],cat:['home','source','base','from','fresh'],ls:['home','source','base','fresh'],
+      links:['home','source','base','fresh'],search:['home','source','base','all','node','regex','case-sensitive','fresh'],
+      setup:['source','enable','disable','install-host','harvest'],init:['base','nodes','output','confirm'],
       migrate:['source-home','legacy','base','node','output','deliver','cutover','soul-dir'],unlock:['lock','token']
     };
     for(const k of Object.keys(flags)) if(!['json','soul',...(accepted[event] || [])].includes(k)) fail('E_USAGE',`unknown flag --${k} for ${event}`);
@@ -107,15 +122,22 @@ else {
       readRun(s,id);return s;
     };
     let result;
-    if(event==='soul-scaffold') {
+    if(event==='read') fail('E_REMOVED','okf 4.0.0 removed read: use `oats okf cat --base ALIAS PATH` (same path, text and receipt)');
+    if(consult) {const answer=CONSULT[event](src(),flags,positionals);result=answer.result;text=answer.text;}
+    else if(event==='refresh') fail('E_REMOVED','okf 3.0.0 has no per-instance views; index/cat always read the accepted state: run `oats okf index`, then `oats okf cat --base ALIAS PATH`');
+    else if(event==='harvest-status') result=harvestStatus({home,flags});
+    else if(event==='soul-scaffold') {
       // Souls are portable declarations, never an implicit knowledge store.
       result={meta:{scaffolded:false},brief:'OKF requires explicit external bindings and soul/okf.json before a working instance can spawn. Use init or migrate; no knowledge was created in this soul.'};
     } else if(event==='spawn') {
       const s=sourceReceipt.mode==='captured'?registerCaptured(home,sourceReceipt.receipt):register(home);
+      const nodes=(list)=>list.join(', ') || 'none';
+      const brief=decl=>`Your soul knowledge is read remotely at its accepted state; there is no local copy. Start every task with your instance knowledge (STATE.md, log.md, notes/), then \`oats okf index\` (owns: ${nodes(decl.owns)}; reads: ${nodes(decl.reads.filter(r=>!decl.owns.includes(r)))}) and \`oats okf cat --base ALIAS PATH\` for the concepts the task needs; \`oats okf search\` before re-deriving a decision. Load okf-consultation and okf-instance-knowledge. Never edit accepted knowledge.`;
       if(s.skipped) result={meta:{memory:'none'},brief:'Service agent: follow your own task; no working-memory upkeep.'};
+      else if(s.harvestOff) result={meta:{memory:'okf-v2',harvest:'off',reason:s.switch.reason},brief:`${brief(s.decl)} Harvest is off for this instance: nothing of this session is captured.`,...(s.switch.warnings.length?{warning:`oats-okf: ${s.switch.warnings.join('; ')}`}:{})};
       else {
         const schedule=loadStatus(s).schedule.result;
-        result={meta:{memory:'okf-v2',source:s.file,schedule},brief:`Knowledge is an immutable accepted snapshot at ./knowledge/. Read knowledge/view.json for base paths under knowledge/bases/<alias>/, then the indexes for ${[...new Set([...s.decl.owns,...s.decl.reads])].join(', ')}. Follow only relevant links. All configured bases are available. Use oats okf read for current accepted text; old views stay stable. Keep STATE.md/log.md/notes/ current; never edit knowledge.`};
+        result={meta:{memory:'okf-v2',harvest:'on',source:s.file,schedule},brief:`${brief(s.decl)} Harvest is on: your notes and session are captured for the knowledge harvester.`};
       }
     } else if(event==='retire') {
       if(captured) {
@@ -124,6 +146,7 @@ else {
         else {if(!fs.existsSync(markerPath(home))) fail('E_MIGRATION','captured retire requires a durable registered source or explicit helper receipt');s=src();}
         if(s) {scheduleSource(s);const r=capture(s,{final:true});const schedule=settleRetiredSchedule(s);result={meta:{retired:r.complete===true,source:s.file,capture:r,schedule},brief:'Final input is in durable custody. Delivery remains asynchronous.'};}
       } else if(service(home)) result={meta:{retired:true}};
+      else if(!fs.existsSync(markerPath(home)) && harvestOffRecord(home)) result={meta:{retired:true,reason:'harvest-off'}};
       else if(!fs.existsSync(markerPath(home))) {
         if(['STATE.md','log.md','notes','.okf-harvest-record.json','.okf-harvest-record.next.json'].some(p=>fs.existsSync(join(home,p)))) fail('E_MIGRATION','unregistered/legacy source has memory; explicitly migrate/register before retirement');
         result={meta:{retired:true,reason:'nothing-to-delete'}};
@@ -139,32 +162,30 @@ else {
         // Snapshot absence does not turn a persisted captured source into legacy.
         if(fs.existsSync(markerPath(home))) requireQualifiedHelper(src());
         const s=register(home);
+        if(s.harvestOff) fail('E_HARVEST_OFF',`harvest is off for this instance: ${s.switch.reason}. Nothing was captured.`);
         result=s.skipped?{status:'skipped',reason:'service'}:runSource(s,{manual:true,noLaunch:!!flags['no-launch']});
       }
-    } else if(event==='run-source') result=runSource(src(),{manual:!!flags.manual,noLaunch:!!flags['no-launch']});
+    } else if(event==='run-source') {
+      // The deployment can switch harvest off after a source registered: the
+      // job then captures and processes nothing (the soul's opt-out was already
+      // applied at registration). Nothing drains when it is switched back on.
+      const source=src();
+      result=settings().harvest!=='on'?{status:'harvest-off',source:source.file,reason:'the deployment does not switch harvest on (settings.oats.okf.harvest); nothing was captured'}
+        :runSource(source,{manual:!!flags.manual,noLaunch:!!flags['no-launch']});
+    }
     else if(event==='complete') {const s=src();if(captured) retainedRun(s);result=complete(s,flags.run,flags.judgment && resolve(flags.judgment));}
     else if(event==='retry') {const s=src();if(captured && !flags.run && !flags.rejudge && !flags.launch && !flags['adopt-home']) retainedRun(s);result=retry(s,{run:flags.run,rejudge:!!flags.rejudge,launch:!!flags.launch,adoptHome:flags['adopt-home']});}
     else if(event==='inspect') result=inspect(src());
+    else if(event==='setup' && flags.harvest!==undefined) {
+      if(flags.source || flags.enable || flags.disable || flags['install-host']) fail('E_USAGE','setup --harvest takes no other setup flag');
+      result=setupHarvest(flags.harvest);
+    }
     else if(event==='setup') {
       const s=src();if(flags.enable && flags.disable) fail('E_USAGE','choose enable or disable');
       scheduleSource(s);
       if(flags.enable || flags.disable) {oats(['schedule',flags.enable?'enable':'disable',`okf-${s.id}`,'--dir',s.context,'--json'],s.context);updateStatus(s,current=>{current.auto=!!flags.enable;});}
       if(flags['install-host']) oats(['schedule','host','install','--dir',s.context,'--json'],s.context);
       result={source:s.file,scheduler:oats(['schedule','list','--dir',s.context,'--json'],s.context).scheduler};
-    } else if(event==='read' || event==='refresh') {
-      const s=src();
-      // A descriptor-selected read is independent of any invoking/source home.
-      // In particular, retired sources must not leave caches in context/repo.
-      const target=join(flags.source?join(dirname(s.file),'views'):home,`knowledge-view-${randomUUID()}`);
-      const receipts=views(s.bindings,s.decl,target);
-      if(event==='refresh') result={path:target,receipts};
-      else {
-        if(!Object.hasOwn(s.bindings.bases,flags.base || '')) fail('E_CONFIG','unknown --base');
-        const basePath=join(target,receipts[flags.base].path);
-        const p=safePath(join(basePath,flags.path || 'index.md'));
-        if(!p.startsWith(basePath+'/') || !p.endsWith('.md')) fail('E_PATH','read only contained Markdown');
-        result={path:p,text:fs.readFileSync(p,'utf8'),receipt:receipts[flags.base]};
-      }
     } else if(event==='init') result=initBase(loadBindings(),flags.base,flags.nodes,flags.output,{confirm:!!flags.confirm});
     else if(event==='migrate') {
       if(flags['source-home']) result=migrateSource(loadBindings(),flags['source-home']);
@@ -176,6 +197,10 @@ else {
     else fail('E_USAGE',`unknown command ${event}; see --help`);
     answer=hook?result:{schemaVersion:1,ok:true,result};
   } catch(e) {const code=e.code || 'E_OKF';exit=1;answer=hook?{meta:{...(event==='retire'?{retired:false,reason:e.message}:{})},warning:`oats-okf ${code}: ${e.message}`}:{schemaVersion:1,ok:false,error:{code,message:e.message}};}
-  // Let Node drain the pipe; no process.exit after a possibly large view.
-  process.stdout.write(JSON.stringify(answer)+'\n');process.exitCode=exit;
+  // Consult commands print text unless --json; every other answer is JSON.
+  // Let Node drain the pipe; no process.exit after a possibly large answer.
+  if(textMode && exit) process.stderr.write(`oats okf ${event}: ${answer.error.code}: ${answer.error.message}\n`);
+  else if(textMode) process.stdout.write(text+'\n');
+  else process.stdout.write(JSON.stringify(answer)+'\n');
+  process.exitCode=exit;
 }

package/capabilities/oats-okf/injects/okf.md

@@ -1,34 +1,42 @@
 ## Knowledge: OKF
 
-Your knowledge is external to the soul. Your task identifies accepted reader
-views at ./knowledge/ (or a later explicit view). Read view.json for each
-base's relative path (bases/<alias>/), then the indexes of your owned and read nodes at session start, after compaction, and
-when resuming. Follow only links relevant to the task: do not bulk-load bases.
-Each base is one link namespace: `/node/concept.md` resolves from that base's
-root, not the filesystem root. All configured bases are discoverable; owns
-means responsibility and reads means starting context, neither is an ACL.
+You have two kinds of knowledge. Work WITH both: consult them at the start of
+every task, after compaction, and every so often while you work, to decide,
+to situate the task and to stay coherent with what your soul already knows.
 
-Consult prior decisions before re-deriving them. Cite base/node/concept paths.
-Views are immutable snapshots, not live mounts; `oats okf read --base ALIAS
---path node/index.md` retrieves current accepted text. `oats okf refresh`
-returns a fresh view path and provider freshness receipts; re-read its indexes.
-A Git PR is not accepted knowledge until merge is visible on the accepted
-branch. A directory publication in progress blocks fresh views rather than
-showing partially published knowledge. Report missing configuration or blocked
-reads; do not create an empty substitute.
+- **Soul knowledge**: your soul's accepted OKF bases, external to the soul and
+  read remotely at their accepted state (there is no local copy).
+  **Consultation** reads them with the `oats okf` CLI from your instance home.
+  Load the **okf-consultation** skill at the start of every task.
+- **Instance knowledge**: this instance's own STATE.md, log.md and notes/ in
+  instance home. Load the **okf-instance-knowledge** skill: it teaches what is
+  worth capturing, not only where to put it.
 
-**Never write accepted knowledge or soul knowledge.** This is an instruction
-boundary, not a filesystem sandbox. Read through the provided views, not by
-editing the base behind them. Skills remain curated soul artifacts.
+The work mode:
+- **At task start and after compaction:** read STATE.md, recent log.md
+  entries and the relevant notes/, then `oats okf index` and
+  `oats okf cat --base ALIAS PATH` for the concepts the task needs. Follow
+  links; do not bulk-load.
+- **Before compaction and before a task boundary:** update STATE.md, log.md
+  and notes/ first, so your future self can continue.
+- **Every so often while working, and always before a design decision or
+  before re-deriving something:** `oats okf search` / `cat` the relevant
+  concepts and re-read your own notes. Consult prior decisions before
+  re-deriving them.
+- Cite what you relied on as `alias/node/concept.md@<short-oid>`. A Git PR is
+  not accepted knowledge until it is merged. Report missing configuration or
+  blocked reads; do not create a substitute.
 
-Keep your task-local memory in instance home, not ./work:
-- STATE.md: rewrite the current task and progress; # Next names one next step.
-- log.md: append dated significant events; never rewrite history.
-- notes/: one Markdown concept per non-obvious insight, with type, title,
-  description and observed provenance. Capture without judging importance.
-  Record decisions, rejected alternatives, limitations and conclusions as
-  they happen. Never include credentials or third-party messages verbatim.
+**Capture with judgment**, as it happens: decisions and why, rejected
+alternatives, costly discoveries, limitations and the workaround that worked,
+conclusions, blockers, human direction and corrections, and surprises that
+contradict soul knowledge (flag those as candidate supersessions). Not code
+descriptions, command logs, retries, secrets, verbatim third-party messages,
+or what the tracker and docs already hold. One concept per note in notes/;
+STATE.md is the current picture (rewritten); log.md is dated events
+(append-only). The knowledge harvester, not you, decides what is promoted.
 
-After compaction re-read STATE.md and the relevant knowledge indexes before
-continuing. Update memory before task boundaries. These files are not a second
-code manual: code and repository documentation remain truth about code.
+**Never write accepted knowledge or soul knowledge.** This is an instruction
+boundary, not a filesystem sandbox. Skills remain curated soul artifacts.
+Instance knowledge lives in instance home, not ./work; code and repository
+documentation remain the truth about code.

package/capabilities/oats-okf/lib/binding-wire.mjs

@@ -115,7 +115,10 @@ function contract(value,{required=false}={}) {
   return value;
 }
 function runtimeSettings(settings) {
-  keys(settings,['bindings-file','state-dir','harvest-runtime','harvest-model'],[], 'OKF settings');
+  // `harvest` (on|off) is read by the lifecycle hooks, not bound: accept it here
+  // so a deployment can set it, and refuse any other value.
+  keys(settings,['bindings-file','state-dir','harvest-runtime','harvest-model','harvest'],[], 'OKF settings');
+  if(settings.harvest!==undefined && !['on','off'].includes(settings.harvest)) wireError('invalid-binding');
   const descriptorFile=settings['bindings-file'],stateDir=settings['state-dir'],runtime=settings['harvest-runtime'],model=settings['harvest-model'] ?? null;
   for(const name of ['bindings-file','state-dir']) {
     if(settings[name]===undefined) settingError(`${name}:missing`);

package/capabilities/oats-okf/lib/config.mjs

@@ -7,8 +7,10 @@ function keys(value, allowed, label, code='E_CONFIG') {
 }
 export function settings() {
   const s = JSON.parse(process.env.OATS_SETTINGS || '{}');
-  keys(s,['bindings-file','state-dir','harvest-runtime','harvest-model','git-timeout'],'OATS_SETTINGS');
+  keys(s,['bindings-file','state-dir','harvest-runtime','harvest-model','git-timeout','consult-max-age','harvest'],'OATS_SETTINGS');
+  if(s.harvest!==undefined && !['on','off'].includes(s.harvest)) fail('E_CONFIG','harvest must be on or off');
   if(s['git-timeout']!==undefined && (!Number.isInteger(s['git-timeout']) || s['git-timeout']<1)) fail('E_CONFIG','git-timeout must be a positive integer number of seconds');
+  if(s['consult-max-age']!==undefined && (!Number.isInteger(s['consult-max-age']) || s['consult-max-age']<0)) fail('E_CONFIG','consult-max-age must be a non-negative integer number of seconds');
   if(s['state-dir']!==undefined && (typeof s['state-dir']!=='string' || !isAbsolute(s['state-dir']) || resolve(s['state-dir'])!==s['state-dir'])) fail('E_CONFIG','state-dir must be a normalized absolute path');
   if(s['harvest-runtime']!==undefined && !['pi','claude','codex'].includes(s['harvest-runtime'])) fail('E_CONFIG','invalid harvest-runtime');
   if(s['harvest-model']!==undefined && (typeof s['harvest-model']!=='string' || !s['harvest-model'].trim())) fail('E_CONFIG','harvest-model must be a nonempty string');
@@ -17,6 +19,9 @@ export function settings() {
 /** Time budget for Git operations that talk to a remote (clone, fetch, push,
  *  ls-remote). Local object reads keep the short exec default. */
 export function gitTimeoutMs() { return (settings()['git-timeout'] ?? 600)*1000; }
+/** How old (seconds) the host cache's accepted commit may be before a consult
+ *  read refetches the accepted branch; 0 fetches on every read. */
+export function consultMaxAgeMs() { return (settings()['consult-max-age'] ?? 300)*1000; }
 export function noGit(path) {
   for (let p = safePath(path); ; p = dirname(p)) {
     if (fs.existsSync(join(p, '.git')) || (fs.existsSync(join(p, 'HEAD')) && fs.existsSync(join(p, 'objects')) && fs.existsSync(join(p, 'refs')))) fail('E_DIRECTORY_GIT', `directory store is in Git custody: ${p}; use kind git`);