@mnemom/mnemom 0.17.34-next.1 → 0.17.34-next.3

package/dist/vendor/shared/durable-contract/constants.js

@@ -0,0 +1,179 @@
+// GENERATED from shared/durable-contract/src/constants.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * Every frozen durable constant (BACKBONE "Pieces / S1", amendments 33-50). A spec or piece cites
+ * these by name and never restates a different value. The values the backbone left to "the S1
+ * freeze record" are chosen here; each carries its reason. `freeze-record.ts` copies them into
+ * the JSON record the eval runner reads as `$S1.<NAME>`.
+ */
+/** The contract version of this package. Any change to FREEZE.json bumps it. */
+export const DURABLE_CONTRACT_VERSION = "1.0.0";
+/**
+ * `durable_schema_version()` must return exactly this. A mismatch makes the entitlement `durable`
+ * field absent and a claim answers 503 durable_claim_unavailable {cause:"schema"} (A3).
+ */
+export const DURABLE_SCHEMA_VERSION = 1;
+// ---- Lease clock (DB settings with these prod defaults; not TEST_MODE seams) ----------------
+/** durable_cell_state.lease_seconds default, CHECK LEASE_SECONDS_MIN..LEASE_SECONDS_MAX. */
+export const LEASE_SECONDS_DEFAULT = 90;
+export const LEASE_SECONDS_MIN = 5;
+export const LEASE_SECONDS_MAX = 90;
+/** durable_cell_state.resume_reset_seconds default, CHECK RESUME_RESET_SECONDS_MIN..MAX. */
+export const RESUME_RESET_SECONDS_DEFAULT = 600;
+export const RESUME_RESET_SECONDS_MIN = 5;
+export const RESUME_RESET_SECONDS_MAX = 600;
+/** Heartbeat period = lease_seconds / HEARTBEAT_DIVISOR (30 s at 90, 2 s at 6). */
+export const HEARTBEAT_DIVISOR = 3;
+/** resume_failures at which a session goes to suspended(respawn_failed). */
+export const RESPAWN_FAILURES_SUSPEND_AT = 3;
+/** Seats the daemon respawns at once. */
+export const RESPAWN_CONCURRENCY = 4;
+// ---- Gateway --------------------------------------------------------------------------------
+/** resolve_durable_session_key touches last_used_at only when NULL or older than this (DB clock). */
+export const LEASE_KEY_TOUCH_SECONDS = 60;
+/** M1 has no stale serve: every resolver fault is 503 durable_admission_unavailable (I20). */
+export const STALE_SERVE_M1 = false;
+/** M1 honours DURABLE_ADMIT, but only for the exact bytes NOFENCE_ADMIT_VALUE (r3 I01). */
+export const NOFENCE_M1 = true;
+export const NOFENCE_ADMIT_VALUE = "nofence";
+/** Upper bound for one resolver RPC; past it the gateway answers 503 (C06-R07 "timeout T"). */
+export const RESOLVER_TIMEOUT_MS = 2000;
+// ---- API executor plane ---------------------------------------------------------------------
+/** Claim-time arm probe (GET /internal/durable/arm at the home cell) must answer within this. */
+export const ARM_PROBE_TIMEOUT_MS = 2000;
+/** A parseable arm probe answer is cached at most this long. */
+export const ARM_PROBE_TTL_S = 10;
+/** Check 12: a `protected` answer is cached per (repo, branch) this long. */
+export const PROTECTION_CACHE_S = 300;
+/** Executor grant: renewal sets grant_expires_at = now() + GRANT_TTL_S. */
+export const GRANT_TTL_S = 30 * 24 * 3600;
+/** sessions, show and host status warn in the last GRANT_WARNING_S of the grant. */
+export const GRANT_WARNING_S = 7.5 * 24 * 3600;
+/** Clean seat exits (exit 0 after an accepted hello) beyond CLEAN_EXIT_MAX in the window count as failures. */
+export const CLEAN_EXIT_MAX = 3;
+export const CLEAN_EXIT_WINDOW_S = 600;
+// ---- Host daemon ----------------------------------------------------------------------------
+/** The daemon polls GET /v1/executor/sessions every EXECUTOR_POLL_S. */
+export const EXECUTOR_POLL_S = 10;
+/** An executor whose last_seen_at is older than this is not live. */
+export const EXECUTOR_LIVE_S = 3 * EXECUTOR_POLL_S;
+/** Claim backoff on 503 durable_claim_unavailable: CLAIM_BACKOFF_BASE_S doubling to CLAIM_BACKOFF_MAX_S. */
+export const CLAIM_BACKOFF_BASE_S = 2;
+export const CLAIM_BACKOFF_MAX_S = 60;
+/** Each backoff delay is stretched by a factor in [1, 1 + CLAIM_BACKOFF_JITTER). */
+export const CLAIM_BACKOFF_JITTER = 0.2;
+/** host status prints the guard fix after more than this many consecutive `guard` unavailable claims. */
+export const CLAIM_UNAVAILABLE_SURFACE_N = 5;
+/** SIGTERM to SIGKILL grace when done/kill stops a local tracked claude (final F04). */
+export const TRACKED_STOP_GRACE_S = 5;
+// ---- Seat / credential proxy ----------------------------------------------------------------
+/**
+ * Upstream attempts one typed turn may produce on a non-retryable refusal (C13-R14). Expected 1;
+ * PROVISIONAL until the day-1 spike with claude 2.1.285 records the real number.
+ */
+export const SEAT_MAX_ATTEMPTS_NONRETRY = 1;
+/** A synced main request waits up to TURN_WAIT_MS for its prompt (= cli/src/turn-origin.mjs WAIT_MS on origin/main). */
+export const TURN_WAIT_MS = 500;
+/** x-mnemom-turn limits, equal to gateway/src/goal-turn-claims.ts. */
+export const TURN_HEADER_MAX_LEN = 8192;
+export const TURN_ENTRIES_MAX = 32;
+// ---- Sweep (C20-R12) ------------------------------------------------------------------------
+/** One global row cap across all categories per run. */
+export const SWEEP_MAX_ROWS = 200;
+/** Rows per batch; SWEEP_BATCH_SIZE < SWEEP_MAX_ROWS. */
+export const SWEEP_BATCH_SIZE = 50;
+/** Time budget T per run. */
+export const SWEEP_TIME_BUDGET_MS = 10000;
+export const SWEEP_CRON = "*/5 * * * *";
+// ---- Budget, contract, journal --------------------------------------------------------------
+/**
+ * The per-session budget limit in USD, code-fixed and conservative (owner Q2). The single source
+ * for the amend bound, the 422 and the gateway 429; durable_org_policy.limits is seeded from it
+ * and not read in M1 (parity test: seed == constant).
+ */
+export const PER_SESSION_BUDGET_LIMIT_USD = 20;
+/** durable_org_policy.limits seed, built from the constant above. */
+export const ORG_POLICY_LIMITS_SEED = Object.freeze({
+    per_session_budget_usd: PER_SESSION_BUDGET_LIMIT_USD,
+});
+/** The API's frozen contract statement limit (= gateway goal-contract STATEMENT_MAX). */
+export const CONTRACT_STATEMENT_MAX_CHARS = 4000;
+/** canonicalJson of the whole contract plaintext (= gateway goal-contract CONTRACT_JSON_MAX). */
+export const CONTRACT_JSON_MAX_BYTES = 8192;
+/** agent_session_events.detail is server-generated and at most this many characters. */
+export const EVENT_DETAIL_MAX_CHARS = 280;
+/** contract_ciphertext is purged this long after the session ends. */
+export const CONTRACT_PURGE_AFTER_S = 30 * 24 * 3600;
+// ---- Device step (A4) -----------------------------------------------------------------------
+/** owner_mutation needs aal2 and a step-up no older than this. */
+export const DEVICE_STEP_FRESHNESS_S = 300;
+/**
+ * The cookie SessionBlob key holding the step-up time, integer unix seconds, optional (ruling 27;
+ * C16-R10). Fresh when 0 <= now - su <= DEVICE_STEP_FRESHNESS_S; an absent or future su is stale.
+ * Separate from `ia`: a step-up renews freshness without extending the session's lifetime.
+ */
+export const STEP_UP_BLOB_FIELD = "su";
+/** An owner_mutation approval expires with its device code (= api DEVICE_CODE_TTL_SECONDS). */
+export const OWNER_MUTATION_APPROVAL_TTL_S = 15 * 60;
+/** The CLI polls the device grant this often (= api DEVICE_POLL_INTERVAL_SECONDS). */
+export const DEVICE_POLL_INTERVAL_S = 5;
+// ---- Versions -------------------------------------------------------------------------------
+/** The laptop risk-line text version (fixlines.ts RISK_LINE_TEXT). Bump with any text change. */
+export const RISK_LINE_VERSION = 1;
+/** RISK_LINE_VERSION as the decimal text the A1 column, the page marker and the enrollment approval subject carry (ruling 32.30). */
+export const RISK_LINE_VERSION_TEXT = String(RISK_LINE_VERSION);
+/** The --settings / --mcp-config renderer version recorded in attestation.passed (spec.ts). */
+export const RENDERER_VERSION = 1;
+/** The plugin dir-hash recipe version (spec.ts pluginDirHash). */
+export const PLUGIN_HASH_RECIPE_VERSION = 1;
+/** The journal preimage version (events.ts EVENT_PREIMAGE_FIELDS). */
+export const EVENT_PREIMAGE_VERSION = 1;
+/**
+ * L_spawn, the lease every real-claude case runs at (20..90), set by ruling 34.17 (calibration):
+ * max(20, ceil(3 x p100 claim-to-hello)) s, capped at 90, with p100 the maximum over the clean
+ * calibration runs (2.616 s, run42), so max(20, 8) = 20. Re-derived only by a new calibration ruling.
+ */
+export const L_SPAWN = 20;
+export const L_SPAWN_MIN = 20;
+export const L_SPAWN_MAX = 90;
+/**
+ * T_hello, the calibrated per-seat spawn-to-hello time in seconds (C12-R31 recovery bound), set by
+ * the same ruling 34.17 calibration as L_SPAWN: p100 claim-to-hello at 4
+ * concurrent respawns, the maximum over the clean runs (run41 1.873, run42 2.616).
+ */
+export const T_HELLO_S = 2.616;
+/**
+ * The first-party public OAuth client an owner_mutation device code is bound to (C16-R01; wave-0
+ * fix ruling 1.12). A1 seeds it; every 202 device-step body returns it as client_id; the generic
+ * /v1/oauth/device_authorization refuses it for every scope (C16-A-032). The CLI's login client is
+ * NOT frozen: it is issued by RFC 7591 dynamic registration.
+ */
+export const OWNER_MUTATION_CLIENT_ID = "mnemom-durable-owner-mutation";
+/** ATTACH_WAIT_S = EXECUTOR_POLL_S + lease_seconds (BACKBONE). Throws outside the lease CHECK range. */
+export function attachWaitSeconds(leaseSeconds) {
+    if (!Number.isInteger(leaseSeconds) ||
+        leaseSeconds < LEASE_SECONDS_MIN ||
+        leaseSeconds > LEASE_SECONDS_MAX) {
+        throw new RangeError(`lease_seconds out of range: ${leaseSeconds}`);
+    }
+    return EXECUTOR_POLL_S + leaseSeconds;
+}
+/** ATTACH_WAIT_S at the default 90 s lease. */
+export const ATTACH_WAIT_S = EXECUTOR_POLL_S + LEASE_SECONDS_DEFAULT;
+/** Heartbeat period in seconds for a lease, derived from the server's lease. */
+export function heartbeatSeconds(leaseSeconds) {
+    return leaseSeconds / HEARTBEAT_DIVISOR;
+}
+/**
+ * Delay before claim attempt `attempt` (1-based) after consecutive 503 durable_claim_unavailable
+ * answers: CLAIM_BACKOFF_BASE_S * 2^(attempt-1), capped at CLAIM_BACKOFF_MAX_S, stretched by
+ * (1 + CLAIM_BACKOFF_JITTER * r) where r in [0, 1) is the caller's random draw. So no gap is under
+ * 2 s and none is over 60 s x (1 + CLAIM_BACKOFF_JITTER) (C12-R30).
+ */
+export function claimBackoffMs(attempt, r) {
+    if (!Number.isInteger(attempt) || attempt < 1)
+        throw new RangeError(`attempt must be >= 1: ${attempt}`);
+    if (!(r >= 0 && r < 1))
+        throw new RangeError(`r must be in [0, 1): ${r}`);
+    const base = Math.min(CLAIM_BACKOFF_BASE_S * 2 ** (attempt - 1), CLAIM_BACKOFF_MAX_S);
+    return Math.round(base * 1000 * (1 + CLAIM_BACKOFF_JITTER * r));
+}

