mistri 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d46cab51a8a899ddd2e3cd0284a7e9eb4185d1362af158303adb97c2a404a657
-  data.tar.gz: 548bf1b8cdc9d22f304674eb5b876b624c16f6b3cc31839daba83909f78641a5
+  metadata.gz: 1414bffbf49921cf9e575ea1a8998cfc435b77325d80d55ed76e6564d63311c5
+  data.tar.gz: b707010a75d56d65a8c42b50a874807e0f529da6b5878246aa9b34239493c808
 SHA512:
-  metadata.gz: 69b2758b3b137714bb2bffc170ff6520f1d38851230ba19acabbb50042d28234ce934d74555fd328d12d1e8002afe6d96bab8dd21a06567411252e4aeabac973
-  data.tar.gz: 972354e7a95bebfa4f5918efa84f13cbc6e45e9e8dabdf49a60a4d210ecf7c11425866b2ad4d8b648916477568aa2ac69915c98d241311e3778c38667d570558
+  metadata.gz: b7781114db5365b8ce899af9ab50b8eaf2279979d8110a282d54a4fb3187a2576fc94821c3ddb550e9af3da8052ad64b14310c5136d3a064044aee57418c209b
+  data.tar.gz: d87fb8db281d3c6cedaea995054723f4f15d62e5268384393e16d655dfd45ba714e4b276c73c378307e8b3314ecec1108b3d320578edd659d77e6d07a8e34e2f

data/CHANGELOG.md

