@awebai/oats 0.29.3 → 0.30.0

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

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import { fs, join, resolve, readJSON, safePath, oats, fail, unlock } from '../lib/io.mjs';
+import { fs, join, resolve, readJSON, safePath, oats, fail, unlock, redactUrls } 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 { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, settleRetiredSchedule, service, markerPath, harvestOffRecord, sourceSwitch, retireHarvestOff, consultSource } 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';
+import { inspect, inspectConsultOnly } from '../lib/inspection.mjs';
 import { loadInvocationKnowledgeBinding } from '../lib/binding-wire.mjs';
 import { loadCapturedOkfInvocation, loadOkfSourceReceiptInput, assertOkfInvocationAction, requireOkfAdmittedAction, assertOkfSourceContext, assertOkfRegisteredSourceReplay } from '../lib/invocation-context.mjs';
 const HELP=`oats okf inspect [--home PATH | --source FILE] [--json]
@@ -98,6 +98,10 @@ else {
         return source;
       } catch(error) {if(captured && ['ENOENT','ENOTDIR'].includes(error.code)) fail('E_SOURCE','captured command requires its durable registered source descriptor');throw error;}
     };
+    // okf 4.0.3: consultation never depends on harvest. A home spawned with
+    // harvest off has no registered source by design; it consults through its
+    // soul's declaration and the deployment's bindings (consultSource).
+    const consultOnly=!flags.source && !captured && !execution && !fs.existsSync(markerPath(home)) && !!harvestOffRecord(home);
     // Deliberate old registered-source replay is a separate qualified contract,
     // never a way to create a source or synthesize generic admission. A present
     // invalid/unadmitted generic invocation cannot enter this compatibility path.
@@ -123,7 +127,7 @@ else {
     };
     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;}
+    if(consult) {const answer=CONSULT[event](consultOnly?consultSource(home):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') {
@@ -151,7 +155,10 @@ else {
         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'}};
       } else {
-        const s=src();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.'};
+        const s=src(),sw=sourceSwitch(s);
+        // okf 4.0.1 #6: harvest switched off since spawn (deployment or soul) → no final capture.
+        if(sw.effective!=='on') result={meta:retireHarvestOff(s,sw),brief:`Harvest is now off (${sw.reason}): no final capture was taken; earlier inputs stay in custody.`};
+        else {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(event==='harvest') {
       if(capturedHarvest) {
@@ -169,13 +176,13 @@ else {
       // 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'}
+      const source=src(),sw=sourceSwitch(source);
+      result=sw.effective!=='on'?{status:'harvest-off',source:source.file,reason:`${sw.reason}; 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==='inspect') result=consultOnly?inspectConsultOnly(consultSource(home)):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);
@@ -196,7 +203,7 @@ else {
     } else if(event==='unlock') result=unlock(resolve(flags.lock),flags.token);
     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}};}
+  } catch(e) {const code=e.code || 'E_OKF',message=redactUrls(e.message);exit=1;answer=hook?{meta:{...(event==='retire'?{retired:false,reason:message}:{})},warning:`oats-okf ${code}: ${message}`}:{schemaVersion:1,ok:false,error:{code,message}};}
   // 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`);

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

@@ -1,5 +1,4 @@
 import { TextDecoder } from 'node:util';
