@zhivex-ai/harness 0.5.0

package/dist/mcp.d.ts

@@ -0,0 +1,37 @@
+import { type JsonValue, type McpClient, type McpListedTool, type ToolSet } from "@zhivex-ai/core";
+export declare const HARNESS_MCP_CONFIG_SCHEMA_VERSION: 1;
+export declare const HARNESS_MCP_PERMISSIONS: readonly ["read", "network", "write", "external-side-effect"];
+export type HarnessMcpPermission = (typeof HARNESS_MCP_PERMISSIONS)[number];
+export type HarnessMcpTransport = "http" | "custom";
+export interface HarnessMcpServerConfig {
+    name: string;
+    transport: HarnessMcpTransport;
+    url?: string;
+    includeTools: readonly string[];
+    excludeTools: readonly string[];
+    toolNamePrefix: string;
+    permissions: readonly HarnessMcpPermission[];
+    headerEnv: Readonly<Record<string, string>>;
+    trustServerToolAnnotations: boolean;
+    maxListPages: number;
+    maxListedTools: number;
+    listToolsTimeoutMs: number;
+    callToolTimeoutMs: number;
+    maxOutputBytes: number;
+}
+export interface HarnessMcpConfiguration {
+    schemaVersion: typeof HARNESS_MCP_CONFIG_SCHEMA_VERSION;
+    servers: readonly HarnessMcpServerConfig[];
+}
+export type HarnessMcpClients = Readonly<Record<string, McpClient>>;
+export declare const normalizeHarnessMcpConfiguration: (value: unknown) => HarnessMcpConfiguration;
+export declare const loadHarnessMcpConfiguration: (workspace: string, configPath: string) => Promise<HarnessMcpConfiguration>;
+type FetchImplementation = typeof fetch;
+export declare const createHttpMcpClient: (server: HarnessMcpServerConfig, env?: NodeJS.ProcessEnv, fetchImplementation?: FetchImplementation) => McpClient;
+export declare const createHarnessMcpTools: (configuration: HarnessMcpConfiguration, options?: {
+    clients?: HarnessMcpClients;
+    env?: NodeJS.ProcessEnv;
+    fetchImplementation?: FetchImplementation;
+}) => Promise<ToolSet>;
+export declare const mcpConfigurationFingerprintInput: (configuration: HarnessMcpConfiguration) => JsonValue;
+export type { McpClient, McpListedTool };

package/dist/operations.d.ts

