@unbrained/pm-cli 2026.11.1 → 2026.11.3

package/dist/core/sentry/instrument.js

@@ -1,2 +1,2 @@
-(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]="16379104-dc20-5034-95ab-ebeb63f54952")}catch{}})();import{createRequire}from"node:module";import{resolvePmCliVersion}from"../packages/root.js";import{resolveTelemetryEnvironmentPolicy,resolveTelemetrySourceAttribution}from"../telemetry/policy.js";import{isPmCliExpectedError}from"../../sdk/errors.js";import{scrubInlineSensitiveAssignments,SENSITIVE_KEY_PATTERN}from"./sensitive-assignments.js";const OPT_OUT_VALUES=new Set(["1","true","yes","on"]);function isSentryDisabled(){return!!(OPT_OUT_VALUES.has((process.env.PM_SENTRY_DISABLED??"").trim().toLowerCase())||resolveTelemetryEnvironmentPolicy().telemetry_disabled||typeof process.env.VITEST=="string"||typeof process.env.VITEST_WORKER_ID=="string")}const ABSOLUTE_PATH_TOKEN_RE=/(^|[\s"'`(=])\/(?:[^\s"'`),;]+)/g,FILE_URL_PATH_RE=/file:\/\/\/?[^\s"'`),;]+/giu,WINDOWS_PATH_TOKEN_RE=/\b[A-Za-z]:\\[^\s"'`),;]+/g,PRIVATE_IP_RE=/\b(?:10\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)|172\.(?:1[6-9]|2\d|3[01])\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)|192\.168\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d))\b/g,PATH_FIELD_KEY_PATTERN=/(?:^|[_-])(path|filename|file|module|cwd|dir|directory|location|source|script)s?$/i,MAX_KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS=15,KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS=["[starter-extension] activating","[starter-extension] all 8 capabilities registered.","[starter-extension] commands:","[starter] preflight check for workspace","[starter] output_format service override active","[pm-ext-ts-starter] activating","[pm-ext-ts-starter] all capabilities registered.","run `pm init` first to initialise a pm workspace"];function looksLikeFilesystemPath(value){const normalized=value.trim();return normalized.length===0?!1:normalized.startsWith("/")||normalized.startsWith("file://")||/^[A-Za-z]:\\/.test(normalized)||normalized.startsWith("\\\\")?!0:normalized.includes("/home/")}function scrubString(value,keyHint){if(keyHint&&PATH_FIELD_KEY_PATTERN.test(keyHint)&&looksLikeFilesystemPath(value))return"[scrubbed_path]";const scrubbed=scrubInlineSensitiveAssignments(value).replaceAll(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/giu,"[scrubbed_email]").replaceAll(/bearer\s+[a-z0-9._=-]+/giu,"bearer [scrubbed]").replaceAll(/sntr[ysu]_[A-Za-z0-9_-]+/g,"[scrubbed_sentry_token]").replaceAll(PRIVATE_IP_RE,"[scrubbed_ip]").replaceAll(FILE_URL_PATH_RE,"[scrubbed_path]").replaceAll(WINDOWS_PATH_TOKEN_RE,"[scrubbed_path]").replaceAll(ABSOLUTE_PATH_TOKEN_RE,(_match,prefix)=>`${prefix}[scrubbed_path]`);return looksLikeFilesystemPath(scrubbed)?"[scrubbed_path]":scrubbed}function scrubEventData(obj){const result={};for(const[key,value]of Object.entries(obj))SENSITIVE_KEY_PATTERN.test(key)||key.startsWith("sentry.message.parameter.")?result[key]="[scrubbed]":typeof value=="string"?result[key]=scrubString(value,key):Array.isArray(value)?result[key]=value.map(entry=>typeof entry=="string"?scrubString(entry,key):entry&&typeof entry=="object"?scrubEventData(entry):entry):value&&typeof value=="object"?result[key]=scrubEventData(value):result[key]=value;return result}function scrubStackFrame(frame){for(const key of["filename","absPath","abs_path","module"]){const rawValue=frame[key];typeof rawValue=="string"&&(frame[key]=scrubString(rawValue,key))}const contextLine=frame.context_line;typeof contextLine=="string"&&(frame.context_line=scrubString(contextLine,"context_line"));for(const key of["pre_context","post_context"]){const context=frame[key];Array.isArray(context)&&(frame[key]=context.map(entry=>typeof entry=="string"?scrubString(entry,key):entry))}frame.vars&&typeof frame.vars=="object"&&(frame.vars=scrubEventData(frame.vars)),frame.data&&typeof frame.data=="object"&&(frame.data=scrubEventData(frame.data))}const requireFromInstrument=createRequire(import.meta.url),defaultSentryLoader=()=>requireFromInstrument("@sentry/node");let _sentry,_initDone=!1,_loadSentry=defaultSentryLoader;const PM_CLI_SENTRY_DSN="https://bf7ad2ec76c0051c2ee94e48e8bd6868@o4510603477712896.ingest.de.sentry.io/4511316775338064";function hasPmCliErrorPrefix(value){return/^\s*PmCliError:/.test(value)}function isKnownNoisyConsoleMessage(value){const normalized=value.trim().toLowerCase();return normalized.length===0?!1:KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS.some(pattern=>normalized.includes(pattern))}function isKnownNoisyConsoleEvent(event){return event.logger!=="console"?!1:typeof event.message=="string"&&isKnownNoisyConsoleMessage(event.message)?!0:Array.isArray(event.exception?.values)&&event.exception.values.some(entry=>typeof entry.value=="string"&&isKnownNoisyConsoleMessage(entry.value))}function isNodeRuntimeWarningEvent(event){if(event.logger!=="console")return!1;const isRuntimeWarning=value=>typeof value=="string"&&/^\(node:\d+\) MaxListenersExceededWarning: Possible EventEmitter memory leak detected\./.test(value);return isRuntimeWarning(event.message)?!0:Array.isArray(event.exception?.values)&&event.exception.values.some(entry=>isRuntimeWarning(entry.value))}function isExpectedCliErrorEvent(event,originalException){return originalException instanceof Error?isPmCliExpectedError(originalException):!!(event.exception?.values?.some(ex=>ex.type==="PmCliError")||event.exception?.values?.some(ex=>typeof ex.value=="string"&&hasPmCliErrorPrefix(ex.value))||event.logger==="console"&&typeof event.message=="string"&&hasPmCliErrorPrefix(event.message))}function isPmCliErrorBreadcrumb(breadcrumb){return breadcrumb.category==="console"&&typeof breadcrumb.message=="string"&&hasPmCliErrorPrefix(breadcrumb.message)}function isKnownNoisyConsoleBreadcrumb(breadcrumb){return breadcrumb.category==="console"&&typeof breadcrumb.message=="string"&&isKnownNoisyConsoleMessage(breadcrumb.message)}function resolveCliVersion(){return resolvePmCliVersion(import.meta.url,["../../.."])??"0.0.0"}function resolveEnvironment(){const explicit=process.env.SENTRY_ENVIRONMENT?.trim();if(explicit&&explicit.length>0)return explicit;if(process.env.VITEST||process.env.VITEST_WORKER_ID||process.env.NODE_ENV==="test")return"test";if(process.env.CI)return"ci";const source=resolveTelemetrySourceAttribution().source_context;return source==="user"?"production":source}const DEFAULT_TRACES_SAMPLE_RATE=.2;function resolveTracesSampleRate(){const raw=process.env.SENTRY_TRACES_SAMPLE_RATE?.trim();if(!raw)return DEFAULT_TRACES_SAMPLE_RATE;const parsed=Number(raw);return!Number.isFinite(parsed)||parsed<0||parsed>1?DEFAULT_TRACES_SAMPLE_RATE:parsed}function scrubSentryExceptionValues(event){if(event.exception?.values){for(const exception of event.exception.values)if(exception.value&&(exception.value=scrubString(exception.value,"value")),exception.stacktrace?.frames)for(const frame of exception.stacktrace.frames)scrubStackFrame(frame)}}function scrubSentryBreadcrumbs(event){if(event.breadcrumbs)for(const breadcrumb of event.breadcrumbs)breadcrumb.message&&(breadcrumb.message=scrubString(breadcrumb.message)),breadcrumb.data&&typeof breadcrumb.data=="object"&&(breadcrumb.data=scrubEventData(breadcrumb.data))}function scrubSentryContexts(event){if(event.contexts)for(const[ctxKey,ctx]of Object.entries(event.contexts))ctx&&typeof ctx=="object"&&(event.contexts[ctxKey]=scrubEventData(ctx))}function scrubSentryRecordField(event,key){const target=event,value=target[key];value&&typeof value=="object"&&(target[key]=scrubEventData(value))}function sourceContextEnvironment(source){if(!process.env.SENTRY_ENVIRONMENT?.trim()&&(source==="automation"||source==="test"||source==="dogfood"||source==="user"))return source==="user"?"production":source}function applySourceContextEnvironment(event){const environment=sourceContextEnvironment(event.tags?.["pm.source_context"]);environment&&(event.environment=environment)}const beforeSend=(event,hint)=>{if(isExpectedCliErrorEvent(event,hint?.originalException)||isKnownNoisyConsoleEvent(event))return null;applySourceContextEnvironment(event),isNodeRuntimeWarningEvent(event)&&(event.level="warning",event.tags={...event.tags,"pm.diagnostic_class":"node_runtime_warning"}),event.message&&(event.message=scrubString(event.message,"message")),event.transaction&&(event.transaction=scrubString(event.transaction,"transaction")),scrubSentryExceptionValues(event),scrubSentryBreadcrumbs(event),scrubSentryRecordField(event,"extra"),scrubSentryContexts(event);for(const key of["request","user","tags"])scrubSentryRecordField(event,key);return event},beforeSendTransaction=event=>(applySourceContextEnvironment(event),event.breadcrumbs&&(event.breadcrumbs=event.breadcrumbs.filter(breadcrumb=>!isPmCliErrorBreadcrumb(breadcrumb)&&!isKnownNoisyConsoleBreadcrumb(breadcrumb)),scrubSentryBreadcrumbs(event)),scrubSentryContexts(event),event),beforeSendSpan=span=>scrubEventData(span),beforeSendLog=log=>{if(log.message=scrubString(log.message),log.attributes){const environment=sourceContextEnvironment(log.attributes["pm.source_context"]);environment&&(log.attributes["sentry.environment"]=environment),log.attributes=scrubEventData(log.attributes)}return log};function applySerializedLogEnvironment(attributes){const environment=sourceContextEnvironment(attributes["pm.source_context"]?.value);environment&&(attributes["sentry.environment"]={type:"string",value:environment})}function scrubSentryLogEnvelope(envelope){for(const item of envelope[1])if(item[0].type==="log")for(const log of item[1].items){log.body=scrubString(log.body);const attributes=log.attributes;if(attributes){applySerializedLogEnvironment(attributes);for(const[key,attribute]of Object.entries(attributes)){const value=scrubEventData({[key]:attribute.value})[key];typeof value=="string"&&(attributes[key]={type:"string",value})}}}}const beforeBreadcrumb=breadcrumb=>isPmCliErrorBreadcrumb(breadcrumb)||isKnownNoisyConsoleBreadcrumb(breadcrumb)?null:(breadcrumb.message&&(breadcrumb.message=scrubString(breadcrumb.message,"message")),breadcrumb.data&&typeof breadcrumb.data=="object"&&(breadcrumb.data=scrubEventData(breadcrumb.data)),breadcrumb);async function ensureSentryInit(){if(_initDone)return _sentry;if(_initDone=!0,isSentryDisabled())return;const SentryModule=_loadSentry(),dsn=process.env.SENTRY_DSN?.trim()||PM_CLI_SENTRY_DSN,release=resolveCliVersion();SentryModule.init({dsn,release:`pm-cli@${release}`,environment:resolveEnvironment(),tracesSampleRate:resolveTracesSampleRate(),enableLogs:!0,attachStacktrace:!0,normalizeDepth:6,shutdownTimeout:3e3,traceLifecycle:"stream",dataCollection:{userInfo:!1,cookies:!1,httpHeaders:{request:!1,response:!1},httpBodies:[],urlQueryParams:!1,genAI:{inputs:!1,outputs:!1},databaseQueryData:!1,graphQL:{document:!1,variables:!1},stackFrameVariables:!1,frameContextLines:0},serverName:void 0,integrations:[SentryModule.extraErrorDataIntegration({depth:4,captureErrorCause:!1}),SentryModule.captureConsoleIntegration({levels:["warn","error"]})],initialScope:{tags:{"cli.name":"pm-cli","cli.version":release,"runtime.node":process.version,"runtime.platform":process.platform,"runtime.arch":process.arch}},beforeSend,beforeSendTransaction,beforeSendSpan:SentryModule.withStreamedSpan(beforeSendSpan),beforeSendLog,beforeBreadcrumb});const client=SentryModule.getClient();if(!client)return;const attribution=resolveTelemetrySourceAttribution();return SentryModule.setTags({"pm.version":release,"pm.source_context":attribution.source_context,"pm.source_context_source":attribution.source_context_source}),SentryModule.setAttribute("pm.source_context",attribution.source_context),client.on("beforeEnvelope",scrubSentryLogEnvelope),_sentry=SentryModule,SentryModule}async function ensureSentryCommandTracing(telemetryEnabled){if(telemetryEnabled!==!0||!OPT_OUT_VALUES.has((process.env.PM_SENTRY_TRACE_COMMANDS??"").trim().toLowerCase())||resolveTracesSampleRate()===0||isSentryDisabled())return!1;try{return await ensureSentryInit()!==void 0}catch{return _sentry=void 0,!1}}function getSentry(){return _sentry}const _testOnly={isExpectedCliErrorEvent,isKnownNoisyConsoleEvent,isNodeRuntimeWarningEvent,isPmCliErrorBreadcrumb,isKnownNoisyConsoleBreadcrumb,scrubString,scrubEventData,resolveTracesSampleRate,KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS,MAX_KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS,defaultSentryLoader,setSentryLoaderForTests(loader){_loadSentry=loader??defaultSentryLoader},resetSentryStateForTests(){_sentry=void 0,_initDone=!1}};export{_testOnly,ensureSentryCommandTracing,ensureSentryInit,getSentry};
+(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]="93725298-6091-543b-969d-bac38d70be89")}catch{}})();import{createRequire}from"node:module";import{resolvePmCliVersion}from"../packages/root.js";import{resolveTelemetryEnvironmentPolicy,resolveTelemetrySourceAttribution}from"../telemetry/policy.js";import{isPmCliExpectedError}from"../../sdk/errors.js";import{crashReportErrorContext,omitEmbeddedPmCliErrorDetails}from"../shared/error-details.js";import{scrubInlineSensitiveAssignments,SENSITIVE_KEY_PATTERN}from"./sensitive-assignments.js";const OPT_OUT_VALUES=new Set(["1","true","yes","on"]);function isSentryDisabled(){return!!(OPT_OUT_VALUES.has((process.env.PM_SENTRY_DISABLED??"").trim().toLowerCase())||resolveTelemetryEnvironmentPolicy().telemetry_disabled||typeof process.env.VITEST=="string"||typeof process.env.VITEST_WORKER_ID=="string")}const ABSOLUTE_PATH_TOKEN_RE=/(^|[\s"'`(=])\/(?:[^\s"'`),;]+)/g,FILE_URL_PATH_RE=/file:\/\/\/?[^\s"'`),;]+/giu,WINDOWS_PATH_TOKEN_RE=/\b[A-Za-z]:\\[^\s"'`),;]+/g,PRIVATE_IP_RE=/\b(?:10\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)|172\.(?:1[6-9]|2\d|3[01])\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)|192\.168\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d))\b/g,PATH_FIELD_KEY_PATTERN=/(?:^|[_-])(path|filename|file|module|cwd|dir|directory|location|source|script)s?$/i,MAX_KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS=15,KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS=["[starter-extension] activating","[starter-extension] all 8 capabilities registered.","[starter-extension] commands:","[starter] preflight check for workspace","[starter] output_format service override active","[pm-ext-ts-starter] activating","[pm-ext-ts-starter] all capabilities registered.","run `pm init` first to initialise a pm workspace"];function looksLikeFilesystemPath(value){const normalized=value.trim();return normalized.length===0?!1:normalized.startsWith("/")||normalized.startsWith("file://")||/^[A-Za-z]:\\/.test(normalized)||normalized.startsWith("\\\\")?!0:normalized.includes("/home/")}function scrubString(value,keyHint){if(keyHint&&PATH_FIELD_KEY_PATTERN.test(keyHint)&&looksLikeFilesystemPath(value))return"[scrubbed_path]";const scrubbed=scrubInlineSensitiveAssignments(value).replaceAll(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/giu,"[scrubbed_email]").replaceAll(/bearer\s+[a-z0-9._=-]+/giu,"bearer [scrubbed]").replaceAll(/sntr[ysu]_[A-Za-z0-9_-]+/g,"[scrubbed_sentry_token]").replaceAll(PRIVATE_IP_RE,"[scrubbed_ip]").replaceAll(FILE_URL_PATH_RE,"[scrubbed_path]").replaceAll(WINDOWS_PATH_TOKEN_RE,"[scrubbed_path]").replaceAll(ABSOLUTE_PATH_TOKEN_RE,(_match,prefix)=>`${prefix}[scrubbed_path]`);return looksLikeFilesystemPath(scrubbed)?"[scrubbed_path]":scrubbed}function scrubEventData(obj){const result={};for(const[key,value]of Object.entries(obj))SENSITIVE_KEY_PATTERN.test(key)||key.startsWith("sentry.message.parameter.")?result[key]="[scrubbed]":typeof value=="string"?result[key]=scrubString(value,key):Array.isArray(value)?result[key]=value.map(entry=>typeof entry=="string"?scrubString(entry,key):entry&&typeof entry=="object"?scrubEventData(entry):entry):value&&typeof value=="object"?result[key]=scrubEventData(value):result[key]=value;return result}function scrubStackFrame(frame){for(const key of["filename","absPath","abs_path","module"]){const rawValue=frame[key];typeof rawValue=="string"&&(frame[key]=scrubString(rawValue,key))}const contextLine=frame.context_line;typeof contextLine=="string"&&(frame.context_line=scrubString(contextLine,"context_line"));for(const key of["pre_context","post_context"]){const context=frame[key];Array.isArray(context)&&(frame[key]=context.map(entry=>typeof entry=="string"?scrubString(entry,key):entry))}frame.vars&&typeof frame.vars=="object"&&(frame.vars=scrubEventData(frame.vars)),frame.data&&typeof frame.data=="object"&&(frame.data=scrubEventData(frame.data))}const requireFromInstrument=createRequire(import.meta.url),defaultSentryLoader=()=>requireFromInstrument("@sentry/node");let _sentry,_initDone=!1,_loadSentry=defaultSentryLoader;const PM_CLI_SENTRY_DSN="https://bf7ad2ec76c0051c2ee94e48e8bd6868@o4510603477712896.ingest.de.sentry.io/4511316775338064";function hasPmCliErrorPrefix(value){return/^\s*PmCliError:/.test(value)}function isKnownNoisyConsoleMessage(value){const normalized=value.trim().toLowerCase();return normalized.length===0?!1:KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS.some(pattern=>normalized.includes(pattern))}function isKnownNoisyConsoleEvent(event){return event.logger!=="console"?!1:typeof event.message=="string"&&isKnownNoisyConsoleMessage(event.message)?!0:Array.isArray(event.exception?.values)&&event.exception.values.some(entry=>typeof entry.value=="string"&&isKnownNoisyConsoleMessage(entry.value))}function isNodeRuntimeWarningEvent(event){if(event.logger!=="console")return!1;const isRuntimeWarning=value=>typeof value=="string"&&/^\(node:\d+\) MaxListenersExceededWarning: Possible EventEmitter memory leak detected\./.test(value);return isRuntimeWarning(event.message)?!0:Array.isArray(event.exception?.values)&&event.exception.values.some(entry=>isRuntimeWarning(entry.value))}function isExpectedCliErrorEvent(event,originalException){return originalException instanceof Error?isPmCliExpectedError(originalException):!!(event.exception?.values?.some(ex=>ex.type==="PmCliError")||event.exception?.values?.some(ex=>typeof ex.value=="string"&&hasPmCliErrorPrefix(ex.value))||event.logger==="console"&&typeof event.message=="string"&&hasPmCliErrorPrefix(event.message))}function isPmCliErrorBreadcrumb(breadcrumb){return breadcrumb.category==="console"&&typeof breadcrumb.message=="string"&&hasPmCliErrorPrefix(breadcrumb.message)}function isKnownNoisyConsoleBreadcrumb(breadcrumb){return breadcrumb.category==="console"&&typeof breadcrumb.message=="string"&&isKnownNoisyConsoleMessage(breadcrumb.message)}function resolveCliVersion(){return resolvePmCliVersion(import.meta.url,["../../.."])??"0.0.0"}function resolveEnvironment(){const explicit=process.env.SENTRY_ENVIRONMENT?.trim();if(explicit&&explicit.length>0)return explicit;if(process.env.VITEST||process.env.VITEST_WORKER_ID||process.env.NODE_ENV==="test")return"test";if(process.env.CI)return"ci";const source=resolveTelemetrySourceAttribution().source_context;return source==="user"?"production":source}const DEFAULT_TRACES_SAMPLE_RATE=.2;function resolveTracesSampleRate(){const raw=process.env.SENTRY_TRACES_SAMPLE_RATE?.trim();if(!raw)return DEFAULT_TRACES_SAMPLE_RATE;const parsed=Number(raw);return!Number.isFinite(parsed)||parsed<0||parsed>1?DEFAULT_TRACES_SAMPLE_RATE:parsed}function scrubSentryExceptionValues(event){if(event.exception?.values){for(const exception of event.exception.values)if(exception.value&&(exception.value=scrubString(exception.value,"value")),exception.stacktrace?.frames)for(const frame of exception.stacktrace.frames)scrubStackFrame(frame)}}function scrubSentryBreadcrumbs(event){if(event.breadcrumbs)for(const breadcrumb of event.breadcrumbs)breadcrumb.message&&(breadcrumb.message=scrubString(breadcrumb.message)),breadcrumb.data&&typeof breadcrumb.data=="object"&&(breadcrumb.data=scrubEventData(breadcrumb.data))}function scrubSentryContexts(event){if(event.contexts)for(const[ctxKey,ctx]of Object.entries(event.contexts))ctx&&typeof ctx=="object"&&(event.contexts[ctxKey]=scrubEventData(ctx))}function scrubSentryRecordField(event,key){const target=event,value=target[key];value&&typeof value=="object"&&(target[key]=scrubEventData(value))}function sourceContextEnvironment(source){if(!process.env.SENTRY_ENVIRONMENT?.trim()&&(source==="automation"||source==="test"||source==="dogfood"||source==="user"))return source==="user"?"production":source}function applySourceContextEnvironment(event){const environment=sourceContextEnvironment(event.tags?.["pm.source_context"]);environment&&(event.environment=environment)}function omitProducerDiagnostics(event,originalException){const ownErrorContext=readOwnErrorContextExtra(event.extra);omitEmbeddedPmCliErrorDetails([event.contexts,event.extra,event.breadcrumbs]),rebuildErrorDataContexts(event.contexts,originalException),ownErrorContext!==void 0&&(event.extra.error_context=crashReportErrorContext(ownErrorContext))}function readOwnErrorContextExtra(extra){if(!(typeof extra!="object"||extra===null||!Object.hasOwn(extra,"error_context")))return extra.error_context}function rebuildErrorDataContexts(contexts,originalException){if(typeof contexts!="object"||contexts===null||typeof originalException!="object"||originalException===null)return;const record=contexts,keys=new Set(errorDataContextKeys(originalException)),rebuilt=safeErrorDataEntry(originalException);for(const[key,entry]of Object.entries(record))(keys.has(key)||typeof entry=="object"&&entry!==null&&Object.hasOwn(entry,"context"))&&(record[key]=rebuilt??{})}function errorDataContextKeys(error){try{return[error.name,error.constructor?.name].filter(candidate=>typeof candidate=="string"&&candidate.length>0)}catch{return[]}}function safeErrorDataEntry(error){try{const entry=crashReportErrorContext(error),context=Object.getOwnPropertyDescriptor(error,"context");return context!==void 0&&"value"in context&&(entry.context=crashReportErrorContext(context.value)),entry}catch{return}}const beforeSend=(event,hint)=>{if(isExpectedCliErrorEvent(event,hint?.originalException)||isKnownNoisyConsoleEvent(event))return null;omitProducerDiagnostics(event,hint?.originalException),applySourceContextEnvironment(event),isNodeRuntimeWarningEvent(event)&&(event.level="warning",event.tags={...event.tags,"pm.diagnostic_class":"node_runtime_warning"}),event.message&&(event.message=scrubString(event.message,"message")),event.transaction&&(event.transaction=scrubString(event.transaction,"transaction")),scrubSentryExceptionValues(event),scrubSentryBreadcrumbs(event),scrubSentryRecordField(event,"extra"),scrubSentryContexts(event);for(const key of["request","user","tags"])scrubSentryRecordField(event,key);return event},beforeSendTransaction=event=>(omitProducerDiagnostics(event),applySourceContextEnvironment(event),event.breadcrumbs&&(event.breadcrumbs=event.breadcrumbs.filter(breadcrumb=>!isPmCliErrorBreadcrumb(breadcrumb)&&!isKnownNoisyConsoleBreadcrumb(breadcrumb)),scrubSentryBreadcrumbs(event)),scrubSentryContexts(event),event),beforeSendSpan=span=>scrubEventData(span),beforeSendLog=log=>{if(log.message=scrubString(log.message),log.attributes){const environment=sourceContextEnvironment(log.attributes["pm.source_context"]);environment&&(log.attributes["sentry.environment"]=environment),log.attributes=scrubEventData(log.attributes)}return log};function applySerializedLogEnvironment(attributes){const environment=sourceContextEnvironment(attributes["pm.source_context"]?.value);environment&&(attributes["sentry.environment"]={type:"string",value:environment})}function scrubSentryLogEnvelope(envelope){for(const item of envelope[1])if(item[0].type==="log")for(const log of item[1].items){log.body=scrubString(log.body);const attributes=log.attributes;if(attributes){applySerializedLogEnvironment(attributes);for(const[key,attribute]of Object.entries(attributes)){const value=scrubEventData({[key]:attribute.value})[key];typeof value=="string"&&(attributes[key]={type:"string",value})}}}}const beforeBreadcrumb=breadcrumb=>isPmCliErrorBreadcrumb(breadcrumb)||isKnownNoisyConsoleBreadcrumb(breadcrumb)?null:(breadcrumb.message&&(breadcrumb.message=scrubString(breadcrumb.message,"message")),breadcrumb.data&&typeof breadcrumb.data=="object"&&(breadcrumb.data=scrubEventData(breadcrumb.data)),breadcrumb);async function ensureSentryInit(){if(_initDone)return _sentry;if(_initDone=!0,isSentryDisabled())return;const SentryModule=_loadSentry(),dsn=process.env.SENTRY_DSN?.trim()||PM_CLI_SENTRY_DSN,release=resolveCliVersion();SentryModule.init({dsn,release:`pm-cli@${release}`,environment:resolveEnvironment(),tracesSampleRate:resolveTracesSampleRate(),enableLogs:!0,attachStacktrace:!0,normalizeDepth:6,shutdownTimeout:3e3,traceLifecycle:"stream",dataCollection:{userInfo:!1,cookies:!1,httpHeaders:{request:!1,response:!1},httpBodies:[],urlQueryParams:!1,genAI:{inputs:!1,outputs:!1},databaseQueryData:!1,graphQL:{document:!1,variables:!1},stackFrameVariables:!1,frameContextLines:0},serverName:void 0,integrations:[SentryModule.extraErrorDataIntegration({depth:4,captureErrorCause:!1}),SentryModule.captureConsoleIntegration({levels:["warn","error"]})],initialScope:{tags:{"cli.name":"pm-cli","cli.version":release,"runtime.node":process.version,"runtime.platform":process.platform,"runtime.arch":process.arch}},beforeSend,beforeSendTransaction,beforeSendSpan:SentryModule.withStreamedSpan(beforeSendSpan),beforeSendLog,beforeBreadcrumb});const client=SentryModule.getClient();if(!client)return;const attribution=resolveTelemetrySourceAttribution();return SentryModule.setTags({"pm.version":release,"pm.source_context":attribution.source_context,"pm.source_context_source":attribution.source_context_source}),SentryModule.setAttribute("pm.source_context",attribution.source_context),client.on("beforeEnvelope",scrubSentryLogEnvelope),_sentry=SentryModule,SentryModule}async function ensureSentryCommandTracing(telemetryEnabled){if(telemetryEnabled!==!0||!OPT_OUT_VALUES.has((process.env.PM_SENTRY_TRACE_COMMANDS??"").trim().toLowerCase())||resolveTracesSampleRate()===0||isSentryDisabled())return!1;try{return await ensureSentryInit()!==void 0}catch{return _sentry=void 0,!1}}function getSentry(){return _sentry}const _testOnly={isExpectedCliErrorEvent,isKnownNoisyConsoleEvent,isNodeRuntimeWarningEvent,isPmCliErrorBreadcrumb,isKnownNoisyConsoleBreadcrumb,scrubString,scrubEventData,resolveTracesSampleRate,KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS,MAX_KNOWN_NOISY_CONSOLE_MESSAGE_PATTERNS,defaultSentryLoader,setSentryLoaderForTests(loader){_loadSentry=loader??defaultSentryLoader},resetSentryStateForTests(){_sentry=void 0,_initDone=!1}};export{_testOnly,ensureSentryCommandTracing,ensureSentryInit,getSentry};
 //# sourceMappingURL=instrument.js.map

