@unbrained/pm-cli 2026.8.27 → 2026.8.29

package/dist/core/item/parse.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Parse.
  */
 
-!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]="2252cfb9-37ea-57f1-b7ea-2b0c0f87ecb2")}catch(e){}}();
+!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]="80965b57-856c-5fef-a372-0c9f3766ada5")}catch(e){}}();
 import { PmCliError } from "../shared/errors.js";
 import { EXIT_CODE } from "../shared/constants.js";
 const STDIN_TOKEN = "-";
@@ -30,6 +30,16 @@ const CONTINUABLE_VALUE_KEYS = new Set([
     "value",
     "why_now",
 ]);
+/** Classify plaintext as structured key/value input using an explicit accepted-key vocabulary. */
+export function looksLikeStructuredKeyValueEntry(raw, keys) {
+    if (raw.startsWith("```") || raw.includes("\n")) {
+        return true;
+    }
+    const keyPattern = keys
+        .map((key) => key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("|");
+    return new RegExp(`^(?:[-*+]\\s+)?(?:${keyPattern})\\s*[:=]`, "i").test(raw);
+}
 /** Implements parse tags for the public runtime surface of this module. */
 export function parseTags(raw) {
     const trimmed = raw.trim();
@@ -188,16 +198,16 @@ function splitCsvSegments(raw) {
     const segments = [];
     let current = "";
     let inQuotes = false;
-    let escaped = false;
-    for (const char of raw) {
-        if (escaped) {
-            current += char;
-            escaped = false;
+    for (let index = 0; index < raw.length; index += 1) {
+        const char = raw[index];
+        if (char === "\\" && raw[index + 1] === ",") {
+            current += ",";
+            index += 1;
             continue;
         }
-        if (char === "\\") {
-            current += char;
-            escaped = true;
+        if (char === "\\" && raw[index + 1] !== undefined) {
+            current += `${char}${raw[index + 1]}`;
+            index += 1;
             continue;
         }
         if (char === '"') {
@@ -206,14 +216,14 @@ function splitCsvSegments(raw) {
             continue;
         }
         if (char === "," && !inQuotes) {
-            segments.push(current.trim());
+            segments.push(current);
             current = "";
             continue;
         }
         current += char;
     }
     if (current.trim()) {
-        segments.push(current.trim());
+        segments.push(current);
     }
     return segments;
 }
@@ -235,8 +245,8 @@ function unquoteValue(value) {
 function findKeyValueDelimiter(segment) {
     const equalsIndex = segment.indexOf("=");
     const colonIndex = segment.indexOf(":");
-    const hasEquals = equalsIndex > 0;
-    const hasColon = colonIndex > 0;
+    const hasEquals = equalsIndex >= 0;
+    const hasColon = colonIndex >= 0;
     if (hasEquals && hasColon) {
         return Math.min(equalsIndex, colonIndex);
     }
@@ -324,15 +334,18 @@ export function parseCsvKv(raw, optionName) {
     const segments = splitCsvSegments(trimmed);
     for (const segment of segments) {
         const delimiterIndex = findKeyValueDelimiter(segment);
-        if (delimiterIndex > 0) {
+        if (delimiterIndex >= 0) {
             const key = segment.slice(0, delimiterIndex).trim();
+            if (!key) {
+                throw new PmCliError(buildInvalidKvMessage(raw, optionName), EXIT_CODE.USAGE);
+            }
             const value = unquoteValue(segment.slice(delimiterIndex + 1).trim());
             result[key] = value;
             activeKey = key;
             continue;
         }
         if (activeKey && CONTINUABLE_VALUE_KEYS.has(activeKey.toLowerCase())) {
-            result[activeKey] = `${result[activeKey]},${segment.trim()}`;
+            result[activeKey] = `${result[activeKey]},${segment}`;
             continue;
         }
         throw new PmCliError(buildInvalidKvMessage(raw, optionName), EXIT_CODE.USAGE);
@@ -358,6 +371,15 @@ export function looksLikeGenericKeyValueEntry(raw) {
     }
     return GENERIC_LEADING_KV_KEY_PATTERN.test(trimmed);
 }
+/** Refuse a comma-bearing bare value whose meaning depends on guessing whether the comma separates values or belongs to one value. */
+export function assertNoAmbiguousBareCommaEntry(raw, optionName, noun, structured) {
+    if (structured || !raw.includes(","))
+        return;
+    throw new PmCliError(`${optionName} received an ambiguous comma-bearing bare ${noun}. Repeat ${optionName} for multiple values, or quote or escape literal commas in a structured key=<value> entry.`, EXIT_CODE.USAGE, {
+        code: "bare_comma_entry_ambiguous",
+        required: `Use one ${optionName} per bare ${noun}, or quote or escape literal commas in a structured key=<value> entry.`,
+    });
+}
 /**
  * Reject any key in a parsed CSV/markdown key/value map that is not part of the
  * caller's allowed-key contract, mirroring the strict `test --add` behavior
@@ -579,4 +601,4 @@ export const _testOnly = {
     parseMarkdownKeyValueLines,
 };
 //# sourceMappingURL=parse.js.map
-//# debugId=2252cfb9-37ea-57f1-b7ea-2b0c0f87ecb2
+//# debugId=80965b57-856c-5fef-a372-0c9f3766ada5

package/dist/core/shared/author.js

@@ -4,7 +4,7 @@
  * Provides shared primitives and utilities for Author.
  */
 
-!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]="8d89d381-5c6e-5f96-ba03-298fc6db9bba")}catch(e){}}();
+!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]="cf550961-0040-5e04-9d8d-16e316027e43")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
@@ -312,20 +312,50 @@ const MAX_PROVENANCE_PROBE_BYTES = 1_048_576;
 const MAX_CODEX_PROVENANCE_PROBE_BYTES = 4_194_304;
 const codexProvenanceSnapshotCache = new Map();
 const EMPTY_CODEX_PROVENANCE_SNAPSHOT = Object.freeze({});
-function parseClaudeProvenanceLine(line, dimension) {
+const claudeProvenanceSnapshotCache = new Map();
+const EMPTY_CLAUDE_PROVENANCE_SNAPSHOT = Object.freeze({});
+function asProvenanceRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function parseClaudeProvenanceLine(line) {
     let parsed;
     try {
         parsed = JSON.parse(line);
     }
     catch {
-        return undefined;
+        return EMPTY_CLAUDE_PROVENANCE_SNAPSHOT;
     }
-    const record = parsed;
-    const message = typeof record.message === "object" && record.message !== null
-        ? record.message
-        : undefined;
-    const value = dimension === "model" ? message?.model : record.version;
-    return nonBlank(value)?.slice(0, 256);
+    const record = asProvenanceRecord(parsed);
+    if (!record)
+        return EMPTY_CLAUDE_PROVENANCE_SNAPSHOT;
+    const queue = [
+        { value: record, depth: 0 },
+    ];
+    let visited = 0;
+    let model;
+    let version;
+    while (queue.length > 0 && visited < 64) {
+        const current = queue.shift();
+        visited += 1;
+        model ??= nonBlank(current.value.model)?.slice(0, 256);
+        version ??= nonBlank(current.value.version)?.slice(0, 256);
+        if (model && version)
+            break;
+        if (current.depth >= 4)
+            continue;
+        for (const value of Object.values(current.value)) {
+            const nested = asProvenanceRecord(value);
+            if (nested) {
+                queue.push({
+                    value: nested,
+                    depth: current.depth + 1,
+                });
+            }
+        }
+    }
+    return Object.freeze({ model, version });
 }
 function readClaudeSessionProvenance(dimension, signals, env) {
     const session = nonBlank(env.CLAUDE_CODE_SESSION_ID);
@@ -337,18 +367,40 @@ function readClaudeSessionProvenance(dimension, signals, env) {
     try {
         const file = fs.openSync(sessionPath, "r");
         try {
-            const size = fs.fstatSync(file).size;
-            const tailLength = Math.min(size, MAX_PROVENANCE_PROBE_BYTES);
+            const stats = fs.fstatSync(file);
+            const cacheKey = `${sessionPath}\u0000${stats.size}\u0000${stats.mtimeMs}`;
+            const cached = claudeProvenanceSnapshotCache.get(cacheKey);
+            if (cached)
+                return cached[dimension];
+            const probeLength = Math.min(stats.size, MAX_PROVENANCE_PROBE_BYTES);
+            const headLength = Math.min(probeLength, Math.ceil(probeLength / 2));
+            const tailLength = Math.min(probeLength - headLength, stats.size - headLength);
+            const head = Buffer.alloc(headLength);
+            fs.readSync(file, head, 0, headLength, 0);
             const tail = Buffer.alloc(tailLength);
-            fs.readSync(file, tail, 0, tailLength, Math.max(0, size - tailLength));
-            const lines = tail.toString("utf8").split("\n").reverse().slice(0, 4_096);
+            if (tailLength > 0) {
+                fs.readSync(file, tail, 0, tailLength, stats.size - tailLength);
+            }
+            const snapshot = {};
+            const lines = stats.size <= probeLength
+                ? Buffer.concat([head, tail]).toString("utf8").split("\n")
+                : [
+                    ...head.toString("utf8").split("\n").slice(0, 4_096),
+                    ...tail.toString("utf8").split("\n").slice(-4_096),
+                ];
             for (const line of lines) {
                 if (line.length === 0 || line.length > 262_144)
                     continue;
-                const value = parseClaudeProvenanceLine(line, dimension);
-                if (value)
-                    return value;
+                const parsed = parseClaudeProvenanceLine(line);
+                snapshot.model ??= parsed.model;
+                snapshot.version ??= parsed.version;
+                if (snapshot.model && snapshot.version)
+                    break;
             }
+            const frozen = Object.freeze(snapshot);
+            claudeProvenanceSnapshotCache.clear();
+            claudeProvenanceSnapshotCache.set(cacheKey, frozen);
+            return frozen[dimension];
         }
         finally {
             fs.closeSync(file);
@@ -1030,4 +1082,4 @@ export function resolveAuthor(candidate, fallback) {
     return identity.author;
 }
 //# sourceMappingURL=author.js.map
-//# debugId=8d89d381-5c6e-5f96-ba03-298fc6db9bba
+//# debugId=cf550961-0040-5e04-9d8d-16e316027e43

package/dist/mcp/tool-definitions.js

@@ -4,7 +4,7 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="b69edba8-884f-521c-9bc3-451c7df755a9")}catch(e){}}();
+!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]="41396cb5-7faf-5642-8746-8d94edb01d86")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_DISCOVERABLE_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
@@ -413,7 +413,7 @@ const RAW_TOOLS = [
     },
     {
         name: "pm_comments",
-        description: "List, add, edit, or delete comments on a pm item. Use options.add to append, options.edit=<1-based index> with replacement text to fix a comment, or options.delete=<1-based index> to remove one. " +
+        description: "List, add, edit, or delete comments on a pm item. Use options.add to append, options.edit=<1-based index> with replacement text to fix a comment, or options.delete=<1-based index> to remove one. options.ifAbsent applies only to options.add for retry-safe author-and-text deduplication and cannot combine with options.edit or options.delete. " +
             "List calls default to the most recent 20 comments with total_count/has_more metadata for token efficiency. " +
             "Pass options.limit=N to choose a page size, options.limit=0 for summary-only metadata, or options.full=true for full history.",
         inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, [
@@ -436,14 +436,14 @@ const RAW_TOOLS = [
     },
     {
         name: "pm_notes",
-        description: "List or add structured notes on a pm item. Use options.add to append a note; omit it to list existing notes.",
+        description: "List, add, edit, or delete structured notes on a pm item. options.ifAbsent applies only to options.add for retry-safe author-and-text deduplication and cannot combine with options.edit or options.delete. Omit mutation options to list existing notes.",
         inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, [
             "id",
         ]),
     },
     {
         name: "pm_learnings",
-        description: "List or add learnings on a pm item. Use options.add to capture a learning/insight; omit it to list existing learnings.",
+        description: "List, add, edit, or delete learnings on a pm item. options.ifAbsent applies only to options.add for retry-safe author-and-text deduplication and cannot combine with options.edit or options.delete. Omit mutation options to list existing learnings.",
         inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, [
             "id",
         ]),
@@ -748,4 +748,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=b69edba8-884f-521c-9bc3-451c7df755a9
+//# debugId=41396cb5-7faf-5642-8746-8d94edb01d86

package/dist/sdk/agent/command-recovery.js

@@ -6,10 +6,10 @@
  * supplied arguments are preserved byte-for-token.
  */
 
-!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]="4973a995-60f0-5990-9927-371dc6716063")}catch(e){}}();
+!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]="6084a18e-ccda-57f9-a7d8-45572799c021")}catch(e){}}();
 import { renderPmCommand } from "../command-line.js";
 import { resolveSubcommandFlagContractsForCommand } from "../cli-contracts.js";