@@ -0,0 +1,234 @@
+import { type AgentRunState, type AgentStatus } from "@zhivex-ai/agents";
+import type { AgentMemoryStore, AgentRunStore } from "@zhivex-ai/agents/ops";
+import { type HarnessConfig, type HarnessStoreBackend } from "./config.js";
+export declare const HARNESS_SQLITE_FILE = "operations.sqlite";
+export declare const HARNESS_OPERATIONS_SCHEMA_VERSION: 1;
+export declare const TERMINAL_RUN_STATUSES: readonly ["completed", "failed", "cancelled", "timed_out"];
+export interface HarnessMigrationResult {
+    scannedRuns: number;
+    migratedRuns: number;
+    migratedToolCalls: number;
+}
+export interface HarnessPersistence {
+    backend: HarnessStoreBackend;
+    store: AgentRunStore;
+    memory: AgentMemoryStore;
+    databasePath?: string;
+    migration: HarnessMigrationResult;
+    close(): void;
+}
+export interface HarnessRunQuery {
+    statuses?: AgentStatus[];
+    limit?: number;
+    cursor?: string;
+    updatedAfter?: number;
+    updatedBefore?: number;
+}
+export declare const listHarnessRuns: (store: AgentRunStore, config: HarnessConfig, query?: HarnessRunQuery) => Promise<{
+    nextCursor?: string;
+    schemaVersion: 1;
+    kind: "run-list";
+    scope: import("@zhivex-ai/core").AgentStoreScope;
+    backend: "sqlite" | "file";
+    runs: {
+        runId: string;
+        revision: number;
+        status: AgentStatus;
+        provider: string;
+        model: string;
+        agentId: string | undefined;
+        parentRunId: string | undefined;
+        idempotencyKey: string | undefined;
+        scope: import("@zhivex-ai/core").AgentStoreScope | undefined;
+        steps: number;
+        toolCalls: number;
+        toolErrors: number;
+        pendingApprovals: number;
+        compactions: number;
+        childRuns: number;
+        usage: import("@zhivex-ai/core").TokenUsage | undefined;
+        startedAt: number | undefined;
+        updatedAt: number | undefined;
+        cancelledAt: number | undefined;
+        cancellationReason: string | undefined;
+    }[];
+}>;
+export declare const inspectHarnessRun: (store: AgentRunStore, config: HarnessConfig, runId: string) => Promise<{
+    schemaVersion: 1;
+    kind: "run-inspection";
+    run: {
+        runId: string;
+        revision: number;
+        status: AgentStatus;
+        provider: string;
+        model: string;
+        agentId: string | undefined;
+        parentRunId: string | undefined;
+        idempotencyKey: string | undefined;
+        scope: import("@zhivex-ai/core").AgentStoreScope | undefined;
+        steps: number;
+        toolCalls: number;
+        toolErrors: number;
+        pendingApprovals: number;
+        compactions: number;
+        childRuns: number;
+        usage: import("@zhivex-ai/core").TokenUsage | undefined;
+        startedAt: number | undefined;
+        updatedAt: number | undefined;
+        cancelledAt: number | undefined;
+        cancellationReason: string | undefined;
+    };
+    budget: import("@zhivex-ai/core").AgentBudgetStatus;
+    snapshot: {
+        runId: string;
+        agentId?: string;
+        status: AgentStatus;
+        provider: string;
+        modelId: string;
+        steps: number;
+        toolCalls: import("@zhivex-ai/core").ToolCall[];
+        childRuns: NonNullable<AgentRunState["childRuns"]>;
+        compactions: NonNullable<AgentRunState["compactions"]>;
+        usage?: AgentRunState["usage"];
+        error?: AgentRunState["error"];
+        pendingApprovals: AgentRunState["pendingApprovals"];
+    };
+    trace: import("@zhivex-ai/core").AgentTraceArtifact;
+    hierarchy: import("@zhivex-ai/core").HierarchicalAgentTrace | undefined;
+    ledger: {
+        snapshot: {
+            runId: string;
+            agentId?: string;
+            status: AgentStatus;
+            provider: string;
+            modelId: string;
+            steps: number;
+            toolCalls: import("@zhivex-ai/core").ToolCall[];
+            childRuns: NonNullable<AgentRunState["childRuns"]>;
+            compactions: NonNullable<AgentRunState["compactions"]>;
+            usage?: AgentRunState["usage"];
+            error?: AgentRunState["error"];
+            pendingApprovals: AgentRunState["pendingApprovals"];
+        };
+        schemaVersion: typeof import("@zhivex-ai/core").AGENT_CONTROL_PLANE_SCHEMA_VERSION;
+        type: "agent_run_ledger";
+        runId: string;
+        agentId?: string;
+        provider: string;
+        modelId: string;
+        status: AgentRunState["status"];
+        audit: import("@zhivex-ai/core").AgentAuditRecord;
+        toolAudit: import("@zhivex-ai/core").ToolAuditRecord[];
+        timeline?: import("@zhivex-ai/core").AgentReplayResult["timeline"];
+        trace: import("@zhivex-ai/core").AgentTraceArtifact;
+        summary: import("@zhivex-ai/core").AgentTraceSummary;
+        cost?: import("@zhivex-ai/core").CostEstimate;
+        metadata?: Record<string, import("@zhivex-ai/core").JsonValue>;
+    };
+    toolJournal: {
+        toolCallId: string;
+        toolName: string;
+        status: import("@zhivex-ai/core").AgentToolCallJournalStatus;
+        revision: number;
+        startedAt: number | undefined;
+        completedAt: number | undefined;
+        updatedAt: number;
+        error: {
+            message: string;
+        } | undefined;
+    }[];
+}>;
+export declare const cancelHarnessRun: (store: AgentRunStore, config: HarnessConfig, runId: string, options?: {
+    reason?: string;
+    cascade?: boolean;
+    final?: boolean;
+}) => Promise<{
+    parent: {
+        runId: string;
+        revision: number;
+        status: AgentStatus;
+        provider: string;
+        model: string;
+        agentId: string | undefined;
+        parentRunId: string | undefined;
+        idempotencyKey: string | undefined;
+        scope: import("@zhivex-ai/core").AgentStoreScope | undefined;
+        steps: number;
+        toolCalls: number;
+        toolErrors: number;
+        pendingApprovals: number;
+        compactions: number;
+        childRuns: number;
+        usage: import("@zhivex-ai/core").TokenUsage | undefined;
+        startedAt: number | undefined;
+        updatedAt: number | undefined;
+        cancelledAt: number | undefined;
+        cancellationReason: string | undefined;
+    };
+    children: {
+        runId: string;
+        revision: number;
+        status: AgentStatus;
+        provider: string;
+        model: string;
+        agentId: string | undefined;
+        parentRunId: string | undefined;
+        idempotencyKey: string | undefined;
+        scope: import("@zhivex-ai/core").AgentStoreScope | undefined;
+        steps: number;
+        toolCalls: number;
+        toolErrors: number;
+        pendingApprovals: number;
+        compactions: number;
+        childRuns: number;
+        usage: import("@zhivex-ai/core").TokenUsage | undefined;
+        startedAt: number | undefined;
+        updatedAt: number | undefined;
+        cancelledAt: number | undefined;
+        cancellationReason: string | undefined;
+    }[];
+    schemaVersion: 1;
+    kind: "run-cancellation";
+    cascade: boolean;
+} | {
+    run: {
+        runId: string;
+        revision: number;
+        status: AgentStatus;
+        provider: string;
+        model: string;
+        agentId: string | undefined;
+        parentRunId: string | undefined;
+        idempotencyKey: string | undefined;
+        scope: import("@zhivex-ai/core").AgentStoreScope | undefined;
+        steps: number;
+        toolCalls: number;
+        toolErrors: number;
+        pendingApprovals: number;
+        compactions: number;
+        childRuns: number;
+        usage: import("@zhivex-ai/core").TokenUsage | undefined;
+        startedAt: number | undefined;
+        updatedAt: number | undefined;
+        cancelledAt: number | undefined;
+        cancellationReason: string | undefined;
+    };
+    schemaVersion: 1;
+    kind: "run-cancellation";
+    cascade: boolean;
+}>;
+export declare const cleanupHarnessRuns: (store: AgentRunStore, config: HarnessConfig, options: {
+    before: number;
+    statuses?: AgentStatus[];
+    limit?: number;
+}) => Promise<{
+    schemaVersion: 1;
+    kind: "run-cleanup";
+    before: number;
+    statuses: AgentStatus[];
+    deleted: number;
+}>;
+export declare const migrateLegacyFileRuns: (directory: string, target: AgentRunStore, config: HarnessConfig) => Promise<HarnessMigrationResult>;
+export declare const openHarnessPersistence: (config: HarnessConfig, options?: {
+    migrateLegacyFileStore?: boolean;
+}) => Promise<HarnessPersistence>;