package/dist/core/shared/error-details.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @module core/shared/error-details
+ *
+ * Admits and bounds producer-owned structured diagnostics carried on an
+ * expected error (`PmCliErrorContext.details`, GH-1631). The host never
+ * interprets these values: it checks that they are plain, well-formed JSON,
+ * renders them whole within a declared byte ceiling, and otherwise replaces
+ * them with an omission receipt. Telemetry and crash reporting never read
+ * them.
+ *
+ * Every traversal reads own data properties only (accessors are refused, never
+ * invoked) and counts the compact JSON encoding as it walks, so a shared or
+ * deeply repeated structure is abandoned as soon as it crosses the ceiling
+ * instead of being expanded first.
+ */
+import type { PmCliErrorDetails,PmCliErrorDetailsOmission } from "./errors.js";
+export type { PmCliErrorDetailsOmission,PmCliErrorDetailsRejection } from "./errors.js";
+/** Declared ceilings for producer-owned error diagnostics. */
+export declare const PM_CLI_ERROR_DETAILS_LIMITS:Readonly<{
+/** Largest compact UTF-8 JSON encoding rendered; larger diagnostics are omitted whole. */
+max_bytes:4096;
+/** Deepest container nesting accepted below the `details` object itself. */
+max_depth:8;
+}>;
+/** Outcome of admitting one diagnostics value. */
+export type PmCliErrorDetailsAdmission = {
+ok:true;
+details:PmCliErrorDetails;
+byte_length:number;
+} | {
+ok:false;
+omission:PmCliErrorDetailsOmission;
+};
+/**
+ * Admit a diagnostics value: a plain object whose leaves are null, booleans,
+ * finite numbers and well-formed strings, nested at most
+ * {@link PM_CLI_ERROR_DETAILS_LIMITS}.max_depth containers deep and encoding
+ * to at most `max_bytes` of compact UTF-8 JSON. Returns a detached copy so
+ * later mutation of the producer's object cannot change a raised refusal.
+ * Accessor properties are refused without being invoked, and the walk stops
+ * at the byte ceiling, so admission cost is bounded by the ceiling.
+ */
+export declare function admitPmCliErrorDetails(value:unknown):PmCliErrorDetailsAdmission;
+/** Check the diagnostics shape and byte ceiling. */
+export declare function isPmCliErrorDetails(value:unknown):value is PmCliErrorDetails;
+/**
+ * Project diagnostics for a structured error envelope: render them whole when
+ * they are well-formed and fit the byte ceiling, otherwise return only the
+ * omission receipt. Partial structures are never emitted.
+ */
+export declare function projectPmCliErrorDetails(value:unknown):{
+details:PmCliErrorDetails;
+} | {
+details_omitted:PmCliErrorDetailsOmission;
+} | undefined;
+/**
+ * Plain snapshot of a foreign error context, taken once at a host boundary:
+ * own enumerable data properties are copied, accessors are never run, a
+ * `details` accessor becomes an `unsupported_value` receipt, and a context the
+ * host cannot inspect at all (a hostile proxy) becomes an empty object.
+ */
+export declare function snapshotPmCliErrorContext(context:unknown):Record<string,unknown>;
+/**
+ * Project the diagnostics of an error context: `details` rendered through
+ * {@link projectPmCliErrorDetails}, otherwise a valid host-recorded
+ * `details_omitted` receipt. Accessors are reported, never run, and an
+ * uninspectable context yields an `unsupported_value` receipt.
+ */
+export declare function projectPmCliErrorContextDetailsSlot(context:unknown):ReturnType<typeof projectPmCliErrorDetails>;
+/**
+ * Bound an error context for a transport that forwards the context as-is
+ * (MCP): diagnostics are rendered through {@link projectPmCliErrorContextDetailsSlot},
+ * every other host field is left untouched.
+ */
+export declare function projectPmCliErrorContextDetails(context:unknown):unknown;
+/**
+ * Remove producer diagnostics, and the receipt describing them (its path can
+ * echo producer keys), from a context bound for telemetry or crash reporting.
+ */
+export declare function omitPmCliErrorDetails(context:unknown):unknown;
+/**
+ * The only form of an error context a crash report may carry: a getter-free
+ * snapshot reduced to its top-level primitive fields, without producer
+ * diagnostics, their receipt or a serializer. Nested values are dropped,
+ * because a custom toJSON or a shared reference could carry diagnostics
+ * under any other key.
+ */
+export declare function crashReportErrorContext(context:unknown):Record<string,unknown>;
+/**
+ * Discard every embedded error context (`*.context` and `*.error_context`
+ * objects) inside a serialized crash-report payload, in place, replacing each
+ * with an empty object. These copies were produced by the reporter's own
+ * serializer (which runs custom toJSON hooks) and their originals cannot be
+ * recovered, so no projection of them can be proven free of diagnostics.
+ * Console captures and breadcrumbs carry them at arbitrary positions, so a
+ * shallow scrub is not enough.
+ */
+export declare function omitEmbeddedPmCliErrorDetails(payload:unknown):void;

