@unbrained/pm-cli 2026.10.21 → 2026.10.23

package/dist/sdk/workspace-snapshot.js

@@ -1,6 +1,6 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3b4a5521-a665-5f60-8d01-16033b078916")}catch{}})();import crypto from"node:crypto";import{cp,lstat,mkdir,readFile,readdir,rename,rm,writeFile}from"node:fs/promises";import path from"node:path";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{appendWorkspaceAuditEvent}from"../core/history/workspace-history.js";import{acquireLock}from"../core/lock/lock.js";import{getLockPath}from"../core/store/paths.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{withHostEnvironmentBoundary}from"./environment/host-environment-errors.js";const SNAPSHOT_SCHEMA="https://schema.unbrained.dev/pm/workspace-snapshot/v1",WORKSPACE_SNAPSHOT_ACTIONS=["create","list","inspect","restore","delete"],SNAPSHOT_RUNTIME_PATH=path.join("runtime","workspace-snapshots"),EXCLUDED_ROOT_NAMES=new Set(["checkpoints","locks","runtime","search","transactions"]),SNAPSHOT_TARGET_PATTERN=/^[a-z0-9][a-z0-9._-]*$/,WORKSPACE_WRITER_LOCK_ID="sdk-workspace-transaction",SNAPSHOT_HOST_FAULT_CODES={capacity:{code:"workspace_snapshot_storage_exhausted"},permission:{code:"workspace_snapshot_permission_denied"},resource:{code:"workspace_snapshot_resource_exhausted"}},DEFAULT_ATOMIC_OPERATIONS={renameEntry:rename,removeEntry:async target=>{await rm(target,{recursive:!0,force:!0})}};class WorkspaceLockHeartbeat{lockPath;owner;intervalMs;timer;refresh;failure;constructor(lockPath,owner,ttlSeconds){this.lockPath=lockPath,this.owner=owner,this.intervalMs=Math.max(10,Math.floor(ttlSeconds*1e3/3))}start(){this.scheduleRenewal(),this.timer=setInterval(()=>{this.scheduleRenewal()},this.intervalMs),this.timer.unref()}async refreshNow(){this.scheduleRenewal(),await this.refresh,this.assertHealthy()}assertHealthy(){if(this.failure!==void 0)throw new Error("Workspace snapshot restore lost its writer lock",{cause:this.failure})}async stop(){this.timer!==void 0&&clearInterval(this.timer),await this.refresh,this.assertHealthy()}scheduleRenewal(){this.refresh!==void 0||this.failure!==void 0||(this.refresh=this.renew().catch(error=>{this.failure=error}).finally(()=>{this.refresh=void 0}))}async renew(){const parsed=JSON.parse(await readFile(this.lockPath,"utf8"));if(typeof parsed!="object"||parsed===null||Array.isArray(parsed))throw new Error("Workspace writer lock has invalid structure");const lock=parsed;if(lock.id!==WORKSPACE_WRITER_LOCK_ID||lock.owner!==this.owner||lock.pid!==process.pid)throw new Error("Workspace writer lock ownership changed");await writeFileAtomic(this.lockPath,`${JSON.stringify({...lock,created_at:new Date().toISOString()},null,2)}
-`)}}const _testOnlyWorkspaceSnapshot={WorkspaceLockHeartbeat,withSnapshotFilesystemGuard};async function collectAuthoritativeFiles(root,relative=""){const entries=await readdir(path.join(root,relative),{withFileTypes:!0}),files=[];for(const entry of entries.sort((left,right)=>left.name.localeCompare(right.name))){if(relative.length===0&&EXCLUDED_ROOT_NAMES.has(entry.name))continue;const entryRelative=path.posix.join(relative.replaceAll(path.sep,"/"),entry.name);if(entry.isSymbolicLink())throw new Error(`Workspace snapshots reject symbolic links: ${entryRelative}`);if(entry.isDirectory())files.push(...await collectAuthoritativeFiles(root,entryRelative));else if(entry.isFile())files.push(entryRelative);else throw new Error(`Workspace snapshots reject unsupported filesystem entries: ${entryRelative}`)}return files}async function buildManifest(pmRoot){const files=await collectAuthoritativeFiles(pmRoot),hash=crypto.createHash("sha256"),contents=[];let bytes=0;for(const file of files){const content=await readFile(path.join(pmRoot,file));contents.push(content),bytes+=content.byteLength,hash.update(file),hash.update("\0"),hash.update(String(content.byteLength)),hash.update("\0"),hash.update(content)}const fingerprint=hash.digest("hex");return{manifest:{schema:SNAPSHOT_SCHEMA,fingerprint,files,bytes},contents}}function lineCount(content){return content===void 0||content.byteLength===0?0:content.toString("utf8").split(`
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="66cb8c82-3760-5628-a1de-69e417cf0292")}catch{}})();import crypto from"node:crypto";import{cp,lstat,mkdir,readFile,readdir,rename,rm,writeFile}from"node:fs/promises";import path from"node:path";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{appendWorkspaceAuditEvent}from"../core/history/workspace-history.js";import{acquireLockLease,waitForStaleCleanupGate}from"../core/lock/lock.js";import{getLockPath}from"../core/store/paths.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{withHostEnvironmentBoundary}from"./environment/host-environment-errors.js";const SNAPSHOT_SCHEMA="https://schema.unbrained.dev/pm/workspace-snapshot/v1",WORKSPACE_SNAPSHOT_ACTIONS=["create","list","inspect","restore","delete"],SNAPSHOT_RUNTIME_PATH=path.join("runtime","workspace-snapshots"),EXCLUDED_ROOT_NAMES=new Set(["checkpoints","locks","runtime","search","transactions"]),SNAPSHOT_TARGET_PATTERN=/^[a-z0-9][a-z0-9._-]*$/,WORKSPACE_WRITER_LOCK_ID="sdk-workspace-transaction",SNAPSHOT_HOST_FAULT_CODES={capacity:{code:"workspace_snapshot_storage_exhausted"},permission:{code:"workspace_snapshot_permission_denied"},resource:{code:"workspace_snapshot_resource_exhausted"}},DEFAULT_ATOMIC_OPERATIONS={renameEntry:rename,removeEntry:async target=>{await rm(target,{recursive:!0,force:!0})}};class WorkspaceLockHeartbeat{lockPath;owner;intervalMs;timer;refresh;failure;constructor(lockPath,owner,ttlSeconds){this.lockPath=lockPath,this.owner=owner,this.intervalMs=Math.max(10,Math.floor(ttlSeconds*1e3/3))}start(){this.scheduleRenewal(),this.timer=setInterval(()=>{this.scheduleRenewal()},this.intervalMs),this.timer.unref()}async refreshNow(){this.scheduleRenewal(),await this.refresh,this.assertHealthy()}assertHealthy(){if(this.failure!==void 0)throw new Error("Workspace snapshot restore lost its writer lock",{cause:this.failure})}async stop(){this.timer!==void 0&&clearInterval(this.timer),await this.refresh,this.assertHealthy()}scheduleRenewal(){this.refresh!==void 0||this.failure!==void 0||(this.refresh=this.renew().catch(error=>{this.failure=error}).finally(()=>{this.refresh=void 0}))}async renew(){const releaseGate=await waitForStaleCleanupGate(this.lockPath,WORKSPACE_WRITER_LOCK_ID);if(releaseGate===null)throw new Error("Workspace writer lock cleanup gate stayed held");try{const parsed=JSON.parse(await readFile(this.lockPath,"utf8"));if(typeof parsed!="object"||parsed===null||Array.isArray(parsed))throw new Error("Workspace writer lock has invalid structure");const lock=parsed;if(lock.id!==WORKSPACE_WRITER_LOCK_ID||lock.owner!==this.owner||lock.pid!==process.pid)throw new Error("Workspace writer lock ownership changed");await writeFileAtomic(this.lockPath,`${JSON.stringify({...lock,created_at:new Date().toISOString()},null,2)}
+`)}finally{await releaseGate()}}}const _testOnlyWorkspaceSnapshot={WorkspaceLockHeartbeat,withSnapshotFilesystemGuard};async function collectAuthoritativeFiles(root,relative=""){const entries=await readdir(path.join(root,relative),{withFileTypes:!0}),files=[];for(const entry of entries.sort((left,right)=>left.name.localeCompare(right.name))){if(relative.length===0&&EXCLUDED_ROOT_NAMES.has(entry.name))continue;const entryRelative=path.posix.join(relative.replaceAll(path.sep,"/"),entry.name);if(entry.isSymbolicLink())throw new Error(`Workspace snapshots reject symbolic links: ${entryRelative}`);if(entry.isDirectory())files.push(...await collectAuthoritativeFiles(root,entryRelative));else if(entry.isFile())files.push(entryRelative);else throw new Error(`Workspace snapshots reject unsupported filesystem entries: ${entryRelative}`)}return files}async function buildManifest(pmRoot){const files=await collectAuthoritativeFiles(pmRoot),hash=crypto.createHash("sha256"),contents=[];let bytes=0;for(const file of files){const content=await readFile(path.join(pmRoot,file));contents.push(content),bytes+=content.byteLength,hash.update(file),hash.update("\0"),hash.update(String(content.byteLength)),hash.update("\0"),hash.update(content)}const fingerprint=hash.digest("hex");return{manifest:{schema:SNAPSHOT_SCHEMA,fingerprint,files,bytes},contents}}function lineCount(content){return content===void 0||content.byteLength===0?0:content.toString("utf8").split(`
 `).filter(line=>line.trim().length>0).length}async function snapshotContents(root,files){const contents=new Map;for(let offset=0;offset<files.length;offset+=32){const batch=files.slice(offset,offset+32),entries=await Promise.all(batch.map(async file=>[file,await readFile(path.join(root,file))]));for(const[file,content]of entries)contents.set(file,content)}return contents}function validateSnapshotTarget(target){if(!SNAPSHOT_TARGET_PATTERN.test(target))throw new PmCliError("Snapshot names and fingerprints must use lowercase letters, digits, dots, underscores, or hyphens",EXIT_CODE.USAGE,{code:"invalid_workspace_snapshot_target",required:"Provide a non-empty lowercase snapshot name or 64-character hexadecimal fingerprint.",why:"Snapshot targets are used as portable reference filenames and content identities.",examples:["pm workspace snapshot list --json","pm workspace snapshot inspect baseline --json"],nextSteps:["List available snapshots, then retry with a returned name or fingerprint."],recovery:{suggested_retry:"pm workspace snapshot list --json"}})}async function withSnapshotFilesystemGuard(operation,run){return withHostEnvironmentBoundary(`workspace_snapshot_${operation}`,run,{codes:{capacity:SNAPSHOT_HOST_FAULT_CODES.capacity.code,permission:SNAPSHOT_HOST_FAULT_CODES.permission.code,resource:SNAPSHOT_HOST_FAULT_CODES.resource.code},why:"Snapshot create and restore copy authoritative tracker state before activation, so the stage needs capacity and write access up front.",nextSteps:["Reclaim rebuildable tracker cache space with pm gc, then retry."],suggestedRetry:"pm gc --json"})}function snapshotStore(pmRoot){return path.join(pmRoot,SNAPSHOT_RUNTIME_PATH)}function workspaceSnapshotNotFound(target){return new PmCliError(`Unknown workspace snapshot: ${target}`,EXIT_CODE.NOT_FOUND,{code:"workspace_snapshot_not_found",required:"Use a snapshot name or fingerprint returned by snapshot list.",why:"The requested reference or immutable snapshot object does not exist.",examples:["pm workspace snapshot list --json"],nextSteps:["List available snapshots and retry with an exact target."],recovery:{suggested_retry:"pm workspace snapshot list --json"}})}async function readSnapshotJson(file,target){try{return JSON.parse(await readFile(file,"utf8"))}catch(error){throw isFileMissingError(error)?workspaceSnapshotNotFound(target):error}}async function removeSnapshotEntry(entry,target,recursive){try{await rm(entry,{recursive})}catch(error){throw isFileMissingError(error)?workspaceSnapshotNotFound(target):error}}async function publishWorkspaceSnapshotObject(temporaryRoot,objectRoot,operations=DEFAULT_ATOMIC_OPERATIONS){try{return await operations.renameEntry(temporaryRoot,objectRoot),!1}catch(error){if(!(error instanceof Error&&"code"in error&&(error.code==="EEXIST"||error.code==="ENOTEMPTY")))throw error;return await operations.removeEntry(temporaryRoot),!0}}async function swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,operations,afterActivation){await operations.renameEntry(pmRoot,backup);try{await operations.renameEntry(staging,pmRoot),await afterActivation?.()}catch(error){throw await operations.renameEntry(backup,pmRoot),await operations.removeEntry(staging),error}await operations.removeEntry(backup)}async function swapWorkspaceSnapshotRoot(staging,pmRoot,backup,operations=DEFAULT_ATOMIC_OPERATIONS){await swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,operations)}async function resolveSnapshotFingerprint(pmRoot,target){return validateSnapshotTarget(target),/^[a-f0-9]{64}$/.test(target)?target:(await readSnapshotJson(path.join(snapshotStore(pmRoot),"refs",`${target}.json`),target)).fingerprint}async function createWorkspaceSnapshot(pmRoot,options={}){if(options.name!==void 0&&(validateSnapshotTarget(options.name),/^[a-f0-9]{64}$/.test(options.name)))throw new PmCliError("Snapshot names must not be 64-character lowercase hexadecimal fingerprints",EXIT_CODE.USAGE,{code:"workspace_snapshot_name_reserved_fingerprint",required:"Choose a human-readable reference name that cannot be mistaken for a content fingerprint.",why:"Exact 64-character hexadecimal values address immutable objects.",examples:["pm workspace snapshot create baseline --json"],nextSteps:["Retry with a shorter descriptive snapshot name."]});const{manifest,contents}=await buildManifest(pmRoot),store=snapshotStore(pmRoot),objectRoot=path.join(store,"objects",manifest.fingerprint);let deduplicated=!1;try{deduplicated=(await lstat(objectRoot)).isDirectory()}catch(error){if(!(error instanceof Error&&"code"in error&&isFileMissingError(error)))throw error}if(!deduplicated){const temporaryRoot=path.join(store,"objects",`.create-${process.pid}-${crypto.randomUUID()}`);await withSnapshotFilesystemGuard("create_object",async()=>{await mkdir(path.join(temporaryRoot,"files"),{recursive:!0});for(const[index,file]of manifest.files.entries()){const target=path.join(temporaryRoot,"files",file);await mkdir(path.dirname(target),{recursive:!0}),await writeFile(target,contents[index])}await writeFile(path.join(temporaryRoot,"manifest.json"),`${JSON.stringify(manifest,null,2)}
 `,"utf8"),await mkdir(path.dirname(objectRoot),{recursive:!0})}),deduplicated=await publishWorkspaceSnapshotObject(temporaryRoot,objectRoot)}if(options.name!==void 0){const reference={name:options.name,fingerprint:manifest.fingerprint},refsRoot=path.join(store,"refs");await mkdir(refsRoot,{recursive:!0});const temporaryRef=path.join(refsRoot,`.ref-${process.pid}-${crypto.randomUUID()}`);await writeFile(temporaryRef,`${JSON.stringify(reference,null,2)}
-`,"utf8"),await rename(temporaryRef,path.join(refsRoot,`${options.name}.json`))}return{manifest,...options.name===void 0?{}:{name:options.name},deduplicated}}async function inspectWorkspaceSnapshot(pmRoot,target){const fingerprint=await resolveSnapshotFingerprint(pmRoot,target),manifest=await readSnapshotJson(path.join(snapshotStore(pmRoot),"objects",fingerprint,"manifest.json"),target);if(manifest.schema!==SNAPSHOT_SCHEMA||manifest.fingerprint!==fingerprint)throw new PmCliError(`Snapshot manifest identity mismatch: ${target}`,EXIT_CODE.CONFLICT,{code:"workspace_snapshot_manifest_mismatch",required:"Use an intact snapshot whose manifest fingerprint matches its object path.",why:"Content identity must be verified before snapshot data is trusted.",examples:["pm workspace snapshot list --json"],nextSteps:["Inspect or recreate the snapshot before restoring it."]});return manifest}async function listWorkspaceSnapshots(pmRoot){const store=snapshotStore(pmRoot),objectNames=await readdir(path.join(store,"objects")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error))return[];throw error}),referenceNames=await readdir(path.join(store,"refs")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error))return[];throw error});return{objects:await Promise.all(objectNames.filter(name=>/^[a-f0-9]{64}$/.test(name)).sort().map(name=>inspectWorkspaceSnapshot(pmRoot,name))),references:await Promise.all(referenceNames.filter(name=>name.endsWith(".json")).sort().map(async name=>JSON.parse(await readFile(path.join(store,"refs",name),"utf8"))))}}async function planWorkspaceSnapshotRestore(pmRoot,target){const targetManifest=await inspectWorkspaceSnapshot(pmRoot,target),{manifest:currentManifest,contents:currentContentList}=await buildManifest(pmRoot),currentContents=new Map(currentManifest.files.map((file,index)=>[file,currentContentList[index]])),targetContents=await snapshotContents(path.join(snapshotStore(pmRoot),"objects",targetManifest.fingerprint,"files"),targetManifest.files),currentFiles=new Set(currentManifest.files),targetFiles=new Set(targetManifest.files),changedFiles=new Set([...currentFiles,...targetFiles]);for(const file of changedFiles){const currentContent=currentContents.get(file),targetContent=targetContents.get(file);currentContent!==void 0&&targetContent!==void 0&&currentContent.equals(targetContent)&&changedFiles.delete(file)}const affectedHistoryStreams=currentManifest.files.filter(file=>file.startsWith("history/")&&file.endsWith(".jsonl")).map(file=>{const currentEntries=lineCount(currentContents.get(file)),targetEntries=lineCount(targetContents.get(file));return{path:file,current_entries:currentEntries,target_entries:targetEntries,removed_entries:Math.max(0,currentEntries-targetEntries)}}).filter(entry=>entry.removed_entries>0).sort((left,right)=>left.path.localeCompare(right.path));return{target_fingerprint:targetManifest.fingerprint,current_fingerprint:currentManifest.fingerprint,changed_file_count:changedFiles.size,removed_file_count:[...currentFiles].filter(file=>!targetFiles.has(file)).length,added_file_count:[...targetFiles].filter(file=>!currentFiles.has(file)).length,removed_item_count:[...currentFiles].filter(file=>file.endsWith(".toon")&&!targetFiles.has(file)).length,affected_history_stream_count:affectedHistoryStreams.length,removed_history_entry_count:affectedHistoryStreams.reduce((total,entry)=>total+entry.removed_entries,0),affected_history_streams:affectedHistoryStreams,changes_authoritative_state:currentManifest.fingerprint!==targetManifest.fingerprint}}async function restoreWorkspaceSnapshotWithRecovery(pmRoot,target,options={}){if(options.force!==!0)throw new PmCliError("Workspace snapshot restore requires explicit force confirmation; inspect the impact with planWorkspaceSnapshotRestore or pm workspace snapshot restore <target> --dry-run, then retry with force",EXIT_CODE.USAGE,{code:"workspace_snapshot_force_required",required:"Preview the destructive impact, then explicitly confirm the restore.",why:"A restore replaces the complete authoritative tracker state.",examples:[`pm workspace snapshot restore ${target} --dry-run --json`,`pm workspace snapshot restore ${target} --force --json`],nextSteps:["Review the dry-run counts before retrying with --force."],recovery:{suggested_retry:`pm workspace snapshot restore ${target} --dry-run --json`}});const author=options.author?.trim()||"pm-sdk",lockTtlSeconds=options.lockTtlSeconds??60,lockWaitMs=options.lockWaitMs??5e3,releaseWorkspaceLock=await acquireLock(pmRoot,WORKSPACE_WRITER_LOCK_ID,lockTtlSeconds,author,!1,!1,lockWaitMs),heartbeat=new WorkspaceLockHeartbeat(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID),author,lockTtlSeconds);heartbeat.start(),await heartbeat.refreshNow();let staging,swapStarted=!1,heartbeatStopped=!1;try{const plan=await planWorkspaceSnapshotRestore(pmRoot,target),manifest=await inspectWorkspaceSnapshot(pmRoot,target),recovery=await createWorkspaceSnapshot(pmRoot),fingerprint=manifest.fingerprint,store=snapshotStore(pmRoot),source=path.join(store,"objects",fingerprint,"files"),parent=path.dirname(pmRoot),base=path.basename(pmRoot);staging=path.join(parent,`.${base}.restore-${crypto.randomUUID()}`);const backup=path.join(parent,`.${base}.backup-${crypto.randomUUID()}`);await withSnapshotFilesystemGuard("restore_stage",async()=>{await mkdir(staging,{recursive:!0}),await cp(source,staging,{recursive:!0,force:!1}),await mkdir(path.join(staging,"runtime"),{recursive:!0}),await cp(store,path.join(staging,SNAPSHOT_RUNTIME_PATH),{recursive:!0,force:!1})});const audit=await appendWorkspaceAuditEvent({pmRoot:staging,op:"workspace_snapshot_restore",author,message:options.message??`Restore workspace snapshot ${fingerprint}; recovery snapshot ${recovery.manifest.fingerprint}`,context:{target_fingerprint:fingerprint,pre_restore_fingerprint:recovery.manifest.fingerprint,changed_file_count:plan.changed_file_count,removed_file_count:plan.removed_file_count,removed_item_count:plan.removed_item_count,affected_history_stream_count:plan.affected_history_stream_count,removed_history_entry_count:plan.removed_history_entry_count},lockTtlSeconds,lockWaitMs}),auditHistoryPath=path.relative(staging,audit.historyPath).replaceAll("\\","/");await heartbeat.stop(),heartbeatStopped=!0;const stagedWorkspaceLock=getLockPath(staging,WORKSPACE_WRITER_LOCK_ID);return await mkdir(path.dirname(stagedWorkspaceLock),{recursive:!0}),await writeFile(stagedWorkspaceLock,await readFile(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID)),{flag:"wx"}),swapStarted=!0,await swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,DEFAULT_ATOMIC_OPERATIONS,async()=>{heartbeat.start(),heartbeatStopped=!1,await heartbeat.refreshNow()}),await heartbeat.stop(),heartbeatStopped=!0,{manifest,plan,recovery_fingerprint:recovery.manifest.fingerprint,audit_history_path:auditHistoryPath,audit_operation:"workspace_snapshot_restore"}}catch(error){throw staging!==void 0&&!swapStarted&&await Promise.allSettled([rm(staging,{recursive:!0,force:!0})]),error}finally{try{heartbeatStopped||await heartbeat.stop()}catch{}finally{await releaseWorkspaceLock()}}}async function restoreWorkspaceSnapshot(pmRoot,target){return(await restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:!0,message:"Restore requested through the compatibility SDK signature"})).manifest}async function deleteWorkspaceSnapshot(pmRoot,target){validateSnapshotTarget(target);const store=snapshotStore(pmRoot);if(!/^[a-f0-9]{64}$/.test(target))return await removeSnapshotEntry(path.join(store,"refs",`${target}.json`),target,!1),{deleted:"reference",target};const{references}=await listWorkspaceSnapshots(pmRoot);if(references.some(reference=>reference.fingerprint===target))throw new Error(`Snapshot object ${target} is still referenced`);return await removeSnapshotEntry(path.join(store,"objects",target),target,!0),{deleted:"object",target}}export{SNAPSHOT_SCHEMA,WORKSPACE_SNAPSHOT_ACTIONS,_testOnlyWorkspaceSnapshot,createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,publishWorkspaceSnapshotObject,restoreWorkspaceSnapshot,restoreWorkspaceSnapshotWithRecovery,swapWorkspaceSnapshotRoot};
+`,"utf8"),await rename(temporaryRef,path.join(refsRoot,`${options.name}.json`))}return{manifest,...options.name===void 0?{}:{name:options.name},deduplicated}}async function inspectWorkspaceSnapshot(pmRoot,target){const fingerprint=await resolveSnapshotFingerprint(pmRoot,target),manifest=await readSnapshotJson(path.join(snapshotStore(pmRoot),"objects",fingerprint,"manifest.json"),target);if(manifest.schema!==SNAPSHOT_SCHEMA||manifest.fingerprint!==fingerprint)throw new PmCliError(`Snapshot manifest identity mismatch: ${target}`,EXIT_CODE.CONFLICT,{code:"workspace_snapshot_manifest_mismatch",required:"Use an intact snapshot whose manifest fingerprint matches its object path.",why:"Content identity must be verified before snapshot data is trusted.",examples:["pm workspace snapshot list --json"],nextSteps:["Inspect or recreate the snapshot before restoring it."]});return manifest}async function listWorkspaceSnapshots(pmRoot){const store=snapshotStore(pmRoot),objectNames=await readdir(path.join(store,"objects")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error))return[];throw error}),referenceNames=await readdir(path.join(store,"refs")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error))return[];throw error});return{objects:await Promise.all(objectNames.filter(name=>/^[a-f0-9]{64}$/.test(name)).sort().map(name=>inspectWorkspaceSnapshot(pmRoot,name))),references:await Promise.all(referenceNames.filter(name=>name.endsWith(".json")).sort().map(async name=>JSON.parse(await readFile(path.join(store,"refs",name),"utf8"))))}}async function planWorkspaceSnapshotRestore(pmRoot,target){const targetManifest=await inspectWorkspaceSnapshot(pmRoot,target),{manifest:currentManifest,contents:currentContentList}=await buildManifest(pmRoot),currentContents=new Map(currentManifest.files.map((file,index)=>[file,currentContentList[index]])),targetContents=await snapshotContents(path.join(snapshotStore(pmRoot),"objects",targetManifest.fingerprint,"files"),targetManifest.files),currentFiles=new Set(currentManifest.files),targetFiles=new Set(targetManifest.files),changedFiles=new Set([...currentFiles,...targetFiles]);for(const file of changedFiles){const currentContent=currentContents.get(file),targetContent=targetContents.get(file);currentContent!==void 0&&targetContent!==void 0&&currentContent.equals(targetContent)&&changedFiles.delete(file)}const affectedHistoryStreams=currentManifest.files.filter(file=>file.startsWith("history/")&&file.endsWith(".jsonl")).map(file=>{const currentEntries=lineCount(currentContents.get(file)),targetEntries=lineCount(targetContents.get(file));return{path:file,current_entries:currentEntries,target_entries:targetEntries,removed_entries:Math.max(0,currentEntries-targetEntries)}}).filter(entry=>entry.removed_entries>0).sort((left,right)=>left.path.localeCompare(right.path));return{target_fingerprint:targetManifest.fingerprint,current_fingerprint:currentManifest.fingerprint,changed_file_count:changedFiles.size,removed_file_count:[...currentFiles].filter(file=>!targetFiles.has(file)).length,added_file_count:[...targetFiles].filter(file=>!currentFiles.has(file)).length,removed_item_count:[...currentFiles].filter(file=>file.endsWith(".toon")&&!targetFiles.has(file)).length,affected_history_stream_count:affectedHistoryStreams.length,removed_history_entry_count:affectedHistoryStreams.reduce((total,entry)=>total+entry.removed_entries,0),affected_history_streams:affectedHistoryStreams,changes_authoritative_state:currentManifest.fingerprint!==targetManifest.fingerprint}}async function restoreWorkspaceSnapshotWithRecovery(pmRoot,target,options={}){if(options.force!==!0)throw new PmCliError("Workspace snapshot restore requires explicit force confirmation; inspect the impact with planWorkspaceSnapshotRestore or pm workspace snapshot restore <target> --dry-run, then retry with force",EXIT_CODE.USAGE,{code:"workspace_snapshot_force_required",required:"Preview the destructive impact, then explicitly confirm the restore.",why:"A restore replaces the complete authoritative tracker state.",examples:[`pm workspace snapshot restore ${target} --dry-run --json`,`pm workspace snapshot restore ${target} --force --json`],nextSteps:["Review the dry-run counts before retrying with --force."],recovery:{suggested_retry:`pm workspace snapshot restore ${target} --dry-run --json`}});const author=options.author?.trim()||"pm-sdk",lockTtlSeconds=options.lockTtlSeconds??60,lockWaitMs=options.lockWaitMs??5e3,workspaceLease=await acquireLockLease(pmRoot,WORKSPACE_WRITER_LOCK_ID,lockTtlSeconds,author,!1,!1,lockWaitMs),releaseWorkspaceLock=workspaceLease.release,heartbeat=new WorkspaceLockHeartbeat(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID),author,lockTtlSeconds);heartbeat.start(),await heartbeat.refreshNow();let staging,swapStarted=!1,heartbeatStopped=!1;try{const plan=await planWorkspaceSnapshotRestore(pmRoot,target),manifest=await inspectWorkspaceSnapshot(pmRoot,target),recovery=await createWorkspaceSnapshot(pmRoot),fingerprint=manifest.fingerprint,store=snapshotStore(pmRoot),source=path.join(store,"objects",fingerprint,"files"),parent=path.dirname(pmRoot),base=path.basename(pmRoot);staging=path.join(parent,`.${base}.restore-${crypto.randomUUID()}`);const backup=path.join(parent,`.${base}.backup-${crypto.randomUUID()}`);await withSnapshotFilesystemGuard("restore_stage",async()=>{await mkdir(staging,{recursive:!0}),await cp(source,staging,{recursive:!0,force:!1}),await mkdir(path.join(staging,"runtime"),{recursive:!0}),await cp(store,path.join(staging,SNAPSHOT_RUNTIME_PATH),{recursive:!0,force:!1})});const audit=await appendWorkspaceAuditEvent({pmRoot:staging,op:"workspace_snapshot_restore",author,message:options.message??`Restore workspace snapshot ${fingerprint}; recovery snapshot ${recovery.manifest.fingerprint}`,context:{target_fingerprint:fingerprint,pre_restore_fingerprint:recovery.manifest.fingerprint,changed_file_count:plan.changed_file_count,removed_file_count:plan.removed_file_count,removed_item_count:plan.removed_item_count,affected_history_stream_count:plan.affected_history_stream_count,removed_history_entry_count:plan.removed_history_entry_count},lockTtlSeconds,lockWaitMs}),auditHistoryPath=path.relative(staging,audit.historyPath).replaceAll("\\","/");await heartbeat.stop(),heartbeatStopped=!0;const stagedWorkspaceLock=getLockPath(staging,WORKSPACE_WRITER_LOCK_ID),stagedRoot=staging;return await workspaceLease.fence(async()=>{await mkdir(path.dirname(stagedWorkspaceLock),{recursive:!0}),await writeFile(stagedWorkspaceLock,await readFile(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID)),{flag:"wx"}),swapStarted=!0,await swapWorkspaceSnapshotRootWithActivation(stagedRoot,pmRoot,backup,DEFAULT_ATOMIC_OPERATIONS,async()=>{heartbeat.start(),heartbeatStopped=!1,await heartbeat.refreshNow()})}),await heartbeat.stop(),heartbeatStopped=!0,{manifest,plan,recovery_fingerprint:recovery.manifest.fingerprint,audit_history_path:auditHistoryPath,audit_operation:"workspace_snapshot_restore"}}catch(error){throw staging!==void 0&&!swapStarted&&await Promise.allSettled([rm(staging,{recursive:!0,force:!0})]),error}finally{try{heartbeatStopped||await heartbeat.stop()}catch{}finally{await releaseWorkspaceLock()}}}async function restoreWorkspaceSnapshot(pmRoot,target){return(await restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:!0,message:"Restore requested through the compatibility SDK signature"})).manifest}async function deleteWorkspaceSnapshot(pmRoot,target){validateSnapshotTarget(target);const store=snapshotStore(pmRoot);if(!/^[a-f0-9]{64}$/.test(target))return await removeSnapshotEntry(path.join(store,"refs",`${target}.json`),target,!1),{deleted:"reference",target};const{references}=await listWorkspaceSnapshots(pmRoot);if(references.some(reference=>reference.fingerprint===target))throw new Error(`Snapshot object ${target} is still referenced`);return await removeSnapshotEntry(path.join(store,"objects",target),target,!0),{deleted:"object",target}}export{SNAPSHOT_SCHEMA,WORKSPACE_SNAPSHOT_ACTIONS,_testOnlyWorkspaceSnapshot,createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,publishWorkspaceSnapshotObject,restoreWorkspaceSnapshot,restoreWorkspaceSnapshotWithRecovery,swapWorkspaceSnapshotRoot};
 //# sourceMappingURL=workspace-snapshot.js.map

