@unbrained/pm-cli 2026.9.12 → 2026.9.14

package/dist/sdk/telemetry.d.ts

@@ -1,4 +1,5 @@
 import type { GlobalOptions } from "../core/shared/command-types.js";
+import { resolveTelemetryEnvironmentPolicy } from "../core/telemetry/policy.js";
 /** Public contract for telemetry subcommands, shared by SDK and presentation-layer consumers. */
 export declare const TELEMETRY_SUBCOMMANDS: readonly ["status", "flush", "stats", "clear"];
 /** Restricts telemetry subcommand values accepted by command, SDK, and storage contracts. */
@@ -7,6 +8,10 @@ export type TelemetrySubcommand = (typeof TELEMETRY_SUBCOMMANDS)[number];
 export interface TelemetryStatusSummary {
     /** Whether telemetry delivery is enabled. */
     enabled: boolean;
+    /** Persisted preference before process consent overrides. */
+    configured_enabled: boolean;
+    /** Process opt-outs, resolved without changing persisted preferences. */
+    env_overrides: ReturnType<typeof resolveTelemetryEnvironmentPolicy>;
     /** Configured delivery endpoint. */
     endpoint: string;
     /** Local event queue path. */

package/dist/sdk/telemetry.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]="32a15ab4-82a2-546f-8519-d4e565e7b578")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{pathExists,readFileIfExists}from"../core/fs/fs-utils.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{nowIso}from"../core/shared/time.js";import{resolveGlobalPmRoot}from"../core/store/paths.js";import{readSettings,writeSettings}from"../core/store/settings.js";import{flushTelemetryQueueNow}from"../core/telemetry/runtime.js";import{createUnknownSubcommandError}from"./agent/subcommand-recovery.js";const TELEMETRY_QUEUE_RELATIVE_PATH=path.join("runtime","telemetry","events.jsonl");const TELEMETRY_STATE_RELATIVE_PATH=path.join("runtime","telemetry","state.json");const TELEMETRY_RUNTIME_RELATIVE_PATH=path.join("runtime","telemetry");const DEFAULT_STATS_LIMIT=20;const TELEMETRY_SUBCOMMANDS=["status","flush","stats","clear"];const nearestRankPercentile=(sortedAscending,fraction)=>{const rank=Math.ceil(fraction*sortedAscending.length);const index=Math.min(sortedAscending.length-1,Math.max(0,rank-1));return sortedAscending[index]};const normalizeTelemetryText=(value,fallback)=>{if(typeof value!=="string"){return fallback}return value.trim().length>0?value:fallback};const normalizeFiniteInteger=value=>{if(typeof value!=="number"||!Number.isFinite(value)){return void 0}return Math.trunc(value)};const normalizeTelemetryQueueEntry=entry=>{return{command:normalizeTelemetryText(entry.event.command,"<unknown>"),eventType:normalizeTelemetryText(entry.event.event_type,"unknown"),eventSchemaVersion:normalizeFiniteInteger(entry.event.schema_version),clientSchemaVersion:normalizeFiniteInteger(entry.client_schema_version)}};const createTelemetryStatsAccumulator=()=>{return{count:0,max_attempts:0,event_type_counts:{},event_schema_versions:new Set,client_schema_versions:new Set,finish_durations_ms:[],ok_count:0,error_count:0,resolution_counts:{}}};const readTelemetryDuration=payload=>{const value=payload?.duration_ms;return typeof value==="number"&&Number.isFinite(value)?value:void 0};const readTelemetryResolution=payload=>{const value=payload?.command_resolution;return normalizeTelemetryText(value,"")||void 0};const incrementTelemetryCount=(counts,key)=>{counts[key]=(counts[key]??0)+1};const recordTelemetryFinishPayload=(current,payload)=>{const durationMs=readTelemetryDuration(payload);if(durationMs!==void 0){current.finish_durations_ms.push(durationMs)}if(payload?.ok===true){current.ok_count+=1}else{current.error_count+=1}const resolution=readTelemetryResolution(payload);if(resolution!==void 0){incrementTelemetryCount(current.resolution_counts,resolution)}};const normalizeTelemetryAttempts=attempts=>Number.isFinite(attempts)?Math.max(0,Math.trunc(attempts)):0;const addTelemetryDimension=(values,value)=>{if(value!==void 0){values.add(value)}};const recordTelemetryQueueEntry=(grouped,entry)=>{const normalized=normalizeTelemetryQueueEntry(entry);const current=grouped.get(normalized.command)??createTelemetryStatsAccumulator();current.count+=1;current.max_attempts=Math.max(current.max_attempts,normalizeTelemetryAttempts(entry.attempts));incrementTelemetryCount(current.event_type_counts,normalized.eventType);addTelemetryDimension(current.event_schema_versions,normalized.eventSchemaVersion);addTelemetryDimension(current.client_schema_versions,normalized.clientSchemaVersion);if(normalized.eventType==="command_finish"){recordTelemetryFinishPayload(current,entry.event.payload)}grouped.set(normalized.command,current)};const buildTelemetryStatsBucket=(command,value)=>{const finishCount=value.ok_count+value.error_count;const sortedDurations=[...value.finish_durations_ms].sort((left,right)=>left-right);const resolutionEntries=Object.entries(value.resolution_counts).sort((left,right)=>left[0].localeCompare(right[0]));return{command,count:value.count,event_type_counts:Object.fromEntries(Object.entries(value.event_type_counts).sort((left,right)=>left[0].localeCompare(right[0]))),max_attempts:value.max_attempts,event_schema_versions:[...value.event_schema_versions].sort((left,right)=>left-right),client_schema_versions:[...value.client_schema_versions].sort((left,right)=>left-right),...sortedDurations.length>0?{duration_p50_ms:nearestRankPercentile(sortedDurations,.5),duration_p95_ms:nearestRankPercentile(sortedDurations,.95),duration_max_ms:sortedDurations[sortedDurations.length-1]}:{},...finishCount>0?{ok_count:value.ok_count,error_count:value.error_count,error_rate:value.error_count/finishCount}:{},...resolutionEntries.length>0?{command_resolution_counts:Object.fromEntries(resolutionEntries)}:{}}};const normalizeTelemetrySubcommand=value=>{const normalized=(value??"status").trim().toLowerCase();if(TELEMETRY_SUBCOMMANDS.includes(normalized)){return normalized}throw createUnknownSubcommandError({command_path:"telemetry",token:value?.trim()||"<empty>",allowed:TELEMETRY_SUBCOMMANDS,examples:["pm telemetry status","pm telemetry flush","pm telemetry stats --limit 10","pm telemetry clear"]})};const throwInvalidTelemetryLimit=()=>{throw new PmCliError("--limit must be a positive integer",EXIT_CODE.USAGE)};const requirePositiveTelemetryLimit=value=>{if([!Number.isFinite(value),!Number.isInteger(value),value<=0].includes(true)){return throwInvalidTelemetryLimit()}return value};const parseTelemetryStringLimit=raw=>{const trimmed=raw.trim();if([trimmed.length===0,!/^\d+$/.test(trimmed)].includes(true)){return throwInvalidTelemetryLimit()}return requirePositiveTelemetryLimit(Number.parseInt(trimmed,10))};const parseTelemetryStatsLimit=raw=>{if(raw===void 0){return DEFAULT_STATS_LIMIT}if(typeof raw==="number"){return requirePositiveTelemetryLimit(raw)}if(typeof raw==="string"){return parseTelemetryStringLimit(raw)}return throwInvalidTelemetryLimit()};const isTelemetryQueueEntry=value=>{if(typeof value!=="object"||value===null){return false}const candidate=value;return typeof candidate.attempts==="number"&&typeof candidate.event==="object"&&candidate.event!==null};const parseTelemetryQueueRow=row=>{try{const parsed=JSON.parse(row);return isTelemetryQueueEntry(parsed)?parsed:void 0}catch{return void 0}};const splitTelemetryQueueRows=raw=>{if(raw===null){return[]}return raw.split("\n").map(line=>line.trim()).filter(line=>line.length>0)};const parseTelemetryQueue=raw=>{const rows=splitTelemetryQueueRows(raw);const entries=[];let invalidRows=0;for(const row of rows){const parsed=parseTelemetryQueueRow(row);if(parsed===void 0){invalidRows+=1}else{entries.push(parsed)}}return{rows_total:rows.length,valid_entries:entries.length,invalid_rows:invalidRows,entries}};const isTelemetryRuntimeState=value=>typeof value==="object"&&value!==null&&!Array.isArray(value);const parseTelemetryRuntimeState=raw=>{try{const parsed=JSON.parse(raw);return isTelemetryRuntimeState(parsed)?parsed:{}}catch{return{}}};const readTelemetryRuntimeState=async statePath=>{const stateRaw=await readFileIfExists(statePath);if(stateRaw===null||stateRaw.trim().length===0){return{}}return parseTelemetryRuntimeState(stateRaw)};const nullableTelemetryStateValue=value=>value??null;const buildTelemetryStatusSummary=async globalPmRoot=>{const settings=await readSettings(globalPmRoot);const queuePath=path.join(globalPmRoot,TELEMETRY_QUEUE_RELATIVE_PATH);const statePath=path.join(globalPmRoot,TELEMETRY_STATE_RELATIVE_PATH);const queueRaw=await readFileIfExists(queuePath);const queue=parseTelemetryQueue(queueRaw);const runtimeState=await readTelemetryRuntimeState(statePath);return{enabled:settings.telemetry.enabled,endpoint:settings.telemetry.endpoint,queue_path:queuePath,state_path:statePath,queue_rows_total:queue.rows_total,queue_entries:queue.valid_entries,queue_invalid_rows:queue.invalid_rows,queue_size_bytes:Buffer.byteLength(queueRaw??"","utf8"),last_attempted_flush_at:nullableTelemetryStateValue(runtimeState.last_attempted_flush_at),last_successful_flush_at:nullableTelemetryStateValue(runtimeState.last_successful_flush_at),last_failed_flush_at:nullableTelemetryStateValue(runtimeState.last_failed_flush_at),last_failed_flush_error:nullableTelemetryStateValue(runtimeState.last_failed_flush_error)}};const buildTelemetryStatsBuckets=entries=>{const grouped=new Map;for(const entry of entries){recordTelemetryQueueEntry(grouped,entry)}return[...grouped.entries()].map(([command,value])=>buildTelemetryStatsBucket(command,value)).sort((left,right)=>right.count-left.count||left.command.localeCompare(right.command))};const runTelemetryStatus=async(_options,context)=>({action:"telemetry",subcommand:"status",status:await buildTelemetryStatusSummary(context.globalPmRoot),generated_at:nowIso()});const runTelemetryFlush=async(_options,context)=>{const before=await buildTelemetryStatusSummary(context.globalPmRoot);await flushTelemetryQueueNow(context.globalPmRoot);const after=await buildTelemetryStatusSummary(context.globalPmRoot);const queueEntriesDrained=Math.max(0,before.queue_entries-after.queue_entries);const queueEmpty=after.queue_entries===0;return{action:"telemetry",subcommand:"flush",queue_entries_before:before.queue_entries,queue_entries_after:after.queue_entries,queue_entries_drained:queueEntriesDrained,queue_progressed:queueEntriesDrained>0,queue_empty:queueEmpty,queue_drained:queueEmpty,status:after,generated_at:nowIso()}};const runTelemetryStats=async(options,context)=>{const limit=parseTelemetryStatsLimit(options.limit);const queueRaw=await readFileIfExists(context.queuePath);const queue=parseTelemetryQueue(queueRaw);const buckets=buildTelemetryStatsBuckets(queue.entries);const selected=buckets.slice(0,limit);return{action:"telemetry",subcommand:"stats",limit,total_commands:buckets.length,queue_entries:queue.valid_entries,queue_invalid_rows:queue.invalid_rows,queue_rows_total:queue.rows_total,truncated:buckets.length>selected.length,stats:selected,generated_at:nowIso()}};const runTelemetryClear=async(_options,context)=>{const settings=await readSettings(context.globalPmRoot);const settingsChanged=[settings.telemetry.enabled!==false,settings.telemetry.installation_id!=="",settings.telemetry.first_run_prompt_completed!==true].includes(true);settings.telemetry.enabled=false;settings.telemetry.first_run_prompt_completed=true;settings.telemetry.installation_id="";if(settingsChanged){await writeSettings(context.globalPmRoot,settings,"telemetry:clear")}const telemetryRuntimePath=path.join(context.globalPmRoot,TELEMETRY_RUNTIME_RELATIVE_PATH);const existed=await pathExists(telemetryRuntimePath);await fs.rm(telemetryRuntimePath,{recursive:true,force:true});return{action:"telemetry",subcommand:"clear",settings_changed:settingsChanged,runtime_dir_removed:existed&&!await pathExists(telemetryRuntimePath),queue_exists_after:await pathExists(context.queuePath),state_exists_after:await pathExists(context.statePath),status:await buildTelemetryStatusSummary(context.globalPmRoot),generated_at:nowIso()}};const TELEMETRY_COMMAND_HANDLERS={status:runTelemetryStatus,flush:runTelemetryFlush,stats:runTelemetryStats,clear:runTelemetryClear};async function runTelemetry(options,_global){void _global;const subcommand=normalizeTelemetrySubcommand(options.subcommand);const globalPmRoot=resolveGlobalPmRoot(process.cwd());return TELEMETRY_COMMAND_HANDLERS[subcommand](options,{globalPmRoot,queuePath:path.join(globalPmRoot,TELEMETRY_QUEUE_RELATIVE_PATH),statePath:path.join(globalPmRoot,TELEMETRY_STATE_RELATIVE_PATH)})}export{TELEMETRY_SUBCOMMANDS,runTelemetry};
+!(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]="0c2960a8-84b8-57d1-bf5f-cea9cde0f544")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{pathExists,readFileIfExists}from"../core/fs/fs-utils.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{nowIso}from"../core/shared/time.js";import{resolveGlobalPmRoot}from"../core/store/paths.js";import{readSettings,writeSettings}from"../core/store/settings.js";import{resolveTelemetryEnvironmentPolicy}from"../core/telemetry/policy.js";import{flushTelemetryQueueNow,withTelemetryQueueMutation}from"../core/telemetry/runtime.js";import{createUnknownSubcommandError}from"./agent/subcommand-recovery.js";const TELEMETRY_QUEUE_RELATIVE_PATH=path.join("runtime","telemetry","events.jsonl");const TELEMETRY_STATE_RELATIVE_PATH=path.join("runtime","telemetry","state.json");const TELEMETRY_RUNTIME_RELATIVE_PATH=path.join("runtime","telemetry");const DEFAULT_STATS_LIMIT=20;const TELEMETRY_SUBCOMMANDS=["status","flush","stats","clear"];const nearestRankPercentile=(sortedAscending,fraction)=>{const rank=Math.ceil(fraction*sortedAscending.length);const index=Math.min(sortedAscending.length-1,Math.max(0,rank-1));return sortedAscending[index]};const normalizeTelemetryText=(value,fallback)=>{if(typeof value!=="string"){return fallback}return value.trim().length>0?value:fallback};const normalizeFiniteInteger=value=>{if(typeof value!=="number"||!Number.isFinite(value)){return void 0}return Math.trunc(value)};const normalizeTelemetryQueueEntry=entry=>{return{command:normalizeTelemetryText(entry.event.command,"<unknown>"),eventType:normalizeTelemetryText(entry.event.event_type,"unknown"),eventSchemaVersion:normalizeFiniteInteger(entry.event.schema_version),clientSchemaVersion:normalizeFiniteInteger(entry.client_schema_version)}};const createTelemetryStatsAccumulator=()=>{return{count:0,max_attempts:0,event_type_counts:{},event_schema_versions:new Set,client_schema_versions:new Set,finish_durations_ms:[],ok_count:0,error_count:0,resolution_counts:{}}};const readTelemetryDuration=payload=>{const value=payload?.duration_ms;return typeof value==="number"&&Number.isFinite(value)?value:void 0};const readTelemetryResolution=payload=>{const value=payload?.command_resolution;return normalizeTelemetryText(value,"")||void 0};const incrementTelemetryCount=(counts,key)=>{counts[key]=(counts[key]??0)+1};const recordTelemetryFinishPayload=(current,payload)=>{const durationMs=readTelemetryDuration(payload);if(durationMs!==void 0){current.finish_durations_ms.push(durationMs)}if(payload?.ok===true){current.ok_count+=1}else{current.error_count+=1}const resolution=readTelemetryResolution(payload);if(resolution!==void 0){incrementTelemetryCount(current.resolution_counts,resolution)}};const normalizeTelemetryAttempts=attempts=>Number.isFinite(attempts)?Math.max(0,Math.trunc(attempts)):0;const addTelemetryDimension=(values,value)=>{if(value!==void 0){values.add(value)}};const recordTelemetryQueueEntry=(grouped,entry)=>{const normalized=normalizeTelemetryQueueEntry(entry);const current=grouped.get(normalized.command)??createTelemetryStatsAccumulator();current.count+=1;current.max_attempts=Math.max(current.max_attempts,normalizeTelemetryAttempts(entry.attempts));incrementTelemetryCount(current.event_type_counts,normalized.eventType);addTelemetryDimension(current.event_schema_versions,normalized.eventSchemaVersion);addTelemetryDimension(current.client_schema_versions,normalized.clientSchemaVersion);if(normalized.eventType==="command_finish"){recordTelemetryFinishPayload(current,entry.event.payload)}grouped.set(normalized.command,current)};const buildTelemetryStatsBucket=(command,value)=>{const finishCount=value.ok_count+value.error_count;const sortedDurations=[...value.finish_durations_ms].sort((left,right)=>left-right);const resolutionEntries=Object.entries(value.resolution_counts).sort((left,right)=>left[0].localeCompare(right[0]));return{command,count:value.count,event_type_counts:Object.fromEntries(Object.entries(value.event_type_counts).sort((left,right)=>left[0].localeCompare(right[0]))),max_attempts:value.max_attempts,event_schema_versions:[...value.event_schema_versions].sort((left,right)=>left-right),client_schema_versions:[...value.client_schema_versions].sort((left,right)=>left-right),...sortedDurations.length>0?{duration_p50_ms:nearestRankPercentile(sortedDurations,.5),duration_p95_ms:nearestRankPercentile(sortedDurations,.95),duration_max_ms:sortedDurations[sortedDurations.length-1]}:{},...finishCount>0?{ok_count:value.ok_count,error_count:value.error_count,error_rate:value.error_count/finishCount}:{},...resolutionEntries.length>0?{command_resolution_counts:Object.fromEntries(resolutionEntries)}:{}}};const normalizeTelemetrySubcommand=value=>{const normalized=(value??"status").trim().toLowerCase();if(TELEMETRY_SUBCOMMANDS.includes(normalized)){return normalized}throw createUnknownSubcommandError({command_path:"telemetry",token:value?.trim()||"<empty>",allowed:TELEMETRY_SUBCOMMANDS,examples:["pm telemetry status","pm telemetry flush","pm telemetry stats --limit 10","pm telemetry clear"]})};const throwInvalidTelemetryLimit=()=>{throw new PmCliError("--limit must be a positive integer",EXIT_CODE.USAGE)};const requirePositiveTelemetryLimit=value=>{if([!Number.isFinite(value),!Number.isInteger(value),value<=0].includes(true)){return throwInvalidTelemetryLimit()}return value};const parseTelemetryStringLimit=raw=>{const trimmed=raw.trim();if([trimmed.length===0,!/^\d+$/.test(trimmed)].includes(true)){return throwInvalidTelemetryLimit()}return requirePositiveTelemetryLimit(Number.parseInt(trimmed,10))};const parseTelemetryStatsLimit=raw=>{if(raw===void 0){return DEFAULT_STATS_LIMIT}if(typeof raw==="number"){return requirePositiveTelemetryLimit(raw)}if(typeof raw==="string"){return parseTelemetryStringLimit(raw)}return throwInvalidTelemetryLimit()};const isTelemetryQueueEntry=value=>{if(typeof value!=="object"||value===null){return false}const candidate=value;return typeof candidate.attempts==="number"&&typeof candidate.event==="object"&&candidate.event!==null};const parseTelemetryQueueRow=row=>{try{const parsed=JSON.parse(row);return isTelemetryQueueEntry(parsed)?parsed:void 0}catch{return void 0}};const splitTelemetryQueueRows=raw=>{if(raw===null){return[]}return raw.split("\n").map(line=>line.trim()).filter(line=>line.length>0)};const parseTelemetryQueue=raw=>{const rows=splitTelemetryQueueRows(raw);const entries=[];let invalidRows=0;for(const row of rows){const parsed=parseTelemetryQueueRow(row);if(parsed===void 0){invalidRows+=1}else{entries.push(parsed)}}return{rows_total:rows.length,valid_entries:entries.length,invalid_rows:invalidRows,entries}};const isTelemetryRuntimeState=value=>typeof value==="object"&&value!==null&&!Array.isArray(value);const parseTelemetryRuntimeState=raw=>{try{const parsed=JSON.parse(raw);return isTelemetryRuntimeState(parsed)?parsed:{}}catch{return{}}};const readTelemetryRuntimeState=async statePath=>{const stateRaw=await readFileIfExists(statePath);if(stateRaw===null||stateRaw.trim().length===0){return{}}return parseTelemetryRuntimeState(stateRaw)};const nullableTelemetryStateValue=value=>value??null;const buildTelemetryStatusSummary=async globalPmRoot=>{const settings=await readSettings(globalPmRoot);const queuePath=path.join(globalPmRoot,TELEMETRY_QUEUE_RELATIVE_PATH);const statePath=path.join(globalPmRoot,TELEMETRY_STATE_RELATIVE_PATH);const queueRaw=await readFileIfExists(queuePath);const queue=parseTelemetryQueue(queueRaw);const runtimeState=await readTelemetryRuntimeState(statePath);const environmentPolicy=resolveTelemetryEnvironmentPolicy();return{enabled:settings.telemetry.enabled&&!environmentPolicy.telemetry_disabled,configured_enabled:settings.telemetry.enabled,env_overrides:environmentPolicy,endpoint:settings.telemetry.endpoint,queue_path:queuePath,state_path:statePath,queue_rows_total:queue.rows_total,queue_entries:queue.valid_entries,queue_invalid_rows:queue.invalid_rows,queue_size_bytes:Buffer.byteLength(queueRaw??"","utf8"),last_attempted_flush_at:nullableTelemetryStateValue(runtimeState.last_attempted_flush_at),last_successful_flush_at:nullableTelemetryStateValue(runtimeState.last_successful_flush_at),last_failed_flush_at:nullableTelemetryStateValue(runtimeState.last_failed_flush_at),last_failed_flush_error:nullableTelemetryStateValue(runtimeState.last_failed_flush_error)}};const buildTelemetryStatsBuckets=entries=>{const grouped=new Map;for(const entry of entries){recordTelemetryQueueEntry(grouped,entry)}return[...grouped.entries()].map(([command,value])=>buildTelemetryStatsBucket(command,value)).sort((left,right)=>right.count-left.count||left.command.localeCompare(right.command))};const runTelemetryStatus=async(_options,context)=>({action:"telemetry",subcommand:"status",status:await buildTelemetryStatusSummary(context.globalPmRoot),generated_at:nowIso()});const runTelemetryFlush=async(_options,context)=>{const before=await buildTelemetryStatusSummary(context.globalPmRoot);await flushTelemetryQueueNow(context.globalPmRoot);const after=await buildTelemetryStatusSummary(context.globalPmRoot);const queueEntriesDrained=Math.max(0,before.queue_entries-after.queue_entries);const queueEmpty=after.queue_entries===0;return{action:"telemetry",subcommand:"flush",queue_entries_before:before.queue_entries,queue_entries_after:after.queue_entries,queue_entries_drained:queueEntriesDrained,queue_progressed:queueEntriesDrained>0,queue_empty:queueEmpty,queue_drained:queueEmpty,status:after,generated_at:nowIso()}};const runTelemetryStats=async(options,context)=>{const limit=parseTelemetryStatsLimit(options.limit);const queueRaw=await readFileIfExists(context.queuePath);const queue=parseTelemetryQueue(queueRaw);const buckets=buildTelemetryStatsBuckets(queue.entries);const selected=buckets.slice(0,limit);return{action:"telemetry",subcommand:"stats",limit,total_commands:buckets.length,queue_entries:queue.valid_entries,queue_invalid_rows:queue.invalid_rows,queue_rows_total:queue.rows_total,truncated:buckets.length>selected.length,stats:selected,generated_at:nowIso()}};const runTelemetryClear=async(_options,context)=>{return withTelemetryQueueMutation(async()=>{const settings=await readSettings(context.globalPmRoot);const settingsChanged=[settings.telemetry.enabled!==false,settings.telemetry.installation_id!=="",settings.telemetry.first_run_prompt_completed!==true].includes(true);settings.telemetry.enabled=false;settings.telemetry.first_run_prompt_completed=true;settings.telemetry.installation_id="";if(settingsChanged){await writeSettings(context.globalPmRoot,settings,"telemetry:clear")}const telemetryRuntimePath=path.join(context.globalPmRoot,TELEMETRY_RUNTIME_RELATIVE_PATH);const existed=await pathExists(telemetryRuntimePath);await fs.rm(telemetryRuntimePath,{recursive:true,force:true});return{action:"telemetry",subcommand:"clear",settings_changed:settingsChanged,runtime_dir_removed:existed&&!await pathExists(telemetryRuntimePath),queue_exists_after:await pathExists(context.queuePath),state_exists_after:await pathExists(context.statePath),status:await buildTelemetryStatusSummary(context.globalPmRoot),generated_at:nowIso()}},context.globalPmRoot)};const TELEMETRY_COMMAND_HANDLERS={status:runTelemetryStatus,flush:runTelemetryFlush,stats:runTelemetryStats,clear:runTelemetryClear};async function runTelemetry(options,_global){void _global;const subcommand=normalizeTelemetrySubcommand(options.subcommand);const globalPmRoot=resolveGlobalPmRoot(process.cwd());return TELEMETRY_COMMAND_HANDLERS[subcommand](options,{globalPmRoot,queuePath:path.join(globalPmRoot,TELEMETRY_QUEUE_RELATIVE_PATH),statePath:path.join(globalPmRoot,TELEMETRY_STATE_RELATIVE_PATH)})}export{TELEMETRY_SUBCOMMANDS,runTelemetry};
 //# sourceMappingURL=telemetry.js.map