@@ -3,6 +3,473 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+## [0.6.1] - 2026-07-21
+
+- The ActiveRecord store and workspace read past the host's query cache.
+  Rails keeps the cache on for a job's whole span and serves repeated
+  identical queries from it, so a parent polling for a child's report inside
+  a job never saw the report land and every wait ran to its timeout, and a
+  workspace read could serve a stale document. Reads bypass only Rails'
+  cache: an open REPEATABLE READ transaction still pins its snapshot, so do
+  not poll from inside one.
+
+## [0.6.0] - 2026-07-12
+
+- Synchronous event subscribers now propagate the exact exception object even
+  when its class also names an internal failure: provider `Mistri::Error`
+  values, transport I/O and timeout errors, SSE `JSON::ParserError`, hook
+  failures, and automatic-compaction `CompactionError` can no longer be
+  swallowed, retried, folded into an errored assistant turn, or persisted as a
+  policy or tool failure. An owner-scoped private marker preserves provenance
+  through nested inline agents and unwraps only at the boundary that first
+  observed the subscriber. A mid-stream subscriber failure closes the
+  interrupted provider connection before propagating. SSE parse tolerance now
+  covers `JSON.parse` only, never its callback. Genuine provider, hook, tool,
+  and compaction failures keep their existing contracts; configured tool
+  timeouts still include progress delivery. Asynchronous background delivery
+  remains unable to raise into a caller that has already returned. A callback
+  that aborts child execution records the original failure class in its failed
+  terminal and dispatcher diagnostic; a post-terminal report callback failure
+  leaves the already-durable terminal and parent inbox intact and appears in
+  the diagnostic. Active subscribers add one short-lived boundary per provider
+  turn, tool batch, hook phase, or automatic compaction and one method/rescue
+  frame per delivered event, with no parsing, buffering, I/O, or string work on
+  the successful path.
+- Approval decisions now behave as a write-once register over the Session
+  store's durable order. The first valid decision is authoritative; repeating
+  that value is idempotent, while a conflicting caller receives
+  `Mistri::ConfigurationError`. Concurrent stale writers may both reach append,
+  but every later well-formed decision for that approval request is an inert
+  losing occurrence, including one that lands after the approved handler has
+  already returned. It cannot revoke the winner, alter settlement, or
+  permanently poison `open_approvals`, `resume`, replay, or compaction. The first
+  note remains authoritative.
+  Malformed decisions, decisions without a matching request, duplicate
+  requests, and ambiguous legacy reused-call approvals still fail closed or
+  interrupt conservatively. A newly appended decision adds one linear
+  control-state re-read to tell a racing loser that it lost; already-visible
+  idempotent retries do not append. No provider streaming path changes.
+- Anchored `edit_file` changes now compose safely with concurrent writers when
+  their Workspace advertises atomic conditional writes. The new optional
+  contract is `atomic_writes?`, `snapshot(path)`, and
+  `compare_and_write(path, content, expected_revision:)`, with immutable
+  `Mistri::Workspace::Snapshot` values and a public
+  `Mistri::WorkspaceConflictError`. Memory implements the contract under its
+  mutex; the optional Active Record adapter advertises it only for PostgreSQL
+  or an InnoDB table on MySQL2 or Trilogy, using exact-byte SHA-256 revisions,
+  unique-index create-only CAS, and short transactions without requiring
+  `lock_version`. It rejects atomic operations inside a host transaction rather
+  than joining a stale or overlong boundary, validates model identity against
+  the database catalog, restricts atomic scope to owned scalar equality values,
+  and reads the committed row before returning its revision. Single opts in
+  through a host `synchronize:` callback that must enforce the same complete
+  boundary and outer-transaction rule. Directory, MyISAM, and existing custom
+  four-method workspaces retain their documented legacy behavior. `edit_file`
+  applies its existing exact/fuzzy anchor outside any lock and retries only a
+  lost conditional write, up to three total attempts. An unrelated concurrent
+  change is preserved, while a target that no longer matches remains an
+  actionable typed edit failure. Callback, validation, I/O, deadlock, and other
+  host errors are never retried. Tool names and schemas are unchanged. A
+  committed storage transformation produces an explicit
+  read-before-continuing failure instead of a false exact-replacement claim.
+  Atomic editing adds owned snapshot copies, three exact-byte linear hashes,
+  one exact committed-byte comparison, and one conditional commit to the
+  ordinary edit path; Memory also returns an owned read copy. Conflicts add at
+  most two complete reapplications. Active Record capability adds cached schema
+  inspection on the first capability check, outside the edit path. No
+  provider streaming path changes. Dedicated MySQL 8.4/InnoDB and PostgreSQL CI
+  jobs prove real locking, readback, and unique-create behavior while the gem
+  retains zero runtime dependencies.
+- Built-in document reads, searches, and edits now return an explicitly failed
+  `ToolResult` when the document is missing or a requested replacement cannot
+  be applied. The same actionable text still reaches the model, but lifecycle
+  events, persisted tool messages, and provider-supported error signaling no
+  longer misclassify an expected document-tool failure as success. Tool names,
+  schemas, and successful results are unchanged.
+- Background dispatch now crosses a versioned, deeply owned JSON capability
+  boundary instead of closing over the spawn-time provider, Tool objects, Agent
+  options, and workspace state. Every `dispatcher:` requires a host
+  `runtime_factory:` that constructs a `SubAgent::Runtime` inside the worker;
+  the runtime provider model and unique Tool names must match the durable grant
+  exactly before any provider call or tool side effect. Missing, additional,
+  renamed, duplicated, non-Tool, reconstructed statically approval-gated, and
+  synthetic Skill capabilities fail closed before execution. New immutable
+  specs carry `spec_version`, require a model identity, reject unknown fields,
+  and omit the model-controlled `workspace` field. The identical canonical
+  spec is stored in the child Session before dispatch; `run_dispatched` compares
+  the complete queue copy and uses the stored grant for execution and report
+  routing, so a changed capability, task, model, name, or parent ID leaves the
+  child untouched. Legacy unversioned specs containing `workspace` remain
+  executable. Finished redeliveries are rejected before factory construction;
+  a configured child lease also rejects concurrent live redeliveries. The
+  compatible direct form receives the same grant checks.
+  Runtime factory exceptions remain retryable for queues by default; built-in
+  in-process runners and an explicit `retry_factory_errors: false` persist a
+  terminal failure before re-raising. An optional Runtime `cleanup:` hook runs
+  exactly once without masking a primary error. Generic child Agent options
+  are allowlisted and travel as one isolated Hash, so they cannot replace the
+  durable Session, task, signal, event sink, or other lifecycle state; Runtime
+  cannot add Skill capabilities. The dispatched
+  lease now spans runtime construction, execution, cleanup, terminal
+  persistence, and parent report delivery; it suppresses ordinary stop and
+  redelivery races while the tokenless lease remains live. Queued and
+  interrupted cancellations now deliver their durable stopped report while holding that
+  lease even when the queue never starts or retries the job; repeating stop
+  reconciles a transient parent-report failure. A queue copy that does not
+  match the persisted grant raises the public, non-retryable
+  `Mistri::DispatchGrantError`, which is reserved for grant binding.
+  Model selection records only its identity at spawn time; its provider is
+  constructed in the worker. `tools: []` now grants no tools, while omission
+  keeps the general pool or typed defaults, so an empty typed Definition can no
+  longer inherit the entire pool. Duplicate pool, model, or model-selected tool
+  names fail before a child starts, and Spawner owns copies of its policy
+  arrays. Dispatch adds one bounded spec ownership/comparison and one linear
+  capability-name check per child, outside all provider streaming paths.
+- Model-originated tool calls now cross a local execution boundary rather than
+  relying on provider guidance alone. Completed calls deeply own immutable JSON,
+  canonicalize symbol keys without coercing values, retain malformed encoded
+  input as a durable `arguments_error`, and stop at 8 MiB, 64 levels, 10,000
+  nodes, or a 64 KiB numeric token. The same numeric bound applies to encoded
+  JSON and programmatic custom-provider arguments. The Agent requires an object
+  argument envelope before `before_tool`, approval predicates, `ends_turn`,
+  handlers, or remote MCP calls. Invalid calls receive a bounded typed result in
+  band, emit no execution-start event, expose no received field values in core
+  errors, and do not prevent valid siblings from running. Results settled in
+  the same phase return in model-call order.
+  Completed tool-call IDs, names, signatures, and provider correlation IDs must
+  be non-empty UTF-8 strings. Live provider turns require IDs unique for the
+  session, and provider correlation IDs are unique within one assistant turn.
+  Persisted histories recognize only the `call_N` reuse without provider
+  correlation IDs that earlier releases synthesized for Gemini and the Fake
+  provider, after the prior occurrence was answered or crash-interrupted.
+  Replay, provider metadata, and compaction track each occurrence independently
+  while live IDs remain reserved for the full session. An unsettled reused-ID
+  approval that cannot distinguish its generation becomes an interrupted result
+  rather than executable stale authorization. Every other duplicate ID,
+  malformed call envelope, or non-assistant provider result rejects the whole
+  provider attempt before persistence, policy, or execution. The normal
+  provider retry contract retries unchanged history; exhaustion persists a
+  pairable error with no tool calls. An abort during normalization, validation,
+  policy, or approval evaluation interrupts every uncommitted call and parks no
+  approval. Custom
+  providers that emitted missing, blank, non-string, non-UTF-8, or duplicate
+  identifiers must correct their completed call contract. Each run or resume
+  validates every persisted message and audits call identity in one control-state
+  preflight before doing work, so malformed legacy history fails closed. The
+  preceding assistant entry remains the durable provider source; a normalized
+  approval stores the reviewed prepared call plus an explicit provenance
+  marker. Resume verifies pairing metadata and revalidates the exact approved
+  arguments without rerunning the normalizer. Requests must follow the exact
+  assistant call, and decisions must follow one request and carry an exact
+  boolean. Duplicate requests and malformed or mismatched controls fail closed.
+  The first valid durable decision wins; later well-formed decisions for that
+  approval request are inert. Legacy requests remain valid only when they
+  exactly mirror the source call.
+  Persisted tool results require one prior call with the exact name, settle in
+  assistant-call order within each direct or approval phase, and cannot cross
+  an unresolved approval; compaction may neither hide an open approval nor
+  split a completed call from its result.
+  `ToolCall#arguments_error?` is stable; its non-nil string remains an opaque
+  diagnostic rather than a public enum. Fake-provider default call IDs now use
+  a per-provider UUID namespace plus a monotonic sequence; explicitly scripted
+  `id:` values remain deterministic. New approval entries no longer duplicate
+  the source argument payload, and generated MySQL-family session tables use
+  LONGTEXT so a legal parallel tool turn is not constrained by MEDIUMTEXT's
+  16 MiB ceiling. Existing MySQL-family stores must migrate `payload` to
+  `size: :long`; generators cannot alter an installed table. `Stores::Memory`
+  owns durable appends while returning fresh mutable snapshots, matching stores
+  that decode each read.
+- Tool schemas compile once into the same deeply frozen canonical UTF-8 JSON
+  value used by provider serializers, so mutation and Ruby encoding cannot make
+  local validation disagree with the wire. Definition checks cover the complete
+  schema document. The zero-dependency runtime subset enforces JSON types and
+  unions, `enum`, `required`, `properties`, `prefixItems`, one-schema `items`,
+  boolean schemas, and boolean or schema-valued `additionalProperties`.
+  `argument_validator:` adds domain rules without weakening core;
+  `complete_argument_validator:` is separate explicit authority for every
+  argument-applicable non-empty `patternProperties` contract. Tool inputs use
+  JSON Schema 2020-12 and require an object root; legacy array-form `items` is
+  rejected in favor of `prefixItems`. A schema-less Tool is now a genuinely
+  closed no-argument contract; hosts that accepted model fields without
+  declaring them must add an explicit schema. The schema-less wire shape
+  changed with it, so provider prompt caches re-warm once per affected tool
+  set after upgrading. Supplied object schemas preserve
+  JSON Schema's default-open semantics unless a raw schema explicitly sets
+  `additionalProperties: false`; handlers should extract named fields instead
+  of mass-assigning model input. MCP bridging enforces directly reachable
+  portable constraints locally and keeps unsupported applicator subtrees and
+  other unimplemented standard assertions as guidance for the server, which the
+  MCP spec obligates to validate its own tool inputs. A complete validator takes
+  explicit whole-contract authority when local policy depends on those
+  assertions. External references and
+  explicit `inputSchema: null` are rejected in every mode, an omitted schema
+  still defaults to a no-argument object, and argument-applicable non-empty
+  `patternProperties` still requires complete authority. Common map schemas
+  work in core. Task mode rejects assertions local validation cannot guarantee
+  before making a provider request, then shares one deeply frozen strict schema
+  between its prompt and compiled local validator.
+  Providers derive a native constraint only for schema shapes their documented
+  and live-verified subsets accept; incompatible shapes fall back to the prompt
+  and local correction loop instead of failing the request. Native constraints
+  are limited to catalogued matching-provider models and documented provider
+  complexity ceilings; unknown models keep the local path. Raw task output is
+  byte-bounded, then lexically
+  width/depth-bounded before JSON parsing so wide hostile JSON is rejected
+  before parser allocation. A Tool-owned `argument_normalizer:` remains the
+  explicit compatibility seam and runs once before validation; approved calls
+  persist that canonical value and revalidate against the current schema on
+  resume without renormalizing or reevaluating approval. `edit_file` declares
+  its existing alias and string-boolean tolerance through that seam and rejects
+  alias collisions. Provider replay substitutes `{}` only as the wire placeholder
+  for an already rejected call, paired with its error result. Direct `Tool#call`
+  remains a trusted host path and skips Agent validation. Task output now uses
+  the same JSON resource limits. This is minor-release behavior for hosts whose
+  policy or handlers previously received malformed values, whose custom
+  validators relied on implicit full-schema authority, or whose code mutated or
+  indexed a Tool's raw schema with symbol keys. `Schema.strict` results are now
+  deeply frozen, and `Tool.define` raises when both `input_schema:` and `schema:`
+  are supplied instead of silently choosing one. Definition compilation is paid
+  once; a completed call adds one bounded ownership pass and one compiled schema
+  traversal, plus ownership only when a normalizer replaces the value. Streaming
+  tool snapshots deep-freeze each newly refreshed bounded preview once; deltas
+  that reuse the cached preview are O(1), and pairing strings are copied.
+  Completed call envelope verification is one linear pass over that turn's
+  calls. Run and resume add one linear control-state read of the session log to
+  seed O(1) identity checks. Encoded Anthropic/OpenAI arguments and task text add
+  one linear lexical scan before JSON parsing; it is off the token-delta path. A
+  normalized approval adds only a small provenance marker. Structured
+  output request building adds one bounded schema ownership pass; task plans
+  compile their local validator once, with no added work on token streaming.
+  Arguments are now deeply frozen before hooks and handlers; hosts that mutated
+  model-supplied hashes or arrays must copy them first.
+- Provider replay now keeps opaque state with its provider of origin. Gemini
+  sends tool schemas through `parametersJsonSchema`, preserves each signed part
+  boundary, and returns Google's function-call ID exactly when one was supplied;
+  legacy calls without a wire ID get a collision-safe internal ID without
+  mutating the signed provider part. On pre-3 Gemini turns, an earlier gated
+  same-name/no-ID call is rejected in band if a later sibling would answer
+  first; Gemini 3 wire IDs retain out-of-order pairing. A MAX_TOKENS turn never
+  executes a returned call. OpenAI treats a missing completed `arguments` field
+  as malformed instead of executing `{}`. Anthropic and OpenAI no longer place
+  another provider's signatures on their wire. These replay checks add constant
+  metadata work per completed block. Terminal records now fence later known
+  content for all three providers. Anthropic enforces
+  sequential and open content-block indexes plus the delta kind expected by the
+  open block. OpenAI enforces one open output item, its kind, any present item or
+  output-index correlation, and terminal event/status agreement. Unknown future
+  event types remain ignorable. The checks add only constant primitive
+  comparisons per known delta, with no parsing, copying, or I/O.
+  Completed foreign tool exchanges project to neutral text when a session
+  moves to Gemini, preserving the result without manufacturing a Gemini
+  function call that lacks Google's thought signature.
+  Real providers now emit the same initial `:start` snapshot as the Fake, and
+  every opened text, thinking, or tool-call block emits its matching end before
+  a terminal failure. Interrupted tool calls remain explicitly incomplete and
+  are stripped before Agent persistence; interrupted Anthropic thinking never
+  replays a partial signature.
+- Tool execution now emits `:tool_started` when each resolved call commits to
+  invocation and carries a structured failure fact end to end. A handler may
+  return `ToolResult(error: true)`; unknown tools, policy blocks,
+  handler exceptions, timeouts, pre-invocation interruptions, failed result
+  hooks, healed dangling calls, and MCP `isError` results set it automatically.
+  The flag is sticky through `after_tool` rewrites, so changing error text
+  cannot relabel a failed operation as successful. `Event#tool_error` is always
+  true or false on `:tool_result`; new tool messages persist the same value, and
+  legacy messages without it remain unknown and replay with the historical
+  unmarked provider shape. Human approval denial remains a normal control
+  outcome rather than an execution error. Anthropic receives `is_error: true`;
+  Gemini receives the documented `error` function-response key; OpenAI retains
+  textual output because its function-call output has no
+  execution-error member. Error text is not classified by prefix, and an error
+  bit never authorizes a mechanical replay because a side effect may already
+  have happened; the model may still choose a new call, so hosts retain
+  idempotency and reconciliation policy. `ends_turn` remains the host's stronger
+  floor-transfer policy even when a result is errored; `handed_off?` does not
+  claim confirmed tool success. The new lifecycle signal adds one synchronous
+  sink event per committed call. Partial streaming Event construction adds two
+  primitive checks and one immutable nil slot; partial Message construction
+  adds one nil check and one immutable nil slot, with no parsing, buffering,
+  I/O, or string work. Tool batches add one sentinel write at commitment and one
+  identity check per result so a hard worker exit distinguishes started calls
+  from untouched queue entries; same-batch ordering adds one short-lived
+  identity map and a linear post-join pass, plus a second identity map only when
+  `after_tool` is configured;
+  starts arrive on serialized worker-thread callbacks, while same-batch results
+  still emit in model-call order after the batch joins. `:tool_started` and
+  handler-progress subscriber exceptions propagate and never become tool
+  failures.
+  Unknown, blocked, denied, queued, and pre-invocation interrupted calls add no
+  start event.
+- A blockless nested object in the tool-schema DSL now declares a freeform JSON
+  object instead of leaking `LocalJumpError` during application boot. A bare
+  top-level `Schema.build` raises `ConfigurationError` with a useful message.
+  Constrained-output preparation now refuses this freeform shape, and directly
+  encountered explicitly open objects, with a schema path instead of silently
+  closing them and changing their meaning. Existing block-built and raw tool
+  schemas keep their wire shape. Tool-schema work remains definition-time;
+  constrained-output request building adds one openness check to its existing
+  property/item traversal, with no streaming or token-path work.
+- Provider and MCP JSON bodies, individual SSE lines, and stdio JSON records
+  now default to an 8 MiB ceiling, configurable with `max_record_bytes:`.
+  Successful bodies are counted incrementally, declared oversized bodies fail
+  before reading, streaming remains unlimited across individually safe records,
+  and error responses retain at most a 500-byte valid UTF-8 preview. Requests
+  use identity encoding so compressed expansion cannot bypass the boundary.
+  Overflow closes the connection or child process; an oversized MCP
+  `tools/call` response remains explicitly ambiguous and is never replayed.
+  Stdio timeouts now cover the complete record instead of only its first byte;
+  any in-flight stdio wire failure after `tools/call` is ambiguous, reaps the
+  child, and requires a clean handshake before the next operation. Explicitly
+  closing and reusing an MCP client also clears its session, negotiated
+  protocol version, and server information before the fresh handshake.
+  Each completed SSE record also receives a bounded 20,001-token lexical
+  preflight, derived from the 10,000-node canonical limit, plus depth and 64 KiB
+  numeric-token ceilings before JSON parsing. A distinct
+  `ResponseTooComplexError` preserves the exact boundary and bounds Gemini
+  argument allocation inside its enclosing record. Either size or complexity
+  overflow resets an MCP wire and its negotiated session. An unconfirmed
+  `tools/call` outcome becomes ambiguous and is never replayed; a matching result
+  received before an invalid trailing SSE record remains authoritative, while
+  the next operation still performs a fresh handshake. Fragmented Anthropic and
+  OpenAI tool arguments also carry an aggregate 8 MiB cap across SSE records.
+  Their live partial preview stops reparsing after a bounded 64 KiB schedule
+  while raw delta events continue unchanged; OpenAI's completed item remains
+  authoritative. Fragmented Anthropic thinking
+  signatures stop immediately at the same aggregate ceiling rather than
+  growing quadratically or replaying a truncated opaque value.
+  The hot path adds one byte-count addition and comparison per JSON socket or SSE
+  line fragment, then one bounded linear lexical pass over each completed SSE
+  record before the provider's existing JSON parse.
+- Remote MCP and server-side OAuth requests now default to public HTTPS and
+  direct connections. Every DNS answer is checked against the IANA
+  special-purpose registries, including embedded NAT64 destinations; one unsafe
+  answer rejects the whole set. Approved addresses are pinned without changing
+  Host, SNI, or certificate identity, alternates are tried only before request
+  transmission, and every connection cycle resolves and validates a fresh DNS
+  set, including Net::HTTP's internal reconnect cycles. Redirects and ambient
+  proxies cannot bypass the boundary. `allow_non_public:` is a narrow host
+  callback for approved internal HTTPS and explicit loopback development.
+  Client construction remains DNS-free; a reused socket adds no request-path
+  work. A new connection cycle pays one validated DNS lookup, with approved
+  candidates tried only before request transmission.
+- MCP custom headers are copied at client construction and transport-owned
+  headers are rejected; a token callable remains the dynamic authentication
+  path. Tool discovery rejects repeated cursors and defaults to at most 100
+  pages and 10,000 tools; hosts can adjust either ceiling.
+- MCP OAuth discovery now follows the required protected-resource and
+  authorization-server candidate order, uses exact candidate-aware resource and
+  issuer binding, honors challenge scope, requires S256 PKCE, and never adds
+  `offline_access` as gem policy. OAuth response bodies are uncompressed and
+  bounded to 256 KiB; token error descriptions cannot reflect credentials into
+  exceptions. A pre-registered client now requires its exact trusted `issuer:`,
+  and completion and refresh rediscover the token endpoint from that persisted
+  issuer instead of trusting a stored endpoint. New confidential flows persist
+  an explicit authentication method; legacy rows with a secret and no method
+  retain their previous `client_secret_post` behavior.
+- The MCP Rails generator now persists `issuer` instead of `token_endpoint` and
+  exposes `mcp_allow_non_public` as the host's shared egress-policy hook. Existing
+  generated models must add and pass an issuer, restart pending OAuth flows,
+  and thread their non-public policy through the client and all OAuth
+  operations. Existing connected rows must reconnect unless the application
+  independently recorded their exact historical issuer. An issuer must never
+  be inferred from a token endpoint.
+- GPT-5.6 Sol, Terra, and Luna are catalogued with their 1.05M-token context,
+  128K-token output ceiling, and standard paid pricing above and below the
+  272K long-context boundary. The `gpt-5.6` alias resolves to Sol. OpenAI usage
+  now separates billable GPT-5.6 cache writes from uncached input, keeping
+  compaction, reported cost, and cost budgets accurate.
+- Directory workspaces reject existing symlinks in model-controlled paths and
+  omit symlinked files from listings. In a stable, host-controlled tree, reads,
+  writes, and deletes no longer follow a link outside the configured root.
+- Streamable HTTP no longer replays an MCP `tools/call` when its response cannot
+  be confirmed. The server may already have committed the tool's side effect,
+  so the call now raises `AmbiguousDeliveryError` with an explicit do-not-retry
+  warning instead of transparently executing twice.
+- Refusals and content-filter stops surface honestly on every provider
+  instead of reading as clean stops or retryable truncations. Gemini's
+  verdict finish reasons (SAFETY, RECITATION, LANGUAGE, BLOCKLIST,
+  PROHIBITED_CONTENT, SPII, the image verdicts) and blocked prompts
+  (promptFeedback.blockReason, which previously read as a retryable
+  truncated stream) fail fast as Mistri::InvalidRequestError with the
+  wire word in the message. MISSING_THOUGHT_SIGNATURE is a deterministic input
+  failure; its model fumbles and incomplete sentinels
+  (MALFORMED_FUNCTION_CALL, UNEXPECTED_TOOL_CALL, TOO_MANY_TOOL_CALLS,
+  MALFORMED_RESPONSE, FINISH_REASON_UNSPECIFIED, NO_IMAGE, and the catch-all
+  OTHER pair, documented as unknown reasons rather than rulings) error retryably.
+  Anthropic's refusal
+  stop reason fails fast carrying stop_details' category and explanation
+  (the API's guidance is a different model, never a same-model retry),
+  and model_context_window_exceeded maps to :length per its guidance.
+  OpenAI's incomplete_details content_filter and structured-output refusal
+  parts or deltas fail fast instead of reading as a completed answer; unknown
+  incomplete reasons retry rather than becoming clean stops. Partial content
+  stays on the errored message for hosts to show. Genuinely undocumented future
+  Gemini stop reasons still tolerate as clean stops, unchanged. Anthropic and
+  OpenAI top-level stream errors now classify documented authentication,
+  request/policy, rate-limit, timeout, overload, and server failures by their
+  wire code rather than retrying deterministic 4xx errors.
+- Active session execution is not yet leased. Store appends from approvals,
+  steers, and reports remain concurrency-safe, but hosts must allow only one
+  `run` or `resume` at a time for a session. Even with one runner, a crash,
+  result-store failure, or subscriber exception after invocation but before
+  result persistence can leave an approved call open for possible duplicate
+  re-execution. Simultaneous runners widen the same risk. Hosts must use
+  idempotency/reconciliation across that commit gap; durable atomic claiming is
+  the next synchronization feature, not simulated by a local mutex.
+- Sinks::Coalesced is origin-aware and thread-safe: a background worker's
+  deltas no longer merge into the parent's (or another worker's) event at
+  the same content index, and concurrent emitters serialize on an
+  internal mutex instead of racing the buffer. One uncontended mutex
+  acquire per event, at coalesced rate; nothing changes on the token
+  path.
+- OpenAI response.failed events classify by their error code instead of
+  all reading as a retryable truncated stream: rate limits and server
+  errors stay retryable, timeouts retry, and permanent rejections
+  (invalid_prompt, the image family) carry the new
+  Mistri::InvalidRequestError shape and fail fast, so the loop no longer
+  burns its retry budget on input the provider already ruled out. A
+  failed response without an error object now errors instead of reading
+  as a clean stop.
+- The model catalog carries each model's published standard paid direct-API
+  prices. Assemblers price every turn's usage from them: message.usage.cost and
+  Result#usage now report list-price dollar estimates for catalogued models, and the
+  Budget cost_usd ceiling actually stops a run. It never could before:
+  nothing computed cost, so the comparison always saw zero. Pricing is
+  selected per request, including GPT-5.4/5.5 and Gemini Pro long-context
+  tiers and Sonnet 5's September 2026 rate change. Unpriced usage is marked
+  unknown instead of free. A cost ceiling rejects an unknown model or origin
+  at construction and fails closed when a request's pricing is unknown at
+  runtime. Catalog pricing requires an explicit `catalog_pricing:` opt-in on
+  custom origins and observes service-tier policy without changing it;
+  nonstandard or unreported tiers stay unknown. A deterministic standard tier
+  is required up front for cost-budgeted Anthropic and OpenAI agents; Gemini's
+  reported standard, Flex, or Priority tier is honored rather than assuming
+  standard. Cost ceilings remain soft and are checked between model-visible
+  turns. An unmetered attempt raises Mistri::BudgetError instead of retrying
+  under false certainty; the error and an unpriced_attempt session entry retain
+  its partial accounting. Run usage includes every retry and compaction attempt,
+  and retry session entries now carry their own usage. Truncated streams preserve
+  partial token counts but mark their dollar total unknown.
+- Compaction now uses the published 1M context windows for catalogued Fable,
+  Opus, and Sonnet models and the 1.05M windows for GPT-5.4 and GPT-5.5.
+  Automatic headroom protects a full next output plus framing slack when the
+  provider shares input and output capacity; Gemini's separately published
+  input limit keeps input-only headroom. An explicit `reserve:` still wins as
+  host policy.
+  `Compaction#automatic_reserve?` lets hosts distinguish the default mode from
+  an explicit 16,384-token policy without changing `Compaction#reserve`.
+  Usage reported before the latest compaction no longer makes a fresh summary
+  appear full. A single run can compact repeatedly across tool turns while
+  keeping parallel calls paired with every result. Large tool results are
+  bounded only on the lossy summarizer wire, with their beginning and end
+  retained. That shortening never mutates the stored result or an ordinary
+  request that still replays it. Compacted replay intentionally remains
+  summary plus tail. The live
+  provider harness now proves two compactions, an exact tool-token handoff,
+  and final fact recall inside one run.
+
 ## [0.5.0] - 2026-07-08
 
 - The children registry: Session#children lists every sub-agent a session
