@unbrained/pm-cli 2026.9.30 → 2026.10.2

package/dist/sdk/workspace-transaction.js

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

package/docs/BOUNDED_CONTEXT_READS.md

@@ -4,8 +4,9 @@ Tracked by [pm-pshhry](../.agents/pm/issues/pm-pshhry.toon),
 [pm-ydshl9](../.agents/pm/issues/pm-ydshl9.toon),
 [pm-bab3gb](../.agents/pm/issues/pm-bab3gb.toon),
 [pm-fx80w2](../.agents/pm/issues/pm-fx80w2.toon),
-[pm-gtw5zh](../.agents/pm/issues/pm-gtw5zh.toon), and
-[pm-s8ybl9](../.agents/pm/issues/pm-s8ybl9.toon).
+[pm-gtw5zh](../.agents/pm/issues/pm-gtw5zh.toon),
+[pm-s8ybl9](../.agents/pm/issues/pm-s8ybl9.toon), and
+[pm-x8jdt8](../.agents/pm/issues/pm-x8jdt8.toon).
 
 Project management is context management. Routine reads should pay for the
 requested evidence, and derived feedback should not grow with every candidate
@@ -21,12 +22,14 @@ The cost still depends on the addressed record, registered type directories,
 and extension activation; this is not a constant-latency guarantee for arbitrary
 extensions or unbounded individual history streams.
 
-Request hierarchy work explicitly with `--fields id,children`, `--tree`, or a
-deep/full container read. These paths preserve registered hierarchy semantics,
+Request hierarchy work explicitly with `--fields id,children`, `--tree`, a
+deep read of a container or custom type, or a full read of any type. These
+paths preserve registered hierarchy semantics,
 including inverse and custom relationship kinds, rather than treating only the
-scalar `parent` field as authoritative. An omitted `children` facet carries a
-restore selector in the omission receipt. Explicit deep/full and child-field
-projections retain a zero-count rollup for an empty container.
+scalar `parent` field as authoritative. An uncomputed `children` facet carries a
+restore selector in the omission receipt even for Task items, which may have
+children. Explicit full and child-field projections retain a zero-count rollup
+for an empty item; a deep container read does the same.
 
 Caller-carried output sessions retain only portable item identities in
 `next_state.seen_item_ids`. Workspace activity such as `_workspace` remains

package/docs/COMMANDS.md

@@ -184,7 +184,7 @@ As a read-only structured surface, `duplicates` accepts the universal output
 controls, including `--output-format json`, `--lean`, projection/amount
 controls, and token accounting, while its default TOON output remains bounded.
 Tracked by [pm-gh1076](../.agents/pm/issues/pm-gh1076.toon).
-Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. The universal `--output-include` selector can request stored collections directly, for example `pm get <id> --output-include comments,learnings,tests`; the same bare and `item.<field>` grammar works through CLI, SDK, and MCP transports. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Standard reads of every item type avoid a workspace child scan. For container-oriented built-ins (Epic, Feature, Milestone, and Plan) and custom types, `--depth deep|full` adds type-agnostic child counts, a bounded sample, and continuation metadata. An explicit `--fields id,children` requests that rollup for any type. See [bounded context reads](BOUNDED_CONTEXT_READS.md) for the cost contract. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
+Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. The universal `--output-include` selector can request stored collections directly, for example `pm get <id> --output-include comments,learnings,tests`; the same bare and `item.<field>` grammar works through CLI, SDK, and MCP transports. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Standard reads of every item type avoid a workspace child scan. For container-oriented built-ins (Epic, Feature, Milestone, and Plan) and custom types, `--depth deep` adds type-agnostic child counts, a bounded sample, and continuation metadata. Explicit `--full` and `--depth full` reads compute that rollup for every type, including Task parents. An explicit `--fields id,children` requests that rollup without the other deep fields. A read without a child rollup retains a `children` omission hint until a rollup proves the item has no children. See [bounded context reads](BOUNDED_CONTEXT_READS.md) for the cost contract. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 
 When the strongest duplicate match is terminal because the same work recurred,
 reuse its lineage instead of creating or copying another item:

package/docs/MERGE_SAFETY.md

@@ -14,7 +14,9 @@ compatibility is tracked by
 Lossless concurrent acceptance-criteria composition is tracked by
 [pm-inn5y5](../.agents/pm/issues/pm-inn5y5.toon).
 The Bun launcher and strict-health repair are tracked by
-[pm-vks66s](../.agents/pm/issues/pm-vks66s.toon).
+[pm-vks66s](../.agents/pm/issues/pm-vks66s.toon), with the Bun 1.3.5
+package-runner recurrence tracked by
+[pm-aaxq4n](../.agents/pm/issues/pm-aaxq4n.toon).
 Recency-aware scalar convergence, bounded fresh-clone decision evidence, and
 audited pre-durable receipt dispositions are tracked by
 [pm-7wzb6d](../.agents/pm/issues/pm-7wzb6d.toon),
@@ -44,11 +46,15 @@ The clone-local driver values record the absolute runtime launcher and bundled
 `dist/cli.js` path resolved by the installing SDK. With Node, the installer
 preserves an absolute PATH symlink when it resolves to the executing runtime, so
 a runtime manager can retarget that launcher during upgrades without breaking
-every clone. With Bun, it resolves an executable `bun` on an absolute PATH entry,
-checks that its version matches the running Bun version, and records its stable
-absolute target. Relative PATH entries, inaccessible launchers, and different
-runtimes are ignored; without a matching launcher, the installer retains the
-executing binary path.
+every clone. With Bun, the installer checks the absolute executable published
+by the package runner, absolute `PATH` entries, and the directly invoked binary
+for a matching Bun version, then records its stable target. Known temporary
+`bun-node-*` launcher copies are rejected even when their version matches.
+Relative paths, inaccessible launchers, and
+different runtimes are ignored. If no durable matching Bun launcher is available,
+installation fails with recovery guidance before it writes Git configuration or
+the shared fence; a temporary `bunx` runtime is never recorded as a successful
+driver installation.
 Git therefore does not depend
 on a bare `pm` command or the caller's later `PATH` when it merges tracker data.
 The item-path placeholder is stored as bare `%P`: Git performs the required

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -244,6 +244,24 @@ Explicit overrides below 256 tokens are rejected because the minimum
 machine-readable receipt cannot fit; malformed or absent overrides retain the
 declared intent budget.
 
+Projection refusals repair the original CLI invocation: tracker selection,
+operands, output encoding, filters and unrelated controls survive the retry.
+Unknown field selectors are removed while valid requested selectors remain.
+Full/projection conflicts retain the selected full or brief mode and remove the
+conflicting projection and intent controls. If that correction cannot be
+constructed safely, the error does not advertise an automatic retry.
+Tracked by [pm-gh1364](../.agents/pm/issues/pm-gh1364.toon).
+
+For a budget-compacted producer page, follow
+`output_budget_truncation.recovery.cursor` with `--output-cursor`, keeping the
+original arguments and any `--after` value. Once that cursor is absent, use the
+producer `next_cursor` with `--after` and remove `--output-cursor`. Universal
+output shaping and continuation controls do not change producer query identity;
+actual filter and scope changes still invalidate its cursor. Emitted `count`
+and `summary.returned_focus` describe delivered rows; matching-population totals
+remain separate, including explicit count-only aggregates. Context hierarchy companions may repeat while continuing a
+focus collection. Tracked by [pm-gh1371](../.agents/pm/issues/pm-gh1371.toon).
+
 The first cursor page carries the complete projection, filtering, sorting,
 completeness, row, and omission contracts. Continuation pages replace those
 chain-invariant blocks with `continuation_contract`, which carries the cursor's
@@ -380,3 +398,12 @@ key continue to receive the same rows.
 Dependency token accounting includes the projection declaration and derived
 receipt. Reported `usedTokens` and truncation estimates therefore describe the
 final serialized result, not a pre-receipt intermediate.
+
+When context field selection hides focus roles or blocker flags, optional
+`summary.focus_row_states` strings retain those classifications across JSON
+transport. Each character corresponds to a delivered record in its named focus
+section: `i`/`I` means in progress, `o`/`O` means open; uppercase means blocked.
+Continuation and compaction slice these receipts with the rows. Self-describing
+focus rows need no extra receipt. Semantic receipts are preserved during
+explanatory-string compaction, and corrupt alphabet or row-count mismatches are
+rejected.

package/docs/SDK.md

@@ -1449,6 +1449,104 @@ the same durable coordinator, restoring annotations, linked artifacts,
 lifecycle fields, and claim ownership on failure. It is the SDK primitive
 behind `pm item complete`.
 
+`previewItemMutations` validates an ordered plan with the same transaction
+coordinator and lifecycle primitives as apply, using a disposable copy of the
+tracker. Earlier staged creates, evidence updates and closures participate in
+later validation. Existing journals retain the coordinator's replay and
+plan-identity behavior. The preview coordinator writes no source item, history,
+claim, lock or journal data. Active declarative extension registrations are preserved;
+executable extension guards, hooks, service overrides, and package command
+handlers remain disabled. Package-backed `--template` create input cannot be
+semantically previewed through its package handler; expand it into explicit core
+mutation options before preview.
+
+Staging excludes derived `search` and `locks` content and unrelated runtime state,
+retaining registered item folders, explicitly configured schema files, and
+`runtime/session.json` for core focus and inherited-parent semantics. Root-layout
+trackers copy only tracker-owned files and directories, including standard and
+custom item folders and configured schema files; unrelated project content is
+excluded. Preview accepts regular files and directories. Entry checks reject
+existing interior symbolic links and special files; an explicitly selected root
+link is resolved once to establish the tracker boundary. Absolute configured
+schema paths inside that resolved boundary are
+remapped only in the staged settings. Schema files configured outside the
+tracker fail with `transaction_preview_external_schema`; relocate them inside
+the selected tracker root before retrying.
+
+Preview requires trusted, stable directory entries and ancestors. Where Node
+exposes `O_NOFOLLOW` and `O_NONBLOCK`, descriptor opens request those POSIX guards.
+Windows retains entry checks, regular-file descriptor checks and snapshot
+comparisons without these flags. Portable Node APIs do not pin directory entries
+or ancestors, and later fingerprints cannot prevent hostile path redirection
+before a read. Use a caller-owned isolated copy when an untrusted actor can
+concurrently replace workspace paths.
+
+Durable source bytes are fingerprinted before and after copying and compared
+with the staged copy. An inconsistent copy or a file disappearing during the
+scan fails with `transaction_preview_snapshot_changed` and can be retried.
+File contents are hashed in bounded streams so large history files do not
+require whole-file buffers. `PmCliError` failures from staged step inspection,
+compensation preparation and apply preserve their lifecycle classification and
+include a structured `transaction_operation` with the zero-based index,
+operation and requested target ID from the mutation plan, after any batch-local
+reference resolution. That ID need not be prefix-normalized. Native errors and
+compensation or recovery failures retain the coordinator's error semantics; if
+compensation also fails, its `AggregateError` preserves the decorated primary
+error.
+
+CLI `item mutate --dry-run`, `item complete --dry-run`, and MCP `pm_mutate`
+with `dryRun: true` share this validation. CLI structured previews use
+`runWithConfigurationOnlySettings(pmRoot, run, isEnabled?)` across bootstrap,
+command execution and error cleanup. The optional predicate defaults to enabled.
+Scoped settings reads validate `settings.json` and
+merge inline configuration with defaults, without loading or scaffolding optional
+schema files, running settings-read hooks, or consulting or populating hydrated
+settings caches. Only selected bootstrap/action tracker roots, the actual global
+tracker root, and their resolved aliases are scoped.
+
+Nested async-local scopes compose through new policy layers without modifying
+their ancestors. Matching-root reads evaluate live predicates, so returning
+`false` disables that layer while an enabled caller-owned ancestor can still
+protect the same root. Concurrent invocations keep separate policies, and scopes
+restore when the callback returns or throws. Staged and unrelated roots retain
+normal settings behavior, including schema-file hydration.
+
+CLI bootstrap conservatively protects normalized invocations in the `item`
+namespace that contain a literal `--dry-run`, before extension option contracts
+are available. These settings policies cover command registration, invocation
+base-settings reads and parser-error cleanup. The earliest root `preAction` hook
+then settles invocation-owned policies from the actual selected command path and
+effective `optsWithGlobals()` values, before host-owned consent, migration and
+telemetry preparation. The real parser owns required-option values, `--`
+boundaries, positional child selection and inherited option precedence. For
+example, an extension's required `--package-note --dry-run` consumes `--dry-run`
+as its value. Without a separate preview flag, ordinary apply disables its own
+policy layers and resumes normal source/global settings hydration, consent,
+identity initialization and migration preparation. Explicit caller-owned layers
+remain effective. Genuine previews remain scoped when extension options are
+present.
+Structured CLI previews skip host-owned extension
+migration execution, first-use telemetry consent persistence and installation-ID
+initialization. Pending migration effects on a later commit remain unvalidated.
+Existing consented telemetry with a persisted identity still
+enters derived local queues; preview schedules no flush worker, and later normal
+commands retain delivery. Normal CLI extension discovery and activation happen
+before staged execution and retain their existing policy. CLI parser/preflight
+overrides and before/after-command hooks are also outside staged
+suppression; `--no-extensions` disables those executable paths.
+
+`ItemMutationPreviewValidation`
+reports `validated: true, state: "staged_snapshot"` when the coordinator
+executes the staged plan. An already committed journal instead returns
+`validated: false, state: "replayed_committed_plan"`, matching idempotent apply
+without freshly executing or validating the supplied lifecycle steps. Both
+results disclose
+`unresolved_commit_constraints: ["concurrent_tracker_changes",
+"extension_mutation_guards_and_hooks"]`. Newly staged validation proves core
+semantic validity at that snapshot; commit still checks current state and runs
+extension guards and hooks. Preview cost is proportional to the tracker data
+staged, rather than unrelated root-layout project content.
+
 `itemDocumentToMutationOptions` is the companion full-document adapter. It
 accepts either a direct `ItemDocument` or the envelope returned by
 `pm get <id> --json`, strips read-only metadata, maps canonical snake-case item

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,12 +4,12 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 390
+- Catalog error codes: 393
 - Executable error codes: 19
 - Executable-code ratchet floor: 18
 - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
-- Uncovered error codes: 371
-- Coverage fraction: 0.048718
+- Uncovered error codes: 374
+- Coverage fraction: 0.048346
 - Closed-domain probes: 19
 - Grammar probes: 117
 
@@ -200,6 +200,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `mcp_annotation_file_unavailable` | `mcp_annotation_file_unavailable` | uncovered | none | 0 |
 | `mcp_stdin_unavailable` | `mcp_stdin_unavailable` | uncovered | none | 0 |
 | `mcp_task_not_found_or_not_authorized` | `mcp_task_not_found_or_not_authorized` | uncovered | none | 0 |
+| `merge_bun_launcher_unavailable` | `merge_bun_launcher_unavailable` | uncovered | none | 0 |
 | `merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
 | `merge_decisions_unreviewed` | `merge_decisions_unreviewed` | uncovered | none | 0 |
 | `merge_driver_configuration_drift` | `merge_driver_configuration_drift` | uncovered | none | 0 |
@@ -320,6 +321,8 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `tracker_root_missing` | `tracker_root_missing` | executable | owned_state | 1 |
 | `tracker_root_not_directory` | `tracker_root_not_directory` | executable | owned_state | 1 |
 | `tracker_root_unreadable` | `tracker_root_unreadable` | executable | owned_state | 1 |
+| `transaction_preview_external_schema` | `transaction_preview_external_schema` | uncovered | none | 0 |
+| `transaction_preview_snapshot_changed` | `transaction_preview_snapshot_changed` | uncovered | none | 0 |
 | `type_duplicate` | `type_duplicate` | uncovered | none | 0 |
 | `type_invalid` | `type_invalid` | uncovered | none | 0 |
 | `undeclared_observation` | `undeclared_observation` | uncovered | none | 0 |

package/marketplace.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "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.30",
+  "version": "2026.10.2",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "pm-claude",
   "displayName": "pm CLI",
   "description": "Native pm CLI integration for Claude Code — 32 MCP tools, 14 skills with slash invocations, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-claude/package.json

@@ -2,8 +2,8 @@
   "name": "pm-claude-runtime",
   "private": true,
   "type": "module",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "dependencies": {
-    "@unbrained/pm-cli": "2026.9.30"
+    "@unbrained/pm-cli": "2026.10.2"
   }
 }

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",

package/plugins/pm-codex/package.json

@@ -2,8 +2,8 @@
   "name": "pm-codex-runtime",
   "private": true,
   "type": "module",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "dependencies": {
-    "@unbrained/pm-cli": "2026.9.30"
+    "@unbrained/pm-cli": "2026.10.2"
   }
 }

package/plugins/pm-codex/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pm-codex",
-  "version": "2026.9.30",
+  "version": "2026.10.2",
   "description": "Repository-native project context workflows and a version-pinned pm MCP server for Codex.",
   "author": {
     "name": "unbrained",