package/docs/AGENT_UX_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Agent UX Contracts
 
-Tracker references: [pm-v1yo](../.agents/pm/issues/pm-v1yo.toon), [pm-i6pi](../.agents/pm/issues/pm-i6pi.toon), [pm-um4g](../.agents/pm/issues/pm-um4g.toon), [pm-tmhs](../.agents/pm/issues/pm-tmhs.toon), [pm-6m1i](../.agents/pm/issues/pm-6m1i.toon), [pm-cj9v](../.agents/pm/issues/pm-cj9v.toon), [pm-yp56](../.agents/pm/issues/pm-yp56.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon), [pm-rggtvd](../.agents/pm/issues/pm-rggtvd.toon), and [pm-vk7zek](../.agents/pm/issues/pm-vk7zek.toon).
+Tracker references: [pm-bwkmp4](../.agents/pm/issues/pm-bwkmp4.toon), [pm-zsic8h](../.agents/pm/issues/pm-zsic8h.toon), [pm-4f86c4](../.agents/pm/issues/pm-4f86c4.toon), [pm-v1yo](../.agents/pm/issues/pm-v1yo.toon), [pm-i6pi](../.agents/pm/issues/pm-i6pi.toon), [pm-um4g](../.agents/pm/issues/pm-um4g.toon), [pm-tmhs](../.agents/pm/issues/pm-tmhs.toon), [pm-6m1i](../.agents/pm/issues/pm-6m1i.toon), [pm-cj9v](../.agents/pm/issues/pm-cj9v.toon), [pm-yp56](../.agents/pm/issues/pm-yp56.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon), [pm-rggtvd](../.agents/pm/issues/pm-rggtvd.toon), and [pm-vk7zek](../.agents/pm/issues/pm-vk7zek.toon).
 
 These contracts keep common agent loops deterministic, token-efficient, and recoverable. Runtime contracts and `--help --json` remain the exact source for available flags.
 