-import { parseBootstrapCommandName } from "../cli-bootstrap.js";
+import { parseBootstrapCommandName } from "../cli-contracts/bootstrap-command-scanner.js";
 function normalizeMissingFlag(label) {
     const match = label.trim().match(/--[a-z0-9][a-z0-9_-]*/i);
     return match?.[0]?.replaceAll("_", "-").toLowerCase();
@@ -57,4 +57,4 @@ export function renderMissingOptionRetry(invocationArgv, commandName, missingLab
         : renderPmCommand(retry);
 }
 //# sourceMappingURL=command-recovery.js.map
-//# debugId=4973a995-60f0-5990-9927-371dc6716063
+//# debugId=6084a18e-ccda-57f9-a7d8-45572799c021

package/dist/sdk/agent/task-transcript-contracts.d.ts

@@ -0,0 +1,52 @@
+import { type PmOutputEnvelopeKind } from "../output-contracts.js";
+/** Stable schema version for replayable agent-task transcript corpora. */
+export declare const PM_AGENT_TASK_TRANSCRIPT_VERSION: 2;
+/** Supported strategies for measuring one transcript step's output cost. */
+export declare const PM_AGENT_TASK_ACCOUNTING_MODES: readonly ["self_reported", "independent_transport"];
+/** Token-accounting strategy a replayed transcript step must preserve. */
+export type PmAgentTaskAccountingMode = (typeof PM_AGENT_TASK_ACCOUNTING_MODES)[number];
+/** Scalar value that a replayed transcript must observe at one output path. */
+export type PmAgentTaskExpectedFieldValue = string | number | boolean | null;
+/** Output family expected from one replayed agent-task step. */
+export type PmAgentTaskStepOutputKind = PmOutputEnvelopeKind | "refusal";
+/** Declares one real CLI invocation within a replayable agent task. */
+export interface PmAgentTaskTranscriptStep {
+    /** Stable step identifier unique within its task. */
+    id: string;
+    /** Shell-free CLI arguments, excluding the pm executable, preserved exactly. */
+    args: readonly string[];
+    /** Process status required for the step to satisfy the transcript. */
+    expected_exit_code: number;
+    /** Semantic output family required from the transport. */
+    expected_output_kind: PmAgentTaskStepOutputKind;
+    /** Accounting strategy required from the measured transport. */
+    expected_accounting_mode: PmAgentTaskAccountingMode;
+    /** Dot-separated own-property paths proving required context was consumed. */
+    required_fields: readonly string[];
+    /** Exact terminal scalar values required at selected output paths. */
+    expected_field_values?: Readonly<Record<string, PmAgentTaskExpectedFieldValue>>;
+    /** Stable diagnostic code required from a refusal step. */
+    expected_error_code?: string;
+    /** Exact command or flag required in a refusal identity. */
+    expected_refusal_surface?: string;
+    /** Earlier refusal step whose recovery this successful step executes. */
+    recovery_for?: string;
+}
+/** Versioned multi-step agent workflow suitable for deterministic replay. */
+export interface PmAgentTaskTranscript {
+    /** Stable task identifier used by baselines and reports. */
+    id: string;
+    /** Human-readable task outcome represented by the transcript. */
+    description: string;
+    /** Ordered invocations whose shared workspace state completes the task. */
+    steps: readonly PmAgentTaskTranscriptStep[];
+}
+/** Published collection of replayable agent workflows. */
+export interface PmAgentTaskTranscriptCorpus {
+    /** Schema version governing every transcript in the corpus. */
+    version: typeof PM_AGENT_TASK_TRANSCRIPT_VERSION;
+    /** Complete ordered task set evaluated by the release gate. */
+    tasks: readonly PmAgentTaskTranscript[];
+}
+/** Parse and fail closed on malformed or internally inconsistent transcripts. */
+export declare function parsePmAgentTaskTranscriptCorpus(value: unknown): PmAgentTaskTranscriptCorpus;

package/dist/sdk/agent/task-transcript-contracts.js

@@ -0,0 +1,198 @@
+/**
+ * @module sdk/agent-task-transcript-contracts
+ *
+ * Defines and validates replayable agent-task transcripts without adding the
+ * SDK-only parser to ordinary CLI command bundles.
+ */
+
+!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]="006109f8-cb09-5a91-8929-7ac7521753b6")}catch(e){}}();
+import { isPmSuccessfulExitCode, resolvePmCommandExitContract, } from "../cli-contracts/command-exit-contracts.js";
+import { parseBootstrapCommandName } from "../cli-contracts/bootstrap-command-scanner.js";
+import { PM_OUTPUT_ENVELOPE_KINDS, resolvePmCommandOutputEnvelope, } from "../output-contracts.js";
+/** Stable schema version for replayable agent-task transcript corpora. */
+export const PM_AGENT_TASK_TRANSCRIPT_VERSION = 2;
+/** Supported strategies for measuring one transcript step's output cost. */
+export const PM_AGENT_TASK_ACCOUNTING_MODES = [
+    "self_reported",
+    "independent_transport",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readTranscriptString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function readTranscriptStringArray(value, field, preserveWhitespace = false) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new TypeError(`${field} must be a non-empty string array`);
+    }
+    return value.map((entry, index) => {
+        const normalized = readTranscriptString(entry, `${field}[${String(index)}]`);
+        return preserveWhitespace ? entry : normalized;
+    });
+}
+function readOptionalTranscriptString(value, field) {
+    return value === undefined ? undefined : readTranscriptString(value, field);
+}
+function readExpectedFieldValues(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value) || Object.keys(value).length === 0) {
+        throw new TypeError(`${field} must be a non-empty object`);
+    }
+    const entries = Object.entries(value).map(([path, expectedValue]) => {
+        if (path.length === 0 ||
+            path.split(".").some((segment) => segment.length === 0)) {
+            throw new TypeError(`${field} must use dot-separated own-property paths`);
+        }
+        if (expectedValue !== null &&
+            typeof expectedValue !== "string" &&
+            typeof expectedValue !== "boolean" &&
+            (typeof expectedValue !== "number" || !Number.isFinite(expectedValue))) {
+            throw new TypeError(`${field} values must be JSON primitives`);
+        }
+        return [path, expectedValue];
+    });
+    return Object.fromEntries(entries);
+}
+function assertTranscriptStepOutputContract(field, args, exitCode, outputKind, errorCode, refusalSurface) {
+    if (outputKind === "refusal") {
+        if (isPmSuccessfulExitCode(exitCode) ||
+            errorCode === undefined ||
+            refusalSurface === undefined) {
+            throw new TypeError(`${field} refusal steps require a non-success exit, error code, and refusal surface`);
+        }
+        return;
+    }
+    if (errorCode !== undefined || refusalSurface !== undefined) {
+        throw new TypeError(`${field} only refusal steps may declare expected_error_code or expected_refusal_surface`);
+    }
+    const command = parseBootstrapCommandName(args);
+    if (command === undefined) {
+        throw new TypeError(`${field}.args must identify a command after global flags`);
+    }
+    const exitContract = resolvePmCommandExitContract(command);
+    if (!isPmSuccessfulExitCode(exitCode) ||
+        (exitCode !== 0 &&
+            !exitContract?.exit_codes.some((declaredExitCode) => declaredExitCode === exitCode))) {
+        throw new TypeError(`${field} successful output must use exit code 0 or a command-declared successful effect exit`);
+    }
+    const declaredKind = resolvePmCommandOutputEnvelope(command).kind;
+    if (outputKind !== declaredKind) {
+        throw new TypeError(`${field} expected ${outputKind}, but ${command} declares ${declaredKind}`);
+    }
+}
+function parseAgentTaskTranscriptStep(value, taskId, index) {
+    if (!isRecord(value)) {
+        throw new TypeError(`tasks.${taskId}.steps[${String(index)}] must be an object`);
+    }
+    const field = `tasks.${taskId}.steps[${String(index)}]`;
+    const id = readTranscriptString(value.id, `${field}.id`);
+    const args = readTranscriptStringArray(value.args, `${field}.args`, true);
+    const expectedExitCode = value.expected_exit_code;
+    if (typeof expectedExitCode !== "number" ||
+        !Number.isSafeInteger(expectedExitCode)) {
+        throw new TypeError(`${field}.expected_exit_code must be a safe integer`);
+    }
+    const rawOutputKind = value.expected_output_kind;
+    if (rawOutputKind !== "refusal" &&
+        !PM_OUTPUT_ENVELOPE_KINDS.includes(rawOutputKind)) {
+        throw new TypeError(`${field}.expected_output_kind is unsupported`);
+    }
+    const expectedOutputKind = rawOutputKind;
+    const rawAccountingMode = value.expected_accounting_mode;
+    if (!PM_AGENT_TASK_ACCOUNTING_MODES.includes(rawAccountingMode)) {
+        throw new TypeError(`${field}.expected_accounting_mode is unsupported`);
+    }
+    const expectedAccountingMode = rawAccountingMode;
+    if (expectedAccountingMode === "independent_transport" &&
+        expectedOutputKind !== "refusal") {
+        throw new TypeError(`${field} independent_transport accounting is supported only for refusal steps`);
+    }
+    const requiredFields = readTranscriptStringArray(value.required_fields, `${field}.required_fields`);
+    if (requiredFields.some((requiredField) => requiredField.split(".").some((segment) => segment.length === 0))) {
+        throw new TypeError(`${field}.required_fields must contain dot-separated own-property paths`);
+    }
+    const expectedFieldValues = readExpectedFieldValues(value.expected_field_values, `${field}.expected_field_values`);
+    const expectedErrorCode = readOptionalTranscriptString(value.expected_error_code, `${field}.expected_error_code`);
+    const expectedRefusalSurface = readOptionalTranscriptString(value.expected_refusal_surface, `${field}.expected_refusal_surface`);
+    const recoveryFor = readOptionalTranscriptString(value.recovery_for, `${field}.recovery_for`);
+    assertTranscriptStepOutputContract(field, args, expectedExitCode, expectedOutputKind, expectedErrorCode, expectedRefusalSurface);
+    return {
+        id,
+        args,
+        expected_exit_code: expectedExitCode,
+        expected_output_kind: expectedOutputKind,
+        expected_accounting_mode: expectedAccountingMode,
+        required_fields: requiredFields,
+        ...(expectedFieldValues
+            ? { expected_field_values: expectedFieldValues }
+            : {}),
+        ...(expectedErrorCode ? { expected_error_code: expectedErrorCode } : {}),
+        ...(expectedRefusalSurface
+            ? { expected_refusal_surface: expectedRefusalSurface }
+            : {}),
+        ...(recoveryFor ? { recovery_for: recoveryFor } : {}),
+    };
+}
+function parseAgentTaskTranscript(value, index) {
+    if (!isRecord(value)) {
+        throw new TypeError(`tasks[${String(index)}] must be an object`);
+    }
+    const id = readTranscriptString(value.id, `tasks[${String(index)}].id`);
+    const description = readTranscriptString(value.description, `tasks.${id}.description`);
+    if (!Array.isArray(value.steps) || value.steps.length === 0) {
+        throw new TypeError(`tasks.${id}.steps must be a non-empty array`);
+    }
+    const steps = value.steps.map((step, stepIndex) => parseAgentTaskTranscriptStep(step, id, stepIndex));
+    const priorSteps = new Map();
+    for (const step of steps) {
+        if (priorSteps.has(step.id)) {
+            throw new TypeError(`tasks.${id} contains duplicate step id ${step.id}`);
+        }
+        if (step.recovery_for !== undefined) {
+            const refusal = priorSteps.get(step.recovery_for);
+            if (refusal?.expected_output_kind !== "refusal" ||
+                step.expected_output_kind === "refusal") {
+                throw new TypeError(`tasks.${id}.${step.id} recovery_for must reference an earlier refusal and declare successful output`);
+            }
+        }
+        priorSteps.set(step.id, step);
+    }
+    if (steps.at(-1)?.expected_output_kind === "refusal") {
+        throw new TypeError(`tasks.${id} completed task must terminate with successful output`);
+    }
+    for (const step of steps) {
+        if (step.expected_output_kind === "refusal" &&
+            !steps.some((candidate) => candidate.recovery_for === step.id)) {
+            throw new TypeError(`tasks.${id}.${step.id} refusal must have a later successful recovery_for step`);
+        }
+    }
+    return { id, description, steps };
+}
+/** Parse and fail closed on malformed or internally inconsistent transcripts. */
+export function parsePmAgentTaskTranscriptCorpus(value) {
+    if (!isRecord(value)) {
+        throw new TypeError("agent-task transcript corpus must be an object");
+    }
+    if (value.version !== PM_AGENT_TASK_TRANSCRIPT_VERSION) {
+        throw new TypeError(`agent-task transcript corpus version must be ${String(PM_AGENT_TASK_TRANSCRIPT_VERSION)}`);
+    }
+    if (!Array.isArray(value.tasks) || value.tasks.length === 0) {
+        throw new TypeError("agent-task transcript corpus tasks must be non-empty");
+    }
+    const tasks = value.tasks.map((task, index) => parseAgentTaskTranscript(task, index));
+    const taskIds = new Set();
+    for (const task of tasks) {
+        if (taskIds.has(task.id)) {
+            throw new TypeError(`duplicate agent-task transcript id ${task.id}`);
+        }
+        taskIds.add(task.id);
+    }
+    return { version: PM_AGENT_TASK_TRANSCRIPT_VERSION, tasks };
+}
+//# sourceMappingURL=task-transcript-contracts.js.map
+//# debugId=006109f8-cb09-5a91-8929-7ac7521753b6