@@ -46,7 +513,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   requires inline mode, enforced in band.
 
 - Report delivery: a background child's terminal outcome reports back to
-  its parent, exactly once. The report queues in the parent's inbox as a
+  its parent. The report queues in the parent's inbox as a
   typed subagent_report entry and folds at the next turn boundary the way
   a steer does (the model sees `[Magpie finished] <report>`; failures
   carry the error, stops say so), and a report landing as a run finishes
@@ -54,9 +521,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   event (agent, session_id, status, content) closes the child's lane in
   whatever UI watched the spawn. Session#pending_inbox is the
   steers-and-reports view (hosts that wake idle sessions on steers should
-  watch it instead); Session#deliver_report is the idempotent primitive
-  underneath.
-- Dispatched runs are fenced by the child's lease, taken before the
+  watch it instead); Session#deliver_report drops sequential duplicate
+  delivery by child Session ID. Concurrent callers need serialization.
+- With a lock adapter, dispatched runs use the child's lease before the
   run-or-not decision: a queue that redelivers a live job leaves the
   owner alone, a retry of a finished or cancelled child is a clean no-op,
   and a retry of a child a crashed process left mid-run runs it again
@@ -415,4 +882,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Reserved the gem name.
 
+[Unreleased]: https://github.com/mcheemaa/mistri/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/mcheemaa/mistri/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/mcheemaa/mistri/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/mcheemaa/mistri/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/mcheemaa/mistri/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/mcheemaa/mistri/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/mcheemaa/mistri/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/mcheemaa/mistri/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/mcheemaa/mistri/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/mcheemaa/mistri/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for wanting to make mistri better.
+
+## Setup
+
+```console
+$ bundle install
+$ bundle exec rake test      # hermetic, fast, no keys needed
+$ bundle exec rubocop
+```
+
+The live suites need provider keys in a gitignored `.env.development.local`
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`):
+
+```console
+$ MISTRI_LIVE=1 bundle exec rake test      # gated live tests
+$ bundle exec rake integration             # critical end-to-end scenarios, per model
+```
+
+Missing keys skip their provider. Read the output before treating a live run as
+three-provider coverage.
+
+## The rules that keep the gem what it is
+
+- **Zero runtime dependencies.** Development and test dependencies are fine;
+  a runtime dependency needs an unusually good reason.
+- **Tests ship with the change**, in the same commit. New provider-touching
+  behavior gets a live test.
+- **Errors follow their boundary.** A tool failure becomes a tool result the
+  model can react to. Built-in provider failures finish as an errored Result;
+  direct MCP Client and configuration failures raise. A bridged MCP Client
+  failure crosses the ordinary tool-result boundary.
+- **Sessions are append-only.** Derive state from the entry log; never
+  require a repair step after a crash.
+- **Comments say why, not what.** Few and load-bearing.
+- Run `bundle exec rubocop` before pushing; CI enforces it and a coverage
+  floor.
+
+## Pull requests
+
+Small, focused, sentence-case titles. Describe the why in a paragraph, not
+a checklist. If the change alters public behavior, add a CHANGELOG entry
+under Unreleased.
+
+## Documentation
+
+The README is the adoption path: category, first success, fit, core mechanism,
+and honest reliability boundaries. Put detailed contracts in the task-oriented
+Markdown guides under `docs/`, and put required host migrations in
+`UPGRADING.md`. Link repository files relatively so links work on branches and
+pull requests. Do not duplicate the changelog into a guide.