package/dist/vendor/shared/durable-contract/doors.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The Doors amendment to M1's claim model (rulings 34.01, 34.03, 34.05, 34.05.1, 34.10, 34.12):
+ * the pool-claim flag, executor scope, the per-org live-lease cap, the dispatch constructor's
+ * names and answers, and the thin runner's (`mnemom agent run`) frozen outcome line.
+ */
+/** The api env flag that gates every pool behaviour; its value is the org allowlist. */
+export declare const DURABLE_POOL_CLAIM_FLAG = "DURABLE_POOL_CLAIM";
+/**
+ * Whether the pool claim is on for `orgId`. The flag's value is a comma-separated list of org ids
+ * (whitespace around each ignored). Unset, empty, or any malformed entry reads as off for every
+ * org: an unknown value is never a partial allowlist (Doors production safety 1).
+ */
+export declare function poolClaimEnabled(flagValue: string | undefined, orgId: string): boolean;
+/** The session facts isPoolSession reads. */
+export interface PoolSessionFacts {
+    readonly home_executor_id: string | null;
+    readonly durable_mode: string;
+    readonly org_id: string;
+}
+/**
+ * Whether a session is a pool session (rulings 34.04.1, 34.14 (3)): home_executor_id NULL, locked,
+ * and its org in the flag's allowlist. This is EffectiveStateInput.pool; the api and A1's parity
+ * test import it and never copy it. A NULL home alone (an erased executor) is never enough.
+ */
+export declare function isPoolSession(s: PoolSessionFacts, flagValue: string | undefined): boolean;
+/**
+ * The flag's org allowlist, in order with duplicates dropped; [] when the flag is off (unset, empty,
+ * or any malformed entry). The api imports this, never a copy: 34.10 (g)(3)'s p_org_ids is its
+ * answer.
+ */
+export declare function poolClaimOrgs(flagValue: string | undefined): string[];
+export declare const EXECUTOR_SCOPES: readonly ["user", "org"];
+export type ExecutorScope = (typeof EXECUTOR_SCOPES)[number];
+/** Only these executor kinds may enroll with scope org. */
+export declare const ORG_SCOPE_EXECUTOR_KINDS: readonly ["container", "fleet"];
+/** exec_oidc_exchange refusals (ruling 34.03's S1 changes). */
+export declare const OIDC_EXCHANGE_REFUSALS: readonly ["bad_issuer", "repo_not_enrolled", "ref_not_allowed", "pool_flag_off"];
+/** The audience a GitHub OIDC token must name for exec_oidc_exchange (ruling 34.12 (5)). */
+export declare const OIDC_EXCHANGE_AUDIENCE = "mnemom-executor";
+/** durable_org_policy.limits keys (34.05 (1)); live_lease_cap is optional. */
+export declare const ORG_POLICY_LIMIT_KEYS: readonly ["per_session_budget_usd", "live_lease_cap"];
+/** live_lease_cap and the registry default share this range. */
+export declare const LIVE_LEASE_CAP_MIN = 1;
+export declare const LIVE_LEASE_CAP_MAX = 1000;
+/** The org advisory lock a pool claim takes: pg_advisory_xact_lock(hashtext(prefix || org_id)). */
+export declare const ORG_CAP_LOCK_PREFIX = "durable_org_cap:";
+/** The api env var carrying the registry's dispatch.per_org_lease_cap (34.05.1 (2)). */
+export declare const DEFAULT_LEASE_CAP_ENV = "DURABLE_DEFAULT_LEASE_CAP";
+/** DURABLE_DEFAULT_LEASE_CAP as an integer, or null when absent or invalid (34.05.1 (3): fail closed). */
+export declare function parseDefaultLeaseCap(envValue: string | undefined): number | null;
+/**
+ * The effective cap of a pool claim (34.05.1 (1)): the org row's limits.live_lease_cap, else the
+ * default row's, else the registry default. Absent or NULL falls through; any present value out of
+ * range (even one that would not win), or no value at all, throws (the claim answers 503 lease_cap_config, never "no cap").
+ */
+export declare function effectiveLeaseCap(orgLimits: {
+    readonly live_lease_cap?: number | null;
+} | null, defaultRowLimits: {
+    readonly live_lease_cap?: number | null;
+} | null, defaultCap: number | null): number;
+export declare const DISPATCH_SESSION_CID_PREFIX = "dispatch-";
+export declare const DISPATCH_SESSION_NAME_PREFIX = "job-";
+export declare const CREATE_READY_SESSION_REFUSALS: readonly ["no_dispatch_agent", "seal_not_found", "cell_unmapped", "charter_mismatch"];
+export declare const CREATE_READY_SESSION_OUTCOMES: readonly ["created", "existing", "refused"];
+/** durable_create_ready_session's answer keys per outcome, closed (34.10 (g)(1)). */
+export declare const CREATE_READY_SESSION_ANSWERS: Readonly<{
+    readonly created: readonly ["outcome", "session_id"];
+    readonly existing: readonly ["outcome", "session_id"];
+    readonly refused: readonly ["outcome", "reason"];
+}>;
+/** Whether `v` is a closed answer: its outcome's keys only, a lowercase uuid session_id or a listed reason. */
+export declare function createReadySessionAnswerOk(v: unknown): boolean;
+/** conversation_id = 'dispatch-' || seal_id: 45 characters, so it passes ID_RE (34.10 (b)). */
+export declare function dispatchConversationId(sealId: string): string;
+/** name = 'job-' || the first 12 hex characters of seal_id without dashes, 16 characters (34.10 (c)). */
+export declare function dispatchSessionName(sealId: string): string;
+export declare const RUNNER_OUTCOMES: readonly ["done", "no_job", "failed", "refused"];
+export type RunnerOutcome = (typeof RUNNER_OUTCOMES)[number];
+/** The v1 outcome line's fields, in order, each always present (34.12 (8)). */
+export declare const RUNNER_OUTCOME_FIELDS: readonly ["v", "outcome", "session_id", "lease_epoch", "contract_sha256", "contract_version", "merge_strategy", "pr_url", "reason"];
+/** Exit code per outcome (34.12 (6)); usage errors and the gate exit 2. */
+export declare const RUNNER_EXIT_CODES: Readonly<{
+    readonly done: 0;
+    readonly no_job: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly refused: 3;
+}>;
+/** failed reasons besides the phase pattern RUNNER_FAILED_PHASE_RE. */
+export declare const RUNNER_FAILED_REASONS: readonly ["pr_open_failed"];
+export declare const RUNNER_FAILED_PHASE_RE: RegExp;
+/** The closed refused list (34.12 (8)). */
+export declare const RUNNER_REFUSED_REASONS: readonly ["bundle_too_large", "bundle_malformed", "bundle_wrong_typ", "bundle_schema", "bundle_unknown_key", "bundle_unusable_key", "bundle_retired_key", "bundle_bad_signature", "bundle_code_digest_mismatch", "bundle_not_yet_valid", "bundle_expired", "bundle_binding_mismatch", "bundle_unavailable", "job_unavailable", "contract_bad_sha", "contract_too_large", "contract_sha_mismatch", "contract_not_a_contract", "contract_mismatch_unrecoverable", "claim_needs_key", "claim_ineligible", "claim_unavailable", "lease_lost", "executor_revoked", "executor_unauthorized", "oidc_bad_issuer", "oidc_repo_not_enrolled", "oidc_ref_not_allowed", "oidc_pool_flag_off", "oidc_unavailable", "api_unavailable"];
+/** Under --fail-mode open, only these may be ridden through, and only once a verified bundle is held (34.12 (2)). */
+export declare const RUNNER_OPEN_MODE_TOLERATED: readonly ["bundle_unavailable", "job_unavailable", "api_unavailable"];
+export declare const RUNNER_MERGE_STRATEGIES: readonly ["external", "merge_on_green"];
+/**
+ * The fields a 200 claim answer carries exactly when the session is a pool session: the charter's
+ * contract_sha256 and contract_version, and the effective cap. A homed claim's answer carries none.
+ */
+export declare const POOL_CLAIM_FIELDS: readonly ["contract_sha256", "contract_version", "cap"];
+/** Whether a 200 claim answer's pool fields match `pool` (other keys are not judged here). */
+export declare function poolClaimFieldsOk(body: Readonly<Record<string, unknown>>, pool: boolean): boolean;
+/**
+ * agent_sessions.wait_ref, closed per PARKED_ONLY_WAIT_REASONS value (34.06 (2)): commitments only.
+ * repo_id is GitHub's numeric repository.id, a positive integer (ruling 34.14 (6)).
+ */
+export declare const WAIT_REF_KEYS: Readonly<{
+    readonly ci: readonly ["repo_id", "head_sha"];
+    readonly question: readonly ["approval_id"];
+    readonly budget: readonly ["approval_id"];
+}>;
+/** Whether `ref` is exactly the wait_ref shape for `reason`. */
+export declare function waitRefOk(reason: string, ref: unknown): boolean;
+/** durable_clear_wait answers (34.06 (4)). */
+export declare const CLEAR_WAIT_OUTCOMES: readonly ["cleared", "stale_ref", "already_clear"];
+/** durable_ready_sessions p_limit and exec_ready_list ?limit= range (34.03 (3)). */
+export declare const READY_SESSIONS_LIMIT_MIN = 1;
+export declare const READY_SESSIONS_LIMIT_MAX = 50;