@@ -50,7 +50,15 @@ Compatibility note: before the 2026.7.19 release, `findings_by_code` incorrectly
 
 ## Extension command ownership
 
-Extension handler aliases may create their own command groups, but they may not replace a core command or graft a handler beneath a core-owned command prefix. Collisions preserve the core command and emit `extension_command_collision:` with the core and extension owners. Package authors should rename or namespace the alias.
+Extensions may add unique leaves beneath core groups: `ops metrics` can coexist with core `ops health`. Core leaf paths, including declared leaves awaiting lazy registration, remain reserved. A same-path handler collision emits `extension_command_collision:` with both owners and preserves core execution. Metadata-only registrations can augment an already registered core command; matching a core action name does not grant ownership of its path. Declared package-backed relocated facets retain their existing registration contract. Packages should rename a conflicting leaf instead of abandoning the shared namespace.
+
+Existing `pm-ops` installations keep their `ops` namespace and command paths. Upgrading to the leaf-composition implementation restores commands such as `ops metrics` without reinstalling or renaming the package. For a true collision such as `ops health`, the warning identifies both owners; rename that extension leaf while keeping its non-conflicting siblings.
+
+## Command recovery and compact reads
+
+Unknown-command suggestions resolve deprecated spellings to their available canonical replacement, including required flags. For example, `pm start` suggests `pm claim --start`, and a misspelled `list-open` points to `pm list --status open`. The SDK exports `canonicalizeCommandSuggestions` alongside its ranking primitives so package hosts can apply the same alias policy. Its optional query token prefers available semantic matches, so `start` does not also suggest unrelated statistics commands. Unavailable replacements are omitted.
+
+Default TOON lists with complete brief rows show the rows, count, and `details: "--full"` recovery pointer. Active filters, warnings, and additional diagnostics remain visible. A producer-owned `details` field preserves the detailed envelope instead of being replaced. Partial or truncated reads retain their detailed completeness and continuation receipts. `--full` restores item metadata; JSON retains the complete structured list envelope. Human recovery bundles echo an attempted command once; JSON retains the separate normalized argument vector for programmatic recovery.
 
 ## Context and work selection
 