package/dist/sdk/workspace.d.ts

@@ -28,10 +28,12 @@ export declare function isPathOutsideRoot(relativePath:string):boolean;
 /** Return the canonical pm ignore block rendered for the given workspace-relative tracker root (defaults to `.agents/pm`), primarily for documentation and tests. */
 export declare function getPmGitignoreBlock(trackerRelativeRoot?:string):string;
 /**
- * Idempotently create or replace the fenced pm cache block in a workspace
+ * Idempotently reconcile the fenced pm cache rules in a workspace
  * `.gitignore`. When `pmRoot` is provided the ignored runtime directories are
  * rendered under the resolved workspace-relative tracker root, so custom-root
  * workspaces (`--pm-path`/`PM_PATH`) stop committing runtime caches (GH-598).
+ * Sibling tracker rules are retained, and an explicitly root-layout tracker
+ * uses anchored repository-root rules rather than the default tracker path.
  * A tracker root outside the workspace needs no ignore rules here, so the
  * file is left untouched.
  */

package/dist/sdk/workspace.js

@@ -1,6 +1,9 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1de99e25-e132-5071-833e-37361b4cc7e6")}catch{}})();import{isFileMissingError}from"../core/fs/fs-utils.js";import{readFile,writeFile}from"node:fs/promises";import path from"node:path";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_GITIGNORE_START="# pm-cli:runtime-cache:start",PM_GITIGNORE_END="# pm-cli:runtime-cache:end",PM_GITIGNORE_DEFAULT_TRACKER_ROOT=".agents/pm",PM_GITIGNORE_RUNTIME_DIRECTORIES=["runtime/","search/","locks/","transactions/","checkpoints/"],PM_GITIGNORE_TRACKED_FILES=["search/eval-queries.json"];async function withGitignorePermissionRecovery(operation){try{return await operation()}catch(error){throw error instanceof Error&&"code"in error&&typeof error.code=="string"&&["EACCES","EPERM","EROFS"].includes(error.code)?new PmCliError("The workspace .gitignore is not writable.",EXIT_CODE.GENERIC_FAILURE,{code:"init_gitignore_unwritable",reason:error.code.toLowerCase(),required:"Grant the current user read and write access to the workspace .gitignore before initialization.",why:"pm init must publish its managed runtime-cache ignore fence without replacing unrelated entries.",nextSteps:["Grant read and write access to the workspace .gitignore and rerun pm init.","If the workspace is intentionally read-only, initialize pm in a writable workspace or clone."]}):error}}function normalizeTrackerRelativeRoot(trackerRelativeRoot){return trackerRelativeRoot.replaceAll("\\","/").replace(/^\.\/+/,"").replace(/\/+$/,"")}function isPathOutsideRoot(relativePath){const normalized=relativePath.replaceAll("\\","/");return path.isAbsolute(relativePath)||normalized===".."||normalized.startsWith("../")}function getPmGitignoreBlock(trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT){const root=normalizeTrackerRelativeRoot(trackerRelativeRoot);return[PM_GITIGNORE_START,...PM_GITIGNORE_RUNTIME_DIRECTORIES.map(directory=>directory==="search/"?`${root}/${directory}*`:`${root}/${directory}`),...PM_GITIGNORE_TRACKED_FILES.map(file=>`!${root}/${file}`),PM_GITIGNORE_END].join(`
-`)}async function ensurePmGitignore(workspaceRoot,options={}){const gitignorePath=path.join(workspaceRoot,".gitignore");let trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT;if(options.pmRoot!==void 0){const relative=normalizeTrackerRelativeRoot(path.relative(path.resolve(workspaceRoot),path.resolve(options.pmRoot)));if(isPathOutsideRoot(relative))return{path:gitignorePath,changed:!1};relative.length>0&&(trackerRelativeRoot=relative)}let current="";try{current=await withGitignorePermissionRecovery(()=>readFile(gitignorePath,"utf8"))}catch(error){if(!(error instanceof Error&&"code"in error&&isFileMissingError(error)))throw error}const start=current.indexOf(PM_GITIGNORE_START),end=current.indexOf(PM_GITIGNORE_END),prefix=(start>=0&&end>=start?`${current.slice(0,start)}${current.slice(end+PM_GITIGNORE_END.length)}`:current).trimEnd(),next=`${prefix.length>0?`${prefix}
-
-`:""}${getPmGitignoreBlock(trackerRelativeRoot)}
-`;return next===current?{path:gitignorePath,changed:!1}:(await withGitignorePermissionRecovery(()=>writeFile(gitignorePath,next,"utf8")),{path:gitignorePath,changed:!0})}export{PM_GITIGNORE_DEFAULT_TRACKER_ROOT,PM_GITIGNORE_END,PM_GITIGNORE_RUNTIME_DIRECTORIES,PM_GITIGNORE_START,PM_GITIGNORE_TRACKED_FILES,ensurePmGitignore,getPmGitignoreBlock,isPathOutsideRoot};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="38df9536-d87a-52ac-958d-091a17c9da9c")}catch{}})();import{isFileMissingError}from"../core/fs/fs-utils.js";import{readFile,realpath,stat,writeFile}from"node:fs/promises";import path from"node:path";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_GITIGNORE_START="# pm-cli:runtime-cache:start",PM_GITIGNORE_END="# pm-cli:runtime-cache:end",PM_GITIGNORE_DEFAULT_TRACKER_ROOT=".agents/pm";async function physicalInitPath(input){let ancestor=path.resolve(input);const missing=[];for(;;)try{const physical=await realpath(ancestor);if(!(await stat(physical)).isDirectory())throw Object.assign(new Error("Initialization path ancestry must be a directory."),{code:"ENOTDIR"});return path.join(physical,...missing)}catch(error){if(!isFileMissingError(error)||path.dirname(ancestor)===ancestor)throw error;missing.unshift(path.basename(ancestor)),ancestor=path.dirname(ancestor)}}const PM_GITIGNORE_RUNTIME_DIRECTORIES=["runtime/","search/","locks/","transactions/","checkpoints/"],PM_GITIGNORE_TRACKED_FILES=["search/eval-queries.json"];async function withGitignorePermissionRecovery(operation){try{return await operation()}catch(error){throw error instanceof Error&&"code"in error&&typeof error.code=="string"&&["EACCES","EPERM","EROFS"].includes(error.code)?new PmCliError("The workspace .gitignore is not writable.",EXIT_CODE.GENERIC_FAILURE,{code:"init_gitignore_unwritable",reason:error.code.toLowerCase(),required:"Grant the current user read and write access to the workspace .gitignore before initialization.",why:"pm init must publish its managed runtime-cache ignore fence without replacing unrelated entries.",nextSteps:["Grant read and write access to the workspace .gitignore and rerun pm init.","If the workspace is intentionally read-only, initialize pm in a writable workspace or clone."]}):error}}function normalizeTrackerRelativeRoot(trackerRelativeRoot){const root=trackerRelativeRoot.split(path.sep).join("/").replace(/^\.\/+/,"");let end=root.length;for(;end>0&&root[end-1]==="/";)end-=1;return root.slice(0,end)}function isPathOutsideRoot(relativePath){const normalized=relativePath.replaceAll("\\","/");return path.isAbsolute(relativePath)||normalized===".."||normalized.startsWith("../")}function getPmGitignoreBlock(trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT){const root=normalizeTrackerRelativeRoot(trackerRelativeRoot);if(/[\r\n]/u.test(root))throw new PmCliError("A tracker path containing a line break cannot be represented safely in .gitignore.",EXIT_CODE.USAGE,{code:"invalid_argument_value",required:"a tracker path without line breaks",nextSteps:["Choose a tracker path without carriage returns or newlines and rerun pm init."]});const literalRoot=root.replace(/[\\*?[\]#! \t]/gu,"\\$&");return[PM_GITIGNORE_START,...PM_GITIGNORE_RUNTIME_DIRECTORIES.map(directory=>directory==="search/"?`${literalRoot}/${directory}*`:`${literalRoot}/${directory}`),...PM_GITIGNORE_TRACKED_FILES.map(file=>`!${literalRoot}/${file}`),PM_GITIGNORE_END].join(`
+`)}function mergeTrackerIgnoreRules(lines,trackerRoot,rules){const literalRoot=trackerRoot.replace(/[\\*?[\]#! \t]/gu,"\\$&"),prefixes=[...new Set([trackerRoot,literalRoot])].flatMap(root=>PM_GITIGNORE_RUNTIME_DIRECTORIES.flatMap(directory=>[`${root}/${directory}`,`!${root}/${directory}`])),merged=[];let replaced=!1;for(const line of lines)prefixes.some(prefix=>line.startsWith(prefix))?(replaced||merged.push(...rules),replaced=!0):merged.push(line);return replaced||merged.push(...rules),merged}function managedGitignoreBlocks(current){const blocks=[];let start=-1,bodyStart=0,offset=0;for(const line of current.split(`
+`)){const marker=line.endsWith("\r")?line.slice(0,-1):line;marker===PM_GITIGNORE_START?(start=offset,bodyStart=offset+line.length+1):marker===PM_GITIGNORE_END&&start>=0&&(blocks.push({index:start,end:offset+marker.length,lines:current.slice(bodyStart,offset).split(/\r?\n/u).filter(entry=>entry.length>0)}),start=-1),offset+=line.length+1}return blocks}function reconcileGitignoreContent(current,trackerRoot){const newline=current.includes(`\r
+`)?`\r
+`:`
+`,rules=getPmGitignoreBlock(trackerRoot).split(`
+`).slice(1,-1),blocks=managedGitignoreBlocks(current),existingRules=blocks.flatMap(entry=>entry.lines),block=[PM_GITIGNORE_START,...mergeTrackerIgnoreRules(existingRules,trackerRoot,rules),PM_GITIGNORE_END].join(newline);if(blocks.length===0){const separator=current.length===0?"":current.endsWith(`
+`)?newline:`${newline}${newline}`;return`${current}${separator}${block}${newline}`}let next=current;for(const[index,match]of[...blocks.entries()].reverse())next=`${next.slice(0,match.index)}${index===0?block:""}${next.slice(match.end)}`;return next}async function ensurePmGitignore(workspaceRoot,options={}){const gitignorePath=path.join(workspaceRoot,".gitignore");let trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT;if(options.pmRoot!==void 0){const relative=normalizeTrackerRelativeRoot(path.relative(await physicalInitPath(workspaceRoot),await physicalInitPath(options.pmRoot)));if(isPathOutsideRoot(relative))return{path:gitignorePath,changed:!1};trackerRelativeRoot=relative}let current="";try{current=await withGitignorePermissionRecovery(()=>readFile(gitignorePath,"utf8"))}catch(error){if(!(error instanceof Error&&"code"in error&&isFileMissingError(error)))throw error}const next=reconcileGitignoreContent(current,trackerRelativeRoot);return next===current?{path:gitignorePath,changed:!1}:(await withGitignorePermissionRecovery(()=>writeFile(gitignorePath,next,"utf8")),{path:gitignorePath,changed:!0})}export{PM_GITIGNORE_DEFAULT_TRACKER_ROOT,PM_GITIGNORE_END,PM_GITIGNORE_RUNTIME_DIRECTORIES,PM_GITIGNORE_START,PM_GITIGNORE_TRACKED_FILES,ensurePmGitignore,getPmGitignoreBlock,isPathOutsideRoot};
 //# sourceMappingURL=workspace.js.map

package/docs/CONFIGURATION.md

@@ -82,7 +82,7 @@ If the existing project `settings.json` has invalid JSON, a configuration write
 | `item_format`                              | item storage format (`toon` writes; legacy markdown is read/migrate only)                                                                                                                             |
 | `output.default_format`                    | default renderer, usually `toon`                                                                                                                                                                      |
 | `locks.ttl_seconds`                        | stale lock threshold                                                                                                                                                                                  |
-| `locks.wait_ms`                            | bounded jittered wait budget before a contended item mutation returns `lock_conflict` (default `3000`; set `0` to fail fast)                                                                          |
+| `locks.wait_ms`                            | wait budget before a contended lock returns `lock_conflict`; item-store mutations, restore and the hierarchy lock restart it on each owner handoff (120 s cap), other locks use it as a fixed total (default `3000`; `0` fails fast) |
 | `history.missing_stream`                   | `auto_create` or `strict_error`                                                                                                                                                                       |
 | `history.compact_policy.enabled`           | enable the compaction advisory: `pm health` warns on over-threshold streams (default `false`); when disabled, `max_entries`/`trigger` are inert                                                       |
 | `history.compact_policy.max_entries`       | when the policy is enabled, the entry count above which a stream is flagged by `pm health` and the default `pm history-compact --all-over` threshold (default `500`)                                  |
@@ -115,7 +115,18 @@ receipt before removal; it records the original owner and is an attempted
 recovery audit, not proof that a later mutation committed. Keep these local
 runtime receipts out of version control.
 
-For expected live contention, set `PM_LOCK_WAIT_MS` to a larger bounded
+For item-store mutations (update, close, claim, comments, notes and the other
+item-store writes), restore and the hierarchy-integrity lock (parented creates,
+parent changes and integrity-sensitive dependency additions) the wait budget
+measures stalls, not queue length: while other writers keep acquiring and releasing the
+lock, a waiter keeps waiting (up to 120 s total), so many concurrent agents on
+one tracker queue instead of failing. Other lock users, including package import
+commits and internal short-lived locks, keep a fixed total budget. A lock held by
+the same owner for the whole budget still refuses with `lock_conflict`, whose
+recovery reports `waited_ms` and `owner_handoffs`. A writer whose lease expired
+and was taken over refuses its commit with `lock_lost` instead of overwriting
+the newer write; re-read and apply the change again. For an owner that is
+expected to hold the lock longer, set `PM_LOCK_WAIT_MS` to a larger bounded
 millisecond budget, or configure `locks.wait_ms`, and retry the same operation.
 CLI recovery preserves its normalized arguments and quoted values, including
 whitespace and empty argument strings. Malformed argument vectors are omitted
@@ -167,7 +178,7 @@ underscore aliases remain accepted for compatibility.
 | `PM_AUTHOR`                       | optional explicit session-wide mutation author override                                                                  |
 | `PM_PATH`                         | override project tracker root for tests or sandboxes                                                                     |
 | `PM_GLOBAL_PATH`                  | override global profile root for tests or sandboxes                                                                      |
-| `PM_LOCK_WAIT_MS`                 | per-process override for `locks.wait_ms`; non-negative integer milliseconds, with `0` restoring fail-fast lock conflicts |
+| `PM_LOCK_WAIT_MS`                 | per-process override for the `locks.wait_ms` budget (a no-progress window only where that lock uses the progress policy); non-negative integer milliseconds, with `0` restoring fail-fast lock conflicts |
 | `PM_OLLAMA_MODEL`                 | choose default Ollama embedding model                                                                                    |
 | `PM_DISABLE_OLLAMA_AUTO_DEFAULTS` | disable implicit Ollama search defaults                                                                                  |
 | `PM_CONTEXT_USAGE_DISABLED`       | set to `1` to disable the derived context/next usage-feedback ledger with zero filesystem reads or writes                |
@@ -177,6 +188,20 @@ For command-level tracker targeting, prefer `--pm-path <tracker-root>`. The old
 itself, not the repository workspace. During `pm init`, explicit tracker paths
 that look like workspace roots are rejected unless `--force` is provided.
 
+Initialization maintains the repository's runtime-cache `.gitignore` fence for
+every tracker sharing that repository. Initializing or reinitializing a nested
+tracker preserves the enclosing tracker's exclusions and unrelated user rules.
+Equivalent physical and symlink-addressed paths share the same containment
+check, including tracker directories that initialization has not created yet.
+A symlink leading outside the repository remains an external tracker and does
+not add rules here. This boundary is tracked by
+[pm-p8s5k7e6lhda](../.agents/pm/issues/pm-p8s5k7e6lhda.toon).
+Custom tracker paths are literal Git paths, including spaces and wildcard
+characters. An intentional root-layout tracker uses repository-root exclusions.
+Paths containing line breaks are refused because `.gitignore` cannot safely
+represent them. Curated `search/eval-queries.json` files remain trackable in
+each tracker. See [merge safety](MERGE_SAFETY.md#runtime-receipts-and-retention).
+
 Implicit discovery checks the current directory and its ancestors up to the
 nearest `.git` directory or file, including worktrees and submodules. An
 uninitialized repository selects its own `.agents/pm` and returns initialization

package/docs/DEVELOPMENT_DEPENDENCY_SECURITY.md

@@ -36,6 +36,11 @@ immediately before SDK assurance evaluation, which verifies advisory evidence
 before slower providers. The blocking registry command settles before OSV starts
 its network deadlines.
 
+CI retains this single receipt after successful and failed static jobs, with a
+separate artifact name for each run attempt and seven-day retention. Inspect both
+feeds before diagnosing a blocked collector: a positive advisory is a refusal,
+even when the other feed is clean.
+
 The command then verifies the installed CodSpeed bundle policy. Network/audit errors,
 missing packages, incomplete policy entries, changed package files, and unreviewed
 upgrades all fail. `quality:static` includes this command, so the existing CI,
@@ -50,6 +55,31 @@ defaults to the `latest` image. The workflow contract checks both values on
 every TruffleHog step. Recheck the action's executable selectors when renewing
 its commit pin.
 
+## Vitest mocker advisory pair
+
+[pm-vitest4112](../.agents/pm/tasks/pm-vitest4112.toon) coordinates the
+[manual-registration finding](../.agents/pm/issues/pm-vitestmanual.toon) and
+[Windows redirect finding](../.agents/pm/issues/pm-vitestredirect.toon).
+[GHSA-qxg6-89mg-rqv8](https://github.com/advisories/GHSA-qxg6-89mg-rqv8)
+and [GHSA-xp26-3454-mjgp](https://github.com/advisories/GHSA-xp26-3454-mjgp)
+affect the previously locked `@vitest/mocker` 4.1.11. The compatible Vitest and
+coverage-provider pair now requires 4.1.12, whose shared mock-source generator
+serializes module URLs and export names, including asynchronous rebinding, and
+whose public redirect handler normalizes backslashes before the file allowlist
+check. Both fixes apply to public mocker/interceptor WebSocket handlers. The
+repository's Node test configurations do not register these handlers, so the
+affected development dependency does not establish an exploitable CLI or SDK
+route.
+
+The retained hosted OSV receipt identified both advisories while the registry
+audit returned zero. Keep full-lock admission mandatory and verify the patched
+graph against both feeds. This patch keeps Vitest 4, the CodSpeed peer contract
+and the Vite 7 override; the broader Vitest 5 migration remains separate. The
+installed-handler regressions run in coverage and the required native Windows
+cohort, whose aggregate refuses failed, canceled or skipped partitions. The
+October 15 patch releases meet pnpm's one-day minimum age on October 21 without
+an exclusion. Dependabot's seven-day scheduling cooldown is unchanged.
+
 ## Indexed source-map offsets
 
 [pm-dba47](../.agents/pm/issues/pm-dba47.toon) tracks Dependabot alert 47 and

package/docs/EXTENSION_AUTHOR_CONTRACTS.md

@@ -76,8 +76,9 @@ Create path:
 `mutateItem` path:
 
 - Used by `pm update`, `pm close`, `pm claim`, `pm release`, `pm restore`, `pm delete`, and other mutations of existing items.
-- Locates the item, acquires the lock, reads the item through the `onRead` hook, enforces ownership and history policy, applies the mutation, consults `item_store_write`, writes the item atomically, appends history, fires `onWrite` for the item and history stream, records the after-command affected-item snapshot, then releases the lock.
+- Locates the item, acquires the lock, reads the item through the `onRead` hook, enforces ownership and history policy, applies the mutation, enters the commit fence, consults `item_store_write`, writes the item atomically, appends history, fires `onWrite` for the item and history stream, records the after-command affected-item snapshot, then releases the lock.
 - `item_store_write` handlers can redirect the target path, replace serialized contents, or skip the physical item write.
+- The commit fence verifies the lock lease and the stored item revision first. When the lease was taken over (`lock_lost`) or the item changed after the read (`stale_revision`), the mutation refuses before `item_store_write` or `item_store_delete` (non-dry-run) runs, so a handler that persists the payload itself never commits a refused write.
 
 Both paths guarantee:
 

package/docs/EXTENSION_LIFECYCLE.md

@@ -4,6 +4,9 @@ Tracked by [pm-ig5cfe](../.agents/pm/issues/pm-ig5cfe.toon),
 [pm-495lkc](../.agents/pm/issues/pm-495lkc.toon), and
 [pm-miy5k6](../.agents/pm/issues/pm-miy5k6.toon).
 Static inventory is tracked by [pm-lhhnx9](../.agents/pm/issues/pm-lhhnx9.toon).
+Verified replacements and disabled compatibility findings are tracked by
+[pm-c9wz5ef4ulnv](../.agents/pm/issues/pm-c9wz5ef4ulnv.toon) and
+[pm-5xn8we1wue0m](../.agents/pm/issues/pm-5xn8we1wue0m.toon).
 
 ## Read-only configured inventory
 
@@ -32,6 +35,45 @@ each. Use `pm install npm:<package>` to force npm identity or the reported bare
 alias command to force the bundled package. Install-all results carry the same
 receipt on every package row.
 
+## Verified replacements
+
+`pm package install` and the SDK's `runExtension(source, { install: true }, global)`
+retain the previous installation through fresh-module runtime verification and
+contribution persistence. When a copied replacement fails to load or activate,
+pm restores the previous package tree and exact managed/settings content. A
+settings restoration appends a compensating workspace-history event.
+
+The failed attempt still returns `ok: false` and its candidate diagnostics, with
+`previous_state_preserved: true`, `overwritten: false`, and
+`rollback.status: "restored"`. The previous command remains available in a new
+process. Multi-target and install-all receipts retain these fields per package.
+SDK `ExtensionCommandResult` / `PackageCommandResult` consumers can narrow
+`details.rollback.status` to access typed recovery arguments on failed restoration.
+These two diagnostic keys are now reserved typed fields. Code constructing
+lifecycle result objects or test doubles must use the boolean and rollback
+shapes, or rename custom metadata stored under those keys. Ordinary result
+readers remain compatible; the runtime implementation is unchanged by this
+declaration refinement.
+
+If restoration fails, `previous_state_preserved` is false. The retained backup
+and executable `rollback.recovery_args` / `rollback.recovery_command` identify a
+source for reinstalling the previous package. Resolve the reported filesystem
+failure first. Fresh installations and installations whose source is already
+the destination retain failed code for diagnosis and report
+`previous_state_preserved: false`; they have no earlier package version to
+recover. Package code can have external side effects during activation; this
+snapshot protects the installation and its managed/settings content.
+
+## Disabled package compatibility
+
+An explicitly disabled package remains visible in inventory and discovery.
+Its host-version warnings use `extension_disabled_pm_*` codes and are advisory
+in health, including `--strict-exit`. Each finding identifies the package,
+required bound and scoped activation command to use after satisfying that
+bound. Enabled packages retain the ordinary `extension_pm_*` compatibility
+checks and blocking policy. Deactivation does not permit incompatible code to
+load or suppress malformed-manifest, missing-entry or other unrelated findings.
+
 ## Durable Extension Migrations
 
 Active packages register schema migrations through `api.registerMigration`.
@@ -62,3 +104,8 @@ compose without warnings, and runtime invokes only the matching owner. Empty or
 omitted command ownership retains the legacy global behavior and collides with
 every other override. Activation summaries and persisted contribution
 inventories expose `preflight_ownership` for static doctor and tooling output.
+
+Rollback failures retain the initial error as their cause and expose an original
+typed refusal as `context.original_code`, while keeping the rollback code and
+exit policy. This diagnostic boundary is tracked by
+[pm-4vymxc](../.agents/pm/issues/pm-4vymxc.toon).

package/docs/MCP_OPTION_CONFORMANCE.md

@@ -1,12 +1,38 @@
 # MCP Option Conformance
 
-Tracked by [pm-v0s2rm](../.agents/pm/chores/pm-v0s2rm.toon).
+Tracked by [pm-v0s2rm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-v0s2rm.toon), [pm-gh1538](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1538.toon), and [pm-ap7ilf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ap7ilf.toon).
+These repository-only tracking records are excluded from npm.
 
 An integration test can pass while an undeclared option is ignored. That leaves
 the test asserting a behavior it never exercised. The repository therefore
 treats emitted MCP unknown-option diagnostics as test failures, while the
 production server retains its advisory warning behavior for clients.
 
+`pm_create` and `pm_update` accept the canonical mutation fields advertised by
+their input schemas either at the top level or inside `options`. `pm_run` with
+the corresponding action uses the same SDK normalization. Explicit nested
+options take precedence, including CLI
+aliases for the same field. Repeatable inputs, numeric values, and linked-resource
+aliases use the shared mutation contracts before persistence. Native SDK `run`
+callers continue to put update fields inside `options`.
+
+Malformed option containers, values discarded from known scalar fields, and malformed repeatable
+entries refuse before execution with `invalid_argument_value` and
+`changed: false`. Declared boolean mutation fields, their aliases, and receipt
+controls must be booleans, including `false`; this covers clear/replace flags,
+parent/dependency exceptions, duplicate allowance, and `force`. These checks preserve project-defined
+custom fields and template-based type resolution while preventing a bad field
+from disappearing as a sibling field is written.
+Array values that become CLI CSV inputs, such as `tags`, must contain only
+strings and are checked before conversion. Validation follows nested precedence:
+an explicit valid nested value replaces a flat value before either is normalized.
+
+For example, `{ "id": "pm-one", "options": {}, "priority": 4 }` changes priority;
+with `"options": { "priority": 2 }`, priority becomes `2`. Create also honors its
+advertised explicit `id`, `deadline`, and other metadata. Regressions check the
+discovered schema, persisted values and verified history, and compare item and
+history bytes after invalid mutations to prove atomic refusal.
+
 Every run using [vitest.config.ts](../vitest.config.ts) installs
 [McpContractReporter](../scripts/mcp-contract-reporter.mts). The reporter records
 the emitting file, full test name, option, tool, and action, and rejects the run

package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md

@@ -3,7 +3,8 @@
 Tracker references: [pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon),
 [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
 [pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon), and
-[pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon).
+[pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon), and executable probes
+[pm-gh1540](../.agents/pm/issues/pm-gh1540.toon).
 
 pm exposes the same MCP 2026-07-28 dispatcher through two adapters:
 
@@ -20,6 +21,20 @@ thin bindings over those contracts.
 
 ## Run the HTTP adapter
 
+Both executables accept `--help` / `-h` and `--version` / `-V`. These probes
+return before reading transport settings, opening stdin, or binding a listener,
+including when server configuration is invalid. Help includes configuration,
+supported protocol revisions, and a version-pinned client or launch example.
+No arguments starts the selected transport. Unsupported arguments return usage
+exit code 64 with a help command. Server configuration uses environment variables.
+
+Embedded launchers can import `resolvePmMcpExecutableInvocation` and its
+`PmMcpExecutableTransport` / `PmMcpExecutableInvocation` types from
+`@unbrained/pm-cli/sdk/contracts` or the aggregate SDK. This pure function takes
+the argument vector, transport, and package version, and returns either a
+`serve` decision or an `exit` decision with stdout, stderr, and exit code.
+It does not read the environment, workspace, or process streams.
+
 The safe default binds only `127.0.0.1:3000`:
 
 ```bash