package/dist/orchestration.d.ts

@@ -0,0 +1,43 @@
+import { runAgentGroup, type AgentDefinition, type AgentHarnessBinding, type AgentRunInput, type AgentSubAgentDefinition, type LanguageModel, type ToolSet } from "@zhivex-ai/agents";
+import type { AgentMemoryStore, AgentRunStore, AgentTelemetryObserver } from "@zhivex-ai/agents/ops";
+import type { HarnessConfig, HarnessSubagentProfile } from "./config.js";
+export interface HarnessSubagentProfileDescriptor {
+    id: HarnessSubagentProfile;
+    toolName: string;
+    description: string;
+    instructions: string;
+    toolNames: readonly string[] | "all";
+}
+export declare const HARNESS_SUBAGENT_PROFILE_DESCRIPTORS: readonly HarnessSubagentProfileDescriptor[];
+export interface HarnessSubagentRuntime {
+    definitions: AgentSubAgentDefinition<LanguageModel>[];
+    agents: ReadonlyMap<HarnessSubagentProfile, AgentDefinition<LanguageModel>>;
+}
+export declare const createHarnessSubagents: (options: {
+    config: HarnessConfig;
+    parentBinding: AgentHarnessBinding;
+    model: LanguageModel;
+    models?: Partial<Record<HarnessSubagentProfile, LanguageModel>>;
+    tools: ToolSet;
+    store: AgentRunStore;
+    memory?: AgentMemoryStore;
+    onTelemetryEvent?: AgentTelemetryObserver;
+}) => HarnessSubagentRuntime;
+export interface HarnessReviewGroupResult {
+    schemaVersion: 1;
+    kind: "review-group";
+    groupId: string;
+    status: "completed" | "failed";
+    profiles: HarnessSubagentProfile[];
+    outputs: Awaited<ReturnType<typeof runAgentGroup>>["outputs"];
+}
+export declare const runHarnessReviewGroup: (runtime: {
+    config: HarnessConfig;
+    subagents: ReadonlyMap<HarnessSubagentProfile, AgentDefinition<LanguageModel>>;
+}, input: {
+    prompt: string;
+    scope?: AgentRunInput<LanguageModel>["scope"];
+    abortSignal?: AbortSignal;
+    metadata?: AgentRunInput<LanguageModel>["metadata"];
+    groupId?: string;
+}, profiles?: readonly HarnessSubagentProfile[]) => Promise<HarnessReviewGroupResult>;