-import { validateInvocationShape } from './invocation-shape.mjs';
 import { tmpdir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { fs, safePath } from './io.mjs';
@@ -14,7 +13,7 @@ import {
   renderKnowledgeRuntime,
   sameJson,
 } from './portable-binding.mjs';
-import { validateBindings } from './config.mjs';
+import { declaration as soulDeclaration, loadBindings, validateBindings } from './config.mjs';
 import { stageBase, validateBase } from './stores.mjs';
 
 export const BINDING_WIRE_LIMITS=Object.freeze({bytes:1024*1024,depth:32,entries:16384});
@@ -254,14 +253,20 @@ export function loadInvocationKnowledgeBinding(env=process.env) {
 // binding.reasons (byte-exact) — the manifest test pins that.
 const checkReasons=Object.freeze({
   'action:not-admitted':'check action is not an admitted knowledge operation',
-  'bindings:invalid':'bound runtime bindings file is missing or invalid',
+  'settings:missing':'OKF settings missing bindings-file: set settings.oats.okf bindings-file, or deactivate oats.okf',
+  'soul:missing':'OKF soul declaration missing: create okf.json for this soul, or deactivate oats.okf',
+  'harvest-runtime:missing':settingMessages['harvest-runtime:missing'],
+  'harvest-runtime:invalid':settingMessages['harvest-runtime:invalid'],
+  'harvest-model:invalid':settingMessages['harvest-model:invalid'],
+  'binding:not-configured':'OKF binding missing or invalid: provision soul OKF declaration and bindings file, or deactivate oats.okf',
+  'bindings:invalid':'OKF bindings file missing or invalid: repair configured bindings file, or deactivate oats.okf',
   'bases:too-many':'more than 64 git knowledge bases declared',
   'base:stage-failed':'declared knowledge base could not be staged from its git source',
   'base:not-validated':'declared knowledge base is not a validated knowledge tree',
   'base:owner-unmet':'knowledge base owner or remote custody requirement not met',
   'base:source-mismatch':'staged git source does not match the declared knowledge base',
   'runtime:command-missing':'harvest runtime command is not installed on this host',
-  'runtime:not-qualified':'harvest runtime could not be qualified against the accepted bases',
+  'runtime:not-qualified':'harvest runtime is not qualified: install/configure the selected harvest runtime or set harvest off',
 });
 function problem(code,reason) {
   if(reason===undefined) return {code};
@@ -276,15 +281,40 @@ function providerActionName(action) {
   if(typeof action.name==='string' && action.name.startsWith('okf:')) return action.name.slice(4);
   return null;
 }
+function readinessRuntime(settings,env=process.env) {
+  if(Object.hasOwn(settings,'bindings-file')) {
+    try {
+      if(typeof settings['bindings-file']!=='string' || !absolute(settings['bindings-file'])) return {problem:problem('needs-configuration','settings:missing')};
+      if(settings.harvest!==undefined && !['on','off'].includes(settings.harvest)) return {problem:problem('needs-configuration','runtime:not-qualified')};
+      if(settings.harvest!=='off') {
+        if(settings['harvest-runtime']===undefined) return {problem:problem('needs-configuration','harvest-runtime:missing')};
+        if(!['pi','claude','codex'].includes(settings['harvest-runtime'])) return {problem:problem('needs-configuration','harvest-runtime:invalid')};
+        if(settings['harvest-model']!==undefined && (typeof settings['harvest-model']!=='string' || !settings['harvest-model'].trim())) return {problem:problem('needs-configuration','harvest-model:invalid')};
+      }
+      const bindings=loadBindings(settings['bindings-file']);
+      if(!env.OATS_SOUL) return {problem:problem('needs-configuration','soul:missing')};
+      const decl=soulDeclaration(env.OATS_SOUL);
+      return {runtime:{descriptorFile:bindings.file,bindings:{version:1,stateDir:bindings.stateDir,bases:bindings.bases},declaration:decl}};
+    } catch(error) {
+      const message=String(error?.message || '');
+      if(error?.code==='E_CONFIG' && /okf\.json|soul has no/.test(message)) return {problem:problem('needs-configuration','soul:missing')};
+      return {problem:problem('needs-configuration','bindings:invalid')};
+    }
+  }
+  if(settings.schemaVersion!==undefined) {
+    try { return {runtime:bindingPayload(settings,{diagnoseSettings:true}).runtime}; }
+    catch(error) {if(['invalid-binding','needs-configuration'].includes(error?.wireCode)) return {problem:problem('needs-configuration','binding:not-configured')};throw error;}
+  }
+  return {problem:problem('needs-configuration','settings:missing')};
+}
 function checkPhase(req) {
-  keys(req.input,['binding','context','action','invocation'],['binding','context','action'],'check input');
+  keys(req.input,['context','action'],['context','action'],'check input');
   if(!obj(req.input.context) || !obj(req.input.action)) wireError('invalid-binding');
-  if(Object.hasOwn(req.input,'invocation')) validateInvocationShape(req.input.invocation,{capability:CAPABILITY,context:req.input.context,action:req.input.action});
-  const {runtime}=bindingPayload(req.input.binding,{diagnoseSettings:true}),action=req.input.action,name=providerActionName(action);
-  const harvestInvocation=req.input.invocation;
-  const admittedHarvest=name==='harvest' && action.kind==='operation' && action.slot==='knowledge' && action.name==='harvest'
-    && harvestInvocation?.subject.kind==='persistent' && harvestInvocation.instance!==null && !!harvestInvocation.intent;
-  if(name && (unsupportedCapturedCommands.has(name) || name==='run-source' || (name==='harvest' && !admittedHarvest))) return {status:'needs-configuration',problems:[problem('provider-not-qualified','action:not-admitted')]};
+  const action=req.input.action,name=providerActionName(action);
+  const prepared=readinessRuntime(req.settings);
+  if(prepared.problem) return {status:'needs-configuration',problems:[prepared.problem]};
+  const runtime=prepared.runtime;
+  if(name && (unsupportedCapturedCommands.has(name) || name==='run-source' || name==='harvest')) return {status:'needs-configuration',problems:[problem('provider-not-qualified','action:not-admitted')]};
   if(action.kind==='hook' && action.name==='soul-scaffold') return {status:'ready',problems:[]};
   let bindings;try{bindings=validateBindings(runtime.bindings,runtime.descriptorFile);}catch{return {status:'needs-configuration',problems:[problem('needs-configuration','bindings:invalid')]};}
   const accepted={},gitBases=Object.entries(bindings.bases).filter(([,base])=>base.kind==='git');
@@ -296,14 +326,16 @@ function checkPhase(req) {
       stage=base.kind==='directory'?'validate':'stage';
       accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias),{alias})).meta;
     }
-    stage='runtime';
-    checkKnowledgeRuntime({rendered:runtime,accepted});
+    if(req.settings.harvest!=='off') {
+      stage='runtime';
+      checkKnowledgeRuntime({rendered:runtime,accepted});
+    }
   } catch(error) {
-    if(error.code==='E_COMMAND') return {status:'unavailable',problems:[problem('provider-unavailable','runtime:command-missing')]};
+    if(error.code==='E_COMMAND') return {status:'needs-configuration',problems:[problem('needs-configuration','runtime:command-missing')]};
     if(error.code==='E_OWNER') return {status:'needs-configuration',problems:[problem('provider-not-qualified','base:owner-unmet')]};
     if(error.code==='E_CONFIRM') return {status:'needs-configuration',problems:[problem('provider-not-qualified','base:source-mismatch')]};
     if(['E_BASE','E_VALIDATION','E_DIRECTORY_GIT'].includes(error.code)) return {status:'needs-configuration',problems:[problem('provider-not-qualified',stage==='stage'?'base:stage-failed':'base:not-validated')]};
-    if(stage==='runtime') return {status:'unavailable',problems:[problem('provider-unavailable','runtime:not-qualified')]};
+    if(stage==='runtime') return {status:'needs-configuration',problems:[problem('needs-configuration','runtime:not-qualified')]};
     return {status:'unavailable',problems:[problem('provider-unavailable')]};
   } finally {
     if(scratch) fs.rmSync(scratch,{recursive:true,force:true});

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

@@ -1,5 +1,5 @@
 import { isAbsolute } from 'node:path';
-import { fs, join, resolve, dirname, fail, readJSON, safePath, relPath, identifier, overlaps, hash } from './io.mjs';
+import { fs, join, resolve, dirname, fail, readJSON, safePath, relPath, identifier, overlaps, hash, embedsCredential } from './io.mjs';
 const obj = v => v && typeof v === 'object' && !Array.isArray(v);
 function keys(value, allowed, label, code='E_CONFIG') {
   if(!obj(value)) fail(code, `${label} must be an object`);
@@ -48,6 +48,7 @@ export function validateBindings(doc, file, { sourceHome, sourceWork } = {}) {
       keys(raw,['id','kind','repository','root','acceptedBranch','pr'],'git base');
       keys(raw.pr,['repository'],'git pr');
       if(typeof raw.repository !== 'string' || !raw.repository || raw.repository.startsWith('-') || /[\r\n\0]/.test(raw.repository) || 'path' in raw) fail('E_CONFIG', 'git base requires repository');
+      if(embedsCredential(raw.repository)) fail('E_CONFIG', `git base "${alias}": the repository locator embeds a credential (user:token@); bind the plain URL and let a Git credential helper or SSH key supply access`);
       const root = relPath(raw.root, true);
       if (typeof raw.acceptedBranch !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(raw.acceptedBranch) || raw.acceptedBranch.includes('..') || raw.acceptedBranch.endsWith('/') || raw.acceptedBranch.endsWith('.lock')) fail('E_CONFIG','invalid acceptedBranch');
       if (!obj(raw.pr) || typeof raw.pr.repository !== 'string' || !/^[\w.-]+\/[\w.-]+$/.test(raw.pr.repository)) fail('E_CONFIG','git pr requires repository: owner/repo (same-repository PRs)');

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

@@ -5,7 +5,7 @@
 import { randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 import { spawnSync } from 'node:child_process';
-import { fs, join, dirname, safePath, readJSON, save, digest, tree, withLock, fail, syncDir, identifier } from './io.mjs';
+import { fs, join, dirname, resolve, safePath, readJSON, save, digest, tree, withLock, fail, syncDir, identifier, relPath, within, displayRepo } from './io.mjs';
 import { noGit, gitTimeoutMs, consultMaxAgeMs, splitRef, resolveNodes } from './config.mjs';
 import { git, gitEnv, validateBase, baseLock, journalPath, preflightLocalRepository, requireNotShallow, verifyRemote, unavailable } from './stores.mjs';
 
@@ -248,6 +248,23 @@ export function withBase(bindings, alias, { fresh = false } = {}, fn) {
 }
 
 // ---------------------------------------------------------------- validation
+/** A tree entry name, from an untrusted accepted tree, as a path under the base
+ *  root. Git accepts literal `..`, absolute-looking and control-character entry
+ *  names (`hash-object --literally`), and they survive a partial clone, so every
+ *  name gets relPath's canonical rules (no empty, `.`, `..`, absolute, backslash,
+ *  NUL or `.git` segment) plus no control characters or percent-escapes. */
+export function treeEntryPath(name) {
+  const bad = () => fail('E_PATH', `invalid tree entry in knowledge base: ${JSON.stringify(String(name)).slice(0, 200)}`);
+  if (typeof name !== 'string' || /[\u0000-\u001f\u007f]/.test(name) || /%[0-9a-fA-F]{2}/.test(name)) bad();
+  try { return relPath(name); } catch { return bad(); }
+}
+/** Where a tree entry lands under `root`, refused unless it stays strictly
+ *  inside it after resolution (the second, independent guard). */
+export function containedTarget(root, name) {
+  const target = resolve(root, treeEntryPath(name));
+  if (target === resolve(root) || !within(root, target)) fail('E_PATH', `tree entry escapes its materialization root: ${JSON.stringify(name).slice(0, 200)}`);
+  return safePath(target);
+}
 const VALIDATION_CODES = new Set(['E_VALIDATION', 'E_BASE', 'E_PATH', 'E_ID', 'E_CONFIG']);
 /** Whether the accepted state is a valid OKF base. Git verdicts are cached per
  *  commit inside the host cache; computing one materializes the base root into
@@ -264,10 +281,15 @@ export function verdict(ctx) {
   try {
     const result = judge(() => {
       const rows = lsTree(ctx, '', { recursive: true });
-      for (const r of rows) if (!['100644', '100755'].includes(r.mode) || r.type !== 'blob') fail('E_PATH', 'symlink or submodule in knowledge base is not allowed');
+      // Every entry is judged before anything is written: the first bad name or
+      // mode refuses the whole base, and nothing lands outside the scratch.
+      for (const r of rows) {
+        if (!['100644', '100755'].includes(r.mode) || r.type !== 'blob') fail('E_PATH', 'symlink or submodule in knowledge base is not allowed');
+        r.target = containedTarget(scratch, r.name);
+      }
       prefetch(ctx, '');
       for (const r of rows) {
-        const target = safePath(join(scratch, r.name)); fs.mkdirSync(dirname(target), { recursive: true });
+        const target = r.target; fs.mkdirSync(dirname(target), { recursive: true });
         const fd = fs.openSync(target, 'wx', 0o600);
         let w; try { w = spawnSync('git', ['--no-replace-objects', '-c', 'core.hooksPath=/dev/null', '-C', ctx.cache, 'cat-file', 'blob', r.oid], { env: gitEnv(), timeout: gitTimeoutMs(), stdio: ['ignore', fd, 'pipe'] }); } finally { fs.closeSync(fd); }
         if (w.error || w.status !== 0) unavailable(ctx.base, ctx.alias, 'read', gitError(w));
@@ -346,7 +368,7 @@ export function bases(source, flags) {
   const rows = [], receipts = [];
   for (const [alias, base] of Object.entries(source.bindings.bases)) withBase(source.bindings, alias, { fresh: !!flags.fresh }, ctx => {
     const v = verdict(ctx), mine = relation => source.decl[relation].filter(ref => splitRef(ref)[0] === alias).map(ref => splitRef(ref)[1]);
-    rows.push({ alias, id: base.id, kind: base.kind, ...(base.kind === 'git' ? { repository: base.repository, acceptedBranch: base.acceptedBranch, root: base.root, commit: ctx.commit } : { path: base.path, digest: ctx.receipt.digest }),
+    rows.push({ alias, id: base.id, kind: base.kind, ...(base.kind === 'git' ? { repository: displayRepo(base.repository), acceptedBranch: base.acceptedBranch, root: base.root, commit: ctx.commit } : { path: base.path, digest: ctx.receipt.digest }),
       fetchedAt: ctx.receipt.fetchedAt, stale: ctx.receipt.stale, ...(ctx.receipt.reason ? { reason: ctx.receipt.reason } : {}),
       validated: v.ok ? { ok: true } : { ok: false, error: v.error }, nodes: v.ok ? Object.keys(v.nodes) : null, owns: mine('owns'), reads: mine('reads'), receipt: ctx.receipt });
     receipts.push(ctx.receipt);

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

@@ -60,11 +60,24 @@ function shaped(value) {
  *  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';
+/** OATS_SETTINGS_ORIGINS (kernel 0.29.0): JSON pointer → { kind, at } of the LAST
+ *  layer that set each leaf. {} when absent or unreadable. */
+export function parseOrigins(text = process.env.OATS_SETTINGS_ORIGINS) {
+  try { const o = JSON.parse(text || '{}'); return o && typeof o === 'object' && !Array.isArray(o) ? o : {}; } catch { return {}; }
+}
+/** okf 4.0.1: origins name the last layer only, and the host's settings merge
+ *  AFTER the soul's slot, so a host `harvest: on` hides a soul's `off` there.
+ *  soul.yaml therefore stays the authority for the absolute opt-out; origins
+ *  are an extra signal: a merged value whose origin is the soul is never the
+ *  deployment switching harvest on (a soul `on` is ignored, a soul `off` is off). */
+export function harvestSwitch({ settings = {}, soulDir = process.env.OATS_SOUL, origins = parseOrigins() } = {}) {
+  const origin = origins?.['/harvest'] && typeof origins['/harvest'] === 'object' ? origins['/harvest'] : null;
+  const fromSoul = origin?.kind === 'soul';
+  const deployment = !fromSoul && VALUES.includes(settings.harvest) ? settings.harvest : 'off';
   const soul = soulHarvest(soulDir);
+  if (fromSoul && VALUES.includes(settings.harvest) && soul.value === null) Object.assign(soul, { value: settings.harvest, readable: true, why: `OATS_SETTINGS_ORIGINS: harvest: ${settings.harvest} came from the soul (${String(origin.at || 'soul.yaml')})` });
   const rows = [
-    { layer: 'deployment', value: deployment, why: settings.harvest === undefined ? 'harvest is not set (default off)' : `settings.oats.okf.harvest: ${settings.harvest}` },
+    { layer: 'deployment', value: deployment, ...(origin ? { origin: origin.kind } : {}), why: fromSoul ? 'the merged harvest value came from the soul, so the deployment does not switch harvest on' : 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 = [];

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

@@ -53,10 +53,8 @@ function liveHome(source,status) {
     return {available:false,reason:'unverified-home',error:{code:e.code || 'E_SOURCE',message:e.message}};
   }
 }
-export function workingDocuments(source,status=loadStatus(source)) {
-  const before=liveHome(source,status),observedAt=new Date().toISOString();
-  const unavailable=state=>({liveMemory:{available:false,reason:state.reason,observedAt,...(state.error?{error:state.error}:{})},documents:[]});
-  if(!before.available) return unavailable(before);
+/** The home's working memory (STATE.md, log.md, notes/*.md), each capped. */
+function homeDocuments(home) {
   const documents=[];
   const doc=(label,file)=>{
     const content=regular(file,DOCUMENT_BYTES);
@@ -64,9 +62,9 @@ export function workingDocuments(source,status=loadStatus(source)) {
   };
   let error;
   try {
-    doc('Working state (STATE.md)',join(source.home,'STATE.md'));
-    doc('Log (log.md)',join(source.home,'log.md'));
-    const notes=safePath(join(source.home,'notes'));
+    doc('Working state (STATE.md)',join(home,'STATE.md'));
+    doc('Log (log.md)',join(home,'log.md'));
+    const notes=safePath(join(home,'notes'));
     function walk(dir,prefix='') {
       let entries;try {entries=fs.readdirSync(dir,{withFileTypes:true});} catch(e) {if(e.code==='ENOENT') return;throw e;}
       for(const entry of entries.sort((a,b)=>a.name<b.name?-1:a.name>b.name?1:0)) {
@@ -79,6 +77,13 @@ export function workingDocuments(source,status=loadStatus(source)) {
     }
     walk(notes);
   } catch(e) {error=e;}
+  return {documents,error};
+}
+export function workingDocuments(source,status=loadStatus(source)) {
+  const before=liveHome(source,status),observedAt=new Date().toISOString();
+  const unavailable=state=>({liveMemory:{available:false,reason:state.reason,observedAt,...(state.error?{error:state.error}:{})},documents:[]});
+  if(!before.available) return unavailable(before);
+  const {documents,error}=homeDocuments(source.home);
   const after=liveHome(source,loadStatus(source));
   if(!after.available) return unavailable(after);
   if(before.dev!==after.dev || before.ino!==after.ino) return unavailable({reason:'home-changed'});
@@ -117,3 +122,17 @@ export function inspect(source) {
     acceptedView:source.acceptedView,legacyLocalView:legacy,status,scheduler:health,liveMemory:working.liveMemory,documents
   };
 }
+/** okf 4.0.3: inspect a harvest-off home (consultSource): its declaration, the
+ *  bases it reads, and its own working memory. There is no source, custody or
+ *  schedule to report; `oats okf bases` shows the accepted state it reads. */
+export function inspectConsultOnly(source) {
+  const {documents,error}=homeDocuments(source.home),observedAt=new Date().toISOString();
+  if(error) fail(error.code==='E_PATH'?'E_PATH':'E_INSPECT_FAILED',error.message);
+  const path=join(source.home,'knowledge');let legacy=null;
+  try {const stat=fs.lstatSync(path);legacy={status:'legacy-local-view',path,ignored:true,...(stat.isSymbolicLink()?{symlink:true}:{}),note:'okf 3.0.0 ignores this okf 2.x snapshot and reads knowledge remotely; it is safe to delete by hand'};} catch(e) {if(!missing(e)) throw e;}
+  return {
+    summary:`OKF harvest off for this instance (${source.harvest.reason}): no source is registered and nothing is captured; ${documents.length} working-memory documents${legacy?'; legacy-local-view ./knowledge/ (ignored, safe to delete)':''}`,
+    source:null,harvest:source.harvest,owns:source.decl.owns,reads:source.decl.reads,bases:source.bindings.bases,
+    acceptedView:null,legacyLocalView:legacy,status:null,scheduler:null,liveMemory:{available:true,reason:'live',observedAt},documents
+  };
+}

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

@@ -8,6 +8,14 @@ export const fail = (code, message) => { throw Object.assign(new Error(message),
 export const hash = value => createHash('sha256').update(typeof value === 'string' || Buffer.isBuffer(value) ? value : JSON.stringify(value)).digest('hex');
 export const readJSON = path => JSON.parse(fs.readFileSync(path, 'utf8'));
 export const within = (root, path) => { const r = relative(root, path); return r === '' || (!r.startsWith('..' + sep) && r !== '..' && !isAbsolute(r)); };
+// okf 4.0.1 #2: a URL's userinfo is a credential (https://user:token@host).
+// Strip it from anything shown to agents or users; an SSH user alone
+// (ssh://git@host) is not a secret and stays.
+const USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/@'"]+)@/gi;
+export const redactUrls = text => String(text).replace(USERINFO, (m, scheme, info) => /^ssh:/i.test(scheme) && !info.includes(':') ? m : scheme);
+export const displayRepo = repository => typeof repository === 'string' ? redactUrls(repository) : repository;
+/** Whether a repository locator embeds a credential (any userinfo except a bare SSH user). */
+export const embedsCredential = repository => { USERINFO.lastIndex = 0; return typeof repository === 'string' && redactUrls(repository) !== repository; };
 export const overlaps = (a, b) => within(a, b) || within(b, a);
 export function safePath(path) {
   path = resolve(path);
@@ -77,7 +85,7 @@ export function unlock(path, token) {
   try { process.kill(o.pid, 0); fail('E_LOCKED', 'lock owner is still alive'); } catch (e) { if(e.code !== 'ESRCH') throw e; }
   fs.rmSync(path, { recursive: true }); syncDir(dirname(path)); return { unlocked: path };
 }
-export const identityKeys = ['OATS_INSTANCE','OATS_INSTANCE_HOME','OATS_HOME','PI_AGENT_HOME','PI_AGENT_NAME','PI_AGENT_INSTANCE','PI_AGENTS_ROOT','OATS_ROOT','OATS_SOUL','OATS_SOUL_ID','OATS_AGENT','OATS_KIND','OATS_EVENT','OATS_CONTEXT','OATS_REPO','OATS_WORK','OATS_BRANCH','OATS_META','OATS_SETTINGS','OATS_BINDING_FILE','OATS_SOURCE_RECEIPT_FILE','OATS_INVOCATION_CONTEXT_FILE','OATS_DEPLOYMENT','OATS_RESOLUTION'];
+export const identityKeys = ['OATS_INSTANCE','OATS_INSTANCE_HOME','OATS_HOME','PI_AGENT_HOME','PI_AGENT_NAME','PI_AGENT_INSTANCE','PI_AGENTS_ROOT','OATS_ROOT','OATS_SOUL','OATS_SOUL_ID','OATS_AGENT','OATS_KIND','OATS_EVENT','OATS_CONTEXT','OATS_REPO','OATS_WORK','OATS_BRANCH','OATS_META','OATS_SETTINGS','OATS_SETTINGS_ORIGINS','OATS_BINDING_FILE','OATS_SOURCE_RECEIPT_FILE','OATS_INVOCATION_CONTEXT_FILE','OATS_DEPLOYMENT','OATS_RESOLUTION'];
 export function cleanEnv(env = process.env) {
   return Object.fromEntries(Object.entries(env).filter(([k]) => !/^(OATS_(?!HOME_DIR$|PACKAGE_CATALOG$)|PI_AGENT|GIT_)/.test(k)));
 }

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

@@ -108,14 +108,28 @@ function finishRegistration(source) {
   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. */
+ *  a small record so retire knows there is nothing to capture, and (4.0.3) the
+ *  soul's declaration, so consultation works without a source. */
 function harvestOff(home,sw,extra={}) {
-  const record={version:1,harvest:'off',reason:sw.reason,rows:sw.rows,warnings:sw.warnings,at:new Date().toISOString()};
+  const record={version:1,harvest:'off',reason:sw.reason,rows:sw.rows,warnings:sw.warnings,...(extra.decl?{decl:extra.decl}:{}),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;
+/** okf 4.0.3: what a harvest-off home consults. Consultation never depends on
+ *  the harvest switch: such a home has no registered source by design, so it
+ *  reads its soul's declaration (recorded at spawn; the kernel's OATS_SOUL for
+ *  a home spawned before 4.0.3) and the deployment's bindings as they are now.
+ *  Nothing is registered, captured or scheduled. */
+export function consultSource(home) {
+  home=safePath(home);
+  const record=harvestOffRecord(home);
+  if(!record) fail('E_SOURCE',`no okf source for ${home}: it was not spawned with oats.okf as its knowledge capability`);
+  const decl=record.decl || (process.env.OATS_SOUL?declaration(fs.realpathSync(process.env.OATS_SOUL)):fail('E_OATS_SOUL_MISSING','OATS_SOUL is not set; oats.okf commands run only under the OATS kernel'));
+  const work=fs.existsSync(join(home,'work'))?fs.realpathSync(join(home,'work')):join(home,'work');
+  return {home,work,decl,bindings:loadBindings(undefined,{sourceHome:home,sourceWork:work}),harvest:{status:'off',reason:record.reason,at:record.at}};
+}
 /** 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;
@@ -202,7 +216,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},soulId,tasksProvider:tasksProvider(meta),created:new Date().toISOString()};
+  const source={version:1,id,home,work,context,agent,instance,owner:decl.owner,soulDir:soul,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 {
@@ -256,6 +270,23 @@ export function input(source,id) {
  *  that is still running (or has unresolved effects) stays disabled and is
  *  removed on the worker's next settle. Idempotent; a scheduler failure is
  *  recorded, never thrown — the evidence is already safe. */
+/** okf 4.0.1 #6: the switch for an already registered source, re-read now: the
+ *  deployment setting AND the soul's opt-out (the current OATS_SOUL the kernel
+ *  hands run-source/retire, else the soul directory recorded at registration). */
+export function sourceSwitch(source) {
+  const current = process.env.OATS_SOUL && fs.existsSync(process.env.OATS_SOUL) ? process.env.OATS_SOUL : null;
+  return harvestSwitch({ settings: settings(), soulDir: current || source.soulDir || undefined });
+}
+/** Retire a registered source whose harvest is now off: no final capture; the
+ *  inputs already in custody stay; the schedule is settled as for any retire. */
+export function retireHarvestOff(source, sw) {
+  updateStatus(source, current => {
+    current.retired = true; current.retiredAt = new Date().toISOString(); current.harvestOff = { reason: sw.reason, at: current.retiredAt };
+    // As a final capture would: the schedule stays only while earlier inputs await processing.
+    current.auto = current.auto && !current.captured.inputs.every(id => current.processed.includes(id));
+  });
+  return { retired: true, reason: 'harvest-off', switch: sw.reason, source: source.file, schedule: settleRetiredSchedule(source) };
+}
 export function settleRetiredSchedule(source) {
   const status=loadStatus(source);
   if(status.schedule?.removed===true) return {status:'already-removed',id:status.schedule.id};

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

@@ -2,14 +2,14 @@ import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { fs, join, dirname, safePath, readJSON, save, atomic, tree, materialize, digest, hash, withLock, exec, cleanEnv, fail, relPath, overlaps, resolve } from './io.mjs';
+import { fs, join, dirname, safePath, readJSON, save, atomic, tree, materialize, digest, hash, withLock, exec, cleanEnv, fail, relPath, overlaps, resolve, within, redactUrls, displayRepo } from './io.mjs';
 import { metadata, noGit, gitTimeoutMs } from './config.mjs';
 const validator = fileURLToPath(new URL('./okf-validate.mjs', import.meta.url));
 // Never let local replace refs reinterpret frozen OIDs, including inside Git's
 // transport subprocesses. Override even an explicitly supplied command env.
 export const gitEnv = (env = cleanEnv()) => ({...env,GIT_NO_REPLACE_OBJECTS:'1'});
 export const git = (cwd,args,opts={}) => exec('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-c','protocol.ext.allow=never','-C',cwd,...args],{cwd,...opts,env:gitEnv(opts.env)});
-function baseError(code,message,base,alias,step,reason) {throw Object.assign(new Error(message),{code,base:alias,repository:base.repository,step,reason});}
+function baseError(code,message,base,alias,step,reason) {throw Object.assign(new Error(redactUrls(message)),{code,base:alias,repository:displayRepo(base.repository),step,reason});}
 function baseRemedy(alias) {return `fix the binding for base alias "${alias}" in the bindings file, or remove the base from the bindings`;}
 function classifyGitFailure(error) {
   const text=String(error?.message || '');
@@ -20,13 +20,13 @@ function classifyGitFailure(error) {
   return 'unknown';
 }
 export function unavailable(base,alias,step,error) {
-  const reason=classifyGitFailure(error),detail=reason==='unknown'?`; original Git failure: ${String(error?.message || 'unknown failure')}`:'';
-  const message=`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but ${step} failed (reason: ${reason}${detail}); ${baseRemedy(alias)}`;
+  const reason=classifyGitFailure(error),detail=reason==='unknown'?`; original Git failure: ${redactUrls(String(error?.message || 'unknown failure'))}`:'';
+  const message=`Git base "${alias}" repository "${displayRepo(base.repository)}" is required by the deployment's bindings, but ${step} failed (reason: ${reason}${detail}); ${baseRemedy(alias)}`;
   baseError('E_BASE_UNAVAILABLE',message,base,alias,step,reason);
 }
 export function requireNotShallow(base,alias,cwd) {
   const shallow=git(cwd,['rev-parse','--is-shallow-repository']);
-  if(shallow==='true') baseError('E_BASE_SHALLOW',`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but the repository is shallow; oats.okf requires full accepted history before staging; ${baseRemedy(alias)}`,base,alias,'clone','shallow');
+  if(shallow==='true') baseError('E_BASE_SHALLOW',`Git base "${alias}" repository "${displayRepo(base.repository)}" is required by the deployment's bindings, but the repository is shallow; oats.okf requires full accepted history before staging; ${baseRemedy(alias)}`,base,alias,'clone','shallow');
 }
 export function preflightLocalRepository(base,alias) {
   if(!base.repository.startsWith('/')) return;
@@ -77,7 +77,9 @@ function materializeGitObjects(base,dest,head) {
   // that an entry outside the root is expected to be absent (see outsideBase).
   for(const [p,entry] of entries) {
     if(outsideBase(base,p)) continue;
-    const target=safePath(join(dest,p));fs.mkdirSync(dirname(target),{recursive:true});
+    // relPath above already refused traversal; containment is asserted again
+    // on the resolved target before any write (okf 4.0.1 #1).
+    const target=resolve(dest,p);if(target===resolve(dest) || !within(dest,target)) fail('E_PATH','Git tree entry escapes the stage');safePath(target);fs.mkdirSync(dirname(target),{recursive:true});
     writeBlob(dest,entry.oid,target,entry.mode==='100755'?0o755:0o644);
   }
 }

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

@@ -37,7 +37,7 @@ export function completionCommand(source,id,judgmentFile) {return command(source
 // It homes in agents/oats-okf--knowledge-harvester/. Its instances get an
 // exact --name okf-harvester-<run> (50 characters): a derived
 // <agent>-<purpose> name would exceed the kernel's 64-character cap.
-export const HARVESTER_SOUL='oats.okf/knowledge-harvester',HARVESTER_AGENT='oats-okf--knowledge-harvester',HARVESTER_TEAM='okf';
+export const HARVESTER_SOUL='oats.okf/knowledge-harvester',HARVESTER_AGENT='oats-okf--knowledge-harvester';
 export const harvesterInstance=id=>`okf-harvester-${id}`;
 /** The harvester's own completion and status commands (oats.okf-harvest). The
  *  completion wrapper runs this source's frozen `oats okf complete` from the
@@ -47,15 +47,6 @@ export function harvesterCommands(source,id) {
   return {complete:['oats','okf-harvest','complete',...tail,'--judgment','<absolute-judgment.json>'].map(quote).join(' '),
     status:['oats','okf-harvest','harvest-status',...tail].map(quote).join(' ')};
 }
-/** The messaging capability the harvester soul resolves (from spawn --preview),
- *  so it can join the okf team; null when it resolves none. */
-function harvesterMessaging(source) {
-  try {
-    const preview=oats(['spawn',HARVESTER_SOUL,'--dir',source.context,'--preview','--json'],source.context,{timeout:90000});
-    const row=(Array.isArray(preview?.modules)?preview.modules:[]).find(m=>m?.layer==='messaging' && typeof m.name==='string');
-    return {messaging:row?row.name:null};
-  } catch(e) {return {messaging:null,error:`${e.code || 'E_RUNTIME'}: ${e.message}`};}
-}
 export function runSource(source,{noLaunch=false,manual=false,capturedInvocation,nativeRequest}={}) {
   const plan=capturedSource(source)?qualifyCapturedWorker(source,{context:capturedInvocation,nativeRequest}):null;
   if(!plan) requireQualifiedHelper(source);
@@ -117,7 +108,7 @@ function spawnWorker(source,run,{parent=false}={}) {
     task=`Process only durable OKF run ${id}. Load the knowledge-harvest skill first.${recovery}\n\n${evidence}\n\nWrite ./work/judgment.json per the skill, then execute the completion command below, replacing only the quoted placeholder with the absolute judgment file path (shell-quote it). A successful command, not this task, is the delivery receipt. On failure retain the worker and report it; do not self-retire. On success report receipt then retire normally.\n\n${complete}\n`;
   } else {
     const cmd=harvesterCommands(source,id);
-    task=`Process only durable OKF run ${id}. Load the knowledge-harvest skill first.${recovery}\n\n${evidence}\n\nWrite ./work/judgment.json per the skill, then run the completion command below, replacing only the quoted placeholder with the absolute judgment file path (shell-quote it). It runs this source's frozen completion in the source deployment. A successful command, not this task, is the delivery receipt. On failure keep your home and report it; do not retire.\n\nAfter a successful completion, stay alive in the okf team until your PR is merged or closed. On every wake run the status command first, and retire only when it says retire or max-age. Never close the PR yourself.\n\nComplete: ${cmd.complete}\nStatus:   ${cmd.status}\n`;
+    task=`Process only durable OKF run ${id}. Load the knowledge-harvest skill first.${recovery}\n\n${evidence}\n\nWrite ./work/judgment.json per the skill, then run the completion command below, replacing only the quoted placeholder with the absolute judgment file path (shell-quote it). It runs this source's frozen completion in the source deployment. A successful command, not this task, is the delivery receipt. On failure keep your home and report it; do not retire.\n\nAfter a successful completion, stay alive until your PR is merged or closed. On every wake run the status command first, and retire only when it says retire or max-age. Never close the PR yourself.\n\nComplete: ${cmd.complete}\nStatus:   ${cmd.status}\n`;
   }
   const taskFile=join(dirname(runPath(source,id)),'TASK.md');
   const actualTask=run.capturedWorker?task.replace('On success report receipt then retire normally.',`On success report the actual receipt and include run ${id} in your final assistant reply. RETAIN this home/history. Public captured retirement is not qualified; never use legacy retirement or self-retire.`) :task;
@@ -143,11 +134,9 @@ function spawnWorker(source,run,{parent=false}={}) {
   const args=['spawn',HARVESTER_SOUL,'--name',harvesterInstance(id),'--dir',source.context,harnessFlag(source),source.execution.runtime,'--no-launch','--task-file',taskFile,'--json'];
   if(source.execution.model) args.push('--model',source.execution.model);
   if(parent) args.push('--parent',source.instance);
-  // Join the okf team through the soul's messaging capability, as a trigger
-  // spawn does; without one the harvester cannot talk to the maintainer.
-  const team=harvesterMessaging(source);
-  if(team.messaging) args.push('--provider',team.messaging,`join=${HARVESTER_TEAM}`);
-  run.team={team:HARVESTER_TEAM,messaging:team.messaging,...(team.error?{error:team.error}:{})};
+  // okf 4.0.2: no team join. The harvester lives in the deployment's default
+  // team, where the maintainer reaches it; a deployment that wants it in
+  // another team opts in locally, as for any soul.
   try {
     run.worker=oats(args,source.context,{timeout:90000});
     if(!run.worker.instance || !run.worker.home) fail('E_RUNTIME','spawn receipt lacks worker identity');
@@ -340,7 +329,8 @@ function harvesterAlias(run) {
 export function provenance(source,run) {
   const identity=source.sourceIdentity;
   return {version:1,run:run.id,input:[...run.inputs],
-    source:{soul:identity?.name ?? identity?.soul ?? source.agent,soulId:source.soulId ?? (identity?JSON.stringify(identity):null),instance:source.instance,
+    // owner: the source's okf.json owner, which okf-base.json nodes record (okf 4.0.1 #3).
+    source:{soul:identity?.name ?? identity?.soul ?? source.agent,soulId:source.soulId ?? (identity?JSON.stringify(identity):null),owner:source.owner ?? null,instance:source.instance,
       ownedNodes:[...source.decl.owns],readNodes:[...source.decl.reads],
       bases:Object.entries(source.bindings.bases).map(([alias,b])=>({alias,id:b.id,kind:b.kind,...(b.kind==='git'?{root:b.root,repository:b.pr.repository}:{})}))},
     tasks:{provider:source.tasksProvider ?? null,refs:[...new Set(run.judgment?.tasks?.refs || [])]},

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "4.0.0",
+  "version": "4.0.4",
   "compatibility": {
     "oats": ">=0.29.0"
   },
@@ -82,14 +82,17 @@
       "setting harvest-runtime must be pi, claude or codex",
       "setting harvest-model must be null or a non-empty string",
       "check action is not an admitted knowledge operation",
-      "bound runtime bindings file is missing or invalid",
+      "OKF settings missing bindings-file: set settings.oats.okf bindings-file, or deactivate oats.okf",
+      "OKF soul declaration missing: create okf.json for this soul, or deactivate oats.okf",
+      "OKF binding missing or invalid: provision soul OKF declaration and bindings file, or deactivate oats.okf",
+      "OKF bindings file missing or invalid: repair configured bindings file, or deactivate oats.okf",
       "more than 64 git knowledge bases declared",
       "declared knowledge base could not be staged from its git source",
       "declared knowledge base is not a validated knowledge tree",
       "knowledge base owner or remote custody requirement not met",
       "staged git source does not match the declared knowledge base",
       "harvest runtime command is not installed on this host",
-      "harvest runtime could not be qualified against the accepted bases"
+      "harvest runtime is not qualified: install/configure the selected harvest runtime or set harvest off"
     ]
   },
   "inject": "injects/okf.md",

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

@@ -74,7 +74,7 @@ export function complete(flags, env = process.env) {
   let answer; try { answer = JSON.parse(r.stdout); } catch { /* below */ }
   if (answer?.schemaVersion === 1 && answer.ok === true) return { deployment: source.context, ...answer.result };
   const code = answer?.error?.code || 'E_COMPLETE', message = answer?.error?.message || (r.error?.message || r.stderr || `exit ${r.status}`).trim();
-  if (INACTIVE.has(code)) fail('E_SOURCE_INACTIVE', `oats.okf cannot run for source soul ${source.agent} in ${source.context} (${code}: ${message}). Nothing was published: report this to the okf team and your operator, and stay.`, { cause: code });
+  if (INACTIVE.has(code)) fail('E_SOURCE_INACTIVE', `oats.okf cannot run for source soul ${source.agent} in ${source.context} (${code}: ${message}). Nothing was published: report this to your operator, and stay.`, { cause: code });
   fail(code, `${message} (completion ran in ${source.context}; keep your home and report)`);
 }
 /** "7d" | "48h" | "90m" | seconds → milliseconds. */
@@ -112,7 +112,7 @@ export function harvestStatus(flags, env = process.env, { now = Date.now(), view
   if (!judged || pending.length) { action = age >= limit ? 'max-age' : 'stay'; reason = !judged ? 'the run is not completed yet' : `destinations not delivered: ${pending.map((d) => d.alias).join(', ')}`; }
   else if (open.length) { action = age >= limit ? 'max-age' : 'stay'; reason = `open PR: ${open.map((d) => d.pr.url).join(', ')}`; }
   else { action = 'retire'; reason = destinations.some((d) => d.pr) ? 'every PR is merged or closed' : 'no PR was needed (no-change or directory publication)'; }
-  if (action === 'max-age') reason += `; older than harvester-max-age (${Math.round(limit / 3600000)}h): tell the okf team and retire, never close the PR`;
+  if (action === 'max-age') reason += `; older than harvester-max-age (${Math.round(limit / 3600000)}h): tell your operator and retire, never close the PR`;
   return { run: run.id, status: run.status, ageSeconds: Math.round(age / 1000), maxAgeSeconds: limit / 1000, destinations, action, reason };
 }
 function text(event, r) {