package/docs/MERGE_SAFETY.md

@@ -667,6 +667,14 @@ Never remove conflict markers manually while leaving the authoritative item and
 
 `transactions/` and `checkpoints/` are per-branch crash-recovery state, not shared project context. `pm init` places both below the resolved tracker root in the managed `.gitignore` block, including custom `--pm-path` roots.
 
+Each tracker sharing a repository retains its own cache exclusions and merge
+patterns in either initialization order. Tracker names containing Git wildcard
+characters are escaped as literal paths, while the generated item/history globs
+remain active. Unrelated user rules and curated evaluation files are preserved.
+These contracts are tracked by
+[pm-nl60tbxzkjwp](../.agents/pm/issues/pm-nl60tbxzkjwp.toon) and
+[pm-47wuv8awpqvj](../.agents/pm/issues/pm-47wuv8awpqvj.toon).
+
 Ignore rules do not remove files that were already committed. `pm health`
 (`integrity`) and `pm validate` (`storage_integrity`) therefore scan Git's
 index for tracked files below `runtime/`, `search/`, `locks/`,

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -85,8 +85,87 @@ If brief still exceeds the ceiling, normal compaction and eventual refusal
 apply. `estimated_tokens` measures the emitted envelope;
 `omitted_result_estimated_tokens` measures the useful result that could not fit.
 
