@awebai/oats 0.23.0 → 0.23.1

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

@@ -0,0 +1,238 @@
+import { randomUUID } from 'node:crypto';
+import { fs, join, dirname, resolve, safePath, readJSON, save, atomic, materialize, hash, withLock, oats, fail, tree, overlaps, syncDir } from './io.mjs';
+import { loadBindings, declaration, metadata, resolveNodes, bindingFingerprint, settings, validateBindings } from './config.mjs';
+import { stageBase } from './stores.mjs';
+export const markerPath = home => join(home,'.okf-source.json');
+export const statusPath = source => join(dirname(source.file),'status.json');
+export const saveStatus = (source,status) => save(statusPath(source),status);
+export function updateStatus(source, mutate) {
+  return withLock(join(dirname(source.file),'status.lock'),()=>{
+    const status=loadStatus(source);mutate(status);saveStatus(source,status);return status;
+  });
+}
+function saveCapture(source, status) {
+  updateStatus(source,current=>{
+    current.captured=status.captured;
+    if(status.launchObserved!==undefined) current.launchObserved=status.launchObserved;
+    if(status.lastCapture) current.lastCapture=status.lastCapture;
+    if(status.retired) {current.retired=true;current.retiredAt=status.retiredAt;current.auto=current.auto && status.auto;}
+  });
+}
+export const loadStatus = source => readJSON(statusPath(source));
+export function loadSource(file) {
+  safePath(file); const s=readJSON(file);
+  if(s.version!==1 || !/^[0-9a-f-]{36}$/.test(s.id) || resolve(file)!==join(s.bindings.stateDir,'sources',s.id,'source.json')) fail('E_SOURCE','invalid source descriptor path/identity');
+  const {file:bindingsFile,...bindingsDoc}=s.bindings;
+  const checked=validateBindings(bindingsDoc,bindingsFile,{sourceHome:s.home,sourceWork:s.work});
+  if(bindingFingerprint(checked)!==s.bindingFingerprint) fail('E_SOURCE','frozen bindings fingerprint mismatch');
+  return {...s,file};
+}
+export function homeSource(home) { const m=readJSON(markerPath(home)); const s=loadSource(m.source); if(s.id!==m.id || s.home!==home) fail('E_SOURCE','home identity does not match durable source');return s; }
+export function service(home) {
+  if(fs.existsSync(join(home,'instance.json'))) return readJSON(join(home,'instance.json')).kind==='capability';
+  return process.env.OATS_KIND==='capability';
+}
+// Control files live at the view root; arbitrary legal aliases live ONLY in
+// bases/. Receipts use paths relative to the view so moving a prepared view
+// into its final location cannot invalidate its navigation.
+export function views(bindings, decl, target) {
+  target=safePath(target); if(fs.existsSync(target)) fail('E_VIEW','view exists; use a new immutable view destination');
+  const all={}; const receipts={};
+  fs.mkdirSync(dirname(target),{recursive:true});
+  const pending=fs.mkdtempSync(join(dirname(target),'.okf-view-'));
+  try {
+    for(const [alias,base] of Object.entries(bindings.bases)) {
+      const scratch=fs.mkdtempSync(join(bindings.stateDir,'read-'));
+      try {
+        const staged=stageBase(base,join(scratch,'base'));
+        all[alias]=staged.meta;
+        const path=`bases/${alias}`;
+        materialize(join(pending,path),staged.files);
+        receipts[alias]={path,id:base.id,digest:staged.digest,head:staged.head || null,nodes:staged.meta.nodes};
+      } finally { fs.rmSync(scratch,{recursive:true,force:true}); }
+    }
+    resolveNodes(decl,bindings,all);
+    save(join(pending,'view.json'),{version:1,at:new Date().toISOString(),bases:receipts,owns:decl.owns,reads:decl.reads});
+    // Never expose a partial view or remove/replace a caller's existing view.
+    if(fs.existsSync(target)) fail('E_VIEW','view exists; use a new immutable view destination');
+    fs.renameSync(pending,target);syncDir(dirname(target));
+    return receipts;
+  } finally { fs.rmSync(pending,{recursive:true,force:true}); }
+}
+const registrationView = source => join(source.home,`.okf-view-${source.id}`);
+function finishRegistration(source) {
+  const pending=safePath(registrationView(source)),target=safePath(join(source.home,'knowledge'));
+  if(fs.existsSync(pending)) {
+    if(fs.existsSync(target)) fail('E_VIEW','knowledge already exists; refusing to replace it with the registered view');
+    fs.renameSync(pending,target);syncDir(source.home);
+  }
+  // A durable home pointer precedes publication. Failures after it was saved
+  // resume this same source/view; they never reset captured evidence or IDs.
+  const receipt=readJSON(join(target,'view.json'));
+  if(source.acceptedView && JSON.stringify(receipt.bases)!==JSON.stringify(source.acceptedView)) fail('E_VIEW','registered accepted view receipt differs; preserve it and inspect');
+  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});
+  scheduleSource(source);return source;
+}
+export function register(home) {
+  home=safePath(home);
+  if(service(home)) return {skipped:'service'};
+  if(fs.existsSync(markerPath(home))) return finishRegistration(homeSource(home));
+  safePath(join(home,'knowledge'));
+  if(fs.existsSync(join(home,'knowledge'))) fail('E_VIEW','unregistered knowledge view exists; preserve it and inspect before registering');
+  if(['.okf-harvest-record.json','.okf-harvest-record.next.json'].some(p=>fs.existsSync(join(home,p))) && !fs.existsSync(join(home,'.okf-v1-migration.json'))) fail('E_MIGRATION','legacy source watermarks require explicit oats okf migrate --source-home PATH before v2 registration; no cursor is silently trusted');
+  const meta=fs.existsSync(join(home,'instance.json'))?readJSON(join(home,'instance.json')):{};
+  const soul=fs.realpathSync(process.env.OATS_SOUL || join(home,'soul'));
+  const work=fs.existsSync(join(home,'work'))?fs.realpathSync(join(home,'work')):join(home,'work');
+  const decl=declaration(soul);
+  const bindings=loadBindings(undefined,{sourceHome:home,sourceWork:work});
+  const context=fs.realpathSync(process.env.OATS_CONTEXT || meta.repo || fail('E_CONFIG','source requires durable config context'));
+  if(overlaps(home,context) && context.startsWith(home)) fail('E_PATH','config context cannot be in disposable 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');
+  fs.mkdirSync(bindings.stateDir,{recursive:true,mode:0o700});
+  const ownersFile=join(bindings.stateDir,'owners.json');
+  withLock(join(bindings.stateDir,'owners.lock'),()=>{
+    const owners=fs.existsSync(ownersFile)?readJSON(ownersFile):{};
+    if(Object.hasOwn(owners,decl.owner) && owners[decl.owner]!==soul) fail('E_OWNER','stable owner ID already identifies a different soul in this state namespace');
+    owners[decl.owner]=soul;save(ownersFile,owners);
+  });
+  const id=randomUUID(); const dir=join(bindings.stateDir,'sources',id);
+  // Copy only the role document, never instance.json wholesale, launch recipes,
+  // environment, credentials, source worktree, or third-party message stores.
+  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 file=join(dir,'source.json');
+  const pending=registrationView(source);
+  fs.mkdirSync(dir,{recursive:true,mode:0o700});
+  try {
+    source.acceptedView=views(bindings,decl,pending);
+    source.acceptedNodes=Object.fromEntries(Object.entries(source.acceptedView).map(([alias,r])=>[alias,r.nodes]));
+    save(file,source);
+    save(join(dir,'status.json'),{version:1,captured:{notes:[],threads:{},inputs:[]},processed:[],delivered:{},accepted:{},retired:false,auto:true,activeRun:null});
+    save(markerPath(home),{version:1,id,source:file});
+  } catch(e) {
+    // Until the pointer is durable no capture or schedule can reference these
+    // files. Leave an installed pointer's state intact even if fsync failed.
+    if(!fs.existsSync(markerPath(home))) {
+      fs.rmSync(pending,{recursive:true,force:true});
+      fs.rmSync(dir,{recursive:true,force:true});
+    }
+    throw e;
+  }
+  return finishRegistration({...source,file});
+}
+function enqueue(source,status,payload) {
+  const id=hash(payload);const path=join(dirname(source.file),'inputs',`${id}.json`);
+  if(!fs.existsSync(path)) save(path,payload);
+  if(!status.captured.inputs.includes(id)) status.captured.inputs.push(id);
+  return id;
+}
+export function input(source,id) {
+  if(!/^[0-9a-f]{64}$/.test(id)) fail('E_INPUT','bad input identity');
+  const value=readJSON(join(dirname(source.file),'inputs',`${id}.json`));
+  if(hash(value)!==id) fail('E_INPUT','durable evidence hash mismatch');return value;
+}
+export function capture(source,{final=false,deadlineMs=85000}={}) {
+  return withLock(join(dirname(source.file),'capture.lock'),()=>{
+    const status=loadStatus(source);
+    if(status.retired) return {status:'complete',complete:true,retired:true};
+    if(!fs.existsSync(markerPath(source.home))) fail('E_SOURCE','source home gone without final capture; existing evidence is retained');
+    if(homeSource(source.home).id!==source.id) fail('E_SOURCE','source name reused');
+    const start=Date.now(); const meta=fs.existsSync(join(source.home,'instance.json'))?readJSON(join(source.home,'instance.json')):{};
+    const noLaunch=meta.launched!==true;status.launchObserved=!noLaunch;
+    // Notes AND record, every pass. Note content versions remain captured even
+    // when the live file is rewritten while a worker is judging a prior version.
+    const notes=join(source.home,'notes');
+    if(fs.existsSync(notes)) for(const [name,b64] of Object.entries(tree(notes))) {
+      if(!name.endsWith('.md')) continue;
+      const text=Buffer.from(b64,'base64').toString('utf8');const key=hash({name,text});
+      if(status.captured.notes.includes(key)) continue;
+      enqueue(source,status,{version:1,kind:'note',name,contentHash:hash(text),text});
+      status.captured.notes.push(key);saveCapture(source,status);
+    }
+    let report;
+    try {
+      report=oats(['capture','--home',source.home,'--quiet'],source.context,{native:true,timeout:Math.min(deadlineMs,60000)});
+      if(!Array.isArray(report.sessions)) fail('E_CAPTURE','capture response has no sessions');
+      for(const session of report.sessions) {
+        if(!session.thread || !session.lastTurnId) continue;
+        let after=status.captured.threads[session.thread] || null;
+        while(after!==session.lastTurnId) {
+          if(Date.now()-start>deadlineMs) fail('E_CAPTURE','capture deadline: backlog preserved; retire must retry');
+          const args=['recall','--thread',session.thread,'--until',session.lastTurnId,'--limit','60','--json','--ids-only'];
+          if(after) args.push('--after',after);
+          const remainingTime=()=>{
+            const remaining=deadlineMs-(Date.now()-start);
+            if(remaining<=0) fail('E_CAPTURE','capture deadline: backlog preserved; retire must retry');
+            return Math.max(1000,remaining);
+          };
+          let plan;
+          try { plan=oats(args,source.context,{native:true,timeout:remainingTime()}); }
+          catch(e) { if(after && /--after: no turn/.test(e.message)) {after=null;continue;} throw e; }
+          if(!Array.isArray(plan.turns) || !plan.turns.length || plan.turns.length>60) fail('E_CAPTURE','capture/recall boundaries disagree');
+          // Plan BEFORE requesting text. Native bytes describe each turn in
+          // pretty JSON. Nested response indentation adds bytes: reserve 3x
+          // that estimate plus envelope space, always below the 16MiB pipe.
+          // The 96k target is soft only for one individually legal turn.
+          let offset=0;
+          while(offset<plan.turns.length) {
+            const window=[];let bytes=0;
+            for(const t of plan.turns.slice(offset)) {
+              if(typeof t.id!=='string' || !t.id || t.thread!==session.thread || t.kind!=='session' || !Number.isSafeInteger(t.bytes) || t.bytes<=0) fail('E_CAPTURE','invalid ids-only record metadata');
+              if(window.length && bytes+t.bytes>96000) break;
+              if(3*(bytes+t.bytes)+4096>16*1024*1024) fail('E_CAPTURE','single captured turn exceeds bounded transport; input retained at source, manual intervention required');
+              window.push(t);bytes+=t.bytes;
+            }
+            const until=window.at(-1).id;
+            const read=['recall','--thread',session.thread,'--until',until,'--limit',String(window.length),'--json'];
+            if(after) read.push('--after',after);
+            const full=oats(read,source.context,{native:true,timeout:remainingTime()});
+            if(!Array.isArray(full.turns) || full.turns.length!==window.length || full.remaining!==0) fail('E_CAPTURE','planned record window changed; retain source and retry');
+            const turns=full.turns.map((t,i)=>{
+              const turn={id:t.id,ts:t.ts,thread:t.thread,kind:t.kind,source:t.source,text:t.text};
+              if(['id','ts','thread','kind','source'].some(k=>turn[k]!==window[i][k]) || !Array.isArray(turn.text) || turn.text.some(p=>typeof p.role!=='string' || typeof p.text!=='string')) fail('E_CAPTURE','unsupported or changed captured session record');
+              if(Buffer.byteLength(JSON.stringify(turn))>1024*1024) fail('E_CAPTURE','single captured turn exceeds 1MiB; input retained at source, manual intervention required');
+              return turn;
+            });
+            // Commit evidence before its cursor; failures retain earlier windows.
+            enqueue(source,status,{version:1,kind:'record',thread:session.thread,after,until,turns});
+            after=until;status.captured.threads[session.thread]=after;saveCapture(source,status);
+            offset+=window.length;
+          }
+          if(plan.remaining===0 && after!==session.lastTurnId) fail('E_CAPTURE','final record boundary missing');
+        }
+      }
+      status.lastCapture={status:report.status,complete:report.complete===true,ignored:report.ignored||0,at:new Date().toISOString()};
+      if(report.complete!==true) fail('E_CAPTURE',`capture ${report.status || 'uncertified'}: retain source and retry`);
+      if(final) {status.retired=true;status.auto=status.auto && !noLaunch;status.retiredAt=new Date().toISOString();}
+      saveCapture(source,status);return {...status.lastCapture,inputs:status.captured.inputs.length};
+    } catch(e) {
+      status.lastCapture={status:'incomplete',complete:false,error:e.message,at:new Date().toISOString()}; saveCapture(source,status);throw e;
+    }
+  });
+}
+export function scheduleSource(source) {
+  const spec={id:`okf-${source.id}`,kind:'command',enabled:loadStatus(source).auto,cron:source.bindings.cron,tz:source.bindings.tz,cwd:source.context,argv:['oats','okf','run-source','--source',source.file,'--soul',source.agent,'--json']};
+  const file=join(dirname(source.file),'schedule.json');
+  try {
+    save(file,spec);
+    let result;
+    try {result=oats(['schedule','add',spec.id,'--file',file,'--dir',source.context,'--json'],source.context);}
+    catch(e) {
+      // Never overwrite a colliding job or re-enable an operator-disabled job.
+      // Retry after an uncertain add must verify the actual definition, not a
+      // local receipt. A deleted definition is recreated by the add above.
+      if(e.code!=='E_SCHEDULE_EXISTS') throw e;
+      result=oats(['schedule','show',spec.id,'--dir',source.context,'--json'],source.context);
+    }
+    const actual=result?.schedule;
+    if(!actual || typeof actual.enabled!=='boolean' || ['id','kind','cron','tz','cwd','argv'].some(k=>JSON.stringify(actual[k])!==JSON.stringify(spec[k]))) fail('E_SCHEDULE','source schedule definition differs; inspect and repair explicitly');
+    updateStatus(source,status=>{status.schedule={id:spec.id,status:'ready',result};});return result;
+  } catch(e) {
+    updateStatus(source,status=>{status.schedule={...(status.schedule || {}),id:spec.id,status:'failed',error:e.message};});throw e;
+  }
+}

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

