@unbrained/pm-cli 2026.10.3 → 2026.10.5

package/dist/sdk/workspace-transaction.js

@@ -1,3 +1,3 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d9ef3878-afce-5983-8fe9-8a896f82d0a7")}catch(e2){}})();import{mkdir,readFile}from"node:fs/promises";import path from"node:path";import{acquireLock}from"../core/lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{nowIso}from"../core/shared/time.js";class WorkspaceTransactionInterruptedError extends Error{constructor(message="Workspace transaction interrupted"){super(message);this.name="WorkspaceTransactionInterruptedError"}}const WORKSPACE_TRANSACTION_LOCK_ID="sdk-workspace-transaction";const TRANSACTION_ID_PATTERN=/^[a-zA-Z0-9._-]+$/;const DEFAULT_LOCK_TTL_SECONDS=30;const DEFAULT_LOCK_WAIT_MS=3e3;function requiredIdentifier(value,label){if(typeof value!=="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized||!TRANSACTION_ID_PATTERN.test(normalized))throw new TypeError(`${label} must match [a-zA-Z0-9._-]+`);return normalized}function requiredText(value,label){if(typeof value!=="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized)throw new TypeError(`${label} must be non-empty`);return normalized}function validateWorkspaceTransactionIdentity(options){return{pmRoot:requiredText(options.pmRoot,"Transaction pmRoot"),transactionId:requiredIdentifier(options.transactionId,"Transaction id"),author:requiredText(options.author,"Transaction author")}}function positiveInteger(value,fallback,label){const resolved=value??fallback;if(!Number.isInteger(resolved)||resolved<=0)throw new TypeError(`${label} must be a positive integer`);return resolved}function journalPath(pmRoot,transactionId){return path.join(pmRoot,"transactions","sdk",`${transactionId}.json`)}async function writeJournal(pmRoot,journal){journal.updatedAt=nowIso();const target=journalPath(pmRoot,journal.transactionId);await mkdir(path.dirname(target),{recursive:true});await writeFileAtomic(target,`${JSON.stringify(journal,null,2)}
-`)}function hasValidJournalMetadata(journal){return Number.isInteger(journal.attempt)&&typeof journal.author==="string"&&typeof journal.createdAt==="string"&&typeof journal.updatedAt==="string"}function createResultMap(source){return Object.assign(Object.create(null),source)}function cloneJournalValue(value,label){try{const serialized=JSON.stringify(value,(_key,nestedValue)=>{if(typeof nestedValue==="number"&&!Number.isFinite(nestedValue))throw new TypeError(`${label} contains a non-finite number`);if(nestedValue===void 0||typeof nestedValue==="function"||typeof nestedValue==="symbol")throw new TypeError(`${label} contains a non-JSON value`);return nestedValue});return JSON.parse(serialized)}catch(error){throw new TypeError(`${label} must be JSON serializable`,{cause:error})}}function cloneOptionalJournalValue(value,label){return value===void 0?void 0:cloneJournalValue(value,label)}function setJournalEntry(target,stepId,value,label){const cloned=cloneOptionalJournalValue(value,label);if(cloned===void 0)delete target[stepId];else target[stepId]=cloned}function isJournalMap(value){return value!==null&&typeof value==="object"&&!Array.isArray(value)}function hasUniqueKnownStepIds(value,stepIds){return Array.isArray(value)&&new Set(value).size===value.length&&value.every(stepId=>typeof stepId==="string"&&stepIds.includes(stepId))}function hasValidJournalLifecycle(journal,stepIds){if(!hasUniqueKnownStepIds(journal.startedStepIds,stepIds)||!hasUniqueKnownStepIds(journal.completedStepIds,stepIds)||!isJournalMap(journal.results)||!isJournalMap(journal.compensationData))return false;const startedStepIds=journal.startedStepIds;const started=new Set(startedStepIds);const completedStepIds=journal.completedStepIds;const completed=new Set(completedStepIds);if(Object.keys(journal.compensationData).some(stepId=>!started.has(stepId))||Object.keys(journal.results).some(stepId=>!completed.has(stepId)))return false;if(journal.status==="committed")return stepIds.every(stepId=>completed.has(stepId));return journal.status!=="compensated"||completed.size===0&&started.size===0}function parseJournal(raw,transactionId,stepIds){let parsed;try{parsed=JSON.parse(raw)}catch{throw new TypeError(`Workspace transaction ${transactionId} journal is invalid JSON`)}if(!parsed||typeof parsed!=="object"||Array.isArray(parsed))throw new TypeError(`Workspace transaction ${transactionId} journal is invalid`);const journal=parsed;const identityMatches=journal.schemaVersion===1&&journal.transactionId===transactionId;const stepsMatch=Array.isArray(journal.stepIds)&&journal.stepIds.length===stepIds.length&&journal.stepIds.every((stepId,index)=>stepId===stepIds[index]);const lifecycleMatches=hasValidJournalLifecycle(journal,stepIds);const metadataMatches=hasValidJournalMetadata(journal);const statusMatches=["applying","compensating","compensated","committed"].includes(String(journal.status));if(!identityMatches||!stepsMatch||!lifecycleMatches||!metadataMatches||!statusMatches)throw new TypeError(`Workspace transaction ${transactionId} journal does not match the supplied plan`);return{...journal,results:createResultMap(journal.results),compensationData:createResultMap(journal.compensationData)}}async function prepareJournalForApply(options,transactionId,author,stepIds,existing){let journal=existing;const recovered=journal!==void 0;if(journal?.status==="compensating")await compensateAppliedSteps(options,journal);if(journal===void 0||journal.status==="compensated"){const timestamp=nowIso();journal={schemaVersion:1,transactionId,author,status:"applying",attempt:(journal?.attempt??0)+1,createdAt:journal?.createdAt??timestamp,updatedAt:timestamp,stepIds,startedStepIds:[],completedStepIds:[],results:createResultMap(),compensationData:createResultMap()};await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"prepared")}return{journal,recovered}}async function applyPreparedTransaction(options,journal,recovered){try{await discoverAppliedSteps(journal,options.steps);await writeJournal(options.pmRoot,journal);const completed=new Set(journal.completedStepIds);const started=new Set(journal.startedStepIds);for(const step of options.steps){if(completed.has(step.id))continue;const inspection=await step.inspect();let result=cloneOptionalJournalValue(inspection.result,`Step ${step.id} result`);if(inspection.state!=="applied"){const compensationData=await step.prepareCompensation?.();setJournalEntry(journal.compensationData,step.id,compensationData,`Step ${step.id} compensation data`);started.add(step.id);journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId));await writeJournal(options.pmRoot,journal);const appliedResult=await step.apply();result=cloneOptionalJournalValue(appliedResult,`Step ${step.id} result`)}await emitTransition(options,journal,"step_applied",step.id);completed.add(step.id);journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId));setJournalEntry(journal.results,step.id,result,`Step ${step.id} result`);await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"step_recorded",step.id)}await emitTransition(options,journal,"committing");journal.status="committed";await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"committed");return{transactionId:journal.transactionId,status:"committed",recovered,results:createResultMap(journal.results)}}catch(error){if(error instanceof WorkspaceTransactionInterruptedError||journal.status==="committed")throw error;try{await compensateAppliedSteps(options,journal)}catch(compensationError){throw new AggregateError([error,compensationError],`Workspace transaction failed and compensation failed: ${String(compensationError)}`,{cause:compensationError})}throw error}}async function loadJournal(pmRoot,transactionId,stepIds){try{return parseJournal(await readFile(journalPath(pmRoot,transactionId),"utf8"),transactionId,stepIds)}catch(error){if(error!==null&&typeof error==="object"&&"code"in error&&isFileMissingError(error))return void 0;throw error}}async function emitTransition(options,journal,transition,stepId){await options.onTransition?.({transactionId:journal.transactionId,attempt:journal.attempt,transition,...stepId===void 0?{}:{stepId}})}async function discoverAppliedSteps(journal,steps){const completed=new Set;const results=createResultMap();for(const step of steps){const inspection=await step.inspect();if(inspection.state==="applied"){completed.add(step.id);setJournalEntry(results,step.id,inspection.result,`Step ${step.id} result`)}}journal.results=results;journal.completedStepIds=steps.map(step=>step.id).filter(stepId=>completed.has(stepId))}async function compensateAppliedSteps(options,journal){journal.status="compensating";await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"compensating");const completed=new Set(journal.completedStepIds);const started=new Set(journal.startedStepIds);for(const step of[...options.steps].reverse()){if(!started.has(step.id)&&!completed.has(step.id))continue;let shouldCompensate;try{shouldCompensate=started.has(step.id)&&(await step.inspect()).state==="applied"}catch{shouldCompensate=started.has(step.id)}if(shouldCompensate){await emitTransition(options,journal,"step_compensating",step.id);await step.compensate(journal.compensationData[step.id])}completed.delete(step.id);started.delete(step.id);journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId));journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId));delete journal.results[step.id];delete journal.compensationData[step.id];await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"step_compensated",step.id)}journal.status="compensated";await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"compensated")}async function commitWorkspaceTransaction(options){const{pmRoot,transactionId,author}=validateWorkspaceTransactionIdentity(options);const lockTtlSeconds=positiveInteger(options.lockTtlSeconds,DEFAULT_LOCK_TTL_SECONDS,"Transaction lock TTL");const lockWaitMs=positiveInteger(options.lockWaitMs,DEFAULT_LOCK_WAIT_MS,"Transaction lock wait");const steps=[...options.steps];if(steps.length===0)throw new TypeError("Workspace transaction requires at least one step");const stepIds=steps.map(step=>{const stepId=requiredIdentifier(step.id,"Transaction step id");if(stepId!==step.id)throw new TypeError("Transaction step id must not contain surrounding whitespace");return stepId});if(new Set(stepIds).size!==stepIds.length)throw new TypeError("Workspace transaction step ids must be unique");const stableOptions={...options,pmRoot,transactionId,author,steps,lockTtlSeconds,lockWaitMs};const release=await acquireLock(pmRoot,WORKSPACE_TRANSACTION_LOCK_ID,lockTtlSeconds,author,false,false,lockWaitMs);try{const existing=await loadJournal(pmRoot,transactionId,stepIds);const recovered=existing!==void 0;if(existing?.status==="committed")return{transactionId,status:"committed",recovered:true,results:createResultMap(existing.results)};const prepared=await prepareJournalForApply(stableOptions,transactionId,author,stepIds,existing);return await applyPreparedTransaction(stableOptions,prepared.journal,recovered||prepared.recovered)}finally{await release()}}export{WorkspaceTransactionInterruptedError,commitWorkspaceTransaction,validateWorkspaceTransactionIdentity};
+(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]="0bd9a904-c076-5c2a-a9d8-42a543625e33")}catch{}})();import{mkdir,readFile}from"node:fs/promises";import path from"node:path";import{acquireLock}from"../core/lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{nowIso}from"../core/shared/time.js";class WorkspaceTransactionInterruptedError extends Error{constructor(message="Workspace transaction interrupted"){super(message),this.name="WorkspaceTransactionInterruptedError"}}const WORKSPACE_TRANSACTION_LOCK_ID="sdk-workspace-transaction",TRANSACTION_ID_PATTERN=/^[a-zA-Z0-9._-]+$/,DEFAULT_LOCK_TTL_SECONDS=30,DEFAULT_LOCK_WAIT_MS=3e3;function requiredIdentifier(value,label){if(typeof value!="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized||!TRANSACTION_ID_PATTERN.test(normalized))throw new TypeError(`${label} must match [a-zA-Z0-9._-]+`);return normalized}function requiredText(value,label){if(typeof value!="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized)throw new TypeError(`${label} must be non-empty`);return normalized}function validateWorkspaceTransactionIdentity(options){return{pmRoot:requiredText(options.pmRoot,"Transaction pmRoot"),transactionId:requiredIdentifier(options.transactionId,"Transaction id"),author:requiredText(options.author,"Transaction author")}}function positiveInteger(value,fallback,label){const resolved=value??fallback;if(!Number.isInteger(resolved)||resolved<=0)throw new TypeError(`${label} must be a positive integer`);return resolved}function journalPath(pmRoot,transactionId){return path.join(pmRoot,"transactions","sdk",`${transactionId}.json`)}async function writeJournal(pmRoot,journal){journal.updatedAt=nowIso();const target=journalPath(pmRoot,journal.transactionId);await mkdir(path.dirname(target),{recursive:!0}),await writeFileAtomic(target,`${JSON.stringify(journal,null,2)}
+`)}function hasValidJournalMetadata(journal){return Number.isInteger(journal.attempt)&&typeof journal.author=="string"&&typeof journal.createdAt=="string"&&typeof journal.updatedAt=="string"}function createResultMap(source){return Object.assign(Object.create(null),source)}function cloneJournalValue(value,label){try{const serialized=JSON.stringify(value,(_key,nestedValue)=>{if(typeof nestedValue=="number"&&!Number.isFinite(nestedValue))throw new TypeError(`${label} contains a non-finite number`);if(nestedValue===void 0||typeof nestedValue=="function"||typeof nestedValue=="symbol")throw new TypeError(`${label} contains a non-JSON value`);return nestedValue});return JSON.parse(serialized)}catch(error){throw new TypeError(`${label} must be JSON serializable`,{cause:error})}}function cloneOptionalJournalValue(value,label){return value===void 0?void 0:cloneJournalValue(value,label)}function setJournalEntry(target,stepId,value,label){const cloned=cloneOptionalJournalValue(value,label);cloned===void 0?delete target[stepId]:target[stepId]=cloned}function isJournalMap(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function hasUniqueKnownStepIds(value,stepIds){return Array.isArray(value)&&new Set(value).size===value.length&&value.every(stepId=>typeof stepId=="string"&&stepIds.includes(stepId))}function hasValidJournalLifecycle(journal,stepIds){if(!hasUniqueKnownStepIds(journal.startedStepIds,stepIds)||!hasUniqueKnownStepIds(journal.completedStepIds,stepIds)||!isJournalMap(journal.results)||!isJournalMap(journal.compensationData))return!1;const startedStepIds=journal.startedStepIds,started=new Set(startedStepIds),completedStepIds=journal.completedStepIds,completed=new Set(completedStepIds);return Object.keys(journal.compensationData).some(stepId=>!started.has(stepId))||Object.keys(journal.results).some(stepId=>!completed.has(stepId))?!1:journal.status==="committed"?stepIds.every(stepId=>completed.has(stepId)):journal.status!=="compensated"||completed.size===0&&started.size===0}function parseJournal(raw,transactionId,stepIds){let parsed;try{parsed=JSON.parse(raw)}catch{throw new TypeError(`Workspace transaction ${transactionId} journal is invalid JSON`)}if(!parsed||typeof parsed!="object"||Array.isArray(parsed))throw new TypeError(`Workspace transaction ${transactionId} journal is invalid`);const journal=parsed,identityMatches=journal.schemaVersion===1&&journal.transactionId===transactionId,stepsMatch=Array.isArray(journal.stepIds)&&journal.stepIds.length===stepIds.length&&journal.stepIds.every((stepId,index)=>stepId===stepIds[index]),lifecycleMatches=hasValidJournalLifecycle(journal,stepIds),metadataMatches=hasValidJournalMetadata(journal),statusMatches=["applying","compensating","compensated","committed"].includes(String(journal.status));if(!identityMatches||!stepsMatch||!lifecycleMatches||!metadataMatches||!statusMatches)throw new TypeError(`Workspace transaction ${transactionId} journal does not match the supplied plan`);return{...journal,results:createResultMap(journal.results),compensationData:createResultMap(journal.compensationData)}}async function prepareJournalForApply(options,transactionId,author,stepIds,existing){let journal=existing;const recovered=journal!==void 0;if(journal?.status==="compensating"&&await compensateAppliedSteps(options,journal),journal===void 0||journal.status==="compensated"){const timestamp=nowIso();journal={schemaVersion:1,transactionId,author,status:"applying",attempt:(journal?.attempt??0)+1,createdAt:journal?.createdAt??timestamp,updatedAt:timestamp,stepIds,startedStepIds:[],completedStepIds:[],results:createResultMap(),compensationData:createResultMap()},await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"prepared")}return{journal,recovered}}async function applyPreparedTransaction(options,journal,recovered){try{await discoverAppliedSteps(journal,options.steps),await writeJournal(options.pmRoot,journal);const completed=new Set(journal.completedStepIds),started=new Set(journal.startedStepIds);for(const step of options.steps){if(completed.has(step.id))continue;const inspection=await step.inspect();let result=cloneOptionalJournalValue(inspection.result,`Step ${step.id} result`);if(inspection.state!=="applied"){const compensationData=await step.prepareCompensation?.();setJournalEntry(journal.compensationData,step.id,compensationData,`Step ${step.id} compensation data`),started.add(step.id),journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId)),await writeJournal(options.pmRoot,journal);const appliedResult=await step.apply();result=cloneOptionalJournalValue(appliedResult,`Step ${step.id} result`)}await emitTransition(options,journal,"step_applied",step.id),completed.add(step.id),journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId)),setJournalEntry(journal.results,step.id,result,`Step ${step.id} result`),await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"step_recorded",step.id)}return await emitTransition(options,journal,"committing"),journal.status="committed",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"committed"),{transactionId:journal.transactionId,status:"committed",recovered,results:createResultMap(journal.results)}}catch(error){if(error instanceof WorkspaceTransactionInterruptedError||journal.status==="committed")throw error;try{await compensateAppliedSteps(options,journal)}catch(compensationError){throw new AggregateError([error,compensationError],`Workspace transaction failed and compensation failed: ${String(compensationError)}`,{cause:compensationError})}throw error}}async function loadJournal(pmRoot,transactionId,stepIds){try{return parseJournal(await readFile(journalPath(pmRoot,transactionId),"utf8"),transactionId,stepIds)}catch(error){if(error!==null&&typeof error=="object"&&"code"in error&&isFileMissingError(error))return;throw error}}async function emitTransition(options,journal,transition,stepId){await options.onTransition?.({transactionId:journal.transactionId,attempt:journal.attempt,transition,...stepId===void 0?{}:{stepId}})}async function discoverAppliedSteps(journal,steps){const completed=new Set,results=createResultMap();for(const step of steps){const inspection=await step.inspect();inspection.state==="applied"&&(completed.add(step.id),setJournalEntry(results,step.id,inspection.result,`Step ${step.id} result`))}journal.results=results,journal.completedStepIds=steps.map(step=>step.id).filter(stepId=>completed.has(stepId))}async function compensateAppliedSteps(options,journal){journal.status="compensating",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"compensating");const completed=new Set(journal.completedStepIds),started=new Set(journal.startedStepIds);for(const step of[...options.steps].reverse()){if(!started.has(step.id)&&!completed.has(step.id))continue;let shouldCompensate;try{shouldCompensate=started.has(step.id)&&(await step.inspect()).state==="applied"}catch{shouldCompensate=started.has(step.id)}shouldCompensate&&(await emitTransition(options,journal,"step_compensating",step.id),await step.compensate(journal.compensationData[step.id])),completed.delete(step.id),started.delete(step.id),journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId)),journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId)),delete journal.results[step.id],delete journal.compensationData[step.id],await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"step_compensated",step.id)}journal.status="compensated",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"compensated")}async function commitWorkspaceTransaction(options){const{pmRoot,transactionId,author}=validateWorkspaceTransactionIdentity(options),lockTtlSeconds=positiveInteger(options.lockTtlSeconds,DEFAULT_LOCK_TTL_SECONDS,"Transaction lock TTL"),lockWaitMs=positiveInteger(options.lockWaitMs,DEFAULT_LOCK_WAIT_MS,"Transaction lock wait"),steps=[...options.steps];if(steps.length===0)throw new TypeError("Workspace transaction requires at least one step");const stepIds=steps.map(step=>{const stepId=requiredIdentifier(step.id,"Transaction step id");if(stepId!==step.id)throw new TypeError("Transaction step id must not contain surrounding whitespace");return stepId});if(new Set(stepIds).size!==stepIds.length)throw new TypeError("Workspace transaction step ids must be unique");const stableOptions={...options,pmRoot,transactionId,author,steps,lockTtlSeconds,lockWaitMs},release=await acquireLock(pmRoot,WORKSPACE_TRANSACTION_LOCK_ID,lockTtlSeconds,author,!1,!1,lockWaitMs);try{const existing=await loadJournal(pmRoot,transactionId,stepIds),recovered=existing!==void 0;if(existing?.status==="committed")return{transactionId,status:"committed",recovered:!0,results:createResultMap(existing.results)};const prepared=await prepareJournalForApply(stableOptions,transactionId,author,stepIds,existing);return await applyPreparedTransaction(stableOptions,prepared.journal,recovered||prepared.recovered)}finally{await release()}}export{WorkspaceTransactionInterruptedError,commitWorkspaceTransaction,validateWorkspaceTransactionIdentity};
 //# sourceMappingURL=workspace-transaction.js.map

package/dist/sdk/workspace.js

@@ -1,5 +1,6 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5b131b40-e139-5a7d-a6ef-633fe2cbee64")}catch(e2){}})();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";const PM_GITIGNORE_END="# pm-cli:runtime-cache:end";const PM_GITIGNORE_DEFAULT_TRACKER_ROOT=".agents/pm";const PM_GITIGNORE_RUNTIME_DIRECTORIES=["runtime/","search/","locks/","transactions/","checkpoints/"];const PM_GITIGNORE_TRACKED_FILES=["search/eval-queries.json"];async function withGitignorePermissionRecovery(operation){try{return await operation()}catch(error){if(error instanceof Error&&"code"in error&&typeof error.code==="string"&&["EACCES","EPERM","EROFS"].includes(error.code)){throw 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."]})}throw 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("\n")}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:false}}if(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);const end=current.indexOf(PM_GITIGNORE_END);const withoutManagedBlock=start>=0&&end>=start?`${current.slice(0,start)}${current.slice(end+PM_GITIGNORE_END.length)}`:current;const prefix=withoutManagedBlock.trimEnd();const next=`${prefix.length>0?`${prefix}
+(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)}
-`;if(next===current){return{path:gitignorePath,changed:false}}await withGitignorePermissionRecovery(()=>writeFile(gitignorePath,next,"utf8"));return{path:gitignorePath,changed:true}}export{PM_GITIGNORE_DEFAULT_TRACKER_ROOT,PM_GITIGNORE_END,PM_GITIGNORE_RUNTIME_DIRECTORIES,PM_GITIGNORE_START,PM_GITIGNORE_TRACKED_FILES,ensurePmGitignore,getPmGitignoreBlock,isPathOutsideRoot};
+`;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/dist/types/index.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0ca7f52c-fb31-5cd9-b689-a918f4e61816")}catch(e2){}})();export*from"../types.js";
+(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]="0ca7f52c-fb31-5cd9-b689-a918f4e61816")}catch{}})();export*from"../types.js";
 //# sourceMappingURL=index.js.map

package/dist/types.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e33ee377-aae0-5158-9af6-e6081287a85b")}catch(e2){}})();const BUILTIN_ITEM_TYPE_VALUES=["Epic","Feature","Task","Chore","Issue","Decision","Event","Reminder","Milestone","Meeting","Plan"];const ITEM_TYPE_VALUES=BUILTIN_ITEM_TYPE_VALUES;const STATUS_VALUES=["draft","open","in_progress","blocked","closed","canceled"];const RUNTIME_STATUS_ROLE_VALUES=["draft","active","blocked","terminal","terminal_done","terminal_canceled","default_open","default_close","default_cancel"];const RUNTIME_FIELD_TYPE_VALUES=["string","number","boolean","string_array","array","object"];const RUNTIME_FIELD_COMMAND_VALUES=["create","update","update_many","list","search","calendar","context"];const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES=["allow","warn","reject"];const DEPENDENCY_KIND_VALUES=["blocks","parent","child","parent_child","child_of","related","related_to","discovered_from","blocked_by","incident_from","epic","implements","recurs_from","supersedes","task","verifies"];const SCOPE_VALUES=["project","global"];const RISK_VALUES=["low","medium","high","critical"];const ISSUE_SEVERITY_VALUES=["low","medium","high","critical"];const CONFIDENCE_TEXT_VALUES=["low","medium","high"];const ITEM_FORMAT_VALUES=["toon","json_markdown"];const SPRINT_RELEASE_FORMAT_POLICY_VALUES=["warn","strict_error"];const PARENT_REFERENCE_POLICY_VALUES=["warn","strict_error"];const VALIDATE_METADATA_PROFILE_VALUES=["core","strict","custom"];const GOVERNANCE_PRESET_VALUES=["minimal","default","strict","custom"];const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES=["none","warn","strict"];const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES=["progressive","strict"];const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES=["off","warn","strict"];const GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES=["off","warn","strict"];const GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES=["off","advisory","strict"];const VALIDATE_METADATA_REQUIRED_FIELD_VALUES=["author","acceptance_criteria","estimated_minutes","close_reason","reviewer","risk","confidence","sprint","release"];const RECURRENCE_FREQUENCY_VALUES=["daily","weekly","monthly","yearly"];const RECURRENCE_WEEKDAY_VALUES=["mon","tue","wed","thu","fri","sat","sun"];function weekdayOrderIndex(value){return RECURRENCE_WEEKDAY_VALUES.indexOf(value)}const PLAN_MODE_VALUES=["draft","research","review","approved","executing","paused","completed","superseded"];const PLAN_STEP_STATUS_VALUES=["pending","in_progress","completed","blocked","skipped","superseded"];const PLAN_HARNESS_VALUES=["codex","claude-code","cursor","generic"];const PLAN_STEP_LINK_KIND_VALUES=["related","blocks","blocked_by","depends_on","discovered_from","implements","recurs_from","verifies","supersedes"];const CONTEXT_DEPTH_VALUES=["brief","standard","deep","full"];const CONTEXT_SECTION_VALUES=["hierarchy","activity","progress","recently_created","unparented","blockers","files","workload","staleness","tests"];export{BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,CONTEXT_DEPTH_VALUES,CONTEXT_SECTION_VALUES,DEPENDENCY_KIND_VALUES,GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES,GOVERNANCE_CREATE_MODE_DEFAULT_VALUES,GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES,GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES,GOVERNANCE_PRESET_VALUES,GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES,ISSUE_SEVERITY_VALUES,ITEM_FORMAT_VALUES,ITEM_TYPE_VALUES,PARENT_REFERENCE_POLICY_VALUES,PLAN_HARNESS_VALUES,PLAN_MODE_VALUES,PLAN_STEP_LINK_KIND_VALUES,PLAN_STEP_STATUS_VALUES,RECURRENCE_FREQUENCY_VALUES,RECURRENCE_WEEKDAY_VALUES,RISK_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES,SCOPE_VALUES,SPRINT_RELEASE_FORMAT_POLICY_VALUES,STATUS_VALUES,VALIDATE_METADATA_PROFILE_VALUES,VALIDATE_METADATA_REQUIRED_FIELD_VALUES,weekdayOrderIndex};
+(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]="e6847fdd-b2c1-5503-b510-56fdfdcf933f")}catch{}})();const BUILTIN_ITEM_TYPE_VALUES=["Epic","Feature","Task","Chore","Issue","Decision","Event","Reminder","Milestone","Meeting","Plan"],ITEM_TYPE_VALUES=BUILTIN_ITEM_TYPE_VALUES,STATUS_VALUES=["draft","open","in_progress","blocked","closed","canceled"],RUNTIME_STATUS_ROLE_VALUES=["draft","active","blocked","terminal","terminal_done","terminal_canceled","default_open","default_close","default_cancel"],RUNTIME_FIELD_TYPE_VALUES=["string","number","boolean","string_array","array","object"],RUNTIME_FIELD_COMMAND_VALUES=["create","update","update_many","list","search","calendar","context"],RUNTIME_UNKNOWN_FIELD_POLICY_VALUES=["allow","warn","reject"],DEPENDENCY_KIND_VALUES=["blocks","parent","child","parent_child","child_of","related","related_to","discovered_from","blocked_by","incident_from","epic","implements","recurs_from","supersedes","task","verifies"],SCOPE_VALUES=["project","global"],RISK_VALUES=["low","medium","high","critical"],ISSUE_SEVERITY_VALUES=["low","medium","high","critical"],CONFIDENCE_TEXT_VALUES=["low","medium","high"],ITEM_FORMAT_VALUES=["toon","json_markdown"],SPRINT_RELEASE_FORMAT_POLICY_VALUES=["warn","strict_error"],PARENT_REFERENCE_POLICY_VALUES=["warn","strict_error"],VALIDATE_METADATA_PROFILE_VALUES=["core","strict","custom"],GOVERNANCE_PRESET_VALUES=["minimal","default","strict","custom"],GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES=["none","warn","strict"],GOVERNANCE_CREATE_MODE_DEFAULT_VALUES=["progressive","strict"],GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES=["off","warn","strict"],GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES=["off","warn","strict"],GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES=["off","advisory","strict"],VALIDATE_METADATA_REQUIRED_FIELD_VALUES=["author","acceptance_criteria","estimated_minutes","close_reason","reviewer","risk","confidence","sprint","release"],RECURRENCE_FREQUENCY_VALUES=["daily","weekly","monthly","yearly"],RECURRENCE_WEEKDAY_VALUES=["mon","tue","wed","thu","fri","sat","sun"];function weekdayOrderIndex(value){return RECURRENCE_WEEKDAY_VALUES.indexOf(value)}const PLAN_MODE_VALUES=["draft","research","review","approved","executing","paused","completed","superseded"],PLAN_STEP_STATUS_VALUES=["pending","in_progress","completed","blocked","skipped","superseded"],PLAN_HARNESS_VALUES=["codex","claude-code","cursor","generic"],PLAN_STEP_LINK_KIND_VALUES=["related","blocks","blocked_by","depends_on","discovered_from","implements","recurs_from","verifies","supersedes"],CONTEXT_DEPTH_VALUES=["brief","standard","deep","full"],CONTEXT_SECTION_VALUES=["hierarchy","activity","progress","recently_created","unparented","blockers","files","workload","staleness","tests"];export{BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,CONTEXT_DEPTH_VALUES,CONTEXT_SECTION_VALUES,DEPENDENCY_KIND_VALUES,GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES,GOVERNANCE_CREATE_MODE_DEFAULT_VALUES,GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES,GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES,GOVERNANCE_PRESET_VALUES,GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES,ISSUE_SEVERITY_VALUES,ITEM_FORMAT_VALUES,ITEM_TYPE_VALUES,PARENT_REFERENCE_POLICY_VALUES,PLAN_HARNESS_VALUES,PLAN_MODE_VALUES,PLAN_STEP_LINK_KIND_VALUES,PLAN_STEP_STATUS_VALUES,RECURRENCE_FREQUENCY_VALUES,RECURRENCE_WEEKDAY_VALUES,RISK_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES,SCOPE_VALUES,SPRINT_RELEASE_FORMAT_POLICY_VALUES,STATUS_VALUES,VALIDATE_METADATA_PROFILE_VALUES,VALIDATE_METADATA_REQUIRED_FIELD_VALUES,weekdayOrderIndex};
 //# sourceMappingURL=types.js.map

package/docs/AGENT_EVIDENCE_CONSISTENCY.md

@@ -0,0 +1,88 @@
+# Agent evidence consistency
+
+Trackers: [pm-gh1383](../.agents/pm/issues/pm-gh1383.toon),
+[pm-gh1385](../.agents/pm/issues/pm-gh1385.toon), and
+[pm-7wzc6f](../.agents/pm/issues/pm-7wzc6f.toon). Distribution verification:
+[pm-2evidence-dist](../.agents/pm/issues/pm-2evidence-dist.toon).
+
+## Agent quick context
+
+Evidence must retain its literal text, validation must compare a consistent
+item/history pair, and recovery help must identify a declared command. These
+contracts apply to ordinary project work and to the evidence used for recursive
+self-improvement.
+
+## Literal annotations
+
+`comments`, `notes`, and `learnings` preserve positional annotation bodies through
+bootstrap normalization. A prefix such as `TDD:` or `add:` is evidence text.
+The same text is preserved when supplied through `--add`, `--file`, `--stdin`,
+`--add -`, or `--file -`.
+
+```bash
+pm comments <id> "TDD: regression reproduced before the fix"
+pm notes <id> --file evidence.txt
+pm learnings <id> --stdin
+```
+
+The annotation SDK still supports its explicit `text:` and `text=` structured
+input syntax. Files and standard input remain literal text sources. Other
+commands retain their supported bare-key option normalization.
+
+## Consistent history validation
+
+Validation first scans the captured corpus. An ordinary writer can advance an
+item and its history after that capture. An item-hash discrepancy is therefore
+read again while holding the same item mutation lock used by ordinary writers.
+This fresh source/history pair determines the finding. A reread whose declared
+identity differs from the locked identity fails before any finding is replaced.
+
+Clean rows and history-only findings do not incur another item read or lock
+acquisition. Each item-hash discrepancy gets one bounded recheck. Lock contention
+and missing or unreadable item source are reported as failures; validation does
+not steal locks or certify an unread pair.
+Missing histories, malformed streams, record-chain corruption, unsupported
+epochs, and identity discontinuities retain their strict findings. History-only
+diagnostics remain available to repair workflows even when a writer owns the item.
+Workspace singleton findings retain their own verification semantics.
+
+The core `scanHistoryDrift` API continues to compare the snapshots supplied by
+its caller. Its strict `scanItemHistoryDrift` companion shares stream verification
+without loading or writing the corpus cache or rereading workspace history and
+governed documents. Workspace checks run once in the initial corpus scan.
+
+## Declared recovery help
+
+An unknown option has no declared value arity. In an invocation such as
+`pm --unknown-option synthetic-value context`, the parser cannot safely assume
+that `synthetic-value` is a command. Recovery falls back to `pm --help --all`
+unless the inferred target belongs to the core or active runtime command surface.
+Known commands, command-first invocations, namespaced aliases, and options with
+an equals value retain command-specific recovery help.
+
+## Verification
+
+The regression owner exercises real isolated tracker persistence, all annotation
+transports, strict corruption cases, writer-lock contention, cache preservation,
+identity binding, bounded cache reads, and public bootstrap normalization:
+
+```bash
+node scripts/run-tests.mjs test -- tests/unit/regressions/agent-evidence-consistency.spec.ts
+node scripts/release/agent-evidence-consistency-control.mjs
+node scripts/release/agent-evidence-consistency-control.mjs --negative-control
+```
+
+The final command must exit with status `1`: each disposable source mutation
+must fail its selected regression. A failure caused by unrelated setup is not
+accepted as regression proof.
+
+Build finalization also compacts redundant syntax in retained runtime modules.
+Exported names, module paths, declarations, bundled files and original source
+maps remain covered by real filesystem and Node consumer tests. The npm artifact
+must satisfy its existing size ceiling before installed npm/npx/bunx acceptance.
+
+Packed SDK continuation acceptance stages the actual publish selectors and
+unchanged package manifest in a disposable source directory before invoking
+`npm pack`. This avoids traversing development dependencies while retaining
+the real tarball, public SDK export, and existing process and test time limits.
+Installed package smoke acceptance separately verifies dependency installation.

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -67,6 +67,31 @@ remains complete and `recovery.suggested_retry_args` is atomic: the projector
 either retains the executable argv or removes the recovery rather than slicing
 it into a dead command.
 
+Enum, date, get-depth, and minimum intent-budget validation producers attach the failed metadata
+`field` and supplied `value` to `PmCliError.context`; closed domains also attach
+the complete legal values, including the accepted `full` depth alias. CLI
+attribution normalizes camelCase and snake_case fields to an actually supplied
+canonical flag, so `tokenBudget` identifies `--token-budget`. Explicit flag
+metadata retains its spelling. Argument order and unrelated valid flags cannot
+become the refusal owner. The error-context `value` is text, including the
+textual representation of numeric SDK inputs. Compound projection conflicts
+identify their flag without inventing a rejected scalar. Missing items identify
+the `id` operand.
+When the producer cannot identify a field or value, the diagnostic retains the
+command surface and omits the unknown scalar. Policy evidence takes precedence
+over syntactic attribution. Tracked by [pm-gh1365](../.agents/pm/issues/pm-gh1365.toon).
+
+`--json` and `--output-format json` (including `--output-format=json`) select
+JSON on stderr for parser and execution errors as well as successful output.
+The canonical `--output-format` selector wins when combined with `--json`, so
+`--output-format toon --json` retains text diagnostics. Exit codes are unchanged.
+The executable's project-runtime compatibility warnings and refusals use that
+same SDK selector, including repeated formats and the `--` terminator. A JSON
+stale-read warning is emitted after successful dispatch; a failed read emits its
+typed error alone so stderr remains one JSON value. Text warnings retain their
+pre-dispatch presentation.
+Tracked by [pm-gh1366](../.agents/pm/issues/pm-gh1366.toon).
+
 The deterministic ladder is:
 
 1. full diagnostic;

package/docs/GET_READ_EVIDENCE.md

@@ -0,0 +1,68 @@
+# Actionable item-read evidence
+
+Trackers: [pm-gh1388](../.agents/pm/issues/pm-gh1388.toon),
+[pm-gh1389](../.agents/pm/issues/pm-gh1389.toon).
+
+The public SDK item query supplies the same evidence to CLI and MCP callers.
+Standard and deep current reads include a `blockers` facet when the item declares
+prerequisites through its legacy `blocked_by` scalar or `blocked_by` dependency
+edges. `blockers.open` supplies each nonterminal target's ID, title and status;
+`blockers.closed_count` counts terminal targets using the runtime status registry.
+Repeated scalar/edge references are deduplicated by the shared actionability
+primitive. Missing targets and external references remain unresolved, with null
+status, so they cannot silently authorize work.
+Short local references resolve to their verified full IDs and count once even
+when both forms are stored. Rows under `open` are unresolved by definition;
+they omit the redundant `resolved: false` flag while retaining resolver context.
+Legacy text that is not a portable filename remains unresolved and never causes
+a lookup outside the registered item folders.
+A target file with a different embedded item identity refuses the read with an
+identity conflict rather than borrowing an unrelated item's terminal status.
+
+`blockers.scope` is `declared`: the facet resolves forward declarations from this
+item, without enumerating unrelated items. Reverse `blocks` relationships require
+a corpus graph or actionability query. The stored scalar remains a compatibility
+field and identifies only the last scalar value. Standard reads replace that
+partial scalar with the complete declared facet; `--fields blocked_by` and
+`--full` retain access to the stored scalar. Storage and provenance are preserved.
+Ordinary dependency rows retain `id` and `kind`; `--full`, `--depth full`, and
+`--fields dependencies` restore the stored timestamp and author/source columns.
+The `dependency_provenance` omission receipt names `--fields dependencies` as the
+narrow restoration. This presentation change preserves every stored edge.
+The receipt describes attribution actually withheld by the selected projection.
+Legacy rows with no timestamp remain complete under full or explicit reads;
+following the restoration never invents a timestamp or repeats a false omission.
+Rows containing only identities and kinds have no attribution to withhold.
+Field selection takes precedence when combined with `--depth full`: a narrow
+selector still discloses withheld attribution, while selecting `dependencies`
+restores its complete stored rows.
+
+```bash
+pm get <id>
+pm get <id> --depth brief
+pm get <id> --fields blockers
+```
+
+Brief and selected reads disclose material withheld blocker evidence with the
+compact `--full` restoration. Use `--fields blockers` for the narrow facet alone;
+`item.blockers` is an equivalent selector.
+Historical reads preserve historical metadata and omit current blocker status.
+An explicit historical blocker projection refuses with current-read guidance,
+because a present-day target status cannot certify a past prerequisite state.
+
+Omission receipts account for what the result actually renders. A reminder or
+event supplied through `schedule.reminders` or `schedule.events` is included even
+when its metadata alias is absent. Nonempty files, tests and docs rendered under
+`linked` are included too. Narrow selectors continue to disclose unselected
+material members; the stable linked envelope's empty placeholders do not certify
+that unrequested artifact contents were returned.
+
+```bash
+pm get <id> --fields schedule.reminders
+pm get <id> --fields linked.tests
+```
+
+The regression suite creates actual disposable tracker data and checks open,
+terminal, custom-terminal, missing and external prerequisites; brief restoration;
+historical separation; and independent schedule/artifact alias projections.
+No source tracker, mocked resolver or suppressed drift check is involved.

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -232,6 +232,29 @@ activity limits so the built-in orientation declaration remains feasible on a
 large tracker. All five intent commands accept the same
 `--token-budget` override. Explicit `--depth` and `--limit` controls still win.
 
+Context omission instructions request the named section, for example
+`--section files`, so they can be appended while retaining `--for handoff` or
+`--for orient`. An explicit depth suppresses the intent's default section subset;
+an explicit section remains authoritative at any depth. Workspace memory that
+is already present is never reported as omitted. The original filters and token
+budget remain binding; an oversized restoration reports its remaining budget
+constraint. Tracked by [pm-gh1367](../.agents/pm/issues/pm-gh1367.toon).
+
+For namespaced commands, options supplied on an ancestor apply only when the
+selected leaf declares them. `context --tag urgent next` forwards the tag;
+a leaf-supplied limit takes precedence. `context next --depth deep` and
+`context --depth deep next` fail with `unknown_option`, because `next` does not
+declare a depth projection. Inspect the leaf's help before applying context
+controls to it. Tracked by [pm-gh1368](../.agents/pm/issues/pm-gh1368.toon).
+
+Ownership compositions use the resolved canonical item ID in every stage and
+the root receipt, including short-ID invocations. Default CLI/MCP start, pause,
+and close receipts expose the final status and aggregate changed-field count
+without repeating item bodies. `--full-changed-fields` and typed SDK methods
+retain complete constituent results. A failed later step reports the canonical
+item and prior durable mutation without implying rollback.
+Tracked by [pm-gh1369](../.agents/pm/issues/pm-gh1369.toon).
+
 If a selected result exceeds its budget, long explanatory strings compact
 first, followed by deterministic root-row reduction that retains at least one
 useful row and reports `budget_row_compaction`. Only a result whose minimum

package/docs/README.md

@@ -35,6 +35,8 @@ pm guide release --json
 - [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
 - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
 - [Agent Read and Test Receipts](AGENT_READ_AND_TEST_RECEIPTS.md) - JSON help provenance, linked-test persistence, and history diff continuation.
+- [Agent Evidence Consistency](AGENT_EVIDENCE_CONSISTENCY.md) - literal annotations, concurrent history validation, and declared recovery help.
+- [Actionable Item-read Evidence](GET_READ_EVIDENCE.md) - declared blocker status, historical separation, and truthful schedule/artifact omission receipts.
 - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
 - [Context and Operations Namespaces](COMMAND_NAMESPACES.md) - native navigation, diagnostics, event streams, and compatibility aliases.
 - [CLI Scripting Contract](SCRIPTING.md) - exit codes, flat mutation receipts versus read envelopes, stdout/stderr boundaries, stable JSON fields, uniform OR filters, and shell composition recipes.

package/docs/SDK_AUDITED_MUTATIONS.md

@@ -3,6 +3,7 @@
 The extension settings contract is tracked by
 [pm-wtqltn](../.agents/pm/issues/pm-wtqltn.toon). Full-item JSON annotation
 integrity is tracked by [pm-2589e6](../.agents/pm/issues/pm-2589e6.toon).
+Canonical previews are tracked by [pm-2sef82](../.agents/pm/features/pm-2sef82.toon).
 
 ## Extension settings
 
@@ -36,10 +37,44 @@ the same operation ID can then be used for the real mutation. A normal return
 also reports `changed` and `dry_run`. Invalid results fail before writing, and
 a history-append failure restores the previous settings bytes. The callback
 must derive its complete next settings object from the locked `current` value.
+The callback receives normalized inline settings with defaults and preset knobs
+even when the source file is sparse. Returning that tree unchanged retains the
+original source bytes, including unknown fields, without creating an audit event.
+Changed writes apply known-setting changes to the captured source through the
+standard serializer, preserving sparse omissions and unrecognized fields in
+unchanged containers for forward compatibility. Those fields remain outside the
+typed callback and canonical preview. Replacing an array replaces its complete
+contents, as in normal settings writes. Present legacy values are canonicalized
+on a changed write; an identity no-op still retains the original bytes.
+The host also validates the final serialized bytes before committing, so a
+proposal that changes while being serialized cannot persist invalid settings.
 The host applies the standard settings serializer, including legacy format
 coercion and collection-name sanitization, and runs active `onWrite` hooks
 after a changed write.
 
+Request `includePreview: true` to receive an optional `preview` settings tree
+alongside the receipt. The host resolves it from the exact serialized bytes
+inside the audit lock, using the same defaults and governance presets as normal
+settings reads. A named `minimal` preset therefore reports ownership `none`
+even if the callback proposed `strict`. Custom presets retain their configured
+knobs. Legacy formats and collection names reflect their canonical persisted
+values. This tree describes inline settings before optional file-backed schema
+overlays; it does not load or create those files.
+
+Use `dryRun: true, includePreview: true` to inspect the result before applying
+the same operation. A fresh no-op also includes its canonical tree. An idempotent
+replay omits `preview`: the original callback is not re-executed, and later
+settings changes cannot reconstruct its historical proposal. Receipts remain
+three booleans when the option is absent. Direct SDK dry runs read configuration
+without executing read hooks, scaffolding optional schemas, or populating the
+hydrated settings cache. Mutation callbacks should only derive settings and
+avoid external side effects.
+
+For an extension that requires previews, set its manifest `pm_min_version` to
+a published host release containing this option. Check for `preview` on a fresh
+dry-run operation before applying settings, while allowing replay receipts to
+omit it as described above.
+
 ## Full-item JSON updates
 
 `pm update <id> --stdin-json` accepts a full item read document. New comments,

package/docs/TESTING.md

@@ -575,6 +575,14 @@ pm test <item-id> --run --workspace-context snapshot --override-linked-workspace
   must be physically disjoint; overlapping roots fail before copying with a
   diagnostic directing the caller to a temporary root outside the checkout.
 
+  Snapshot target probes treat only `ENOENT` as absence and propagate other
+  filesystem failures. They use explicit error handling so Node 22 and older
+  Node 24 releases retain the same dangling-link behavior; the async `stat`
+  `throwIfNoEntry` option was added in
+  [Node 24.15](https://nodejs.org/download/release/v24.20.0/docs/api/fs.html#fspromisesstatpath-options).
+  The real filesystem and CLI snapshot suite runs in the required Node 22
+  telemetry regression job and native Windows regression job before merge.
+
   The real-filesystem regression for this contract is tracked by
   [pm-5iwfkj](../.agents/pm/issues/pm-5iwfkj.toon).