package/dist/core/shared/error-details.js

@@ -0,0 +1,2 @@
+(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]="a483f454-e261-5232-bae0-da3cdb8c0518")}catch{}})();const PM_CLI_ERROR_DETAILS_LIMITS=Object.freeze({max_bytes:4096,max_depth:8}),MAX_OMISSION_PATH_BYTES=160,DETAILS_REJECTIONS=new Set(["not_plain_object","unsupported_value","non_finite_number","malformed_unicode","reserved_key","depth_limit","byte_limit","diagnostic_budget"]),LONE_SURROGATE=/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u,RESERVED_KEYS=new Set(["__proto__"]);class DetailsShapeError extends Error{reason;path;constructor(reason,path){super(reason),this.reason=reason,this.path=path}}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const prototype=Object.getPrototypeOf(value);return prototype===Object.prototype||prototype===null}function childPath(path,key){return/^[A-Za-z_$][\w$]*$/u.test(key)?`${path}.${key}`:`${path}[${JSON.stringify(key)}]`}function boundPath(path){if(Buffer.byteLength(path,"utf8")<=MAX_OMISSION_PATH_BYTES)return path;let bounded="",bytes=Buffer.byteLength("\u2026","utf8");for(const character of path){if(bytes+=Buffer.byteLength(character,"utf8"),bytes>MAX_OMISSION_PATH_BYTES)break;bounded+=character}return`${bounded}\u2026`}function charge(budget,bytes,path){if(budget.bytes+=bytes,!(budget.bytes<=PM_CLI_ERROR_DETAILS_LIMITS.max_bytes))throw new DetailsShapeError("byte_limit",path)}function assertCanFit(budget,minimumBytes,path){if(budget.bytes+minimumBytes>PM_CLI_ERROR_DETAILS_LIMITS.max_bytes)throw new DetailsShapeError("byte_limit",path)}function readOwnDataValue(container,key,path){const descriptor=Object.getOwnPropertyDescriptor(container,key);if(descriptor===void 0||!("value"in descriptor))throw new DetailsShapeError("unsupported_value",path);return descriptor.value}function copyDetailLeaf(value,path,budget){if(typeof value=="number"&&!Number.isFinite(value))throw new DetailsShapeError("non_finite_number",path);if(typeof value=="string"&&(assertCanFit(budget,value.length+2,path),LONE_SURROGATE.test(value)))throw new DetailsShapeError("malformed_unicode",path);if(value!==null&&!["boolean","number","string"].includes(typeof value))throw new DetailsShapeError("unsupported_value",path);return charge(budget,Buffer.byteLength(JSON.stringify(value),"utf8"),path),value}function copyDetailValue(value,path,depth,budget){if(typeof value!="object"||value===null)return copyDetailLeaf(value,path,budget);if(depth>=PM_CLI_ERROR_DETAILS_LIMITS.max_depth)throw new DetailsShapeError("depth_limit",path);if(Array.isArray(value)){const length=readOwnDataValue(value,"length",path);if(typeof length!="number"||!Number.isSafeInteger(length)||length<0)throw new DetailsShapeError("unsupported_value",path);charge(budget,length>0?length+1:2,path);const copy=[];for(let index=0;index<length;index+=1){const entryPath=`${path}[${index}]`;copy.push(copyDetailValue(readOwnDataValue(value,String(index),entryPath),entryPath,depth+1,budget))}return copy}if(!isPlainObject(value))throw new DetailsShapeError("unsupported_value",path);return copyDetailObject(value,path,depth+1,budget)}function copyDetailObject(value,path,depth,budget){const keys=Object.keys(value);charge(budget,keys.length>0?keys.length+1:2,path);const copy={};for(const key of keys){assertCanFit(budget,key.length+3,path);const keyPath=childPath(path,key);if(RESERVED_KEYS.has(key))throw new DetailsShapeError("reserved_key",keyPath);if(LONE_SURROGATE.test(key))throw new DetailsShapeError("malformed_unicode",keyPath);charge(budget,Buffer.byteLength(JSON.stringify(key),"utf8")+1,keyPath),copy[key]=copyDetailValue(readOwnDataValue(value,key,keyPath),keyPath,depth,budget)}return copy}function classifyAdmissionFault(error){try{if(error instanceof DetailsShapeError)return error}catch{}return new DetailsShapeError("unsupported_value","details")}function admitPmCliErrorDetails(value){const byteLimit=PM_CLI_ERROR_DETAILS_LIMITS.max_bytes,budget={bytes:0};try{if(!isPlainObject(value))throw new DetailsShapeError("not_plain_object","details");return{ok:!0,details:copyDetailObject(value,"details",0,budget),byte_length:budget.bytes}}catch(error){const refusal=classifyAdmissionFault(error);return{ok:!1,omission:refusal.reason==="byte_limit"?{reason:"byte_limit",byte_limit:byteLimit}:{reason:refusal.reason,path:boundPath(refusal.path),byte_limit:byteLimit}}}}function isPmCliErrorDetails(value){return admitPmCliErrorDetails(value).ok}function projectPmCliErrorDetails(value){if(value===void 0)return;const admission=admitPmCliErrorDetails(value);return admission.ok?{details:admission.details}:{details_omitted:admission.omission}}function unsupportedDetailsReceipt(){return{reason:"unsupported_value",path:"details",byte_limit:PM_CLI_ERROR_DETAILS_LIMITS.max_bytes}}function ownDataValue(container,key){const descriptor=Object.getOwnPropertyDescriptor(container,key);return descriptor!==void 0&&"value"in descriptor?descriptor.value:void 0}function readRecordedOmission(value){if(!isPlainObject(value))return;const reason=ownDataValue(value,"reason");if(typeof reason!="string"||!DETAILS_REJECTIONS.has(reason))return;const recordedPath=ownDataValue(value,"path"),path=typeof recordedPath=="string"?boundPath(recordedPath):void 0;return{reason,...path===void 0?{}:{path},byte_limit:PM_CLI_ERROR_DETAILS_LIMITS.max_bytes}}function snapshotPmCliErrorContext(context){const snapshot={};try{if(typeof context!="object"||context===null||Array.isArray(context))return snapshot;for(const[key,descriptor]of Object.entries(Object.getOwnPropertyDescriptors(context)))descriptor.enumerable&&("value"in descriptor?Object.defineProperty(snapshot,key,{value:descriptor.value,enumerable:!0,writable:!0,configurable:!0}):key==="details"&&(snapshot.details_omitted=unsupportedDetailsReceipt()));return snapshot}catch{return{}}}function projectPmCliErrorContextDetailsSlot(context){if(!(typeof context!="object"||context===null))try{const descriptor=Object.getOwnPropertyDescriptor(context,"details");if(descriptor!==void 0&&!("value"in descriptor))return{details_omitted:unsupportedDetailsReceipt()};if(descriptor!==void 0&&descriptor.value!==void 0)return projectPmCliErrorDetails(descriptor.value);const recorded=Object.getOwnPropertyDescriptor(context,"details_omitted"),omission=recorded!==void 0&&"value"in recorded?readRecordedOmission(recorded.value):void 0;return omission===void 0?void 0:{details_omitted:omission}}catch{return{details_omitted:unsupportedDetailsReceipt()}}}const DIAGNOSTIC_KEYS=new Set(["details","details_omitted"]);function contextWithoutDiagnostics(context){const rest={};for(const key of Object.keys(context)){if(DIAGNOSTIC_KEYS.has(key)||key==="toJSON")continue;const descriptor=Object.getOwnPropertyDescriptor(context,key);descriptor!==void 0&&"value"in descriptor&&Object.defineProperty(rest,key,{value:descriptor.value,enumerable:!0,writable:!0,configurable:!0})}return rest}function projectPmCliErrorContextDetails(context){if(typeof context!="object"||context===null)return context;try{return Array.isArray(context)?context:{...contextWithoutDiagnostics(context),...projectPmCliErrorContextDetailsSlot(context)}}catch{return{details_omitted:unsupportedDetailsReceipt()}}}function omitPmCliErrorDetails(context){if(typeof context!="object"||context===null)return context;try{return Array.isArray(context)?context:contextWithoutDiagnostics(context)}catch{return{}}}function crashReportErrorContext(context){const safe={};for(const[key,value]of Object.entries(snapshotPmCliErrorContext(context)))DIAGNOSTIC_KEYS.has(key)||key==="toJSON"||(value===null||typeof value=="string"||typeof value=="number"||typeof value=="boolean")&&Object.defineProperty(safe,key,{value,enumerable:!0,writable:!0,configurable:!0});return safe}const MAX_EMBEDDED_CONTEXT_DEPTH=12,EMBEDDED_CONTEXT_KEYS=new Set(["context","error_context"]),SERIALIZED_ARGUMENT_KEYS=new Set(["arguments"]);function omitEmbeddedPmCliErrorDetails(payload){const seen=new WeakSet,visit=(value,depth)=>{if(typeof value!="object"||value===null||depth>MAX_EMBEDDED_CONTEXT_DEPTH||seen.has(value))return;seen.add(value);const record=value;let keys;try{keys=Object.keys(record)}catch{return}for(const key of keys){const descriptor=Object.getOwnPropertyDescriptor(record,key);if(descriptor===void 0||!("value"in descriptor))continue;const entry=descriptor.value,scrubbed=EMBEDDED_CONTEXT_KEYS.has(key)?{}:SERIALIZED_ARGUMENT_KEYS.has(key)?[]:entry;scrubbed!==entry&&(record[key]=scrubbed),visit(scrubbed,depth+1)}};visit(payload,0)}export{PM_CLI_ERROR_DETAILS_LIMITS,admitPmCliErrorDetails,crashReportErrorContext,isPmCliErrorDetails,omitEmbeddedPmCliErrorDetails,omitPmCliErrorDetails,projectPmCliErrorContextDetails,projectPmCliErrorContextDetailsSlot,projectPmCliErrorDetails,snapshotPmCliErrorContext};
+//# sourceMappingURL=error-details.js.map