+## Typed producer pages
+
+Tracked by [pm-oybmsd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-oybmsd.toon),
+[pm-jqgkis](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-jqgkis.toon), and
+[pm-qal1uw](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-qal1uw.toon)
+(repository-only tracker records excluded from npm).
+Native `PmClient.list`, `search`, and `context` reads and their standalone
+convenience functions return sparse metadata when `after` resumes a producer
+page. Retain the first page's filters, projection, sorting, totals and completeness
+certificate. Subsequent pages carry `continuation_contract` with
+`metadata: "reference"` and `restore_with: "omit --after"`; repeated metadata
+is optional in `PmReadOutputProducerContinuation<Result>`. Follow `next_cursor`
+until it is empty, rather than relying on the optional `has_more` field.
+
+Calls whose options contain no producer cursor retain their first-page types.
+Omitting the options argument has the same precise type as passing `{}` for
+client and standalone `list`, `context`, and `search` calls; it does not imply
+that an explicit budget, session, or output cursor was supplied.
+Options with an optional cursor can return either page shape. When a budget,
+session, or output cursor is possible, first use `isReadOutputBudgetExceeded`
+to narrow the omission branch before accessing rows. This remains required for
+unions of option shapes: a budgeted variant cannot be erased by an unbudgeted
+variant. The low-level query producers retain their original result contracts;
+metadata suppression belongs to the shared native SDK transport.
+
+```ts
+const first = await client.list({ brief: true, limit: "10" });
+consume(first.items);
+let cursor = first.next_cursor;
+while (cursor) {
+  const page = await client.list({ brief: true, limit: "10", after: cursor });
+  consume(page.items);
+  cursor = page.next_cursor;
+}
+```
+
 ## Cross-Call Context Sessions
 