package/docs/CLI_GRAMMAR.md

@@ -133,3 +133,62 @@ shared compatibility contracts carry the parser and discovery mapping.
 Existing aliases retain their flags, arguments, and results and are hidden from
 default discovery. `search -- advanced` preserves the literal query that would
 otherwise collide with the package facet; options belong before the separator.
+
+## Item evidence facets and internal routing
+
+Tracked by [pm-yql1](../.agents/pm/tasks/pm-yql1.toon),
+[pm-lp4j](../.agents/pm/tasks/pm-lp4j.toon), and
+[pm-szdc](../.agents/pm/tasks/pm-szdc.toon).
+
+`item comments`, `item notes`, `item learnings`, `item files`, `item docs`,
+`item deps`, `item append`, and `item test` share the item noun. Each retains
+its existing arguments, flags, output, and SDK operation identity. For example:
+
+```bash
+pm item comments pm-a1b2 --add "Verified the acceptance criteria."
+pm item files pm-a1b2 --add path=src/example.ts,scope=project
+pm item test pm-a1b2 --add 'command=node --test,scope=project'
+pm item test pm-a1b2 --run --progress
+```
+
+The old root spellings remain executable compatibility aliases. Singular
+`comment`, `note`, `learning`, and plural `tests` resolve directly to the same
+canonical leaves. SDK and MCP clients continue using their published operation
+names; command relocation does not rename those APIs.
+
+`item test worker` is internal orchestration plumbing. With `guide-shell`
+installed, `completion statuses`, `completion tags`, and `completion types`
+provide runtime shell values. These internal leaves remain directly invocable
+but are excluded from public help and completion suggestions, including beneath
+public parents. Existing worker and completion-helper spellings remain valid.
+Default contract discovery also omits internal paths; use `contracts --full` or
+an exact `contracts --command "item test worker" --flags-only` selection to
+inspect their contracts without expanding ordinary agent context.
+
+## Declared visibility and completed destinations
+
+Tracked by [pm-34xisz](../.agents/pm/issues/pm-34xisz.toon),
+[pm-3ig9b6](../.agents/pm/issues/pm-3ig9b6.toon), and
+[pm-djyvbk](../.agents/pm/tasks/pm-djyvbk.toon).
+
+A package command's declared `tier` controls SDK runtime discovery. Internal
+commands and actions are omitted from default contracts, summaries, and schemas;
+full or explicitly scoped inspection retains them and their declared tier.
+Packages need no entry in a core-only visibility list.
+
+`history acknowledge` is the canonical author-disposition command. The permanent
+`history-author-acknowledge` alias keeps the same preview/apply handshake, flags,
+results, and SDK/MCP action identity. `assurance` retains its established surface
+as a reasoned exception: measurements, assertions, gates, and verdicts are
+persistent project data, with operations beyond diagnostics.
+
+Consolidation rows are checked against a complete all-status tracker snapshot.
+A missing, closed, or canceled owner fails the grammar gate unless a declared
+alias already resolves the spelling to a live canonical command. Delivered
+leaves are classified as target paths; deliberate concise item operations carry
+explicit keep-as-is reasons. Closing an owner cannot silently certify unfinished
+command migration.
+
+Full discovery uses a uniform destination table. Its `reason` column contains
+the rationale for exceptions and an empty string where no exception applies,
+so adding a rationale does not expand every row into repeated field names.

