@awebai/oats 0.28.0 → 0.29.0

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

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 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 } from '../lib/sources.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';
@@ -19,11 +21,12 @@ 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]
-oats okf read --base ALIAS [--path node/index.md] [--json]   (2.x alias of cat)
 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]
@@ -50,7 +53,7 @@ else {
     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(consult && args[i]==='--') {positionals.push(...args.slice(i+1));break;}
-      if(!args[i].startsWith('--')) {if(!consult || event==='read') fail('E_USAGE',`unexpected argument ${args[i]}`);positionals.push(args[i]);continue;}
+      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];}
@@ -59,10 +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','fresh'],refresh:['home','source'],
+      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'],init:['base','nodes','output','confirm'],
+      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}`);
@@ -119,18 +122,22 @@ else {
       readRun(s,id);return s;
     };
     let result;
+    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;
-        const nodes=(list)=>list.join(', ') || 'none';
-        result={meta:{memory:'okf-v2',source:s.file,schedule},brief:`Your knowledge is read remotely at its accepted state; there is no local copy. Start every task with \`oats okf index\` (owns: ${nodes(s.decl.owns)}; reads: ${nodes(s.decl.reads.filter(r=>!s.decl.owns.includes(r)))}), then \`oats okf cat --base ALIAS PATH\` for the concepts the task needs; \`oats okf search\` before re-deriving a decision. Load the okf-consultation skill for the procedure. 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) {
@@ -139,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'}};
@@ -154,12 +162,24 @@ 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);

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

@@ -1,42 +1,42 @@
 ## Knowledge: OKF
 
-You have two kinds of knowledge. Consult both throughout your work: at the
-start of every task, after compaction, and while you work, to make decisions
-and to understand things.
+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.
 
-- **Soul knowledge**: your soul's accepted OKF bases. They are external to the
-  soul and read remotely at their accepted state; there is no local copy.
+- **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 (and whenever
-  you look something up): it teaches the commands, navigation, search, citing
-  and freshness.
+  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: what you are doing, what happened, what you have learned.
+  instance home. Load the **okf-instance-knowledge** skill: it teaches what is
+  worth capturing, not only where to put it.
 
-- **At the start of every task:** re-read STATE.md 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.
-- **After compaction, before continuing:** re-read STATE.md, recent log.md
-  entries and notes/, then `oats okf index` again.
-- **Throughout the work, not only at the start:** before a design decision,
-  before re-deriving something, whenever you need to understand something, and
-  whenever a question touches your domain, check your notes/ and
-  `oats okf search` / `cat` the relevant concepts first. Consult prior
-  decisions before re-deriving them.
-- Cite `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.
+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.
+
+**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.
 
 **Never write accepted knowledge or soul knowledge.** This is an instruction
 boundary, not a filesystem sandbox. Skills remain curated soul artifacts.
-
-Keep instance knowledge current, 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.
-
-Update memory before task boundaries. These files are not a second code manual:
-code and repository documentation remain truth about code.
+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,7 +7,8 @@ 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','consult-max-age'],'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');

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

@@ -493,8 +493,4 @@ export function search(source, flags, positionals) {
   return { result: { query, regex: !!flags.regex, bases: scope, node, hits: shownHits, total: hits.length, more, receipts: Object.fromEntries(receipts.map(r => [r.base, r])) },
     text: `${text || `no matches for ${JSON.stringify(query)}`}${more ? `\n… and ${more} more (narrow with --node or a longer query)` : ''}\n${footer(receipts)}` };
 }
-/** okf 2.x compatibility: read --base A [--path P] is cat of P (default the base index). */
-export function readCompat(source, flags) {
-  return cat(source, { base: flags.base, fresh: flags.fresh }, [flags.path ?? 'index.md']);
-}
-export const CONSULT = { bases, index, cat, ls, links, search, read: readCompat };
+export const CONSULT = { bases, index, cat, ls, links, search };

package/capabilities/oats-okf/lib/harvest-status.mjs