package/dist/vendor/shared/durable-contract/doors.js

@@ -0,0 +1,249 @@
+// GENERATED from shared/durable-contract/src/doors.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * The Doors amendment to M1's claim model (rulings 34.01, 34.03, 34.05, 34.05.1, 34.10, 34.12):
+ * the pool-claim flag, executor scope, the per-org live-lease cap, the dispatch constructor's
+ * names and answers, and the thin runner's (`mnemom agent run`) frozen outcome line.
+ */
+import { ID_RE } from "./paths.js";
+import { UUID_RE } from "./canonical.js";
+// ---- Flag (ruling 34.01 (1), (2)) -----------------------------------------------------------
+/** The api env flag that gates every pool behaviour; its value is the org allowlist. */
+export const DURABLE_POOL_CLAIM_FLAG = "DURABLE_POOL_CLAIM";
+/**
+ * Whether the pool claim is on for `orgId`. The flag's value is a comma-separated list of org ids
+ * (whitespace around each ignored). Unset, empty, or any malformed entry reads as off for every
+ * org: an unknown value is never a partial allowlist (Doors production safety 1).
+ */
+export function poolClaimEnabled(flagValue, orgId) {
+    return poolClaimOrgs(flagValue).includes(orgId);
+}
+/**
+ * Whether a session is a pool session (rulings 34.04.1, 34.14 (3)): home_executor_id NULL, locked,
+ * and its org in the flag's allowlist. This is EffectiveStateInput.pool; the api and A1's parity
+ * test import it and never copy it. A NULL home alone (an erased executor) is never enough.
+ */
+export function isPoolSession(s, flagValue) {
+    return (s.home_executor_id === null &&
+        s.durable_mode === "locked" &&
+        poolClaimEnabled(flagValue, s.org_id));
+}
+/**
+ * The flag's org allowlist, in order with duplicates dropped; [] when the flag is off (unset, empty,
+ * or any malformed entry). The api imports this, never a copy: 34.10 (g)(3)'s p_org_ids is its
+ * answer.
+ */
+export function poolClaimOrgs(flagValue) {
+    if (flagValue === undefined)
+        return [];
+    const orgs = flagValue.split(",").map((s) => s.trim());
+    if (orgs.some((o) => !ID_RE.test(o)))
+        return [];
+    return [...new Set(orgs)];
+}
+// ---- Executor scope (ruling 34.03 (1)) ------------------------------------------------------
+export const EXECUTOR_SCOPES = ["user", "org"];
+/** Only these executor kinds may enroll with scope org. */
+export const ORG_SCOPE_EXECUTOR_KINDS = ["container", "fleet"];
+/** exec_oidc_exchange refusals (ruling 34.03's S1 changes). */
+export const OIDC_EXCHANGE_REFUSALS = [
+    "bad_issuer",
+    "repo_not_enrolled",
+    "ref_not_allowed",
+    "pool_flag_off",
+];
+/** The audience a GitHub OIDC token must name for exec_oidc_exchange (ruling 34.12 (5)). */
+export const OIDC_EXCHANGE_AUDIENCE = "mnemom-executor";
+// ---- Per-org live-lease cap (rulings 34.05, 34.05.1) ----------------------------------------
+/** durable_org_policy.limits keys (34.05 (1)); live_lease_cap is optional. */
+export const ORG_POLICY_LIMIT_KEYS = ["per_session_budget_usd", "live_lease_cap"];
+/** live_lease_cap and the registry default share this range. */
+export const LIVE_LEASE_CAP_MIN = 1;
+export const LIVE_LEASE_CAP_MAX = 1000;
+/** The org advisory lock a pool claim takes: pg_advisory_xact_lock(hashtext(prefix || org_id)). */
+export const ORG_CAP_LOCK_PREFIX = "durable_org_cap:";
+/** The api env var carrying the registry's dispatch.per_org_lease_cap (34.05.1 (2)). */
+export const DEFAULT_LEASE_CAP_ENV = "DURABLE_DEFAULT_LEASE_CAP";
+const capOk = (v) => Number.isInteger(v) && v >= LIVE_LEASE_CAP_MIN && v <= LIVE_LEASE_CAP_MAX;
+/** DURABLE_DEFAULT_LEASE_CAP as an integer, or null when absent or invalid (34.05.1 (3): fail closed). */
+export function parseDefaultLeaseCap(envValue) {
+    if (envValue === undefined || !/^[1-9][0-9]{0,3}$/.test(envValue))
+        return null;
+    const n = Number(envValue);
+    return capOk(n) ? n : null;
+}
+/**
+ * The effective cap of a pool claim (34.05.1 (1)): the org row's limits.live_lease_cap, else the
+ * default row's, else the registry default. Absent or NULL falls through; any present value out of
+ * range (even one that would not win), or no value at all, throws (the claim answers 503 lease_cap_config, never "no cap").
+ */
+export function effectiveLeaseCap(orgLimits, defaultRowLimits, defaultCap) {
+    const present = [orgLimits?.live_lease_cap, defaultRowLimits?.live_lease_cap, defaultCap].filter((v) => v !== undefined && v !== null);
+    // every present value is range-checked, not only the one that wins
+    for (const v of present)
+        if (!capOk(v))
+            throw new RangeError(`live lease cap out of range: ${String(v)}`);
+    if (present.length === 0)
+        throw new RangeError("no live lease cap: DURABLE_DEFAULT_LEASE_CAP is unset");
+    return present[0];
+}
+// ---- Dispatch constructor (ruling 34.10) ----------------------------------------------------
+export const DISPATCH_SESSION_CID_PREFIX = "dispatch-";
+export const DISPATCH_SESSION_NAME_PREFIX = "job-";
+export const CREATE_READY_SESSION_REFUSALS = [
+    "no_dispatch_agent",
+    "seal_not_found",
+    "cell_unmapped",
+    // 34.10.1 (4): the api-built charter v1 or its envelope does not match the seal; nothing written
+    "charter_mismatch",
+];
+export const CREATE_READY_SESSION_OUTCOMES = ["created", "existing", "refused"];
+/** durable_create_ready_session's answer keys per outcome, closed (34.10 (g)(1)). */
+export const CREATE_READY_SESSION_ANSWERS = Object.freeze({
+    created: ["outcome", "session_id"],
+    existing: ["outcome", "session_id"],
+    refused: ["outcome", "reason"],
+});
+/** Whether `v` is a closed answer: its outcome's keys only, a lowercase uuid session_id or a listed reason. */
+export function createReadySessionAnswerOk(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return false;
+    const a = v;
+    if (typeof a.outcome !== "string" ||
+        !Object.prototype.hasOwnProperty.call(CREATE_READY_SESSION_ANSWERS, a.outcome))
+        return false;
+    const keys = CREATE_READY_SESSION_ANSWERS[a.outcome];
+    if (Object.keys(a).length !== keys.length || !keys.every((k) => k in a))
+        return false;
+    return a.outcome === "refused"
+        ? CREATE_READY_SESSION_REFUSALS.includes(a.reason)
+        : typeof a.session_id === "string" && UUID_RE.test(a.session_id);
+}
+function sealIdOk(sealId) {
+    if (!UUID_RE.test(sealId))
+        throw new RangeError(`seal id must be a lowercase uuid: ${sealId}`);
+    return sealId;
+}
+/** conversation_id = 'dispatch-' || seal_id: 45 characters, so it passes ID_RE (34.10 (b)). */
+export function dispatchConversationId(sealId) {
+    return DISPATCH_SESSION_CID_PREFIX + sealIdOk(sealId);
+}
+/** name = 'job-' || the first 12 hex characters of seal_id without dashes, 16 characters (34.10 (c)). */
+export function dispatchSessionName(sealId) {
+    return DISPATCH_SESSION_NAME_PREFIX + sealIdOk(sealId).replace(/-/g, "").slice(0, 12);
+}
+// ---- Thin runner (ruling 34.12) -------------------------------------------------------------
+export const RUNNER_OUTCOMES = ["done", "no_job", "failed", "refused"];
+/** The v1 outcome line's fields, in order, each always present (34.12 (8)). */
+export const RUNNER_OUTCOME_FIELDS = [
+    "v",
+    "outcome",
+    "session_id",
+    "lease_epoch",
+    "contract_sha256",
+    "contract_version",
+    "merge_strategy",
+    "pr_url",
+    "reason",
+];
+/** Exit code per outcome (34.12 (6)); usage errors and the gate exit 2. */
+export const RUNNER_EXIT_CODES = Object.freeze({
+    done: 0,
+    no_job: 0,
+    failed: 1,
+    usage: 2,
+    refused: 3,
+});
+/** failed reasons besides the phase pattern RUNNER_FAILED_PHASE_RE. */
+export const RUNNER_FAILED_REASONS = ["pr_open_failed"];
+export const RUNNER_FAILED_PHASE_RE = /^phase_[0-9]+_[a-z0-9_]+$/;
+/** The closed refused list (34.12 (8)). */
+export const RUNNER_REFUSED_REASONS = [
+    "bundle_too_large",
+    "bundle_malformed",
+    "bundle_wrong_typ",
+    "bundle_schema",
+    "bundle_unknown_key",
+    "bundle_unusable_key",
+    "bundle_retired_key",
+    "bundle_bad_signature",
+    "bundle_code_digest_mismatch",
+    "bundle_not_yet_valid",
+    "bundle_expired",
+    "bundle_binding_mismatch",
+    "bundle_unavailable",
+    "job_unavailable",
+    "contract_bad_sha",
+    "contract_too_large",
+    "contract_sha_mismatch",
+    "contract_not_a_contract",
+    "contract_mismatch_unrecoverable",
+    "claim_needs_key",
+    "claim_ineligible",
+    "claim_unavailable",
+    "lease_lost",
+    "executor_revoked",
+    "executor_unauthorized",
+    "oidc_bad_issuer",
+    "oidc_repo_not_enrolled",
+    "oidc_ref_not_allowed",
+    "oidc_pool_flag_off",
+    "oidc_unavailable",
+    "api_unavailable",
+];
+/** Under --fail-mode open, only these may be ridden through, and only once a verified bundle is held (34.12 (2)). */
+export const RUNNER_OPEN_MODE_TOLERATED = [
+    "bundle_unavailable",
+    "job_unavailable",
+    "api_unavailable",
+];
+export const RUNNER_MERGE_STRATEGIES = ["external", "merge_on_green"];
+// ---- Pool claim answer (rulings 34.03 (3), 34.05.1 (4)) -------------------------------------
+/**
+ * The fields a 200 claim answer carries exactly when the session is a pool session: the charter's
+ * contract_sha256 and contract_version, and the effective cap. A homed claim's answer carries none.
+ */
+export const POOL_CLAIM_FIELDS = ["contract_sha256", "contract_version", "cap"];
+const HEX64_RE = /^[0-9a-f]{64}$/;
+/** Whether a 200 claim answer's pool fields match `pool` (other keys are not judged here). */
+export function poolClaimFieldsOk(body, pool) {
+    if (!pool)
+        return POOL_CLAIM_FIELDS.every((k) => !(k in body));
+    return (typeof body.contract_sha256 === "string" &&
+        HEX64_RE.test(body.contract_sha256) &&
+        Number.isInteger(body.contract_version) &&
+        body.contract_version >= 1 &&
+        capOk(body.cap));
+}
+// ---- Waits (ruling 34.06) -------------------------------------------------------------------
+/**
+ * agent_sessions.wait_ref, closed per PARKED_ONLY_WAIT_REASONS value (34.06 (2)): commitments only.
+ * repo_id is GitHub's numeric repository.id, a positive integer (ruling 34.14 (6)).
+ */
+export const WAIT_REF_KEYS = Object.freeze({
+    ci: ["repo_id", "head_sha"],
+    question: ["approval_id"],
+    budget: ["approval_id"],
+});
+const HEX40_RE = /^[0-9a-f]{40}$/;
+/** Whether `ref` is exactly the wait_ref shape for `reason`. */
+export function waitRefOk(reason, ref) {
+    if (!Object.prototype.hasOwnProperty.call(WAIT_REF_KEYS, reason))
+        return false;
+    if (ref === null || typeof ref !== "object" || Array.isArray(ref))
+        return false;
+    const r = ref;
+    const want = WAIT_REF_KEYS[reason];
+    if (Object.keys(r).length !== want.length || !want.every((k) => k in r))
+        return false;
+    if (reason === "ci")
+        return (Number.isSafeInteger(r.repo_id) &&
+            r.repo_id > 0 &&
+            typeof r.head_sha === "string" &&
+            HEX40_RE.test(r.head_sha));
+    return typeof r.approval_id === "string" && UUID_RE.test(r.approval_id);
+}
+/** durable_clear_wait answers (34.06 (4)). */
+export const CLEAR_WAIT_OUTCOMES = ["cleared", "stale_ref", "already_clear"];
+/** durable_ready_sessions p_limit and exec_ready_list ?limit= range (34.03 (3)). */
+export const READY_SESSIONS_LIMIT_MIN = 1;
+export const READY_SESSIONS_LIMIT_MAX = 50;