package/docs/COMMAND_NAMESPACES.md

@@ -40,10 +40,13 @@ pm contracts --command "ops stats" --flags-only
 ```
 
 Help, contracts, and shell completion expose native paths. Compatibility aliases
-remain declared in the SDK alias table. Alias guidance uses the existing
-`ux.deprecation_hints` setting. Human-readable calls emit it on stderr; JSON and
-quiet calls suppress it. Compact contract summaries omit duplicate root alias
-rows; full and explicitly selected contracts retain them. Optional commands appear only when their providing package is active;
+remain declared in the SDK alias table with a `lifecycle` field. The root
+spellings in the table above are `permanent` aliases: they are ergonomic API and
+emit nothing on stderr. Only `deprecated` spellings (for example `list-open` or
+`start-task`) emit the one-line migration hint, which the existing
+`ux.deprecation_hints` setting suppresses and which JSON and quiet calls never
+print. Compact contract summaries omit duplicate root alias rows; full and
+explicitly selected contracts retain them. Optional commands appear only when their providing package is active;
 namespace placement does not promote package behavior into core.
 
 ## SDK and package integration

package/docs/CONFIGURATION.md

@@ -150,29 +150,74 @@ Tests should set both `PM_PATH` and `PM_GLOBAL_PATH` to temporary directories. T
 
 ### Telemetry environment variables
 
-Telemetry is opt-in via `pm config set telemetry-tracking on` (see [Common Settings](#common-settings)). When enabled, these environment variables tune runtime behaviour. All boolean knobs accept `1`, `true`, `yes`, or `on` (case-insensitive); any other value leaves the knob off.
+Telemetry is enabled by default. Use `pm config set telemetry-tracking off` to opt out persistently (see [Common Settings](#common-settings)). When enabled, these environment variables tune runtime behaviour. All boolean knobs accept `1`, `true`, `yes`, or `on` (case-insensitive); any other value leaves the knob off.
 
 | Variable                             | Values                                        | Use                                                                                                                                             |
 | ------------------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | `PM_TELEMETRY_DISABLED`              | boolean                                       | Hard-disable all telemetry for this process, ignoring settings.                                                                                 |
+| `DO_NOT_TRACK` | boolean | Hard-disable event capture, identity creation, flush workers, endpoint probes, and Sentry, regardless of persisted preferences. |
+| `PM_TELEMETRY_SEND_TEST_EVENTS` | boolean | Explicitly allow inferred test events. Hard opt-outs still take precedence. |
+| `PM_TELEMETRY_READ_SAMPLE_RATE` | number greater than `0` and at most `1` | Opt-in inclusion probability for successful core-only reads; omitted or invalid values retain every invocation. |
 | `PM_NO_TELEMETRY`                    | boolean                                       | Alias for `PM_TELEMETRY_DISABLED` (honoured by the same checks).                                                                                |
 | `PM_TELEMETRY_OTEL_DISABLED`         | boolean                                       | Disable only OTLP trace-span export; the event queue still flushes.                                                                             |
 | `PM_TELEMETRY_INLINE_FLUSH`          | boolean                                       | Flush the queue and OTLP spans inline instead of dispatching the detached worker. Mainly for tests; normal use relies on the background worker. |
-| `PM_TELEMETRY_SOURCE_CONTEXT`        | `user` \| `automation` \| `test` \| `dogfood` | Override the inferred source context recorded on each event. Any other value is ignored and the context is inferred.                            |
+| `PM_TELEMETRY_SOURCE_CONTEXT`        | `user` \| `automation` \| `test` \| `dogfood` | Override the inferred source context recorded on each event. Unrecognized nonempty values use inferred context with `source_context_source=env_override_rejected`; the raw value is never emitted.                            |
 | `PM_TELEMETRY_HTTP_TIMEOUT_MS`       | integer milliseconds                          | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL).                     |
 | `PM_TELEMETRY_INGEST_KEY`            | string                                        | Sent as the `x-pm-telemetry-key` header on queue flushes; never logged.                                                                         |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | URL                                           | OTLP/HTTP traces endpoint for command spans. Takes precedence over the base endpoint.                                                           |
 | `OTEL_EXPORTER_OTLP_ENDPOINT`        | URL                                           | Base OTLP endpoint; the traces endpoint is derived by appending `/v1/traces`.                                                                   |
 | `OTEL_SERVICE_NAME`                  | string                                        | `service.name` attribute on exported spans (defaults to `pm-cli`).                                                                              |
 
+Unrecognized source-context overrides produce one bounded warning per process on
+stderr, naming the accepted values without echoing the rejected input. JSON
+invocations retain parseable stdout and receive the warning on stderr. Explicit
+quiet mode suppresses the warning; events and spans still carry the fixed
+rejection marker. Empty overrides mean no override. Existing consent
+rules continue to suppress all capture when telemetry is disabled.
+
+Event and OTLP queue appends and reconciliation share an installation-level
+mutex. Successful delivery, retry updates, and retention pruning reread the
+current queue while holding that mutex, so another updated CLI process cannot
+append into a file about to be replaced. Network delivery runs outside the
+mutex. Each foreground start, finish, or error capture uses a 250 ms
+lock-acquisition budget by default; queue maintenance, clear, and flush initialization
+retain a five-second default. `PM_LOCK_WAIT_MS` explicitly overrides these
+budgets. These are per-acquisition contention budgets, not total operation
+deadlines: queued in-process transactions and filesystem work can add latency.
+The existing 60-second stale-lock recovery policy applies. Telemetry remains best
+effort when storage is unavailable or contention exhausts the wait budget;
+collector success and an empty queue are separate observations, not a guarantee
+of exactly-once delivery. Upgrade concurrent CLI processes together: older
+versions do not participate in the installation mutex.
+
+Start and error capture recheck process opt-outs and saved consent under the
+installation mutex before initializing identity, and retain that mutex through
+immediate event writes. Completion rechecks both consent sources and its saved
+installation identity under the same mutex through deferred start, finish,
+and span writes. `telemetry clear` uses this transaction boundary, so it either
+removes a completed capture or prevents that capture from appending afterward.
+Flush identity initialization also revalidates consent under the mutex; network
+delivery and flush scheduling remain outside it. Preference changes are
+evaluated at the capture transaction's consent check. Re-enabling after a clear
+does not revive an invocation's old identity. These checks cannot recall
+requests already dispatched to a collector.
+
 Interaction rules:
 
-- `PM_TELEMETRY_DISABLED` / `PM_NO_TELEMETRY` short-circuit everything, including OTLP export, regardless of the other knobs.
+- `DO_NOT_TRACK` / `PM_TELEMETRY_DISABLED` / `PM_NO_TELEMETRY` short-circuit everything, including OTLP export, regardless of the other knobs.
 - `PM_TELEMETRY_HTTP_TIMEOUT_MS` applies only to the detached flush worker in normal use. It covers DNS, each IPv4/IPv6 connection attempt, TLS, and response completion. The upper bound preserves the 60-second worker-lock safety margin across the sequential event and OTLP phases; it does not make foreground commands wait for the network.
 - OTLP span export only happens when telemetry is enabled, `PM_TELEMETRY_OTEL_DISABLED` is off, and a traces endpoint is configured. By default spans are persisted to a bounded queue and exported by the detached, unref'd flush worker so commands exit promptly even when the traces endpoint is unreachable. `PM_TELEMETRY_INLINE_FLUSH=1` is the explicit test-oriented exception that performs the flush inline.
 - `pm health --check-telemetry --json` surfaces flush and OTLP export diagnostics (`pending_otel_spans`, `last_otel_attempt_at`, `last_otel_success_at`, `last_otel_failure_at`, `last_otel_failure_error`) and the active `env_overrides` (including `telemetry_inline_flush` and `telemetry_source_context`) so agents can self-diagnose a stalled endpoint.
 - An explicit `PM_AUTHOR` override adds a privacy-preserving agent-identity dimension to `command_start`/`command_finish` events so overridden invocations can be segmented in dashboards without leaking the raw author string. At `redacted`/`max` capture the events carry `author_context_hash` — the same installation-id-keyed one-way SHA-256 used for `pm_root_hash`/`cwd_hash`, so the same author hashes consistently within an installation but differently across installations. At `minimal` capture only a boolean `has_author_context` is emitted. The raw `PM_AUTHOR` value is never exported.
 
+Test environments inferred from `VITEST`, `VITEST_WORKER_ID`, or `NODE_ENV=test` suppress telemetry before identity creation. A valid explicit `PM_TELEMETRY_SOURCE_CONTEXT` or `PM_TELEMETRY_SEND_TEST_EVENTS=1` permits intentional test delivery. Point such tests at a local collector. Neither setting overrides a hard opt-out. `pm telemetry status` exposes effective `enabled`, persisted `configured_enabled`, and `env_overrides` so an empty queue is distinguishable from disabled delivery.
+
+SDK consumers that previously used `TelemetryStatusSummary.enabled` to display the saved preference should read `configured_enabled` instead. Use `enabled` to determine whether this process permits delivery.
+
+At `redacted` and `max` capture, events include a bounded `agent_harness` dimension (`claude-code`, `codex`, `pi`, `opencode`, `cursor`, `aider`, `gemini-cli`, `ci`, `other`, or `none`) and a boolean `ci`. Installation-keyed hashes remain available; raw author and model names remain private. Minimal capture omits both new dimensions.
+
+For repeated read loops, set `PM_TELEMETRY_READ_SAMPLE_RATE=0.1` and use `--no-extensions`. Sampling applies only to `stats`, `ops stats`, `list`, `get`, `next`, `context`, `activity`, and `aggregate`. Mutations, unknown commands, extension-enabled invocations, and failures are retained. Successful sampled reads defer their start until completion so both lifecycle events are retained or dropped together; abruptly terminated sampled reads have no event pair. Retained pairs carry numeric `sample_rate`, and OTLP spans carry `pm.sample_rate`; estimate population totals with weight `1 / sample_rate`. Failed sampled reads carry probability `1`. Local queue statistics describe retained observations, not weighted population estimates.
+
 `pm telemetry stats` reads the local queue and reports, per command bucket, latency percentiles (`duration_p50_ms`/`duration_p95_ms`/`duration_max_ms`, nearest-rank over `command_finish` `duration_ms`), outcome rates (`ok_count`/`error_count`/`error_rate`; a finish event whose `ok` is missing or not strictly `true` is counted conservatively as an error), and `command_resolution_counts`. These are an always-available, zero-network performance and reliability signal for the most recent queued window.
 
 ### Sentry environment variables

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -7,11 +7,11 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | Capability family | Commands |
 | --- | --- |
 | workspace | `init`, `config`, `workspace merge`, `schema`, `profile`, `ops telemetry`, `ops health`, `ops gc`, `workspace` |
-| intake | `create`, `item copy`, `context focus`, `history restore` |
+| intake | `create`, `item`, `item copy`, `context focus`, `history restore` |
 | context | `list`, `aggregate`, `context`, `get`, `search`, `item duplicates`, `ops eval`, `context next`, `history activity`, `ops stats`, `help` |
 | lifecycle | `update`, `update many`, `close`, `close many`, `close delete`, `claim`, `release` |
-| evidence | `history`, `history events`, `history redact`, `history repair`, `history compact`, `history attest`, `history-author-acknowledge`, `append`, `comments`, `notes`, `learnings`, `files`, `docs` |
-| graph | `graph`, `deps`, `plan` |
-| quality | `test`, `ops test-all`, `ops validate`, `assurance`, `contracts`, `ops` |
+| evidence | `history`, `history events`, `history redact`, `history repair`, `history compact`, `history attest`, `history acknowledge`, `item append`, `item comments`, `item notes`, `item learnings`, `item files`, `item docs` |
+| graph | `graph`, `item deps`, `plan` |
+| quality | `item test`, `ops test-all`, `ops validate`, `assurance`, `contracts`, `ops` |
 | automation | `meet`, `event`, `remind` |
 | extensions | `package` |

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -12,6 +12,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `install` | full | extensions |
 | `upgrade` | full | extensions |
 | `create` | core | intake |
+| `item` | full | intake |
 | `item-reopen` | full | lifecycle |
 | `copy` | full | intake |
 | `item copy` | full | intake |
@@ -49,6 +50,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `history-attest` | full | evidence |
 | `history attest` | full | evidence |
 | `history-author-acknowledge` | full | evidence |
+| `history acknowledge` | full | evidence |
 | `merge` | full | workspace |
 | `workspace merge` | full | workspace |
 | `schema` | standard | workspace |
@@ -66,14 +68,22 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `delete` | full | lifecycle |
 | `close delete` | full | lifecycle |
 | `append` | standard | evidence |
+| `item append` | standard | evidence |
 | `comments` | standard | evidence |
+| `item comments` | standard | evidence |
 | `notes` | standard | evidence |
+| `item notes` | standard | evidence |
 | `learnings` | standard | evidence |
+| `item learnings` | standard | evidence |
 | `files` | standard | evidence |
+| `item files` | standard | evidence |
 | `docs` | standard | evidence |
+| `item docs` | standard | evidence |
 | `deps` | standard | graph |
+| `item deps` | standard | graph |
 | `plan` | core | graph |
 | `test` | standard | quality |
+| `item test` | standard | quality |
 | `test-all` | full | quality |
 | `ops test-all` | full | quality |
 | `telemetry` | full | workspace |
@@ -103,3 +113,4 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `completion-tags` | internal | internal |
 | `completion-types` | internal | internal |
 | `test-runs-worker` | internal | internal |
+| `item test worker` | internal | internal |

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -5,6 +5,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | Command | Capability family | Canonical flags | Maximum |
 | --- | --- | ---: | ---: |
 | `init` | workspace | 30 | 30 |
+| `item` | intake | 20 | 20 |
 | `config` | workspace | 36 | 36 |
 | `extension` | extensions | 54 | 54 |
 | `package` | extensions | 55 | 55 |
@@ -74,7 +75,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `meet` | automation | 33 | 33 |
 | `event` | automation | 33 | 33 |
 | `remind` | automation | 29 | 29 |
-| `test-runs-worker` | internal | 25 | 25 |
+| `test-runs-worker` | internal | 20 | 20 |
 | `history attest` | evidence | 23 | 23 |
 | `history redact` | evidence | 27 | 27 |
 | `history repair` | evidence | 27 | 27 |
@@ -94,6 +95,16 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `update many` | lifecycle | 146 | 146 |
 | `close many` | lifecycle | 72 | 72 |
 | `close delete` | lifecycle | 24 | 24 |
+| `item comments` | evidence | 31 | 31 |
+| `item notes` | evidence | 35 | 35 |
+| `item learnings` | evidence | 31 | 31 |
+| `item files` | evidence | 39 | 39 |
+| `item docs` | evidence | 30 | 30 |
+| `item deps` | graph | 32 | 32 |
+| `item append` | evidence | 25 | 25 |
+| `item test` | quality | 53 | 53 |
+| `item test worker` | internal | 20 | 20 |
+| `history acknowledge` | evidence | 28 | 28 |
 | `item copy` | intake | 24 | 24 |
 | `workspace merge` | workspace | 27 | 27 |
 | `item duplicates` | context | 25 | 25 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -11,7 +11,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 - Uncovered error codes: 355
 - Coverage fraction: 0.050802
 - Closed-domain probes: 19
-- Grammar probes: 101
+- Grammar probes: 113
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -214,7 +214,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_positive_execution_receipt` | `missing_positive_execution_receipt` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 63 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 75 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
 | `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
 | `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.9.12"
