runlist 0.0.0 → 0.94.2

package/src/app-git.mjs

@@ -0,0 +1,180 @@
+// Read-only checkout Git operations. Commit execution has a separate feasibility gate.
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, lstat, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { authorizeManagedSource, authorizeManagedDestination } from './managed-path.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { SourceEditError } from './source-editor.mjs';
+import { localCommitSupport } from './git-commit-support.mjs';
+
+const MAX_OUTPUT=16*1024*1024, MAX_FILE=8*1024*1024, MAX_DIFF=1024*1024, MAX_LINES=20_000;
+const fail=(code,message)=>{throw new SourceEditError(code,message);};
+const decoder=new TextDecoder('utf-8',{fatal:true});
+const decode=bytes=>{try{return decoder.decode(bytes);}catch{fail('git-encoding','This Git output is not valid UTF-8. Review it with Git.');}};
+const inside=(root,file)=>{const rel=path.relative(root,file);return rel!== '..'&&!rel.startsWith(`..${path.sep}`)&&!path.isAbsolute(rel);};
+
+export function parseGitChanges(bytes) {
+  const fields=decode(bytes).split('\0'),rows=[];
+  for(let i=0;i<fields.length;i++) {
+    const field=fields[i];if(!field)continue;
+    const type=field[0];
+    if(type==='?'||type==='!'){rows.push({path:field.slice(2),xy:type==='?'?'??':'!!',kind:type==='?'?'Added':'Local only',ignored:type==='!'});continue;}
+    const parts=field.split(' '),count=type==='1'?8:type==='2'?9:type==='u'?10:0;
+    if(!count||parts.length<=count)fail('git-output','Git returned an unsupported change record.');
+    const file=parts.slice(count).join(' '),xy=parts[1],original=type==='2'?fields[++i]:null;
+    if(type==='2'&&!original)fail('git-output','Git returned an incomplete rename.');
+    const kind=type==='u'?'Conflicted':type==='2'?'Renamed':xy.includes('D')?'Deleted':xy.includes('A')?'Added':'Modified';
+    rows.push({path:file,original,xy,kind,conflict:type==='u',partial:xy[0]!=='.'&&xy[1]!=='.',staged:xy[0]!=='.',indexMode:parts[4],headMode:parts[3]});
+  }
+  return rows;
+}
+
+export function gitEnvironment() {
+  const result={};
+  for(const key of ['HOME','USER','LOGNAME','TMPDIR','USERPROFILE','USERNAME','HOMEDRIVE','HOMEPATH','APPDATA','LOCALAPPDATA','ProgramData','SystemRoot','WINDIR','TEMP','TMP','XDG_CONFIG_HOME','GNUPGHOME'])if(process.env[key])result[key]=process.env[key];
+  result.PATH=(process.env.PATH??'').split(path.delimiter).filter(value=>path.isAbsolute(value)).join(path.delimiter);
+  return {...result,LANG:'C',LC_ALL:'C',GIT_TERMINAL_PROMPT:'0',GIT_OPTIONAL_LOCKS:'0',GIT_NO_LAZY_FETCH:'1'};
+}
+
+// Fixed commands only; the renderer never chooses a binary, argument or cwd.
+function runner(config,deadline) {
+  return (args,{allow=[0],input,max=MAX_OUTPUT,configOverrides=[]}={})=>new Promise((resolve,reject)=>{
+    const remaining=deadline-Date.now();if(remaining<=0){reject(new SourceEditError('git-timeout','Git inspection timed out. Narrow the checkout or try Refresh.'));return;}
+    const child=spawn('git',['--no-optional-locks','--literal-pathspecs','-c','core.fsmonitor=false','-c','core.untrackedCache=false',...configOverrides.flatMap(v=>['-c',v]),...args],{cwd:config.repoRoot,env:gitEnvironment(),windowsHide:true,stdio:['pipe','pipe','pipe']});
+    const output=[],errors=[];let size=0,errorSize=0,failed=false;
+    const stop=(code,message)=>{if(failed)return;failed=true;child.kill('SIGKILL');reject(new SourceEditError(code,message));};
+    const timer=setTimeout(()=>stop('git-timeout','Git inspection timed out. Try Refresh.'),remaining);
+    child.on('error',error=>{clearTimeout(timer);stop(error.code==='ENOENT'?'git-missing':'git-unavailable','Git is unavailable. Document editing is still available.');});
+    child.stdout.on('data',chunk=>{size+=chunk.length;if(size>max)stop('git-limit','Git output exceeds the review limit. Review this checkout with Git.');else output.push(chunk);});
+    child.stderr.on('data',chunk=>{errorSize+=chunk.length;if(errorSize>64*1024)stop('git-limit','Git diagnostics exceed the review limit.');else errors.push(chunk);});
+    child.stdin.on('error',()=>{});child.stdin.end(input);
+    child.on('close',code=>{clearTimeout(timer);if(failed)return;if(!allow.includes(code)){reject(new SourceEditError('git-unavailable','Git could not inspect this checkout. Review its state with Git and try Refresh.'));return;}resolve({code,bytes:Buffer.concat(output),text:()=>decode(Buffer.concat(output)).trim()});});
+  });
+}
+
+export function createAppGit({config,actor,authenticate,library}) {
+  let active=0;
+  function identity(req) {const user=authenticate(req);if(user?.kind!=='human'||user.id!==actor.id)fail('forbidden','Git inspection belongs to the authenticated checkout owner.');}
+  function scope(input,{disk=true}={}) {
+    if(typeof input!=='string'||!input||input.includes('\0')||input.includes('\\')||path.posix.isAbsolute(input)||path.posix.normalize(input)!==input||input.split('/').includes('..'))fail('forbidden','Choose a document in this checkout.');
+    const file=path.resolve(config.repoRoot,input),parts=input.split('/');
+    if(!input.endsWith('.md')||!inside(config.repoRoot,file)||file===config.indexPath||parts.some(p=>['.git','.runlist','.dotmd','prompts','drafts','receipts','before-images','credentials'].includes(p)||config.excludeDirs?.has(p)))fail('forbidden','Private or excluded files are unavailable in Changes.');
+    const roots=(config.docsRoots??[config.docsRoot]).filter(root=>inside(root,file)).sort((a,b)=>b.length-a.length);
+    if(!roots.length)fail('forbidden','Choose a document in a configured document root.');
+    const scoped={...config,docsRoots:[roots[0]],docsRoot:roots[0]};
+    // Destination authorization also checks existing ancestors for deleted paths.
+    try{if(disk)authorizeManagedDestination(file,scoped);}catch{fail('forbidden','This document escapes its configured root.');}
+    return {file,scoped};
+  }
+  async function saved(input) {
+    const {file,scoped}=scope(input);let stamp;
+    try{stamp=await lstat(file);}catch(error){if(error.code==='ENOENT')return null;throw error;}
+    if(stamp.isSymbolicLink()||!stamp.isFile())fail('forbidden','Symlinks and non-document files are unavailable in Changes.');
+    try{authorizeManagedSource(file,scoped);}catch{fail('forbidden','This document escapes its configured root.');}
+    if(stamp.size>MAX_FILE)fail('git-file-limit','This file exceeds the 8 MiB review limit.');
+    const fd=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW??0));
+    try{const opened=await fd.stat();if(opened.dev!==stamp.dev||opened.ino!==stamp.ino||opened.size>MAX_FILE)fail('git-review-changed','The file changed. Refresh Changes.');const bytes=Buffer.alloc(opened.size+1);const {bytesRead}=await fd.read(bytes,0,bytes.length,0);const after=await fd.stat();if(bytesRead!==opened.size||after.size!==opened.size||after.mtimeMs!==opened.mtimeMs||after.ctimeMs!==opened.ctimeMs)fail('git-review-changed','The file changed while reading. Refresh Changes.');const source=decode(bytes.subarray(0,bytesRead));if(source.includes('\0'))fail('git-binary','This document is not reviewable text.');return source;}finally{await fd.close();}
+  }
+  const privateType=source=>parseSimpleFrontmatter(extractFrontmatter(source??'').frontmatter).type==='prompt';
+  async function historical(git,head,input) {
+    scope(input);if(!head)return null;
+    const record=(await git(['ls-tree','-z',head,'--',input])).bytes;
+    if(!record.length)return null;
+    const entry=decode(record).split('\0')[0],match=entry.match(/^(100644|100755) blob ([a-f0-9]{40,64})\t/);
+    if(!match)fail('forbidden','Symlinks and submodules are unavailable in Changes.');
+    const length=Number((await git(['cat-file','-s',match[2]])).text());if(length>MAX_FILE)fail('git-file-limit','This historical file exceeds the review limit.');
+    const source=decode((await git(['cat-file','blob',match[2]],{max:MAX_FILE})).bytes);
+    if(source.includes('\0'))fail('git-binary','This document is not reviewable text.');if(privateType(source))fail('forbidden','Saved prompts are unavailable in Changes.');return source;
+  }
+  async function inspect(req,git,params) {
+    identity(req);
+    const top=await git(['rev-parse','--show-toplevel'],{allow:[0,128]});
+    if(top.code!==0)return {available:false,reason:'This folder is not a Git checkout.',code:'not-git',rows:[]};
+    const [a,b]=await Promise.all([stat(await realpath(top.text())),stat(await realpath(config.repoRoot))]);
+    if(a.dev!==b.dev||a.ino!==b.ino)return {available:false,reason:'Open the Git checkout root to review its changes.',code:'git-root',rows:[]};
+    const headResult=await git(['rev-parse','--verify','HEAD'],{allow:[0,128]}),head=headResult.code===0?headResult.text():null;
+    const branchResult=await git(['symbolic-ref','--quiet','--short','HEAD'],{allow:[0,1]}),branch=branchResult.code===0?branchResult.text():null;
+    // Listing and saved-source inspection never execute clean/process drivers.
+    // Filtered candidates require the separate, explicit Git-tree commit review.
+    const filterRecords=decode((await git(['config','--null','--get-regexp','^filter.*[.](clean|process)$'],{allow:[0,1]})).bytes).split('\0');
+    const filters=new Set(filterRecords.flatMap(record=>{const at=record.indexOf('\n'),key=record.slice(0,at),value=record.slice(at+1);const name=key.match(/^filter[.](.*)[.](clean|process)$/)?.[1];return name&&value.trim()?[name]:[];}));
+    const candidates=decode((await git(['ls-files','--cached','--others','--exclude-standard','-z'])).bytes).split('\0').filter(Boolean).filter(file=>{try{scope(file,{disk:false});return true;}catch{return false;}});
+    await library.refresh(true);
+    const catalog=await library.all(),metadata=new Map(catalog.map(doc=>[doc.path,doc]));
+    const filteredCandidates=candidates;
+    const attrs=filteredCandidates.length?decode((await git(['check-attr','-z','--stdin','filter','working-tree-encoding'],{input:Buffer.from(filteredCandidates.join('\0')+'\0')})).bytes).split('\0'):[];
+    const filtered=new Set(),encoded=new Set();for(let i=0;i+2<attrs.length;i+=3){if(attrs[i+1]==='filter'&&filters.has(attrs[i+2]))filtered.add(attrs[i]);if(attrs[i+1]==='working-tree-encoding'&&!['unspecified','unset'].includes(attrs[i+2]))encoded.add(attrs[i]);}
+    // This metadata scan can over-report filtered candidates. Eligibility and
+    // exact filtered blobs are resolved by explicit private-index review.
+    const configOverrides=[...filters].flatMap(name=>[`filter.${name}.clean=`,`filter.${name}.process=`,`filter.${name}.required=false`]);
+    const raw=parseGitChanges((await git(['status','--porcelain=v2','-z','--untracked-files=all','--ignored=matching','--renames'],{configOverrides})).bytes);
+    const reported=new Set(raw.map(row=>row.path));for(const file of filtered)if(!reported.has(file))raw.push({path:file,xy:'.M',kind:'Review required',staged:false,partial:false});
+    const tracked=new Set(decode((await git(['ls-files','--cached','-z'])).bytes).split('\0'));
+    let reason=!head?'Create the first commit with Git before reviewing local commits.':!branch?'This checkout has a detached HEAD. Choose a branch with Git.':null;
+    for(const marker of ['MERGE_HEAD','CHERRY_PICK_HEAD','REVERT_HEAD','rebase-merge','rebase-apply']) {
+      const file=(await git(['rev-parse','--git-path',marker])).text();try{await lstat(path.resolve(config.repoRoot,file));reason='Finish the current merge, rebase or cherry-pick with Git first.';}catch(error){if(error.code!=='ENOENT')throw error;}
+    }
+    const unrelatedStaged=raw.filter(row=>row.staged).filter(row=>{try{scope(row.path,{disk:false});if(row.original)scope(row.original,{disk:false});return false;}catch{return true;}}).length;
+    const ignored=raw.filter(row=>row.ignored).map(row=>row.path),rows=[];
+    for(const rawRow of raw.filter(row=>!row.ignored)) {
+      try {
+        scope(rawRow.path,{disk:false});if(rawRow.original)scope(rawRow.original);
+        if(['120000','160000'].includes(rawRow.indexMode)||['120000','160000'].includes(rawRow.headMode))continue;
+        const meta=metadata.get(rawRow.path);let fm={},archived=meta?.archived??false;
+        if(!meta) {
+          // An existing file absent from the freshly authorized library is
+          // excluded or private. Only genuine deletions use historical scope.
+          const file=path.resolve(config.repoRoot,rawRow.path);
+          try{await lstat(file);continue;}catch(error){if(error.code!=='ENOENT')throw error;}
+          const old=await historical(git,head,rawRow.original??rawRow.path);
+          fm=parseSimpleFrontmatter(extractFrontmatter(old??'').frontmatter);
+          archived=fm.status==='archived'||rawRow.path.split('/').includes(path.basename(config.archiveDir??'archived'));
+        } else if(rawRow.original)await historical(git,head,rawRow.original);
+        if(archived&&params.get('archived')!=='1')continue;
+        const filterReviewRequired=filtered.has(rawRow.path)||filtered.has(rawRow.original);
+        const blocked=reason??(encoded.has(rawRow.path)?'Working-tree encoding requires Git.':rawRow.conflict?'Resolve the conflict with Git.':rawRow.partial&&!filterReviewRequired?'Staged content differs from the saved file. Whole-file selection would replace partial staging.':meta?.bytes>MAX_FILE?'Exceeds the 8 MiB review limit.':null);
+        rows.push({...meta,...rawRow,filterReviewRequired,title:String(meta?.title??fm.title??path.posix.basename(rawRow.path)).slice(0,300),archived,eligible:!blocked,blockedReason:blocked});
+      }catch(error){if(error instanceof SourceEditError&&error.code==='forbidden')continue;throw error;}
+    }
+    // Git collapses ignored directories. Expand only freshly authorized
+    // library metadata, never ignored private storage or document bodies.
+    const visible=new Set(rows.map(row=>row.path));
+    for(const doc of catalog)if(!tracked.has(doc.path)&&(params.get('archived')==='1'||!doc.archived)&&ignored.some(prefix=>doc.path===prefix||prefix.endsWith('/')&&doc.path.startsWith(prefix))&&!visible.has(doc.path)) {
+      try{scope(doc.path,{disk:false});rows.push({...doc,kind:'Local only',ignored:true,eligible:false,blockedReason:'Ignored by Git. This document stays local.'});}catch{}
+    }
+    rows.sort((a,b)=>a.path.localeCompare(b.path));
+    const finalHead=(await git(['rev-parse','--verify','HEAD'],{allow:[0,128]})).text(),finalBranch=(await git(['symbolic-ref','--quiet','--short','HEAD'],{allow:[0,1]})).text();
+    if(finalHead!==(head??'')||finalBranch!==(branch??''))fail('git-review-changed','The branch changed during inspection. Refresh Changes.');
+    const commitSupport=localCommitSupport((await git(['--version'])).text());
+    identity(req);return {available:true,reason,branch,head,unrelatedStaged,rows,commitSupport,commitEnabled:false};
+  }
+  async function operation(req,fn) {identity(req);if(active>=2)fail('git-busy','Git inspection is already running. Try again when it finishes.');active++;try{return await fn(runner(config,Date.now()+10_000));}finally{active--;}}
+  async function status(req,params=new URLSearchParams()) {return operation(req,async git=>{
+    let result;try{result=await inspect(req,git,params);}catch(error){if(!['git-missing','git-unavailable','git-limit','git-timeout'].includes(error.code))throw error;return {available:false,code:error.code,reason:error.message,changes:[],total:0,commitEnabled:false};}
+    const query=(params.get('q')??'').slice(0,500).toLowerCase(),matches=result.rows.filter(row=>`${row.title??''} ${row.path} ${row.original??''}`.toLowerCase().includes(query));
+    const limit=100,requested=Math.max(0,Math.floor(Number(params.get('offset'))||0)),offset=Math.min(requested,Math.max(0,Math.floor((matches.length-1)/limit)*limit));
+    const {rows,...info}=result;return {...info,changes:matches.slice(offset,offset+limit),total:matches.length,changedDocuments:rows.filter(r=>!r.ignored).length,localOnly:rows.filter(r=>r.ignored).length,offset,limit,hasMore:offset+limit<matches.length,commitEnabled:false};
+  });}
+  async function diff(req,params) {scope(params.get('path'));return operation(req,async git=>{
+    const result=await inspect(req,git,params);if(!result.available)fail(result.code??'git-unavailable',result.reason);
+    const row=result.rows.find(row=>row.path===params.get('path'));if(!row)fail('git-review-changed','This change is no longer available. Refresh Changes.');
+    const before=await historical(git,result.head,row.original??row.path),after=await saved(row.path);if(privateType(after))fail('forbidden','Saved prompts are unavailable in Changes.');
+    if(Buffer.byteLength(before??'')+Buffer.byteLength(after??'')>MAX_DIFF)fail('git-limit','This diff exceeds the inline review limit. Review it with Git.');
+    for(const source of [before??'',after??'']){let count=1,at=-1;while((at=source.indexOf('\n',at+1))!==-1)if(++count>MAX_LINES)fail('git-limit','This diff has too many lines for inline review. Review it with Git.');}
+    identity(req);return {change:row,branch:result.branch,head:result.head,before:before??'',after:after??'',basis:row.filterReviewRequired?'Saved Markdown against HEAD; commit review applies the clean filter':'Saved Markdown against HEAD',commitEnabled:false};
+  });}
+  async function selection(req,chosen) {return operation(req,async git=>{
+    if(!Array.isArray(chosen)||!chosen.length||chosen.length>100||new Set(chosen).size!==chosen.length)fail('invalid-request','Select between 1 and 100 distinct saved documents.');
+    const result=await inspect(req,git,new URLSearchParams({archived:'1'}));
+    if(!result.available||result.reason)fail(result.code??'git-unavailable',result.reason);
+    const rows=chosen.map(file=>{scope(file);const row=result.rows.find(row=>row.path===file);if(!row||!row.eligible)fail('git-review-changed',row?.blockedReason??'A selected document changed or is unavailable. Refresh Changes.');return row;});
+    // Read/authorize both sides now, including historical private types.
+    for(const row of rows)await historical(git,result.head,row.original??row.path);
+    const paths=[...new Set(rows.flatMap(row=>row.original?[row.path,row.original]:[row.path]))],authorizedSources={};
+    for(const file of paths){const source=await saved(file);if(privateType(source))fail('forbidden','Saved prompts are unavailable in Changes.');authorizedSources[file]=source===null?null:createHash('sha256').update(source).digest('hex');}
+    identity(req);return {paths,authorizedSources,rows,head:result.head,branch:result.branch};
+  });}
+  return {status,diff,selection};
+}