package/dist/vendor/shared/durable-contract/envelope.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Contract ciphertext envelope v1 and the charter commitment schema (C18-R01..R03; BACKBONE
+ * amendment 36; r3 U05). API only: no other repo decrypts.
+ *
+ *   contract_ciphertext = "v1." + b64url(iv, 12 bytes) + "." + b64url(ciphertext || 16-byte tag)
+ *   AES-256-GCM, per-session 32-byte DEK, random IV per write
+ *   AAD = UTF-8 "durable-contract:v1:<session_id>:<charter_version>"
+ *   plaintext = canonicalJson({statement, requirements, allowed_paths, forbidden_paths}), plus
+ *               goal_id, work_card and shape when the seal carries them (amendment 55)
+ *   wrapped_data_key = encryptBlob(dekWrapInput(DEK)) under the SESSION_COOKIE_KEY keyring (api)
+ *   statement_hash = sha256(canonicalJson(statement)); requirements_hash = sha256(canonicalJson(requirements))
+ */
+export declare const ENVELOPE_VERSION = "v1";
+export declare const CIPHER_KEY_REFS: readonly ["mnemom"];
+export declare const DEK_BYTES = 32;
+export declare const IV_BYTES = 12;
+export declare const TAG_BYTES = 16;
+export interface Contract {
+    statement: string;
+    requirements: string[];
+    allowed_paths: string[];
+    forbidden_paths: string[];
+    /** Amendment 55: the seal's goal_id, work_card and shape ride the ciphertext, present only when sealed. */
+    goal_id?: string;
+    work_card?: true;
+    shape?: "duty";
+}
+/** The Contract's optional keys (amendment 55); absent unless the gateway seal carried them. */
+export declare const CONTRACT_OPTIONAL_KEYS: readonly ["goal_id", "work_card", "shape"];
+export declare function contractAad(sessionId: string, charterVersion: number): string;
+/** Validate a submitted contract; null when malformed or over the statement limit. */
+export declare function parseContract(raw: unknown): Contract | null;
+export declare function contractPlaintext(c: Contract): string;
+export declare function statementHash(statement: string): Promise<string>;
+export declare function requirementsHash(requirements: readonly string[]): Promise<string>;
+/** What encryptBlob wraps: base64url of the raw DEK (so wrapped_data_key never decodes to 32 raw bytes). */
+export declare function dekWrapInput(dek: Uint8Array): string;
+export declare function dekFromWrapInput(text: string): Uint8Array | null;
+export declare function newDek(random?: (n: number) => Uint8Array): Uint8Array;
+/** Seal a contract. `random` is injectable for golden vectors only; production uses getRandomValues. */
+export declare function sealContract(dek: Uint8Array, sessionId: string, charterVersion: number, contract: Contract, random?: (n: number) => Uint8Array): Promise<string>;
+export declare function parseEnvelope(text: string): {
+    iv: Uint8Array;
+    ct: Uint8Array;
+} | null;
+/** Open an envelope; null on a malformed envelope, wrong key, wrong session or wrong version (AAD). */
+export declare function openContract(dek: Uint8Array, sessionId: string, charterVersion: number, envelope: string): Promise<Contract | null>;
+export declare const COMMITMENT_KEYS: readonly ["statement_hash", "requirements_hash", "budget_usd", "per_wake_cap_usd", "max_wakes_per_day", "max_turns", "active_time_limit_s", "pins", "tool_classes", "launch_spec", "mode", "stall_turns", "contract_hash"];
+/** The gateway's sealed-contract modes (MNE-8199); committed as `mode` by amendment 55. */
+export declare const CONTRACT_MODE_VALUES: readonly ["nudge", "enforce"];
+export declare const TOOL_CLASS_VALUES: readonly ["input_dependent", "safe", "idempotent"];
+/**
+ * Charter pins (BACKBONE A3, rulings U13, C07-R23): card_content_hash is the agent's live /state
+ * content_hash read at lock; policy_engine_major is the API's policy-engine major at lock. Both
+ * required, never empty, inside the charter preimage.
+ */
+export declare const PIN_KEYS: readonly ["card_content_hash", "policy_engine_major"];
+/** Validate a charter commitment object (keys a subset of COMMITMENT_KEYS; no text values). */
+export declare function isValidCommitment(raw: unknown): boolean;
+/** M1 accepts only input_dependent tool classes (safe/idempotent -> 422 durable_unsupported {feature:'tool_classes'}). */
+export declare function toolClassesSupportedM1(toolClasses: Readonly<Record<string, string>> | undefined): boolean;
+/**
+ * The charter row preimage. hash = sha256(canonicalJson(charterPreimage(row))); v(1).prev_hash =
+ * GENESIS_PREV_HASH (64 zeros) and v(n).prev_hash = v(n-1).hash. The preimage is exactly these
+ * fields (canonicalJson sorts keys):
+ *   v           CHARTER_PREIMAGE_VERSION (1)
+ *   session_id  the session uuid, lowercase text
+ *   version     the charter version, integer >= 1
+ *   prev_hash   64 lowercase hex
+ *   charter     the commitment object (isValidCommitment; pins included)
+ *   created_at  canonicalEventTs(created_at): UTC, "T", 6 fraction digits, "Z" (a Postgres
+ *               timestamptz text such as "2026-10-16 12:00:00.123+00" canonicalises the same).
+ *               Amendment 55: v1's created_at IS the original seal's sealed_at (T0, the gateway's
+ *               first sealed request), never the lock time: build it with charterV1CreatedAt. Every
+ *               reader that reports a session's sealed_at reads v1's created_at. v(n>1)'s created_at
+ *               is the amend time and never changes sealed_at.
+ * Every other agent_session_charters column is outside it (CHARTER_HASH_EXCLUDED_COLUMNS), so a KEK
+ * re-wrap (wrapped_data_key changes) and the contract purge (contract_ciphertext nulled,
+ * contract_purge_after stamped) leave every hash and agent_sessions.charter_hash unchanged.
+ */
+export declare const CHARTER_PREIMAGE_VERSION = 1;
+export declare const CHARTER_PREIMAGE_FIELDS: readonly ["v", "session_id", "version", "prev_hash", "charter", "created_at"];
+export declare const CHARTER_HASH_EXCLUDED_COLUMNS: readonly ["hash", "contract_ciphertext", "wrapped_data_key", "cipher_key_ref", "contract_purge_after", "signature"];
+export interface CharterPreimageInput {
+    session_id: string;
+    version: number;
+    prev_hash: string;
+    charter: Record<string, unknown>;
+    created_at: string;
+}
+/**
+ * Build the preimage from a charter row. Extra row columns (the excluded ones) are ignored. Throws on
+ * a bad version, a malformed prev_hash, a version-1 row that does not chain from genesis, or an
+ * invalid commitment.
+ */
+export declare function charterPreimage(row: CharterPreimageInput): Record<string, unknown>;
+/**
+ * Charter v1's created_at from the gateway seal's sealed_at (amendment 55). The seal may carry any
+ * ISO-8601 instant (UTC, or an offset such as "-07:00", at millisecond precision); the result is the same instant in
+ * canonicalEventTs form. Throws on text that is not an instant.
+ */
+export declare function charterV1CreatedAt(sealedAt: string): string;
+export declare function charterHash(row: CharterPreimageInput): Promise<string>;