package/dist/core/shared/errors.d.ts

@@ -91,6 +91,30 @@ reason:string;
 /** Value that configures or reports next best command for this contract. */
 next_best_command?:string;
 }
+/** One JSON value inside producer-owned error diagnostics. */
+export type PmCliErrorDetailValue = null | boolean | number | string | PmCliErrorDetailValue[] | {
+[key:string]:PmCliErrorDetailValue;
+};
+/**
+ * Producer-owned structured diagnostics for an expected error (GH-1631). The
+ * host renders them as-is in structured error output, bounded by
+ * `PM_CLI_ERROR_DETAILS_LIMITS`, and never sends them to telemetry or crash
+ * reporting.
+ */
+export type PmCliErrorDetails = {
+[key:string]:PmCliErrorDetailValue;
+};
+/** Why a producer's diagnostics could not be rendered. */
+export type PmCliErrorDetailsRejection = "not_plain_object" | "unsupported_value" | "non_finite_number" | "malformed_unicode" | "reserved_key" | "depth_limit" | "byte_limit" | "diagnostic_budget";
+/** Host-set receipt that replaces diagnostics the host could not render. */
+export interface PmCliErrorDetailsOmission {
+/** Stable reason the diagnostics were withheld. */
+reason:PmCliErrorDetailsRejection;
+/** Bounded JSON path of the first offending value, when the shape was refused. */
+path?:string;
+/** Byte ceiling that applied. */
+byte_limit:number;
+}
 /** Documents the pm cli error context payload exchanged by command, SDK, and package integrations. */
 export interface PmCliErrorContext {
 /** Durable writes completed before refusal; paths are relative to the selected tracker. */
@@ -299,8 +323,27 @@ created_at:string;
 /** Stale-lock lifetime of the current lock generation. */
 ttl_seconds:number;
 } | null;
