@unbrained/pm-cli 2026.9.3 → 2026.9.4

package/dist/core/lock/lock.js

@@ -4,8 +4,9 @@
  * Coordinates tracker lock ownership and cleanup for Lock.
  */
 
-!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]="7352375d-55f2-5751-934e-ba0cd5c358d5")}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]="b21a63b8-9da9-5c7c-b288-3a2dae342bef")}catch(e){}}();
 import { isFileMissingError } from "../fs/fs-utils.js";
+import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -95,6 +96,43 @@ function isErrno(error, code) {
         "code" in error &&
         error.code === code);
 }
+/**
+ * Classify exclusive-create failures that prove another lock lifecycle is in
+ * flight. Windows can report `EPERM`, `EACCES`, or `EBUSY` while a just-unlinked
+ * lock is still delete-pending; treating those as fatal makes bounded lock
+ * waiting fail nondeterministically. Existing paths are contention on every
+ * host. A missing or temporarily unstatable Windows path is contention only
+ * when its parent remains writable, preserving genuine permission failures.
+ */
+async function isLockCreateContention(error, lockPath, platform = process.platform) {
+    if (isErrno(error, "EEXIST"))
+        return true;
+    if (!isErrno(error, "EPERM") &&
+        !isErrno(error, "EACCES") &&
+        !isErrno(error, "EBUSY")) {
+        return false;
+    }
+    try {
+        await fs.lstat(lockPath);
+        return true;
+    }
+    catch (probeError) {
+        if (platform !== "win32" ||
+            (!isFileMissingError(probeError) &&
+                !isErrno(probeError, "EPERM") &&
+                !isErrno(probeError, "EACCES") &&
+                !isErrno(probeError, "EBUSY"))) {
+            return false;
+        }
+    }
+    try {
+        await fs.access(path.dirname(lockPath), fsConstants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function emitLockWriteHook(lockPath, op) {
     await runActiveOnWriteHooks({
         path: lockPath,
@@ -464,6 +502,7 @@ export const _testOnly = {
     parseLockInfo,
     readLockInfo,
     isErrno,
+    isLockCreateContention,
     buildLockPayload,
     isStaleLock,
     lockOwnerSuffix,
@@ -515,7 +554,7 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
             };
         }
         catch (error) {
-            if (!isErrno(error, "EEXIST")) {
+            if (!(await isLockCreateContention(error, lockPath))) {
                 throw new PmCliError(`Failed to acquire lock for ${id}: ${toErrorMessage(error)}`, EXIT_CODE.GENERIC_FAILURE);
             }
             let lockInfo = await readLockInfo(lockPath);
@@ -549,4 +588,4 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
     }
 }
 //# sourceMappingURL=lock.js.map
-//# debugId=7352375d-55f2-5751-934e-ba0cd5c358d5
+//# debugId=b21a63b8-9da9-5c7c-b288-3a2dae342bef

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

@@ -26,7 +26,7 @@ export interface AgentProvenanceObservation {
  */
 export type AgentProvenance = Readonly<Record<string, AgentProvenanceObservation | null>>;
 /** Bounded reason explaining why one declared provenance dimension was absent. */
-export type AgentProvenanceAbsenceReason = "harness_unavailable" | "resolver_failed" | "resolver_not_configured" | "probes_disabled" | "invalid_value";
+export type AgentProvenanceAbsenceReason = "harness_unavailable" | "resolver_input_missing" | "resolver_failed" | "resolver_not_configured" | "probes_disabled" | "invalid_value";
 /** Machine-readable resolution outcome for one provenance dimension. */
 export interface AgentProvenanceOutcome {
     /** Whether the dimension resolved without retaining private source material. */
@@ -168,6 +168,8 @@ export interface HarnessDetectionSignals {
     cwd?: string;
     /** Home directory override used by embedders and isolated tests. */
     home_dir?: string;
+    /** Explicit harness-owned session file supplied by an embedding host. */
+    session_file?: string;
 }
 /** Built-in agent descriptors evaluated before package and workspace additions. */
 export declare const BUILTIN_HARNESS_SIGNAL_DESCRIPTORS: readonly HarnessSignalDescriptor[];

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]="cf550961-0040-5e04-9d8d-16e316027e43")}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]="dfbf4eb8-1f02-5880-a70a-0e7ed9b9784a")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
@@ -12,6 +12,7 @@ import os from "node:os";
 import path from "node:path";
 import { resolveAgentSessionContextFromSignals, } from "./agent-session-context.js";
 import { readAgentSemanticAttributionSync, } from "../session/session-state.js";
+import { isFileAbsentError } from "../fs/fs-utils.js";
 /** Stable built-in provenance dimensions understood by the default runtime. */
 export const AGENT_PROVENANCE_DIMENSIONS = [
     "model",
@@ -357,18 +358,83 @@ function parseClaudeProvenanceLine(line) {
     }
     return Object.freeze({ model, version });
 }
-function readClaudeSessionProvenance(dimension, signals, env) {
+/** Classify one candidate without following symlinks or leaking filesystem detail. */
+function claudeTranscriptCandidateStatus(candidate) {
+    try {
+        return fs.lstatSync(candidate).isFile() ? "available" : "missing";
+    }
+    catch (error) {
+        return isFileAbsentError(error) ? "missing" : "failed";
+    }
+}
+/** Resolve a bounded cross-workspace Claude transcript discovery result. */
+function discoverClaudeSessionFile(projectsRoot, session) {
+    let discovered;
+    try {
+        discovered = fs
+            .readdirSync(projectsRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .slice(0, 512)
+            .map((entry) => {
+            const candidate = path.join(projectsRoot, entry.name, `${session}.jsonl`);
+            return {
+                candidate,
+                status: claudeTranscriptCandidateStatus(candidate),
+            };
+        });
+    }
+    catch (error) {
+        return { status: isFileAbsentError(error) ? "missing" : "failed" };
+    }
+    const matches = discovered
+        .filter(({ status }) => status === "available")
+        .map(({ candidate }) => candidate);
+    if (matches.length === 0) {
+        return {
+            status: discovered.some(({ status }) => status === "failed")
+                ? "failed"
+                : "missing",
+        };
+    }
+    if (matches.length > 1)
+        return { status: "ambiguous" };
+    return { status: "available", path: matches[0] };
+}
+/** Resolve one Claude transcript by stable session identity without exposing its path. */
+function resolveClaudeSessionFile(signals, env) {
     const session = nonBlank(env.CLAUDE_CODE_SESSION_ID);
-    if (!session || !/^[A-Za-z0-9_-]{1,128}$/u.test(session))
-        return undefined;
+    if (!session || !/^[A-Za-z0-9_-]{1,128}$/u.test(session)) {
+        return { status: "unavailable" };
+    }
     const workspace = path.resolve(signals.cwd ?? process.cwd());
     const encodedWorkspace = workspace.replaceAll(/[^A-Za-z0-9-]/gu, "-");
-    const sessionPath = path.join(signals.home_dir ?? os.homedir(), ".claude", "projects", encodedWorkspace, `${session}.jsonl`);
+    const projectsRoot = path.join(signals.home_dir ?? os.homedir(), ".claude", "projects");
+    const directPath = path.join(projectsRoot, encodedWorkspace, `${session}.jsonl`);
+    const explicitPath = nonBlank(signals.session_file);
+    const suppliedPath = explicitPath && path.basename(explicitPath) === `${session}.jsonl`
+        ? explicitPath
+        : undefined;
+    for (const candidate of [suppliedPath, directPath]) {
+        if (!candidate)
+            continue;
+        const status = claudeTranscriptCandidateStatus(candidate);
+        if (status === "available")
+            return { status, path: candidate };
+        if (status === "failed")
+            return { status };
+    }
+    return discoverClaudeSessionFile(projectsRoot, session);
+}
+function readClaudeSessionProvenance(dimension, signals, env) {
+    const resolution = resolveClaudeSessionFile(signals, env);
+    if (resolution.status !== "available")
+        return undefined;
     try {
-        const file = fs.openSync(sessionPath, "r");
+        const file = fs.openSync(resolution.path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
         try {
             const stats = fs.fstatSync(file);
-            const cacheKey = `${sessionPath}\u0000${stats.size}\u0000${stats.mtimeMs}`;
+            const cacheKey = `${resolution.path}\u0000${stats.size}\u0000${stats.mtimeMs}`;
             const cached = claudeProvenanceSnapshotCache.get(cacheKey);
             if (cached)
                 return cached[dimension];
@@ -553,14 +619,20 @@ function resolveProvenanceProbe(dimension, signals, env, descriptor) {
     }
     return undefined;
 }
-function provenanceResolverHasInput(resolver, descriptor, env) {
+function provenanceResolverHasInput(resolver, descriptor, signals, env) {
     if (resolver === "ai_agent_version") {
         const value = nonBlank(env.AI_AGENT);
-        return (value !== undefined && literalSignalMatches(value, descriptor.harness));
+        return value !== undefined &&
+            literalSignalMatches(value, descriptor.harness)
+            ? "available"
+            : "unavailable";
+    }
+    if (resolver === "codex_session_file") {
+        return nonBlank(env.CODEX_THREAD_ID) !== undefined
+            ? "available"
+            : "unavailable";
     }
-    return resolver === "codex_session_file"
-        ? nonBlank(env.CODEX_THREAD_ID) !== undefined
-        : nonBlank(env.CLAUDE_CODE_SESSION_ID) !== undefined;
+    return resolveClaudeSessionFile(signals, env).status;
 }
 function effectiveHarnessDetectionSignals(signals) {
     if (signals)
@@ -907,7 +979,17 @@ export function detectAgentIdentity(signals) {
     ];
     return Object.fromEntries(entries.filter((entry) => entry[1] !== undefined));
 }
-function resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEnabled, invalidValue) {
+/** Classify one configured resolver's privacy-safe absence outcome. */
+function provenanceResolverAbsence(resolverInput) {
+    if (resolverInput === "unavailable") {
+        return { status: "unavailable", reason: "harness_unavailable" };
+    }
+    if (resolverInput === "missing") {
+        return { status: "unavailable", reason: "resolver_input_missing" };
+    }
+    return { status: "failed", reason: "resolver_failed" };
+}
+function resolveProvenanceOutcome(dimension, identity, descriptor, signals, env, probesEnabled, invalidValue) {
     const resolver = descriptor?.provenance_resolvers[dimension];
     if (identity.provenance?.[dimension]) {
         return {
@@ -924,14 +1006,20 @@ function resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEn
         };
     }
     if (resolver) {
-        const resolverHasInput = provenanceResolverHasInput(resolver, descriptor, env);
-        const status = resolverHasInput && probesEnabled ? "failed" : "unavailable";
-        const reason = !resolverHasInput
-            ? "harness_unavailable"
-            : probesEnabled
-                ? "resolver_failed"
-                : "probes_disabled";
-        return { status, reason, resolver, rule_version: "v1" };
+        if (!probesEnabled) {
+            return {
+                status: "unavailable",
+                reason: "probes_disabled",
+                resolver,
+                rule_version: "v1",
+            };
+        }
+        const resolverInput = provenanceResolverHasInput(resolver, descriptor, signals, env);
+        return {
+            ...provenanceResolverAbsence(resolverInput),
+            resolver,
+            rule_version: "v1",
+        };
     }
     return {
         status: descriptor?.provenance_unavailable_dimensions.includes(dimension)
@@ -972,7 +1060,7 @@ export function diagnoseAgentIdentity(signals) {
     });
     const outcomes = Object.fromEntries(AGENT_PROVENANCE_DIMENSIONS.map((dimension) => [
         dimension,
-        resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEnabled, dimension === "role" && invalidRoleValue),
+        resolveProvenanceOutcome(dimension, identity, descriptor, effectiveSignals, env, probesEnabled, dimension === "role" && invalidRoleValue),
     ]));
     return { ...identity, provenance_outcomes: outcomes };
 }
@@ -1082,4 +1170,4 @@ export function resolveAuthor(candidate, fallback) {
     return identity.author;
 }
 //# sourceMappingURL=author.js.map
-//# debugId=cf550961-0040-5e04-9d8d-16e316027e43
+//# debugId=dfbf4eb8-1f02-5880-a70a-0e7ed9b9784a

package/dist/sdk/environment/agent-environment.d.ts

@@ -0,0 +1,296 @@
+import { type WorkspaceRecipe } from "../workspace-recipe.js";
+/** Schema identifier for a portable observation contract. */
+export declare const PM_OBSERVATION_SCHEMA: "pm.agent-observation/v1";
+/** Schema identifier for a deterministic verdict contract. */
+export declare const PM_VERDICT_SCHEMA: "pm.agent-verdict/v1";
+/** Schema identifier for a bounded agent-environment episode. */
+export declare const PM_EPISODE_SCHEMA: "pm.agent-episode/v1";
+/** A JSON-compatible object used as immutable recorded workspace state. */
+export type RecordedStateObject = Readonly<Record<string, unknown>>;
+/** One declared read and its guaranteed token ceiling. */
+export interface ObservationReadDeclaration {
+    /** Public SDK or CLI command name used to collect the read. */
+    command: string;
+    /** Maximum tokens this read may consume. */
+    budget_tokens: number;
+}
+/** Emitted-byte calibration for a representative observation corpus. */
+export interface ObservationCalibration {
+    /** Stable measurement basis; serialized payload bytes are authoritative. */
+    basis: "emitted_bytes";
+    /** Historical emitted-byte measurements used to calibrate expectations. */
+    samples: readonly number[];
+    /** Expected serialized payload size before an observation is served. */
+    expected_emitted_bytes: number;
+    /** Accepted drift around the expected emitted-byte measurement. */
+    tolerance_bytes: number;
+}
+/** Declares whether observation cost varies with corpus size. */
+export type ObservationCorpusDependence = {
+    readonly kind: "independent";
+} | {
+    readonly kind: "bounded";
+    readonly dimension: string;
+    readonly maximum: number;
+};
+/** One ordered disclosure tier in an observation degradation ladder. */
+export interface ObservationTier {
+    /** Stable tier identity included in every observation receipt. */
+    id: string;
+    /** Maximum tokens this tier is permitted to emit. */
+    max_tokens: number;
+    /** Dot-separated recorded-state fields disclosed by the tier. */
+    fields: readonly string[];
+}
+/** Portable declaration for a bounded, calibrated observation. */
+export interface ObservationContract {
+    /** Versioned schema identity. */
+    schema: typeof PM_OBSERVATION_SCHEMA;
+    /** Stable contract identity. */
+    id: string;
+    /** Positive contract revision. */
+    version: number;
+    /** Reads whose ceilings form the guaranteed collection cost. */
+    reads: readonly ObservationReadDeclaration[];
+    /** Emitted-byte calibration visible before collection starts. */
+    calibration: ObservationCalibration;
+    /** Explicit corpus-size dependence of the cost model. */
+    corpus_dependence: ObservationCorpusDependence;
+    /** Ordered richest-to-smallest degradation ladder. */
+    tiers: readonly ObservationTier[];
+}
+/** Pre-call observation-cost description available to schedulers. */
+export interface ObservationCostDescription {
+    /** Stable observation identity. */
+    contract_id: string;
+    /** Observation revision. */
+    contract_version: number;
+    /** Sum of all declared collection ceilings. */
+    guaranteed_ceiling_tokens: number;
+    /** Calibrated expected serialized payload size. */
+    expected_emitted_bytes: number;
+    /** Conservative token estimate derived from emitted bytes. */
+    expected_tokens: number;
+    /** Accepted emitted-byte calibration drift. */
+    tolerance_bytes: number;
+    /** Stable calibration basis. */
+    calibration_basis: "emitted_bytes";
+    /** Declared corpus-size dependence. */
+    corpus_dependence: ObservationCorpusDependence;
+}
+/** Audit receipt emitted for every served or refused observation. */
+export interface ObservationReceipt {
+    /** Stable observation identity. */
+    contract_id: string;
+    /** Observation revision. */
+    contract_version: number;
+    /** Tier whose payload was returned, or null after truthful refusal. */
+    served_tier: string | null;
+    /** Whether a smaller tier was attempted or served. */
+    degraded: boolean;
+    /** Tier identities evaluated in deterministic order. */
+    attempted_tiers: readonly string[];
+    /** Exact serialized payload bytes, or null when nothing was served. */
+    emitted_bytes: number | null;
+    /** Conservative token estimate, or null when nothing was served. */
+    estimated_tokens: number | null;
+    /** Stable measurement basis. */
+    calibration_basis: "emitted_bytes";
+}
+/** Successful bounded observation with its explicit receipt. */
+export interface ServedObservation<T> {
+    /** Discriminator for a payload-bearing response. */
+    status: "served";
+    /** Payload produced by the declared tier. */
+    payload: T;
+    /** Cost and degradation evidence. */
+    receipt: ObservationReceipt;
+}
+/** Refusal returned when no declared tier can fit the caller's ceiling. */
+export interface RefusedObservation {
+    /** Discriminator for a payload-free refusal. */
+    status: "refused";
+    /** Stable reason callers can route without parsing prose. */
+    reason: "no_declared_tier_fits_budget";
+    /** Cost and degradation evidence. */
+    receipt: ObservationReceipt;
+}
+/** Complete outcome of attempting one declared observation. */
+export type ObservationResult<T> = ServedObservation<T> | RefusedObservation;
+/** Caller-imposed ceiling for one observation response. */
+export interface ObservationRequest {
+    /** Maximum response tokens accepted by the caller. */
+    budget_tokens: number;
+}
+/** Predicate supported by the versioned total-verdict interpreter. */
+export type VerdictPredicate = {
+    readonly id: string;
+    readonly kind: "field_equals";
+    readonly path: string;
+    readonly expected: unknown;
+} | {
+    readonly id: string;
+    readonly kind: "field_present";
+    readonly path: string;
+} | {
+    readonly id: string;
+    readonly kind: "field_absent";
+    readonly path: string;
+};
+/** Declarative composition applied to predicate outcomes. */
+export interface VerdictComposition {
+    /** Whether every or at least one referenced predicate must satisfy. */
+    operator: "all" | "any";
+    /** Ordered predicate identities evaluated by the total verdict. */
+    predicate_ids: readonly string[];
+}
+/** Portable named and versioned total-verdict declaration. */
+export interface VerdictContract {
+    /** Versioned schema identity. */
+    schema: typeof PM_VERDICT_SCHEMA;
+    /** Stable contract identity. */
+    id: string;
+    /** Positive contract revision. */
+    version: number;
+    /** Predicates evaluated exclusively over recorded state. */
+    predicates: readonly VerdictPredicate[];
+    /** Explicit deterministic predicate composition. */
+    composition: VerdictComposition;
+}
+/** Recorded state and stable snapshot identity supplied by an adapter. */
+export interface WorkspaceRecordedState {
+    /** Stable identity of the exact state being evaluated. */
+    snapshot_id: string;
+    /** Recorded, JSON-compatible project state. */
+    state: RecordedStateObject;
+}
+/** Per-predicate evidence in a deterministic total verdict. */
+export interface PredicateVerdict {
+    /** Declared predicate identity. */
+    id: string;
+    /** Whether the predicate is satisfied by recorded state. */
+    outcome: "satisfied" | "violated";
+    /** Snapshot-qualified JSON pointer to the inspected field. */
+    evidence_pointer: string;
+    /** Hash of the observed value without duplicating potentially private data. */
+    evidence_digest: string;
+}
+/** Total, reproducible result produced by a verdict contract. */
+export interface VerdictResult {
+    /** Stable verdict identity. */
+    contract_id: string;
+    /** Verdict revision. */
+    contract_version: number;
+    /** Exact recorded-state snapshot evaluated. */
+    snapshot_id: string;
+    /** Total outcome, including an explicit empty-contract state. */
+    outcome: "satisfied" | "violated" | "not_applicable";
+    /** Satisfied fraction, or null when no predicates are declared. */
+    score: number | null;
+    /** Explicitly separates evaluation from reward or learning signals. */
+    policy: "verdict_only_no_reward";
+    /** Stable explanation for a not-applicable verdict. */
+    reason?: "no_predicates_declared";
+    /** Ordered predicate evidence. */
+    predicates: readonly PredicateVerdict[];
+}
+/** Hard limits enforced within one isolated episode. */
+export interface EpisodeLimits {
+    /** Maximum ordinary project-management actions. */
+    max_actions: number;
+    /** Maximum observations, including the close-time grading read. */
+    max_observations: number;
+    /** Per-observation response ceiling. */
+    max_tokens_per_observation: number;
+}
+/** Portable specification shared by evaluation and training harnesses. */
+export interface EpisodeSpecification {
+    /** Versioned schema identity. */
+    schema: typeof PM_EPISODE_SCHEMA;
+    /** Stable episode identity and session provenance key. */
+    id: string;
+    /** Positive episode revision. */
+    version: number;
+    /** Consumer intent without coupling the runtime to a training framework. */
+    mode: "benchmark" | "evaluation" | "training" | "scale_transfer";
+    /** Deterministic workspace construction recipe. */
+    recipe: WorkspaceRecipe;
+    /** Canonical pm items that define the task set. */
+    task_item_ids: readonly string[];
+    /** State fields that observations may disclose. */
+    observable_fields: readonly string[];
+    /** Grading-only fields that must never enter observations. */
+    withheld_fields: readonly string[];
+    /** Bounded observation declaration. */
+    observation: ObservationContract;
+    /** Recorded-state verdict declaration. */
+    verdict: VerdictContract;
+    /** Hard action and observation limits. */
+    limits: EpisodeLimits;
+}
+/** Reset receipt returned by an episode adapter. */
+export interface EpisodeResetReceipt {
+    /** Adapter-defined isolated workspace identity. */
+    workspace_id: string;
+    /** Stable state identity after reset. */
+    state_id: string;
+}
+/** Action receipt returned by an episode adapter. */
+export interface EpisodeActionReceipt<TOutput> {
+    /** Stable state identity after the action. */
+    state_id: string;
+    /** Adapter-defined ordinary command result. */
+    output: TOutput;
+}
+/** Host boundary for ordinary pm SDK actions and recorded-state reads. */
+export interface EpisodeRuntimeAdapter<TAction, TOutput = unknown> {
+    /** Construct a fresh isolated workspace using the declared recipe. */
+    reset(recipe: WorkspaceRecipe): Promise<EpisodeResetReceipt>;
+    /** Execute one ordinary action, normally by calling `PmClient.run`. */
+    execute(action: TAction): Promise<EpisodeActionReceipt<TOutput>>;
+    /** Read immutable grading state from the workspace system of record. */
+    readRecordedState(): Promise<WorkspaceRecordedState>;
+}
+/** One deterministic entry in a portable episode trajectory. */
+export interface EpisodeTrajectoryEntry {
+    /** Monotonic event number within the isolated episode. */
+    sequence: number;
+    /** Stable event classification. */
+    kind: "reset" | "observation" | "action" | "verdict" | "close";
+    /** Snapshot, state, or observation tier associated with the event. */
+    state_id: string;
+}
+/** Closed episode evidence without reward or framework-specific shaping. */
+export interface ClosedEpisode {
+    /** Deterministic total verdict. */
+    verdict: VerdictResult;
+    /** Complete bounded trajectory. */
+    trajectory: readonly EpisodeTrajectoryEntry[];
+    /** Explicitly absent to prevent verdicts from becoming reward signals. */
+    reward?: never;
+}
+/** Isolated runtime returned for one declared agent episode. */
+export interface PmEpisodeSession<TAction, TOutput> {
+    /** Observe recorded state through the declared disclosure ladder. */
+    observe(): Promise<ObservationResult<RecordedStateObject>>;
+    /** Execute one bounded ordinary project-management action. */
+    step(action: TAction): Promise<EpisodeActionReceipt<TOutput>>;
+    /** Evaluate the current recorded state without closing the session. */
+    score(): Promise<VerdictResult>;
+    /** Evaluate and close the episode, returning immutable evidence. */
+    close(): Promise<ClosedEpisode>;
+}
+/** Validate, clone, and freeze a portable observation declaration. */
+export declare function defineObservationContract(declaration: ObservationContract): ObservationContract;
+/** Describe guaranteed and calibrated observation cost before collection. */
+export declare function describeObservationCost(contract: ObservationContract): ObservationCostDescription;
+/** Serve the richest declared tier that fits both caller and tier ceilings. */
+export declare function serveDeclaredObservation<T>(contract: ObservationContract, collect: (tier: ObservationTier) => Promise<T>, request: ObservationRequest): Promise<ObservationResult<T>>;
+/** Validate, clone, and freeze a portable total-verdict declaration. */
+export declare function defineVerdictContract(declaration: VerdictContract): VerdictContract;
+/** Evaluate a total verdict exclusively from one immutable recorded snapshot. */
+export declare function evaluateVerdictContract(contract: VerdictContract, recorded: WorkspaceRecordedState): VerdictResult;
+/** Validate, clone, and freeze a portable episode specification. */
+export declare function defineEpisodeSpecification(declaration: EpisodeSpecification): EpisodeSpecification;
+/** Open one isolated, deterministic episode around an adapter's ordinary actions. */
+export declare function openPmEpisode<TAction, TOutput = unknown>(specification: EpisodeSpecification, adapter: EpisodeRuntimeAdapter<TAction, TOutput>): Promise<PmEpisodeSession<TAction, TOutput>>;