@gajae-code/coding-agent 0.12.21 → 0.13.0

package/dist/types/sdk/broker/session-index.d.ts

@@ -1,5 +1,25 @@
 import { SDK_STATE_VERSION } from "./state-version";
-export type SessionIndexEventType = "host_registered" | "host_heartbeat" | "host_unregistered" | "lifecycle_started" | "lifecycle_terminal" | "session_closed" | "record_reconciled";
+export type SessionIndexEventType = "host_registered" | "host_heartbeat" | "host_unregistered" | "lifecycle_started" | "lifecycle_terminal" | "session_closed" | "session_deleted" | "record_reconciled";
+export type SessionActivityState = "active" | "idle";
+/** Coalesced broker-owned heartbeat checkpoint (C2): state plus the observation time. */
+export interface SessionActivity {
+    state: SessionActivityState;
+    at: number;
+}
+/** Events persisted without an OS process incarnation (v1/v2 era) are legacy provenance. */
+export type SessionIdentityProvenance = "composite" | "legacy";
+export type SessionTombstoneRule = "retain" | "expire";
+/**
+ * Injected retention policy (C3). The broker schedules compaction independently of
+ * rotation; settings apply at the next scheduled compaction. `clock` drives both
+ * retention expiry and heartbeat-freshness liveness reads.
+ */
+export interface RetentionPolicy {
+    clock?: () => number;
+    maxAgeMs?: number;
+    maxRows?: number;
+    tombstoneRule?: SessionTombstoneRule;
+}
 export interface SessionIndexEvent {
     version: typeof SDK_STATE_VERSION;
     indexSeq: number;
@@ -11,9 +31,20 @@ export interface SessionIndexEvent {
     };
     endpointGeneration: number;
     pid: number;
+    /**
+     * OS start incarnation of `pid`, published by the host that owns that pid. A
+     * pid is reusable, so teardown needs this binding to prove the pid is still
+     * the same process; keeping it here, in broker-owned storage, is what lets
+     * that proof outlive the session's own workspace.
+     */
+    processIncarnation?: string;
     endpointMtimeMs?: number;
     lifecycleRequestId?: string;
     terminalUncertain?: boolean;
+    /** OS process incarnation (C1); absent on legacy v1/v2 events. */
+    hostIncarnation?: string;
+    /** Present on host_heartbeat checkpoints (C2). */
+    activity?: SessionActivity;
     ts: number;
     checksum: string;
 }
@@ -25,11 +56,22 @@ export interface IndexedSession {
     };
     endpointGeneration: number;
     pid: number;
+    /** OS start incarnation of `pid` as published by its own host at registration. */
+    processIncarnation?: string;
     endpointMtimeMs?: number;
     live: boolean;
     indexSeq: number;
     lifecycleRequestId?: string;
     terminalUncertain?: boolean;