+/** Tracker-relative lock path component that a refused `lock_path_unsafe` acquisition could not prove confined. */
+lock_component?:string;
+/** Revision a refused compare-and-set write expected, or null when it required absence. */
+expected_revision?:string | null;
+/** Revision found at a refused compare-and-set write, or null when the target was absent. */
+current_revision?:string | null;
 /** Value that configures or reports recovery for this contract. */
 recovery?:PmCliErrorRecoveryPayload;
+/**
+     * Producer-owned structured diagnostics: plain JSON the host renders whole
+     * in `--json`, text and MCP error output when it fits the declared ceiling,
+     * and otherwise replaces with a `details_omitted` receipt. Never sent to
+     * telemetry or crash reporting.
+     */
+details?:PmCliErrorDetails;
+/**
+     * Host-set receipt recorded instead of `details` when they could not be
+     * admitted (for example oversized at construction). Producers set `details`;
+     * the host owns this field and never sends it to telemetry or crash reporting.
+     */
+details_omitted?:PmCliErrorDetailsOmission;
 }
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 export declare class PmCliError extends Error {

package/dist/core/shared/errors.js

@@ -1,2 +1,2 @@
-(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]="277cefd2-1da3-55f6-aa07-9f0d34d02314")}catch{}})();class PmCliError extends Error{exitCode;code;context;constructor(message,exitCode,context={}){super(message),this.name="PmCliError",this.exitCode=exitCode,this.context=context,this.code=context.code}}export{PmCliError};
+(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]="9896afd0-b833-5b30-b047-4881891d3976")}catch{}})();class PmCliError extends Error{exitCode;code;context;constructor(message,exitCode,context={}){super(message),this.name="PmCliError",this.exitCode=exitCode,this.context=context,this.code=context.code}}export{PmCliError};
 //# sourceMappingURL=errors.js.map

package/dist/core/store/settings-sections.d.ts

@@ -0,0 +1,61 @@
+/** Validate and normalize a stored section value; throw to refuse it. */
+export type SettingsSectionValidator<T> = (raw:unknown) => T;
+/** Options for reading one extension-owned settings section. */
+export interface ReadSettingsSectionOptions<T> {
+/** Validate the stored value; a throw becomes a typed `settings_section_invalid` refusal. */
+validate?:SettingsSectionValidator<T>;
+/** Value returned, unvalidated, when the section is absent. */
+defaultValue?:T;
+}
+/** One extension-owned settings section as the host resolved it. */
+export interface SettingsSectionReadResult<T> {
+/** Top-level settings key that holds the section. */
+section:string;
+/** `stored` when settings.json holds the section, `default` when it is absent. */
+source:"stored" | "default";
+/** Validated stored value, or the default (undefined when none was given). */
+value:T | undefined;
+/** Content revision of the stored section (`sha256:<hex>`), or null when absent. */
+revision:string | null;
+}
+/** Options for a revision-safe write of one extension-owned settings section. */
+export interface WriteSettingsSectionOptions<T> {
+/** Refuse unless the stored section still has this revision; null requires it to be absent. */
+expectedRevision?:string | null;
+/** Validate and normalize the value before it is stored. */
+validate?:SettingsSectionValidator<T>;
+/**
+     * Mutation author for the history event; omitted, the workspace default and
+     * detected identity apply. The host-bound `context.sdk` writer passes the
+     * invocation author.
+     */
+author?:string;
+}
+/** Receipt of a settings-section write. */
+export interface SettingsSectionWriteResult {
+/** Top-level settings key that holds the section. */
+section:string;
+/** Whether settings.json changed. */
+changed:boolean;
+/** Revision before the write, or null when the section was absent. */
+previous_revision:string | null;
+/** Revision after the write, or null when the section was removed. */
+revision:string | null;
+}
+/** Content revision of a stored section value. */
+export declare function settingsSectionRevision(value:unknown):string;
+/**
+ * Read one extension-owned top-level section of the tracker's settings through
+ * the host. Absent sections resolve to the default; malformed documents and
+ * values the validator refuses become typed refusals instead of thrown parse
+ * errors.
+ */
+export declare function readSettingsSection<T = unknown>(pmRoot:string,section:string,options?:ReadSettingsSectionOptions<T>):Promise<SettingsSectionReadResult<T>>;
+/**
+ * Replace (or, with `undefined`, remove) one extension-owned settings section
+ * under the workspace-history lock. Every other key of settings.json is kept
+ * byte-for-byte in value. `expectedRevision` makes the write compare-and-set:
+ * a section changed since it was read refuses with
+ * `settings_section_revision_conflict` and nothing is written.
+ */
+export declare function writeSettingsSection<T>(pmRoot:string,section:string,value:T | undefined,options?:WriteSettingsSectionOptions<T>):Promise<SettingsSectionWriteResult>;

package/dist/core/store/settings-sections.js

@@ -0,0 +1,3 @@
+(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]="7cbbb50d-e9bc-5940-9ae6-6270e9c2fcbf")}catch{}})();import{createHash}from"node:crypto";import{readFileIfExists}from"../fs/fs-utils.js";import{runActiveOnReadHooks,runActiveOnWriteHooks}from"../extensions/index.js";import{mutateWorkspaceJsonWithHistory}from"../history/workspace-history.js";import{resolveAuthor}from"../shared/author.js";import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{toErrorMessage}from"../shared/primitives.js";import{stableValueEquals}from"../shared/serialization.js";import{getSettingsPath}from"./paths.js";import{readSettings}from"./settings.js";import{clearSettingsReadCache}from"./settings-read-cache.js";import{CORE_SETTINGS_SECTION_KEYS}from"./settings-validator.js";const SETTINGS_SECTION_NAME_PATTERN=/^[a-z][a-z0-9_-]{0,63}$/u,RESERVED_SECTION_NAMES=new Set(["constructor","prototype"]),SETTINGS_SECTION_WRITE_OP="settings:section:write",MAX_VALIDATION_MESSAGE_LENGTH=240;function settingsSectionRevision(value){return`sha256:${createHash("sha256").update(canonicalSectionJson(value)).digest("hex")}`}function canonicalSectionJson(value){return Array.isArray(value)?`[${value.map(entry=>canonicalSectionJson(entry)).join(",")}]`:typeof value=="object"&&value!==null?`{${Object.keys(value).sort().map(key=>`${JSON.stringify(key)}:${canonicalSectionJson(Object.getOwnPropertyDescriptor(value,key)?.value)}`).join(",")}}`:String(JSON.stringify(value))}function assertSettingsSectionName(section){if(!SETTINGS_SECTION_NAME_PATTERN.test(section)||RESERVED_SECTION_NAMES.has(section))throw new PmCliError(`Invalid settings section name "${section.slice(0,80)}". Use 1-64 lowercase letters, digits, underscores or hyphens, starting with a letter.`,EXIT_CODE.USAGE,{code:"settings_section_name_invalid",field:"section",required:"Name the section after the package, for example lint or jev."});if(CORE_SETTINGS_SECTION_KEYS.includes(section))throw new PmCliError(`Settings section "${section}" is owned by core settings; extension sections must use another name.`,EXIT_CODE.USAGE,{code:"settings_section_reserved",field:"section",value:section,required:"Read core settings with readSettings and change them with writeSettings or pm config."})}function parseSettingsDocument(raw){let parsed;try{parsed=JSON.parse(raw)}catch{parsed=void 0}if(typeof parsed!="object"||parsed===null||Array.isArray(parsed))throw new PmCliError("settings.json is not a JSON object, so no settings section can be read or written.",EXIT_CODE.USAGE,{code:"settings_section_document_malformed",reason:parsed===void 0?"settings_json_malformed":"settings_json_not_object",nextSteps:["Repair .agents/pm/settings.json so it is a JSON object, then retry.","Run pm health to confirm the settings warning has cleared."]});return parsed}function validateSectionValue(section,raw,validate){let value;try{value=validate===void 0?raw:validate(raw)}catch(error){throw new PmCliError(`Settings section "${section}" is invalid: ${toErrorMessage(error).slice(0,MAX_VALIDATION_MESSAGE_LENGTH)}`,EXIT_CODE.USAGE,{code:"settings_section_invalid",field:section,required:`Fix the "${section}" section of .agents/pm/settings.json so the owning package accepts it, then retry.`})}return value}function hasJsonHook(value){return typeof Reflect.get(value,"toJSON")=="function"}function describeJsonPath(segments){return segments.length===0?"the value":segments.join(".")}function hasOnlyDataProperties(value,requireEnumerable){return Object.values(Object.getOwnPropertyDescriptors(value)).every(descriptor=>"value"in descriptor&&(!requireEnumerable||descriptor.enumerable===!0))}function isPlainJsonArray(value){if(Object.getPrototypeOf(value)!==Array.prototype||!hasOnlyDataProperties(value,!1))return!1;const keys=Object.keys(value);return keys.length===value.length&&keys.every((key,index)=>key===String(index))&&Object.getOwnPropertyNames(value).length===value.length+1&&Object.getOwnPropertySymbols(value).length===0&&!hasJsonHook(value)}function isPlainJsonObject(value){const prototype=Object.getPrototypeOf(value);return(prototype===Object.prototype||prototype===null)&&hasOnlyDataProperties(value,!0)&&Object.getOwnPropertySymbols(value).length===0&&!hasJsonHook(value)}function findScalarDrift(value,segments){if(value===null||typeof value=="string"||typeof value=="boolean")return null;const where=describeJsonPath(segments);return typeof value=="number"?Number.isFinite(value)?null:{detail:`${where} is a non-finite number`,representable:!0}:{detail:`${where} is ${typeof value}`,representable:typeof value!="bigint"&&segments.length>0}}function findJsonDrift(value,segments=[],ancestors=new Set){if(typeof value!="object"||value===null)return findScalarDrift(value,segments);const where=describeJsonPath(segments);if(ancestors.has(value))return{detail:`${where} is a circular reference`,representable:!1};if(!(Array.isArray(value)?isPlainJsonArray(value):isPlainJsonObject(value)))return{detail:`${where} is not a plain JSON ${Array.isArray(value)?"array":"object"}`,representable:!0};ancestors.add(value);for(const[key,entry]of Object.entries(value)){const drift=findJsonDrift(entry,[...segments,key],ancestors);if(drift!==null)return drift}return ancestors.delete(value),null}function findReservedJsonKey(value,segments=[]){if(typeof value!="object"||value===null)return null;for(const[key,entry]of Object.entries(value)){const keyPath=[...segments,key];if(key==="__proto__"||key==="prototype"&&segments.at(-1)==="constructor")return describeJsonPath(keyPath);const nested=findReservedJsonKey(entry,keyPath);if(nested!==null)return nested}return null}function refuseSectionValue(section,value,reason){return validateSectionValue(section,value,()=>{throw new Error(reason)})}function toStoredSectionValue(section,value){const drift=findJsonDrift(value);if(drift!==null){const reason=drift.representable?`the value would change when stored as JSON: ${drift.detail}`:`the value is not representable as JSON: ${drift.detail}`;return refuseSectionValue(section,value,reason)}const reserved=findReservedJsonKey(value);return reserved!==null?refuseSectionValue(section,value,`${reserved} is a reserved key that settings history cannot record`):JSON.parse(JSON.stringify(value))}function readSectionEntry(document,section){return Object.hasOwn(document,section)?document[section]:void 0}async function readSettingsSection(pmRoot,section,options={}){assertSettingsSectionName(section);const settingsPath=getSettingsPath(pmRoot);await runActiveOnReadHooks({path:settingsPath,scope:"project"});const raw=await readFileIfExists(settingsPath),stored=raw===null?void 0:readSectionEntry(parseSettingsDocument(raw),section);if(stored===void 0)return{section,source:"default",value:options.defaultValue,revision:null};const revision=settingsSectionRevision(stored);return{section,source:"stored",value:validateSectionValue(section,structuredClone(stored),options.validate),revision}}async function writeSettingsSection(pmRoot,section,value,options={}){assertSettingsSectionName(section);const next=value===void 0?void 0:toStoredSectionValue(section,validateSectionValue(section,value,options.validate)),settingsPath=getSettingsPath(pmRoot),settings=await readSettings(pmRoot);try{const mutation=await mutateWorkspaceJsonWithHistory({pmRoot,filePath:settingsPath,op:SETTINGS_SECTION_WRITE_OP,author:resolveAuthor(options.author,settings.author_default),lockTtlSeconds:settings.locks.ttl_seconds,lockWaitMs:settings.locks.wait_ms,recordCreation:!1,mutate:beforeRaw=>{if(beforeRaw===null)throw new PmCliError("settings.json does not exist, so no settings section can be written.",EXIT_CODE.NOT_FOUND,{code:"settings_section_document_missing",required:"Initialize the tracker with pm init, then retry."});const document=parseSettingsDocument(beforeRaw),current=readSectionEntry(document,section),previousRevision=current===void 0?null:settingsSectionRevision(current);if(options.expectedRevision!==void 0&&options.expectedRevision!==previousRevision)throw new PmCliError(`Settings section "${section}" changed since it was read; read it again and reapply the change.`,EXIT_CODE.CONFLICT,{code:"settings_section_revision_conflict",field:section,expected_revision:options.expectedRevision,current_revision:previousRevision,required:"Read the section again with readSettingsSection, then retry with its current revision."});const receipt={section,changed:!1,previous_revision:previousRevision,revision:next===void 0?null:settingsSectionRevision(next)};return stableValueEquals(current,next)?{raw:beforeRaw,result:receipt}:(next===void 0?delete document[section]:document[section]=next,{raw:`${JSON.stringify(document,null,2)}
+`,result:{...receipt,changed:!0}})}});return mutation.changed&&await runActiveOnWriteHooks({path:settingsPath,scope:"project",op:SETTINGS_SECTION_WRITE_OP}),mutation.result}finally{clearSettingsReadCache(pmRoot)}}export{readSettingsSection,settingsSectionRevision,writeSettingsSection};
+//# sourceMappingURL=settings-sections.js.map