+    "version": "2026.9.14"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.9.12",
+      "version": "2026.9.14",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -213,25 +213,25 @@
     "fast-json-patch": "^3.1.1",
     "npm-package-arg": "^13.0.2",
     "tar": "7.5.22",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@codspeed/vitest-plugin": "^5.7.1",
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@sentry/cli": "^3.7.0",
-    "@types/node": "^26.5.0",
+    "@types/node": "^26.5.1",
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.2",
     "eslint": "^10.10.0",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "74.0.0",
-    "fast-check": "^4.9.0",
+    "fast-check": "^4.10.0",
     "github-slugger": "2.0.0",
     "greptile": "^3.5.2",
     "jscpd": "^5.2.0",
-    "marked": "18.0.12",
+    "marked": "18.0.13",
     "parse5": "8.0.1",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/extensions/guide-shell/index.ts

@@ -126,50 +126,37 @@ function completionCommand(): CommandDefinition {
       runCompletionPackage(context.args, context.options, context.global),
   };
 }
-
-function completionTagsCommand(): CommandDefinition {
-  return {
-    name: "completion-tags",
+/** Registers this package's commands, actions, and runtime hooks with the host. */
+export function activate(api: ExtensionApi): void {
+  api.registerCommand(guideCommand());
+  api.registerCommand(completionCommand());
+  api.registerCommand({
+    name: "completion tags",
     action: "completion-tags",
     tier: "internal",
     family: "internal",
     description: "Print known tags for completion filters.",
     intent: "List tag values for lazy shell completion.",
     run: async (context) => runCompletionTagsPackage(context.global),
-  };
-}
-
-function completionStatusesCommand(): CommandDefinition {
-  return {
-    name: "completion-statuses",
+  });
+  api.registerCommand({
+    name: "completion statuses",
     action: "completion-statuses",
     tier: "internal",
     family: "internal",
     description: "Print runtime status IDs for completion filters.",
     intent: "List runtime status values for shell completion.",
     run: async (context) => runCompletionStatusesPackage(context.global),
-  };
-}
-
-function completionTypesCommand(): CommandDefinition {
-  return {
-    name: "completion-types",
+  });
+  api.registerCommand({
+    name: "completion types",
     action: "completion-types",
     tier: "internal",
     family: "internal",
     description: "Print runtime item type IDs for completion filters.",
     intent: "List runtime item types for shell completion.",
     run: async (context) => runCompletionTypesPackage(context.global),
-  };
-}
-
-/** Registers this package's commands, actions, and runtime hooks with the host. */
-export function activate(api: ExtensionApi): void {
-  api.registerCommand(guideCommand());
-  api.registerCommand(completionCommand());
-  api.registerCommand(completionTagsCommand());
-  api.registerCommand(completionStatusesCommand());
-  api.registerCommand(completionTypesCommand());
+  });
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(
       context as ServiceOverrideContext,

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.12",
+  "version": "2026.9.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",