@6reduk/workspace-pipeline 0.5.0 → 0.7.0

package/src/desired-state/doctor.js

@@ -0,0 +1,106 @@
+import {homedir} from 'node:os';
+import {parseTOML,getStaticTOMLValue} from 'toml-eslint-parser';
+import {parse,fail,ContractError,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {readTOMLField} from '../operations/toml-fields.js';
+import {utf8} from '../source/inventory.js';
+import {readDesiredRecords,installedPath,pendingPath} from './records.js';
+import {includeRetiredTargets} from './retirement.js';
+import {inspectDesiredFiles} from './inventory.js';
+import {parseDesiredWorkspace} from './source.js';
+import {inspectDesiredLock} from './lock-recovery.js';
+
+const paths={
+  'codex.workspace':'.codex/config.toml','claude.workspace':'.claude/settings.local.json',
+  'claude.mcp':'.mcp.json','grok.workspace':'.grok/config.toml','grok.user':'.grok/config.toml'
+};
+function field(bytes,setting) {
+  if(bytes===null)return {present:false};
+  if(bytes.length>MAX_INPUT_BYTES)fail('desired.config-size');
+  if(['codex.workspace','grok.workspace'].includes(setting.target))return readTOMLField(bytes,setting.pointer);
+  let value;
+  if(setting.target==='grok.user') {
+    try{value=getStaticTOMLValue(parseTOML(utf8(bytes),{tomlVersion:'1.0'}));}catch{fail('desired.config-syntax');}
+  } else value=parse(utf8(bytes),'json');
+  for(const part of setting.pointer.slice(1).split('/')) {
+    if(value===null || typeof value!=='object' || Array.isArray(value))fail('desired.config-ancestor');
+    if(!Object.hasOwn(value,part))return {present:false};
+    value=value[part];
+  }
+  return {present:true,value};
+}
+
+// Read-only and local: no source fetch, lock, settings change, harness or MCP.
+// null routes old-format installations to the existing doctor implementation.
+export async function inspectDesiredInstallation(workspace,{userHome=homedir(),protectedPaths=[]}={}) {
+  workspace=absoluteRoot(workspace);
+  const markers=await observeTargets(workspace,[installedPath,pendingPath]);
+  if(markers.every(item=>item.bytes===null))return null;
+  const records=await readDesiredRecords(workspace),record=(records.pending??records.installed).value;
+  if(record.intent==='removed')return {workspace,ready:false,status:'not-installed',
+    pipeline:{...record.pipeline,providers:[]},binding:record.binding??null,configuration:'not-installed',
+    diagnostics:[{code:'desired.not-installed',subject:installedPath}],globalSettings:'preserved',
+    limits:'Delivery removed; saved workspace declaration and shared user settings were preserved. No runtime checks.'};
+  const diagnostics=[];
+  const locks=[];
+  for(const global of [false,...(record.settings.some(s=>s.target==='grok.user')?[true]:[])]) {
+    const target=global?'global':'workspace';
+    try {
+      const observed=await inspectDesiredLock(workspace,{userHome,global});
+      locks.push({target,path:observed.path,status:observed.status});
+      if(observed.status!=='absent')diagnostics.push({code:'desired.'+target+'-lock-present',subject:observed.path});
+    }catch(error){
+      locks.push({target,status:'unverified'});
+      diagnostics.push({code:error instanceof ContractError?error.code:'desired.lock-read',subject:target+' lock'});
+    }
+  }
+  const protectedRoots=new Set(protectedPaths);
+  if(record.binding) {
+    for(const repo of Object.values(record.binding.layout.repositories))protectedRoots.add(repo.path);
+    try {
+      const [entry]=await observeTargets(workspace,['workspace.json']);
+      if(entry.bytes===null)diagnostics.push({code:'desired.workspace-missing',subject:'workspace.json'});
+      else {
+        const descriptor=parseDesiredWorkspace(utf8(entry.bytes));
+        for(const repo of Object.values(descriptor.layout.repositories))protectedRoots.add(repo.path);
+        if(contractDigest(descriptor.pipeline)!==contractDigest(record.binding.source) ||
+            contractDigest(descriptor.layout)!==contractDigest(record.binding.layout) ||
+            (record.adapters && contractDigest([...descriptor.adapters].sort())!==contractDigest([...record.adapters].sort())))
+          diagnostics.push({code:'desired.workspace-different',subject:'workspace.json'});
+      }
+    }catch(error){
+      diagnostics.push({code:'desired.workspace-invalid',subject:'workspace.json',
+        reason:error instanceof ContractError?error.code:'desired.workspace-read'});
+    }
+  }
+  const desired={scopes:record.scopes,entries:record.files};
+  includeRetiredTargets(record,{settings:[]},desired,[...protectedRoots]);
+  const files=await inspectDesiredFiles(workspace,desired);
+  if(records.pending)diagnostics.push({code:'desired.installation-incomplete',subject:pendingPath});
+  for(const [category,items] of Object.entries(files)) {
+    if(!['extra','modified','missing','blocked'].includes(category))continue;
+    for(const item of items)diagnostics.push({code:'desired.file-'+category,subject:item.path,...(item.reason?{reason:item.reason}:{})});
+  }
+  const cache=new Map(),settings=[];
+  for(const setting of record.settings) {
+    try {
+      if(!cache.has(setting.target)) {
+        const [observed]=await observeTargets(setting.target==='grok.user'?absoluteRoot(userHome):workspace,[paths[setting.target]]);
+        cache.set(setting.target,observed.bytes);
+      }
+      const found=field(cache.get(setting.target),setting);
+      const matches=setting.operation==='remove'?!found.present:found.present && contractDigest(found.value)===setting.valueHash;
+      settings.push({target:setting.target,pointer:setting.pointer,status:matches?'pass':'different'});
+      if(!matches)diagnostics.push({code:'desired.setting-different',subject:setting.target,pointer:setting.pointer});
+    }catch(error){
+      settings.push({target:setting.target,pointer:setting.pointer,status:'unverified'});
+      diagnostics.push({code:error instanceof ContractError?error.code:'desired.config-read',subject:setting.target,pointer:setting.pointer});
+    }
+  }
+  return {workspace,ready:diagnostics.length===0,status:records.pending?'incomplete':diagnostics.length?'drift':'ready',
+    pipeline:{...record.pipeline,providers:record.providers},binding:record.binding??null,configuration:diagnostics.length?'fail':'pass',
+    diagnostics,files,settings,locks,backupDefault:false,
+    limits:'Installed-record comparison only; no source authenticity, runtime, model-visible skills or MCP certification.'};
+}

package/src/desired-state/global-settings.js

@@ -0,0 +1,74 @@
+import path from 'node:path';
+import {homedir,hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+import {mkdir,mkdtemp,writeFile,readFile,readdir,unlink,rmdir,open,rename} from 'node:fs/promises';
+import {fail} from '../contracts/parse.js';
+import {absoluteRoot,inspectDirectory} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {sha256} from '../source/inventory.js';
+import {compileDesiredSettings} from './settings.js';
+
+// userHome is a trusted host/test dependency, never a source manifest field.
+// Cooperative profile lock serializes installations from different workspaces.
+export async function acquireGlobalSettings(operations,{userHome=homedir(),workspace}={}) {
+  if(!operations.length)return null;
+  if(operations.some(op=>op.target!=='grok.user'))fail('desired.global-target');
+  // Validate scope/value declarations before creating profile metadata.
+  compileDesiredSettings('grok.user',null,operations);
+  const root=absoluteRoot(userHome);
+  if(!(await inspectDirectory(root)).exists)fail('desired.profile-missing');
+  const directory=path.join(root,'.grok'),lockDirectory=path.join(directory,'.wpc-config-lock');
+  await inspectDirectory(directory);await mkdir(directory,{recursive:true});await inspectDirectory(directory);
+  try{await mkdir(lockDirectory);}catch(e){if(e.code==='EEXIST')fail('desired.profile-busy');throw e;}
+  const token=randomUUID(),owner=Buffer.from(JSON.stringify({schemaVersion:1,token,pid:process.pid,host:hostname(),
+    createdAt:new Date().toISOString(),workspace:workspace===undefined?null:absoluteRoot(workspace),purpose:'desired-global-settings'})+'\n'),ownerPath=path.join(lockDirectory,'owner');
+  await writeFile(ownerPath,owner,{flag:'wx',mode:0o600});
+  let released=false;
+  async function held() {
+    if(released)fail('desired.profile-lock-released');
+    await inspectDirectory(lockDirectory);
+    const [observed]=await observeTargets(root,['.grok/.wpc-config-lock/owner']);
+    if(observed.bytes===null || !observed.bytes.equals(owner))fail('desired.profile-lock-changed');
+  }
+  async function release() {
+    await held();
+    const names=await readdir(lockDirectory);
+    if(names.length!==1 || names[0]!=='owner')fail('desired.profile-lock-changed');
+    await unlink(ownerPath);await rmdir(lockDirectory);released=true;
+  }
+  try {
+    const relative='.grok/config.toml',filename=path.join(directory,'config.toml');
+    const [initial]=await observeTargets(root,[relative]);
+    const edited=compileDesiredSettings('grok.user',initial.bytes,operations);
+    const beforeHash=initial.bytes===null?null:sha256(initial.bytes);
+    let backupDirectory=null;
+    async function check() {
+      await held();const [current]=await observeTargets(root,[relative]);
+      if((current.bytes===null?null:sha256(current.bytes))!==beforeHash)fail('desired.global-config-changed');
+      return current.bytes;
+    }
+    return {
+      path:filename,changed:edited.changed,release,check,
+      async backup() {
+        const bytes=await check();
+        if(!edited.changed || bytes===null)return null;
+        const parent=path.join(directory,'workspace-pipeline-backups');
+        await inspectDirectory(parent);await mkdir(parent,{recursive:true});await inspectDirectory(parent);
+        backupDirectory=await mkdtemp(path.join(parent,'desired-'));
+        const destination=path.join(backupDirectory,'config.toml');
+        await writeFile(destination,bytes,{flag:'wx',mode:0o600});
+        if(sha256(await readFile(destination))!==beforeHash)fail('desired.backup-verification');
+        return backupDirectory;
+      },
+      async apply() {
+        await check();if(!edited.changed)return;
+        const staging=beforeHash===null?filename:path.join(directory,'config.toml.wpc-'+token+'.tmp');
+        const handle=await open(staging,'wx',0o600);
+        try{await handle.writeFile(edited.bytes);await handle.sync();}finally{await handle.close();}
+        if(beforeHash!==null){await check();await rename(staging,filename);}
+        const [after]=await observeTargets(root,[relative]);
+        if(after.bytes===null || !after.bytes.equals(edited.bytes))fail('desired.global-readback');
+      }
+    };
+  } catch(error){await release();throw error;}
+}

package/src/desired-state/inventory.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {lstat,readdir,readFile} from 'node:fs/promises';
+import {fail} from '../contracts/parse.js';
+import {portablePath} from '../contracts/semantic.js';
+import {absoluteRoot,inspectDirectory,resolveChild} from '../workspace/paths.js';
+
+const hash=bytes=>'sha256:'+createHash('sha256').update(bytes).digest('hex');
+const order=(a,b)=>a.path<b.path?-1:a.path>b.path?1:0;
+const maxFiles=10000,maxBytes=64*1024*1024;
+
+// Compiled manifest and authenticated source map are supplied by the caller.
+// This function performs no writes and copies source buffers before returning.
+export function materializeDesiredFiles(compiled,source) {
+  if(!compiled || compiled.schemaVersion!==2 || !Array.isArray(compiled.files) || !(source instanceof Map))fail('desired.input');
+  const entries=new Map(),aliases=new Map();let bytes=0;
+  function add(name,kind,content) {
+    portablePath(name);
+    const key=name.toLowerCase(),old=entries.get(name);
+    if(aliases.has(key) && aliases.get(key)!==name)fail('desired.case-alias');
+    if(old){if(kind==='directory' && old.kind===kind)return;fail('desired.materialized-overlap');}
+    aliases.set(key,name);const entry={path:name,kind};
+    if(kind==='file') {
+      if(!Buffer.isBuffer(content))fail('desired.source-bytes');
+      bytes+=content.length;if(bytes>maxBytes)fail('desired.byte-limit');
+      entry.bytes=Buffer.from(content);entry.hash=hash(entry.bytes);
+    }
+    entries.set(name,entry);if(entries.size>maxFiles)fail('desired.file-limit');
+  }
+  for(const mapping of compiled.files) {
+    portablePath(mapping.source);portablePath(mapping.target);
+    if(mapping.kind==='file') {
+      if(!source.has(mapping.source))fail('desired.source-missing');
+      add(mapping.target,'file',source.get(mapping.source));
+    } else if(mapping.kind==='directory') {
+      add(mapping.target,'directory');let found=false;
+      for(const [name,content] of source) {
+        portablePath(name);if(!name.startsWith(mapping.source+'/'))continue;
+        found=true;const suffix=name.slice(mapping.source.length+1),parts=suffix.split('/');
+        for(let i=1;i<parts.length;i++)add(mapping.target+'/'+parts.slice(0,i).join('/'),'directory');
+        add(mapping.target+'/'+suffix,'file',content);
+      }
+      // Git has no empty directory entries: a missing source must not become
+      // an empty desired tree that deletes all installed contents.
+      if(!found)fail('desired.source-missing');
+    } else fail('desired.kind');
+  }
+  return {scopes:compiled.files.map(({target,kind})=>({path:target,kind})),entries:[...entries.values()].sort(order)};
+}
+
+// Read-only observation, not a lease or write authorization. Apply must hold
+// its lock and recheck safety. Only declared file scopes are traversed.
+export async function inspectDesiredFiles(workspace,desired) {
+  workspace=absoluteRoot(workspace);
+  if(!(await inspectDirectory(workspace)).exists)fail('desired.workspace-missing');
+  const actual=new Map(),blocked=[];let totalBytes=0,count=0;
+  async function visit(relative,absolute,depth=0) {
+    if(++count>maxFiles || depth>64)fail('desired.file-limit');
+    let stat;
+    try{stat=await lstat(absolute);}catch(error){if(error.code==='ENOENT')return;throw error;}
+    if(stat.isSymbolicLink()){blocked.push({path:relative,reason:'link'});return;}
+    if(stat.isDirectory()) {
+      await inspectDirectory(absolute);actual.set(relative,{path:relative,kind:'directory'});
+      const names=await readdir(absolute),seen=new Set();
+      for(const name of names.sort()) {
+        const child=relative+'/'+name,key=name.toLowerCase();
+        if(seen.has(key)){blocked.push({path:child,reason:'case-alias'});continue;}
+        seen.add(key);
+        if(key==='.git'){blocked.push({path:child,reason:'nested-repository'});continue;}
+        await visit(child,path.join(absolute,name),depth+1);
+      }
+    } else if(stat.isFile()) {
+      if(stat.nlink>1){blocked.push({path:relative,reason:'hardlink'});return;}
+      totalBytes+=stat.size;if(totalBytes>maxBytes)fail('desired.byte-limit');
+      const bytes=await readFile(absolute);
+      if(bytes.length!==stat.size)fail('desired.observation-changed');
+      actual.set(relative,{path:relative,kind:'file',hash:hash(bytes)});
+    } else blocked.push({path:relative,reason:'special-file'});
+  }
+  for(const scope of desired.scopes) {
+    const absolute=resolveChild(workspace,scope.path),parent=await inspectDirectory(path.dirname(absolute));
+    if(!parent.exists)continue;
+    const matches=(await readdir(parent.path)).filter(n=>n.toLowerCase()===path.basename(absolute).toLowerCase());
+    if(matches.length>1 || (matches.length===1 && matches[0]!==path.basename(absolute))) {
+      blocked.push({path:scope.path,reason:'case-alias'});continue;
+    }
+    await visit(scope.path,absolute);
+  }
+  const expected=new Map(desired.entries.map(e=>[e.path,e]));
+  const extra=[],modified=[],missing=[],unchanged=[];
+  for(const [name,want] of expected) {
+    const have=actual.get(name);
+    if(!have){missing.push({path:name,kind:want.kind});continue;}
+    if(have.kind!==want.kind || (want.kind==='file' && have.hash!==want.hash))
+      modified.push({path:name,kind:want.kind,currentKind:have.kind,beforeHash:have.hash??null,desiredHash:want.hash??null});
+    else unchanged.push({path:name,kind:want.kind});
+  }
+  for(const [name,have] of actual)if(!expected.has(name))extra.push(have);
+  return {extra:extra.sort(order),modified:modified.sort(order),missing:missing.sort(order),
+    unchanged:unchanged.sort(order),blocked:blocked.sort(order),ready:blocked.length===0,
+    backupDefault:false,scope:'declared-file-targets-only'};
+}

package/src/desired-state/legacy-state.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import {parse,fail} from '../contracts/parse.js';
+import {validateState} from '../contracts/semantic.js';
+import {sha256,utf8} from '../source/inventory.js';
+import {observeTargets} from '../operations/state.js';
+import {writeCheckedFile,deleteCheckedFile} from '../operations/apply.js';
+
+const configTargets={'.codex/config.toml':'codex.workspace','.claude/settings.local.json':'claude.workspace',
+  '.mcp.json':'claude.mcp','.grok/config.toml':'grok.workspace'};
+
+export function decodeLegacyState(workspace,bytes) {
+  const value=parse(utf8(bytes),'json');validateState(value);
+  if(path.resolve(value.workspace)!==path.resolve(workspace))fail('desired.legacy-workspace');
+  if(value.pending!==null || !value.active || !['ready','drift','conflict'].includes(value.status))fail('desired.legacy-unfinished');
+  const scopes=[],settings=[];
+  for(const owned of value.active.owned) {
+    if(owned.kind==='file')scopes.push({path:owned.path,kind:'file'});
+    else {
+      const target=configTargets[owned.path];
+      if(!target)fail('desired.legacy-field-target');
+      settings.push({target,pointer:owned.pointer,operation:'set',valueHash:owned.managedHash});
+    }
+  }
+  return {value,bytes,hash:sha256(bytes),protectedPaths:Object.values(value.active.layout.repositories).map(repo=>repo.path),
+    ownership:{pipeline:{id:value.active.pipelineId,version:value.active.version},scopes,settings}};
+}
+
+export async function retireLegacyState(lock,legacy) {
+  if(!legacy)return;
+  const history='.pipeline/history/state-v1-'+legacy.hash.slice(7)+'.json';
+  const [existing]=await observeTargets(lock.workspace,[history]);
+  if(existing.bytes===null)await writeCheckedFile(lock,history,null,legacy.bytes);
+  else if(sha256(existing.bytes)!==legacy.hash)fail('desired.legacy-history-conflict');
+  // Preserve the pre-existing operational record as history, not a backup of
+  // overwritten adapter files. Original journals/snapshots are not rewritten.
+  await deleteCheckedFile(lock,'.pipeline/state.json',legacy.hash,async()=>{});
+}

package/src/desired-state/local-settings.js

@@ -0,0 +1,40 @@
+import {fail} from '../contracts/parse.js';
+import {observeTargets} from '../operations/state.js';
+import {sha256} from '../source/inventory.js';
+import {compileDesiredSettings} from './settings.js';
+
+const destinations=Object.freeze({
+  'codex.workspace':'.codex/config.toml',
+  'claude.workspace':'.claude/settings.local.json',
+  'claude.mcp':'.mcp.json',
+  'grok.workspace':'.grok/config.toml'
+});
+
+// Read and compile every configuration before any adapter file is deleted.
+// Global configuration is intentionally not resolved through workspace paths.
+export async function prepareLocalSettings(workspace,settings) {
+  const groups=new Map();
+  for(const operation of settings) {
+    if(!Object.hasOwn(destinations,operation.target))fail('desired.global-settings-not-integrated');
+    if(!groups.has(operation.target))groups.set(operation.target,[]);
+    groups.get(operation.target).push(operation);
+  }
+  const observations=await observeTargets(workspace,[...groups.keys()].map(key=>destinations[key]));
+  const result=[];
+  for(const [target,operations] of groups) {
+    const relative=destinations[target],before=observations.find(o=>o.path===relative).bytes;
+    const edited=compileDesiredSettings(target,before,operations);
+    result.push({path:relative,beforeHash:before===null?null:sha256(before),
+      bytes:edited.bytes,afterHash:sha256(edited.bytes),changed:edited.changed});
+  }
+  return result;
+}
+
+export async function checkLocalSettings(workspace,prepared) {
+  const observed=await observeTargets(workspace,prepared.map(item=>item.path));
+  for(const item of prepared) {
+    const current=observed.find(o=>o.path===item.path);
+    if((current.bytes===null?null:sha256(current.bytes))!==item.beforeHash)fail('desired.config-changed');
+  }
+  return observed;
+}

package/src/desired-state/lock-recovery.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import {homedir,hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+import {readdir,rename,unlink,rmdir} from 'node:fs/promises';
+import {fail,parse} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {absoluteRoot,inspectDirectory} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {assertNoRepositoryPending} from '../operations/repository-pending.js';
+import {withRecoveryLease,assertRecoveryLeaseHeld} from '../operations/recovery-lease.js';
+import {sha256,utf8} from '../source/inventory.js';
+import {readDesiredRecords} from './records.js';
+
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+function liveness(owner) {
+  if(owner.host!==hostname())return 'unknown-host';
+  try{process.kill(owner.pid,0);return 'live-or-reused-pid';}
+  catch(e){return e.code==='ESRCH'?'local-pid-absent':'unknown';}
+}
+function location(workspace,{global=false,userHome=homedir()}={}) {
+  if(typeof global!=='boolean')fail('desired.recovery-options');
+  const root=global?absoluteRoot(userHome):workspace;
+  return {root,relative:global?'.grok/.wpc-config-lock':'.pipeline/lock',
+    filename:global?'owner':'owner.json',purpose:global?'desired-global-settings':'desired-state'};
+}
+async function ownerAt(loc,relative,workspace) {
+  const directory=path.join(loc.root,...relative.split('/'));
+  if(!(await inspectDirectory(directory)).exists)return null;
+  const names=await readdir(directory);
+  if(names.length!==1||names[0]!==loc.filename)fail('desired.recovery-foreign-entry');
+  const [observed]=await observeTargets(loc.root,[relative+'/'+loc.filename]);
+  if(observed.bytes===null)fail('desired.recovery-owner-missing');
+  const owner=parse(utf8(observed.bytes),'json');
+  if(!owner || Object.keys(owner).sort().join(',')!=='createdAt,host,pid,purpose,schemaVersion,token,workspace' ||
+      owner.schemaVersion!==1||owner.purpose!==loc.purpose||owner.workspace!==workspace||!uuid.test(owner.token??'')||
+      !Number.isSafeInteger(owner.pid)||owner.pid<=0||typeof owner.host!=='string'||
+      typeof owner.createdAt!=='string'||!Number.isFinite(Date.parse(owner.createdAt)))fail('desired.recovery-owner-invalid');
+  return {owner,hash:sha256(observed.bytes),liveness:liveness(owner)};
+}
+
+// Read-only: age alone never authorizes release, and signal 0 does not kill.
+export async function inspectDesiredLock(workspace,options={}) {
+  workspace=absoluteRoot(workspace);const loc=location(workspace,options);
+  await assertNoRepositoryPending(workspace);
+  const records=await readDesiredRecords(workspace);
+  const state={installed:records.installed?.hash??null,pending:records.pending?.hash??null};
+  const lock=await ownerAt(loc,loc.relative,workspace);
+  const result={workspace,global:options.global===true,path:path.join(loc.root,...loc.relative.split('/')),state,
+    status:lock===null?'absent':lock.liveness==='local-pid-absent'?'stopped-owner-observed':'owner-unconfirmed',lock};
+  return {...result,digest:contractDigest(result)};
+}
+
+// The existing OS lease serializes recoverers, without another stale lockfile.
+// Rename the exact stale directory atomically; never delete/reuse its old path
+// after rename, since a fresh cooperative writer may immediately acquire it.
+export async function recoverDesiredLock(workspace,expected,options={}) {
+  workspace=absoluteRoot(workspace);const loc=location(workspace,options);
+  return withRecoveryLease(loc.root,async lease=>{
+    let current=await inspectDesiredLock(workspace,options);
+    if(current.digest!==expected.digest)fail('desired.recovery-observation-changed');
+    if(current.status==='absent')return {status:'no-lock',workspace,global:options.global===true};
+    if(current.status!=='stopped-owner-observed')fail('desired.recovery-owner-unconfirmed');
+    current=await inspectDesiredLock(workspace,options);
+    if(current.digest!==expected.digest)fail('desired.recovery-observation-changed');
+    assertRecoveryLeaseHeld(lease);
+    const relative=loc.relative+'-retiring-'+randomUUID(),temporary=path.join(loc.root,...relative.split('/'));
+    await rename(current.path,temporary);
+    try {
+      const saved=await ownerAt(loc,relative,workspace);
+      if(!saved || saved.hash!==current.lock.hash)fail('desired.recovery-retired-mismatch');
+      assertRecoveryLeaseHeld(lease);
+      await unlink(path.join(temporary,loc.filename));
+      await rmdir(temporary); // Never recursively remove unexpected children.
+    }catch(error){error.recovery={lockReleased:true,residualPath:temporary};throw error;}
+    return {status:'lock-retired',workspace,global:options.global===true,
+      next:'Inspect doctor, then explicitly retry reset or remove; operation records and configuration were not changed.'};
+  });
+}

package/src/desired-state/records.js

@@ -0,0 +1,75 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import {fail,parse} from '../contracts/parse.js';
+import {contractDigest,portablePath} from '../contracts/semantic.js';
+import {observeTargets} from '../operations/state.js';
+import {writeCheckedFile,deleteCheckedFile} from '../operations/apply.js';
+import {sha256,utf8} from '../source/inventory.js';
+import {decodeLegacyState,retireLegacyState} from './legacy-state.js';
+import {validateDesiredBinding} from './binding.js';
+
+export const installedPath='.pipeline/desired-install.json';
+export const pendingPath='.pipeline/desired-pending.json';
+const hash={type:'string',pattern:'^sha256:[a-f0-9]{64}$'};
+const validate=new Ajv2020({strict:true}).compile({type:'object',additionalProperties:false,
+  required:['schemaVersion','operationHash','pipeline','providers','scopes','files','settings'],properties:{
+    schemaVersion:{const:1},operationHash:hash,binding:{type:'object'},
+    intent:{enum:['remove','removed']},
+    adapters:{type:'array',minItems:1,uniqueItems:true,items:{type:'string',pattern:'^[a-z][a-z0-9-]{0,62}$'}},
+    pipeline:{type:'object',additionalProperties:false,required:['id','version'],properties:{id:{type:'string'},version:{type:'string'}}},
+    providers:{type:'array',uniqueItems:true,items:{enum:['codex','claude','grok','kimi']}},
+    scopes:{type:'array',maxItems:10000,items:{type:'object',additionalProperties:false,required:['path','kind'],properties:{path:{type:'string'},kind:{enum:['file','directory']}}}},
+    files:{type:'array',maxItems:10000,items:{type:'object',additionalProperties:false,required:['path','kind','hash'],properties:{path:{type:'string'},kind:{enum:['file','directory']},hash:{anyOf:[hash,{type:'null'}]}}}},
+    settings:{type:'array',maxItems:1000,items:{type:'object',additionalProperties:false,required:['target','pointer','operation','valueHash'],properties:{target:{type:'string'},pointer:{type:'string'},operation:{enum:['set','remove']},valueHash:{anyOf:[hash,{type:'null'}]}}}}
+  }});
+
+// Only desired identities/digests, never old contents or secret setting values.
+export function installationRecord(compiled,desired,{protectedPaths,globalConfigPath,binding}) {
+  const files=desired.entries.map(e=>({path:e.path,kind:e.kind,hash:e.hash??null}));
+  const provenance=binding===undefined?{}:{binding:validateDesiredBinding(binding)};
+  return {schemaVersion:1,operationHash:contractDigest({compiled,files,protectedPaths,globalConfigPath,...provenance}),...provenance,
+    pipeline:compiled.pipeline,adapters:compiled.adapters,providers:compiled.providers,scopes:desired.scopes,files,
+    settings:compiled.settings.map(s=>({target:s.target,pointer:s.pointer,operation:s.operation,
+      valueHash:s.operation==='set'?contractDigest(s.value):null}))};
+}
+
+export async function readDesiredRecords(workspace,{allowLegacyMigration=false}={}) {
+  const observations=await observeTargets(workspace,[installedPath,pendingPath,'.pipeline/state.json']);
+  // Migration is explicit; never silently abandon the old lifecycle state.
+  const legacyBytes=observations.find(o=>o.path==='.pipeline/state.json').bytes;
+  if(legacyBytes!==null && !allowLegacyMigration)fail('desired.legacy-migration-required');
+  const result={legacy:legacyBytes===null?null:decodeLegacyState(workspace,legacyBytes)};
+  for(const [key,name] of [['installed',installedPath],['pending',pendingPath]]) {
+    const bytes=observations.find(o=>o.path===name).bytes;
+    if(bytes===null){result[key]=null;continue;}
+    const value=parse(utf8(bytes),'json');
+    if(!validate(value))fail('desired.record-invalid');
+    if(value.intent==='removed' && (key==='pending'||value.scopes.length||value.files.length||value.settings.length||value.providers.length))fail('desired.record-invalid');
+    if(value.intent==='remove' && (key==='installed'||value.files.length||value.settings.some(s=>s.operation!=='remove'||s.target==='grok.user')))fail('desired.record-invalid');
+    if(value.binding!==undefined)validateDesiredBinding(value.binding);
+    for(const e of [...value.scopes,...value.files])portablePath(e.path);
+    result[key]={value,hash:sha256(bytes)};
+  }
+  return result;
+}
+
+export function assertDesiredTransition(records,next) {
+  if(records.pending?.value.intent==='remove' && next.intent!=='remove')fail('desired.finish-remove-before-update');
+  if(records.pending && records.pending.value.operationHash!==next.operationHash)fail('desired.retry-same-source-required');
+  const previous=records.installed?.value??records.legacy?.ownership;
+  if(!previous || previous.intent==='removed')return;
+  if(previous.pipeline.id!==next.pipeline.id)fail('desired.pipeline-switch-not-integrated');
+}
+
+const encode=record=>Buffer.from(JSON.stringify(record,null,2)+'\n');
+export async function beginDesiredInstall(lock,records,next) {
+  if(records.pending)return records.pending.hash;
+  return writeCheckedFile(lock,pendingPath,null,encode(next));
+}
+export async function completeDesiredInstall(lock,records,next,pendingHash) {
+  const completed=next.intent==='remove'?{...next,intent:'removed',scopes:[],files:[],settings:[],providers:[]}:next;
+  const bytes=encode(completed);
+  if(records.installed?.hash!==sha256(bytes))
+    await writeCheckedFile(lock,installedPath,records.installed?.hash??null,bytes);
+  await retireLegacyState(lock,records.legacy);
+  if(pendingHash)await deleteCheckedFile(lock,pendingPath,pendingHash,async()=>{});
+}

package/src/desired-state/removal.js

@@ -0,0 +1,32 @@
+import {fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {observeTargets} from '../operations/state.js';
+import {utf8} from '../source/inventory.js';
+import {parseDesiredWorkspace} from './source.js';
+import {includeRetiredTargets} from './retirement.js';
+
+// Offline full-delivery removal. Historical ownership never grants deletion of
+// repositories. User-wide compatibility remains shared, not workspace-owned.
+export async function prepareDesiredRemoval(workspace,records,protectedPaths=[]) {
+  if(records.pending && records.pending.value.intent!=='remove')fail('desired.finish-install-before-remove');
+  const previous=(records.pending??records.installed)?.value;
+  if(!previous)fail('desired.not-installed');
+  if(previous.intent==='removed')return {alreadyRemoved:true};
+  if(!previous.binding)fail('desired.removal-binding-required');
+  const protectedRoots=new Set(protectedPaths);
+  for(const repo of Object.values(previous.binding.layout.repositories))protectedRoots.add(repo.path);
+  const [entry]=await observeTargets(workspace,['workspace.json']);
+  if(entry.bytes!==null) {
+    const descriptor=parseDesiredWorkspace(utf8(entry.bytes));
+    for(const repo of Object.values(descriptor.layout.repositories))protectedRoots.add(repo.path);
+  }
+  const desired={scopes:[],entries:[]};
+  const retired=includeRetiredTargets(previous,{settings:[]},desired,[...protectedRoots]);
+  const settings=records.pending?previous.settings.map(s=>({target:s.target,pointer:s.pointer,operation:'remove'})):
+    retired.settings.filter(s=>s.target!=='grok.user');
+  const next=records.pending?.value??{...previous,intent:'remove',files:[],
+    settings:settings.map(s=>({...s,valueHash:null})),
+    operationHash:contractDigest({intent:'remove',previous,preserveGlobalSettings:true})};
+  return {alreadyRemoved:false,next,desired:retired.desired,settings,
+    protectedPaths:[...protectedRoots]};
+}

package/src/desired-state/reset.js

@@ -0,0 +1,27 @@
+import {fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {readDesiredRecords} from './records.js';
+import {parseDesiredWorkspace,prepareDesiredWorkspace} from './source.js';
+
+// Reset is restoration of the recorded Git package, not a fetch of today's ref.
+// The source remains declarative: updates keep using its original branch/ref.
+export async function prepareDesiredReset(workspace,text,options={}) {
+  const descriptor=parseDesiredWorkspace(text),records=await readDesiredRecords(workspace);
+  if(records.pending?.value.intent==='remove')fail('desired.finish-remove-before-reset');
+  const record=(records.pending??records.installed)?.value;
+  if(!record?.binding || !record.adapters)fail('desired.reset-binding-required');
+  if(contractDigest(descriptor.pipeline)!==contractDigest(record.binding.source) ||
+      contractDigest(descriptor.layout)!==contractDigest(record.binding.layout) ||
+      contractDigest([...descriptor.adapters].sort())!==contractDigest([...record.adapters].sort()))
+    fail('desired.reset-workspace-different');
+  const pinned={...descriptor,pipeline:{...record.binding.source,ref:record.binding.commit}};
+  const prepared=await prepareDesiredWorkspace(workspace,JSON.stringify(pinned),options);
+  if(prepared.provenance.commit!==record.binding.commit || prepared.provenance.digest!==record.binding.digest)
+    fail('desired.reset-source-mismatch');
+  prepared.input.binding=record.binding;
+  prepared.provenance={source:record.binding.source,commit:record.binding.commit,digest:record.binding.digest};
+  prepared.descriptor=descriptor;
+  prepared.reset={mode:records.pending?'pending-installation':'installed',commit:record.binding.commit};
+  prepared.expectedRecords={installed:records.installed?.hash??null,pending:records.pending?.hash??null};
+  return prepared;
+}

package/src/desired-state/retirement.js

@@ -0,0 +1,37 @@
+import {compileDesiredManifest} from '../contracts/desired-state.js';
+import {compileDesiredSettings} from './settings.js';
+import {fail} from '../contracts/parse.js';
+
+const contains=(parent,child)=>parent===child || child.startsWith(parent+'/');
+
+// Revalidate stored ownership through today's scope policy. A historical record
+// is not a bypass for repository exclusions or config-field permissions.
+export function includeRetiredTargets(previous,compiled,desired,protectedPaths) {
+  if(!previous)return {desired,settings:compiled.settings};
+  const priorSettings=previous.settings.map(s=>({target:s.target,pointer:s.pointer,operation:'remove'}));
+  compileDesiredManifest(JSON.stringify({schemaVersion:2,id:'retirement-check',version:'0.0.0',adapters:{prior:{
+    providers:['codex'],files:previous.scopes.map(s=>({source:'unused',target:s.path,kind:s.kind})),settings:priorSettings
+  }}}),{selected:['prior'],protectedPaths});
+  for(const op of priorSettings)compileDesiredSettings(op.target,null,[op]);
+  const settings=[...compiled.settings,...priorSettings.filter(old=>
+    previous.settings.find(s=>s.target===old.target && s.pointer===old.pointer).operation==='set' &&
+    !compiled.settings.some(s=>s.target===old.target && s.pointer===old.pointer))];
+  const all=[...previous.scopes,...desired.scopes];
+  // Different spellings of intersecting scopes cannot be resolved portably.
+  for(const a of all)for(const b of all) {
+    if(contains(a.path.toLowerCase(),b.path.toLowerCase()) && !contains(a.path,b.path))fail('desired.retirement-case-alias');
+  }
+  const unique=[...new Map(all.map(s=>[s.path,s])).values()];
+  const scopes=unique.filter(s=>!unique.some(parent=>parent.path!==s.path && contains(parent.path,s.path)));
+  const entries=new Map(desired.entries.map(e=>[e.path,e]));
+  // A narrowed former directory still needs structural parents while deleting
+  // its obsolete siblings. Those parents are not new ownership grants.
+  for(const entry of desired.entries) {
+    const parts=entry.path.split('/');
+    for(let i=1;i<parts.length;i++) {
+      const name=parts.slice(0,i).join('/');
+      if(scopes.some(s=>contains(s.path,name)) && !entries.has(name))entries.set(name,{path:name,kind:'directory'});
+    }
+  }
+  return {desired:{scopes,entries:[...entries.values()]},settings};
+}