@zhivex-ai/harness 1.1.1 → 1.2.0-rc.13

package/docs/CONTEXT_ENGINEERING.md

@@ -85,23 +85,42 @@ identifies the last returned line so ordinary reads can continue from the next l
 not treat that clipped text as the entire source line. Search an exact file to locate
 relevant short excerpts instead of repeatedly reading a large file.
 
-Conversation compaction uses `bounded-evidence-v5`. It retains a redacted excerpt of
-the initial user objective, recent conversation excerpts, bounded local-tool path
+Conversation compaction uses `bounded-evidence-v8`. It retains a redacted excerpt of
+the latest user direction as `objective`, the earlier task as `historicalObjective`
+when it changes, chronological steering, recent conversation excerpts, bounded local-tool path
 and digest evidence, and a separate short history of check exit codes, timeouts,
 and tool failures. These are recollections, not approvals or verification receipts.
 The latest four check/error records are kept independently of ordinary file-read
-noise. The latest three subsequent user excerpts are retained separately from
+noise. Up to ten distinct subsequent user excerpts are retained separately from
 assistant chatter, redacted and bounded to 512 characters each. They share the
 existing total summary budget and remain untrusted context. Interactive summaries
-can carry this structure across subsequent compactions.
+can carry this structure across subsequent compactions. Older summaries migrate
+their most recent steering into the current objective. A follow-up question does
+not erase the earlier task: it remains historical context and steering, and
+assistant narration cannot supersede user direction.
 
 The latest successful `repair_plan` is retained separately from assistant chatter,
 with bounded hypothesis, expected behavior, next check, and safe relative paths.
 It remains model-authored recollection, never authorization or a verification receipt.
-Older v1-v4 summaries remain readable. Original requests remain recoverable with
+Older v1-v6 summaries remain readable. Original requests remain recoverable with
 `read_task`; a summary is not a replacement for full acceptance criteria.
 
-Automatic compaction uses `adaptive-tokens-v1`. The configured recent-message count
+Context is useful working memory, not a proof system. Conceptual discussion,
+decisions, hypotheses and unresolved questions remain available without a
+`repair_plan` or verification receipt. Up to three redacted local diagnostic
+excerpts (640 characters each) are retained as `unverified` observations, separate
+from typed check records. These may include command stdout/stderr, SDK tool-error
+messages and terminal-verifier diagnostics. They share the summary's total bound;
+file bodies and external-tool payloads are not copied into these observations.
+Repeated identical excerpts do not evict distinct decisions. A summary neither
+authorizes an effect nor proves that a check passed.
+
+Repeated hybrid compaction preserves the deterministic JSON and the model's
+recollection separately. Recollection stays untrusted conversational material,
+including when another model summarizes it. No additional provider or paid call
+is selected automatically; `/compaction provider:model` selects that route.
+
+Automatic compaction uses `adaptive-tokens-v2`. The configured recent-message count
 is an upper target: the runtime selects a smaller complete tail when its estimated
 size exceeds the token target. Calls/results and provider approval groups remain
 correlated; pending approvals and durable compaction records remain SDK-owned.
@@ -110,11 +129,28 @@ the summary. A protected newest group that cannot fit still fails closed.
 
 Compaction and transport budgets share the same character-based estimator
 (characters / 3 plus envelope allowance), not a provider tokenizer. Tool schemas
-are measured separately from the configured message ceiling. Repair runs reduce
-the trigger as remaining cumulative input allowance shrinks, aiming to leave room
-for three requests; this does not increase budget ceilings. Unlimited-token mode
+are measured separately from the configured message ceiling. Runs reduce the
+trigger as remaining cumulative input allowance shrinks, aiming to leave room
+for three requests. That heuristic reserves enough space for the newest indivisible
+call/result group, system instructions and summary rather than rejecting a prompt
+that still fits the actual allowance. The configured context threshold and transport
+token ceilings remain authoritative. Unlimited-token mode
 keeps the configured context thresholds. Explicit per-run compaction overrides
 and `compaction: false` remain honored. No model context-window size is inferred.
+
+For single-agent runs, the remaining balance updates after each provider response,
+including within the same invocation. Before sending another request, the harness
+checks estimated input against the remaining input and total budgets. Estimates
+are heuristic; reported usage remains authoritative and can still exceed a limit.
+Failed checkpoints include that reported usage even when the response's tools
+were rejected.
+
+In ordinary runs, requests approaching the last 30% of the token budget
+switch to a final answer with no new tools. The answer must distinguish collected
+evidence from unfinished work. This is a best-effort closure reserve, not a
+guarantee that every task completes within its budget. Runs with required verified
+delivery use their verification controller instead. Unlimited-token mode disables these token
+stops and closure transitions.
 Schema serialization is cached by schema identity; messages and tool descriptions
 are measured anew. Transport accounting reuses its measurement for diagnostics.
 
@@ -149,13 +185,41 @@ artifact; they cannot silently resume under the changed context behavior.
 Run `bun run evaluate:continuity` for deterministic retention, redaction, and agent
 loop regressions. These checks do not measure model coding capability.
 