package/src/app-library.mjs

@@ -0,0 +1,152 @@
+import { open, lstat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { setImmediate as yieldThread } from 'node:timers/promises';
+import { collectDocFiles } from './index.mjs';
+import { authorizeManagedSource } from './managed-path.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { extractFirstHeading } from './extractors.mjs';
+import { isHubDoc, detectBodyRunlistRefs } from './hub.mjs';
+import { normalizeStringList } from './util.mjs';
+import { getStageDefinitions, readPlanStage, readShipsFrontmatter } from './stages.mjs';
+import { referenceValues } from './reference-values.mjs';
+
+const list = value => normalizeStringList(value).map(v=>v.slice(0,200)).slice(0,40);
+const repoPath = (file,config) => path.relative(config.repoRoot,file).split(path.sep).join('/');
+async function readHeader(fd,size) {
+  const limit=Math.min(128*1024,size),chunks=[];let length=0,source='';
+  while(length<limit){
+    const bytes=Buffer.alloc(Math.min(4096,limit-length)),{bytesRead}=await fd.read(bytes,0,bytes.length,length);
+    if(!bytesRead)break;
+    chunks.push(bytes.subarray(0,bytesRead));length+=bytesRead;
+    source=Buffer.concat(chunks,length).toString('utf8');
+    const parts=extractFrontmatter(source),complete=parts.bodyLineOffset>0||!/^---\r?\n/.test(source);
+    if(complete&&(parseSimpleFrontmatter(parts.frontmatter).title||extractFirstHeading(parts.body.slice(0,parts.body.lastIndexOf('\n')+1))))break;
+  }
+  return {source,bytesRead:length};
+}
+export function libraryKind(fm,documentPath) {
+  return isHubDoc({type:fm.type,path:documentPath,executionMode:fm.execution_mode,refFields:{runlist:list(fm.runlist)}}) ? 'hub' : fm.type==='plan' ? 'plan' : 'document';
+}
+export function matchesLibraryStage(row, stage) {
+  return !stage || row.kind==='plan' && (stage==='@unset'?row.stage===null&&!row.stageInvalid:stage==='@invalid'?row.stageInvalid:row.stage===(stage.startsWith('word:')?stage.slice(5):stage));
+}
+export function libraryStageComparator(config) {
+  const order=new Map(getStageDefinitions(config).map((stage,index)=>[stage.word,index]));
+  const rank=row=>row.stageInvalid?order.size+2:row.stage===null?order.size+1:order.get(row.stage)??order.size;
+  return (a,b)=>rank(a)-rank(b)||(rank(a)===order.size?String(a.stage).localeCompare(String(b.stage)):0);
+}
+export function sortLibraryRows(rows,params,config) {
+  const sort=params.get('sort'),compare=sort==='title'?(a,b)=>a.title.localeCompare(b.title)||a.path.localeCompare(b.path):sort==='path'?(a,b)=>a.path.localeCompare(b.path):(a,b)=>String(b.updated??'').localeCompare(String(a.updated??''))||a.path.localeCompare(b.path);
+  const stage=params.get('group')==='stage'&&params.get('kind')==='plans'?libraryStageComparator(config):()=>0;
+  return rows.sort((a,b)=>stage(a,b)||compare(a,b));
+}
+export function createDocumentLibrary(config,{refreshMs=15_000}={}) {
+  const roots=[...(config.docsRoots??[config.docsRoot])].sort((a,b)=>b.length-a.length);
+  const sourceConfig=file=>{const root=roots.find(root=>{const rel=path.relative(root,file);return rel!== '..'&&!rel.startsWith(`..${path.sep}`)&&!path.isAbsolute(rel);});return root?{repoRoot:config.repoRoot,docsRoots:[root],docsRoot:root}:config;};
+  let rows=[],byPath=new Map(),cache=new Map(),pending,pendingMode,lastScan=0,generation=0,stats={};
+  let fullDirty=true,knownFiles=new Set(),unavailable=new Set();
+  const dirty=new Set();
+  function excluded(documentPath) {return documentPath.split('/').some(p=>p==='prompts'||p==='.git'||config.excludeDirs?.has(p)) || path.resolve(config.repoRoot,documentPath)===config.indexPath;}
+  function invalidate(documentPaths) {
+    if(documentPaths===undefined){fullDirty=true;dirty.clear();return;}
+    for(const input of Array.isArray(documentPaths)?documentPaths:[documentPaths]) {
+      if(typeof input!=='string'){fullDirty=true;dirty.clear();return;}
+      const file=path.resolve(config.repoRoot,input),relative=repoPath(file,config);
+      if(!file.endsWith('.md')||excluded(relative)||!roots.some(root=>{const rel=path.relative(root,file);return rel!== '..'&&!rel.startsWith(`..${path.sep}`)&&!path.isAbsolute(rel);}))continue;
+      dirty.add(file);
+      // A burst of changes falls back to discovery instead of retaining an
+      // unbounded queue. Ordinary saves retain only their changed paths.
+      if(dirty.size>512){fullDirty=true;dirty.clear();return;}
+    }
+  }
+  async function refresh(force=false) {
+    // Join an existing full discovery. A force request during a targeted read
+    // still schedules discovery after it finishes.
+    if(force&&pendingMode!=='full')fullDirty=true;
+    for(;;) {
+      if(pending){await pending;continue;}
+      const full=fullDirty||!lastScan||Date.now()-lastScan>=refreshMs;
+      if(!full&&!dirty.size)return;
+      const changed=[...dirty];dirty.clear();
+      if(full)fullDirty=false;
+      pendingMode=full?'full':'changed';
+      pending=(async()=>{
+      const start=performance.now();let headersRead=0,headerBytesRead=0,failures=0,discoveryErrors=0;
+      const files=full?collectDocFiles(config,{onError:()=>discoveryErrors++}).filter(file=>!excluded(repoPath(file,config))):changed;
+      const next=full?new Map():new Map(cache),nextKnown=full?new Set(files):new Set(knownFiles),nextUnavailable=full?new Set():new Set(unavailable);let index=0;
+      const worker=async()=>{while(index<files.length){const file=files[index++],relative=repoPath(file,config);let fd;try{
+        const stamp=await lstat(file);if(!stamp.isFile())throw Error('Not a regular document.');
+        nextKnown.add(file);nextUnavailable.delete(file);
+        const key=`${stamp.dev}:${stamp.ino}:${stamp.size}:${stamp.mtimeMs}:${stamp.ctimeMs}`;
+        const cached=cache.get(file);if(cached?.key===key){next.set(file,cached);continue;}
+        const authorized=authorizeManagedSource(file,sourceConfig(file));fd=await open(authorized.path,constants.O_RDONLY|(constants.O_NOFOLLOW??0));
+        const same=(a,b)=>['dev','ino','size','mtimeMs','ctimeMs','mode'].every(key=>a[key]===b[key]);
+        if(!same(stamp,await fd.stat()))throw Error('Document changed while opening.');
+        const {source,bytesRead}=await readHeader(fd,stamp.size);headersRead++;headerBytesRead+=bytesRead;
+        if(!same(stamp,await fd.stat())||!same(stamp,await lstat(file)))throw Error('Document changed while reading.');
+        const parts=extractFrontmatter(source),warnings=[],fm=parseSimpleFrontmatter(parts.frontmatter,warnings);
+        let row=null;
+        if(fm.type!=='prompt') {
+          const type=typeof fm.type==='string'?fm.type.slice(0,100):'untyped';
+          row={path:relative,bytes:stamp.size,title:String((fm.record_schema==='runlist.record/v1'&&(fm.finding||fm.question))||fm.title||extractFirstHeading(parts.body)||path.basename(file,'.md')).slice(0,300),type,kind:libraryKind(fm,relative),status:String(fm.status||'unknown').slice(0,100),updated:typeof fm.updated==='string'?fm.updated:null,folder:path.posix.dirname(relative),modules:list(fm.modules),surfaces:list(fm.surfaces),parents:normalizeStringList(fm.parent_plan),archived:fm.status==='archived'||relative.split('/').includes(path.basename(config.archiveDir??'archived')),untyped:type==='untyped',metadataWarnings:warnings.length};
+        }
+        if(row?.kind==='plan'){const stage=readPlanStage(readShipsFrontmatter(parts.frontmatter));row.stage=stage.word;row.stageInvalid=stage.invalid;}
+        if(row&&fm.record_schema==='runlist.record/v1')try{const id=JSON.parse(fm.record_data).repository_id;if(/^repo:[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(id))row.recordRepositoryId=id;}catch{}
+        // Parsed headings/frontmatter can be V8 substring views into the whole
+        // 128 KiB header. Detach the small metadata record before caching it;
+        // otherwise a short title/parent can retain an entire document buffer.
+        const refFields={};
+        for(const field of [...(config.referenceFields?.bidirectional??[]),...(config.referenceFields?.unidirectional??[])])refFields[field]=referenceValues(fm[field]).paths;
+        const filing=row?{path:relative,repoPath:relative,title:row.title,type:typeof fm.type==='string'?fm.type:null,status:typeof fm.status==='string'?fm.status:null,executionMode:typeof fm.execution_mode==='string'?fm.execution_mode:null,refFields,stamp:key,metadataComplete:!warnings.length&&(!/^---\r?\n/.test(source)||parts.bodyLineOffset>0)}:null;
+        next.set(file,{key,row:row?JSON.parse(JSON.stringify(row)):null,filing:filing?JSON.parse(JSON.stringify(filing)):null});
+      }catch(error){next.delete(file);if(error.code==='ENOENT'){nextKnown.delete(file);nextUnavailable.delete(file);}else{failures++;nextUnavailable.add(file);}}finally{await fd?.close();}await yieldThread();}};
+      await Promise.all(Array.from({length:12},worker));cache=next;knownFiles=nextKnown;unavailable=nextUnavailable;rows=[...next.values()].flatMap(v=>v.row?[v.row]:[]);byPath=new Map(rows.map(r=>[r.path,r]));
+      // Targeted reads must not postpone periodic discovery of external edits.
+      if(full)lastScan=Date.now();generation++;
+      const previous=stats;
+      stats={files:knownFiles.size,checkedFiles:files.length,refreshMode:pendingMode,fullScans:(previous.fullScans??0)+(full?1:0),incrementalRefreshes:(previous.incrementalRefreshes??0)+(full?0:1),headersRead,headerBytesRead,unavailable:unavailable.size,discoveryErrors:full?discoveryErrors:(previous.discoveryErrors??0),refreshFailures:failures,elapsedMs:Math.round(performance.now()-start),indexedAt:new Date(lastScan).toISOString(),generation};
+      })().catch(error=>{fullDirty=true;throw error;}).finally(()=>{pending=null;pendingMode=null;});
+      // Invalidations received during any await stay queued for the next pass;
+      // callers never return a scan that silently consumed a newer mutation.
+      await pending;
+      if(refreshMs<=0&&!fullDirty&&!dirty.size)return;
+    }
+  }
+  function resolve(ref,from) {
+    const clean=String(ref).replace(/^>\s*/,'').split('#')[0].trim();if(!clean.endsWith('.md'))return null;
+    const candidates=[path.posix.normalize(path.posix.join(path.posix.dirname(from),clean)),path.posix.normalize(clean.replace(/^\//,''))];
+    return candidates.map(p=>byPath.get(p)).find(Boolean)??null;
+  }
+  function relations(documentPath,fm,body) {
+    const parentRefs=normalizeStringList(fm.parent_plan),members=[...new Set([...normalizeStringList(fm.runlist),...(libraryKind(fm,documentPath)==='hub'?detectBodyRunlistRefs(body):[])])];
+    const groups=[['Parent hub',parentRefs],['Hub members',members],['Related plans',normalizeStringList(fm.related_plans)],['Related documents',normalizeStringList(fm.related_docs)]];
+    const result=groups.flatMap(([label,refs])=>refs.map(ref=>({label,ref,target:resolve(ref,documentPath)})));
+    // Parent back-pointers are membership evidence, not arbitrary body links.
+    if(libraryKind(fm,documentPath)==='hub')for(const row of rows)if(row.parents.some(ref=>resolve(ref,row.path)?.path===documentPath)&&!result.some(r=>r.label==='Hub members'&&r.target?.path===row.path))result.push({label:'Hub members',ref:row.path,target:row});
+    return result.map(r=>({...r,target:r.target?{path:r.target.path,title:r.target.title,status:r.target.status,kind:r.target.kind,type:r.target.type}:null}));
+  }
+  async function query(params=new URLSearchParams()) {
+    await refresh(params.get('refresh')==='1');
+    const includeArchived=params.get('archived')==='1',scope=rows.filter(r=>includeArchived||!r.archived),kind=params.get('kind')??'all',status=params.get('status')??'',folder=params.get('folder')??'',type=params.get('type')??'',stage=params.get('stage')??'';
+    const words=(params.get('q')??'').slice(0,500).toLowerCase().trim().split(/\s+/).filter(Boolean);
+    let matches=scope.filter(r=>(kind==='all'||kind==='documents'&&r.kind==='document'||kind==='hubs'&&r.kind==='hub'||kind==='plans'&&r.kind==='plan')&&matchesLibraryStage(r,stage)&&(!status||r.status===status)&&(!type||r.type===type)&&(!folder||r.folder===folder||r.folder.startsWith(folder+'/'))&&words.every(w=>`${r.title} ${r.path} ${r.status} ${r.type} ${r.modules.join(' ')} ${r.surfaces.join(' ')}`.toLowerCase().includes(w)));
+    sortLibraryRows(matches,params,config);
+    const number=(key,fallback,max)=>{const n=Number(params.get(key)??fallback);return Number.isInteger(n)&&n>=0?Math.min(n,max):fallback;};
+    const limit=Math.max(1,number('limit',50,100)),offset=Math.min(number('offset',0,10_000_000),Math.max(0,Math.floor((matches.length-1)/limit)*limit));
+    const counts={all:scope.length,hubs:scope.filter(r=>r.kind==='hub').length,plans:scope.filter(r=>r.kind==='plan').length,documents:scope.filter(r=>r.kind==='document').length};
+    const facets=key=>{const counts=new Map();for(const r of scope)counts.set(r[key],(counts.get(r[key])??0)+1);return [...counts].sort(([a],[b])=>a.localeCompare(b)).map(([value,count])=>({value,count}));};
+    const stageDefinitions=getStageDefinitions(config),planRows=scope.filter(r=>r.kind==='plan'),stageCounts=new Map();for(const row of planRows){const value=row.stageInvalid?'@invalid':row.stage===null?'@unset':`word:${row.stage}`;stageCounts.set(value,(stageCounts.get(value)??0)+1);}
+    const configured=new Set(stageDefinitions.map(s=>`word:${s.word}`)),stages=[...stageDefinitions.map(s=>({value:`word:${s.word}`,label:s.word,meaning:s.meaning,count:stageCounts.get(`word:${s.word}`)??0})),...[...stageCounts].filter(([value])=>!configured.has(value)&&!['@unset','@invalid'].includes(value)).sort(([a],[b])=>a.localeCompare(b)).map(([value,count])=>({value,label:value.slice(5),count,unknown:true})),{value:'@unset',label:'Unset · no stage',count:stageCounts.get('@unset')??0},...(stageCounts.has('@invalid')?[{value:'@invalid',label:'Invalid metadata',count:stageCounts.get('@invalid')}]:[])];
+    return {stageDefinitions,group:params.get('group')==='stage'&&kind==='plans'?'stage':null,documents:matches.slice(offset,offset+limit),total:matches.length,inventoryTotal:rows.length,counts,offset,limit,hasMore:offset+limit<matches.length,facets:{stages,statuses:facets('status'),types:facets('type'),folders:facets('folder')},stats};
+  }
+  async function filingInventory({refresh:force=false}={}) {
+    await refresh(force);
+    const documents=[...cache.values()].flatMap(entry=>entry.filing?[structuredClone(entry.filing)]:[]);
+    const failures=[...unavailable].map(file=>({path:repoPath(file,config),message:'Document metadata could not be read safely.'}));
+    for(const doc of documents)if(!doc.metadataComplete)failures.push({path:doc.path,message:'Document reference metadata is incomplete or malformed.'});
+    if(stats.discoveryErrors)failures.push({path:'',message:'Some document roots could not be fully discovered.'});
+    return {documents,generation,complete:failures.length===0,failures};
+  }
+  return {query,refresh,filingInventory,async all(){await refresh();return rows.map(row=>({...row}));},resolve,relations,invalidate,get stats(){return stats;}};
+}

package/src/app-lifecycle-worker.mjs

@@ -0,0 +1,12 @@
+// Trusted child runner: CLI lifecycle behavior, without borrowing agent identity.
+import {resolveConfig} from './config.mjs';import {runSet} from './lifecycle.mjs';
+import {runYardstick,assertYardstickReviewGuards} from './yardstick-command.mjs';
+import {isBundledRunlistRuntime} from './desktop-runtime.mjs';
+if (isBundledRunlistRuntime(process.execPath)) process.title='RunlistLifecycle';
+process.on('message',async request=>{
+ try{if(request.kind==='yardstick')assertYardstickReviewGuards(request.guards);const config=await resolveConfig(request.repoRoot,request.configPath??undefined);const options={dryRun:request.dryRun,note:request.note,guards:request.guards??[],expectedDestination:request.expectedDestination};
+  const result=request.kind==='yardstick'?await runYardstick(request.argv,config,{...options,captureGuards:true}):await runSet([request.status,request.file],config,options);
+  process.send({ok:true,result,...(request.kind==='yardstick'?{guards:result.preparedGuards}: {})});}
+ catch(error){process.send({ok:false,code:error.code??(/changed|appeared|owned|claim/i.test(error.message)?'lifecycle-conflict':'lifecycle-failed'),message:error.message});}
+ finally{process.disconnect();}
+});

package/src/app-lifecycle.mjs

@@ -0,0 +1,79 @@
+import {fork} from 'node:child_process';import {createHash} from 'node:crypto';
+import {existsSync,readFileSync,lstatSync,mkdirSync,readdirSync,openSync,fsyncSync,closeSync} from 'node:fs';import path from 'node:path';
+import {authorizeRepoGeneratedPath,authorizeManagedDestination} from './managed-path.mjs';import {currentProcessOwner,processStartIdentity,processOwnerLiveness,inspectTransactions,withPathLocks,snapshotFile,replaceSnapshot,createFileExclusive} from './atomic-mutation.mjs';
+import {readPlanOwnership,canonicalPlanIdentity} from './pickup.mjs';import {stateDir} from './naming.mjs';import {SourceEditError,sourceRevision,assertPrivateEditorStorage} from './source-editor.mjs';
+import {containingRoot} from './path-containment.mjs';
+import {isBundledRunlistRuntime} from './desktop-runtime.mjs';
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const fail=(code,message)=>{throw new SourceEditError(code,message);};const json=value=>JSON.stringify(value,null,2)+'\n';
+const activeJobs=new Set();
+function worker(request,onStart){return new Promise((resolve,reject)=>{
+ const env={...process.env};for(const key of Object.keys(env))if(/SESSION|^CODEX_|^OPENCODE_/.test(key))delete env[key];
+ const child=fork(new URL('./app-lifecycle-worker.mjs',import.meta.url),[],{env,windowsHide:true,stdio:['ignore','pipe','pipe','ipc'],execArgv:isBundledRunlistRuntime(process.execPath)?['--max-old-space-size=256','--max-semi-space-size=4']:[]});let report='',result;
+ const timer=setTimeout(()=>{child.kill();reject(new SourceEditError('lifecycle-uncertain','The lifecycle runner timed out. Inspect its retained operation before retrying.'));},60_000);
+ const append=data=>{if(report.length<128000)report+=data;};child.stdout.on('data',append);child.stderr.on('data',append);child.on('message',value=>{result=value;});child.on('error',error=>{clearTimeout(timer);reject(error);});child.on('exit',()=>{clearTimeout(timer);if(!result)return reject(new SourceEditError('lifecycle-uncertain','The lifecycle runner stopped. Inspect its retained operation before retrying.'));if(!result.ok)return reject(new SourceEditError(result.code,result.message,{report}));resolve({result:result.result,report:report.replace(/\x1b\[[0-9;]*m/g,'')});});try{onStart?.({...currentProcessOwner(),pid:child.pid,processStartIdentity:processStartIdentity(child.pid),processStartedAt:new Date().toISOString()});child.send(request);}catch(error){child.kill();clearTimeout(timer);reject(error);}
+ });}
+export function createAppLifecycle({config,read,actor}) {
+ const directory=path.join(stateDir(config.repoRoot),'editor','lifecycle');
+ const safe=input=>{const file=authorizeRepoGeneratedPath(input,config,{kind:'Lifecycle receipt'}).path;let current=config.repoRoot;for(const part of path.relative(config.repoRoot,file).split(path.sep)){current=path.join(current,part);if(existsSync(current)&&lstatSync(current).isSymbolicLink())fail('unsafe-local-state','Lifecycle receipts may not traverse symlinks.');}return file;};
+ const location=id=>{if(!uuid.test(id??''))fail('invalid-id','A UUID v4 operation is required.');return safe(path.join(directory,`${id}.json`));};
+ function storage(){assertPrivateEditorStorage(config.repoRoot,directory);
+   const make=dir=>{safe(dir);if(existsSync(dir)){if(!lstatSync(dir).isDirectory())fail('unsafe-local-state','Receipt storage must be a directory.');return;}make(path.dirname(dir));mkdirSync(dir,{mode:0o700});let fd;try{fd=openSync(path.dirname(dir),'r');fsyncSync(fd);}catch(error){if(!['EINVAL','ENOTSUP','EPERM','EACCES','EBADF','EISDIR'].includes(error.code))throw error;}finally{if(fd!==undefined)closeSync(fd);}};make(directory);
+ }
+ function receipt(id){const file=location(id);if(!existsSync(file))return null;if(!lstatSync(file).isFile()||lstatSync(file).size>16*1024*1024)fail('state-corrupt','Inspect the lifecycle receipt before continuing.');try{const value=JSON.parse(readFileSync(file,'utf8'));if(value.id!==id||value.schema!==1||!['reviewed','running','committed','failed','settled-unknown'].includes(value.state)||typeof value.path!=='string'||typeof value.newPath!=='string'||value.file!==path.resolve(config.repoRoot,value.path)||!value.actor||!Array.isArray(value.guards)||value.guards[0]?.path!==value.file||sourceRevision(value.guards[0]?.expectedContent)!==value.expectedRevision)throw new Error('invalid');return value;}catch{fail('state-corrupt','Inspect the lifecycle receipt before continuing.');}}
+ function write(value){const file=location(value.id);if(existsSync(file))replaceSnapshot(snapshotFile(file),json(value),{repoRoot:config.repoRoot,locked:true});else createFileExclusive(file,json(value),{repoRoot:config.repoRoot,locked:true,mode:0o600});}
+ const own=(context,value)=>{const current=actor(context);if(current.kind!==value.actor.kind||current.id!==value.actor.id)fail('forbidden','This lifecycle review belongs to another actor.');};
+ function eligible(context,input){const doc=read(context,input);if(!doc.editable||['flag','decision','prompt'].includes(doc.type))fail('lifecycle-unavailable','Use this document’s domain actions or repair its source before changing lifecycle status.');if(doc.metadata?.record_schema)fail('lifecycle-unavailable','Status changes for structured plans are not available yet. You can continue editing this plan’s text; its current status and history are kept.');const ownership=readPlanOwnership(doc.path,config);if(ownership?.corrupt||ownership?.state==='owned'||doc.status==='in-session')fail('claim-conflict','This source is claimed. Coordinate or release its claim through the CLI first.');
+  if(existsSync(directory)){safe(directory);for(const name of readdirSync(directory).filter(n=>n.endsWith('.json'))){const value=receipt(name.slice(0,-5));if(value?.state==='running'&&[value.path,value.newPath].includes(doc.path))fail('lifecycle-repair-required','A lifecycle operation for this document may be interrupted. Inspect its receipt and CLI transactions before starting another change.');}}
+  const edits=safe(path.join(stateDir(config.repoRoot),'editor','operations'));if(existsSync(edits))for(const name of readdirSync(edits).filter(n=>n.endsWith('.json'))){const file=safe(path.join(edits,name));let value;try{value=JSON.parse(readFileSync(file,'utf8'));}catch{fail('state-corrupt','Inspect private editor operations before changing lifecycle status.');}if(value.state==='prepared'&&value.path===path.resolve(config.repoRoot,doc.path))fail('lifecycle-repair-required','Inspect the pending editor save before moving this source or changing its lifecycle status.');}
+  return doc;}
+ function statuses(doc){const rootLabel=path.relative(config.repoRoot,containingRoot(path.resolve(config.repoRoot,doc.path),config.docsRoots??[config.docsRoot])??config.docsRoot).split(path.sep).join('/');return [...(config.typeStatuses?.get(doc.type)??config.rootValidStatuses?.get(rootLabel)??config.validStatuses)].filter(s=>s!=='in-session');}
+ function information(context,input){const doc=read(context,input);try{eligible(context,input);return {statuses:statuses(doc),current:doc.status,enabled:true};}catch(error){return {statuses:[],current:doc.status,enabled:false,reason:error.message};}}
+ async function preview(context,request){const doc=eligible(context,request.path),who=actor(context);if(who.kind!=='human')fail('forbidden','The application lifecycle runner is human scoped.');if(!statuses(doc).includes(request.status)||request.status===doc.status)fail('invalid-status','Choose a different configured status.');if(doc.revision!==request.expectedRevision)fail('revision-conflict','The document changed. Reload it before reviewing lifecycle changes.');if(typeof request.note!=='string'||!request.note.trim()||request.note.length>4000)fail('invalid-request','Give a reason, up to 4,000 characters.');
+  const file=path.resolve(config.repoRoot,doc.path),owner=path.join(stateDir(config.repoRoot),'ownership',canonicalPlanIdentity(file,config).key+'.json');
+  const guards=[{path:file,expectedContent:doc.source},existsSync(owner)?{path:owner,expectedContent:readFileSync(owner,'utf8')}:{path:owner,absent:true}];if(config.configPath)guards.push({path:config.configPath,expectedContent:readFileSync(config.configPath,'utf8')});
+  const requestHash=createHash('sha256').update(JSON.stringify([doc.path,doc.revision,request.status,request.note,who.id])).digest('hex');
+  const note=`${request.note.trim().replace(/[\r\n]+/g,' ')} — ${who.label??who.id} (human)`;
+  const prepared=await worker({repoRoot:config.repoRoot,configPath:config.configPath,file,status:request.status,note,dryRun:true});storage();
+  return withPathLocks([location(request.operationId)],{repoRoot:config.repoRoot},()=>{const prior=receipt(request.operationId);if(prior){own(context,prior);if(prior.requestHash!==requestHash)fail('operation-reused','This ID already belongs to another lifecycle review.');return publicReview(prior);}
+   const value={schema:1,id:request.operationId,state:'reviewed',actor:who,requestHash,path:doc.path,file,status:request.status,note,guards,expectedRevision:doc.revision,report:prepared.report,newPath:prepared.result?.newRepoPath??doc.path,at:new Date().toISOString()};write(value);return publicReview(value);
+  });
+ }
+ function publicReview(value){return {operationId:value.id,path:value.path,newPath:value.newPath,status:value.status,report:value.report,state:value.state,result:value.result??null};}
+ async function commit(context,{operationId}){storage();const current=withPathLocks([location(operationId)],{repoRoot:config.repoRoot},()=>{const value=receipt(operationId);if(!value)fail('operation-missing','Review this lifecycle change first.');own(context,value);if(value.state==='committed')return value;if(value.state==='running')fail('lifecycle-repair-required','This lifecycle operation may be running or interrupted. Inspect it before starting another change.');if(value.state==='settled-unknown')fail('lifecycle-settled','This operation was acknowledged without replay. Review a new change against the current source.');if(value.state==='failed')fail(value.failure.code,value.failure.message);const doc=eligible(context,value.path);if(doc.revision!==value.expectedRevision)fail('revision-conflict','The source changed since this review. Your review is kept; reload and review it again.');value.state='running';value.parentOwner=currentProcessOwner();write(value);return value;});if(current.state==='committed')return {...publicReview(current),replayed:true};
+  const activeKey=config.repoRoot+':'+operationId;activeJobs.add(activeKey);
+  try{const outcome=await worker({repoRoot:config.repoRoot,configPath:config.configPath,file:current.file,status:current.status,note:current.note,guards:current.guards,expectedDestination:path.resolve(config.repoRoot,current.newPath),dryRun:false},owner=>withPathLocks([location(operationId)],{repoRoot:config.repoRoot},()=>{const value=receipt(operationId);value.workerOwner=owner;write(value);}));return withPathLocks([location(operationId)],{repoRoot:config.repoRoot},()=>{const value=receipt(operationId);if(value.state!=='running')fail('lifecycle-repair-required','The retained lifecycle outcome changed while the runner was finishing. Inspect it before continuing.');value.state='committed';value.result=outcome.result;value.report=outcome.report;write(value);return publicReview(value);});}
+  catch(error){withPathLocks([location(operationId)],{repoRoot:config.repoRoot},()=>{const value=receipt(operationId);value.failure={code:error.code??'lifecycle-failed',message:error.message};if(error.code!=='lifecycle-uncertain'&&existsSync(current.file)&&sourceRevision(readFileSync(current.file,'utf8'))===current.expectedRevision&&inspectTransactions(config.repoRoot).every(tx=>tx.generation==='old'&&tx.resolvable)){value.state='failed';}write(value);});throw error;}
+  finally{activeJobs.delete(activeKey);}
+ }
+ function currentDocument(context,value){const target=path.resolve(config.repoRoot,value.newPath);return existsSync(target)?read(context,value.newPath):existsSync(value.file)?read(context,value.path):null;}
+ const running=value=>activeJobs.has(config.repoRoot+':'+value.id)||(value.workerOwner?processOwnerLiveness(value.workerOwner)!=='dead':value.parentOwner&&processOwnerLiveness(value.parentOwner)!=='dead');
+ function inspect(context,{operationId}){const value=receipt(operationId);if(!value)return null;own(context,value);return {...publicReview(value),canAcknowledge:value.state==='running'&&!running(value),failure:value.failure??null,settlement:value.settlement??null,current:currentDocument(context,value)};}
+ function settle(context,{operationId,expectedRevision,note}){
+  storage();const existing=receipt(operationId);if(!existing)fail('operation-missing','There is no retained lifecycle operation.');own(context,existing);
+  return withPathLocks([location(operationId),existing.file,path.resolve(config.repoRoot,existing.newPath)],{repoRoot:config.repoRoot},()=>{
+   const value=receipt(operationId);own(context,value);if(value.state!=='running')fail('invalid-request','Only an uncertain lifecycle operation can be acknowledged.');
+   if(running(value))fail('operation-running','The lifecycle runner is still active or cannot be verified as stopped. Wait before acknowledging its outcome.');
+   if(actor(context).kind!=='human')fail('forbidden','A human must acknowledge an inspected lifecycle outcome.');
+   if(typeof note!=='string'||!note.trim()||note.length>4000)fail('invalid-request','Record what you inspected, up to 4,000 characters.');
+   if(inspectTransactions(config.repoRoot).length)fail('lifecycle-repair-required','Inspect and resolve retained CLI transactions with runlist doctor --transactions before acknowledging this operation.');
+   const current=currentDocument(context,value);if(!current||current.revision!==expectedRevision)fail('revision-conflict','The current source changed. Inspect the operation again before acknowledging it.');
+   value.state='settled-unknown';value.settlement={by:actor(context),at:new Date().toISOString(),reason:note.trim(),outcome:'unknown',current:{path:current.path,revision:current.revision,status:current.status}};write(value);
+   return {...publicReview(value),current,settlement:value.settlement};
+  });
+ }
+ function list(context){
+  safe(directory);if(!existsSync(directory))return {items:[],unavailable:0};
+  const items=[];let unavailable=0;
+  for(const name of readdirSync(directory).filter(n=>n.endsWith('.json')&&uuid.test(n.slice(0,-5))))try{
+   const value=receipt(name.slice(0,-5));if(value.actor.id!==actor(context).id||!['reviewed','running','failed'].includes(value.state))continue;own(context,value);
+   // Use the same path authorization as document opening, including exclusions.
+   authorizeManagedDestination(path.resolve(config.repoRoot,value.newPath),config);
+   let doc=null;try{doc=currentDocument(context,value);}catch{unavailable++;continue;}
+   if(!doc){unavailable++;continue;}
+   items.push({kind:'lifecycle',path:doc.path,operationId:value.id,state:value.state,at:value.at,available:true,newPath:value.newPath});
+  }catch{unavailable++;}
+  return {items,unavailable};
+ }
+ return {information,preview,commit,inspect,settle,list};
+}

package/src/app-records.mjs

@@ -0,0 +1,134 @@
+import path from 'node:path';
+import { setImmediate as yieldThread } from 'node:timers/promises';
+import { analyzeDecisionItems, blocksOf, decisionSettings, parseDecisionItems, pendingRows, dispositionOf, openWork } from './decisions.mjs';
+import { deriveFlags, flagRevision, flagsFile, readFlagEvents } from './flags.mjs';
+import { authorizeRepoGeneratedPath } from './managed-path.mjs';
+import { parseNativeRecord } from './native-record.mjs';
+import { readPlanOwnership } from './pickup.mjs';
+import { SourceEditError } from './source-editor.mjs';
+
+const nativeKey=doc=>`${doc}#native`,decisionKey=row=>`${row.doc}#${row.line}:${row.id??''}`;
+const detached=value=>JSON.parse(JSON.stringify(value));
+const escapePattern=value=>value.replace(/[.*+?^${}()|[\]\\]/g,'\\$&');
+// Match all known flag IDs in one pass per document, rather than one regex
+// scan per flag over the entire corpus. Paths retain their substring semantics.
+function flagIndexer(rows){
+  const byId=new Map(),byPath=new Map(),links=new Map();
+  for(const row of rows){
+    const key=JSON.stringify([row.id,row.path]);links.set(key,[]);
+    for(const [map,value] of [[byId,String(row.id)],[byPath,row.path]]){if(!map.has(value))map.set(value,[]);map.get(value).push(key);}
+  }
+  const patterns=[...byId].map(([id,keys])=>({id,keys,pattern:new RegExp(`(?<![A-Za-z0-9])${escapePattern(id)}(?![A-Za-z0-9])`)}));
+  const matchingKeys=new Map(patterns.map(({id})=>[id,patterns.filter(entry=>entry.pattern.test(id)).flatMap(entry=>entry.keys)]));
+  const ids=byId.size?new RegExp(`(?<![A-Za-z0-9])(?:${[...byId.keys()].sort((a,b)=>b.length-a.length).map(escapePattern).join('|')})(?![A-Za-z0-9])`,'g'):null;
+  // A zero-width lookahead also finds paths overlapping at different offsets.
+  // Same-offset prefixes are included by the longest match's containment map.
+  const files=[...byPath.keys()].filter(Boolean),paths=files.length?new RegExp(`(?=(${files.sort((a,b)=>b.length-a.length).map(escapePattern).join('|')}))`,'g'):null;
+  const pathKeys=new Map(files.map(file=>[file,files.filter(other=>file.includes(other)).flatMap(other=>byPath.get(other))]));
+  return {links,add(doc,source){
+    const keys=new Set();
+    for(const key of byPath.get('')??[])keys.add(key);
+    if(ids)for(const match of source.matchAll(ids))for(const key of matchingKeys.get(match[0]))keys.add(key);
+    if(paths)for(const match of source.matchAll(paths))for(const key of pathKeys.get(match[1]))keys.add(key);
+    for(const key of keys)links.get(key).push(doc);
+  }};
+}
+export function createRecordLibrary({config,library,readSource,evidence}) {
+  const settings=decisionSettings(config.raw?.decisions??{});
+  let documents=[],sourcePaths=[],decisions=[],flagLinks=new Map(),lastScan=0,pending,unavailable=0;
+  const flagKey=row=>JSON.stringify([row.id,row.path]);
+  const flagPattern=row=>new RegExp(`(?<![A-Za-z0-9])${String(row.id).replace(/[.*+?^${}()|[\]\\]/g,'\\$&')}(?![A-Za-z0-9])`);
+  const allowed=file=>typeof file==='string'&&!path.isAbsolute(file)&&!file.split(/[\\/]/).some(p=>p==='..'||p==='prompts'||p==='.git'||config.excludeDirs?.has(p));
+  function journal(){const file=flagsFile(config);authorizeRepoGeneratedPath(file,config,{kind:'Flag journal'});return readFlagEvents(file).filter(e=>e.event!=='add'||allowed(e.file));}
+  async function refresh(context,force=false){
+    if(pending){await pending;return refresh(context);}
+    if(!force&&lastScan&&Date.now()-lastScan<15_000)return;
+    const observedInvalidation=invalidation;
+    pending=(async()=>{
+      await library.refresh(force);const nextDocuments=await library.all(),sources=[],records=[],native=[];let nextUnavailable=0,indexer;
+      // Native summaries first, so their IDs are available to the flag index.
+      const ordered=[...nextDocuments.filter(doc=>['decision','flag'].includes(doc.type)),...nextDocuments.filter(doc=>!['decision','flag'].includes(doc.type))];
+      for(const [index,doc] of ordered.entries()){
+        const legacy=(settings.types.includes(doc.type)||doc.type==='untyped')&&!doc.archived&&(!settings.paths||[].concat(settings.paths).some(p=>doc.path===p||doc.path.startsWith(p.replace(/\/$/,'')+'/')));
+        if(!legacy&&!['decision','flag'].includes(doc.type))continue;
+        try{
+          const opened=readSource(context,doc.path);
+          if(['decision','flag'].includes(doc.type)){
+            const parsed=parseNativeRecord(opened.source),relations=parsed.record?.record_data?.relations;
+            native.push({key:parsed.record?.id??nativeKey(doc.path),native:true,kind:doc.type,id:parsed.record?.id??doc.path,title:parsed.record?.question??parsed.record?.finding??doc.title,question:parsed.record?.question??doc.title,status:parsed.record?.status==='rejected'?'closed':parsed.record?.status??doc.status,severity:parsed.record?.record_data?.severity,triage:parsed.record?.record_data?.triage?.disposition,hints:(Array.isArray(relations)?relations:[]).map(r=>r?.target?.path).filter(allowed),path:doc.path,line:1,editable:false,diagnostics:parsed.diagnostics});
+          }else{
+            indexer??=flagIndexer([...flags().filter(row=>!row.native),...native.filter(row=>row.kind==='flag')]);
+            indexer.add(doc.path,opened.source);
+            // Parse and detach this file's useful fragments before moving on.
+            // Neither sliced strings nor a corpus-sized source array survive.
+            records.push(...detached(parseDecisionItems(opened.source,settings).map(item=>({...item,doc:doc.path,docTitle:doc.title}))));
+            sources.push(detached({path:doc.path,work:openWork(opened.source)}));
+          }
+        }catch{nextUnavailable++;}
+        if(index%12===0)await yieldThread();
+      }
+      const identities=new Map();for(const row of native)identities.set(row.id,(identities.get(row.id)??0)+1);
+      for(const row of native)if(identities.get(row.id)>1){row.duplicate=true;row.key=nativeKey(row.path);}
+      const items=analyzeDecisionItems(records,settings),blocks=blocksOf(items,sources,items),byLocation=new Map(items.map(i=>[`${i.doc}:${i.line}`,i]));
+      const nextDecisions=pendingRows(items,{all:true,blocks}).map(row=>({...row,key:decisionKey(row),kind:'decision',path:row.doc,searchText:byLocation.get(`${row.doc}:${row.line}`)?.text,peers:(byLocation.get(`${row.doc}:${row.line}`)?.peers??[]).map(p=>({doc:p.doc,line:p.line,id:p.id,status:p.effective})),title:row.question||row.id,status:row.disposition??'unknown'}));
+      for(const item of items.filter(i=>!i.id))nextDecisions.push({key:decisionKey(item),kind:'decision',path:item.doc,line:item.line,id:null,title:'Unnamed decision',question:'Unnamed decision',status:item.effective??'unknown',missing:item.missing});
+      nextDecisions.push(...native.filter(row=>row.kind==='decision'));
+      const nextNativeFlags=native.filter(row=>row.kind==='flag');
+      indexer??=flagIndexer([...flags().filter(row=>!row.native),...nextNativeFlags]);
+      // Detach substring-backed record text too. Peer bodies are read on demand;
+      // the analysis graph and full documents belong only to this refresh.
+      decisions=nextDecisions.map(detached);
+      nativeFlags=nextNativeFlags.map(detached);
+      documents=nextDocuments;sourcePaths=sources.map(doc=>doc.path);flagLinks=indexer.links;unavailable=nextUnavailable;lastScan=observedInvalidation===invalidation?Date.now():0;
+    })().finally(()=>{pending=null;});await pending;if(!lastScan)return refresh(context);
+  }
+  let nativeFlags=[];
+  function flags(){return [...deriveFlags(journal()).map(flag=>({...flag,key:flag.id,kind:'flag',path:flag.file,title:flag.text,status:flag.state,revision:flagRevision(flag)})),...nativeFlags];}
+  function connections(row,context){
+    const paths=new Set([row.path,...(row.hints??[]),...(row.blocks??[]).map(b=>b.doc),...(row.peers??[]).map(p=>p.doc)]);
+    if(row.kind==='flag'){
+      const key=flagKey(row);
+      // Journal additions are visible between document refreshes. Resolve a new
+      // finding once using the same authenticated source reader, then cache paths.
+      if(!flagLinks.has(key)){
+        const pattern=flagPattern(row),matches=[];
+        for(const sourcePath of sourcePaths)try{const {source}=readSource(context,sourcePath);if(source.includes(row.path)||pattern.test(source))matches.push(sourcePath);}catch{/* Missing/unsafe sources supply no connection. */}
+        flagLinks.set(key,matches);
+      }
+      for(const sourcePath of flagLinks.get(key))paths.add(sourcePath);
+    }
+    const links=documents.filter(doc=>paths.has(doc.path));
+    for(const doc of [...links])for(const relation of library.relations(doc.path,{parent_plan:doc.parents},''))if(relation.label==='Parent hub'&&relation.target&&!links.some(l=>l.path===relation.target.path))links.push(relation.target);
+    return links.map(({path,title,type,kind,status})=>({path,title,type,kind,status}));
+  }
+  async function query(context,kind,params){
+    await refresh(context,params.get('refresh')==='1');
+    const flagRows=flags(),all=kind==='flags'?flagRows:decisions,words=(params.get('q')??'').slice(0,500).toLowerCase().trim().split(/\s+/).filter(Boolean),status=params.get('status')??'pending',severity=params.get('severity')??'',scope=params.get('scope')??'';
+    let rows=all.filter(row=>(!status||status==='pending'?(!status||['open','held'].includes(row.status)):row.status===status)&&(!severity||row.severity===severity)&&(!scope||row.path===scope||connections(row,context).some(c=>c.path===scope))&&words.every(word=>`${row.id} ${row.title} ${row.question??''} ${row.path} ${row.status} ${row.text??''} ${row.searchText??''}`.toLowerCase().includes(word)));
+    rows.sort(kind==='flags'?(a,b)=>['problem','warn','info'].indexOf(a.severity)-['problem','warn','info'].indexOf(b.severity)||String(b.at??'').localeCompare(String(a.at??'')):(a,b)=>String(a.id??'').localeCompare(String(b.id??''),'en',{numeric:true})||a.path.localeCompare(b.path));
+    const sourcePaths=new Set(all.flatMap(row=>[row.path,...(row.peers??[]).map(p=>p.doc),...(row.blocks??[]).map(b=>b.doc),...(row.hints??[])]));
+    const offset=Math.max(0,Math.min(Number(params.get('offset'))||0,Math.max(0,Math.floor((rows.length-1)/50)*50))),limit=50;
+    return {records:rows.slice(offset,offset+limit).map(row=>({key:row.key,id:row.id,title:row.title,status:row.status,severity:row.severity,triage:row.triage,path:row.path,line:row.line,native:row.native,missing:row.missing})),total:rows.length,offset,hasMore:offset+limit<rows.length,counts:{flags:flagRows.filter(f=>f.status==='open').length,decisions:decisions.filter(d=>['open','held'].includes(d.status)).length},scopes:documents.filter(d=>sourcePaths.has(d.path)||d.kind==='hub').map(d=>({path:d.path,title:d.title})),unavailable};
+  }
+  async function detail(context,kind,key){
+    await refresh(context);const row=(kind==='flags'?flags():decisions).find(row=>row.key===key);
+    if(!row)throw new SourceEditError('record-not-found','This record is unavailable. Refresh the list.');
+    const peers=kind==='decisions'&&!row.native?(row.peers??[]):[];
+    const links=connections(row,context);
+    if(row.native){const opened=readSource(context,row.path),parsed=parseNativeRecord(opened.source),claim=readPlanOwnership(row.path,config);return {...row,status:parsed.record?.status==='rejected'?'closed':parsed.record?.status??row.status,revision:opened.revision,body:parsed.body??'',data:parsed.record?.record_data,diagnostics:row.duplicate?[...parsed.diagnostics,{code:'duplicate-record-id',message:'This ID is declared in multiple documents. Reconcile their identities before recording an action.'}]:parsed.diagnostics,connections:links,editable:parsed.ok&&!row.duplicate&&!claim?.corrupt&&claim?.state!=='owned',readOnlyReason:row.duplicate?'This record ID is declared in multiple documents. Reconcile their identities first.':claim?.corrupt?'Ownership needs repair through the CLI.':claim?.state==='owned'?'This record is claimed by another session. Coordinate through the CLI first.':null};}
+    if(kind==='flags')return {...row,...evidence(row),connections:links,editable:row.state==='open'};
+    const opened=readSource(context,row.path),item=parseDecisionItems(opened.source,settings).find(i=>i.id===row.id&&i.line===row.line);
+    if(!item)throw new SourceEditError('decision-revision-conflict','This decision moved. Refresh the list to find its current record.');
+    const peerSources=new Map([[row.path,parseDecisionItems(opened.source,settings)]]);
+    const peerDetails=peers.map(peer=>{
+      if(!peerSources.has(peer.doc))peerSources.set(peer.doc,parseDecisionItems(readSource(context,peer.doc).source,settings));
+      const current=peerSources.get(peer.doc).find(item=>item.id===peer.id&&item.line===peer.line);
+      if(!current)throw new SourceEditError('decision-revision-conflict','A related decision moved. Refresh the list to find its current record.');
+      return {path:peer.doc,line:peer.line,id:peer.id,status:peer.status,body:current.text};
+    });
+    const ownership=readPlanOwnership(row.path,config),claimBlocked=ownership?.corrupt||ownership?.state==='owned';
+    return {...row,claim:ownership?{state:ownership.state,corrupt:ownership.corrupt,sessionId:ownership.sessionId}:null,readOnlyReason:claimBlocked?(ownership.corrupt?'Ownership needs repair through the CLI before recording an outcome.':`This source is owned by session ${ownership.sessionId}. Coordinate or release that claim through the CLI before recording an outcome.`):null,status:dispositionOf(item,settings)??row.status,revision:opened.revision,body:item.text,blocks:row.blocks??[],missing:row.missing??[],connections:links,peers:peerDetails,editable:opened.editable&&!!row.id&&!claimBlocked,source:opened.source};
+  }
+  let invalidation=0;
+  return {query,detail,refresh,invalidate(){invalidation++;lastScan=0;}};
+}