package/dist/core/store/settings-validator.d.ts

@@ -172,6 +172,10 @@ success:true;
 data:ParsedSettings;
 } | {
 success:false;
+/** Dotted path of the first invalid setting; empty when the document root is not an object. */
+path:string;
 };
+/** Top-level settings keys owned and validated by core; extension sections must use other names. */
+export declare const CORE_SETTINGS_SECTION_KEYS:readonly string[];
 /** Validate raw settings, returning stripped, type-checked data or failure (matching the legacy zod safeParse). */
 export declare function validateSettings(raw:unknown):SettingsValidationResult;

package/dist/core/store/settings-validator.js

@@ -1,2 +1,2 @@
-(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]="405e7bd1-25c0-5e04-b313-d9871efce4f5")}catch{}})();import{GOVERNANCE_PRESET_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES}from"../../types.js";const FAIL={ok:!1},vString=input=>typeof input=="string"?{ok:!0,value:input}:FAIL,vBoolean=input=>typeof input=="boolean"?{ok:!0,value:input}:FAIL;function vNumber(options={}){return input=>typeof input!="number"||!Number.isFinite(input)||options.int&&(!Number.isInteger(input)||!Number.isSafeInteger(input))||options.positive&&input<=0||typeof options.min=="number"&&input<options.min||typeof options.max=="number"&&input>options.max?FAIL:{ok:!0,value:input}}function vLiteral(...allowed){return input=>typeof input=="string"&&allowed.includes(input)?{ok:!0,value:input}:FAIL}function vArray(item,maxLength){return input=>{if(!Array.isArray(input)||maxLength!==void 0&&input.length>maxLength)return FAIL;const value=[];for(const element of input){const result=item(element);if(!result.ok)return FAIL;value.push(result.value)}return{ok:!0,value}}}function vBoundedNormalizedString(maxLength,pattern){return input=>typeof input=="string"&&input.length>0&&input.length<=maxLength&&input===input.trim()&&(pattern===void 0||pattern.test(input))?{ok:!0,value:input}:FAIL}function vOptional(inner){return input=>input===void 0?{ok:!0,value:void 0}:inner(input)}function vRecordOf(valueCheck){return input=>{if(typeof input!="object"||input===null||Array.isArray(input))return FAIL;const value={};for(const[key,raw]of Object.entries(input)){const result=valueCheck(raw);if(!result.ok)return FAIL;value[key]=result.value}return{ok:!0,value}}}function vObject(shape){return input=>{if(typeof input!="object"||input===null||Array.isArray(input))return FAIL;const record=input,value={};for(const[key,check]of Object.entries(shape)){const result=check(record[key]);if(!result.ok)return FAIL;result.value!==void 0&&(value[key]=result.value)}return{ok:!0,value}}}const itemTypeOption=vObject({key:vString,values:vArray(vString),required:vOptional(vBoolean),aliases:vOptional(vArray(vString)),description:vOptional(vString)}),itemTypeCommandOptionPolicy=vObject({command:vLiteral("create","update"),option:vString,required:vOptional(vBoolean),visible:vOptional(vBoolean),enabled:vOptional(vBoolean)}),itemTypeDefinition=vObject({name:vString,description:vOptional(vString),default_status:vOptional(vString),execution_role:vOptional(vLiteral("agent","human","gate")),folder:vOptional(vString),aliases:vOptional(vArray(vString)),required_create_fields:vOptional(vArray(vString)),required_create_repeatables:vOptional(vArray(vString)),options:vOptional(vArray(itemTypeOption)),command_option_policies:vOptional(vArray(itemTypeCommandOptionPolicy))}),runtimeStatusDefinition=vObject({id:vString,aliases:vOptional(vArray(vString)),roles:vOptional(vArray(vLiteral(...RUNTIME_STATUS_ROLE_VALUES))),description:vOptional(vString),order:vOptional(vNumber())}),runtimeFieldDefinition=vObject({key:vString,metadata_key:vOptional(vString),front_matter_key:vOptional(vString),cli_flag:vOptional(vString),cli_aliases:vOptional(vArray(vString)),description:vOptional(vString),type:vOptional(vLiteral(...RUNTIME_FIELD_TYPE_VALUES)),commands:vOptional(vArray(vLiteral(...RUNTIME_FIELD_COMMAND_VALUES))),repeatable:vOptional(vBoolean),required:vOptional(vBoolean),required_on_create:vOptional(vBoolean),required_types:vOptional(vArray(vString)),allow_unset:vOptional(vBoolean)}),statusTransitionPair=input=>{if(!Array.isArray(input)||input.length!==2)return FAIL;const[from,to]=input;return typeof from!="string"||typeof to!="string"?FAIL:{ok:!0,value:[from,to]}},typeWorkflowDefinition=vObject({type:vString,allowed_transitions:vArray(statusTransitionPair)}),runtimeSchemaSettings=vOptional(vObject({version:vOptional(vNumber({int:!0})),files:vOptional(vObject({types:vOptional(vString),statuses:vOptional(vString),fields:vOptional(vString),workflows:vOptional(vString)})),statuses:vOptional(vArray(runtimeStatusDefinition)),fields:vOptional(vArray(runtimeFieldDefinition)),workflow:vOptional(vObject({draft_status:vOptional(vString),open_status:vOptional(vString),in_progress_status:vOptional(vString),blocked_status:vOptional(vString),close_status:vOptional(vString),canceled_status:vOptional(vString)})),type_workflows:vOptional(vArray(typeWorkflowDefinition)),unknown_field_policy:vOptional(vLiteral(...RUNTIME_UNKNOWN_FIELD_POLICY_VALUES))})),governanceSettings=vOptional(vObject({preset:vOptional(vLiteral(...GOVERNANCE_PRESET_VALUES)),ownership_enforcement:vOptional(vLiteral("none","warn","strict")),create_mode_default:vOptional(vLiteral("progressive","strict")),close_validation_default:vOptional(vLiteral("off","warn","strict")),require_close_reason:vOptional(vBoolean),parent_reference:vOptional(vLiteral("warn","strict_error")),metadata_profile:vOptional(vLiteral("core","strict","custom")),force_required_for_stale_lock:vOptional(vBoolean),create_default_type:vOptional(vString),workflow_enforcement:vOptional(vLiteral("off","warn","strict")),duplicate_detection_mode:vOptional(vLiteral("off","advisory","strict")),duplicate_detection_threshold:vOptional(vNumber({min:0,max:1})),duplicate_detection_limit:vOptional(vNumber({int:!0,min:0,max:20}))})),extensionPolicyOverride=vObject({name:vString,disabled:vOptional(vBoolean),require_trusted:vOptional(vBoolean),require_provenance:vOptional(vBoolean),sandbox_profile:vOptional(vLiteral("none","restricted","strict")),allowed_capabilities:vOptional(vArray(vString)),blocked_capabilities:vOptional(vArray(vString)),allowed_surfaces:vOptional(vArray(vString)),blocked_surfaces:vOptional(vArray(vString)),allowed_commands:vOptional(vArray(vString)),blocked_commands:vOptional(vArray(vString)),allowed_actions:vOptional(vArray(vString)),blocked_actions:vOptional(vArray(vString)),allowed_services:vOptional(vArray(vString)),blocked_services:vOptional(vArray(vString))}),pmMaxVersionExceededModeLiteral=vLiteral("block","warn"),pmMaxVersionExceededMode=input=>typeof input=="string"?pmMaxVersionExceededModeLiteral(input):vObject({global:vOptional(pmMaxVersionExceededModeLiteral),project:vOptional(pmMaxVersionExceededModeLiteral)})(input),extensionPolicy=vOptional(vObject({mode:vOptional(vLiteral("off","warn","enforce")),trust_mode:vOptional(vLiteral("off","warn","enforce")),pm_max_version_exceeded_mode:vOptional(pmMaxVersionExceededMode),require_provenance:vOptional(vBoolean),trusted_extensions:vOptional(vArray(vString)),default_sandbox_profile:vOptional(vLiteral("none","restricted","strict")),allowed_extensions:vOptional(vArray(vString)),blocked_extensions:vOptional(vArray(vString)),allowed_capabilities:vOptional(vArray(vString)),blocked_capabilities:vOptional(vArray(vString)),allowed_surfaces:vOptional(vArray(vString)),blocked_surfaces:vOptional(vArray(vString)),allowed_commands:vOptional(vArray(vString)),blocked_commands:vOptional(vArray(vString)),allowed_actions:vOptional(vArray(vString)),blocked_actions:vOptional(vArray(vString)),allowed_services:vOptional(vArray(vString)),blocked_services:vOptional(vArray(vString)),extension_overrides:vOptional(vArray(extensionPolicyOverride))})),harnessSignalLiteral=vBoundedNormalizedString(128),harnessSignalDescriptor=vObject({harness:vBoundedNormalizedString(128,/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),environment_keys:vOptional(vArray(harnessSignalLiteral,64)),model_environment_keys:vOptional(vArray(harnessSignalLiteral,64)),session_environment_keys:vOptional(vArray(harnessSignalLiteral,64)),provenance_environment_keys:vOptional(vRecordOf(vArray(harnessSignalLiteral,64))),provenance_resolvers:vOptional(vRecordOf(vLiteral("ai_agent_version","claude_session_file"))),provenance_unavailable_dimensions:vOptional(vArray(harnessSignalLiteral,64)),argv_markers:vOptional(vArray(harnessSignalLiteral,64)),client_names:vOptional(vArray(harnessSignalLiteral,64))}),settingsCheck=vObject({version:vNumber({int:!0}),id_prefix:vString,ids:vOptional(vObject({token_length:vOptional(vNumber({int:!0,min:4,max:12}))})),author_default:vString,agent_identity:vOptional(vObject({probes_enabled:vOptional(vBoolean),identity_vocabulary:vOptional(vObject({version:vNumber({int:!0,positive:!0}),aliases:vRecordOf(vBoundedNormalizedString(128,/^[a-z0-9]+(?:-[a-z0-9]+)*$/u))})),harness_signals:vArray(harnessSignalDescriptor)})),mutation_guard:vOptional(vObject({require_attributed_author:vOptional(vBoolean),secret_guard:vOptional(vLiteral("off","advise","block")),stale_in_progress_hours:vOptional(vNumber({int:!0,positive:!0}))})),item_format:vOptional(vLiteral("toon","json_markdown")),locks:vObject({ttl_seconds:vNumber({int:!0}),wait_ms:vOptional(vNumber({int:!0,min:0}))}),checkpoints:vOptional(vObject({retention_days:vOptional(vNumber({int:!0,positive:!0}))})),output:vObject({default_format:vLiteral("toon","json")}),ux:vOptional(vObject({deprecation_hints:vOptional(vBoolean)})),history:vOptional(vObject({missing_stream:vLiteral("auto_create","strict_error"),compact_policy:vOptional(vObject({enabled:vOptional(vBoolean),max_entries:vOptional(vNumber({int:!0,positive:!0})),trigger:vOptional(vLiteral("health_warn","auto"))}))})),validation:vOptional(vObject({sprint_release_format:vLiteral("warn","strict_error"),parent_reference:vOptional(vLiteral("warn","strict_error")),metadata_profile:vOptional(vLiteral("core","strict","custom")),metadata_required_fields:vOptional(vArray(vString)),lifecycle_stale_blocker_reason_patterns:vOptional(vArray(vString)),lifecycle_closure_like_blocked_reason_patterns:vOptional(vArray(vString)),lifecycle_closure_like_resolution_patterns:vOptional(vArray(vString)),lifecycle_closure_like_actual_result_patterns:vOptional(vArray(vString)),estimate_defaults_by_type:vOptional(vRecordOf(vNumber({int:!0,positive:!0})))})),governance:governanceSettings,workflow:vOptional(vObject({definition_of_done:vArray(vString)})),testing:vOptional(vObject({record_results_to_items:vBoolean,allow_untrusted_linked_tests:vOptional(vBoolean)})),telemetry:vOptional(vObject({enabled:vBoolean,first_run_prompt_completed:vOptional(vBoolean),capture_level:vOptional(vLiteral("minimal","redacted","max")),endpoint:vOptional(vString),installation_id:vOptional(vString),retention_days:vOptional(vNumber({int:!0,positive:!0}))})),agent_guidance:vOptional(vObject({prompt_completed:vOptional(vBoolean),declined:vOptional(vBoolean),declined_at:vOptional(vString),template_version:vOptional(vNumber({int:!0,positive:!0})),last_checked_files:vOptional(vArray(vString))})),item_types:vOptional(vObject({definitions:vArray(itemTypeDefinition)})),schema:runtimeSchemaSettings,context:vOptional(vObject({default_depth:vOptional(vLiteral("brief","standard","deep")),activity_limit:vOptional(vNumber({int:!0,positive:!0})),stale_threshold_days:vOptional(vNumber({int:!0,positive:!0})),next_ranking_policy:vOptional(vLiteral("priority_floor","weighted")),sections:vOptional(vObject({hierarchy:vOptional(vBoolean),activity:vOptional(vBoolean),progress:vOptional(vBoolean),recently_created:vOptional(vBoolean),unparented:vOptional(vBoolean),blockers:vOptional(vBoolean),files:vOptional(vBoolean),workload:vOptional(vBoolean),staleness:vOptional(vBoolean),tests:vOptional(vBoolean)}))})),extensions:vObject({enabled:vArray(vString),disabled:vArray(vString),policy:extensionPolicy}),search:vObject({score_threshold:vNumber(),hybrid_semantic_weight:vOptional(vNumber()),max_results:vNumber({int:!0}),embedding_model:vString,embedding_corpus_max_characters:vOptional(vNumber()),embedding_batch_size:vNumber({int:!0}),embedding_timeout_ms:vOptional(vNumber({int:!0})),scanner_max_batch_retries:vNumber({int:!0}),provider:vOptional(vString),default_mode:vOptional(vLiteral("auto","keyword","semantic","hybrid")),corpus_fields:vOptional(vArray(vString)),mutation_refresh_policy:vOptional(vLiteral("cache_only","semantic_configured","semantic_auto")),query_expansion:vOptional(vObject({enabled:vOptional(vBoolean),provider:vOptional(vString)})),rerank:vOptional(vObject({enabled:vOptional(vBoolean),model:vOptional(vString),top_k:vOptional(vNumber({int:!0,positive:!0}))})),bm25:vOptional(vObject({k1:vOptional(vNumber()),b:vOptional(vNumber())}))}),providers:vObject({openai:vObject({base_url:vString,api_key:vString,model:vString}),ollama:vObject({base_url:vString,model:vString})}),vector_store:vObject({adapter:vOptional(vString),collection_name:vOptional(vString),qdrant:vObject({url:vString,api_key:vString}),lancedb:vObject({path:vString})})});function validateSettings(raw){const result=settingsCheck(raw);return result.ok?{success:!0,data:result.value}:{success:!1}}export{validateSettings};
+(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]="c7f9d249-e2c2-5edd-afbd-b14ac1c12e81")}catch{}})();import{GOVERNANCE_PRESET_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES}from"../../types.js";const FAIL={ok:!1,path:[]};function failAt(segment,failure){return{ok:!1,path:[segment,...failure.path]}}const vString=input=>typeof input=="string"?{ok:!0,value:input}:FAIL,vBoolean=input=>typeof input=="boolean"?{ok:!0,value:input}:FAIL;function vNumber(options={}){return input=>typeof input!="number"||!Number.isFinite(input)||options.int&&(!Number.isInteger(input)||!Number.isSafeInteger(input))||options.positive&&input<=0||typeof options.min=="number"&&input<options.min||typeof options.max=="number"&&input>options.max?FAIL:{ok:!0,value:input}}function vLiteral(...allowed){return input=>typeof input=="string"&&allowed.includes(input)?{ok:!0,value:input}:FAIL}function vArray(item,maxLength){return input=>{if(!Array.isArray(input)||maxLength!==void 0&&input.length>maxLength)return FAIL;const value=[];for(const[index,element]of input.entries()){const result=item(element);if(!result.ok)return failAt(String(index),result);value.push(result.value)}return{ok:!0,value}}}function vBoundedNormalizedString(maxLength,pattern){return input=>typeof input=="string"&&input.length>0&&input.length<=maxLength&&input===input.trim()&&(pattern===void 0||pattern.test(input))?{ok:!0,value:input}:FAIL}function vOptional(inner){return input=>input===void 0?{ok:!0,value:void 0}:inner(input)}function vRecordOf(valueCheck){return input=>{if(typeof input!="object"||input===null||Array.isArray(input))return FAIL;const value={};for(const[key,raw]of Object.entries(input)){const result=valueCheck(raw);if(!result.ok)return failAt(key,result);value[key]=result.value}return{ok:!0,value}}}function vObject(shape){return input=>{if(typeof input!="object"||input===null||Array.isArray(input))return FAIL;const record=input,value={};for(const[key,check]of Object.entries(shape)){const result=check(record[key]);if(!result.ok)return failAt(key,result);result.value!==void 0&&(value[key]=result.value)}return{ok:!0,value}}}const itemTypeOption=vObject({key:vString,values:vArray(vString),required:vOptional(vBoolean),aliases:vOptional(vArray(vString)),description:vOptional(vString)}),itemTypeCommandOptionPolicy=vObject({command:vLiteral("create","update"),option:vString,required:vOptional(vBoolean),visible:vOptional(vBoolean),enabled:vOptional(vBoolean)}),itemTypeDefinition=vObject({name:vString,description:vOptional(vString),default_status:vOptional(vString),execution_role:vOptional(vLiteral("agent","human","gate")),folder:vOptional(vString),aliases:vOptional(vArray(vString)),required_create_fields:vOptional(vArray(vString)),required_create_repeatables:vOptional(vArray(vString)),options:vOptional(vArray(itemTypeOption)),command_option_policies:vOptional(vArray(itemTypeCommandOptionPolicy))}),runtimeStatusDefinition=vObject({id:vString,aliases:vOptional(vArray(vString)),roles:vOptional(vArray(vLiteral(...RUNTIME_STATUS_ROLE_VALUES))),description:vOptional(vString),order:vOptional(vNumber())}),runtimeFieldDefinition=vObject({key:vString,metadata_key:vOptional(vString),front_matter_key:vOptional(vString),cli_flag:vOptional(vString),cli_aliases:vOptional(vArray(vString)),description:vOptional(vString),type:vOptional(vLiteral(...RUNTIME_FIELD_TYPE_VALUES)),commands:vOptional(vArray(vLiteral(...RUNTIME_FIELD_COMMAND_VALUES))),repeatable:vOptional(vBoolean),required:vOptional(vBoolean),required_on_create:vOptional(vBoolean),required_types:vOptional(vArray(vString)),allow_unset:vOptional(vBoolean)}),statusTransitionPair=input=>{if(!Array.isArray(input)||input.length!==2)return FAIL;const[from,to]=input;return typeof from!="string"||typeof to!="string"?FAIL:{ok:!0,value:[from,to]}},typeWorkflowDefinition=vObject({type:vString,allowed_transitions:vArray(statusTransitionPair)}),runtimeSchemaSettings=vOptional(vObject({version:vOptional(vNumber({int:!0})),files:vOptional(vObject({types:vOptional(vString),statuses:vOptional(vString),fields:vOptional(vString),workflows:vOptional(vString)})),statuses:vOptional(vArray(runtimeStatusDefinition)),fields:vOptional(vArray(runtimeFieldDefinition)),workflow:vOptional(vObject({draft_status:vOptional(vString),open_status:vOptional(vString),in_progress_status:vOptional(vString),blocked_status:vOptional(vString),close_status:vOptional(vString),canceled_status:vOptional(vString)})),type_workflows:vOptional(vArray(typeWorkflowDefinition)),unknown_field_policy:vOptional(vLiteral(...RUNTIME_UNKNOWN_FIELD_POLICY_VALUES))})),governanceSettings=vOptional(vObject({preset:vOptional(vLiteral(...GOVERNANCE_PRESET_VALUES)),ownership_enforcement:vOptional(vLiteral("none","warn","strict")),create_mode_default:vOptional(vLiteral("progressive","strict")),close_validation_default:vOptional(vLiteral("off","warn","strict")),require_close_reason:vOptional(vBoolean),parent_reference:vOptional(vLiteral("warn","strict_error")),metadata_profile:vOptional(vLiteral("core","strict","custom")),force_required_for_stale_lock:vOptional(vBoolean),create_default_type:vOptional(vString),workflow_enforcement:vOptional(vLiteral("off","warn","strict")),duplicate_detection_mode:vOptional(vLiteral("off","advisory","strict")),duplicate_detection_threshold:vOptional(vNumber({min:0,max:1})),duplicate_detection_limit:vOptional(vNumber({int:!0,min:0,max:20}))})),extensionPolicyOverride=vObject({name:vString,disabled:vOptional(vBoolean),require_trusted:vOptional(vBoolean),require_provenance:vOptional(vBoolean),sandbox_profile:vOptional(vLiteral("none","restricted","strict")),allowed_capabilities:vOptional(vArray(vString)),blocked_capabilities:vOptional(vArray(vString)),allowed_surfaces:vOptional(vArray(vString)),blocked_surfaces:vOptional(vArray(vString)),allowed_commands:vOptional(vArray(vString)),blocked_commands:vOptional(vArray(vString)),allowed_actions:vOptional(vArray(vString)),blocked_actions:vOptional(vArray(vString)),allowed_services:vOptional(vArray(vString)),blocked_services:vOptional(vArray(vString))}),pmMaxVersionExceededModeLiteral=vLiteral("block","warn"),pmMaxVersionExceededMode=input=>typeof input=="string"?pmMaxVersionExceededModeLiteral(input):vObject({global:vOptional(pmMaxVersionExceededModeLiteral),project:vOptional(pmMaxVersionExceededModeLiteral)})(input),extensionPolicy=vOptional(vObject({mode:vOptional(vLiteral("off","warn","enforce")),trust_mode:vOptional(vLiteral("off","warn","enforce")),pm_max_version_exceeded_mode:vOptional(pmMaxVersionExceededMode),require_provenance:vOptional(vBoolean),trusted_extensions:vOptional(vArray(vString)),default_sandbox_profile:vOptional(vLiteral("none","restricted","strict")),allowed_extensions:vOptional(vArray(vString)),blocked_extensions:vOptional(vArray(vString)),allowed_capabilities:vOptional(vArray(vString)),blocked_capabilities:vOptional(vArray(vString)),allowed_surfaces:vOptional(vArray(vString)),blocked_surfaces:vOptional(vArray(vString)),allowed_commands:vOptional(vArray(vString)),blocked_commands:vOptional(vArray(vString)),allowed_actions:vOptional(vArray(vString)),blocked_actions:vOptional(vArray(vString)),allowed_services:vOptional(vArray(vString)),blocked_services:vOptional(vArray(vString)),extension_overrides:vOptional(vArray(extensionPolicyOverride))})),harnessSignalLiteral=vBoundedNormalizedString(128),harnessSignalDescriptor=vObject({harness:vBoundedNormalizedString(128,/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),environment_keys:vOptional(vArray(harnessSignalLiteral,64)),model_environment_keys:vOptional(vArray(harnessSignalLiteral,64)),session_environment_keys:vOptional(vArray(harnessSignalLiteral,64)),provenance_environment_keys:vOptional(vRecordOf(vArray(harnessSignalLiteral,64))),provenance_resolvers:vOptional(vRecordOf(vLiteral("ai_agent_version","claude_session_file"))),provenance_unavailable_dimensions:vOptional(vArray(harnessSignalLiteral,64)),argv_markers:vOptional(vArray(harnessSignalLiteral,64)),client_names:vOptional(vArray(harnessSignalLiteral,64))}),SETTINGS_SHAPE={version:vNumber({int:!0}),id_prefix:vString,ids:vOptional(vObject({token_length:vOptional(vNumber({int:!0,min:4,max:12}))})),author_default:vString,agent_identity:vOptional(vObject({probes_enabled:vOptional(vBoolean),identity_vocabulary:vOptional(vObject({version:vNumber({int:!0,positive:!0}),aliases:vRecordOf(vBoundedNormalizedString(128,/^[a-z0-9]+(?:-[a-z0-9]+)*$/u))})),harness_signals:vArray(harnessSignalDescriptor)})),mutation_guard:vOptional(vObject({require_attributed_author:vOptional(vBoolean),secret_guard:vOptional(vLiteral("off","advise","block")),stale_in_progress_hours:vOptional(vNumber({int:!0,positive:!0}))})),item_format:vOptional(vLiteral("toon","json_markdown")),locks:vObject({ttl_seconds:vNumber({int:!0}),wait_ms:vOptional(vNumber({int:!0,min:0}))}),checkpoints:vOptional(vObject({retention_days:vOptional(vNumber({int:!0,positive:!0}))})),output:vObject({default_format:vLiteral("toon","json")}),ux:vOptional(vObject({deprecation_hints:vOptional(vBoolean)})),history:vOptional(vObject({missing_stream:vLiteral("auto_create","strict_error"),compact_policy:vOptional(vObject({enabled:vOptional(vBoolean),max_entries:vOptional(vNumber({int:!0,positive:!0})),trigger:vOptional(vLiteral("health_warn","auto"))}))})),validation:vOptional(vObject({sprint_release_format:vLiteral("warn","strict_error"),parent_reference:vOptional(vLiteral("warn","strict_error")),metadata_profile:vOptional(vLiteral("core","strict","custom")),metadata_required_fields:vOptional(vArray(vString)),lifecycle_stale_blocker_reason_patterns:vOptional(vArray(vString)),lifecycle_closure_like_blocked_reason_patterns:vOptional(vArray(vString)),lifecycle_closure_like_resolution_patterns:vOptional(vArray(vString)),lifecycle_closure_like_actual_result_patterns:vOptional(vArray(vString)),estimate_defaults_by_type:vOptional(vRecordOf(vNumber({int:!0,positive:!0})))})),governance:governanceSettings,workflow:vOptional(vObject({definition_of_done:vArray(vString)})),testing:vOptional(vObject({record_results_to_items:vBoolean,allow_untrusted_linked_tests:vOptional(vBoolean)})),telemetry:vOptional(vObject({enabled:vBoolean,first_run_prompt_completed:vOptional(vBoolean),capture_level:vOptional(vLiteral("minimal","redacted","max")),endpoint:vOptional(vString),installation_id:vOptional(vString),retention_days:vOptional(vNumber({int:!0,positive:!0}))})),agent_guidance:vOptional(vObject({prompt_completed:vOptional(vBoolean),declined:vOptional(vBoolean),declined_at:vOptional(vString),template_version:vOptional(vNumber({int:!0,positive:!0})),last_checked_files:vOptional(vArray(vString))})),item_types:vOptional(vObject({definitions:vArray(itemTypeDefinition)})),schema:runtimeSchemaSettings,context:vOptional(vObject({default_depth:vOptional(vLiteral("brief","standard","deep")),activity_limit:vOptional(vNumber({int:!0,positive:!0})),stale_threshold_days:vOptional(vNumber({int:!0,positive:!0})),next_ranking_policy:vOptional(vLiteral("priority_floor","weighted")),sections:vOptional(vObject({hierarchy:vOptional(vBoolean),activity:vOptional(vBoolean),progress:vOptional(vBoolean),recently_created:vOptional(vBoolean),unparented:vOptional(vBoolean),blockers:vOptional(vBoolean),files:vOptional(vBoolean),workload:vOptional(vBoolean),staleness:vOptional(vBoolean),tests:vOptional(vBoolean)}))})),extensions:vObject({enabled:vArray(vString),disabled:vArray(vString),policy:extensionPolicy}),search:vObject({score_threshold:vNumber(),hybrid_semantic_weight:vOptional(vNumber()),max_results:vNumber({int:!0}),embedding_model:vString,embedding_corpus_max_characters:vOptional(vNumber()),embedding_batch_size:vNumber({int:!0}),embedding_timeout_ms:vOptional(vNumber({int:!0})),scanner_max_batch_retries:vNumber({int:!0}),provider:vOptional(vString),default_mode:vOptional(vLiteral("auto","keyword","semantic","hybrid")),corpus_fields:vOptional(vArray(vString)),mutation_refresh_policy:vOptional(vLiteral("cache_only","semantic_configured","semantic_auto")),query_expansion:vOptional(vObject({enabled:vOptional(vBoolean),provider:vOptional(vString)})),rerank:vOptional(vObject({enabled:vOptional(vBoolean),model:vOptional(vString),top_k:vOptional(vNumber({int:!0,positive:!0}))})),bm25:vOptional(vObject({k1:vOptional(vNumber()),b:vOptional(vNumber())}))}),providers:vObject({openai:vObject({base_url:vString,api_key:vString,model:vString}),ollama:vObject({base_url:vString,model:vString})}),vector_store:vObject({adapter:vOptional(vString),collection_name:vOptional(vString),qdrant:vObject({url:vString,api_key:vString}),lancedb:vObject({path:vString})})},settingsCheck=vObject(SETTINGS_SHAPE),CORE_SETTINGS_SECTION_KEYS=Object.freeze(Object.keys(SETTINGS_SHAPE));function validateSettings(raw){const result=settingsCheck(raw);return result.ok?{success:!0,data:result.value}:{success:!1,path:result.path.join(".")}}export{CORE_SETTINGS_SECTION_KEYS,validateSettings};
 //# sourceMappingURL=settings-validator.js.map