@@ -0,0 +1,331 @@
+import { createHash } from 'node:crypto';
+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 { metadata, noGit } from './config.mjs';
+const validator = fileURLToPath(new URL('../skills/okf/scripts/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.
+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)});
+export const baseLock = b => `${b.path}.okf-lock`;
+export const journalPath = b => `${b.path}.okf-publication.json`;
+export function validateBase(root, base) {
+  const files=tree(root,{git:base.kind==='git' && base.root==='.'}); const meta=metadata(files,base);
+  const result=JSON.parse(exec(process.execPath,[validator,root,'--strict','--json'],{acceptedStatus:[0,1]}));
+  if(result.errors.length || result.warnings.length) fail('E_VALIDATION', [...result.errors,...result.warnings].join('; '));
+  return {files,meta,digest:digest(files)};
+}
+function clone(base, dest) {
+  safePath(dest);
+  if(fs.existsSync(dest)) fail('E_PATH',`staging destination exists: ${dest}`);
+  fs.mkdirSync(dirname(dest),{recursive:true});
+  git(dirname(dest),['clone','--no-hardlinks','--no-checkout','--',base.repository,dest]);
+  git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+  const head=git(dest,['rev-parse','FETCH_HEAD']);
+  git(dest,['checkout','--detach',head]);
+  // Reject a linked bundle even if Git happily checked the link out.
+  safePath(join(dest,base.root));
+  return head;
+}
+export function stageBase(base, dest) {
+  safePath(dest);
+  if(fs.existsSync(dest)) fail('E_PATH',`staging destination exists: ${dest}`);
+  const acceptedPath=base.kind==='directory'?base.path:(base.repository.startsWith('/')?resolve(base.repository,base.root):null);
+  if(acceptedPath && overlaps(acceptedPath,dest)) fail('E_PATH','stage overlaps accepted base');
+  if(base.kind==='git') {
+    const head=clone(base,dest); const root=join(dest,base.root);
+    const validated=validateBase(root,base);
+    verifyPublicationTree(base,dest,head,head,validated.files);
+    return { ...validated, head, root, checkout:dest };
+  }
+  noGit(base.path);
+  return withLock(baseLock(base),()=>{
+    if(fs.existsSync(journalPath(base))) fail('E_RECOVERY',`publication pending: ${journalPath(base)}; retry its recorded run before reading`);
+    const result=validateBase(base.path,base); materialize(dest,result.files);
+    return {...result,root:dest};
+  });
+}
+export function allowedChanges(before, after, meta, owned) {
+  const changed=[...new Set([...Object.keys(before),...Object.keys(after)])].filter(p=>before[p]!==after[p]);
+  if(changed.includes('okf-base.json')) fail('E_OWNER','harvest cannot change base identity/ownership');
+  const paths=owned.map(n=>meta.nodes[n]?.path || fail('E_OWNER',`unknown owned node ${n}`));
+  for(const p of changed) if(!['index.md','log.md'].includes(p) && !paths.some(n=>p.startsWith(n+'/'))) fail('E_OWNER',`unauthorized touched path: ${p}`);
+  // Base navigation can only gain/remove listings for this worker's nodes.
+  if(changed.includes('index.md')) {
+    const filter=value=>Buffer.from(value || '', 'base64').toString().split('\n').filter(l=>!paths.some(p=>l.includes(`](${p}/`) || l.includes(`](/${p}/`))).join('\n');
+    if(filter(before['index.md'])!==filter(after['index.md'])) fail('E_OWNER','base index edits must be navigation for owned nodes only');
+  }
+  if(changed.includes('log.md')) {
+    const old=Buffer.from(before['log.md']||'','base64').toString();
+    const next=Buffer.from(after['log.md']||'','base64').toString();
+    if(!next.includes(old)) fail('E_OWNER','base log is append/prepend-only, preserve history bytes');
+  }
+  return changed;
+}
+export function verifyGitScope(base, dest, baseline, { checkModes = true } = {}) {
+  const names=git(dest,['diff','--name-only','-z',baseline,'--']).split('\0').filter(Boolean);
+  // A restored working file can conceal a staged, unauthorized index entry.
+  names.push(...git(dest,['diff','--cached','--name-only','-z',baseline,'--']).split('\0').filter(Boolean));
+  names.push(...git(dest,['ls-files','--others','--exclude-standard','-z']).split('\0').filter(Boolean));
+  if(base.root!=='.' && names.some(p=>!p.startsWith(base.root+'/'))) fail('E_OWNER','Git worker touched files outside its knowledge base');
+  // --others without exclude-standard includes ignored additions as well.
+  // Unchanged code symlinks outside the base are not knowledge and need not be
+  // traversed. Bundle symlinks are rejected by validateBase/tree.
+  const extra=git(dest,['ls-files','--others','-z']).split('\0').filter(Boolean);
+  if(base.root!=='.' && extra.some(p=>!p.startsWith(base.root+'/'))) fail('E_OWNER','untracked/ignored file outside knowledge');
+  if(checkModes) {
+    // Harvest judgments authorize content, not executable-bit edits. Inspect
+    // the filesystem against frozen objects, not core.fileMode or index flags.
+    for(const [p,entry] of gitTreeEntries(dest,baseline)) {
+      if(!['100644','100755'].includes(entry.mode)) continue;
+      const path=join(dest,p);
+      let stat;try {stat=fs.lstatSync(path);} catch(e) {if(e.code==='ENOENT' || e.code==='ENOTDIR') continue;throw e;}
+      if(stat.isFile() && (stat.mode & 0o100 ? '100755':'100644')!==entry.mode) fail('E_OWNER',`harvest cannot change Git file mode: ${p}`);
+    }
+  }
+  verifyRemote(base,dest);
+}
+// Caller MUST hold the cooperative base lock. Intent is durable before journal
+// installation; publishing is durable AFTER it and BEFORE the first accepted
+// write. The journal is removed only after a durable accepted receipt. Thus an
+// absent journal can cancel an intent, but never a write-authorized publication.
+export function reconcileDirectoryIntent(base, receipt, persist) {
+  if(fs.existsSync(journalPath(base))) return;
+  if(receipt.status==='publication-intent') {
+    receipt.status='validated'; persist();
+  } else if(!['validated','staged','accepted','no-change'].includes(receipt.status)) {
+    fail('E_RECOVERY','directory publication journal missing after writes were authorized; inspect and restore custody before retrying or rejudging');
+  }
+}
+export function directoryPublish(base, proposal, receipt, persist, { afterWrite } = {}) {
+  noGit(base.path);
+  return withLock(baseLock(base),()=>{
+    const jp=journalPath(base);
+    reconcileDirectoryIntent(base,receipt,persist);
+    if(receipt.status==='accepted' && !fs.existsSync(jp)) return receipt;
+    const changed=[...new Set([...Object.keys(proposal.before),...Object.keys(proposal.after)])].filter(p=>proposal.before[p]!==proposal.after[p]);
+    // A mount boundary cannot support our cross-directory atomic rename.
+    // Detect it BEFORE journal intent or any deletion/replacement, rather than
+    // leaving a partially applied publication that can only fail with EXDEV.
+    const device=fs.statSync(baseLock(base)).dev;
+    for(const p of changed.filter(p=>proposal.after[p]!==undefined)) {
+      let parent=dirname(safePath(join(base.path,relPath(p))));
+      while(!fs.existsSync(parent)) parent=dirname(parent);
+      if(fs.statSync(parent).dev!==device) fail('E_PATH','directory publication targets and sibling lock must share a filesystem');
+    }
+    let journal;
+    if(fs.existsSync(jp)) {
+      journal=readJSON(jp);
+      if(journal.run!==proposal.run || journal.proposalHash!==hash(proposal)) fail('E_RECOVERY',`another publication must recover first: ${jp}`);
+    } else {
+      const current=validateBase(base.path,base);
+      if(current.digest!==digest(proposal.before)) fail('E_BASELINE','directory base changed; retain evidence and rejudge on a fresh run');
+      journal={version:1,run:proposal.run,proposalHash:hash(proposal),proposalFile:proposal.file,status:'publishing'};
+      receipt.status='publication-intent'; persist();
+      atomic(jp,JSON.stringify(journal,null,2)+'\n',{tempDir:baseLock(base)});
+    }
+    if(receipt.status==='accepted') {
+      // A death after receipt persistence needs only journal cleanup, never
+      // another accepted write (nor a replay over unexpected newer bytes).
+      const final=validateBase(base.path,base);
+      if(final.digest!==digest(proposal.after) || receipt.acceptedDigest!==final.digest) fail('E_CONFIRM','accepted directory receipt differs from journalled bytes');
+      fs.rmSync(jp); syncParent(jp); return receipt;
+    }
+    const current=tree(base.path);
+    for(const p of new Set([...Object.keys(current),...Object.keys(proposal.before),...Object.keys(proposal.after)])) {
+      if(current[p]!==proposal.before[p] && current[p]!==proposal.after[p]) fail('E_BASELINE',`unexpected bytes during publication recovery: ${p}`);
+      if(!changed.includes(p) && current[p]!==proposal.before[p]) fail('E_BASELINE',`unchanged file differs: ${p}`);
+    }
+    receipt.status='publishing'; persist();
+    let count=0;
+    for(const p of changed) {
+      const target=safePath(join(base.path,relPath(p)));
+      // A previous death may follow rename/unlink but precede its directory
+      // fsync. Confirm that metadata without replacing accepted bytes again.
+      if(current[p]===proposal.after[p]) {syncParent(target);continue;}
+      if(proposal.after[p]===undefined) { fs.rmSync(target,{force:true}); syncParent(target); }
+      // The lock owns scratch files as well as owner.json. A dead-owner unlock
+      // removes incomplete scratch; it never leaves temp files in the bundle.
+      else atomic(target,Buffer.from(proposal.after[p],'base64'),{tempDir:baseLock(base)});
+      afterWrite?.(++count); // fault injection is programmatic tests only, never an environment switch
+    }
+    const final=validateBase(base.path,base);
+    if(final.digest!==digest(proposal.after)) fail('E_CONFIRM','directory publication confirmation differs');
+    receipt.status='accepted'; receipt.acceptedDigest=final.digest; receipt.acceptedAt=new Date().toISOString(); persist();
+    fs.rmSync(jp); syncParent(jp);
+    return receipt;
+  });
+}
+function syncParent(p) { const fd=fs.openSync(dirname(p),'r'); try {fs.fsyncSync(fd);} finally {fs.closeSync(fd);} }
+function prRows(base,branch,cwd,{identity,allBases=false}={}) {
+  const fields='number,url,state,headRefOid,baseRefName,headRefName,mergedAt,mergeCommit';
+  // Once observed, a PR is addressed by repository + number, never a mutable
+  // head/base filter. A missing/inaccessible identity is an error, not absence.
+  if(identity) {
+    if(!Number.isInteger(identity.number) || identity.number<1 || !/^https:\/\//.test(identity.url)) fail('E_RECOVERY','invalid recorded PR identity');
+    const pr=JSON.parse(exec('gh',['pr','view',String(identity.number),'--repo',base.pr.repository,'--json',fields],{cwd,env:gitEnv()}));
+    if(!pr || Array.isArray(pr) || typeof pr!=='object') fail('E_RECOVERY','known PR missing; reconcile custody before rejudging');
+    return [pr];
+  }
+  const raw=exec('gh',['pr','list','--repo',base.pr.repository,'--head',branch,...(allBases?[]:['--base',base.acceptedBranch]),'--state','all','--json',fields],{cwd,env:gitEnv()});
+  const rows=JSON.parse(raw); if(!Array.isArray(rows)) fail('E_PR','invalid gh PR list'); return rows;
+}
+function verifyRemote(base,cwd) {
+  for(const mode of [[],['--push']]) {
+    const urls=git(cwd,['remote','get-url',...mode,'--all','origin']).split('\n');
+    if(!urls.length || urls.some(url=>url!==base.repository)) fail('E_OWNER','worker changed frozen Git publication remote or effective push destination');
+  }
+}
+function changedPaths(before,after) {
+  return [...new Set([...Object.keys(before),...Object.keys(after)])].filter(p=>before[p]!==after[p]);
+}
+function gitTreeEntries(cwd,treeId) {
+  return new Map(git(cwd,['ls-tree','-r','-z',treeId]).split('\0').filter(Boolean).map(entry=>{
+    const tab=entry.indexOf('\t'),[mode,type,oid]=entry.slice(0,tab).split(' ');
+    return [entry.slice(tab+1),{mode,type,oid}];
+  }));
+}
+// Verify the REAL tree, not Git's working-tree view. Blob hashes include the
+// exact bytes (no text trimming); Git filters/attributes and ignores cannot
+// substitute something different from the validated proposal. Modes come only
+// from the frozen baseline (new files are non-executable), never worker state.
+function verifyPublicationTree(base,cwd,baseline,treeId,after,before=after) {
+  const names=git(cwd,['diff-tree','--no-commit-id','--no-renames','--name-only','-r','-z',baseline,treeId,'--']).split('\0').filter(Boolean);
+  if(base.root!=='.' && names.some(p=>!p.startsWith(base.root+'/'))) fail('E_OWNER','publication tree changes files outside its knowledge base');
+  const format=git(cwd,['rev-parse','--show-object-format']);
+  const prefix=base.root==='.'?'':base.root+'/';
+  const changed=new Set(changedPaths(before,after).map(p=>prefix+p));
+  if(names.some(p=>!changed.has(p))) fail('E_OWNER','publication tree changes paths outside the validated content changes');
+  const baselineEntries=gitTreeEntries(cwd,baseline);
+  const found=new Set();
+  for(const [path,{mode,type,oid}] of gitTreeEntries(cwd,treeId)) {
+    if(!path.startsWith(prefix)) continue;
+    const p=path.slice(prefix.length);
+    if(!Object.hasOwn(after,p) || type!=='blob' || !['100644','100755'].includes(mode)) fail('E_CONFIRM',`publication tree differs from validated proposal: ${p}`);
+    if(mode!==(baselineEntries.get(path)?.mode || '100644')) fail('E_OWNER',`publication tree changes frozen Git file mode: ${p}`);
+    const bytes=Buffer.from(after[p],'base64');
+    const expected=createHash(format).update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+    if(oid!==expected) fail('E_CONFIRM',`publication tree bytes differ from validated proposal: ${p}`);
+    found.add(p);
+  }
+  if(found.size!==Object.keys(after).length) fail('E_CONFIRM','publication tree omits validated proposal files (check Git ignores/attributes)');
+}
+function immutableCommit(cwd,oid) {
+  if(typeof oid!=='string' || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(oid)) fail('E_CONFIRM','publication requires an immutable full commit OID');
+  if(git(cwd,['cat-file','-t',oid])!=='commit') fail('E_CONFIRM','publication OID must identify a commit object, not a peelable tag');
+  // Read object headers, not revision history (which can honor grafts).
+  const header=git(cwd,['cat-file','commit',oid]).split('\n\n')[0].split('\n');
+  return {tree:header.find(l=>l.startsWith('tree '))?.slice(5),parents:header.filter(l=>l.startsWith('parent ')).map(l=>l.slice(7))};
+}
+export function gitPublish(base, stage, proposal, receipt, persist, {beforePublish=()=>{},prIdentity=receipt.pr}={}) {
+  const cwd=stage.checkout, branch=`okf/${proposal.attempt || proposal.run}-${base.id}`;
+  verifyRemote(base,cwd);
+  const baseline=immutableCommit(cwd,stage.head);
+  verifyPublicationTree(base,cwd,baseline.tree,baseline.tree,proposal.before);
+  // Baseline must still be accepted. Never rebase model output without rejudging it.
+  git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+  const accepted=git(cwd,['rev-parse','FETCH_HEAD']);
+  if(accepted!==stage.head) {
+    // A known or uncertain previously created PR may be reconciled, but a
+    // committed/pushed proposal alone does not authorize a NEW stale-base PR.
+    const prior=receipt.commit?prRows(base,branch,cwd,{identity:prIdentity}).filter(p=>p.headRefOid===receipt.commit && p.headRefName===branch && p.baseRefName===base.acceptedBranch):[];
+    if(prior.length!==1) fail('E_BASELINE','accepted Git head changed before verified PR delivery; explicit rejudgment required');
+  }
+  if(!receipt.commit) {
+    // Publication consumes a frozen content proposal, also on migration/retry
+    // where materialization may have reset filesystem permissions. Its modes
+    // are reconstructed below, not authorized by the mutable worktree.
+    verifyGitScope(base,cwd,stage.head,{checkModes:false});
+    if(digest(tree(stage.root,{git:base.root==='.'}))!==digest(proposal.after)) fail('E_BASELINE','staged proposal changed after validation');
+    beforePublish();
+    receipt.status='commit-intent'; receipt.branch=branch; persist();
+    // Never trust the model's index. Start a private publication index from
+    // the frozen accepted commit, and leave the worker's own index intact.
+    const scratch=fs.mkdtempSync(join(dirname(proposal.file),'git-index-'));
+    let treeId;
+    try {
+      const env={...cleanEnv(),GIT_INDEX_FILE:join(scratch,'index')};
+      git(cwd,['read-tree',baseline.tree],{env});
+      const prefix=base.root==='.'?'':base.root+'/';
+      const entries=gitTreeEntries(cwd,baseline.tree);
+      // Recompute the delta from validated bytes, never trust proposal.changed
+      // or stage an entire directory (which also collects mode-only edits).
+      for(const p of changedPaths(proposal.before,proposal.after)) {
+        const path=prefix+relPath(p);
+        // An ignored addition can exit 1. The exact tree check below must still
+        // reject its omission; no ignore/filter failure becomes a partial PR.
+        git(cwd,['--literal-pathspecs','add','--all','--chmod=-x','--',path],{env,acceptedStatus:[0,1]});
+        if(Object.hasOwn(proposal.after,p) && entries.get(path)?.mode==='100755') git(cwd,['--literal-pathspecs','update-index','--chmod=+x','--',path],{env});
+      }
+      treeId=git(cwd,['write-tree'],{env});
+      verifyPublicationTree(base,cwd,baseline.tree,treeId,proposal.after,proposal.before);
+    } finally {fs.rmSync(scratch,{recursive:true,force:true});}
+    // Deterministic commit-tree permits replay after process death between the
+    // real Git write and receipt persistence; no guessed commit or fake repository.
+    const stamp=proposal.created;
+    const env={...cleanEnv(),GIT_AUTHOR_NAME:'OKF harvest',GIT_AUTHOR_EMAIL:'okf@localhost',GIT_COMMITTER_NAME:'OKF harvest',GIT_COMMITTER_EMAIL:'okf@localhost',GIT_AUTHOR_DATE:stamp,GIT_COMMITTER_DATE:stamp};
+    receipt.commit=git(cwd,['commit-tree',treeId,'-p',stage.head,'-m',`memory-harvest: ${proposal.run}`],{env});
+    receipt.status='committed'; persist();
+  }
+  const publication=immutableCommit(cwd,receipt.commit);
+  if(publication.parents.length!==1 || publication.parents[0]!==stage.head) fail('E_CONFIRM','publication commit must have exactly the frozen baseline as its parent');
+  verifyPublicationTree(base,cwd,baseline.tree,publication.tree,proposal.after,proposal.before);
+  const remoteTip=()=>git(cwd,['ls-remote','--heads','origin',`refs/heads/${branch}`]).split(/\s/)[0] || null;
+  let tip=remoteTip();
+  if(tip && tip!==receipt.commit) fail('E_PR','publication branch has unexpected commit; never force push');
+  if(tip!==receipt.commit) {
+    beforePublish();
+    receipt.status='push-intent'; persist();
+    try { verifyRemote(base,cwd);git(cwd,['push','--no-follow-tags','--recurse-submodules=no','origin',`${receipt.commit}:refs/heads/${branch}`]); }
+    catch(e) { receipt.status='push-unknown'; receipt.error=e.message; persist(); throw e; }
+    tip=remoteTip(); if(tip!==receipt.commit) {receipt.status='push-unknown';persist();fail('E_CONFIRM','pushed head not confirmed');}
+  }
+  receipt.status='pushed'; persist();
+  let rows;
+  try {rows=prRows(base,branch,cwd,{identity:prIdentity});} catch(e) {receipt.status='pr-unknown';receipt.error=e.message;persist();throw e;}
+  if(!rows.length) {
+    beforePublish();
+    receipt.status='pr-intent'; persist();
+    try { exec('gh',['pr','create','--repo',base.pr.repository,'--head',branch,'--base',base.acceptedBranch,'--title',`memory-harvest: ${proposal.run}`,'--body',`Knowledge-only proposal from durable OKF input ${proposal.run}. Review provenance and promotion judgment.`],{cwd,env:gitEnv()}); }
+    catch(e) {receipt.status='pr-unknown';receipt.error=e.message;persist();throw e;}
+    rows=prRows(base,branch,cwd);
+  }
+  const matching=rows.filter(p=>p.headRefOid===receipt.commit && p.headRefName===branch && p.baseRefName===base.acceptedBranch && Number.isInteger(p.number) && /^https:\/\//.test(p.url) && (!prIdentity || (p.number===prIdentity.number && p.url===prIdentity.url)));
+  if(matching.length!==1 || rows.length!==1) {receipt.status='pr-unknown';persist();fail('E_PR','actual PR identity/head/base could not be uniquely verified');}
+  const pr=matching[0];receipt.pr=pr;receipt.status='delivered';receipt.deliveredAt ||= new Date().toISOString();persist();
+  if(pr.state==='CLOSED' && !pr.mergedAt) {receipt.status='rejected';persist();fail('E_PR','PR closed without merge; retained proposal requires operator review');}
+  if(pr.mergedAt) {
+    git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+    const merge=pr.mergeCommit?.oid;
+    if(!merge) fail('E_CONFIRM','merged PR lacks merge commit');
+    git(cwd,['merge-base','--is-ancestor',merge,'FETCH_HEAD']);
+    receipt.status='accepted';receipt.acceptedCommit=git(cwd,['rev-parse','FETCH_HEAD']);receipt.acceptedAt=new Date().toISOString();persist();
+  }
+  return receipt;
+}
+
+export function recoveryStage(base, stage, proposal, dest) {
+  clone(base,dest);
+  git(dest,['checkout','--detach',stage.head]);
+  const root=join(dest,base.root);
+  for(const p of Object.keys(proposal.before)) if(!(p in proposal.after)) fs.rmSync(safePath(join(root,p)),{force:true});
+  materialize(root,proposal.after);validateBase(root,base);
+  return {...stage,root,checkout:dest};
+}
+
+// Remote-read-only recovery gate. --repo makes this independent of any deleted
+// worker checkout. The caller durably saves first observations separately from
+// historical receipts, even if a later gate prevents recovery from completing.
+export function gitRecoveryState(base,receipt,cwd,{identity=receipt.pr,onObserve=()=>{}}={}) {
+  if(['accepted','no-change'].includes(receipt.status)) return 'settled';
+  if(!receipt.branch) return 'unresolved';
+  const rows=prRows(base,receipt.branch,cwd,{identity,allBases:true});
+  if(!rows.length) {
+    if(identity || ['delivered','rejected'].includes(receipt.status)) fail('E_RECOVERY','known PR missing; reconcile custody before rejudging');
+    return 'unresolved';
+  }
+  const pr=rows[0];
+  if(rows.length!==1 || pr.headRefOid!==receipt.commit || pr.headRefName!==receipt.branch || pr.baseRefName!==base.acceptedBranch || !Number.isInteger(pr.number) || pr.number<1 || !/^https:\/\//.test(pr.url) || [identity,receipt.pr].some(known=>known && (pr.number!==known.number || pr.url!==known.url)) || !['OPEN','CLOSED','MERGED'].includes(pr.state) || (pr.state==='MERGED' && !pr.mergedAt)) fail('E_RECOVERY','actual PR identity/head/base could not be uniquely verified for recovery');
+  onObserve(pr);
+  return pr.state==='CLOSED' && !pr.mergedAt?'unresolved':'settled';
+}