+Typed session results are tracked by
+[pm-t1p1jv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-t1p1jv.toon)
+(repository-only tracker record excluded from npm). After narrowing budget
+omission with `isReadOutputBudgetExceeded`, use `isReadOutputSessionReference`
+from the SDK or `sdk/core` before accessing row prose or a search hit's nested
+`item`. A reference contains only `id` and `context_ref`. Calls with no session,
+including calls that specify only an output budget, retain their ordinary row
+types. The direct `applyReadOutputDimensions` helper also infers session
+capability from its options, including the accepted `output_session` spelling.
+Unspecified or explicitly undefined session options retain ordinary rows;
+optional, union, or dynamically typed session options admit references.
+`PmReadOutputSessionResult<Result>` models literal `row_contract.row_keys`
+paths (including nested arrays and keyed maps). Dynamic path declarations
+conservatively admit references in nested collections, and envelopes without a
+row declaration use the top-level array fallback. Keep package row paths literal
+with `as const` to preserve precision in package result declarations.
+
+```ts
+const page = await client.context({ outputSession: sessionState });
+if (!isReadOutputBudgetExceeded(page)) {
+  for (const row of page.high_level) {
+    if (isReadOutputSessionReference(row)) consumeReference(row.context_ref);
+    else consumeTitle(row.title);
+  }
+}
+```
+
+Read-option recovery is tracked by
+[pm-7gpx34](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7gpx34.toon)
+(repository-only tracker record excluded from npm). For explicit static encoding,
+use `--output-format toon|json` across read commands. Completeness uses
+`--output-include full` on list, search and get; context detail depth uses
+`--depth full`. These controls retain the normal row and token ceilings.
+When `context --full`, `list/search --depth full`, or `--toon` on list, search,
+context or get is refused,
+the error provides `recovery.suggested_retry_args` for the same command with the
+supported spelling. The SDK's `resolveReadOptionRetryArgs` exposes the same
+token-preserving correction. Conflicting controls or ambiguous operands do not
+receive a guessed retry.
+An explicit `--json` conflicts with `--toon`, so that invocation receives no
+encoding-changing retry. Non-conflicting TOON refusals include the corrected
+command in human output without requiring JSON diagnostics.
+
 `--output-session <json>` / `outputSession` composes the four per-call
 dimensions across a request group. The caller supplies versioned state and
 passes the returned `read_session.next_state` to the next read:

