@unbrained/pm-cli 2026.10.4 → 2026.10.6

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/DEVELOPMENT_DEPENDENCY_SECURITY.md

@@ -20,6 +20,42 @@ nightly quality and release paths enforce it. The registry-owned local
 preflight also requires the static gate and permits no skip. Trivy separately
 includes development dependencies in its required repository scan.
 
+## Indexed source-map offsets
+
+[pm-dba47](../.agents/pm/issues/pm-dba47.toon) tracks Dependabot alert 47 and
+the new source-map cause of Scorecard alert 29.
+[GHSA-68fv-2mgg-jv7q](https://github.com/advisories/GHSA-68fv-2mgg-jv7q)
+affects `source-map-js` before 1.2.2. Unchecked indexed-map section offsets can
+block the event loop. The dependency is used by the development lint and test
+graph through `@eslint/css-tree`, `magicast` and `postcss`; this inventory does
+not establish a production exploit. The pnpm override requires a patched 1.x
+release while retaining normal release-age policy and frozen installation.
+The pinned pnpm 11 uses its default one-day minimum release age; the separate
+seven-day Dependabot cooldown governs version-update scheduling. This repair
+adds no age override or exclusion.
+
+A clean audit feed is only evidence about that feed at its observation time.
+GitHub and OSV reported this advisory while the npm audit response was still
+empty. A freshly updated Trivy database also admitted both vulnerable and
+patched temporary fixtures, so that scan did not establish regression sensitivity.
+The independent safe constructor control rejected an oversized indexed-map
+offset only on the patched version, without serializing the huge offset.
+Read the actual locked graph and every available scanner report before
+claiming that findings are retired. Native scans of merged main must confirm
+retirement independently of green PR workflow jobs.
+
+## Worker diagnostics
+
+[pm-cql43](../.agents/pm/issues/pm-cql43.toon) tracks CodeQL alert 43 in the
+test worker bridge. Its captured scanner flow contains a generated temporary
+path, so it does not prove a credential leak. The debug path nevertheless
+previously broadcast arbitrary CLI arguments and stderr. Debug failures now
+emit only a fixed notification; the complete captured result remains available
+to deliberate assertions. A real worker regression uses synthetic private
+input and verifies both notification privacy and preserved result contents,
+plus silence when debugging is disabled or the command succeeds. The harness
+is excluded from the published package.
+
 ## File matching dependency removal
 
 [GHSA-vfj7-8cjw-p6xm](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm)

package/docs/GET_READ_EVIDENCE.md

@@ -0,0 +1,84 @@
+# Actionable item-read evidence
+
+Trackers: [pm-gh1388](../.agents/pm/issues/pm-gh1388.toon),
+[pm-gh1389](../.agents/pm/issues/pm-gh1389.toon),
+[pm-gh1409](../.agents/pm/issues/pm-gh1409.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.
+Local comparison keys ignore case for deduplication, while filesystem lookups
+retain the declared spelling. Imported mixed-case IDs therefore resolve to their
+live status on both case-sensitive and case-insensitive filesystems without
+weakening the embedded-identity check.
+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.
+Physical filename verification also runs when the probe and embedded IDs match:
+case-insensitive access can open a differently spelled leaf with the same probe.
+Verification gives an exact leaf precedence and sorts equally
+preferred case aliases deterministically. A directory-read failure refuses the
+query with `blocker_identity_read_failed` and access-restoration guidance. The
+public SDK retains the original error as its cause; the read never invents a
+missing prerequisite or changes item/history bytes. Native case-insensitive
+fixtures intentionally share a physical destination, while case-sensitive
+fixtures retain colliding leaves and exercise the same identity refusal.
+If the physical leaf disappears between the document read and verification,
+the query refuses the identity instead of treating the probe as proof.
+
+`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

@@ -21,6 +21,11 @@ is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon) and
 projection discovery is tracked by
 [pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon). Shared graph defaults and
 scale enforcement are tracked by [pm-mfy1ux](../.agents/pm/issues/pm-mfy1ux.toon).
+Combined ceiling coordinates, explicit-selector receipt cost, and executable
+global projection retries are tracked by
+[pm-gh1411](../.agents/pm/issues/pm-gh1411.toon),
+[pm-gh1408](../.agents/pm/issues/pm-gh1408.toon), and
+[pm-gh1386](../.agents/pm/issues/pm-gh1386.toon).
 
 For enforcement of declared MCP input options in repository tests, see
 [MCP Option Conformance](MCP_OPTION_CONFORMANCE.md).
@@ -199,6 +204,15 @@ when several groups are needed. This remains truthful for leaf items because
 an explicit children projection returns an empty rollup instead of silently
 conflating “no children” with “children were not requested.”
 
+Explicit `get --fields` selection defines the requested answer. Its receipt
+describes that selection, so intentionally unselected groups do not generate
+restoration rows. The existing complete-receipt shape remains available, and
+requested empty collections and canonical identity remain explicit. Default
+and depth reads retain material-group restoration instructions. A token budget
+that shortens requested strings or collections still emits the shared
+`read_output` and budget-truncation evidence; a complete field-selection
+receipt does not certify that later budget shaping preserved every value.
+
 ## Intent Budgets
 
 Built-in read intents apply valid command-specific defaults and disclose the
@@ -274,6 +288,10 @@ Full/projection conflicts retain the selected full or brief mode and remove the
 conflicting projection and intent controls. If that correction cannot be
 constructed safely, the error does not advertise an automatic retry.
 Tracked by [pm-gh1364](../.agents/pm/issues/pm-gh1364.toon).
+Global `--output-include` conflicts are removed with their consumed values,
+including attached values and options before the subcommand. The surviving
+command-local mode keeps its original option position. An ambiguous mode
+location does not produce an automatic retry.
 
 For a budget-compacted producer page, follow
 `output_budget_truncation.recovery.cursor` with `--output-cursor`, keeping the
@@ -284,6 +302,11 @@ actual filter and scope changes still invalidate its cursor. Emitted `count`
 and `summary.returned_focus` describe delivered rows; matching-population totals
 remain separate, including explicit count-only aggregates. Context hierarchy companions may repeat while continuing a
 focus collection. Tracked by [pm-gh1371](../.agents/pm/issues/pm-gh1371.toon).
+When `--output-limit` and `--output-budget` both reduce a page, snapshot counts
+and fingerprints are captured before either row ceiling. Producer cursors
+rebase from the original page coordinate, so an unchanged output continuation
+is accepted and deletion of its last delivered identity cannot skip withheld
+rows through positional fallback. Filter and tracker-scope checks still apply.
 
 The first cursor page carries the complete projection, filtering, sorting,
 completeness, row, and omission contracts. Continuation pages replace those

package/docs/PR_REVIEW_LOOP.md

@@ -1,6 +1,6 @@
 # Pull Request Review Loop
 
-Trackers: [pm-hq28](../.agents/pm/tasks/pm-hq28.toon), [pm-cp5pbo](../.agents/pm/tasks/pm-cp5pbo.toon), [pm-8we38i](../.agents/pm/issues/pm-8we38i.toon)
+Trackers: [pm-hq28](../.agents/pm/tasks/pm-hq28.toon), [pm-0fxa](../.agents/pm/tasks/pm-0fxa.toon), [pm-zpwfzy](../.agents/pm/issues/pm-zpwfzy.toon), [pm-cp5pbo](../.agents/pm/tasks/pm-cp5pbo.toon), [pm-8we38i](../.agents/pm/issues/pm-8we38i.toon)
 
 Use `scripts/reviews/pr-review-loop.mjs` to inventory every GitHub pull-request
 conversation surface before deciding that review is complete. The inventory includes
@@ -46,10 +46,27 @@ reply thread. Legacy calls without the flag retain their existing behavior.
 After every push or reviewer retrigger, run `watch`. It delegates waiting to
 `gh pr checks --watch`, because reviewer agents report completion through GitHub
 checks, and only fetches the complete conversation inventory after those checks
-finish. A failed reviewer check is still a completed review signal: `watch` records
+finish. Native watch success covers emitted checks only: a required provider may
+never emit its context. The helper unions classic branch-protection requirements
+with all effective ruleset requirements, compares those names with the complete
+head rollup, and records `mergeReadiness.requiredContexts`, `missingContexts`, and
+GitHub's `mergeStateStatus`. An attempt is `passed` only when no required name is
+missing and GitHub reports `CLEAN`. GitHub's merge state also retains enforcement
+of expected check publishers and other merge requirements; a matching name alone
+does not establish that its expected app passed. Missing contexts and blocked or
+unknown merge state remain `incomplete`; native watch failures remain `failed`.
+Superseded attempts carry `superseded: true` and never certify readiness. Unavailable policy or status reads
+fail visibly instead of certifying readiness. Successful
+coverage uploads alone cannot certify a downstream provider's patch status.
+The direct `watch` command emits its complete JSON receipt before exiting `1`
+for `incomplete` or `failed`, and exits `0` only for `passed`. Shell automation
+can therefore stop on the exit status while retaining all findings for triage.
+
+A failed reviewer check is still a completed review signal: `watch` records
 the failed outcome and returns all findings instead of aborting before inventory.
-If the PR head changes while checks are running, the helper automatically watches
-the new head, up to three consecutive attempts, before returning exact-head state.
+If the PR head or target branch changes during the wait or final readiness read,
+the helper watches the new target, up to three consecutive attempts, before
+returning exact-head state. It does not poll an absent required provider status.
 A review pass is complete only when every bot surface in that inventory has been
 handled appropriately, every actionable thread is resolved, and required checks
 have completed successfully.

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.
@@ -48,6 +50,7 @@ pm guide release --json
 - [Noun–Verb CLI Grammar](CLI_GRAMMAR.md) - accepted command architecture, exhaustive destination census, hidden aliases, and the surface-growth gate.
 - [SDK Primitive Inventory](SDK_PRIMITIVE_INVENTORY.md) - SDK-first migration map and private-import ratchet for CLI/MCP layering.
 - [Package SDK Contract Conformance](PACKAGE_SDK_CONTRACT_CONFORMANCE.md) - authoritative public types, `typeof` module derivation, and the first-party parity gate.
+- [SDK Configuration and Diagnostic Safety](SDK_CONFIGURATION_SAFETY.md) - explicit settings ownership, transient npm freshness, audited schema sandboxes, and mutation-safe help.
 - [SDK Action and Boundary Conformance](SDK_ACTION_CONFORMANCE.md) - derived CLI/SDK/MCP action vocabulary, public-import ratchets, intent budget diagnostics, and package-runner proof.
 - [MCP 2026-07-28 Protocol Decision](MCP_2026_07_28.md) - stateless request metadata, discovery, result envelopes, explicit legacy boundary, and migration policy.
 - [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md) - opt-in bounded MCP catalogs, public SDK ranking and pagination, canonical results, and compatibility isolation.

package/docs/RELEASING.md

@@ -494,6 +494,24 @@ gh run list --workflow Release --limit 5
 gh run watch <run-id> --exit-status
 ```
 
+## Verified Coverage Uploads
+
+Tracked by [pm-2x67z9](../.agents/pm/issues/pm-2x67z9.toon). CI downloads the
+official Codecov CLI from an immutable GitHub release and checks the reviewed
+SHA-256 before making it executable. Both coverage and test-result uploads
+require that verifier to succeed and retain mandatory upload failures plus
+the exact PR-head identity. The pinned action's supported `url` input selects
+the official `https://codecov.io` Cloud host for the current coverage and
+test-result APIs; certificate validation remains required for every request.
+Both uploads disable verbose logging because debug output can expose signed
+storage upload URLs in public Actions logs. Normal upload-result diagnostics
+remain available, and upload errors still fail the required gate.
+Failed tests can still upload diagnostic reports
+after successful verification. Update the release URL and digest together;
+verify the official artifact and its adoption age before changing those pins.
+The shell regression executes the real checksum with approved and corrupt
+download fixtures; a failed check must prevent executable permission and uploads.
+
 ## Post-Release Verification
 
 Use the [rolling reliability report](RELEASE_RELIABILITY.md) as well as the

package/docs/SDK_CONFIGURATION_SAFETY.md

@@ -0,0 +1,123 @@
+# SDK Configuration and Diagnostic Safety
+
+Trackers: [pm-gh1394](../.agents/pm/issues/pm-gh1394.toon), [pm-gh1393](../.agents/pm/issues/pm-gh1393.toon), [pm-gh1392](../.agents/pm/issues/pm-gh1392.toon), [pm-gh1398](../.agents/pm/issues/pm-gh1398.toon).
+
+Package authors use the host-injected `context.sdk` services to change project
+configuration. The SDK owns settings normalization, locking, immutable audit
+history, retry identity, and dry-run behavior. See [SDK](SDK.md) and
+[Packages and Extensions](EXTENSIONS.md) for the broader authoring contract.
+
+## Explicit Settings Ownership
+
+`mutateWorkspaceSettings` preserves unknown source fields by default. A package
+that replaces a complete settings object can explicitly declare the objects it
+owns with `replaceSubtrees`:
+
+```ts
+await context.sdk!.mutateWorkspaceSettings({
+  operationId: "apply-governance-policy",
+  replaceSubtrees: ["governance"],
+  includePreview: true,
+  dryRun: context.options.dryRun === true,
+  mutate: (current) => ({
+    ...current,
+    governance: { ...current.governance, preset: "minimal" },
+  }),
+});
+```
+
+The selected object is replaced by its normalized serialized value, removing
+unknown raw keys omitted from the callback's result. Unselected source fields,
+including future root fields and sibling objects, are preserved. Dot-delimited
+paths such as `search.rerank` select nested objects. Missing ancestors are
+materialized with their canonical settings so the complete persisted document
+remains valid. Scalar, array, unknown, and prototype paths are rejected before
+writing. Declare ownership only for configuration the package is authorized to
+replace. An empty ownership list retains the default preservation behavior.
+
+Replacement runs inside the same settings lock and history transaction as the
+callback. Dry runs write no settings or workspace history; retries with the same
+operation identity skip the callback after a successful commit. Fresh semantic
+no-ops preserve the existing bytes and produce no history event.
+
+The optional `preview` describes normalized inline settings resolved from the
+exact proposed bytes. Preset-derived values can be omitted from serialized JSON
+and reconstructed in the preview. File-backed schema overlays and unknown raw
+keys are outside this normalized preview. Inspect the persisted document when
+raw-source information is needed.
+
+## Read-only Package Freshness
+
+`pm package explore`, `doctor`, and `manage` preserve managed installation state.
+`manage` checks GitHub revisions and npm registry identities transiently; it
+does not rewrite `.managed-extensions.json`, reorder its contribution inventory,
+or advance its modification time. Install, update, and explicit adoption own
+managed-state persistence. `--fix-managed-state` remains an explicit adoption
+mutation.
+
+```bash
+pm package manage --project --json
+pm package manage --project --offline --json
+```
+
+For npm sources the SDK compares the recorded package version with the configured
+registry's `latest` dist-tag, honoring npm registry configuration. A different
+dist-tag version reports `update_available: true`; this is a channel comparison,
+including an intentional registry rollback. `last_update_remote_version` identifies
+the observed registry version. Missing provenance, invalid metadata, and failed
+lookups report unknown availability and incomplete health. Lookups are bounded
+to ten seconds and 64 KiB. npm execution failures use a stable public diagnostic
+code to avoid exposing registry credentials through command stderr. Invalid
+installed versions, registry versions, and JSON metadata also use stable reasons
+that do not reflect their raw contents.
+
+`--offline` performs no remote freshness lookup and reports `not_checked`,
+`offline_requested`, and unknown availability for supported remote sources.
+Runtime activation diagnostics still run. A bare installed npm extension name
+or recorded package name reuses its managed registry identity on reinstall;
+explicit local paths and bundled aliases retain their existing precedence.
+For a confirmed missing bare input, npm records match by exact manifest name,
+then stored directory, then recorded package identity. A weaker identity match
+cannot replace a stronger match because its record appears earlier.
+The selected stored package must parse as exactly one registry package name.
+URLs, local files, aliases, versioned specs, options, and shell-bearing values
+cannot become installation authority through managed metadata; invalid identity
+retains local-source recovery. Explicit `npm:` sources still accept their existing
+caller-selected package specs. Managed state is local installation provenance
+written by lifecycle operations, not permission for arbitrary source execution;
+protect project and global extension roots with the invoking account's filesystem
+permissions.
+
+## Isolated Schema History
+
+Linked tests using `pm_context_mode=schema` inherit project and global settings
+and extensions without inheriting source items. Settings are seeded through the
+workspace history writer against each sandbox's own initialized state. Nested
+`pm validate --check-history-drift --strict-exit` therefore validates that
+sandbox's configuration successfully. Out-of-band sandbox edits still fail
+history validation. Tracker context continues to retain the source audit history
+and its genuine drift. Source settings and history are never changed by seeding.
+
+## Help Discovery Before Mutation
+
+Bare `--help` and `-h` following declared options are discovery requests:
+
+```bash
+pm test pm-example --add --help
+pm files pm-example --add -h
+pm update pm-example -b -h
+pm create --file --help
+```
+
+These invocations print help and leave item and history bytes unchanged. To
+persist a literal flag-looking value, attach it explicitly: `--add=--help`.
+JSON help follows the same discovery policy. Bootstrap normalization preserves
+the argv terminator and attached values. The immediately preceding declared
+option is neutralized before parsing, regardless of whether its contract has
+value metadata. Short options, aliases, and booleans follow the same policy;
+no value parser runs for the neutralized option. The original help token stays
+reachable even when another adjacent option consumes the replacement token.
+Global boolean flags retain their presentation semantics, so `--json --help`
+still renders JSON help.
+Explicit bare assignments preserve a single value boundary during expansion,
+so values such as `body=--help` retain their literal meaning.

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -7,9 +7,9 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `init` | workspace | 30 | 30 |
 | `item` | intake | 20 | 20 |
 | `config` | workspace | 36 | 36 |
-| `extension` | extensions | 54 | 54 |
-| `package` | extensions | 55 | 55 |
-| `packages` | extensions | 55 | 55 |
+| `extension` | extensions | 55 | 55 |
+| `package` | extensions | 56 | 56 |
+| `packages` | extensions | 56 | 56 |
 | `install` | extensions | 27 | 27 |
 | `upgrade` | extensions | 29 | 29 |
 | `create` | intake | 100 | 100 |