package/dist/sdk/annotations.d.ts

@@ -25,6 +25,8 @@ export interface AnnotationCommandOptions {
     includeMeta?: boolean;
     /** Return the complete collection after a mutation instead of the bounded mutation receipt. */
     fullHistory?: boolean;
+    /** Append only when no entry has the same resolved author and text. */
+    ifAbsent?: boolean;
 }
 /** Identifies the single annotation mutation represented by a bounded response. */
 export interface AnnotationMutationReceipt {
@@ -32,8 +34,8 @@ export interface AnnotationMutationReceipt {
     action: "add" | "edit" | "delete";
     /** Stable one-based collection position targeted by the mutation. */
     entry_index: number;
-    /** Number of stored entries changed by the mutation. */
-    changed_count: 1;
+    /** Number of stored entries changed by the mutation attempt. */
+    changed_count: 0 | 1;
     /** Whether the response includes the complete post-mutation collection. */
     full_history_included: boolean;
 }
@@ -133,6 +135,7 @@ export type AnnotationCommandResult<TKey extends string, TEntry extends Annotati
     limit?: number;
     mutation_receipt?: AnnotationMutationReceipt;
     omission_receipt?: AnnotationOmissionReceipt;
+    changed?: boolean;
 };
 /** Implements limit annotation entries for the public runtime surface of this module. */
 export declare function limitAnnotationEntries<TEntry>(values: TEntry[], limit: number | undefined): TEntry[];