+    hostIncarnation?: string;
+    identityProvenance: SessionIdentityProvenance;
+    activity?: SessionActivity;
+    /** Wall-clock timestamp of the latest admitted heartbeat, when one exists. */
+    lastHeartbeatAt?: number;
+    /** True when the same sessionId maps to more than one stateRoot (cross-repo duplicate). */
+    ambiguous: boolean;
+    /** True when the identity's latest event is host_unregistered or session_closed (DR-1: stopped rows are retained). */
+    terminal: boolean;
 }
 export interface SessionList {
     indexSeq: number;
@@ -46,10 +88,30 @@ export interface SessionIndexRepairResult extends SessionIndexDiagnosis {
     repaired: boolean;
     quarantinePath?: string;
 }
+/** Admission-fence rejection codes recorded in the durable index audit (C5/C4). */
+export type SessionIndexAuditCode = "rejected_superseded_incarnation" | "rejected_after_tombstone";
+export interface SessionIndexAuditRecord {
+    version: typeof SDK_STATE_VERSION;
+    code: SessionIndexAuditCode;
+    /** indexSeq of the rejected event (unique per record; used for idempotent dedupe). */
+    indexSeq: number;
+    sessionId: string;
+    endpointGeneration: number;
+    stateRoot: string;
+    hostIncarnation?: string;
+    supersededByIncarnation?: string;
+    /** indexSeq of the superseding registration, or of the tombstone for post-delete rejections. */
+    supersededByIndexSeq: number;
+    ts: number;
+}
 export declare const sessionIndexChecksum: (event: Omit<SessionIndexEvent, "checksum">) => string;
+/** Coalesced heartbeat checkpoint rate cap (C2): at most one per session per minute. */
+export declare const SESSION_HEARTBEAT_INTERVAL_MS = 60000;
+export declare const DEFAULT_SESSION_RETENTION_MAX_AGE_MS: number;
+export declare const DEFAULT_SESSION_RETENTION_MAX_ROWS = 25000;
 export declare class SessionIndex {
     #private;
-    constructor(agentDir: string);
+    constructor(agentDir: string, policy?: RetentionPolicy);
     open(): Promise<this>;
     replay(): Promise<void>;
     diagnose(): Promise<SessionIndexDiagnosis>;
@@ -57,8 +119,27 @@ export declare class SessionIndex {
     refresh(): Promise<void>;
     get indexSeq(): number;
     append(input: Omit<SessionIndexEvent, "version" | "indexSeq" | "checksum" | "ts"> & Partial<Pick<SessionIndexEvent, "ts">>): Promise<SessionIndexEvent>;
+    /** Hold the canonical index lock across an authority-sensitive operation. */
+    withLocked<T>(callback: () => Promise<T>): Promise<T>;
     snapshot(): Promise<void>;
+    /**
+     * Broker-scheduled compaction (C3), independent of rotation size: applies the
+     * injected retention policy to a fresh snapshot and truncates the log.
+     */
+    compact(): Promise<void>;
     listSessions(): SessionList;
+    /**
+     * Production coalesced heartbeat checkpoint pass (C2): appends one
+     * `host_heartbeat` per session at most once per {@link SESSION_HEARTBEAT_INTERVAL_MS}.
+     * The pass observes liveness the same way the projection does — the host process
+     * must be alive and, for composite identities, still carry the recorded OS process
+     * incarnation (a reused PID is never checkpointed). Stopped/terminal rows and rows
+     * whose heartbeat is still fresh are skipped. After a broker restart, sessions whose
+     * host survived are re-observed as live on the first pass; sessions whose host died
+     * while the broker was down keep their stale or missing heartbeat and read as
+     * unknown/not-live (never fresh forever). Returns the number of checkpoints written.
+     */
+    checkpointLiveHeartbeats(now?: number): Promise<number>;
     hostUnregisteredAfter(registration: Pick<IndexedSession, "sessionId" | "endpointGeneration" | "pid" | "indexSeq" | "lifecycleRequestId">): {
         indexSeq: number;
         lifecycleRequestId?: string;

package/dist/types/sdk/broker/state-version.d.ts

@@ -1,5 +1,5 @@
 export declare const SDK_STATE_VERSION = 1;
-export declare const SESSION_INDEX_SNAPSHOT_VERSION = 2;
+export declare const SESSION_INDEX_SNAPSHOT_VERSION = 3;
 export declare class UnsupportedStateVersionError extends Error {
     readonly file: string;
     readonly version: number;

package/dist/types/sdk/bus/notification-service.d.ts

@@ -170,6 +170,12 @@ export interface DaemonHealth {
     stopped: boolean;
     heartbeatAt: number | undefined;
     heartbeatAgeMs: number | undefined;
+    /**
+     * Session endpoints the live owner reported an OPEN socket to in its latest
+     * matching heartbeat sidecar. `undefined` means the owner never published the
+     * field (older daemon, no stable owner tag, no matching sidecar): unknown, not zero.
+     */
+    attachedEndpoints: number | undefined;
     generation: number | undefined;
     currentGeneration: number;
     generationRelation: DaemonGenerationRelation;

package/dist/types/sdk/bus/prompt-reconciliation.d.ts

@@ -16,7 +16,9 @@
  *   Session-scoped durable retention (kind-aware store) is provided by reconciliation-store.ts (#3032).
  * - The clientRef index is session-runtime scoped; a ref conflicts only while
  *   retained and must never be reused as a retry mechanism.
- * - Terminal transitions settle once: the first terminal outcome wins.
+ * - Terminal transitions settle once: first terminal outcome wins. A late
+ *   `agent_failed` may still attach its sanitized reason to an already-terminal
+ *   record that has none, but never changes status, terminalAt, or retention.
  */
 import { PROMPT_FAILURE_CODE_MAX, sanitizePromptFailure } from "../prompt-failure";
 export { PROMPT_FAILURE_CODE_MAX, sanitizePromptFailure };
@@ -60,6 +62,11 @@ export type TurnPromptReconciliation = {
     acceptedAt: number;
     startedAt?: number;
     terminalAt: number;
+    /** Present when a late `agent_failed` supplied the only failure reason. */
+    error?: {
+        code: string;
+        message: string;
+    };
 } | {
     status: "failed";
     commandId: string;

package/dist/types/sdk/bus/telegram-daemon-contract.d.ts

@@ -91,8 +91,11 @@ export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
  * later session from creating a topic or replaying notifications. Generation
  * 58 preserves that invariant during durable-fence load promotion and restores
  * the exact grace deadline when a failed archive publication rolls back.
+ * Generation 59 publishes the owner's attached OPEN-socket count in the
+ * heartbeat sidecar so `gjc notify health` can report a live daemon that is
+ * attached to no registered endpoint (#4128).
  */
-export declare const DAEMON_GENERATION = 58;
+export declare const DAEMON_GENERATION = 59;
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 5
  * requires the complete generation-36 topic authority contract, so older

package/dist/types/sdk/bus/telegram-daemon.d.ts

@@ -273,11 +273,23 @@ type OwnerHeartbeatSidecar = {
     ownerId: string;
     acquisitionId: string;
     heartbeatAt: number;
+    /**
+     * Session endpoints this owner had an OPEN WebSocket to when the heartbeat was
+     * published. Optional: a sidecar written by an older daemon omits it and must
+     * read back as unknown, never as zero.
+     */
+    attachedEndpoints?: number;
 };
 export interface OwnerFreshnessSnapshot {
     ownerTag: Pick<OwnerHeartbeatSidecar, "pid" | "incarnation" | "ownerId" | "acquisitionId"> | null;
     effectiveHeartbeatAt: number | undefined;
     legacyEmbedded: boolean;
+    /**
+     * Session endpoints the current owner reported as attached in its latest matching
+     * heartbeat sidecar. `undefined` means the owner never published the field (older
+     * daemon, no stable owner tag, or no matching sidecar) — that is unknown, not zero.
+     */
+    attachedEndpoints: number | undefined;
     state: DaemonState | undefined;
 }
 export declare function readOwnerFreshnessSnapshot(input: {
@@ -293,6 +305,12 @@ export declare function renewOwnerHeartbeatSidecar(input: {
     now?: () => number;
     pid?: number;
     pidIncarnation?: (pid: number) => string | undefined;
+    /**
+     * Session endpoints the caller currently holds an OPEN WebSocket to. Omitted by
+     * non-daemon callers (bootstrap/proof paths) so their sidecar reports unknown
+     * rather than falsely claiming zero attachments.
+     */
+    attachedEndpoints?: number;
 }): Promise<boolean>;
 export interface NotificationRootRegistration {
     root?: string;
@@ -1252,6 +1270,14 @@ export declare class TelegramNotificationDaemon {
     private notifyThreadedFallback;
     private startFlushTimer;
     private stopFlushTimer;
+    /**
+     * Sessions this owner can actually deliver to right now. Only `WebSocket.OPEN`
+     * counts: a CONNECTING socket is constructed but cannot carry a frame, and
+     * CLOSING/CLOSED ones are gone. Every delivery path in this daemon refuses to
+     * send unless `readyState === WebSocket.OPEN`, so OPEN is exactly the state
+     * that means a notification can leave this process for that session.
+     */
+    private attachedEndpointCount;
     private renewOwnershipHeartbeat;
     /**
      * Ownership must be renewed independently of Telegram's 25-second long poll:

package/dist/types/sdk/cli/rows.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Versioned DTO rows for `gjc sdk session` semantic verbs (row DTO v1, DR-12).
+ *
+ * Every semantic verb renders its output through these rows so machine
+ * consumers get one deterministic, versioned envelope per verb. Credentials
+ * are never part of the row schema: broker `session.list` rows carry no
+ * credentials, offline inspect rows are projected from endpoint discovery
+ * records with secret-shaped fields stripped before they can reach a row, and
+ * pass-through host payloads are redacted recursively before rendering.
+ */
+export declare const SESSION_ROWS_VERSION = 1;
+export type SdkSessionActivityState = "active" | "idle";
+export interface SdkSessionActivityV1 {
+    state: SdkSessionActivityState;
+    at: number;
+}
+export interface SdkSessionRowV1 {
+    sessionId: string;
+    locator: {
+        repo: string;
+        stateRoot: string;
+    };
+    endpointGeneration: number;
+    /** Process-bound incarnation of the hosting process (C1); absent for legacy-provenance rows. */
+    hostIncarnation?: string;
+    pid: number;
+    live: boolean;
+    /** Tombstone flag (C4): deleted sessions are excluded from list/endpoint/resumable surfaces. */
+    deleted: boolean;
+    indexSeq: number;
+    terminalUncertain?: boolean;
+    lifecycleRequestId?: string;
+    endpointMtimeMs?: number;
+    /** Coalesced broker-owned heartbeat checkpoint (C2). */
+    activity?: SdkSessionActivityV1;
+    /** Wall-clock timestamp of the latest admitted heartbeat, when one exists. */
+    lastHeartbeatAt?: number;
+    /** "legacy" for v1/v2-era rows that predate process-incarnation identity. */
+    identityProvenance?: "composite" | "legacy";
+    /** True when the same sessionId maps to more than one stateRoot (cross-repo duplicate). */
+    ambiguous?: boolean;
+}
+export interface SdkCheckpointRecordV1 {
+    revision: number;
+    generation: number;
+    seq: number;
+}
+export interface SdkRetentionGapV1 {
+    code: "retention_gap";
+    missing?: {
+        from: number;
+        to: number;
+    };
+    resync?: SdkCheckpointRecordV1;
+}
+/** One tail item: a retained transcript entry or a live event-ring event. */
+export interface SdkTailItemV1 {
+    /** "transcript" for retained transcript entries, otherwise the event-ring kind. */
+    kind: string;
+    id?: string;
+    generation?: number;
+    seq?: number;
+    payload: unknown;
+}
+export interface SdkTailEnvelopeV1 {
+    version: typeof SESSION_ROWS_VERSION;
+    source: "session" | "offline";
+    session: SdkSessionRowV1;
+    checkpoint?: SdkCheckpointRecordV1;
+    gap?: SdkRetentionGapV1;
+    items: SdkTailItemV1[];
+}
+/** Recursively removes secret-shaped fields (defense in depth for DTO output). */
+export declare function stripSecretFields(value: unknown): unknown;
+/**
+ * Projects one broker `session.list` row into the credential-free v1 row DTO.
+ * The row is a superset-tolerant projection: identity fields introduced by
+ * later index versions (hostIncarnation, activity, deleted) pass through when
+ * present and are omitted otherwise, so the same mapper serves both v2 and v3
+ * index shapes.
+ */
+export declare function toSessionRowV1(value: unknown): SdkSessionRowV1;
+/**
+ * Offline inspect row projected from a local SDK endpoint discovery record.
+ * The discovery record carries the endpoint credential (`url`/`token`); neither
+ * is ever projected into the row. `path` is the endpoint file
+ * `<stateRoot>/sdk/<sessionId>.json`, so the state root is recovered from the
+ * path when the layout matches.
+ */
+export declare function toOfflineSessionRowV1(value: unknown): SdkSessionRowV1;
+export declare function toCheckpointRecordV1(value: unknown): SdkCheckpointRecordV1 | undefined;
+export declare function toRetentionGapV1(value: unknown): SdkRetentionGapV1 | undefined;
+/** Projects a transcript entry or ring event into a tail item with dedupe keys. */
+export declare function toTailItemV1(value: unknown, fallback: {
+    kind: string;
+    generation?: number;
+    seq?: number;
+}): SdkTailItemV1;

package/dist/types/sdk/cli/session-cli.d.ts

@@ -1,19 +1,51 @@
-export type SdkSessionCliAction = "list" | "control" | "query" | "global";
+import { type OperationKind } from "../protocol/operation-registry";
+export type SdkSessionCliAction = "list" | "inspect" | "send" | "status" | "tail" | "elevate" | "raw";
+export type SdkSessionCliRawKind = "control" | "query" | "global";
 export interface SdkSessionCliArgs {
     action?: string;
+    /** Raw dispatch kind when action is "raw" (control | query | global). */
+    rawAction?: string;
     sessionId?: string;
+    /** Caller-chosen operation reference (ULID) for `send`; required target for `status`. */
+    opRef?: string;
     operation?: string;
     query?: string;
+    /** Convenience `send` body: forwarded as the `text` field of turn.prompt. */
+    text?: string;
     jsonInput?: string;
     jsonInputFile?: string;
-    idempotencyKey?: string;
     jsonInputStdin?: boolean;
+    idempotencyKey?: string;
+    elevationRequestId?: string;
+    operationKind?: OperationKind;
     confirm?: boolean;
+    /** Raw query continuation cursor, or a saved checkpoint token to resume `tail` from (re-minted per connection). */
     cursor?: string;
     showEndpointCredential?: boolean;
     yes?: boolean;
+    /** `send --wait`: poll turn.prompt_status until terminal or the wait window elapses. */
+    wait?: boolean;
+    /** Bounded wait for `send --wait`, `status`, and live `tail` follow. */
+    timeoutMs?: number;
+    /** `tail --strict`: fail closed on retention gaps (exit 1 retention_gap). */
+    strict?: boolean;
+    /** `tail --until-idle`: exit once the observed event stream reaches a terminal turn state. */
+    untilIdle?: boolean;
+    /** `tail --all-events`: include every event-ring kind instead of the tail subset. */
+    allEvents?: boolean;
     repo?: string;
     agentDir?: string;
 }
-/** Runs the pure-SDK `gjc daemon session` command family. */
+/**
+ * Time-ordered operation reference (ULID): 48-bit millisecond timestamp plus
+ * 80 bits of randomness, Crockford base32, lowercase. The ref is used as the
+ * `turn.prompt` clientRef so `send`/`status` correlate without a broker round
+ * trip, and matches the plan's durable op-ref ledger shape (C7).
+ */
+export declare function createOperationRef(now?: number): string;
+export declare function runTail(repo: string, agentDir: string, sessionId: string, args: SdkSessionCliArgs): Promise<unknown>;
+/**
+ * Runs the `gjc sdk session` command family: semantic verbs (list, inspect,
+ * send, status, tail) plus the explicit raw control/query/global hatch.
+ */
 export declare function runSdkSessionCli(args: SdkSessionCliArgs, writeOutput?: (value: unknown) => void, setExitCode?: (exitCode: 1 | 2) => void): Promise<void>;

package/dist/types/sdk/elevation/allowlist.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Exact elevation-gated allowlist, fully qualified and enumerative.
+ *
+ * The elevation allowlist is the exact set of registry operations below (the
+ * raw destructive lifecycle and workflow-approval operations). It is declared
+ * ONCE here as a `Set<string>` of `"kind:sdkId"` keys and mechanically pinned
+ * against `operation-registry.ts` by the allowlist unit test: every key must
+ * resolve via `findOperation(kind, sdkId)` and no elevatable operation may be
+ * silently missing. Any operation NOT in this set is rejected at issue with
+ * `elevation_not_allowlisted` before any ledger reservation. There is no
+ * generalized policy engine: this is the deterministic predicate.
+ */
+export declare const ELEVATION_ALLOWLIST_KEYS: readonly ["global:session.close", "global:session.delete", "control:session.delete", "control:session.close", "control:context.clear", "control:session.cwd.move", "control:compaction.run", "control:bash.execute", "control:bash.background", "control:queue.message.remove", "control:queue.message.update", "control:retry.abort", "control:retry.now", "control:bash.abort", "control:retry.auto.set", "control:compaction.auto.set", "control:extension.set_enabled", "control:queue.interrupt_mode.set", "control:queue.follow_up_mode.set", "control:queue.steering_mode.set", "control:tools.active.set", "control:permission_mode.set", "control:service_tier.set", "control:workflow.gate_answer", "control:workflow.plan_approve"];
+/**
+ * Whether `(kind, sdkId)` is the fully qualified identity of an allowlisted
+ * elevation-gated operation. The pair is validated against the operation
+ * registry before any elevation is admitted, so a key can never name an
+ * operation that does not exist.
+ */
+export declare function isElevationAllowlisted(kind: unknown, sdkId: unknown): boolean;

package/dist/types/sdk/elevation/audit.d.ts

@@ -0,0 +1,93 @@
+import { SDK_STATE_VERSION } from "../broker/state-version";
+import { classifyProcessIncarnationLiveness } from "./owner";
+/**
+ * Durable elevation audit trail.
+ *
+ * Append-only JSONL under the same elevation-local lock as the grant ledger,
+ * mode 0600. Every state transition of a grant — issue, operator answer,
+ * expiry, misuse, duplicate answer, claim, and dispatch outcome — is
+ * recorded with the exact identity evidence the transition consumed, so an
+ * auditor can reproduce why a grant reached its terminal state without
+ * trusting in-memory state.
+ *
+ * The audit stream is an evidence trail, never an authority: audit rows are
+ * append-only, are never re-read to drive decisions, and a corrupted row is
+ * quarantined (like ledger rows) instead of failing the ledger.
+ */
+export type ElevationAuditEvent = {
+    kind: "issued";
+} | {
+    kind: "answered";
+    outcome: "granted" | "denied" | "expired" | "misused" | "target_unavailable" | "duplicate_answer";
+} | {
+    kind: "expired";
+} | {
+    kind: "misused";
+} | {
+    kind: "duplicate_answer";
+} | {
+    kind: "claimed";
+    claim: {
+        ownerId: string;
+        epoch: number;
+        pid: number;
+        incarnation: string;
+    };
+} | {
+    kind: "dispatched";
+    dispatch: {
+        ownerId: string;
+        epoch: number;
+        dispatchedAt: number;
+    };
+    outcome: {
+        status: "ok" | "failed";
+        code?: string;
+        message?: string;
+        dispatchedAt: number;
+    };
+} | {
+    kind: "consumed";
+    message: string;
+} | {
+    kind: "unavailable";
+    reason: string;
+};
+export interface ElevationAuditEntry {
+    version: typeof SDK_STATE_VERSION;
+    ts: number;
+    elevationRequestId: string;
+    issueIndex: number;
+    event: ElevationAuditEvent;
+}
+export type ElevationAuditEventName = ElevationAuditEvent["kind"];
+export declare function isElevationAuditEntry(value: unknown): value is ElevationAuditEntry;
+export interface ElevationAuditOptions {
+    /** Injectable clock. */
+    now?: () => number;
+    /**
+     * Injectable tri-state process-incarnation liveness classifier, defaulting
+     * to `classifyProcessIncarnationLiveness`. The audit trail records the
+     * liveness verdict behind `consumed`/`unavailable` settlements so the
+     * crash-truth settlement is reproducible; the verdict never drives the
+     * settlement itself (that lives in the ledger).
+     */
+    classifyLiveness?: typeof classifyProcessIncarnationLiveness;
+}
+export declare class ElevationAudit {
+    #private;
+    constructor(agentDir: string, options?: ElevationAuditOptions);
+    get warnings(): readonly string[];
+    /**
+     * Appends one audit row for an elevation grant transition. Callers MUST
+     * hold the same elevation-local lock that guards the grant ledger; the
+     * audit row and the grant row therefore commit together.
+     */
+    append(entry: Omit<ElevationAuditEntry, "version">): Promise<void>;
+    /**
+     * Opens the audit stream: creates the 0600 directory/file if absent and
+     * quarantines any corrupt tail so subsequent appends are always readable.
+     * Called under the same lock as `ElevationLedger.open()`.
+     */
+    open(): Promise<this>;
+}

package/dist/types/sdk/elevation/capability.d.ts

@@ -0,0 +1,3 @@
+export declare function signElevationCapability(authorityToken: string, requestId: string, sdkId: string, input: Record<string, unknown>): string;
+export declare function verifyElevationCapability(authorityToken: string, capability: string, sdkId: string, input: Record<string, unknown>): boolean;
+export declare function elevationAuthorityPath(stateRoot: string, sessionId: string): string;

package/dist/types/sdk/elevation/digest.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Fully qualified elevation request digest.
+ *
+ * An elevation grant binds the exact operation the operator approved. The
+ * digest covers the complete `{kind, sdkId, input}` triple so substituting a
+ * different operation or different input bytes changes the digest and the
+ * gate presentation fails closed (`misused`). The top-level
+ * `elevationRequestId` correlation field is deliberately excluded: it is the
+ * durable correlation ID assigned to a request, not part of the approved
+ * content, and the same content re-issued under a new ID must produce the
+ * same digest.
+ *
+ * Only allowlisted operations can be elevated; anything else is refused so a
+ * caller cannot mint a grant for an operation outside the elevation policy.
+ */
+export declare const ELEVATION_OPERATION_KINDS: readonly ["control", "query", "global"];
+export type ElevationOperationKind = (typeof ELEVATION_OPERATION_KINDS)[number];
+export interface ElevationOperation {
+    kind: ElevationOperationKind;
+    sdkId: string;
+}
+/**
+ * Operations that require an elevation grant. Default SDK scope
+ * (list/query/send/tail) stays grant-free; destructive lifecycle operations
+ * and workflow approval operations are elevatable and therefore gated.
+ */
+export declare const ELEVATION_ALLOWLIST: readonly {
+    kind: ElevationOperationKind;
+    sdkId: string;
+}[];
+export declare function isElevatableOperation(kind: unknown, sdkId: unknown): boolean;
+/**
+ * Whether the `(kind, sdkId)` pair names a registry operation that the
+ * elevation allowlist recognizes. Used by the ledger row validator so a
+ * persisted row can never bind an operation outside the allowlist.
+ */
+export declare function isKnownElevationOperation(kind: unknown, sdkId: unknown): boolean;
+/**
+ * Canonical JSON encoding for elevation digest leaves.
+ *
+ * Intentionally byte-compatible with the broker's identity canonicalization
+ * (`canonicalJson` in `sdk/broker/broker.ts`): object keys sorted, compact
+ * separators, `undefined` fields preserved verbatim, arrays joined without
+ * separators. The broker computes the request digest at issue time and the
+ * ledger recomputes/compares the same encoding, so digest verification is
+ * stable across issue, gate presentation, and answer.
+ */
+export declare function canonicalElevationJson(value: unknown): string;
+export type ElevationDigestResult = {
+    ok: true;
+    digest: string;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * Computes the fully qualified digest for an elevation request.
+ *
+ * `input` is digested exactly as supplied except that a top-level
+ * `elevationRequestId` field is removed first (it is the correlation ID, not
+ * approved content). Operations outside `ELEVATION_ALLOWLIST` are refused
+ * with `elevation_not_required` so the broker never mints a grant for an
+ * operation that does not need one.
+ */
+export declare function elevationRequestDigest(request: {
+    kind: unknown;
+    sdkId: unknown;
+    input: unknown;
+}): ElevationDigestResult;

package/dist/types/sdk/elevation/dispatch-receipt.d.ts

@@ -0,0 +1,85 @@
+export declare const ELEVATION_RECEIPT_VERSION = 1;
+/**
+ * Identity of the broker tenure that claims a grant and dispatches it.
+ *
+ * `ownerId` is the broker instance owner id and `epoch` increments per broker
+ * start, so a restart (even of the same object) yields a new tenure. `pid` and
+ * `incarnation` are retained for truthful tri-state liveness replay.
+ */
+export interface ElevationClaimIdentity {
+    ownerId: string;
+    epoch: number;
+    pid: number;
+    incarnation: string;
+}
+export type ElevationReceiptState = "claimed" | "dispatched" | "uncertain";
+/**
+ * Durable dispatch outcome. `unknown` is the crash truth: the grant was
+ * consumed by a claim but the dispatch outcome is not knowable, so retry
+ * requires a new grant.
+ */
+export type ElevationDispatchOutcome = {
+    status: "ok";
+    dispatchedAt: number;
+} | {
+    status: "failed";
+    code: string;
+    message: string;
+    dispatchedAt: number;
+} | {
+    status: "unknown";
+    message: string;
+    dispatchedAt: number;
+};
+/**
+ * Owner/epoch-bound dispatch receipt.
+ *
+ * State machine: `claimed` (grant spent, dispatch in flight, bound to the
+ * claiming broker tenure) -> `dispatched` (terminal, outcome recorded) or
+ * `uncertain` (terminal truth: the claim's outcome is unknowable after its
+ * broker tenure died). Replay never fabricates an outcome: a receipt left in
+ * `claimed` by a dead tenure is truthfully terminalized to `uncertain`.
+ */
+export interface ElevationDispatchReceipt {
+    version: typeof ELEVATION_RECEIPT_VERSION;
+    elevationRequestId: string;
+    issueIndex: number;
+    state: ElevationReceiptState;
+    claim: ElevationClaimIdentity & {
+        claimedAt: number;
+    };
+    dispatch?: {
+        ownerId: string;
+        epoch: number;
+        dispatchedAt: number;
+    };
+    outcome?: ElevationDispatchOutcome;
+    ts: number;
+}
+export declare function isElevationRequestId(value: unknown): value is string;
+export declare function isElevationClaimIdentity(value: unknown): value is ElevationClaimIdentity;
+export declare function isElevationDispatchOutcome(value: unknown): value is ElevationDispatchOutcome;
+export declare function isElevationDispatchReceipt(value: unknown): value is ElevationDispatchReceipt;
+export declare function claimReceipt(requestId: string, issueIndex: number, claim: ElevationClaimIdentity, claimedAt: number): ElevationDispatchReceipt;
+export declare function dispatchReceipt(receipt: ElevationDispatchReceipt, dispatch: {
+    ownerId: string;
+    epoch: number;
+    dispatchedAt: number;
+}, outcome: ElevationDispatchOutcome): ElevationDispatchReceipt;
+export declare function uncertainReceipt(receipt: ElevationDispatchReceipt, at: number): ElevationDispatchReceipt;
+export declare function receiptClaimMatches(receipt: ElevationDispatchReceipt, identity: ElevationClaimIdentity): boolean;
+/**
+ * Who may answer an elevation gate.
+ *
+ * Internal operator-only: the answer boundary is the broker's internal
+ * operator attestation (`local_operator`), reached only through broker-owned
+ * surfaces. There is no public `elevation.answer` operation and no
+ * requester-correlation check: the answerer is structurally an operator
+ * attestation, so requester self-approval is impossible by construction.
+ */
+export type ElevationAnswerAuthority = {
+    source: "local_operator";
+    attestedBy: string;
+};
+/** Structural guard for the internal operator attestation. */
+export declare function isElevationAnswerAuthority(value: unknown): value is ElevationAnswerAuthority;