package/docs/RELATIONSHIP_GRAPH.md

@@ -238,6 +238,21 @@ Every returned node is explainable: `role` names its semantic family (`prerequis
 
 `meta.completeness` reports result quality: the exact in-memory kernel emits `complete` or `truncated`, and the contract reserves `sampled`, `approximate`, `stale_index`, and `redacted` for index-backed or policy-filtered providers so consumers can branch on one field.
 
+The packer orders direct prerequisite and ancestor endpoints before optional
+descendants or related nodes, reserves their direct relationship costs, and
+emits root-incident edges first. An oversized edge is skipped so later feasible
+edges can still be returned. The same order governs cursor pages; the cursor
+fingerprint identifies this packing policy and rejects earlier-policy cursors. An
+edge limit or a budget too small for an endpoint and its edges can still omit
+evidence: inspect the direct-family totals, omitted counts and completeness
+before using the packet to make a decision. The native adapter also reports
+`relationship_context_bounds` in `omission_receipt` whenever the producer is
+truncated. Increase the relevant bounds or follow the node cursor for more
+detail; a full projection alone does not remove traversal limits.
+
+Tracked by [pm-gh1534](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1534.toon)
+(repository tracker records are excluded from npm).
+
 Node, edge, depth, kind, direction, and token bounds are independent. The cursor fingerprint covers semantic filters and traversal shape, so it is rejected when reused for a different root or query. Output remains a plain object suitable for TOON, JSON, JSONL, MCP, or a custom UI; adapters own rendering and do not reimplement traversal.
 
 The native adapter is `pm deps <id> --format context`. It is also available through `PmClient.deps`, `runAction({ action: "deps" })`, and the MCP `pm_deps` tool. `--max-depth`, `--node-limit`, `--edge-limit`, `--token-budget`, `--cursor`, `--direction`, and repeatable or comma-separated `--kind` map directly to the public SDK context options; `--summary` keeps only counts. Unknown `--kind` values fail fast with the registered-kind list instead of silently matching nothing. Tree and graph formats share those first four bounds, use safe defaults when omitted, and report deterministic truncation metadata instead of recursively expanding a cyclic or multiply-linked graph without limit.

package/docs/RELEASING.md

@@ -171,6 +171,15 @@ configuration belong in private operator documentation.
   result before candidate provenance, proves publication, and exits without
   evaluating the generated release commit as a new candidate
 
+Dependency advisory diagnostics are tracked by
+[pm-z20n3s](../.agents/pm/tasks/pm-z20n3s.toon). Both Auto Release and Release
+retain the original `.cache/dependency-security/receipt.json` after the gate,
+including failures, as `dependency-advisory-<run-id>-<attempt>` for seven days.
+Only that public receipt is uploaded, with explicit hidden-file inclusion.
+It records registry and OSV findings or unavailable evidence without raw
+stderr, credentials, telemetry, or sibling caches. Missing receipts warn rather
+than masking the original failure. Retention never changes the gate verdict.
+
 Pipeline entrypoint:
 
 ```bash
@@ -315,6 +324,14 @@ missing locked package. npm 12 ignores published shrinkwraps; shipping
 a shrinkwrap alone therefore cannot enforce this contract. SDK consumers
 supply the bounded optional Node types peer themselves.
 
+Physical entrypoint verification is tracked by
+[pm-tl7vlu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-tl7vlu.toon)
+(repository-only tracker record excluded from npm). The dependency advisory CLI
+resolves both its invocation and module to physical paths, so directory aliases
+and Node's symlink-preserving main-module mode still execute verification and
+return a receipt or failure status. Module imports expose the collector without
+starting verification.
+
 Push the final implementation commit through a reviewed pull request first,
 wait for DeepScan and CodeFactor to finish on that reviewed SHA, then run the
 canonical registry-owned preflight: