@unbrained/pm-cli 2026.7.18 → 2026.7.19

package/dist/sdk/tracker-root-discovery.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module sdk/tracker-root-discovery
+ *
+ * Exposes safe tracker-root discovery primitives to CLI and package consumers.
+ */
+export { discoverNearbyPmRoot } from "../core/store/paths.js";

package/dist/sdk/tracker-root-discovery.js

@@ -0,0 +1,10 @@
+/**
+ * @module sdk/tracker-root-discovery
+ *
+ * Exposes safe tracker-root discovery primitives to CLI and package consumers.
+ */
+
+!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]="3989cf71-e5bd-5c4f-8dd1-c98c7cd79f79")}catch(e){}}();
+export { discoverNearbyPmRoot } from "../core/store/paths.js";
+//# sourceMappingURL=tracker-root-discovery.js.map
+//# debugId=3989cf71-e5bd-5c4f-8dd1-c98c7cd79f79

package/dist/sdk/tracker-root-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker-root-discovery.js","sources":["sdk/tracker-root-discovery.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/tracker-root-discovery\n *\n * Exposes safe tracker-root discovery primitives to CLI and package consumers.\n */\nexport { discoverNearbyPmRoot } from \"../core/store/paths.js\";\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC","debugId":"3989cf71-e5bd-5c4f-8dd1-c98c7cd79f79"}

package/dist/sdk/workspace-transaction.d.ts

@@ -0,0 +1,83 @@
+/** Durable state reported by a transaction step inspection. */
+export type WorkspaceTransactionStepState = "pending" | "applied" | "compensated";
+/** JSON-compatible values retained in the durable transaction journal. */
+export type WorkspaceTransactionJsonValue = null | boolean | number | string | WorkspaceTransactionJsonValue[] | {
+    [key: string]: WorkspaceTransactionJsonValue;
+};
+/** Result returned by a step inspection during replay or recovery. */
+export interface WorkspaceTransactionStepInspection {
+    /** Current durable state of the step's domain mutation. */
+    state: WorkspaceTransactionStepState;
+    /** Reconstructed result when the mutation is already applied. */
+    result?: WorkspaceTransactionJsonValue;
+}
+/** One idempotent forward mutation with an append-only compensation. */
+export interface WorkspaceTransactionStep {
+    /** Stable identifier unique within the transaction plan. */
+    id: string;
+    /** Inspect durable domain state without mutating it. */
+    inspect(): Promise<WorkspaceTransactionStepInspection>;
+    /** Capture journal-safe pre-mutation data required by compensation. */
+    prepareCompensation?(): Promise<WorkspaceTransactionJsonValue | undefined>;
+    /** Apply the forward mutation and return a journal-safe result, or store nothing. */
+    apply(): Promise<WorkspaceTransactionJsonValue | undefined>;
+    /** Idempotently reconcile only this step's exact forward mutation when present. */
+    compensate(data?: WorkspaceTransactionJsonValue): Promise<void>;
+}
+/** Observable transition points available to diagnostics and failure injection. */
+export type WorkspaceTransactionTransition = "prepared" | "step_applied" | "step_recorded" | "committing" | "committed" | "compensating" | "step_compensating" | "step_compensated" | "compensated";
+/** Context emitted at each transaction transition. */
+export interface WorkspaceTransactionTransitionContext {
+    /** Stable transaction identifier. */
+    transactionId: string;
+    /** Current durable transaction attempt. */
+    attempt: number;
+    /** Transition reached; `step_applied` follows mutation and precedes journal recording. */
+    transition: WorkspaceTransactionTransition;
+    /** Step associated with a step-level transition. */
+    stepId?: string;
+}
+/** Options accepted by the public workspace transaction coordinator. */
+export interface CommitWorkspaceTransactionOptions {
+    /** Tracker root that owns the journal and workspace-wide writer lock. */
+    pmRoot: string;
+    /** Stable idempotency key reused to recover an interrupted transaction. */
+    transactionId: string;
+    /** Attributable actor recorded in the durable journal. */
+    author: string;
+    /** Ordered idempotent mutations; compensations run in reverse order. */
+    steps: readonly WorkspaceTransactionStep[];
+    /** Lock lifetime in seconds; size this above the longest expected attempt. */
+    lockTtlSeconds?: number;
+    /** Maximum time to wait for the workspace writer lock. */
+    lockWaitMs?: number;
+    /** Optional transition observer used by telemetry and deterministic crash tests. */
+    onTransition?(context: WorkspaceTransactionTransitionContext): void | Promise<void>;
+}
+/** Successful durable transaction result. */
+export interface WorkspaceTransactionCommitResult {
+    /** Stable transaction identifier. */
+    transactionId: string;
+    /** Final durable state. */
+    status: "committed";
+    /** Whether an interrupted journal was resumed. */
+    recovered: boolean;
+    /** One result per ordered transaction step. */
+    results: Record<string, WorkspaceTransactionJsonValue>;
+}
+/**
+ * Deliberate process-boundary interruption used by deterministic crash tests.
+ * Throwing this from `onTransition` leaves the journal resumable and skips the
+ * normal in-process compensation path.
+ */
+export declare class WorkspaceTransactionInterruptedError extends Error {
+    /** Create one explicit crash-boundary interruption. */
+    constructor(message?: string);
+}
+/**
+ * Commit an ordered set of idempotent SDK mutations under one workspace writer
+ * lock. The durable journal resumes interrupted forward work, while ordinary
+ * failures append reverse-order compensations. This provides atomic logical
+ * replay without deleting or rewriting immutable domain histories.
+ */
+export declare function commitWorkspaceTransaction(options: CommitWorkspaceTransactionOptions): Promise<WorkspaceTransactionCommitResult>;