package/dist/core/store/settings.d.ts

@@ -80,6 +80,12 @@ schema_statuses:PmSettings["schema"]["statuses"];
 schema_fields:PmSettings["schema"]["fields"];
 schema_type_workflows:PmSettings["schema"]["type_workflows"];
 };
+/**
+ * Whether these settings are the defaults fallback for a stored document that
+ * could not be read. Automatic writers (format pinning, telemetry identity,
+ * consent) must skip their write instead of acting on the fallback.
+ */
+export declare function isSettingsReadFallback(settings:PmSettings):boolean;
 declare function hasExplicitItemFormat(raw:unknown):boolean;
 declare function normalizeStringList(values:string[] | undefined):string[];
 declare function normalizeLowerStringList(values:string[] | undefined):string[];
@@ -104,15 +110,36 @@ declare function applySettingsDelta(target:Record<string,unknown>,baseline:Recor
 export declare function serializeSettings(settings:PmSettings,options?:SerializeSettingsOptions):string;
 /** Implements read settings with metadata for the public runtime surface of this module. */
 export declare function readSettingsWithMetadata(pmRoot:string):Promise<SettingsReadResult>;
+/** Options for {@link writeSettings}. */
+export interface WriteSettingsOptions {
+/**
+     * Dotted settings paths (for example `context.next_ranking_policy`) the
+     * caller assigned explicitly. A snapshot cannot tell an assignment equal to
+     * the default from an untouched field, so over a defaults fallback returned
+     * for an unreadable document these paths are applied even when their value
+     * equals the default; that is how an explicit repair to the default value
+     * takes effect. A core-section path whose parent the proposed settings carry
+     * but whose value they omit (a default-valued optional key or a cleared key)
+     * is removed from the stored document; any other path the proposed settings
+     * do not carry is left to the delta. A record key that itself contains a dot
+     * cannot be addressed;
+     * repair such an entry in settings.json. Readable documents ignore the
+     * option (pm-4zpq71).
+     */
+assignedPaths?:readonly string[];
+}
 /** Implements read settings for the public runtime surface of this module. */
 export declare function readSettings(pmRoot:string):Promise<PmSettings>;
 /**
  * Persist edits to a readSettings snapshot under the workspace-history lock.
  * Disjoint concurrent edits survive; overlapping stale edits fail before any
  * write. Caller-constructed settings without a read snapshot replace the whole
- * document. History append failures compensate the document before unlocking.
+ * document. A default fallback returned for an unreadable document applies only
+ * its own change, plus `options.assignedPaths`, to the stored document and
+ * refuses when the result is still schema-invalid. History append failures
+ * compensate the document before unlocking.
  */
-export declare function writeSettings(pmRoot:string,settings:PmSettings,op?:string):Promise<void>;
+export declare function writeSettings(pmRoot:string,settings:PmSettings,op?:string,options?:WriteSettingsOptions):Promise<void>;
 /** Public contract for settings store test only, shared by SDK and presentation-layer consumers. */
 export declare const settingsStoreTestOnly:{
 applySettingsDelta:typeof applySettingsDelta;