+The live follow-up exposed an older objective competing with a newer user correction.
+The v7 policy protects recent user steering and describes its precedence explicitly.
+This follows the approach of retaining recent user messages independently of a summary
+in [Codex's compactor](https://github.com/openai/codex/blob/main/codex-rs/core/src/compact.rs);
+it does not adopt Codex's token budget or imply equivalent model performance.
+
+Repair transport budgeting also avoids an implicit 2,048-token response cap. Reasoning
+and visible output can share the provider's output allowance, as explained in
+[OpenAI's reasoning guide](https://developers.openai.com/api/docs/guides/reasoning).
+Explicit caller limits and the remaining cumulative budget still apply where the
+selected transport supports a request cap. A completed change needs relevant checks
+and review, not repeated audits without new evidence; this is consistent with
+[Claude Code's guidance on scoped review](https://code.claude.com/docs/en/best-practices#add-an-adversarial-review-step).
+These are product choices supported by those sources, not a universal harness standard.
+
 ## Task continuity and repair policy (audit remediation)
 
-The `bounded-evidence-v5` summary remains lossy and bounded. Original operator
-requests are stored separately in run metadata (`zhivexTaskSources`), redacted,
-deduplicated by digest and limited to 64 requests / 256000 UTF-8 bytes. Exceeding
-that bound is an explicit error. `read_task` reads 4000 characters at an offset
-and lists source IDs; summaries do not replace the original acceptance criteria.
+The `bounded-evidence-v8` summary remains lossy and bounded. It keeps up to ten
+distinct user steering messages within the same 4,000-character limit. The initial
+request is historical context; `objective` holds the latest direction. Later
+user corrections take precedence, the
+latest user message overrides the summary, and recalled assistant text cannot
+redefine user facts. This prevents repetitive narration from giving old values
+priority over later corrections; it does not make summaries authoritative.
+Original operator
+requests are stored separately in run metadata (`zhivexTaskSources`), redacted
+and deduplicated by digest, ordered by the latest occurrence of each request.
+Repeating an earlier request makes it current without duplicating its stored text;
+an explicit original-source marker preserves `firstSourceId`. Durable history is retained beyond 64 requests and
+256000 UTF-8 bytes instead of aborting the conversation or discarding requirements.
+`read_task` reads 4000 characters at an offset and projects at most 64 source IDs.
+The default ID page contains the latest requests; `sourceOffset` pages older IDs
+and `firstSourceId` addresses the original request directly. Stored metadata grows
+with operator history, while model-facing pages remain bounded. Summaries do not
+replace the original acceptance criteria.
 Interactive sessions retain this metadata across turns and durable resumes.
 Manual compaction keeps a bounded summary in the prompt and retains redacted
 operator sources separately. The CLI persists them in session/run metadata.
@@ -167,8 +231,8 @@ and the next check in the durable tool journal. Its optional `verifier` records
 exact `command`, `args` and a bounded `purpose`. Neither tool creates approval
 or proof that a task is solved.
 
-The optional `repair` runtime profile is shared by CLI, library and external
-benchmark. Before each actual provider request it predicts the full message and
+The optional `requireVerifiedDelivery` completion contract is shared by CLI, library
+and external benchmark. Before each actual provider request it predicts the full message and
 tool-schema context, reserves 30% of input/output allowance for closure, and caps
 requested output to the current phase allowance. The predictor uses serialized
 characters, not the provider tokenizer: actual billing can exceed a prediction.
@@ -190,7 +254,7 @@ not independently establish that the chosen check covers the user's requirement.
 Host-mode edits require an approved `run_check` before completion.
 
 Applications that require an actual repair can set `requireVerifiedDelivery: true`
-when creating a Harness with `agentProfile: "repair"`. This creates a durable
+when creating a Harness, without choosing a runtime profile. This creates a durable
 completion obligation before exploration starts; a final answer without a
 verified delivery is failed in both the result and saved checkpoint. The option
 is bound to the run fingerprint and cannot be removed by restoring the controller
@@ -239,6 +303,12 @@ four further read calls and three command calls remain. Every `read_files` path
 is checked against the normalized plan scope. Approved verification remains
 subject to the run deadline, lease and tool budgets.
 
+A rejected plan leaves the previous accepted plan intact. An out-of-scope read
+does not consume the closure read allowance, though it still consumes the ordinary
+tool-error budget. Correcting or replacing a plan does not replenish allowances.
+If an operation fails after changing a previously delivered candidate, the new
+candidate remains pending verification across resume.
+
 Primary and child definitions share the durable policy factory. Their manifests
 identify the role, catalogue, budget and whether the primary closure controller
 is installed. Read-only review groups and SDK-managed delegated runs do not gain
@@ -251,14 +321,108 @@ search evidence and fully overlapping read slices are suppressed on their third
 observation; real reads still validate current bytes. Possible mutation/command
 effects reset those hashes. Closure counters, known paths and bounded evidence
 hashes survive SDK checkpoints in `zhivexRepairProgress`. Runtime read output is
-limited to 32000 serialized characters per model step in this profile.
+limited to 32000 serialized characters per model step when verified delivery is required.
 
-Changing the compaction strategy or runtime profile changes the harness binding.
+Changing the compaction strategy or delivery requirement changes the harness binding.
 Paused runs from an older binding must be completed/denied with their original
 artifact; these changes deliberately do not reinterpret an old approval.
 
-Repair mode returns an unknown tool selection to the model as `TOOL_NOT_REGISTERED`, just as invalid arguments receive structured feedback. It never resolves aliases or executes an unregistered tool. Existing tool-error, step and token limits bound recovery; callers can override `unknownToolMode` to `throw` or use `stopOnError`. Strict mode retains its fail-fast behavior, and subsequent mutations still require approval.
+The shared execution loop returns unknown tool selections as `TOOL_NOT_REGISTERED`
+and invalid arguments as structured error feedback. This general-purpose recovery
+is separate from the optional verified-delivery controller: ordinary runs keep
+ordinary model-driven task completion without imposing a verifier plan. No
+unregistered tool or invalid arguments are executed. Existing tool-error, step,
+token and time limits bound recovery; callers can select `stopOnError: true`,
+`validationErrorMode: "throw"` and `unknownToolMode: "throw"` explicitly. Delegated
+runs use the same recovery defaults with sequential execution and their existing
+child budgets. Subsequent mutations still require approval.
 
 For required-delivery OCI runs, reaching the predicted work-budget boundary without a verifier transitions into the same durable two-attempt planning path before rejecting another exploration request. That request exposes only `repair_plan` and `read_task`. The estimate includes the working-state message and current tool catalogue; the budget gate recalculates after narrowing. This spends only the existing closure reserve, keeps total input/output ceilings, and neither executes nor approves a repair. Optional inspection runs do not gain access to the reserve.
 
 Closure-reserve eligibility from this boundary is durable across checkpoints and remains active after recording the verifier, so planning can lead to an edit. A repair with an existing verifier can enter the same reserve. This does not replenish tokens, grant tool approval, or establish that a candidate satisfies the task.
+
+### Qwen reasoning fragments
+
+The harness losslessly joins adjacent plain Qwen `reasoning_content` fragments
+before estimating saved histories and when collecting new model streams. This
+removes repeated JSON envelopes without truncating reasoning text, tool calls,
+or results. Signed or unknown provider data forms a boundary and is preserved
+unchanged. Streaming aggregation flushes at 16 KiB of characters or the next
+non-reasoning event. Oversized irreducible groups still fail closed; the CLI
+identifies this as a context-compaction failure rather than an unknown cause.
+## Hierarchical context and hybrid compaction
+
+The pinned Zhivex SDK owns paid-compaction admission and durable attempt receipts. Harness supplies an explicit route fingerprint and reserves 32,000 input tokens plus 1,024 output tokens before the callback runs. The serialized utility input is capped below 31,000 UTF-8 bytes, leaving framing allowance; this conservative bound can reject a call when a tight budget cannot reserve it. Small sources use deterministic evidence and a zero-usage receipt. Confirmed usage survives summary rejection; interrupted or unknown attempts block paid retries. The separate Harness ledger remains responsible for per-route monetary limits and partial provider usage.
+
+The SDK shared budget coordinator is available to library callers through an explicit run policy; it is not enabled automatically. Harness persistence supports its reserved namespace without widening tenant/user access. Portable backups include linked coordinator ledgers and reject unresolved reservations or unknown compaction attempts, so restoring a backup cannot silently reset the shared consumption. Backups created before these optional records remain readable.
+
+Successful `read_file` and `read_files` calls discover ancestor `AGENTS.md` files
+inside the workspace, excluding the already loaded root. Discovery is bounded,
+rejects links/protected paths, and records both present and absent file identities
+in SDK-owned checkpoints. Applicable guidance is supplied on subsequent requests,
+with its scope and provenance; it cannot change permissions or verification.
+The number of previously visited directories or small instruction files does not
+exhaust a lifetime quota. Content remains bounded by per-file and aggregate byte
+limits, and each discovery request retains its target/ancestor bound.
+The runtime refreshes these discovered scopes before model requests, including
+normal edits, deletion and creation at a previously absent instruction path.
+Updated guidance replaces the previous scoped context; it cannot authorize an
+effect. Unsafe links, protected paths, invalid text and exceeded limits still
+fail before that guidance reaches the model. The strict
+`validateHarnessScopedContext` library function remains available for callers
+that explicitly require fixed instruction identities. The root context bundle
+and execution/approval fingerprints keep their existing binding rules.
+Project context can still be disabled with `--no-project-context`.
+
+Primary runs now monitor repeated tool-result cycles and long repeated text across
+compaction and resume. Three unchanged cycles request a new hypothesis; five stop
+before the next model call. Changed results break repetition. Bounded persisted
+hashes contain no source text. Changing narration around identical tools does
+not count as progress. Text-only repetition remains monitored independently of
+tool turns. A genuine new user request resets that history, including when the
+user deliberately asks to reread an unchanged file. Approval resumes, summarized
+history and assistant/tool-only continuations retain it, so continuation cannot
+erase a loop within the same turn. Reads are not replaced with cached evidence.
+A separate durable counter requests a decision after eight exploratory operations
+without a successful edit or check, even when every read/search differs. This
+advisory asks for the smallest justified implementation, a synthesis for read-only
+work, a specific missing fact, or an explicit blocker. It never forces a tool call
+or adds a hard stop to legitimate exploration. New user requests and successful
+edits/checks reset it; approval resumes and compaction preserve it.
+Trusted independent local reads use up to four SDK workers; writes, checks,
+approvals, MCP and delegation remain barriers. This is not a latency benchmark.
+
+Optional semantic compaction supplements deterministic evidence with an untrusted
+recollection from an explicitly chosen model. Selection, credentials and usage are
+separate from the primary model. It can summarize bounded, redacted local code
+from authenticated builtin read/search results as well as conversational decisions and diagnostics;
+the model is no longer limited to typed operational evidence. These excerpts
+share one input allowance and never include arbitrary external-tool/provider
+payloads. Source authentication uses a bounded process-local hash registry issued
+by actual builtin executions and bound to run ID, tool-call ID, tool name and
+complete output. Caller history, custom tools with builtin names and persisted
+metadata cannot issue this proof. Unauthenticated tool output, extra error fields
+and tool-call arguments are excluded before constructing either utility summaries
+or excerpts. Previously compacted envelopes without matching process-local proof
+retain only user objectives and steering; their markers alone grant no provenance
+for tool observations, paths, plans or recollections. Malformed envelopes are
+omitted. After restarting or evicting a proof, source excerpts become eligible
+again after new builtin reads.
+The semantic strategy is `hybrid-context-v3-attested-sources`, which changes the
+durable runtime fingerprint. See [CLI](CLI.md#configurable-model-assisted-compaction)
+and [model catalog](MODEL_CATALOG.md). Tool metadata, approval state and verification
+receipts remain outside the summarizer's authority. These runtime strategy changes
+alter durable fingerprints: finish old paused runs with their original artifact.
+Every run returns the matching persisted revision, including refreshed
+context and accounting metadata, rather than an older in-memory SDK projection.
+Named child agents keep their existing bounded runtime; these new primary-run
+context/progress/compaction integrations do not claim a child-runtime migration.
+
+### Correcting malformed read calls
+
+Provider-facing tool errors explain the difference between `read_file` (one
+string `path`) and `read_files` (an actual array of slice objects), and clarify
+that `endLine` is an absolute line number, not a count. The runtime does not
+execute, rename or silently repair malformed calls. Durable error receipts stay
+unchanged; the model must issue a corrected request, and edits still require
+current read evidence and approval.

package/docs/CREDENTIALS.md

@@ -40,7 +40,7 @@ outside the CLI support contract; adding this binding does not certify Windows.
 
 Environment keys take precedence over saved and temporary keys, including provider
 aliases. The CLI reports that precedence when managing a key while an environment
-key exists. Changing the saved key does not override the launching shell.
+key exists. For Qwen, explicitly configuring a connection selects its managed credential for the current CLI session, overriding Qwen shell settings. On a new launch, environment keys take precedence again.
 
 One-shot commands (`run`, `review`, `resume`), `providers`, and service connections
 retain their existing environment/host-owned behavior: they never prompt for keys
@@ -62,8 +62,40 @@ Keys are kept outside profiles, repositories, run metadata and chat history. Man
 keys are passed only to provider model clients, not to `process.env`, MCP or command
 execution environments. Do not paste a key into a normal conversation.
 
-Managed keys require default provider endpoints. Shell-defined base URL or Qwen
-region/workspace overrides are rejected before reading the keychain. To intentionally
-use a custom endpoint, supply its credential explicitly through the environment.
-Credential storage is separate from live provider validation; the first model
-request checks account access and may be billable.
+Managed keys for other providers require default endpoints. Qwen keys are bound to
+an explicitly selected service and region. When shell endpoint settings conflict,
+the console offers to use the saved destination for this session or cancel. It never
+sends a managed key to an arbitrary shell-defined endpoint. Custom endpoints still
+require explicit environment credentials.
+
+## Qwen interactive setup
+
+Open `/credentials` → Qwen → save or temporary → Standard API or QwenCloud Token
+Plan. Standard API asks for region and, where needed, a workspace ID. Then enter
+the hidden key. Service/region/workspace and key are stored together in the system
+keychain (or only in memory for temporary use); no key enters the profile.
+Existing raw Qwen keychain entries retain the historical Singapore API destination.
+Changing service requires entering the matching key; the CLI does not infer it
+from a key prefix. Cancellation preserves the previous connection.
+
+Select the model with `/model`, then use `/connection` for an optional small,
+potentially billable request. It sends no repository content or tools, allows 16
+output tokens, disables retries, and times out after 15 seconds. A successful test
+only verifies access to that model. Setup itself does not validate account access.
+Regional destinations follow the [official Model Studio region documentation](https://www.alibabacloud.com/help/en/model-studio/regions).
+
+## QwenCloud Token Plan
+
+Harness includes `@zhivex-ai/qwen` 0.15.2. For an interactive Token Plan session,
+set `QWEN_BASE_URL=https://token-plan.maas.qwencloudapi.com/compatible-mode/v1`
+and supply your dedicated Token Plan key through `DASHSCOPE_API_KEY` (or
+`QWEN_API_KEY`). Start `zhx chat --provider qwen --model qwen3.8-max`, or select
+`qwen3.8-flash`. Enter/export credentials privately; never paste them into chat
+or commit them. Leave `QWEN_WORKSPACE_ID` unset for this endpoint.
+
+The endpoint is explicit: Harness does not infer billing mode from a key prefix.
+The interactive setup also supports this fixed Token Plan endpoint with managed keys. Arbitrary custom endpoints require environment credentials.
+Use standard pay-as-you-go credentials for backend/scheduled workloads. See the
+[official Token Plan quickstart](https://docs.qwencloud.com/token-plan/personal/token-plan-personal-quickstart)
+for matching key types and endpoints. Account entitlements are provider-controlled;
+local transport tests do not certify access to a paid plan.

package/docs/DURABLE_OPERATIONS.md

@@ -2,6 +2,8 @@
 
 Zhivex Harness durable operations make local runs inspectable and recoverable across process restarts. The default store is runtime-portable SQLite at `<workspace>/.zhivex-harness/runs/operations.sqlite`, backed by `node:sqlite`; `--store file` remains a migration fallback. The `0.10.x` runtime change does not alter the SQLite file or table format.
 
+Before creating session or run state, Harness writes a local `.gitignore` that excludes all contents of `.zhivex-harness/` (or the configured custom state directory), including SQLite journals and file-store records. This protects untracked files from ordinary `git add`; it cannot override `git add --force` or untrack files already committed. If state was previously tracked, add `.zhivex-harness/` to the repository's root `.gitignore` and use `git rm --cached` on the tracked state files to keep local data while removing it from future commits. Existing Git history is unchanged and must be assessed separately.
+
 ## Scope and identity
 
 Every durable key is isolated by:
@@ -62,6 +64,14 @@ zhx sessions archive <sessionId>
 
 The store uses SQLite WAL transactions, optimistic revisions, workspace/scope hashes, owner-only permissions, soft deletion/retention, and bounded session/run/metadata/index sizes. It rejects a new run while the latest session run is active or waiting for approval. Fork and archive operations also require a terminal branch point.
 
+SQLite runs store steps, tool results and compaction records separately from the active checkpoint. Large repeated text is retained in per-run content-addressed artifacts. Checkpoint and history changes commit in the same transaction; unchanged historical records are not rewritten. The 4 MiB state limit applies to the active checkpoint, including current messages, approvals, metadata and counters. Conversation compaction still controls model input size independently.
+
+Loading a run reconstructs its complete state for compatibility with approvals, recovery and verification. Programmatic history inspection can use `store.loadHistory(runId, { field: "toolResults", offset: 0, limit: 50 }, scope)` to read a page. Full hydrated states and total disk usage can grow with the run; run retention remains necessary. File and in-memory stores retain the full-state size limit.
+
+Logical backups contain hydrated history rather than database references, so restoration does not require the original artifact tables. Exports up to 64 MiB retain the legacy JSON format; larger exports use the versioned `ZHIVEX-STATE-SEGMENTS-1` transport with bounded frames, including split strings. RC13 reads both formats and verifies the same logical checksum before import. Older versions cannot read segmented exports. File I/O and checksum serialization are incremental; the public backup/import APIs still hydrate the complete logical bundle in memory. Segmented files have no aggregate 64 MiB ceiling. A state-limit failure records a bounded terminal diagnostic on the last durable checkpoint; the unsaved payload is not claimed as preserved. Use `/status` to inspect the failed run before `/continue`. Recovery retains tool journal receipts and never re-executes an operation itself.
+
+Incremental SQLite history uses the published Core 1.26.0 and Agents 1.10.1 packages. No local dependency patch is required. Install this checkout with `bun install --frozen-lockfile`.
+
 ## Provider handoff safety
 
 Every console turn preallocates a new run ID and binds it permanently to one provider/model. Provider or model changes take effect only on the next run and are blocked while an approval is pending. Before transferring context to another provider/model, the console creates a bounded deterministic redacted summary: text is truncated and common credentials are removed, while tool inputs, outputs, and provider payloads are replaced by tool/type names.

package/docs/EXTENSIBILITY.md

@@ -8,12 +8,28 @@ Built-in registrations are Meta, Qwen, OpenAI, and Gemini. Each registration own
 
 Library callers can use `DEFAULT_PROVIDER_REGISTRY`, `BUILTIN_PROVIDER_REGISTRATIONS`, `createProviderRegistry`, or `DEFAULT_PROVIDER_REGISTRY.extend(...)`, then pass the registry to `resolveHarnessConfig`, `createProviderModel`, provider diagnostics, or `createHarness({ providerRegistry })`. Registration IDs, environment-variable names, defaults, diagnostics, and factories are validated before they become selectable.
 
-The coordinated SDK batch pins `@zhivex-ai/agents@1.9.0`, `@zhivex-ai/core@1.23.0`, `@zhivex-ai/meta@0.2.7`, `@zhivex-ai/qwen@0.15.1`, `@zhivex-ai/openai@0.13.5`, and `@zhivex-ai/gemini@0.12.2`. Qwen `0.11.x` normalizes missing, placeholder, and continuation tool-call identifiers inside the adapter; Harness retains its deterministic provider-boundary normalizer as defense in depth until the exact candidate passes the complete release-bound representative matrix. A Core override keeps one runtime contract identity across every adapter, while Core `1.13.0` corrects compaction usage accounting and interaction-group retention. OpenAI `0.11.2` preserves synthetic assistant history in Responses, so the harness no longer requires its compaction transport or accounting workarounds.
+The coordinated stable SDK batch pins `@zhivex-ai/agents@1.10.1`, `@zhivex-ai/core@1.26.0`, `@zhivex-ai/meta@0.2.8`, `@zhivex-ai/qwen@0.16.2`, `@zhivex-ai/openai@0.13.6`, and `@zhivex-ai/gemini@0.12.3`. Qwen 0.16.2 types malformed Responses tool arguments and malformed SSE events; Core 1.26.0 satisfies its published dependency range. These exact versions are pinned in the lockfile. Stable SDK publication does not replace Harness release-bound certification. Qwen `0.11.x` normalizes missing, placeholder, and continuation tool-call identifiers inside the adapter; Harness retains its deterministic provider-boundary normalizer as defense in depth until the exact candidate passes the complete release-bound representative matrix. A Core override keeps one runtime contract identity across every adapter, while Core `1.13.0` corrects compaction usage accounting and interaction-group retention. OpenAI `0.11.2` preserves synthetic assistant history in Responses, so the harness no longer requires its compaction transport or accounting workarounds.
 
 OpenAI is based on the GPT-5.6 family: `gpt-5.6-luna` is the default, with `gpt-5.6-terra` and `gpt-5.6-sol` available through `--model`. Availability remains organization-dependent while the upstream family is in limited preview, and the adapter uses the Responses API by default.
 
 Gemini still defaults to `gemini-3.6-flash`, uses `GEMINI_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY`, and accepts optional `GEMINI_BASE_URL`. Adapter `0.11.0` adds modeled Gemini 3.7 and media/realtime surfaces, but the default and support level do not change implicitly. Gemini remains provisional until proposal/approval/restart, delegation, mixed routing, and OCI execution pass the credentialed Harness live matrix; adapter-level evidence alone does not make the Harness integration certified.
 
+### Meta conversation continuity
+
+The built-in Meta route uses Responses with `store: false` and `include: ["reasoning.encrypted_content"]`. It sends retained messages, tool calls, receipts, and opaque encrypted reasoning on every turn. It does not depend on server-side response IDs. A narrow compatibility layer inserts reasoning items omitted by the pinned Meta SDK serializer; the SDK still owns ordinary serialization, streaming, and HTTP handling. Serializer-layout mismatches fail explicitly.
+
+Existing sessions retain visible history and tool receipts; reasoning from old turns that never requested encrypted content cannot be recovered. New encrypted items stay intact in the local checkpoint and are replayed only with retained turns. Model instances do not share replay buffers. No completed host tool is rerun to restore context.
+
+The legacy receipt-only recovery helper permits two backoffs, 1s then 2s, when Meta rejects a just-completed response ID. It never retries arbitrary invalid input or hosted-tool requests. The built-in stateless route does not need this recovery path.
+
+For a bounded live check of both generate and streaming replay, including a new model instance and JSON-restored history:
+
+```bash
+ZHIVEX_HARNESS_LIVE=1 bun --env-file=.env scripts/meta-replay-live-smoke.ts
+```
+
+The check makes four requests and reports only assertions; it does not print response IDs or encrypted content. It validates source behavior, not a newly published release artifact.
+
 ## Capability gate
 
 Every run requires streaming and callable-tool support by default. Add explicit requirements with repeatable CLI flags:
@@ -57,9 +73,9 @@ The schema is versioned independently:
 }
 ```
 
-Every server requires a non-empty tool allowlist and permission set. Tool discovery is paginated and bounded. Tool names are prefixed with `<server>_` unless an explicit safe prefix is supplied. Configuration contains environment-variable names rather than credential values; diagnostics and fingerprints never include resolved header values. Credential variables must use the dedicated `ZHIVEX_MCP_*` namespace, and HTTP authentication is limited to the canonical `authorization` and `x-api-key` headers so a workspace file cannot select unrelated process credentials or arbitrary outbound headers.
+Every server requires a non-empty tool or exact-resource allowlist and permission set. Tool discovery is paginated and bounded. Tool names are prefixed with `<server>_` unless an explicit safe prefix is supplied. Configuration contains environment-variable names rather than credential values; diagnostics and fingerprints never include resolved header values. Credential variables must use the dedicated `ZHIVEX_MCP_*` namespace, and HTTP authentication is limited to the canonical `authorization` and `x-api-key` headers so a workspace file cannot select unrelated process credentials or arbitrary outbound headers.
 
-The built-in transport supports HTTPS and loopback HTTP. Redirects, URL credentials, unsafe configurable headers, oversized configuration, symlinked configuration, and configuration outside the workspace are rejected. `stdio` is intentionally unavailable because spawning an MCP server is process execution; it remains deferred until the enforced execution environment in `0.6.x`.
+The legacy built-in transport supports HTTPS and loopback HTTP; the opt-in SDK transport requires HTTPS. Redirects, URL credentials, unsafe configurable headers, oversized configuration, symlinked configuration, and configuration outside the workspace are rejected. `stdio` is intentionally unavailable because spawning an MCP server is process execution; it remains deferred until the enforced execution environment in `0.6.x`.
 
 Library callers can inject a custom `McpClient`. Trusted read-only annotations are accepted only for an explicitly injected custom transport whose sole declared permission is `read`. HTTP always declares `network` and therefore always pauses for operator approval, even when a server claims a tool is read-only.
 
@@ -221,9 +237,90 @@ Human terminal mode reports child start and finish telemetry. `run-result` JSON
 
 ## Known limits
 
-- The built-in MCP transport implements bounded JSON-RPC over Streamable HTTP response forms; it does not support OAuth discovery, server-initiated sampling, roots, subscriptions, elicitation, or arbitrary SSE reconnection.
+- The legacy MCP transport implements bounded JSON-RPC over Streamable HTTP response forms; it does not support OAuth discovery, server-initiated sampling, roots, subscriptions, elicitation, or arbitrary SSE reconnection.
 - MCP prompt-injection detection is a safety filter, not a proof that remote content is trustworthy.
 - Parallel review groups have a durable shared parent identifier, but the group itself is not a standalone persisted agent state.
 - With `execution=none`, subagents share the host process and workspace and are policy boundaries rather than OS isolation. With `execution=oci`, they inherit the same acquired snapshot and environment authorization; this does not turn the local container runtime into a VM.
 - Generic host shell, `stdio` MCP, network-enabled OCI policies, and remote workers remain unavailable. The `0.6.x` OCI policy rejects all MCP before discovery rather than executing an undeclared client outside the acquired boundary.
 - Provider-specific orchestration behavior requires date-bound live certification and is separate from deterministic implementation evidence.
+
+## Allowlisted MCP text resources
+
+MCP servers may expose text resources as well as tools. Add `includeResources` with exact URIs to the existing MCP server configuration:
+
+```json
+{
+  "schemaVersion": 1,
+  "servers": [{
+    "name": "docs",
+    "transport": "http",
+    "url": "https://mcp.example.com/rpc",
+    "includeResources": ["docs://project/architecture"],
+    "permissions": ["read", "network"]
+  }]
+}
+```
+
+`includeTools` may be omitted or empty only when resources are explicitly allowlisted. Tool-only configurations keep their previous normalization and fingerprint. Discovery uses MCP `resources/list`; a server must list every requested URI within the configured `maxListPages`, `maxListedTools` (also the resource item cap), `listToolsTimeoutMs`, and per-response `maxOutputBytes` bounds. HTTP servers must declare the `resources` capability during initialization. Existing HTTPS/loopback restrictions, credential-header allowlist, no-redirect behavior, session negotiation and JSON-RPC response matching apply unchanged.
+
+The harness exposes `<toolNamePrefix>read_resource`, accepting exactly one allowlisted URI. Every read requires approval, including a custom read-only server with trusted tool annotations. Resource metadata carries the MCP origin and read/network permissions, so the scheduler cannot treat these calls as trusted workspace reads. Contents are fetched only after approval, limited by `callToolTimeoutMs` and `maxOutputBytes`, and returned as untrusted evidence. The reader rejects substituted URIs, probable prompt injection, binary blobs and malformed content. URI templates, wildcard grants, subscriptions and automatic context injection are not supported. `file:` URIs are sent to the MCP server; the harness does not open them as local files.
+
+Injected clients can implement the optional `listResources` and `readResource` methods on `HarnessMcpResourceClient`; existing tools-only `McpClient` implementations remain compatible. Custom operations receive abort signals and are bounded even when they ignore cancellation. Applications remain responsible for stopping any background work in their injected implementation after cancellation. The existing prohibition on host MCP clients under OCI execution also covers resource servers.
+
+Protocol reference: [MCP resources, 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/server/resources). The resource tools do not expose resource templates, prompts, or binary resource rendering. OAuth is available only through the explicitly selected SDK transport and a trusted host provider, described below.
+## Application tool policies (Experimental)
+
+`createHarness({ toolPolicy })` accepts trusted application-owned declarative rules
+with stable IDs, exact tool names, optional exact paths, reasons and `allow`,
+`ask_user` or `deny`. The most restrictive matching decision wins. An allow rule
+cannot remove existing approval requirements, enable a missing tool or weaken
+filesystem/OCI policy. The policy also wraps tools supplied to named child profiles.
+
+Path rules require a trusted `toolPolicyPaths(toolName, input)` resolver plus a
+stable `toolPolicyPathsVersion`. Its version and the policy digest bind durable
+resume. SDK approval flags are static, so a path-scoped ask rule conservatively
+requires approval for the entire named tool. Such tools are never parallel reads.
+`onToolPolicyDecision` receives the applied rule IDs and reason. Repository manifests
+cannot register these callbacks. Existing lifecycle hooks remain available.
+
+```ts
+const harness = await createHarness({
+  toolPolicy: { schemaVersion: 1, rules: [{
+    id: "review-deletes", tools: ["quarantine_file"], decision: "deny",
+    reason: "This application does not permit removing files."
+  }] }
+});
+```
+
+See [ACP](ACP.md) for the experimental text-session client adapter and
+[workspace checkpoints](WORKSPACE_CHECKPOINTS.md) for reviewed restoration and
+recovery. OAuth credential UI and process-based MCP remain unavailable. The
+explicit SDK HTTP path below supports host-owned OAuth providers.
+
+
+## SDK HTTP transport and host-owned OAuth (experimental)
+
+Existing configurations keep the MCP `2025-06-18` HTTP transport, including loopback HTTP. Opt into the SDK's reusable Streamable HTTP client with `protocolVersion: "2025-11-25"` on an HTTPS server. The version is included in the durable configuration fingerprint; there is no automatic downgrade or retry after a potentially effectful call.
+
+```json
+{
+  "schemaVersion": 1,
+  "servers": [{
+    "name": "docs",
+    "transport": "http",
+    "protocolVersion": "2025-11-25",
+    "url": "https://mcp.example.com/rpc",
+    "includeTools": ["lookup"],
+    "includeResources": ["docs://project/architecture"],
+    "permissions": ["read", "network"]
+  }]
+}
+```
+
+The selected SDK client handles session negotiation, capability checks, bounded JSON/SSE responses, protocol validation and typed resource requests. The harness retains exact tool/resource allowlists, text-only resource validation, untrusted-content handling, interrupt approvals and OCI restrictions. Every destination is pinned to the configured endpoint and redirects are prohibited. A host `destinationPolicy` can further restrict DNS/IP/tenant access; it cannot permit another server. DNS resolution enforcement remains the host deployment's responsibility. The harness propagates its per-operation deadline into the SDK's initialization fetch and host credential provider as well as the caller-facing operation.
+
+For OAuth, construct `createMcpOAuthProvider` from `@zhivex-ai/core/mcp-http` in trusted host code. The SDK implements PKCE, resource/issuer binding and token refresh. The host supplies the issuer/client ID, approved endpoints, token store and authorization callback flow. Workspace JSON cannot define an OAuth issuer, token store, browser action or raw credential.
+
+Pass that SDK provider to `createHarness` as `mcpHttpOptions: { docs: { auth: oauthProvider, destinationPolicy } }`, or directly to `createHarnessMcpTools(config, { httpOptions: { docs: { auth: oauthProvider, destinationPolicy } } })`. An existing host can instead inject `createHttpMcpClient(server, env, fetch, { auth: oauthProvider })` through `mcpClients`. The provider object and tokens are never added to persisted configuration. An OAuth provider cannot be combined with a static `authorization` header; the dedicated `x-api-key` environment header remains available where required.
+
+Authentication failures are surfaced with sanitized SDK error codes. The harness does not automatically launch login, select an issuer from untrusted metadata, or retry `tools/call`. An `INDETERMINATE` result means an external effect may have happened: reconcile it before retrying. Host OAuth injection is unavailable on the legacy protocol path. The SDK supports additional prompt/template APIs, but this harness deliberately exposes only its configured tools and exact text resources.

package/docs/FIRST_USE.md

@@ -1,11 +1,13 @@
 # First use
 
+This guide targets the unpublished `1.2.0-rc.13` candidate. Installation commands become available after protected publication to npm `next`; stable users can install `@zhivex-ai/harness@latest`.
+
 ## Install and start
 
 Install Node.js 22.13.0 or newer and Git. Then:
 
 ```sh
-npm install -g @zhivex-ai/harness@1.1.1
+npm install -g @zhivex-ai/harness@1.2.0-rc.13
 cd /path/to/your/project
 zhx
 ```
@@ -80,16 +82,16 @@ For command execution, configure [OCI isolation](EXECUTION_ENVIRONMENTS.md).
 With Bun 1.4.0 or newer and a supported Node runtime:
 
 ```sh
-bun add --global @zhivex-ai/harness@1.1.1
+bun add --global @zhivex-ai/harness@1.2.0-rc.13
 zhx
 ```
 
 For a disposable version/help/environment check without a global installation:
 
 ```sh
-bunx @zhivex-ai/harness@1.1.1 --version
-bunx @zhivex-ai/harness@1.1.1 --help
-bunx @zhivex-ai/harness@1.1.1 doctor
+bunx @zhivex-ai/harness@1.2.0-rc.13 --version
+bunx @zhivex-ai/harness@1.2.0-rc.13 --help
+bunx @zhivex-ai/harness@1.2.0-rc.13 doctor
 ```
 
 For source development, use the [contributor guide](https://github.com/Zhivex/zhivex-harness/blob/main/CONTRIBUTING.md).

package/docs/MODEL_CATALOG.md

@@ -31,7 +31,7 @@ To roll back, republish the earlier valid manifest at the same URL; clients acce
 
 ## Selection behavior
 
-Both selectors expose Primary models, Other models, and a custom ID option. Desktop searches across names, IDs and providers, expanding Other models for search results. Deprecation details and replacements accompany model choices.
+The CLI exposes Featured models, Other models, and a custom ID option; Desktop uses Primary models. Desktop searches across names, IDs and providers, expanding Other models for search results. Deprecation details and replacements accompany model choices.
 
 Catalog refresh never writes project or conversation selections and never silently migrates a selected model. A current ID missing from the catalog stays visible. Retirement is metadata, not proof of account access or an execution block; the provider decides whether a request is accepted. Remote defaults guide explicit choices in the selector. Runtime startup defaults remain the bundled defaults, preserving startup behavior without requiring networking.
 
@@ -46,3 +46,54 @@ The official [model catalog](https://developers.openai.com/api/docs/models), [GP
 ## Qwen default — 2026-09-22
 
 Revision `2026-09-23.2` restores `qwen3.8-max` as the bundled Qwen default for CLI, Desktop and RC.10 live certification. Max is Primary; `qwen3.8-flash` remains available under Other models. Existing profiles and conversation model selections are preserved. Max remains `unverified` for this candidate until its exact release-bound route passes certification.
+
+## Context limits and compaction advice
+
+Revision `2026-09-24.1` adds optional metadata without invalidating older schema-version-1 manifests. Older clients with a strict parser reject enriched manifests and fall back to their cache/bundle; upgrade clients before publishing the enriched manifest remotely.
+
+- `limits` records `contextWindowTokens`, `contextWindowType` (`combined` input plus output, or independently documented `input`), `maxOutputTokens`, and optional conservative `maxInputTokens`. Never infer limits from a name or another model version.
+- `pricing` records USD per million input/output tokens, optional cached-input price, a `scope` explaining the applicable tier and exclusions, and optional `maxInputTokens` above which the recorded rates must not be extrapolated. These are estimates, not billing guarantees. Regional or subscription pricing may differ.
+- `compaction.suitability` is `candidate`, `evaluated`, `unsuitable`, or `unknown`. Candidate is an editorial inference from documented text capabilities. Evaluated requires a summary-fidelity evaluation with a referenced report, not just provider marketing or a successful generation.
+- Each metadata group requires HTTPS `evidence.sourceUrl` and `evidence.checkedAt` (`YYYY-MM-DD`). Missing metadata means unknown, not zero or unlimited. Source links are evidence only and are never fetched automatically by recommendations.
+
+The first curated limits cover GPT-6 Astra/Sol/Luna, GPT-4o Mini, Qwen 3.8 Max/Flash, and Gemini 3.5 Flash-Lite/3.6 Flash/3.7 Flash/3.8 Flash. Values were checked against each model's official page on 2026-09-24; exact links and dates are embedded in the JSON. Qwen uses the lower documented thinking-mode input ceiling. Initial pricing covers those four OpenAI models and Gemini 3.5 Flash-Lite; other prices remain unknown rather than assuming a region. Other existing model IDs remain available, with unknown limits. No entry is promoted to Zhivex `verified` by adding provider documentation.
+
+`recommendCompactionModels(catalog, request)` is a pure advisory function. Its request includes a provider, estimated full input tokens (including instructions and wrappers), reserved output tokens, an optional allowlist of available models, and an optional clock/evidence age (90 days by default). It never changes the configured model, credentials, provider, or catalog defaults. It excludes unknown/stale limits, missing suitability, retired/deprecated models, and insufficient input/output capacity. Results expose exclusion reasons, route/quality warnings, and scoped cost estimates where known. Future-dated evidence is not considered fresh.
+
+Ranking prefers known estimated cost, then catalog order and ID. Unknown prices sort behind known prices; this does not claim that an unpriced model costs more. Legacy `evaluated` labels without an evaluation artifact are treated as candidates and reported with `compaction_evaluation_evidence_missing`; a label alone does not earn a quality preference. Pricing above an undocumented tier produces a warning and no estimate. Supply `availableModels` when account availability is known. An explicitly configured model remains the user's choice, including a custom ID; recommendations are never an automatic cross-provider fallback. Runtime token guards and actual usage accounting remain authoritative.
+
+
+## Shared SDK recommendation engine
+
+The harness uses `@zhivex-ai/core` 1.24.0 `createModelCatalog` and `recommendAuxiliaryModel` for limit validation, per-datum evidence freshness and cost estimates. `src/models/sdk-catalog-adapter.ts` adapts the existing version-1 manifest into that contract, converting USD per million tokens into the SDK's per-thousand units. It retains missing values, provider/model identities and exact source dates. Pricing above a locally recorded tier ceiling is omitted rather than extrapolated. Combined windows reject output limits larger than the window; separately published input windows allow independent output limits.
+
+The harness retains its curated inventory, defaults, chooser ordering, lifecycle policy and route validation labels. The core package's `defaultModelCatalog` is an explicitly frozen compatibility inventory, so it is not used to replace the current manifest. Release-managed upstream inventory lives in `@zhivex-ai/sdk`; `models:import` remains an explicit curation workflow. This integration removes duplicate recommendation calculations, without introducing an automatic inventory migration or depending on an unpublished checkout.
+
+The SDK requires an evaluation artifact with source, fixture, version, date and pass result for evaluated compaction quality. The current manifest's `evaluated` label has only generic evidence, so the adapter conservatively emits a candidate plus a warning instead of inventing an evaluation. Host lifecycle restrictions and compaction curation freshness remain additional harness checks; public recommendation arguments, return shape and existing reason codes are preserved. Recommendations remain advisory and never authorize credentials or automatically switch providers.
+
+## Featured choices, 2026-09-26
+
+Revision `2026-09-26-frontier` puts Qwen 3.8 Flash and Max on the first CLI page,
+followed by GLM 5.3, DeepSeek V4.1 Flash, Kimi K3 and Qwen 3.7 Plus. Third-party
+entries identify the model author separately from Alibaba Model Studio, the API
+provider. GPT-6 Astra, Sol and Luna appear before older GPT generations. The current
+model is labelled but does not displace featured models; saved selections and
+provider defaults do not change. Other models contains older generations and snapshots.
+
+The installed Qwen adapter declares these hosted model IDs and model-specific
+reasoning levels. Availability still depends on account, region and endpoint. No new
+entry is certified by listing it. Reviewed primary sources:
+
+- [Qwen 3.8 Flash release](https://www.alibabacloud.com/en/news/product/qwen38-flash-released-noi).
+- [GLM on Model Studio](https://help.aliyun.com/en/model-studio/glm): `glm-5.3`; Responses availability depends on region.
+- [DeepSeek V4.1 Flash on Alibaba](https://www.alibabacloud.com/blog/603550): `deepseek-v4.1-flash`; Token Plan uses a distinct endpoint and credential.
+- [Kimi on Model Studio](https://help.aliyun.com/en/model-studio/kimi-api): `kimi-k3`.
+
+Unknown context/output limits and prices for new entries remain unset; the selector
+does not infer them from model age or the provider default.
+
+Kimi K3 has an application-side compatibility restriction: current official Model
+Studio documentation requires Chat Completions and thinking-only mode. The harness
+uses that transport and offers only default reasoning for this entry, rather than
+exposing the broader levels/Responses route in the installed SDK snapshot. Explicit
+incompatible overrides fail before sending a request.

package/docs/README.md

@@ -20,6 +20,7 @@ Start with [First use](FIRST_USE.md). You only need `zhx` for everyday conversat
 - [Extensibility](EXTENSIBILITY.md): providers, MCP, routing and subagents.
 - [API stability](STABILITY.md) and [deprecations](DEPRECATIONS.md).
 - [Local service](LOCAL_SERVICE.md) and [client protocol](CLIENT_PROTOCOL.md).
+- [Experimental ACP text sessions](ACP.md) and [workspace checkpoint restoration](WORKSPACE_CHECKPOINTS.md).
 - [Durable operations](DURABLE_OPERATIONS.md), [repository editing](REPOSITORY_EDITING.md) and [change envelopes](CHANGE_ENVELOPES.md).
 - [Threat model](THREAT_MODEL.md) and [public repository security](PUBLIC_SECURITY.md).