package/dist/sdk/workspace-transaction.js

@@ -0,0 +1,364 @@
+/**
+ * @module sdk/workspace-transaction
+ *
+ * Coordinates crash-recoverable, compensating transactions across public SDK
+ * mutation primitives without rewriting immutable item or relationship history.
+ */
+
+!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]="2f31b5a8-1462-545e-aa55-8e8f09f511b5")}catch(e){}}();
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { acquireLock } from "../core/lock/lock.js";
+import { writeFileAtomic } from "../core/fs/fs-utils.js";
+import { nowIso } from "../core/shared/time.js";
+/**
+ * Deliberate process-boundary interruption used by deterministic crash tests.
+ * Throwing this from `onTransition` leaves the journal resumable and skips the
+ * normal in-process compensation path.
+ */
+export class WorkspaceTransactionInterruptedError extends Error {
+    /** Create one explicit crash-boundary interruption. */
+    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 = 3_000;
+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)}\n`);
+}
+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 === undefined ||
+                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 === undefined ? undefined : cloneJournalValue(value, label);
+}
+function setJournalEntry(target, stepId, value, label) {
+    const cloned = cloneOptionalJournalValue(value, label);
+    if (cloned === undefined)
+        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 !== undefined;
+    if (journal?.status === "compensating")
+        await compensateAppliedSteps(options, journal);
+    if (journal === undefined || 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 &&
+            error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function emitTransition(options, journal, transition, stepId) {
+    await options.onTransition?.({
+        transactionId: journal.transactionId,
+        attempt: journal.attempt,
+        transition,
+        ...(stepId === undefined ? {} : { 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");
+}
+/**
+ * Commit an ordered set of idempotent SDK mutations under one workspace writer
+ * lock. The durable journal resumes interrupted forward work, while ordinary
+ * failures append reverse-order compensations. This provides atomic logical
+ * replay without deleting or rewriting immutable domain histories.
+ */
+export 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 !== undefined;
+        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();
+    }
+}
+//# sourceMappingURL=workspace-transaction.js.map
+//# debugId=2f31b5a8-1462-545e-aa55-8e8f09f511b5

package/dist/sdk/workspace-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-transaction.js","sources":["sdk/workspace-transaction.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/workspace-transaction\n *\n * Coordinates crash-recoverable, compensating transactions across public SDK\n * mutation primitives without rewriting immutable item or relationship history.\n */\nimport { mkdir, readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { acquireLock } from \"../core/lock/lock.js\";\nimport { writeFileAtomic } from \"../core/fs/fs-utils.js\";\nimport { nowIso } from \"../core/shared/time.js\";\n\n/** Durable state reported by a transaction step inspection. */\nexport type WorkspaceTransactionStepState =\n  | \"pending\"\n  | \"applied\"\n  | \"compensated\";\n\n/** JSON-compatible values retained in the durable transaction journal. */\nexport type WorkspaceTransactionJsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | WorkspaceTransactionJsonValue[]\n  | { [key: string]: WorkspaceTransactionJsonValue };\n\n/** Result returned by a step inspection during replay or recovery. */\nexport interface WorkspaceTransactionStepInspection {\n  /** Current durable state of the step's domain mutation. */\n  state: WorkspaceTransactionStepState;\n  /** Reconstructed result when the mutation is already applied. */\n  result?: WorkspaceTransactionJsonValue;\n}\n\n/** One idempotent forward mutation with an append-only compensation. */\nexport interface WorkspaceTransactionStep {\n  /** Stable identifier unique within the transaction plan. */\n  id: string;\n  /** Inspect durable domain state without mutating it. */\n  inspect(): Promise<WorkspaceTransactionStepInspection>;\n  /** Capture journal-safe pre-mutation data required by compensation. */\n  prepareCompensation?(): Promise<WorkspaceTransactionJsonValue | undefined>;\n  /** Apply the forward mutation and return a journal-safe result, or store nothing. */\n  apply(): Promise<WorkspaceTransactionJsonValue | undefined>;\n  /** Idempotently reconcile only this step's exact forward mutation when present. */\n  compensate(data?: WorkspaceTransactionJsonValue): Promise<void>;\n}\n\n/** Observable transition points available to diagnostics and failure injection. */\nexport type WorkspaceTransactionTransition =\n  | \"prepared\"\n  | \"step_applied\"\n  | \"step_recorded\"\n  | \"committing\"\n  | \"committed\"\n  | \"compensating\"\n  | \"step_compensating\"\n  | \"step_compensated\"\n  | \"compensated\";\n\n/** Context emitted at each transaction transition. */\nexport interface WorkspaceTransactionTransitionContext {\n  /** Stable transaction identifier. */\n  transactionId: string;\n  /** Current durable transaction attempt. */\n  attempt: number;\n  /** Transition reached; `step_applied` follows mutation and precedes journal recording. */\n  transition: WorkspaceTransactionTransition;\n  /** Step associated with a step-level transition. */\n  stepId?: string;\n}\n\n/** Options accepted by the public workspace transaction coordinator. */\nexport interface CommitWorkspaceTransactionOptions {\n  /** Tracker root that owns the journal and workspace-wide writer lock. */\n  pmRoot: string;\n  /** Stable idempotency key reused to recover an interrupted transaction. */\n  transactionId: string;\n  /** Attributable actor recorded in the durable journal. */\n  author: string;\n  /** Ordered idempotent mutations; compensations run in reverse order. */\n  steps: readonly WorkspaceTransactionStep[];\n  /** Lock lifetime in seconds; size this above the longest expected attempt. */\n  lockTtlSeconds?: number;\n  /** Maximum time to wait for the workspace writer lock. */\n  lockWaitMs?: number;\n  /** Optional transition observer used by telemetry and deterministic crash tests. */\n  onTransition?(\n    context: WorkspaceTransactionTransitionContext,\n  ): void | Promise<void>;\n}\n\n/** Successful durable transaction result. */\nexport interface WorkspaceTransactionCommitResult {\n  /** Stable transaction identifier. */\n  transactionId: string;\n  /** Final durable state. */\n  status: \"committed\";\n  /** Whether an interrupted journal was resumed. */\n  recovered: boolean;\n  /** One result per ordered transaction step. */\n  results: Record<string, WorkspaceTransactionJsonValue>;\n}\n\n/**\n * Deliberate process-boundary interruption used by deterministic crash tests.\n * Throwing this from `onTransition` leaves the journal resumable and skips the\n * normal in-process compensation path.\n */\nexport class WorkspaceTransactionInterruptedError extends Error {\n  /** Create one explicit crash-boundary interruption. */\n  public constructor(message = \"Workspace transaction interrupted\") {\n    super(message);\n    this.name = \"WorkspaceTransactionInterruptedError\";\n  }\n}\n\ntype WorkspaceTransactionJournalStatus =\n  | \"applying\"\n  | \"compensating\"\n  | \"compensated\"\n  | \"committed\";\n\ninterface WorkspaceTransactionJournal {\n  schemaVersion: 1;\n  transactionId: string;\n  author: string;\n  status: WorkspaceTransactionJournalStatus;\n  attempt: number;\n  createdAt: string;\n  updatedAt: string;\n  stepIds: string[];\n  startedStepIds: string[];\n  completedStepIds: string[];\n  results: Record<string, WorkspaceTransactionJsonValue>;\n  compensationData: Record<string, WorkspaceTransactionJsonValue>;\n}\n\nconst WORKSPACE_TRANSACTION_LOCK_ID = \"sdk-workspace-transaction\";\nconst TRANSACTION_ID_PATTERN = /^[a-zA-Z0-9._-]+$/;\nconst DEFAULT_LOCK_TTL_SECONDS = 30;\nconst DEFAULT_LOCK_WAIT_MS = 3_000;\n\nfunction requiredIdentifier(value: unknown, label: string): string {\n  if (typeof value !== \"string\")\n    throw new TypeError(`${label} must be a string`);\n  const normalized = value.trim();\n  if (!normalized || !TRANSACTION_ID_PATTERN.test(normalized))\n    throw new TypeError(`${label} must match [a-zA-Z0-9._-]+`);\n  return normalized;\n}\n\nfunction requiredText(value: unknown, label: string): string {\n  if (typeof value !== \"string\")\n    throw new TypeError(`${label} must be a string`);\n  const normalized = value.trim();\n  if (!normalized) throw new TypeError(`${label} must be non-empty`);\n  return normalized;\n}\n\nfunction positiveInteger(\n  value: number | undefined,\n  fallback: number,\n  label: string,\n) {\n  const resolved = value ?? fallback;\n  if (!Number.isInteger(resolved) || resolved <= 0)\n    throw new TypeError(`${label} must be a positive integer`);\n  return resolved;\n}\n\nfunction journalPath(pmRoot: string, transactionId: string): string {\n  return path.join(pmRoot, \"transactions\", \"sdk\", `${transactionId}.json`);\n}\n\nasync function writeJournal(\n  pmRoot: string,\n  journal: WorkspaceTransactionJournal,\n): Promise<void> {\n  journal.updatedAt = nowIso();\n  const target = journalPath(pmRoot, journal.transactionId);\n  await mkdir(path.dirname(target), { recursive: true });\n  await writeFileAtomic(target, `${JSON.stringify(journal, null, 2)}\\n`);\n}\n\nfunction hasValidJournalMetadata(\n  journal: Partial<WorkspaceTransactionJournal>,\n): boolean {\n  return (\n    Number.isInteger(journal.attempt) &&\n    typeof journal.author === \"string\" &&\n    typeof journal.createdAt === \"string\" &&\n    typeof journal.updatedAt === \"string\"\n  );\n}\n\nfunction createResultMap(\n  source?: Record<string, WorkspaceTransactionJsonValue>,\n): Record<string, WorkspaceTransactionJsonValue> {\n  return Object.assign(\n    Object.create(null) as Record<string, WorkspaceTransactionJsonValue>,\n    source,\n  );\n}\n\nfunction cloneJournalValue(\n  value: unknown,\n  label: string,\n): WorkspaceTransactionJsonValue {\n  try {\n    const serialized = JSON.stringify(value, (_key, nestedValue: unknown) => {\n      if (typeof nestedValue === \"number\" && !Number.isFinite(nestedValue))\n        throw new TypeError(`${label} contains a non-finite number`);\n      if (\n        nestedValue === undefined ||\n        typeof nestedValue === \"function\" ||\n        typeof nestedValue === \"symbol\"\n      )\n        throw new TypeError(`${label} contains a non-JSON value`);\n      return nestedValue;\n    }) as string;\n    return JSON.parse(serialized) as WorkspaceTransactionJsonValue;\n  } catch (error) {\n    throw new TypeError(`${label} must be JSON serializable`, { cause: error });\n  }\n}\n\nfunction cloneOptionalJournalValue(\n  value: unknown,\n  label: string,\n): WorkspaceTransactionJsonValue | undefined {\n  return value === undefined ? undefined : cloneJournalValue(value, label);\n}\n\nfunction setJournalEntry(\n  target: Record<string, WorkspaceTransactionJsonValue>,\n  stepId: string,\n  value: unknown,\n  label: string,\n): void {\n  const cloned = cloneOptionalJournalValue(value, label);\n  if (cloned === undefined) delete target[stepId];\n  else target[stepId] = cloned;\n}\n\nfunction isJournalMap(\n  value: unknown,\n): value is Record<string, WorkspaceTransactionJsonValue> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction hasUniqueKnownStepIds(\n  value: unknown,\n  stepIds: readonly string[],\n): value is string[] {\n  return (\n    Array.isArray(value) &&\n    new Set(value).size === value.length &&\n    value.every(\n      (stepId) => typeof stepId === \"string\" && stepIds.includes(stepId),\n    )\n  );\n}\n\nfunction hasValidJournalLifecycle(\n  journal: Partial<WorkspaceTransactionJournal>,\n  stepIds: readonly string[],\n): boolean {\n  if (\n    !hasUniqueKnownStepIds(journal.startedStepIds, stepIds) ||\n    !hasUniqueKnownStepIds(journal.completedStepIds, stepIds) ||\n    !isJournalMap(journal.results) ||\n    !isJournalMap(journal.compensationData)\n  )\n    return false;\n  const startedStepIds = journal.startedStepIds;\n  const started = new Set(startedStepIds);\n  const completedStepIds = journal.completedStepIds;\n  const completed = new Set(completedStepIds);\n  if (\n    Object.keys(journal.compensationData).some(\n      (stepId) => !started.has(stepId),\n    ) ||\n    Object.keys(journal.results).some((stepId) => !completed.has(stepId))\n  )\n    return false;\n  if (journal.status === \"committed\")\n    return stepIds.every((stepId) => completed.has(stepId));\n  return (\n    journal.status !== \"compensated\" ||\n    (completed.size === 0 && started.size === 0)\n  );\n}\n\nfunction parseJournal(\n  raw: string,\n  transactionId: string,\n  stepIds: readonly string[],\n): WorkspaceTransactionJournal {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw) as unknown;\n  } catch {\n    throw new TypeError(\n      `Workspace transaction ${transactionId} journal is invalid JSON`,\n    );\n  }\n  if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed))\n    throw new TypeError(\n      `Workspace transaction ${transactionId} journal is invalid`,\n    );\n  const journal = parsed as Partial<WorkspaceTransactionJournal>;\n  const identityMatches =\n    journal.schemaVersion === 1 && journal.transactionId === transactionId;\n  const stepsMatch =\n    Array.isArray(journal.stepIds) &&\n    journal.stepIds.length === stepIds.length &&\n    journal.stepIds.every((stepId, index) => stepId === stepIds[index]);\n  const lifecycleMatches = hasValidJournalLifecycle(journal, stepIds);\n  const metadataMatches = hasValidJournalMetadata(journal);\n  const statusMatches = [\n    \"applying\",\n    \"compensating\",\n    \"compensated\",\n    \"committed\",\n  ].includes(String(journal.status));\n  if (\n    !identityMatches ||\n    !stepsMatch ||\n    !lifecycleMatches ||\n    !metadataMatches ||\n    !statusMatches\n  )\n    throw new TypeError(\n      `Workspace transaction ${transactionId} journal does not match the supplied plan`,\n    );\n  return {\n    ...(journal as WorkspaceTransactionJournal),\n    results: createResultMap(journal.results),\n    compensationData: createResultMap(journal.compensationData),\n  };\n}\n\nasync function prepareJournalForApply(\n  options: CommitWorkspaceTransactionOptions,\n  transactionId: string,\n  author: string,\n  stepIds: string[],\n  existing: WorkspaceTransactionJournal | undefined,\n): Promise<{\n  journal: WorkspaceTransactionJournal;\n  recovered: boolean;\n}> {\n  let journal = existing;\n  const recovered = journal !== undefined;\n  if (journal?.status === \"compensating\")\n    await compensateAppliedSteps(options, journal);\n  if (journal === undefined || journal.status === \"compensated\") {\n    const timestamp = nowIso();\n    journal = {\n      schemaVersion: 1,\n      transactionId,\n      author,\n      status: \"applying\",\n      attempt: (journal?.attempt ?? 0) + 1,\n      createdAt: journal?.createdAt ?? timestamp,\n      updatedAt: timestamp,\n      stepIds,\n      startedStepIds: [],\n      completedStepIds: [],\n      results: createResultMap(),\n      compensationData: createResultMap(),\n    };\n    await writeJournal(options.pmRoot, journal);\n    await emitTransition(options, journal, \"prepared\");\n  }\n  return { journal, recovered };\n}\n\nasync function applyPreparedTransaction(\n  options: CommitWorkspaceTransactionOptions,\n  journal: WorkspaceTransactionJournal,\n  recovered: boolean,\n): Promise<WorkspaceTransactionCommitResult> {\n  try {\n    await discoverAppliedSteps(journal, options.steps);\n    await writeJournal(options.pmRoot, journal);\n    const completed = new Set(journal.completedStepIds);\n    const started = new Set(journal.startedStepIds);\n    for (const step of options.steps) {\n      if (completed.has(step.id)) continue;\n      const inspection = await step.inspect();\n      let result = cloneOptionalJournalValue(\n        inspection.result,\n        `Step ${step.id} result`,\n      );\n      if (inspection.state !== \"applied\") {\n        const compensationData = await step.prepareCompensation?.();\n        setJournalEntry(\n          journal.compensationData,\n          step.id,\n          compensationData,\n          `Step ${step.id} compensation data`,\n        );\n        started.add(step.id);\n        journal.startedStepIds = options.steps\n          .map((candidate) => candidate.id)\n          .filter((stepId) => started.has(stepId));\n        await writeJournal(options.pmRoot, journal);\n        const appliedResult = await step.apply();\n        result = cloneOptionalJournalValue(\n          appliedResult,\n          `Step ${step.id} result`,\n        );\n      }\n      await emitTransition(options, journal, \"step_applied\", step.id);\n      completed.add(step.id);\n      journal.completedStepIds = options.steps\n        .map((candidate) => candidate.id)\n        .filter((stepId) => completed.has(stepId));\n      setJournalEntry(\n        journal.results,\n        step.id,\n        result,\n        `Step ${step.id} result`,\n      );\n      await writeJournal(options.pmRoot, journal);\n      await emitTransition(options, journal, \"step_recorded\", step.id);\n    }\n    await emitTransition(options, journal, \"committing\");\n    journal.status = \"committed\";\n    await writeJournal(options.pmRoot, journal);\n    await emitTransition(options, journal, \"committed\");\n    return {\n      transactionId: journal.transactionId,\n      status: \"committed\",\n      recovered,\n      results: createResultMap(journal.results),\n    };\n  } catch (error) {\n    if (\n      error instanceof WorkspaceTransactionInterruptedError ||\n      journal.status === \"committed\"\n    )\n      throw error;\n    try {\n      await compensateAppliedSteps(options, journal);\n    } catch (compensationError) {\n      throw new AggregateError(\n        [error, compensationError],\n        `Workspace transaction failed and compensation failed: ${String(compensationError)}`,\n        { cause: compensationError },\n      );\n    }\n    throw error;\n  }\n}\n\nasync function loadJournal(\n  pmRoot: string,\n  transactionId: string,\n  stepIds: readonly string[],\n): Promise<WorkspaceTransactionJournal | undefined> {\n  try {\n    return parseJournal(\n      await readFile(journalPath(pmRoot, transactionId), \"utf8\"),\n      transactionId,\n      stepIds,\n    );\n  } catch (error) {\n    if (\n      error !== null &&\n      typeof error === \"object\" &&\n      \"code\" in error &&\n      error.code === \"ENOENT\"\n    )\n      return undefined;\n    throw error;\n  }\n}\n\nasync function emitTransition(\n  options: CommitWorkspaceTransactionOptions,\n  journal: WorkspaceTransactionJournal,\n  transition: WorkspaceTransactionTransition,\n  stepId?: string,\n): Promise<void> {\n  await options.onTransition?.({\n    transactionId: journal.transactionId,\n    attempt: journal.attempt,\n    transition,\n    ...(stepId === undefined ? {} : { stepId }),\n  });\n}\n\nasync function discoverAppliedSteps(\n  journal: WorkspaceTransactionJournal,\n  steps: readonly WorkspaceTransactionStep[],\n): Promise<void> {\n  const completed = new Set<string>();\n  const results = createResultMap();\n  for (const step of steps) {\n    const inspection = await step.inspect();\n    if (inspection.state === \"applied\") {\n      completed.add(step.id);\n      setJournalEntry(\n        results,\n        step.id,\n        inspection.result,\n        `Step ${step.id} result`,\n      );\n    }\n  }\n  journal.results = results;\n  journal.completedStepIds = steps\n    .map((step) => step.id)\n    .filter((stepId) => completed.has(stepId));\n}\n\nasync function compensateAppliedSteps(\n  options: CommitWorkspaceTransactionOptions,\n  journal: WorkspaceTransactionJournal,\n): Promise<void> {\n  journal.status = \"compensating\";\n  await writeJournal(options.pmRoot, journal);\n  await emitTransition(options, journal, \"compensating\");\n  const completed = new Set(journal.completedStepIds);\n  const started = new Set(journal.startedStepIds);\n  for (const step of [...options.steps].reverse()) {\n    if (!started.has(step.id) && !completed.has(step.id)) continue;\n    let shouldCompensate: boolean;\n    try {\n      shouldCompensate =\n        started.has(step.id) && (await step.inspect()).state === \"applied\";\n    } catch {\n      shouldCompensate = started.has(step.id);\n    }\n    if (shouldCompensate) {\n      await emitTransition(options, journal, \"step_compensating\", step.id);\n      await step.compensate(journal.compensationData[step.id]);\n    }\n    completed.delete(step.id);\n    started.delete(step.id);\n    journal.completedStepIds = options.steps\n      .map((candidate) => candidate.id)\n      .filter((stepId) => completed.has(stepId));\n    journal.startedStepIds = options.steps\n      .map((candidate) => candidate.id)\n      .filter((stepId) => started.has(stepId));\n    delete journal.results[step.id];\n    delete journal.compensationData[step.id];\n    await writeJournal(options.pmRoot, journal);\n    await emitTransition(options, journal, \"step_compensated\", step.id);\n  }\n  journal.status = \"compensated\";\n  await writeJournal(options.pmRoot, journal);\n  await emitTransition(options, journal, \"compensated\");\n}\n\n/**\n * Commit an ordered set of idempotent SDK mutations under one workspace writer\n * lock. The durable journal resumes interrupted forward work, while ordinary\n * failures append reverse-order compensations. This provides atomic logical\n * replay without deleting or rewriting immutable domain histories.\n */\nexport async function commitWorkspaceTransaction(\n  options: CommitWorkspaceTransactionOptions,\n): Promise<WorkspaceTransactionCommitResult> {\n  const pmRoot = requiredText(options.pmRoot, \"Transaction pmRoot\");\n  const transactionId = requiredIdentifier(\n    options.transactionId,\n    \"Transaction id\",\n  );\n  const author = requiredText(options.author, \"Transaction author\");\n  const lockTtlSeconds = positiveInteger(\n    options.lockTtlSeconds,\n    DEFAULT_LOCK_TTL_SECONDS,\n    \"Transaction lock TTL\",\n  );\n  const lockWaitMs = positiveInteger(\n    options.lockWaitMs,\n    DEFAULT_LOCK_WAIT_MS,\n    \"Transaction lock wait\",\n  );\n  const steps = [...options.steps];\n  if (steps.length === 0)\n    throw new TypeError(\"Workspace transaction requires at least one step\");\n  const stepIds = steps.map((step) => {\n    const stepId = requiredIdentifier(step.id, \"Transaction step id\");\n    if (stepId !== step.id)\n      throw new TypeError(\n        \"Transaction step id must not contain surrounding whitespace\",\n      );\n    return stepId;\n  });\n  if (new Set(stepIds).size !== stepIds.length)\n    throw new TypeError(\"Workspace transaction step ids must be unique\");\n  const stableOptions: CommitWorkspaceTransactionOptions = {\n    ...options,\n    pmRoot,\n    transactionId,\n    author,\n    steps,\n    lockTtlSeconds,\n    lockWaitMs,\n  };\n\n  const release = await acquireLock(\n    pmRoot,\n    WORKSPACE_TRANSACTION_LOCK_ID,\n    lockTtlSeconds,\n    author,\n    false,\n    false,\n    lockWaitMs,\n  );\n  try {\n    const existing = await loadJournal(pmRoot, transactionId, stepIds);\n    const recovered = existing !== undefined;\n    if (existing?.status === \"committed\")\n      return {\n        transactionId,\n        status: \"committed\",\n        recovered: true,\n        results: createResultMap(existing.results),\n      };\n    const prepared = await prepareJournalForApply(\n      stableOptions,\n      transactionId,\n      author,\n      stepIds,\n      existing,\n    );\n    return await applyPreparedTransaction(\n      stableOptions,\n      prepared.journal,\n      recovered || prepared.recovered,\n    );\n  } finally {\n    await release();\n  }\n}\n"],"names":[],"mappings":"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","debugId":"2f31b5a8-1462-545e-aa55-8e8f09f511b5"}

package/docs/AGENT_UX_CONTRACTS.md

@@ -0,0 +1,41 @@
+# 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).
+
+These contracts keep common agent loops deterministic, token-efficient, and recoverable. Runtime contracts and `--help --json` remain the exact source for available flags.
+
+## Relationship mutations
+
+`pm create`, `pm update`, and `pm update-many` preserve existing relationship data, including legacy cycles. When a mutation introduces a new cycle through an ordering relationship such as `blocked_by`, the result includes an `ordering_cycle_created:` warning with a concrete cycle path and a `pm graph audit` recovery pointer.
+
+The public SDK exports `collectNewOrderingCycleWarnings(beforeItems, afterItems, changedItemId)` from `@unbrained/pm-cli/sdk`. Package authors can apply the same immutable-snapshot advisory to custom mutation workflows; activated custom relationship kinds participate through the shared registry.
+
+`pm graph audit` uses two explicit units:
+
+- `finding_count`, `findings_by_severity`, and `findings_by_code` count finding rows.
+- `affected_subjects_by_severity` and `affected_subjects_by_code` count the items or edges represented by those findings.
+
+Compatibility note: before the 2026.7.19 release, `findings_by_code` incorrectly accumulated affected-subject counts while `findings_by_severity` counted finding rows. SDK and JSON consumers that depended on that old unit must migrate to `affected_subjects_by_code`; consumers comparing code and severity finding counts should keep using `findings_by_code`.
+
+## 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.
+
+## Context and work selection
+
+When an agenda event belongs to an item already emitted in `high_level`, `low_level`, or `blocked_fallback`, `pm context` emits a compact event containing `reference_only: true`, the item ID, time, kind, and event-specific data. Unlisted agenda items retain the full calendar projection.
+
+`pm next --assignee <identity>` ranks from that assignee's perspective unless `--caller-author` explicitly overrides it. This makes delegated work selection useful without temporarily changing `PM_AUTHOR`.
+
+Claim conflicts distinguish stored assignment from an explicit claim:
+
+- `assigned to <identity>` means assignment metadata owns the current value.
+- `claimed by <identity>` means the latest ownership mutation was `pm claim`.
+
+The structured conflict code remains `already_claimed_by` for compatibility with atomic claim retry loops.
+
+## Input and tracker recovery
+
+`--message` labels mutation history; it is never comment content. A comment invocation that supplies `--message` without positional text, `--add`, `--stdin`, or `--file` exits with a usage error instead of silently listing comments.
+
+Implicit tracker discovery covers the default `.agents/pm` layout and ancestor root-layout trackers. If the command misses those layouts but detects a directly nested custom tracker, recovery guidance names the existing root and shows both `--pm-path <root>` and `PM_PATH=<root>` forms. Initialize a new tracker only when no intended existing root is available.

package/docs/EXTENSIONS.md

@@ -225,6 +225,7 @@ First-party package exemplars:
 - [`pm-search-advanced`](../packages/pm-search-advanced/README.md): deterministic local search provider registration.
 - [`pm-templates`](../packages/pm-templates/README.md): reusable create-template package.
 - [`pm-todos`](../packages/pm-todos/README.md): todo import/export package with generated command contracts.
+- [`pm-vcs`](../packages/pm-vcs/README.md): deliberately non-PM VCS exemplar using custom schema, lifecycle commands, point-in-time reads, and durable relationship projections entirely through public SDK contracts.
 
 ## Governance Policy
 
@@ -296,17 +297,16 @@ Common APIs:
 - `api.registerFlags(command, flags)` adds runtime command flags. A flag may declare `value_type` (canonical; the legacy `type` alias is honored only when `value_type` is absent), `list: true` to accumulate repeated/comma-joined values like core `--tags`, and a `default` applied when the flag is omitted.
 - `api.registerItemFields(fields)` adds custom metadata fields. Agents can set declared fields with repeatable `pm create --field name=value` and `pm update <id> --field name=value`; undeclared names are rejected. Each field `type` is validated against `string | number | boolean | array | object` at activation, with a did-you-mean hint on typos.
 - `api.registerItemTypes(types)` adds custom item types.
+- `api.registerRelationshipKinds(definitions)` adds validated graph semantics. Definitions declare direction, inverse spelling, ordering/precedence, hierarchy, cardinality, lifecycle, aliases, payload schema, compatibility version, and self-edge policy. Active definitions are merged into native CLI, MCP, and SDK workspace graph assembly. Requires the `schema` capability and is governed by the `schema.relationshipkinds` policy surface.
 - `api.registerMigration(definition)` adds schema migrations.
 - `api.registerProfile(profile)` contributes a project profile — a declarative archetype bundling item types, statuses, fields, per-type workflows, config, templates, and package recommendations. Once active it resolves by name through `pm profile list/show/apply` alongside the core `agile`/`ops`/`research` archetypes (built-in names are reserved; a colliding registration is ignored with a warning). Requires the `schema` capability.
 - `api.registerService("output_format", handler)` customizes output formatting through the service override API. Return `context.payload`, `null`, or `undefined` for commands the extension does not own.
 - `api.registerRenderer("toon" | "json", renderer)` adds format-specific renderers. Return `null` for unrelated payloads so pm falls back to native rendering.
-- `suppressHostOutput(result?)` from `@unbrained/pm-cli/sdk` returns a structural
-  result marker for commands that already wrote their output. The CLI emits no
-  second payload; the optional `result` remains available to hooks, telemetry,
-  and embedded hosts.
+- `suppressHostOutput(result?)` from `@unbrained/pm-cli/sdk` marks commands that already wrote output, preventing a second CLI payload while retaining the optional result for hooks, telemetry, and embedded hosts.
 - `api.hooks.beforeCommand(handler)`, `api.hooks.afterCommand(handler)`, `api.hooks.onWrite(handler)`, `api.hooks.onRead(handler)`, and `api.hooks.onIndex(handler)` add lifecycle hooks.
   `afterCommand` receives command outcome fields plus optional compact `affected` item entries for mutations, including `previous_status`, `status`, `changed_fields`, and partial `previous`/`current` item metadata snapshots.
   `onWrite` always includes `path`, `scope`, and `op`; item mutations also add optional `item_id`, `item_type`, `before`, `after`, and `changed_fields`.
+- Registered command handlers receive `context.sdk`, a host-bound service bundle containing a native-action `PmClient`, `getItemAt`, and `openRelationshipEventStore`. The client reuses the already-active extension schema context without recursively loading extensions, so package commands can compose core lifecycle operations safely in CLI and SDK hosts.
 - An optional module-level `deactivate()` export (VS Code-style) is invoked by the host on shutdown/reload — including by the long-running MCP server between native-action requests — to close connections, clear timers, and release resources opened during `activate`. Teardown is best-effort and timeout-bounded by default so it does not block other extensions, except when a host explicitly disables waiting limits with `deactivate_timeout_ms: 0` or `Infinity`, which can wait indefinitely for a hanging `deactivate()` hook.
 
 The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only

package/docs/README.md

@@ -39,6 +39,7 @@ pm guide release --json
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
 - [SDK Primitive Inventory](SDK_PRIMITIVE_INVENTORY.md) - SDK-first migration map and private-import ratchet for CLI/MCP layering.
+- [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
 - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.