@@ -0,0 +1,88 @@
+// `oats okf harvest-status` and `oats okf setup --harvest on|off` (okf 4.0.0).
+import { fs, join, dirname, resolve, readJSON, atomic, fail } from './io.mjs';
+import { settings, loadBindings } from './config.mjs';
+import { harvestSwitch } from './harvest-switch.mjs';
+import { markerPath, harvestOffRecord } from './sources.mjs';
+
+const SOURCE_LIMIT = 500;
+/** The registered sources in the bound state directory, optionally for one soul. */
+function registeredSources(soul) {
+  let bindings;
+  try { bindings = loadBindings(); } catch (e) { return { error: `${e.code || 'E_CONFIG'}: ${e.message}` }; }
+  const dir = join(bindings.stateDir, 'sources');
+  if (!fs.existsSync(dir)) return { stateDir: bindings.stateDir, sources: [] };
+  const rows = [];
+  for (const id of fs.readdirSync(dir).sort()) {
+    if (rows.length >= SOURCE_LIMIT) return { stateDir: bindings.stateDir, sources: rows, truncated: true };
+    let source, status;
+    try { source = readJSON(join(dir, id, 'source.json')); status = readJSON(join(dir, id, 'status.json')); } catch { continue; }
+    if (soul && source.agent !== soul) continue;
+    rows.push({ id, soul: source.agent, instance: source.instance, created: source.created, retired: status.retired === true, auto: status.auto === true, activeRun: status.activeRun || null, schedule: status.schedule?.id || null, file: join(dir, id, 'source.json') });
+  }
+  return { stateDir: bindings.stateDir, sources: rows };
+}
+export function harvestStatus({ home, flags = {} }) {
+  const sw = harvestSwitch({ settings: settings(), soulDir: process.env.OATS_SOUL });
+  const soul = flags.soul || process.env.OATS_AGENT || null;
+  const inHome = !!process.env.OATS_INSTANCE_HOME && fs.existsSync(join(home, 'instance.json'));
+  const instance = inHome ? { home, registered: fs.existsSync(markerPath(home)), spawnedWith: fs.existsSync(markerPath(home)) ? 'on' : harvestOffRecord(home) ? 'off' : 'unknown' } : null;
+  return { harvest: sw.effective, reason: sw.reason, rows: sw.rows, warnings: sw.warnings, soul, instance, ...registeredSources(soul),
+    note: 'harvest applies from the next spawn: switching it on never captures earlier sessions, and switching it off stops run-source capture for registered sources. `oats schedule disable okf-<source>` is the per-source emergency brake.' };
+}
+
+/** Find the deployment's oats-local.yaml: OATS_WORKSPACE, else up from cwd. */
+function localFile() {
+  const candidates = [];
+  if (process.env.OATS_WORKSPACE) candidates.push(join(process.env.OATS_WORKSPACE, 'oats-local.yaml'));
+  for (let d = resolve(process.cwd()); ; d = dirname(d)) { candidates.push(join(d, 'oats-local.yaml')); if (dirname(d) === d) break; }
+  return candidates.find((f) => fs.existsSync(f)) || null;
+}
+/** Edit `settings: / oats.okf: / harvest:` in block style; null when the file
+ *  has any shape this small editor will not touch (then the line is printed). */
+export function editLocalYaml(text, value) {
+  if (/\t/.test(text)) return null;
+  const lines = text.split('\n');
+  const top = (i) => /^\S/.test(lines[i]) && !/^#/.test(lines[i]);
+  const s = lines.findIndex((l) => /^settings\s*:/.test(l));
+  if (s < 0) {
+    const tail = text.endsWith('\n') || text === '' ? '' : '\n';
+    return `${text}${tail}settings:\n  oats.okf:\n    harvest: ${value}\n`;
+  }
+  if (lines[s].replace(/^settings\s*:/, '').replace(/\s+#.*$/, '').trim() !== '') return null;
+  let end = lines.length;
+  for (let i = s + 1; i < lines.length; i++) if (top(i)) { end = i; break; }
+  let o = -1, childIndent = null;
+  for (let i = s + 1; i < end; i++) {
+    const m = /^(\s+)(['"]?)oats\.okf\2\s*:(.*)$/.exec(lines[i]);
+    if (m) { if (m[3].replace(/\s+#.*$/, '').trim() !== '') return null; o = i; childIndent = m[1].length; break; }
+  }
+  if (o < 0) {
+    const first = lines.slice(s + 1, end).find((l) => /^\s+\S/.test(l) && !/^\s*#/.test(l));
+    const ind = first ? /^(\s+)/.exec(first)[1] : '  ';
+    lines.splice(s + 1, 0, `${ind}oats.okf:`, `${ind}  harvest: ${value}`);
+    return lines.join('\n');
+  }
+  let blockEnd = end, keyIndent = null;
+  for (let i = o + 1; i < end; i++) {
+    if (/^\s*(#.*)?$/.test(lines[i])) continue;
+    const lead = /^(\s*)/.exec(lines[i])[1].length;
+    if (lead <= childIndent) { blockEnd = i; break; }
+    if (keyIndent === null) keyIndent = lead;
+    if (lead === keyIndent && /^\s*harvest\s*:/.test(lines[i])) { lines[i] = `${' '.repeat(lead)}harvest: ${value}`; return lines.join('\n'); }
+  }
+  lines.splice(o + 1, 0, `${' '.repeat(keyIndent ?? childIndent + 2)}harvest: ${value}`);
+  return lines.join('\n');
+}
+export function setupHarvest(value) {
+  if (!['on', 'off'].includes(value)) fail('E_USAGE', '--harvest must be on or off');
+  const line = `settings:\n  oats.okf:\n    harvest: ${value}`;
+  const file = localFile();
+  const note = value === 'on'
+    ? 'Harvest applies to new spawns of souls that do not opt out (knowledge: { harvest: off }). Earlier sessions are never captured. Run `oats okf harvest-status` to confirm.'
+    : 'New spawns register no source. Registered sources stop capturing at their next run-source. Nothing is deleted.';
+  if (!file) return { written: false, harvest: value, reason: 'no oats-local.yaml found (OATS_WORKSPACE or up from the current directory)', add: line, note };
+  const edited = editLocalYaml(fs.readFileSync(file, 'utf8'), value);
+  if (edited === null) return { written: false, file, harvest: value, reason: 'oats-local.yaml has a shape this command does not edit (flow style or tabs); add the line by hand', add: line, note };
+  atomic(file, edited);
+  return { written: true, file, harvest: value, note };
+}

package/capabilities/oats-okf/lib/harvest-switch.mjs

@@ -0,0 +1,81 @@
+// The harvest switch (okf 4.0.0; plan §2.4). `harvest: on|off` is a host
+// fact, default off. A soul may only opt OUT (`knowledge: { harvest: off }` in
+// soul.yaml), and that opt-out is absolute. The kernel merges soul ⊕ host ⊕
+// spawn with later-wins, so a host `on` would hide a soul `off` in the merged
+// settings. The soul's own value is therefore read from its soul.yaml
+// ($OATS_SOUL), with a deliberately small reader. Anything it cannot read with
+// certainty counts as off (fail closed): a private transcript is never kept
+// because a file was ambiguous.
+import { fs, join } from './io.mjs';
+
+const VALUES = ['on', 'off'];
+const scalar = (raw) => {
+  const v = raw.replace(/\s+#.*$/, '').trim();
+  const q = /^(['"])(.*)\1$/.exec(v);
+  return q ? q[2] : v;
+};
+/** The soul's own `knowledge.harvest` → { value: 'on'|'off'|null, readable, why }. */
+export function soulHarvest(soulDir) {
+  if (!soulDir) return { value: null, readable: false, why: 'the soul directory is not known to this command (OATS_SOUL unset)' };
+  let text;
+  try { text = fs.readFileSync(join(soulDir, 'soul.yaml'), 'utf8'); } catch (e) { return { value: null, readable: false, why: `soul.yaml unreadable (${e.code || e.message})` }; }
+  const lines = text.split(/\r?\n/);
+  const at = lines.findIndex((l) => /^knowledge\s*:/.test(l));
+  if (at < 0) return { value: null, readable: true, why: 'no knowledge: payload' };
+  const rest = lines[at].replace(/^knowledge\s*:/, '').replace(/\s+#.*$/, '').trim();
+  if (rest === 'none' || rest === "'none'" || rest === '"none"') return { value: null, readable: true, why: 'knowledge: none' };
+  if (rest.startsWith('{')) {
+    if (!rest.endsWith('}') || /[{}]/.test(rest.slice(1, -1))) return { value: null, readable: false, why: 'knowledge: flow mapping is not a single flat line' };
+    const pairs = rest.slice(1, -1).split(',').map((p) => p.trim()).filter(Boolean);
+    let value = null;
+    for (const pair of pairs) {
+      const m = /^(['"]?)([A-Za-z0-9._-]+)\1\s*:\s*(.*)$/.exec(pair);
+      if (!m) return { value: null, readable: false, why: 'knowledge: flow mapping entry is not key: value' };
+      if (m[2] === 'harvest') value = scalar(m[3]);
+    }
+    return shaped(value);
+  }
+  if (rest !== '') return { value: null, readable: false, why: 'knowledge: is neither none, a flow mapping nor a block mapping' };
+  let value = null, indent = null;
+  for (const line of lines.slice(at + 1)) {
+    if (/^\s*(#.*)?$/.test(line)) continue;
+    const lead = /^(\s*)/.exec(line)[1].length;
+    if (lead === 0) break;
+    if (/\t/.test(line.slice(0, lead))) return { value: null, readable: false, why: 'tab indentation under knowledge:' };
+    if (indent === null) indent = lead;
+    if (lead < indent) return { value: null, readable: false, why: 'inconsistent indentation under knowledge:' };
+    if (lead > indent) continue; // a nested value of another key
+    const m = /^\s*(['"]?)([A-Za-z0-9._-]+)\1\s*:(.*)$/.exec(line);
+    if (!m) return { value: null, readable: false, why: 'a knowledge: entry is not key: value' };
+    if (m[2] === 'harvest') value = scalar(m[3]);
+  }
+  return shaped(value);
+}
+function shaped(value) {
+  if (value === null) return { value: null, readable: true, why: 'the soul does not set harvest' };
+  if (!VALUES.includes(value)) return { value: null, readable: false, why: `the soul's harvest is ${JSON.stringify(value)}, not on or off` };
+  return { value, readable: true, why: `soul.yaml knowledge.harvest: ${value}` };
+}
+/** Effective = on only if the deployment says on AND the soul does not say off.
+ *  A soul `on` is ignored and reported: a soul cannot switch a host on. It also
+ *  hides the host's value (the kernel's merged `harvest` is then the soul's),
+ *  so with a soul `on` the switch stays off until the soul drops the line. */
+export function harvestSwitch({ settings = {}, soulDir = process.env.OATS_SOUL } = {}) {
+  const deployment = VALUES.includes(settings.harvest) ? settings.harvest : 'off';
+  const soul = soulHarvest(soulDir);
+  const rows = [
+    { layer: 'deployment', value: deployment, why: settings.harvest === undefined ? 'harvest is not set (default off)' : `settings.oats.okf.harvest: ${settings.harvest}` },
+    { layer: 'soul', value: soul.value, readable: soul.readable, why: soul.why },
+  ];
+  const warnings = [];
+  if (soul.value === 'on') warnings.push('the soul says harvest: on, which is ignored: only the deployment can switch harvest on; a soul may only opt out with harvest: off');
+  let effective = 'off', reason;
+  if (soul.value === 'on') reason = "the soul's harvest: on is ignored and hides the deployment's own value; remove it from soul.yaml (a soul may only opt out)";
+  else if (deployment !== 'on') reason = 'the deployment does not switch harvest on (oats-local.yaml settings.oats.okf.harvest)';
+  else if (!soul.readable) reason = `the soul's opt-out could not be read (${soul.why}); unreadable counts as off`;
+  else if (soul.value === 'off') reason = 'the soul opts out (knowledge: { harvest: off }), which the deployment cannot override';
+  else { effective = 'on'; reason = 'the deployment switches harvest on and the soul does not opt out'; }
+  return { effective, reason, rows, warnings };
+}
+/** The home's record that it was spawned with harvest off (no source registered). */
+export const instanceRecordPath = (home) => join(home, '.okf-instance.json');

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

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * okf-validate.mjs — OKF v0.1 bundle validator (no dependencies).
+ *
+ * Usage: node okf-validate.mjs <bundle-dir> [--strict] [--json]
+ *
+ * Conformance (errors): frontmatter parses; non-empty `type` on concepts;
+ * reserved files (index.md, log.md) carry no `type`.
+ * Producer lints (--strict, warnings): broken intra-bundle links (log.md exempt),
+ * links missing .md, concepts unreachable from any index.md, missing title/description.
+ * Exit: 0 conformant, 1 errors (or warnings with --strict), 2 usage.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve, dirname, posix } from "node:path";
+
+const args = process.argv.slice(2);
+const strict = args.includes("--strict");
+const asJson = args.includes("--json");
+const dir = args.find((a) => !a.startsWith("--"));
+if (!dir || !existsSync(dir)) { console.error("usage: okf-validate.mjs <bundle-dir> [--strict] [--json]"); process.exit(2); }
+const root = resolve(dir);
+
+const files = [];
+(function walk(d) {
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    if (e.name.startsWith(".")) continue;
+    const p = join(d, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (e.name.endsWith(".md")) files.push(p);
+  }
+})(root);
+
+const errors = [], warnings = [];
+const rel = (p) => relative(root, p).split("\\").join("/");
+const isReserved = (p) => ["index.md", "log.md"].includes(posix.basename(rel(p)));
+
+function parseFrontmatter(text) {
+  if (!text.startsWith("---")) return { present: false };
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+  if (!m) return { present: true, parsed: false };
+  const meta = {};
+  for (const line of m[1].split("\n")) {
+    if (/^\s*#/.test(line) || !line.trim()) continue;
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (kv) meta[kv[1]] = kv[2].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim();
+    else if (!/^\s+/.test(line)) return { present: true, parsed: false };
+  }
+  return { present: true, parsed: true, meta, body: text.slice(m[0].length) };
+}
+
+const concepts = new Map(); // rel path -> { meta, body }
+for (const f of files) {
+  const r = rel(f);
+  const text = readFileSync(f, "utf8");
+  const fm = parseFrontmatter(text);
+  if (isReserved(f)) {
+    if (fm.present && fm.parsed && fm.meta.type) errors.push(`${r}: reserved file must not carry a 'type'`);
+    if (fm.present && fm.parsed && posix.basename(r) === "index.md" && r !== "index.md") {
+      const keys = Object.keys(fm.meta);
+      if (keys.some((k) => k !== "okf_version")) warnings.push(`${r}: only the bundle-root index.md may carry frontmatter`);
+    }
+    concepts.set(r, { reserved: true, body: fm.parsed ? fm.body : text });
+    continue;
+  }
+  if (!fm.present) { errors.push(`${r}: missing YAML frontmatter`); continue; }
+  if (!fm.parsed) { errors.push(`${r}: unparseable YAML frontmatter`); continue; }
+  if (!fm.meta.type) errors.push(`${r}: missing or empty required field 'type'`);
+  if (strict) {
+    if (!fm.meta.title) warnings.push(`${r}: missing recommended field 'title'`);
+    if (!fm.meta.description) warnings.push(`${r}: missing recommended field 'description'`);
+  }
+  concepts.set(r, { meta: fm.meta, body: fm.body });
+}
+
+if (strict) {
+  // Link checks (log.md bodies exempt) + reachability from index files.
+  const reachable = new Set();
+  const linkRe = /\[[^\]]*\]\(([^)\s]+)\)/g;
+  const resolveLink = (fromRel, target) => {
+    if (/^[a-z]+:\/\//i.test(target) || target.startsWith("mailto:")) return null; // external
+    const clean = target.split("#")[0];
+    if (!clean) return null;
+    const abs = clean.startsWith("/")
+      ? posix.normalize(clean.slice(1))
+      : posix.normalize(posix.join(posix.dirname(fromRel), clean));
+    return abs;
+  };
+  for (const [r, c] of concepts) {
+    const body = c.body ?? "";
+    const fromLog = posix.basename(r) === "log.md";
+    for (const m of body.matchAll(linkRe)) {
+      const t = resolveLink(r, m[1]);
+      if (t === null) continue;
+      const isDir = t.endsWith("/") || concepts.has(posix.join(t, "index.md")) || existsSync(join(root, t)) && statSync(join(root, t)).isDirectory?.();
+      if (posix.basename(r) === "index.md" || !fromLog) {
+        if (!t.endsWith(".md") && !isDir) { if (!fromLog) warnings.push(`${r}: link missing .md extension: ${m[1]}`); continue; }
+      }
+      if (fromLog) continue; // history exempt from broken-link lint
+      if (t.endsWith(".md") && !concepts.has(t)) warnings.push(`${r}: broken link: ${m[1]}`);
+      if (posix.basename(r) === "index.md" && t.endsWith(".md") && concepts.has(t)) reachable.add(t);
+      if (posix.basename(r) === "index.md" && isDir) reachable.add(posix.join(t.replace(/\/$/, ""), "index.md"));
+    }
+  }
+  // Reachability: walk index closure (an index that lists a subdir makes that subdir's index reachable).
+  for (const [r, c] of concepts) {
+    if (c.reserved || reachable.has(r)) continue;
+    // root-level concepts listed in root index handled above; report the rest
+    const anyIndex = [...concepts.keys()].some((k) => posix.basename(k) === "index.md");
+    if (anyIndex) warnings.push(`${r}: unreachable from any index.md`);
+  }
+}
+
+const conceptCount = [...concepts.values()].filter((c) => !c.reserved).length;
+if (asJson) {
+  console.log(JSON.stringify({ bundle: root, concepts: conceptCount, errors, warnings, conformant: errors.length === 0 }, null, 2));
+} else {
+  console.log(`OKF validate — ${root}`);
+  console.log(`  ${conceptCount} concept(s), ${errors.length} error(s), ${warnings.length} warning(s)`);
+  for (const e of errors) console.log(`  ERROR ${e}`);
+  for (const w of warnings) console.log(`  warn  ${w}`);
+  console.log(errors.length === 0 ? (strict && warnings.length ? "PASS (with lints)" : "PASS — conformant") : "FAIL — nonconformant");
+}
+process.exit(errors.length > 0 ? 1 : strict && warnings.length > 0 && process.env.OKF_STRICT_EXIT ? 1 : 0);

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

@@ -5,6 +5,7 @@ import { acceptedResolution } from './consult.mjs';
 import { loadInvocationKnowledgeBinding, readPrivateInvocationJson, sourceRuntimeFromKnowledgeBinding } from './binding-wire.mjs';
 import { sameJson } from './portable-binding.mjs';
 import { qualifiedSoulIdentity } from './source-contract.mjs';
+import { harvestSwitch, instanceRecordPath } from './harvest-switch.mjs';
 
 const obj=value=>value!==null && typeof value==='object' && !Array.isArray(value);
 function exact(value,allowed,required,label) {
@@ -94,13 +95,32 @@ export function service(home) {
 // instance consults the bases remotely through `oats okf`. A ./knowledge/ left
 // by okf 2.x is not touched; inspect reports it as a legacy local view.
 const acceptedNodes = view => Object.fromEntries(Object.entries(view).map(([alias,row])=>[alias,row.nodes]));
+/** Instance knowledge (STATE.md, log.md, notes/) exists whether or not this
+ *  instance is harvested: it is the instance's own working memory. */
+export function ensureInstanceKnowledge(home) {
+  for(const [p,text] of [['STATE.md','# Working state\n\n# Task\n\n# Next\n'],['log.md','# Instance log\n']]) if(!fs.existsSync(join(home,p))) atomic(join(home,p),text);
+  fs.mkdirSync(join(home,'notes'),{recursive:true});
+}
 function finishRegistration(source) {
   // A durable home pointer precedes publication. Failures after it was saved
   // resume this same source; they never reset captured evidence or IDs.
-  for(const [p,text] of [['STATE.md','# Working state\n\n# Task\n\n# Next\n'],['log.md','# Instance log\n']]) if(!fs.existsSync(join(source.home,p))) atomic(join(source.home,p),text);
-  fs.mkdirSync(join(source.home,'notes'),{recursive:true});
+  ensureInstanceKnowledge(source.home);
   scheduleSource(source);return source;
 }
+/** Harvest off (okf 4.0.0): no source, no custody, no schedule. The home keeps
+ *  a small record so retire knows there is nothing to capture. */
+function harvestOff(home,sw,extra={}) {
+  const record={version:1,harvest:'off',reason:sw.reason,rows:sw.rows,warnings:sw.warnings,at:new Date().toISOString()};
+  atomic(instanceRecordPath(home),JSON.stringify(record,null,2)+'\n');
+  ensureInstanceKnowledge(home);
+  return {harvestOff:true,switch:sw,home,...extra};
+}
+export const harvestOffRecord = home => fs.existsSync(instanceRecordPath(home))?readJSON(instanceRecordPath(home)):null;
+/** The source's tasks provider (its instance.json tasks-layer capability), or null. */
+function tasksProvider(meta) {
+  const row=Array.isArray(meta?.capabilities)?meta.capabilities.find(c=>c && c.layer==='tasks' && typeof c.id==='string'):null;
+  return row?row.id:null;
+}
 function capturedOwner(bindings,owner,identity) {
   const file=join(bindings.stateDir,'owners.json'),row={schemaVersion:1,kind:'captured-qualified-soul',identity};
   withLock(join(bindings.stateDir,'owners.lock'),()=>{
@@ -126,6 +146,9 @@ export function registerCaptured(home,receipt) {
     return finishRegistration(source);
   }
   if(['.okf-harvest-record.json','.okf-harvest-record.next.json'].some(path=>fs.existsSync(join(home,path)))) fail('E_MIGRATION','legacy source watermarks require explicit migration before captured registration');
+  // The captured path takes its authority from the frozen binding and never
+  // reads live settings or the soul, so the 4.0.0 harvest switch (a live host
+  // setting) does not apply here. No released kernel drives this path.
   if(overlaps(home,captured.context) && captured.context.startsWith(home)) fail('E_PATH','captured deployment context cannot be in disposable home');
   const {file:bindingsFile,...bindingsDoc}=captured.binding.bindings;
   const bindings={file:bindingsFile,...validateBindings(bindingsDoc,bindingsFile,{sourceHome:home,sourceWork:captured.work})};
@@ -169,6 +192,8 @@ export function register(home) {
   const agent=process.env.OATS_AGENT || meta.agent;
   const instance=process.env.OATS_INSTANCE || meta.instance;
   if(!agent || !instance) fail('E_SOURCE','source instance/agent required');
+  const sw=harvestSwitch({settings:settings(),soulDir:soul});
+  if(sw.effective!=='on') {acceptedResolution(bindings,decl);return harvestOff(home,sw,{decl});}
   fs.mkdirSync(bindings.stateDir,{recursive:true,mode:0o700});
   const ownersFile=join(bindings.stateDir,'owners.json');
   const id=randomUUID(); const dir=join(bindings.stateDir,'sources',id);
@@ -177,7 +202,7 @@ export function register(home) {
   const roleFile=safePath(join(soul,'AGENTS.md'));
   const role=fs.existsSync(roleFile)?fs.readFileSync(roleFile,'utf8'):'';
   if(Buffer.byteLength(role)>128*1024) fail('E_SOURCE','role document exceeds 128KiB; provide a concise role before registering');
-  const source={version:1,id,home,work,context,agent,instance,owner:decl.owner,decl,role,bindings,bindingFingerprint:bindingFingerprint(bindings),execution:{runtime:settings()['harvest-runtime']||'pi',model:settings()['harvest-model']||null},created:new Date().toISOString()};
+  const source={version:1,id,home,work,context,agent,instance,owner:decl.owner,decl,role,bindings,bindingFingerprint:bindingFingerprint(bindings),execution:{runtime:settings()['harvest-runtime']||'pi',model:settings()['harvest-model']||null},soulId,tasksProvider:tasksProvider(meta),created:new Date().toISOString()};
   const file=join(dir,'source.json');
   fs.mkdirSync(dir,{recursive:true,mode:0o700});
   try {