open-multi-agent-kit 0.95.2 → 0.96.1

package/dist/types/evidence.js.map

@@ -1 +1 @@
-{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/types/evidence.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * Evidence and verification types for OMK v0.80.3+\n *\n * Defines contracts for agent completion evidence, replay persistence,\n * merge gating, and artifact validation.\n */\n\n// ============================================================================\n// Evidence Contract\n// ============================================================================\n\nexport type EvidenceCategory =\n\t| \"feature\"\n\t| \"bugfix\"\n\t| \"refactor\"\n\t| \"research\"\n\t| \"release\"\n\t| \"security\"\n\t| \"docs\"\n\t| \"orchestration\";\n\nexport type EvidenceStatus = \"pending\" | \"gathering\" | \"satisfied\" | \"failed\" | \"waived\";\n\nexport interface EvidenceItem {\n\t/** What this evidence proves. */\n\tclaim: string;\n\t/** Category of the task. */\n\tcategory: EvidenceCategory;\n\t/** Path to artifact or command that produced it. */\n\tartifactPath?: string;\n\t/** Command that can reproduce the evidence. */\n\tverificationCommand?: string;\n\t/** SHA-256 of the artifact for integrity. */\n\thash?: string;\n\t/** When the evidence was gathered. */\n\ttimestamp: string;\n\t/** Whether the evidence is available. */\n\tstatus: EvidenceStatus;\n\t/** Receipt v3 metadata consumed by receipt-aware evidence gates. */\n\treceiptId?: string;\n\treceiptSchemaVersion?: 3;\n\t/** Domain-separated digest of the exact structured command descriptor. */\n\treceiptCommandSha256?: Sha256Hex;\n\t/** Lane that executed the verification command, when lane-scoped. */\n\treceiptLaneId?: string;\n\t/** Reason if evidence is missing or waived. */\n\tgapReason?: string;\n}\n\nexport interface TaskContract {\n\t/** Unique task / goal identifier. */\n\tgoalId: string;\n\t/** One-sentence completion claim. */\n\tcompletionClaim: string;\n\t/** Required evidence items. */\n\trequiredEvidence: EvidenceItem[];\n\t/** Remaining risk note. */\n\tfinalRisk: string;\n\t/** Verdict: can the task be considered done? */\n\tverdict: \"pass\" | \"fail\" | \"conditional\";\n\t/** ISO-8601 timestamp of contract creation. */\n\tcreatedAt: string;\n\t/** ISO-8601 timestamp of last update. */\n\tupdatedAt: string;\n}\n\n// ============================================================================\n// Replay Ledger\n// ============================================================================\n\nexport type ReplayEventType =\n\t| \"session_start\"\n\t| \"tool_call\"\n\t| \"tool_result\"\n\t| \"message\"\n\t| \"guardrail_decision\"\n\t| \"lane_grant\"\n\t| \"merge_attempt\"\n\t| \"merge_blocked\"\n\t| \"evidence_gathered\"\n\t| \"evidence_receipt\"\n\t| \"contract_created\"\n\t| \"contract_updated\"\n\t| \"checkpoint\"\n\t| \"error\"\n\t| \"transcript_repaired\"\n\t| \"tool_timeout\"\n\t| \"tool_late_settlement\"\n\t| \"workspace_mutation\"\n\t| \"sandbox_audit\";\n\n/**\n * Payload contract for `workspace_mutation` replay events. Emitters live in the\n * agent runtime; evidence gates consume these fail-closed: an event whose payload\n * does not provably target other paths in the same workspace root is treated as\n * relevant to every scope.\n */\nexport interface WorkspaceMutationReplayPayload {\n\t/** Absolute workspace root the mutation applies to. */\n\treadonly root: string;\n\t/** Root-relative normalized paths that were mutated; empty means unknown/whole workspace. */\n\treadonly paths: readonly string[];\n}\n\n// ============================================================================\n// Execution-bound evidence receipts (v3)\n// ============================================================================\n\ndeclare const SHA256_HEX_BRAND: unique symbol;\n\n/** A validated lowercase SHA-256 digest encoded as exactly 64 hexadecimal characters. */\nexport type Sha256Hex = string & { readonly [SHA256_HEX_BRAND]: \"sha256-hex\" };\n\nexport interface ArgvCommandDescriptor {\n\treadonly kind: \"argv\";\n\t/** Exact executable identity supplied by the caller. */\n\treadonly executable: string;\n\t/** Exact argument boundaries; values are never joined or whitespace-normalized. */\n\treadonly argv: readonly string[];\n}\n\nexport interface ShellCommandDescriptor {\n\treadonly kind: \"shell\";\n\t/** Exact shell identity supplied by the caller. */\n\treadonly shell: string;\n\t/** Exact script bytes decoded as a string; whitespace is significant. */\n\treadonly script: string;\n}\n\nexport type EvidenceCommandDescriptor = ArgvCommandDescriptor | ShellCommandDescriptor;\n\nexport interface MissingArtifactState {\n\treadonly path: string;\n\treadonly state: \"missing\";\n}\n\nexport interface FileArtifactState {\n\treadonly path: string;\n\treadonly state: \"file\";\n\treadonly sha256: Sha256Hex;\n\treadonly size: number;\n}\n\nexport type ArtifactState = MissingArtifactState | FileArtifactState;\n\n/** Trusted caller-selected workspace root and root-relative artifact set. */\nexport interface WorkspaceScope {\n\treadonly root: string;\n\treadonly artifactPaths: readonly string[];\n}\n\n/** A point-in-time digest of only the selected artifact set; not an immutable-workspace proof. */\nexport interface ArtifactSetWorkspaceFingerprint {\n\treadonly kind: \"artifact-set\";\n\treadonly scope: WorkspaceScope;\n\treadonly artifacts: readonly ArtifactState[];\n\treadonly manifestSha256: Sha256Hex;\n}\n\n/** Scope-limited Git workspace facts committed by a git-kind fingerprint. */\nexport interface GitWorkspaceState {\n\t/** Full hex object name of HEAD, or null while HEAD is unborn. */\n\treadonly headCommit: string | null;\n\t/** Sorted root-relative paths git reports changed (staged, unstaged, or untracked) within scope. */\n\treadonly changedPaths: readonly string[];\n\t/** SHA-256 of the scope-limited staged diff bytes (index vs HEAD). */\n\treadonly stagedDiffSha256: Sha256Hex;\n\t/** SHA-256 of the scope-limited unstaged diff bytes (work tree vs index). */\n\treadonly unstagedDiffSha256: Sha256Hex;\n\t/** Canonical digest committing changed paths, both diff digests, and every selected artifact state. */\n\treadonly dirtySha256: Sha256Hex;\n}\n\n/**\n * A point-in-time digest of a Git work-tree root: HEAD, scope-limited staged and\n * unstaged diffs, and direct states for every selected path. Direct states keep\n * ignored and index-flagged work-tree bytes content-bound independently of Git.\n */\nexport interface GitWorkspaceFingerprint {\n\treadonly kind: \"git\";\n\treadonly scope: WorkspaceScope;\n\treadonly artifacts: readonly ArtifactState[];\n\treadonly git: GitWorkspaceState;\n\treadonly manifestSha256: Sha256Hex;\n}\n\nexport type WorkspaceFingerprint = ArtifactSetWorkspaceFingerprint | GitWorkspaceFingerprint;\n\nexport interface EvidenceOutputDigest {\n\treadonly sha256: Sha256Hex;\n\treadonly byteCount: number;\n}\n\n/** Digests only; receipt v3 never carries raw output or excerpts. */\nexport interface EvidenceOutputCapture {\n\treadonly redactionPolicyId: string;\n\treadonly stdout: EvidenceOutputDigest;\n\treadonly stderr: EvidenceOutputDigest;\n}\n\n/** CLI form that produced one or more `[REDACTED]` placeholders in a persisted command. */\nexport type CommandRedactionPlaceholderType =\n\t| \"api-key-header\"\n\t| \"authorization-header\"\n\t| \"basic-auth\"\n\t| \"bearer-token\"\n\t| \"cli-option-inline\"\n\t| \"cli-option-value\"\n\t| \"cookie-header\"\n\t| \"env-assignment\"\n\t| \"known-token\"\n\t| \"url-credential\"\n\t| \"url-query\";\n\nexport interface CommandRedactionPlaceholder {\n\treadonly type: CommandRedactionPlaceholderType;\n\treadonly count: number;\n}\n\n/** Bounded description of the placeholders applied to a persisted redacted command. */\nexport interface CommandRedactionSummary {\n\treadonly policyId: string;\n\t/** Unique types in ascending order; empty when nothing was redacted. */\n\treadonly placeholders: readonly CommandRedactionPlaceholder[];\n}\n\n/**\n * Keyed commitment to the original (pre-redaction) command. The HMAC key is\n * process-internal and never persisted or exported, so this value is not\n * verifiable (and not brute-forceable) outside the executing trust boundary.\n */\nexport interface CommandHmacBinding {\n\treadonly algorithm: \"hmac-sha256\";\n\t/** Identifies the ephemeral process key generation, not the key itself. */\n\treadonly keyId: string;\n\t/** Per-binding random nonce; makes persisted MACs non-comparable. */\n\treadonly nonce: string;\n\treadonly mac: Sha256Hex;\n}\n\nexport type EvidenceReceiptStatus = \"passed\" | \"failed\" | \"timeout\" | \"aborted\";\n\nexport type EvidenceReceiptDisposition =\n\t| { readonly status: \"passed\"; readonly exitCode: 0 }\n\t| { readonly status: \"failed\"; readonly exitCode: number }\n\t| { readonly status: \"timeout\"; readonly exitCode: null }\n\t| { readonly status: \"aborted\"; readonly exitCode: null };\n\nexport type EvidenceExecutor = \"bash-tool\" | \"ci-runner\" | \"mcp\" | \"internal\";\n\nexport interface EvidenceReceiptCoreFields {\n\treadonly schemaVersion: 3;\n\treadonly receiptId: string;\n\treadonly goalId: string;\n\treadonly laneId?: string;\n\treadonly claim: string;\n\treadonly command: EvidenceCommandDescriptor;\n\treadonly cwd: string;\n\treadonly timeoutMs: number | null;\n\treadonly startedAt: string;\n\treadonly finishedAt: string;\n\treadonly durationMs: number;\n\treadonly workspaceBefore: WorkspaceFingerprint;\n\treadonly workspaceAfter: WorkspaceFingerprint;\n\treadonly output: EvidenceOutputCapture;\n\treadonly executor: EvidenceExecutor;\n\treadonly toolCallId?: string;\n\t/** Redaction metadata for the persisted `command` representation. */\n\treadonly commandRedaction?: CommandRedactionSummary;\n\t/** Keyed binding of the ORIGINAL command; required when placeholders were applied. */\n\treadonly commandBinding?: CommandHmacBinding;\n}\n\n/** Immutable execution facts. Envelope metadata is deliberately excluded from this core. */\nexport type EvidenceReceiptCore = EvidenceReceiptCoreFields & EvidenceReceiptDisposition;\n\nexport interface EvidenceReceiptLedgerBinding {\n\treadonly seq: number;\n\treadonly eventHash: Sha256Hex;\n}\n\n/**\n * Opaque metadata for an attestation verified by a separately configured trust anchor.\n * Its presence alone does not make a receipt trusted proof.\n */\nexport interface TrustedEvidenceAttestation {\n\treadonly attesterId: string;\n\treadonly keyId: string;\n\treadonly algorithm: \"ed25519\";\n\treadonly signature: string;\n\treadonly issuedAt: string;\n}\n\nexport interface EvidenceReceiptEnvelope {\n\treadonly coreSha256: Sha256Hex;\n\treadonly ledgerBinding?: EvidenceReceiptLedgerBinding;\n\treadonly trustedAttestation?: TrustedEvidenceAttestation;\n}\n\nexport interface EvidenceReceipt {\n\treadonly core: EvidenceReceiptCore;\n\treadonly envelope: EvidenceReceiptEnvelope;\n}\n\n/** Replay payload intentionally commits only the immutable core, avoiding a ledger/hash cycle. */\nexport interface EvidenceReceiptReplayPayload {\n\treadonly receiptId: string;\n\treadonly coreSha256: Sha256Hex;\n}\n\nexport interface ReplayEvent {\n\t/** Monotonic sequence number within a session. */\n\tseq: number;\n\t/** Event type. */\n\ttype: ReplayEventType;\n\t/** ISO-8601 timestamp. */\n\ttimestamp: string;\n\t/** Goal or session identifier. */\n\tgoalId: string;\n\t/** Optional lane identifier. */\n\tlaneId?: string;\n\t/** Event-specific payload. */\n\tpayload: unknown;\n\t/** SHA-256 of the serialized payload for integrity. */\n\tpayloadHash: string;\n\t/** eventHash of the previous event in the chain (\"genesis\" for the first event). */\n\tprevHash: string;\n\t/** SHA-256 over [seq, type, timestamp, goalId, laneId, payloadHash, prevHash]. */\n\teventHash: string;\n}\n\nexport interface ReplayLedgerFileIdentity {\n\treadonly dev: string;\n\treadonly ino: string;\n}\n\n/** Durable CAS tuple published atomically beside the replay JSONL. */\nexport interface ReplayLedgerHead {\n\treadonly fileIdentity: ReplayLedgerFileIdentity | null;\n\treadonly size: number;\n\treadonly lastSeq: number;\n\treadonly lastHash: string;\n}\n\n/** One chain- and committed-head-verified point-in-time ledger source. */\nexport interface VerifiedReplayLedgerSnapshot {\n\treadonly events: readonly ReplayEvent[];\n\treadonly head: ReplayLedgerHead;\n}\n\nexport interface ReplayLedger {\n\t/** Session / goal this ledger belongs to. */\n\tgoalId: string;\n\t/** Ordered event log. */\n\tevents: ReplayEvent[];\n\t/** Path where the ledger is persisted. */\n\tledgerPath: string;\n\t/** Last persisted sequence number. */\n\tlastPersistedSeq: number;\n}\n\n// ============================================================================\n// Merge Gates\n// ============================================================================\n\nexport type MergeGateStatus = \"open\" | \"blocked\" | \"conditional\";\n\n/** Compatibility policy for execution-bound evidence receipts. */\nexport type EvidenceReceiptMode = \"strict\" | \"prefer\" | \"legacy\";\n\nexport interface MergeGateResult {\n\t/** Gate identifier. */\n\tgateId: string;\n\t/** Current status. */\n\tstatus: MergeGateStatus;\n\t/** Human-readable reason. */\n\treason: string;\n\t/** Suggested remediation. */\n\tsuggestion?: string;\n\t/** Evidence that was checked. */\n\tevidenceChecked: EvidenceItem[];\n}\n\nexport interface EvidenceGateCheck {\n\t/** Which evidence item was checked. */\n\tevidenceClaim: string;\n\t/** Whether it is satisfied. */\n\tsatisfied: boolean;\n\t/** Reason if not satisfied. */\n\treason?: string;\n}\n\n// ============================================================================\n// Verify Reporter v2\n// ============================================================================\n\nexport interface OmkVerifyResultV2 {\n\tgoalId: string;\n\tstatus: \"completed\" | \"failed\" | \"blocked\" | \"partial\";\n\tsummary: string;\n\tchangedFiles: string[];\n\tevidence: EvidenceItem[];\n\trisks: string[];\n\tnextAction: string;\n\t/** Associated task contract. */\n\tcontract?: TaskContract;\n\t/** Replay ledger path. */\n\treplayLedgerPath?: string;\n\t/** Merge gate results. */\n\tmergeGates: MergeGateResult[];\n}\n\nexport interface CiReportV2 {\n\tgoalId: string;\n\tstatus: string;\n\tsummary: string;\n\tchangedFilesCount: number;\n\tevidenceCount: number;\n\trisks: string[];\n\tmarkdown: string;\n\tcontractVerdict?: string;\n\tmergeGateStatus?: string;\n}\n"]}
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/types/evidence.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * Evidence and verification types for OMK v0.80.3+\n *\n * Defines contracts for agent completion evidence, replay persistence,\n * merge gating, and artifact validation.\n */\n\n// ============================================================================\n// Evidence Contract\n// ============================================================================\n\nexport type EvidenceCategory =\n\t| \"feature\"\n\t| \"bugfix\"\n\t| \"refactor\"\n\t| \"research\"\n\t| \"release\"\n\t| \"security\"\n\t| \"docs\"\n\t| \"orchestration\";\n\n/** @deprecated Use protocol Observation presence plus ClaimEvaluation; do not persist mutable semantic state. */\nexport type EvidenceStatus = \"pending\" | \"gathering\" | \"satisfied\" | \"failed\" | \"waived\";\n\nexport interface EvidenceItem {\n\t/** What this evidence proves. */\n\tclaim: string;\n\t/** Category of the task. */\n\tcategory: EvidenceCategory;\n\t/** Path to artifact or command that produced it. */\n\tartifactPath?: string;\n\t/** Command that can reproduce the evidence. */\n\tverificationCommand?: string;\n\t/** SHA-256 of the artifact for integrity. */\n\thash?: string;\n\t/** When the evidence was gathered. */\n\ttimestamp: string;\n\t/** @deprecated Legacy mutable state. New code records an immutable protocol Observation instead. */\n\tstatus: EvidenceStatus;\n\t/** Receipt v3 metadata consumed by receipt-aware evidence gates. */\n\treceiptId?: string;\n\treceiptSchemaVersion?: 3;\n\t/** Domain-separated digest of the exact structured command descriptor. */\n\treceiptCommandSha256?: Sha256Hex;\n\t/** Lane that executed the verification command, when lane-scoped. */\n\treceiptLaneId?: string;\n\t/** Reason if evidence is missing or waived. */\n\tgapReason?: string;\n}\n\nexport interface TaskContract {\n\t/** Unique task / goal identifier. */\n\tgoalId: string;\n\t/** One-sentence completion claim. */\n\tcompletionClaim: string;\n\t/** Required evidence items. */\n\trequiredEvidence: EvidenceItem[];\n\t/** Remaining risk note. */\n\tfinalRisk: string;\n\t/** @deprecated Derive `EvaluationResult.semanticVerdict` from current observations instead. */\n\tverdict: \"pass\" | \"fail\" | \"conditional\";\n\t/** ISO-8601 timestamp of contract creation. */\n\tcreatedAt: string;\n\t/** ISO-8601 timestamp of last update. */\n\tupdatedAt: string;\n}\n\n// ============================================================================\n// Replay Ledger\n// ============================================================================\n\nexport type ReplayEventType =\n\t| \"session_start\"\n\t| \"tool_call\"\n\t| \"tool_result\"\n\t| \"message\"\n\t| \"guardrail_decision\"\n\t| \"lane_grant\"\n\t| \"merge_attempt\"\n\t| \"merge_blocked\"\n\t| \"evidence_gathered\"\n\t| \"evidence_receipt\"\n\t| \"contract_created\"\n\t| \"contract_updated\"\n\t| \"checkpoint\"\n\t| \"error\"\n\t| \"transcript_repaired\"\n\t| \"tool_timeout\"\n\t| \"tool_late_settlement\"\n\t| \"workspace_mutation\"\n\t| \"sandbox_audit\";\n\n/**\n * Payload contract for `workspace_mutation` replay events. Emitters live in the\n * agent runtime; evidence gates consume these fail-closed: an event whose payload\n * does not provably target other paths in the same workspace root is treated as\n * relevant to every scope.\n */\nexport interface WorkspaceMutationReplayPayload {\n\t/** Absolute workspace root the mutation applies to. */\n\treadonly root: string;\n\t/** Root-relative normalized paths that were mutated; empty means unknown/whole workspace. */\n\treadonly paths: readonly string[];\n}\n\n// ============================================================================\n// Execution-bound evidence receipts (v3)\n// ============================================================================\n\ndeclare const SHA256_HEX_BRAND: unique symbol;\n\n/** A validated lowercase SHA-256 digest encoded as exactly 64 hexadecimal characters. */\nexport type Sha256Hex = string & { readonly [SHA256_HEX_BRAND]: \"sha256-hex\" };\n\nexport interface ArgvCommandDescriptor {\n\treadonly kind: \"argv\";\n\t/** Exact executable identity supplied by the caller. */\n\treadonly executable: string;\n\t/** Exact argument boundaries; values are never joined or whitespace-normalized. */\n\treadonly argv: readonly string[];\n}\n\nexport interface ShellCommandDescriptor {\n\treadonly kind: \"shell\";\n\t/** Exact shell identity supplied by the caller. */\n\treadonly shell: string;\n\t/** Exact script bytes decoded as a string; whitespace is significant. */\n\treadonly script: string;\n}\n\nexport type EvidenceCommandDescriptor = ArgvCommandDescriptor | ShellCommandDescriptor;\n\nexport interface MissingArtifactState {\n\treadonly path: string;\n\treadonly state: \"missing\";\n}\n\nexport interface FileArtifactState {\n\treadonly path: string;\n\treadonly state: \"file\";\n\treadonly sha256: Sha256Hex;\n\treadonly size: number;\n}\n\nexport type ArtifactState = MissingArtifactState | FileArtifactState;\n\n/** Trusted caller-selected workspace root and root-relative artifact set. */\nexport interface WorkspaceScope {\n\treadonly root: string;\n\treadonly artifactPaths: readonly string[];\n}\n\n/** A point-in-time digest of only the selected artifact set; not an immutable-workspace proof. */\nexport interface ArtifactSetWorkspaceFingerprint {\n\treadonly kind: \"artifact-set\";\n\treadonly scope: WorkspaceScope;\n\treadonly artifacts: readonly ArtifactState[];\n\treadonly manifestSha256: Sha256Hex;\n}\n\n/** Scope-limited Git workspace facts committed by a git-kind fingerprint. */\nexport interface GitWorkspaceState {\n\t/** Full hex object name of HEAD, or null while HEAD is unborn. */\n\treadonly headCommit: string | null;\n\t/** Sorted root-relative paths git reports changed (staged, unstaged, or untracked) within scope. */\n\treadonly changedPaths: readonly string[];\n\t/** SHA-256 of the scope-limited staged diff bytes (index vs HEAD). */\n\treadonly stagedDiffSha256: Sha256Hex;\n\t/** SHA-256 of the scope-limited unstaged diff bytes (work tree vs index). */\n\treadonly unstagedDiffSha256: Sha256Hex;\n\t/** Canonical digest committing changed paths, both diff digests, and every selected artifact state. */\n\treadonly dirtySha256: Sha256Hex;\n}\n\n/**\n * A point-in-time digest of a Git work-tree root: HEAD, scope-limited staged and\n * unstaged diffs, and direct states for every selected path. Direct states keep\n * ignored and index-flagged work-tree bytes content-bound independently of Git.\n */\nexport interface GitWorkspaceFingerprint {\n\treadonly kind: \"git\";\n\treadonly scope: WorkspaceScope;\n\treadonly artifacts: readonly ArtifactState[];\n\treadonly git: GitWorkspaceState;\n\treadonly manifestSha256: Sha256Hex;\n}\n\nexport type WorkspaceFingerprint = ArtifactSetWorkspaceFingerprint | GitWorkspaceFingerprint;\n\nexport interface EvidenceOutputDigest {\n\treadonly sha256: Sha256Hex;\n\treadonly byteCount: number;\n}\n\n/** Digests only; receipt v3 never carries raw output or excerpts. */\nexport interface EvidenceOutputCapture {\n\treadonly redactionPolicyId: string;\n\treadonly stdout: EvidenceOutputDigest;\n\treadonly stderr: EvidenceOutputDigest;\n}\n\n/** CLI form that produced one or more `[REDACTED]` placeholders in a persisted command. */\nexport type CommandRedactionPlaceholderType =\n\t| \"api-key-header\"\n\t| \"authorization-header\"\n\t| \"basic-auth\"\n\t| \"bearer-token\"\n\t| \"cli-option-inline\"\n\t| \"cli-option-value\"\n\t| \"cookie-header\"\n\t| \"env-assignment\"\n\t| \"known-token\"\n\t| \"url-credential\"\n\t| \"url-query\";\n\nexport interface CommandRedactionPlaceholder {\n\treadonly type: CommandRedactionPlaceholderType;\n\treadonly count: number;\n}\n\n/** Bounded description of the placeholders applied to a persisted redacted command. */\nexport interface CommandRedactionSummary {\n\treadonly policyId: string;\n\t/** Unique types in ascending order; empty when nothing was redacted. */\n\treadonly placeholders: readonly CommandRedactionPlaceholder[];\n}\n\n/**\n * Keyed commitment to the original (pre-redaction) command. The HMAC key is\n * process-internal and never persisted or exported, so this value is not\n * verifiable (and not brute-forceable) outside the executing trust boundary.\n */\nexport interface CommandHmacBinding {\n\treadonly algorithm: \"hmac-sha256\";\n\t/** Identifies the ephemeral process key generation, not the key itself. */\n\treadonly keyId: string;\n\t/** Per-binding random nonce; makes persisted MACs non-comparable. */\n\treadonly nonce: string;\n\treadonly mac: Sha256Hex;\n}\n\nexport type EvidenceReceiptStatus = \"passed\" | \"failed\" | \"timeout\" | \"aborted\";\n\nexport type EvidenceReceiptDisposition =\n\t| { readonly status: \"passed\"; readonly exitCode: 0 }\n\t| { readonly status: \"failed\"; readonly exitCode: number }\n\t| { readonly status: \"timeout\"; readonly exitCode: null }\n\t| { readonly status: \"aborted\"; readonly exitCode: null };\n\nexport type EvidenceExecutor = \"bash-tool\" | \"ci-runner\" | \"mcp\" | \"internal\";\n\nexport interface EvidenceReceiptCoreFields {\n\treadonly schemaVersion: 3;\n\treadonly receiptId: string;\n\treadonly goalId: string;\n\treadonly laneId?: string;\n\treadonly claim: string;\n\treadonly command: EvidenceCommandDescriptor;\n\treadonly cwd: string;\n\treadonly timeoutMs: number | null;\n\treadonly startedAt: string;\n\treadonly finishedAt: string;\n\treadonly durationMs: number;\n\treadonly workspaceBefore: WorkspaceFingerprint;\n\treadonly workspaceAfter: WorkspaceFingerprint;\n\treadonly output: EvidenceOutputCapture;\n\treadonly executor: EvidenceExecutor;\n\treadonly toolCallId?: string;\n\t/** Redaction metadata for the persisted `command` representation. */\n\treadonly commandRedaction?: CommandRedactionSummary;\n\t/** Keyed binding of the ORIGINAL command; required when placeholders were applied. */\n\treadonly commandBinding?: CommandHmacBinding;\n}\n\n/** Immutable execution facts. Envelope metadata is deliberately excluded from this core. */\nexport type EvidenceReceiptCore = EvidenceReceiptCoreFields & EvidenceReceiptDisposition;\n\nexport interface EvidenceReceiptLedgerBinding {\n\treadonly seq: number;\n\treadonly eventHash: Sha256Hex;\n}\n\n/**\n * Opaque metadata for an attestation verified by a separately configured trust anchor.\n * Its presence alone does not make a receipt trusted proof.\n */\nexport interface TrustedEvidenceAttestation {\n\treadonly attesterId: string;\n\treadonly keyId: string;\n\treadonly algorithm: \"ed25519\";\n\treadonly signature: string;\n\treadonly issuedAt: string;\n}\n\nexport interface EvidenceReceiptEnvelope {\n\treadonly coreSha256: Sha256Hex;\n\treadonly ledgerBinding?: EvidenceReceiptLedgerBinding;\n\treadonly trustedAttestation?: TrustedEvidenceAttestation;\n}\n\nexport interface EvidenceReceipt {\n\treadonly core: EvidenceReceiptCore;\n\treadonly envelope: EvidenceReceiptEnvelope;\n}\n\n/** Serializer contract used to derive a replay event's payload hash. */\nexport type ReplayPayloadHashAlgorithm = \"json-stringify-v1\" | \"jcs-rfc8785-v2\";\n\n/** Replay payload intentionally commits only the immutable core, avoiding a ledger/hash cycle. */\nexport interface EvidenceReceiptReplayPayload {\n\treadonly receiptId: string;\n\treadonly coreSha256: Sha256Hex;\n}\n\nexport interface ReplayEvent {\n\t/** Monotonic sequence number within a session. */\n\tseq: number;\n\t/** Event type. */\n\ttype: ReplayEventType;\n\t/** ISO-8601 timestamp. */\n\ttimestamp: string;\n\t/** Goal or session identifier. */\n\tgoalId: string;\n\t/** Optional lane identifier. */\n\tlaneId?: string;\n\t/** Event-specific payload. */\n\tpayload: unknown;\n\t/** SHA-256 of the serialized payload for integrity. */\n\tpayloadHash: string;\n\t/**\n\t * Serializer contract for `payloadHash`. Missing means the legacy\n\t * `json-stringify-v1` algorithm; new events use `jcs-rfc8785-v2`.\n\t */\n\tpayloadHashAlgorithm?: ReplayPayloadHashAlgorithm;\n\t/** eventHash of the previous event in the chain (\"genesis\" for the first event). */\n\tprevHash: string;\n\t/** SHA-256 over chain metadata, the optional payload hash algorithm, payloadHash, and prevHash. */\n\teventHash: string;\n}\n\nexport interface ReplayLedgerFileIdentity {\n\treadonly dev: string;\n\treadonly ino: string;\n}\n\n/** Durable CAS tuple published atomically beside the replay JSONL. */\nexport interface ReplayLedgerHead {\n\treadonly fileIdentity: ReplayLedgerFileIdentity | null;\n\treadonly size: number;\n\treadonly lastSeq: number;\n\treadonly lastHash: string;\n}\n\n/** One chain- and committed-head-verified point-in-time ledger source. */\nexport interface VerifiedReplayLedgerSnapshot {\n\treadonly events: readonly ReplayEvent[];\n\treadonly head: ReplayLedgerHead;\n}\n\nexport interface ReplayLedger {\n\t/** Session / goal this ledger belongs to. */\n\tgoalId: string;\n\t/** Ordered event log. */\n\tevents: ReplayEvent[];\n\t/** Path where the ledger is persisted. */\n\tledgerPath: string;\n\t/** Last persisted sequence number. */\n\tlastPersistedSeq: number;\n}\n\n// ============================================================================\n// Merge Gates\n// ============================================================================\n\nexport type MergeGateStatus = \"open\" | \"blocked\" | \"conditional\";\n\n/** Compatibility policy for execution-bound evidence receipts. */\nexport type EvidenceReceiptMode = \"strict\" | \"prefer\" | \"legacy\";\n\nexport interface MergeGateResult {\n\t/** Gate identifier. */\n\tgateId: string;\n\t/** Current status. */\n\tstatus: MergeGateStatus;\n\t/** Human-readable reason. */\n\treason: string;\n\t/** Suggested remediation. */\n\tsuggestion?: string;\n\t/** Evidence that was checked. */\n\tevidenceChecked: EvidenceItem[];\n}\n\nexport interface EvidenceGateCheck {\n\t/** Which evidence item was checked. */\n\tevidenceClaim: string;\n\t/** Whether it is satisfied. */\n\tsatisfied: boolean;\n\t/** Reason if not satisfied. */\n\treason?: string;\n}\n\n// ============================================================================\n// Verify Reporter v2\n// ============================================================================\n\nexport interface OmkVerifyResultV2 {\n\tgoalId: string;\n\tstatus: \"completed\" | \"failed\" | \"blocked\" | \"partial\";\n\tsummary: string;\n\tchangedFiles: string[];\n\tevidence: EvidenceItem[];\n\trisks: string[];\n\tnextAction: string;\n\t/** Associated task contract. */\n\tcontract?: TaskContract;\n\t/** Replay ledger path. */\n\treplayLedgerPath?: string;\n\t/** Merge gate results. */\n\tmergeGates: MergeGateResult[];\n}\n\nexport interface CiReportV2 {\n\tgoalId: string;\n\tstatus: string;\n\tsummary: string;\n\tchangedFilesCount: number;\n\tevidenceCount: number;\n\trisks: string[];\n\tmarkdown: string;\n\tcontractVerdict?: string;\n\tmergeGateStatus?: string;\n}\n"]}

package/docs/adaptorch-preview-spec.md

@@ -14,7 +14,7 @@
 | `path_hints` | string[] | cwd, owned paths, globs | Optional; used for domain triggers and write-scope checks. |
 | `upstream_tags` | string[] | goal id, lane role, preset | e.g. `grok-adaptorch-prod`, `omk-planner`. |
 | `payload_shape` | object | planner / DAG artifact | Sanitized shape for topology preview only — **no** raw prompts, secrets, or session ids. |
-| `provider_profile` | enum | session | `grok-oauth-proxy` \| `default` \| other registered provider. |
+| `provider_profile` | enum | session | `xai` \| `default` \| other registered provider. |
 | `adaptorch_transport` | optional | MCP grant | If absent, preview runs **local-only** (OMK compose + deterministic fallbacks). |
 | `lane_grants[]` | object[] | root coordinator | Each: scope, authority, skills, MCP, acceptance, evidence path. |
 | `budget_caps` | object | loop / goal | `max_lanes`, `max_dispatch_preview_calls`, wall-clock cap (immutable per preview instance). |

package/docs/adaptorch-preview.md

@@ -34,7 +34,7 @@ Related packages:
 
 관련 경로:
 
-- 실험 WPL 루프: `packages/adaptorch-wpl/` (설계 단계, 기본 CLI 미연결).
+- WPL 루프: `packages/adaptorch-wpl/` (0.91.0부터 안정화, CLI 런타임 의존성으로 포함).
 - 어드바이저리 브리지(기본 비활성): `packages/coding-agent/src/core/adaptorch-bridge.ts`.
 - Grok 세션: [grok-harness.md](./grok-harness.md).
 
@@ -73,7 +73,7 @@ Models execute; **OMK routes, verifies, measures, and controls**. AdaptTorch Pre
 
 ## Grok sessions
 
-For provider presets, Imagine tool discipline, and when to load AdaptOrch skills on Grok chat models, see **[grok-harness.md](./grok-harness.md)** (canonical playbook: `~/.omk/agent/grok.md`).
+For provider presets, Imagine tool discipline, and when to load AdaptOrch skills on Grok chat models, see the canonical **[Grok harness guide](./grok-harness.md)**.
 
 ## Correctness Wall (preview)
 

package/docs/book-to-skill.md

@@ -0,0 +1,79 @@
+# Book to Skill
+
+`omk-book-to-skill` is an optional OMK package for turning documents into reusable Agent Skills. It is not part of the OMK core install.
+
+## Install
+
+Pin the package when installing from npm:
+
+```bash
+omk install npm:omk-book-to-skill@0.96.1
+```
+
+In a source checkout:
+
+```bash
+npm run build --workspace packages/book-to-skill
+omk install ./packages/book-to-skill
+```
+
+Run `/reload` after installation if the current session was already open.
+
+## Requirements
+
+- Node.js 22.19 or newer, as required by OMK
+- Python 3.9 or newer for document extraction
+- Optional extractors in a user-managed Python environment
+
+The package does not add Docling or other Python dependencies to OMK. Plain text and Markdown use the Python standard library; PDF, EPUB, DOCX, RTF, and technical extraction select an available upstream extractor and preserve its confirmation/fallback behavior.
+
+## Commands
+
+```text
+/book-to-skill-compile <source...>
+/book-to-skill-update <existing-skill> <new-source...>
+/book-to-skill-verify <generated-skill-directory>
+```
+
+The compile and update commands start an agent turn with the bundled workflow. The package also exposes the ordinary skill commands:
+
+```text
+/skill:book-to-skill <source...>
+!book-to-skill <source...>
+```
+
+Generated personal skills default to `~/.omk/agent/skills/`; project skills use `.omk/skills/`. The workflow asks when scope is ambiguous.
+
+## Provenance and verification
+
+After generation, the skill runs the upstream advisory scanner and records `.book-to-skill-provenance.json`. The bundled workflow resolves `scripts/provenance.mjs` from the skill directory, so it does not depend on an npm bin path. If `omk-book-to-skill` is on `PATH`, the standalone CLI can repeat the checks:
+
+```bash
+omk-book-to-skill record \
+  --skill ~/.omk/agent/skills/example \
+  --source ./book.pdf
+
+omk-book-to-skill verify \
+  --skill ~/.omk/agent/skills/example \
+  --source ./book.pdf
+```
+
+Repeat `--source` in the original order. During Update / Fold-in, use `record --merge-sources` to retain prior source digests.
+
+Exit codes:
+
+- `0`: artifact hashes, supplied source hashes, and advisory scan passed
+- `1`: mismatch or scanner finding
+- `2`: usage error or incomplete verification, such as omitted source files or unavailable Python
+
+`/book-to-skill-verify` checks artifact integrity and the advisory scanner. Use the CLI with `--source` to recheck source bytes.
+
+## Trust boundary
+
+The provenance file is an unsigned local integrity record. It detects byte changes after compilation, but does not establish authorship, redistribution rights, trusted attestation, or semantic claim-to-source grounding. Source documents remain untrusted data; the workflow must not execute instructions embedded in them.
+
+## Supply chain
+
+The package pins the upstream runtime snapshot at commit `c4c5e948caaa912c9e2024b925a7cdee9237b0c0` (`book-to-skill` `1.4.0`). `upstream.json` records SHA-256 digests for every vendored file. Python packages remain external to the npm package and OMK core.
+
+See [Skills](skills.md) for discovery and invocation and [OMK Packages](packages.md) for package management.

package/docs/compaction.md

@@ -77,6 +77,16 @@ If the reserved budget exceeds the context window, the reserve boundary is ignor
 
 You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary. If a run is active, manual compaction waits for abort-driven terminal events, including tool results, to persist before capturing the transcript.
 
+### Overflow Recovery
+
+If a provider rejects a request for context overflow despite OMK's projection, OMK removes the rejected assistant message from retry context, compacts, and retries automatically. Recovery is bounded and staged:
+
+1. The first recovery uses the configured compaction budgets.
+2. If that retry also overflows, OMK recompacts from the previous kept boundary with `reserveTokens`, `reservedOutputTokens`, and `keepRecentTokens` capped at 4096, then retries once more.
+3. A third overflow stops recovery and reports an actionable error instead of looping.
+
+Compaction cannot shrink a latest user message that alone exceeds the provider's effective context window; split that input or select a model with a larger effective window.
+
 ### Model Selection
 
 By default, compaction uses the active session model. Set `compaction.model` to an authenticated canonical `provider/model` reference when summaries should use a different model. For example, `zai/glm-5.2` keeps an interactive Claude session while using GLM only for auto-compaction and `/compact`.

package/docs/containerization.md

@@ -8,11 +8,15 @@ The default `enforce` profile wraps each local bash spawn with macOS `sandbox-ex
 
 - macOS requires `sandbox-exec`.
 - Linux requires `bwrap` and unprivileged user namespaces.
+- Backend probing is lazy. `AgentSession` caches the first automatic probe for the session lifetime. `createLocalBashOperations({ sandboxPolicy })` caches one probe per operations instance when the preflight omits `backend`.
+- `sandbox.backend_missing` includes the concrete cause: missing `bwrap` or `sandbox-exec`, disabled unprivileged user namespaces, both Linux failures, or an unsupported host platform.
 - `OMK_BASH_SANDBOX=audit` explicitly selects the unwrapped, ledger-only compatibility mode.
 - `OMK_BASH_SANDBOX=0` or `off` explicitly disables the preflight.
 
 The workspace-write profile protects host paths from writes; it is not a read-confidentiality boundary. It also does not cover injected or remote `BashOperations`, custom `createBashTool()` calls without a `sandboxPolicy`, extension tools, or other OMK file tools. Use one of the whole-process or delegated patterns below when that broader boundary is required.
 
+When a verified outer whole-process sandbox owns the boundary, set `OMK_BASH_SANDBOX=off` only inside that sandbox to avoid unsupported nested `bwrap` or `sandbox-exec`. This disables OMK's inner bash wrapper; it does not create isolation. Do not copy this override to host-run OMK.
+
 There are two general isolation options:
 
 1. run the whole `omk` process inside an isolated environment, or
@@ -102,10 +106,15 @@ RUN apt-get update \
   && rm -rf /var/lib/apt/lists/*
 RUN npm install -g --ignore-scripts open-multi-agent-kit
 
+# Docker owns the whole-process boundary; avoid a nested bwrap requirement.
+ENV OMK_BASH_SANDBOX=off
+
 WORKDIR /workspace
 ENTRYPOINT ["omk"]
 ```
 
+The `OMK_BASH_SANDBOX=off` override is intentional in this image because Docker contains the whole `omk` process. The image does not install `bwrap`, so leaving the inner default at `enforce` would make built-in bash fail closed.
+
 Build and run:
 
 ```bash

package/docs/docs.json

@@ -19,6 +19,14 @@
           "title": "Providers",
           "path": "providers.md"
         },
+        {
+          "title": "Provider Resilience",
+          "path": "provider-resilience.md"
+        },
+        {
+          "title": "Native xAI Grok",
+          "path": "grok-harness.md"
+        },
         {
           "title": "Containerization",
           "path": "containerization.md"
@@ -60,6 +68,10 @@
           "title": "Skills",
           "path": "skills.md"
         },
+        {
+          "title": "Book to Skill",
+          "path": "book-to-skill.md"
+        },
         {
           "title": "MCP",
           "path": "mcp.md"
@@ -96,12 +108,16 @@
       ]
     },
     {
-      "title": "Programmatic Usage",
+      "title": "Automation and Control",
       "items": [
         {
-          "title": "SDK",
+          "title": "SDK & Session Control",
           "path": "sdk.md"
         },
+        {
+          "title": "Run Protocol & Durable Goals",
+          "path": "run-protocol.md"
+        },
         {
           "title": "RPC Mode",
           "path": "rpc.md"

package/docs/environment-variables.md

@@ -6,7 +6,7 @@ OMK uses environment variables in three ways:
 - OMK sets `OMK_CODING_AGENT` so child processes can detect that they run inside OMK.
 - Commands run by the LLM-callable bash tool receive `PI_*` variables describing the current session.
 
-Provider API-key variables are documented separately in [Providers](providers.md).
+Provider API-key variables are documented separately in [Providers](providers.md). `XAI_API_KEY` is an xAI Platform API-billing credential; it is not the OAuth credential created by `/login` and cannot populate weekly SuperGrok usage/reset.
 
 ## Process Marker
 
@@ -22,7 +22,7 @@ Commands run by the bash tool receive the current session state (the `PI_*` name
 | `PI_SESSION_FILE` | Absolute path to the current session JSONL file; unset for ephemeral sessions |
 | `PI_PROVIDER` | Currently selected model provider |
 | `PI_MODEL` | Currently selected model ID |
-| `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
+| `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `ultra` |
 
 The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next bash command without restarting OMK. `PI_PROVIDER` and `PI_MODEL` identify the selected OMK model, not a different upstream model that a router may choose internally.
 
@@ -71,7 +71,7 @@ When disabled, OMK removes inherited values for these variables so nested OMK pr
 
 ## OMK Process Configuration
 
-These variables are read by OMK itself:
+These variables are read by OMK itself. The four built-in harness flags below are enabled when unset. Any of `0`, `false`, `off`, `disable`, or `disabled` disables the corresponding built-in; matching is case-insensitive and ignores surrounding whitespace. `--no-extensions` does not disable these first-party built-ins.
 
 | Variable | Description |
 | --- | --- |
@@ -85,9 +85,16 @@ These variables are read by OMK itself:
 | `OMK_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
 | `OMK_CONTEXT_GOVERNOR` | Configure the context-budget governor; see `context-budget-*` sources |
 | `OMK_VERIFIED_BASH` | Default-on verified bash adapter for AgentSession/CLI bash. Set to `0` to opt out and use the legacy unverified path (see [SDK — Evidence and Verification](sdk.md#evidence-and-verification)) |
-| `OMK_BASH_SANDBOX` | Session bash sandbox mode: `enforce` by default (macOS `sandbox-exec` / Linux `bwrap`, workspace/temp writes only, network disabled, fail closed without a backend); explicit `audit` keeps an unwrapped ledger-only compatibility path; `0`/`off` disables the preflight. Unknown values resolve to `enforce` |
+| `OMK_BASH_SANDBOX` | AgentSession built-in local bash mode. Unset or unknown values select `enforce`: macOS `sandbox-exec` or Linux `bwrap`, workspace/temp writes only, network disabled, and fail closed without a usable backend. Explicit `audit` selects the unwrapped ledger-only path; `0`/`off` disables the preflight. Use `off` only when a verified outer whole-process sandbox owns isolation; it does not isolate OMK by itself |
 | `LIVE_E2E` | Test-only: keep provider credentials so live-API e2e suites run on purpose (default scrubbed for hermetic tests) |
 | `OMK_OMP_SEAMS` | Default-on OMP pure seams for `read`/`grep`. Set to `0` to opt out |
+| `OMK_IDENTICAL_LOOP` | Default-on consecutive-loop guard. Warns from the third identical `tool+args` call and blocks the sixth. Set a disabling value to opt out |
+| `OMK_TOOL_PAIR_REPAIR` | Default-on outbound-context repair. Removes unmatched tool-use and tool-result blocks before provider requests without rewriting the transcript. Set a disabling value to opt out |
+| `OMK_PROMPT_PRESET` | Default-on model-specific guidance for supported Claude/Anthropic, Kimi, GLM/ZAI, and Grok/xAI models. Set a disabling value to opt out |
+| `OMK_CLAUDE_CONTEXT_FILES` | Claude models omit discovered `AGENTS.md` and `CLAUDE.md` files by default to prevent unrelated context from causing provider false positives. Set to `1`, `true`, `on`, or `yes` to restore them |
+| `OMK_GOAL_CONTROLLER` | Default-on working-directory `/goal` command and automatic continuation. Goals created by `/goal` use an eight-round cap. Set a disabling value to opt out |
+| `OMK_GROK_HARNESS` | Default-on native `xai` provider dispatch to the `grok-harness` loadout. `0`, `false`, `off`, or `no` disables it |
+| `OMK_DOMAIN_ROUTING` | Set to `1` to enable general prompt-based domain routing. Native xAI harness dispatch does not require it |
 | `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
 | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
 

package/docs/extensions.md

@@ -1711,7 +1711,20 @@ Use `promptGuidelines` to add tool-specific bullets to the default system prompt
 
 Note: Some models are idiots and include the @ prefix in tool path arguments. Built-in tools strip a leading @ before resolving paths. If your custom tool accepts a path, normalize a leading @ as well.
 
-If your custom tool mutates files, use `withFileMutationQueue()` so it participates in the same per-file queue as built-in `edit` and `write`. This matters because tool calls run in parallel by default. Without the queue, two tools can read the same old file contents, compute different updates, and then whichever write lands last overwrites the other.
+For concurrent custom tools, set `executionMode: "parallel"` and provide a `resourceClaims(args, context)` resolver. OMK's `dag-v2` scheduler requires extension claims and runs only calls whose claims do not conflict. Claims use `kind: "path" | "session" | "terminal" | "network" | "global"`, a non-empty `key`, and `access: "read" | "write"` (`"exclusive"` is also valid for non-path claims). Return `"exclusive"` to run alone. Empty, malformed, rejected, or missing extension claims fail closed to exclusive scheduling.
+
+```typescript
+omk.registerTool({
+  name: "isolated_task",
+  // ...
+  executionMode: "parallel",
+  resourceClaims: (_args, { toolCallId }) => [
+    { kind: "session", key: `isolated-task:${toolCallId}`, access: "write" },
+  ],
+});
+```
+
+If your custom tool mutates files, use `withFileMutationQueue()` so it participates in the same per-file queue as built-in `edit` and `write`. This matters because tool calls can run in parallel. Without the queue, two tools can read the same old file contents, compute different updates, and then whichever write lands last overwrites the other.
 
 Example failure case: your custom tool edits `foo.ts` while built-in `edit` also changes `foo.ts` in the same assistant turn. If your tool does not participate in the queue, both can read the original `foo.ts`, apply separate changes, and one of those changes is lost.
 

package/docs/grok-harness.md

@@ -1,6 +1,6 @@
 # Grok harness
 
-This page is the project-local operator guide for running OMK with the xAI OAuth proxy. The canonical Grok playbook remains `~/.omk/agent/grok.md`; keep this page as a short routing and preset reference, not a duplicate source of truth.
+This page is the canonical operator guide for the native `xai` provider. Use `/login` for xAI subscription OAuth or `XAI_API_KEY` for xAI Platform API billing. A user-local `~/.omk/agent/grok.md` may add operator notes, but it is not the portable product contract.
 
 ## Presets
 
@@ -8,27 +8,50 @@ Project presets live in `.omk/presets.json` and are consumed by the preset exten
 
 | Preset | Provider | Model | Thinking | Use |
 | --- | --- | --- | --- | --- |
-| `grok-verified` | `grok-oauth-proxy` | `grok-4.5` | `high` | Default Grok text-chat baseline (local OAuth proxy). |
-| `grok-adaptorch-prod` | `grok-oauth-proxy` | `grok-4.5` | `high` | Same baseline, with AdaptOrch reserved for explicit DAG routing, synthesis, or consistency-verification lanes. |
+| `grok-verified` | `xai` | `grok-4.5` | `high` | Default native xAI text-chat baseline. |
+| `grok-adaptorch-prod` | `xai` | `grok-4.5` | `high` | Same baseline, with AdaptOrch reserved for explicit DAG routing, synthesis, or consistency-verification lanes. |
 
-Register the provider in `~/.omk/agent/models.json` with `baseUrl: http://127.0.0.1:9996/v1` and chat models including `grok-4.5` (and optional fallbacks such as `grok-4.3`). Loopback proxy accepts a dummy `apiKey`; do not put OAuth tokens in models.json. Confirm proxy health with `curl -fsS http://127.0.0.1:9996/health` before long sessions.
+## Authentication and weekly usage
 
-Suggested TUI flow:
+Both authentication methods use provider ID `xai`. See [Providers](providers.md#xai-grok) for the authoritative OAuth, API-key, credential-storage, and weekly-usage behavior. Do not put OAuth access or refresh tokens in `models.json`.
 
-1. Run `/grok` to inject the pointer to `~/.omk/agent/grok.md`.
+## Thinking tiers
+
+OMK sends the mapped value as xAI `reasoning_effort`.
+
+| OMK tier | `grok-4.6` | `grok-4.5` | `grok-4.3` |
+| --- | --- | --- | --- |
+| `off` | unavailable | unavailable | `none` |
+| `minimal` | unavailable | unavailable | unavailable |
+| `low` | `low` | `low` | `low` |
+| `medium` | `medium` | `medium` | `medium` |
+| `high` | `high` | `high` | `high` |
+| `xhigh` | `xhigh` | unavailable | unavailable |
+| `max` | `xhigh` | `high` | `high` |
+| `ultra` | `xhigh` | `high` | `high` |
+
+Grok 4.6 and 4.5 cannot disable reasoning. Grok 4.3 supports `off` by sending `reasoning_effort: "none"`.
+
+## Migration from `grok-oauth-proxy`
+
+The proxy provider is retired. Remove stale `grok-oauth-proxy` entries from `models.json` and `auth.json`, then use native `xai`. OMK ignores stale entries during migration.
+
+## Suggested TUI flow
+
+1. Run `/grok` only when you want to load the optional local operator overlay.
 2. Select `/preset grok-verified` for normal chat/coding work.
 3. Select `/preset grok-adaptorch-prod` only when the task has an explicit DAG, routing, or synthesis objective.
 4. Keep credentials and OAuth material out of preset JSON.
 
 ## Domain routing
 
-Domain routing is opt-in. Start OMK with `OMK_DOMAIN_ROUTING=1` when you want the domain router to compose the role loadout with a domain profile before dispatch. With the variable unset or any value other than `1`, the domain dispatch layer does not apply a domain access policy.
+Selecting the native `xai` provider auto-applies the `grok-harness` loadout by default; this does not require `OMK_DOMAIN_ROUTING=1`. Set `OMK_GROK_HARNESS=0` to disable that provider-specific dispatch.
 
-The router selects one of the documented domain profiles under [`loadout-domains/`](loadout-domains/README.md), then composes that profile with the active role loadout. Grok presets do not replace this mechanism; they only set provider, model, thinking level, and instruction pointers.
+General prompt-based domain routing is separate and opt-in through `OMK_DOMAIN_ROUTING=1`. It selects one of the profiles under [`loadout-domains/`](loadout-domains/README.md) and composes it with the active role loadout. Grok presets only set provider, model, thinking level, and instruction pointers.
 
-## Composer model
+## Chat model selection
 
-`grok-composer-2.5-fast` is a valid Grok chat model, but the project presets keep `grok-4.5` as the default. Use Composer only for explicit Composer validation or comparison work. `grok-4.3` remains a supported fallback chat model. Do not use `grok-imagine-*` ids as chat models; session `setModel` / `prompt` reject them on `grok-oauth-proxy`.
+The native `xai` catalog includes `grok-4.6`, `grok-4.5`, and `grok-4.3`. Use `/model` or `omk --list-models xai` for the current complete list. Project presets intentionally pin the verified `grok-4.5` baseline, and `grok-4.3` remains a fallback. Do not use `grok-imagine-*` IDs as chat models.
 
 ## Imagine tools
 
@@ -58,6 +81,6 @@ Use the normal OMK lane grant model: grant the smallest skill and MCP surface th
 
 Relevant evidence hooks for Grok lanes are `pre-shell-guard`, `protect-secrets`, `typecheck-after-edit`, and `stop-verify`. Hook output is incremental evidence; code changes still need the project's required final verification command before claiming type/lint cleanliness.
 
-## Canonical reference
+## Local overlay
 
-For proxy health checks, chat model rules, Imagine tool behavior, Hermes parity, Telegram behavior, and unsafe `GROK.MD` handling, read `~/.omk/agent/grok.md`.
+`/grok` may load `~/.omk/agent/grok.md` for host-specific Hermes, Telegram, or Imagine notes. Treat that file as optional local configuration; this page and the current provider documentation remain authoritative.

package/docs/index.md

@@ -1,6 +1,6 @@
 # OMK Documentation
 
-OMK is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and omk packages.
+OMK is a provider-neutral coding agent with multi-agent orchestration, durable harness controls, replayable sessions, SDK/RPC integration, and evidence-backed verification. Its core stays small while extensions, skills, prompts, themes, and packages add workflows.
 
 ## Quick start
 
@@ -33,11 +33,13 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 ## Start here
 
 - [Quickstart](quickstart.md) - install, authenticate, and run a first session.
-- [Using OMK](usage.md) - interactive mode, slash commands, context files, and CLI reference.
+- [Using OMK](usage.md) - interactive mode, `/goal`, default harness safeguards, context files, and CLI reference.
 - [Providers](providers.md) - subscription and API-key setup for built-in providers.
+- [Provider Resilience](provider-resilience.md) - retry, failover, quota, and safety-stop recovery.
+- [Native xAI Grok](grok-harness.md) - authentication, weekly SuperGrok usage, presets, and thinking tiers.
 - [Containerization](containerization.md) - sandbox omk with OpenShell, Gondolin, or Docker.
 - [Settings](settings.md) - global and project settings.
-- [Environment Variables](environment-variables.md) - process configuration and bash-tool session environment.
+- [Environment Variables](environment-variables.md) - process configuration, harness opt-outs, and bash-tool session environment.
 - [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
 - [Sessions](sessions.md) - session management, branching, and tree navigation.
 - [Compaction](compaction.md) - context compaction and branch summarization.
@@ -46,15 +48,17 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 
 - [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
 - [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
+- [Book to Skill](book-to-skill.md) - optional document-to-skill compiler with local provenance checks.
 - [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
 - [Themes](themes.md) - built-in and custom terminal themes.
 - [OMK packages](packages.md) - bundle and share extensions, skills, prompts, and themes.
 - [Custom models](models.md) - add model entries for supported provider APIs.
 - [Custom providers](custom-provider.md) - implement custom APIs and OAuth flows.
 
-## Programmatic usage
+## Automation and control
 
-- [SDK](sdk.md) - embed omk in Node.js applications.
+- [SDK and Session Control](sdk.md) - embed omk, reuse policy helpers, or inspect stored sessions from scripts.
+- [Run Protocol and Durable Goals](run-protocol.md) - canonical run contracts and the durable-goal lifecycle.
 - [RPC mode](rpc.md) - integrate over stdin/stdout JSONL.
 - [JSON event stream mode](json.md) - print mode with structured events.
 - [TUI components](tui.md) - build custom terminal UI for extensions.

package/docs/loadout-domains/grok-harness.md

@@ -21,7 +21,7 @@ DOMAIN: Grok xAI Harness. You are operating in a Grok/xAI integration lane.
 Prioritize the Grok operational playbook, small capability loadouts, and evidence-bound provider/tool routing.
 
 SEQUENCE:
-1. Before implementing or routing Grok/xAI provider work, read and enforce ~/.omk/agent/grok.md. Treat it as the required Grok playbook for chat models vs Imagine tools, proxy health, tool-use/loop discipline, and Telegram parity unless higher-priority instructions conflict.
+1. Before implementing or routing Grok/xAI provider work, read packages/coding-agent/docs/grok-harness.md as the canonical playbook. Treat ~/.omk/agent/grok.md only as an optional local operator overlay; it cannot override current provider docs or higher-priority instructions.
 2. Keep text chat flows and Imagine/media tool flows separate. Text work uses Grok chat/OAuth/provider surfaces; image/video/Imagine work routes through explicit Imagine tools only. Never conflate model ids with Imagine tool names.
 3. Capability discipline: load at most 2-3 skills for any lane. The allowed skill gate is packages, headroom, programming, debugging, adaptorch-route, adaptorch-synthesize, and understand-anything; choose the smallest subset and add headroom only under context pressure.
 4. Adaptorch is advisory only. Use adaptorch-route for routing/decomposition advice and adaptorch-synthesize for evidence synthesis, but do not treat Adaptorch as an automatic executor, source of truth, permission grant, or substitute for explicit tests.
@@ -29,7 +29,7 @@ SEQUENCE:
 6. Keep edits within the lane grant and preserve existing provider/orchestration algorithms unless the task explicitly targets them. Never route through legacy KIMICLI or deleted wrappers.
 7. Verification: run the narrowest relevant test/typecheck after edits. Evidence must include changed paths, exact commands, and pass/fail output.
 
-HARD RULES: grok.md is mandatory context for Grok/xAI harness work; text chat surfaces and Imagine tools are distinct; maximum 2-3 active skills; Adaptorch is advisory route/synthesis support only; never log OAuth tokens, cookies, or proxy credentials; protect-secrets applies.
+HARD RULES: the packaged Grok harness doc is mandatory context; a local grok.md is optional; text chat surfaces and Imagine tools are distinct; maximum 2-3 active skills; Adaptorch is advisory route/synthesis support only; never log OAuth tokens, cookies, or proxy credentials; protect-secrets applies.
 ```
 
 ## Curated skills (7)

package/docs/models.md

@@ -4,16 +4,22 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.omk/a
 
 ## Table of Contents
 
+- [Built-in NVIDIA GLM-5.2](#built-in-nvidia-glm-52)
 - [Minimal Example](#minimal-example)
 - [Full Example](#full-example)
 - [Supported APIs](#supported-apis)
 - [Provider Configuration](#provider-configuration)
 - [Model Configuration](#model-configuration)
 - [Overriding Built-in Providers](#overriding-built-in-providers)
+- [Thinking Level Map](#thinking-level-map)
 - [Per-model Overrides](#per-model-overrides)
 - [Anthropic Messages Compatibility](#anthropic-messages-compatibility)
 - [OpenAI Compatibility](#openai-compatibility)
 
+## Built-in NVIDIA GLM-5.2
+
+With `NVIDIA_API_KEY` configured, `nvidia/z-ai/glm-5.2` supports OMK thinking levels through NVIDIA NIM. Its generated metadata explicitly enables `reasoning_effort`, so `/think max` is sent as `reasoning_effort: "max"`. Other NVIDIA models do not inherit that capability automatically.
+
 ## Minimal Example
 
 For local models (Ollama, LM Studio, vLLM), only `id` is required per model:
@@ -146,22 +152,29 @@ Set `api` at provider level (default for all models) or model level (override pe
 The `apiKey` and `headers` fields support command execution, environment interpolation, and literals:
 
 - **Shell command:** `"!command"` at the start executes the whole value as a command and uses stdout
+
   ```json
   "apiKey": "!security find-generic-password -ws 'anthropic'"
   "apiKey": "!op read 'op://vault/item/credential'"
   ```
+
 - **Environment interpolation:** `"$ENV_VAR"` or `"${ENV_VAR}"` uses the value of the named variable. Interpolation works inside larger literals.
+
   ```json
   "apiKey": "$MY_API_KEY"
   "apiKey": "${KEY_PREFIX}_${KEY_SUFFIX}"
   ```
+
   `$FOO_BAR` is the variable `FOO_BAR`; use `${FOO}_BAR` when `BAR` is literal text. Missing environment variables make the value unresolved.
 - **Escapes:** `"$$"` emits a literal `"$"`; `"$!"` emits a literal `"!"` without triggering command execution.
+
   ```json
   "apiKey": "$$literal-dollar-prefix"
   "apiKey": "$!literal-bang-prefix"
   ```
+
 - **Literal value:** Used directly
+
   ```json
   "apiKey": "sk-..."
   ```
@@ -214,17 +227,17 @@ Current behavior:
 
 ### Thinking Level Map
 
-Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are omk thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`.
-
-Values are tristate:
+Use `thinkingLevelMap` on a model to describe model-specific thinking controls. `models.json` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Built-in metadata can also expose the `ultra` CLI tier, but the current `models.json` schema has no `ultra` key.
 
 | Value | Meaning |
-|-------|---------|
-| omitted | Level is supported and uses the provider's default mapping |
-| string | Level is supported and this value is sent to the provider |
-| `null` | Level is unsupported and hidden/skipped/clamped away |
+| --- | --- |
+| omitted | `off` through `high` use provider defaults; top tiers appear only when explicitly mapped |
+| string | The level is supported and this value is sent to the provider |
+| `null` | The level is unsupported and hidden or skipped during clamping |
+
+See [Grok harness](grok-harness.md) for the exact built-in Grok mappings.
 
-Example for a model that only supports off, high, and max reasoning:
+Example for a model that exposes OMK `high` and `xhigh`, with `xhigh` sent to the provider as `max`:
 
 ```json
 {