package/dist/state-directory.d.ts

@@ -0,0 +1 @@
+export declare const validateStateDirectory: (workspace: string, stateDirectory: string) => Promise<void>;

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+/** The application version. package.json is the single source of truth. */
+export declare const HARNESS_VERSION: string;
+/** The Bun compatibility range declared by the package. */
+export declare const BUN_ENGINE_RANGE: string;

package/dist/workspace.d.ts

@@ -0,0 +1,90 @@
+import { type ApplyEditProposalInput, type ApplyPatchResult, type FileDigest, type MoveFileInput, type MoveFileResult, type MutationAuditEntry, type QuarantineFileInput, type QuarantineFileResult, type RestoreFileInput, type RestoreFileResult } from "./edit-contracts.js";
+export type HarnessCheck = string;
+export interface WorkspaceFile {
+    path: string;
+    size: number;
+    digest: FileDigest;
+}
+export interface SearchMatch {
+    path: string;
+    line: number;
+    text: string;
+    digest: FileDigest;
+}
+export interface ListFilesOptions {
+    limit?: number;
+    cursor?: string;
+}
+export interface SearchFilesOptions {
+    caseSensitive?: boolean;
+    limit?: number;
+    cursor?: string;
+    /** @deprecated Use limit. */
+    maxMatches?: number;
+}
+export interface CommandResult {
+    command: string[];
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+export declare class Workspace {
+    readonly root: string;
+    private readonly auditEntries;
+    private constructor();
+    static open(root: string): Promise<Workspace>;
+    private lexicalPath;
+    private safePath;
+    private readStableFile;
+    private rulesForDirectory;
+    private collectFiles;
+    listFiles(relativePath?: string, options?: number | ListFilesOptions): Promise<{
+        nextCursor?: string;
+        files: WorkspaceFile[];
+        truncated: boolean;
+    }>;
+    readFile(relativePath: string, startLine?: number, endLine?: number): Promise<{
+        path: string;
+        digest: string;
+        startLine: number;
+        endLine: number;
+        totalLines: number;
+        content: string;
+        truncated: boolean;
+    }>;
+    searchFiles(query: string, relativePath?: string, options?: SearchFilesOptions): Promise<{
+        nextCursor?: string;
+        matches: SearchMatch[];
+        truncated: boolean;
+    }>;
+    private audit;
+    mutationAudit(): readonly MutationAuditEntry[];
+    private secureWorkspaceDirectory;
+    private stageFile;
+    applyPatch(input: ApplyEditProposalInput): Promise<ApplyPatchResult>;
+    /** @deprecated Use applyPatch with an inspected expectedDigest. */
+    writeFile(relativePath: string, content: string, overwrite?: boolean): Promise<{
+        path: string;
+        bytes: number;
+        overwritten: boolean;
+    }>;
+    /** @deprecated Use applyPatch with an inspected expectedDigest. */
+    replaceInFile(relativePath: string, oldText: string, newText: string): Promise<{
+        path: string;
+        beforeBytes: number;
+        afterBytes: number;
+    }>;
+    moveFile(input: MoveFileInput): Promise<MoveFileResult>;
+    private secureQuarantineDirectory;
+    private writeManifest;
+    private readInternalRegularFile;
+    quarantineFile(input: QuarantineFileInput): Promise<QuarantineFileResult>;
+    restoreQuarantined(input: RestoreFileInput): Promise<RestoreFileResult>;
+    runCheck(check: HarnessCheck, expectedScript: string, allowedChecks?: readonly string[]): Promise<CommandResult>;
+    gitDiff(): Promise<{
+        status: CommandResult;
+        diff: CommandResult;
+        staged: CommandResult;
+    }>;
+}

package/docs/CLI.md

@@ -0,0 +1,65 @@
+# CLI contract
+
+Zhivex Harness `0.5.x` is Bun-first and exposes a human terminal interface plus versioned JSON documents for automation.
+
+## Commands
+
+```text
+zhivex-harness run [options] "task"
+zhivex-harness review [options] "review task"
+zhivex-harness chat [options]
+zhivex-harness providers [--json]
+zhivex-harness doctor [options] [--json]
+zhivex-harness resume [options] <runId> --approve|--deny
+zhivex-harness runs list [--status <status>] [--limit <n>] [--cursor <cursor>]
+zhivex-harness runs inspect <runId>
+zhivex-harness runs export <runId>
+zhivex-harness runs cancel <runId> [--reason <text>] [--cascade] [--final]
+zhivex-harness runs cleanup --before <date|timestamp> [--status <status>] [--limit <n>]
+zhivex-harness --version
+zhivex-harness --help
+```
+
+`doctor` is local and makes no provider or MCP request. It checks the Bun version, workspace, Git, supported package scripts, state-directory safety, provider credential presence, endpoint shape, provider configuration, and the local MCP configuration file without returning secret or endpoint values.
+
+`--allow-check <script>` is repeatable and replaces the default check allowlist for that invocation. Values are declared `package.json` script names, never command text.
+
+`--require-capability <name>`, `--subagent <profile>`, and `--reviewer <explorer|reviewer>` are repeatable. `--mcp-config <path>` loads a schema-versioned file inside the canonical workspace. Child limits use `--subagent-max-steps`, `--subagent-max-tool-calls`, `--subagent-max-tool-errors`, `--subagent-max-input-tokens`, `--subagent-max-output-tokens`, `--subagent-max-total-tokens`, and `--subagent-timeout-ms`. Parallel review is capped by `--max-parallel-reviews`.
+
+`review` is application-owned parallelism and accepts only read-only explorer/reviewer members. Model-directed delegation occurs only inside `run` or `chat` when the parent invokes an enabled `delegate_<profile>` tool.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Command completed successfully. |
+| `1` | Runtime, provider, or agent failure. |
+| `2` | Invalid CLI usage. |
+| `3` | `doctor` found a blocking configuration problem. |
+
+Agent results with status `failed` or `timed_out` return `1`. A paused approval is a valid durable result and does not imply a runtime failure.
+
+Operator commands do not construct a provider model and do not require provider credentials. They must use the workspace, state directory, backend, and scope that own the target run. `cancel` creates a cooperative cancellation request by default; `--final` writes a terminal cancellation. `cleanup` requires an explicit cutoff and defaults to terminal statuses only.
+
+## JSON schemas
+
+All structured documents include:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "providers | doctor | run-result | review-group | run-list | run-inspection | run-export | run-cancellation | run-cleanup"
+}
+```
+
+Additive fields may appear within schema version `1`. Removing a field, changing its meaning, or changing a field type requires a new schema version and a migration note. Human-readable output is not a machine contract.
+
+Provider diagnostics include credential variable names and boolean presence only. Endpoint diagnostics include validation booleans only. Neither contract contains credential values or endpoint URLs.
+
+`run-result.mutations` contains the mutation audit entries produced by the current harness process. `run-result.children` reports bounded child identity, status, steps, tool/error counts, and usage without raw child messages or tool payloads. Capability evidence and configured MCP server names are included. `review-group` contains a group ID and one bounded member result. Operational inspect/export documents are redacted and do not include raw messages, tool inputs/outputs, approval arguments, metadata, or full output text; `run-inspection.hierarchy` adds the redacted run tree. Tool-level repository-editing documents use their own schema version `1` and kinds such as `edit-proposal`, `patch-result`, `mutation-audit`, and `workspace-diff`; see [REPOSITORY_EDITING.md](./REPOSITORY_EDITING.md).
+
+## Configuration schema
+
+Resolved library configuration includes `schemaVersion: 3`, an explicit `allowedChecks` array, `storeBackend`, `scope`, parent `budget`, `compaction`, `requiredCapabilities`, optional `mcpConfigPath`, and an `orchestration` object with profiles, child budget/timeout, and review concurrency. The check default is `test`, `typecheck`, `lint`, and `build`; `--allow-check` or `ZHIVEX_HARNESS_ALLOWED_CHECKS` replaces that set. Passing a different explicit schema version fails before a model or tool can run. During `0.x`, a minor release may add a new schema version with a documented migration; patch releases remain compatible.
+
+The default state directory is `<workspace>/.zhivex-harness/runs` and the default backend is scoped SQLite at `operations.sqlite`. Explicit external state directories are supported, but the workspace root, filesystem root, sensitive workspace paths, regular files, and symbolic-link targets are rejected before the run store is created. See [DURABLE_OPERATIONS.md](./DURABLE_OPERATIONS.md) for state migration and operations, and [EXTENSIBILITY.md](./EXTENSIBILITY.md) for capability, MCP, subagent, and review-group configuration.

package/docs/DURABLE_OPERATIONS.md

@@ -0,0 +1,116 @@
+# Durable operations
+
+Zhivex Harness `0.4.x` makes local runs inspectable and recoverable across process restarts. The default store is Bun SQLite at `<workspace>/.zhivex-harness/runs/operations.sqlite`; `--store file` remains a migration fallback.
+
+## Scope and identity
+
+Every durable key is isolated by:
+
+- tenant: `local` by default;
+- optional user;
+- namespace: a SHA-256-derived canonical-workspace identifier by default.
+
+Use the same workspace, state directory, backend, tenant, user, and namespace for `run`, `resume`, and every `runs` command. A run fingerprint is bound to the canonical workspace, durable scope, provider/model, tool contract, approval policy, config schema, and harness version. Resume fails closed when a current binding differs.
+
+```bash
+zhivex-harness run \
+  --tenant acme \
+  --user operator-7 \
+  --namespace payments \
+  --idempotency-key incident-482 \
+  "diagnose and repair the regression"
+```
+
+An idempotency key atomically reserves one run inside its scope. Repeating the request returns the existing durable state instead of starting another side-effecting run. SQLite leases and compare-and-swap revisions prevent concurrent workers from silently owning the same checkpoint, while the tool journal records exactly-once claims for side effects.
+
+## Operator commands
+
+Operator commands open the store directly. They do not create a provider model and do not require provider credentials.
+
+```bash
+zhivex-harness runs list --status waiting_approval --limit 50
+zhivex-harness runs list --cursor <opaque-cursor> --json
+zhivex-harness runs inspect <runId> --json
+zhivex-harness runs export <runId> --json
+zhivex-harness runs cancel <runId> --reason "superseded"
+zhivex-harness runs cancel <runId> --cascade --final
+zhivex-harness runs cleanup --before 2026-08-01T00:00:00Z
+```
+
+`cancel` records a cooperative `cancel_requested` state by default. Use `--final` only when the operator intends to make cancellation terminal. `--cascade` includes known child runs. `cleanup` requires an ISO-8601 date or millisecond timestamp; without `--status`, it removes only `completed`, `failed`, `cancelled`, and `timed_out` runs. The default maximum cleanup batch is 1,000.
+
+`inspect` and `export` share the same redacted operational artifact. Export changes only the document kind to `run-export`; it does not create an unredacted archive on disk.
+
+## Budgets
+
+Default limits are:
+
+| Budget | Default |
+| --- | ---: |
+| Steps | 12 |
+| Wall clock | 900,000 ms |
+| Tool calls | 32 |
+| Tool errors | 4 |
+| Input tokens | 100,000 |
+| Output tokens | 30,000 |
+| Total tokens | 120,000 |
+
+Configure them with `--max-steps`, `--timeout-ms`, `--max-tool-calls`, `--max-tool-errors`, `--max-input-tokens`, `--max-output-tokens`, and `--max-total-tokens`. Production guardrails stop the run and persist a clear termination reason when a measured limit is reached. Meta and OpenAI receive a compatible output ceiling. Qwen Responses cannot accept `maxTokens`, so its token limits are checked durably before and after a provider step; one step can cross a measured token limit before the output guard observes it.
+
+Cost is optional because provider/model pricing is not inferred:
+
+```bash
+zhivex-harness run \
+  --max-cost-usd 0.50 \
+  --input-cost-per-million 2.50 \
+  --output-cost-per-million 10 \
+  "review the repository"
+```
+
+At least one pricing value is required with `--max-cost-usd`. Missing input or output pricing is treated as zero. Cost uses provider-reported token usage and operator-supplied prices; it is not a billing record and a single provider step can cross the ceiling before the post-step guardrail observes it.
+
+## Context compaction
+
+The default compactor activates at 60 messages or an estimated 40,000 input tokens, retains the 12 most recent messages, and records each compaction durably. The summary includes roles, bounded text, and tool names rather than raw tool payloads. Library users can configure `compactionMaxMessages`, `compactionMaxEstimatedInputTokens`, and `compactionKeepRecentMessages`; corresponding environment variables are listed below.
+
+## Redaction and exports
+
+Operational artifacts are schema version `1`. By default they exclude raw messages, tool inputs, tool outputs, approval arguments, run metadata, and full output text. Traces, ledger previews, and journal errors apply the production secret/email redaction policy. This is a defensive export boundary, not a guarantee that arbitrary model-generated prose can never contain sensitive business data; control prompt contents and workspace permissions accordingly.
+
+## Migration from 0.3.x
+
+Opening either backend under the default local/workspace scope scans legacy unscoped file-backed runs in the selected state directory. Runs absent from the scoped store are copied with their tool journals and marked `metadata.migratedFrom: "0.3-file-store"`. With the default backend the target is SQLite; `--store file` creates scoped file copies as a temporary compatibility path. Migration is idempotent and retains the unscoped source files for rollback; it does not delete or rewrite the legacy state. Custom tenant, user, or namespace scopes never import unscoped legacy data implicitly; library operators must call `migrateLegacyFileRuns` intentionally with the target scoped store.
+
+Legacy paused approvals can be resumed explicitly. The harness writes the current binding before continuing, so subsequent resumes are protected by the `0.4.x` fingerprint. Review the pending approval before accepting it. If migration must be deferred, use `--store file`; do not point SQLite and file workers at the same logical request concurrently.
+
+The SQLite state directory is owner-only and the database file is owner-readable/writable. Symlinked state directories and database files are rejected. Back up the state directory before moving scopes or performing manual database maintenance.
+
+## Environment variables
+
+CLI flags take precedence over these variables:
+
+```text
+ZHIVEX_HARNESS_STORE
+ZHIVEX_HARNESS_TENANT_ID
+ZHIVEX_HARNESS_USER_ID
+ZHIVEX_HARNESS_NAMESPACE
+ZHIVEX_HARNESS_MAX_STEPS
+ZHIVEX_HARNESS_TIMEOUT_MS
+ZHIVEX_HARNESS_MAX_TOOL_CALLS
+ZHIVEX_HARNESS_MAX_TOOL_ERRORS
+ZHIVEX_HARNESS_MAX_INPUT_TOKENS
+ZHIVEX_HARNESS_MAX_OUTPUT_TOKENS
+ZHIVEX_HARNESS_MAX_TOTAL_TOKENS
+ZHIVEX_HARNESS_MAX_COST_USD
+ZHIVEX_HARNESS_INPUT_COST_PER_MILLION
+ZHIVEX_HARNESS_OUTPUT_COST_PER_MILLION
+ZHIVEX_HARNESS_COMPACTION_MAX_MESSAGES
+ZHIVEX_HARNESS_COMPACTION_MAX_INPUT_TOKENS
+ZHIVEX_HARNESS_COMPACTION_KEEP_RECENT
+```
+
+## Evaluation gate
+
+`bun run evaluate` executes five deterministic golden cases: analysis-only, approved edit-and-test, denied approval, SQLite restart recovery, and provider switching. It checks terminal status, exact tool sequence, maximum steps, a 30-second per-case latency bound, denied-write safety, and exactly-once recovery. `bun run check` runs this gate before the installed-tarball smoke.
+
+The golden baseline is packaged at `evaluations/golden-expectations.json`. It is regression evidence, not live-provider certification. Provider behavior must still pass the opt-in, credentialed live gate described in [LIVE_CERTIFICATION.md](./LIVE_CERTIFICATION.md).