mistri 0.5.0 → 0.6.0

data/docs/sessions.md

@@ -0,0 +1,295 @@
+# Sessions and control
+
+A session is Mistri's source of truth: an append-only sequence of typed JSON
+entries. Messages, approvals, steering, compaction boundaries, child links, and
+reports share that one record. Derived state is rebuilt from the log instead of
+being repaired in place after a crash. Persistence strength belongs to the
+chosen store.
+
+## Sessions
+
+Every Agent has a Session. Without one, Mistri creates an in-memory session:
+
+```ruby
+agent = Mistri.agent("claude-opus-4-8")
+agent.session.id
+```
+
+Pass a persistent store when work must survive a process:
+
+```ruby
+store = Mistri::Stores::JSONL.new("tmp/mistri-sessions")
+session = Mistri::Session.new(store: store)
+
+agent = Mistri.agent("claude-opus-4-8", session: session)
+agent.run("Start the research plan.")
+
+reloaded = Mistri::Session.new(store: store, id: session.id)
+Mistri.agent("claude-opus-4-8", session: reloaded).run("Continue the plan.")
+```
+
+`Session#entries` returns the raw typed log. `Session#messages` returns the
+provider-neutral conversation after replay and compaction. `Session#transcript`
+returns a presentation-oriented entry view with inline image bytes removed. It
+is not an authorization or redaction boundary: prompts, tool arguments and
+results, UI payloads, errors, and provider metadata can remain. Authorize and
+redact before exposing a transcript.
+
+Mistri does not encrypt JSONL or Active Record session payloads. The host owns
+storage encryption, access control, retention, deletion, and redaction specific
+to the application. Treat the complete session record as sensitive data.
+
+## Store contract
+
+A store implements:
+
+```ruby
+append(session_id, entry_hash) # append one JSON-shaped entry
+load(session_id)               # return entries in append order
+```
+
+The store must preserve each append as one entry, provide a stable total order
+per session, and make a successful append visible to subsequent loads. Values
+returned by `load` must not let caller mutation rewrite durable history: return
+fresh decoded copies or deeply immutable snapshots. Mistri does not rely on
+Ruby object identity. `Session#append` normalizes entries through JSON, so store
+implementations see string keys and JSON values.
+
+Built-in stores are:
+
+- `Mistri::Stores::Memory` for one process and tests;
+- `Mistri::Stores::JSONL` for one file per session;
+- `Mistri::Stores::ActiveRecord` for a host model and database.
+
+JSONL closes each append, so completed lines survive an ordinary process
+restart. It does not call `fsync`, provide a database transaction, or promise
+power-loss durability. Use a database or host store when that distinction
+matters.
+
+### Active Record
+
+The adapter is opt-in and Mistri never requires Rails at boot:
+
+```ruby
+require "mistri/stores/active_record"
+
+store = Mistri::Stores::ActiveRecord.new(AgentEntry)
+```
+
+Generate a host-named model and migration in Rails:
+
+```console
+$ bin/rails generate mistri:install AgentEntry
+```
+
+The table needs `session_id`, `position`, and `payload`, plus a unique index on
+`[session_id, position]`. The unique index is the optimistic append boundary for
+independent writers.
+
+On MySQL and Trilogy, `payload` must be LONGTEXT because one legal parallel
+tool turn can exceed MEDIUMTEXT even while each call stays inside its own
+limit. New migrations use `size: :long`. Existing tables need a host migration:
+
+```ruby
+change_column :agent_entries, :payload, :text, size: :long, null: false
+```
+
+PostgreSQL `text` does not need that change.
+
+## Run and resume
+
+`run` appends a new user input and advances the model loop. Do not call it while
+the session has open approvals; use `resume`.
+
+`resume` does not append user text. It audits open approval state, returns
+immediately if a decision is still missing, settles decided calls, and then
+continues the existing exchange.
+
+Rebuild the Agent with the current tool definitions, authorization context,
+hooks, provider configuration, and business policy before resuming. The Session
+contains durable facts, not frozen application policy.
+
+## Human approval
+
+Declare a boolean or argument predicate on the tool:
+
+```ruby
+send_gift = Mistri::Tool.define(
+  "send_gift", "Sends a physical gift.",
+  schema: lambda {
+    string :recipient_id, "Recipient ID", required: true
+    number :value_usd, "Gift value", required: true
+  },
+  needs_approval: ->(args) { args.fetch("value_usd") > 100 },
+) do |args|
+  Gifts.send!(
+    recipient_id: args.fetch("recipient_id"),
+    value_usd: args.fetch("value_usd"),
+  )
+end
+```
+
+When the model calls it:
+
+```ruby
+result = agent.run("Send the launch gift to customer 42")
+result.awaiting_approval? # => true
+
+call = result.pending.first
+session_id = agent.session.id
+```
+
+The handler has not run. Persist or route `session_id` and `call.id` in the
+host's own UI. A decision needs only a store and Session:
+
+```ruby
+session = Mistri::Session.new(store: store, id: session_id)
+session.approve(call.id, note: "Approved by finance")
+# or: session.deny(call.id, note: "Use the standard gift instead")
+```
+
+The decision may be appended from another process at any later time. Nothing
+sleeps while waiting. To continue:
+
+```ruby
+session = Mistri::Session.new(store: store, id: session_id)
+agent = Mistri.agent(
+  "claude-opus-4-8",
+  tools: current_tools,
+  session: session,
+  context: current_authorization_context,
+  before_tool: current_policy,
+)
+
+result = agent.resume
+```
+
+Approved arguments are the exact prepared value the human reviewed. Resume
+verifies their source and pairing metadata, revalidates them against the current
+schema, and runs `before_tool` again. It does not renormalize or reevaluate the
+approval predicate.
+
+`Session#open_approvals` derives every still-open call and its decision from the
+log. A decision is single-assignment: the first valid decision in durable store
+order wins, repeating that winning value is idempotent, and a conflicting caller
+receives `Mistri::ConfigurationError`. Concurrent losing attempts can remain in
+the raw append-only log, but they are inert and cannot revoke the winner or
+corrupt the Session. The first note wins. Duplicate requests and malformed,
+orphaned, or mismatched controls still fail closed.
+
+Mistri does not implement quorum or denial precedence. Resolve multi-reviewer
+policy in the host before recording its one final Session decision. A host that
+must prevent losing attempts from reaching the raw log also needs to serialize
+its decision endpoint; the two-method store contract reconciles concurrent
+appends rather than conditionally preventing them.
+
+Denial is returned to the model as an expected result so it can choose another
+path. It is not marked as a tool execution error.
+
+## Steering and the inbox
+
+Steering queues a user message for the next turn boundary:
+
+```ruby
+Mistri::Session.new(store: store, id: session_id).steer(
+  "Focus only on contracts renewed this quarter."
+)
+```
+
+The active Agent does not need to be shared with the writer. If a steer lands
+while the model finishes cleanly, the run extends for another turn so the new
+instruction is answered.
+
+Background child reports use the same ordered inbox. A host that wakes idle
+sessions should watch `session.pending_inbox`, not only
+`session.pending_steers`, so worker reports receive the same treatment.
+
+Inbox consumption is itself an append: the folded message records the source
+entry ID. A crash cannot consume a steer invisibly or require a repair write.
+
+## Compaction
+
+For a catalogued model, automatic compaction begins when estimated context use
+crosses the published window minus safe output headroom. Disable it with
+`compaction: false`, or pass policy explicitly:
+
+```ruby
+settings = Mistri::Compaction.new(
+  reserve: 64_000,
+  keep_recent: 24_000,
+  instructions: "Preserve decisions, identifiers, and unresolved risks.",
+)
+
+agent = Mistri.agent("claude-opus-4-8", compaction: settings)
+```
+
+An explicit `window:` enables compaction for an uncatalogued deployment. An
+explicit `reserve:` is host policy; the automatic default otherwise protects a
+catalogued model's shared output capacity plus framing slack. Gemini publishes
+an independent input limit, so its automatic reserve remains input-oriented.
+
+```ruby
+agent.context_usage
+# => { tokens: 141_000, window: 1_000_000, fraction: 0.141 }
+
+agent.compact
+```
+
+Manual `compact` returns nil when there is no useful cut. During a compaction,
+`:compacting` announces that work began. The later `:compaction` event carries
+the visible summary in `event.content`.
+
+The summary and kept-tail boundary append to the session. Provider replay then
+uses the visible summary plus the retained tail, while the full original log
+remains available through `entries` and `transcript`. Compaction cannot hide an
+open approval or split a completed tool call from its result.
+
+Very large tool results may be shortened only in the request sent to the
+summarizer. The durable result and ordinary replay remain unchanged until a
+successful compaction intentionally replaces earlier context with the summary.
+
+## Provider changes
+
+The shared message model permits a session to continue with another built-in
+provider. Opaque reasoning, signatures, and pairing metadata replay only to the
+provider that created them.
+
+Completed foreign tool exchanges become a neutral representation when needed.
+In particular, Mistri does not manufacture a signed Gemini function call from
+another provider's metadata.
+
+Changing providers can alter model behavior even when replay is valid. Treat it
+as explicit host policy, not transparent failover.
+
+## Transcripts and child sessions
+
+```ruby
+session.transcript
+session.transcript(include_children: true)
+```
+
+With `include_children: true`, each child transcript is spliced after its link
+entry. Entries carry the same origin labels used by live events, so a reloaded
+UI can reconstruct parent and worker lanes. See [Sub-agents](sub-agents.md).
+
+## Concurrency and crashes
+
+Independent appenders such as approvals, steering, and child reports are part
+of the design. Active execution is different: only one Agent may call `run` or
+`resume` for a session at a time.
+
+Mistri persists each completed message promptly, but a process can still fail
+after a handler starts or commits an external write and before its result is
+durable. Replay heals an unanswered call with an interrupted error so the
+provider history remains pairable. That error explicitly says the tool may
+have run; it does not make replay safe.
+
+Hosts must serialize active runners and make side effects idempotent or
+reconcilable. Read [Reliability](reliability.md) for the complete contract.
+
+## Related guides
+
+- [Tool contracts](tool-contracts.md)
+- [Sub-agents](sub-agents.md)
+- [Reliability](reliability.md)
+- [Upgrading](../UPGRADING.md)

data/docs/sub-agents.md

@@ -0,0 +1,401 @@
+# Sub-agents
+
+A sub-agent runs a self-contained task in a new Session. Its exploration stays
+out of the parent's context; only the final report returns. The child transcript
+remains linked for inspection, streaming, and UI reconstruction.
+
+Mistri supports two shapes on that mechanism:
+
+- a fixed specialist curated by the host;
+- a host-bounded spawn tool whose model chooses a name, instructions, type,
+  tool subset, model, and execution mode within explicit allowlists.
+
+The open Spawner rejects `spawn_agent` in its own pool, so model-composed
+recursive spawning is not available by default. A host may deliberately give a
+fixed specialist another specialist or spawn tool; nested origins and
+transcripts are supported.
+
+## Fixed specialists
+
+```ruby
+researcher = Mistri::SubAgent.new(
+  name: "researcher",
+  description: "Reads approved sources and answers factual questions.",
+  provider: Mistri.provider("claude-haiku-4-5"),
+  system: "Research the question. Return findings and source URLs.",
+  tools: [fetch_page],
+)
+
+agent = Mistri.agent(
+  "claude-opus-4-8",
+  tools: [researcher.tool],
+)
+```
+
+Each call creates a fresh child Session in the parent's store. The model may
+provide a display name for that run, so parallel specialists can appear as
+distinct lanes.
+
+Pass `schema:` to validate a normally completed report as structured output.
+An `ends_turn` tool hands off with unvalidated text and `output` nil, so do not
+grant one when every report must satisfy the schema. Other Agent options, such
+as a budget or compaction policy, pass to the child through
+`Mistri::SubAgent.new`.
+
+## The spawn tool
+
+The open spawner lets the parent compose a worker from a pool the host controls:
+
+```ruby
+spawn = Mistri::SubAgent.spawner(
+  provider: child_provider,
+  tools: [fetch_page, search_catalog],
+  models: ["claude-haiku-4-5", "gpt-5-nano"],
+  max_children: 4,
+)
+
+agent = Mistri.agent("claude-opus-4-8", tools: [spawn])
+```
+
+The generated `spawn_agent` tool asks for a complete task and system
+instructions. The model may select only tools in the pool and only model IDs in
+`models:`. Without an explicit model, an inline child inherits the supplied
+provider object. A background child records that provider's model identity and
+the Runtime factory reconstructs its provider inside the worker.
+
+Do not place `spawn_agent` inside its own tool pool. Mistri rejects that host
+configuration.
+
+### Typed workers
+
+Definitions let the host own a worker's base prompt and its default tools and
+model:
+
+```ruby
+types = {
+  "researcher" => Mistri::Definition.load("agents/researcher.md"),
+  "reviewer" => Mistri::Definition.load("agents/reviewer.md"),
+}
+
+spawn = Mistri::SubAgent.spawner(
+  provider: child_provider,
+  tools: [fetch_page, search_catalog, inspect_record],
+  types: types,
+  models: ["claude-haiku-4-5"],
+)
+```
+
+A typed worker always begins with its Definition's rendered prompt. The model
+may append focus instructions, choose another subset from the host's tool pool,
+and select another model from the explicit allowlist. Without those overrides,
+the Definition's declared tool names and model are the defaults. Definitions
+are checked when the spawner is built, so a missing pool tool or unresolved
+placeholder fails before a model can spawn. Use a fixed `Mistri::SubAgent` when
+the worker's tools and model must not be model-selectable.
+
+`general-purpose` remains the built-in open type and requires model-written
+instructions.
+
+## Execution modes
+
+Without a dispatcher, a child runs inline inside the tool call. The parent waits
+for the report, and its abort signal cascades to the child.
+
+Add a dispatcher to expose `mode: "background"`:
+
+```ruby
+runtime_factory = lambda do |spec|
+  workspace = HostWorkspaces.for_child(spec.fetch("session_id"))
+  provider = HostModels.build(spec.fetch("model"))
+  tools = HostTools.build(spec.fetch("tool_names"), workspace: workspace)
+
+  Mistri::SubAgent::Runtime.new(
+    provider: provider,
+    system: HostAgents.system_for(spec),
+    tools: tools,
+    cleanup: -> { HostAgents.release(provider: provider, tools: tools) },
+  )
+end
+
+tools = Mistri::SubAgent.pack(
+  provider: child_provider,
+  tools: [fetch_page, search_catalog],
+  dispatcher: Mistri::Dispatchers::Thread.new,
+  runtime_factory: runtime_factory,
+)
+```
+
+`pack` returns the spawn tool plus `list_agents`, `read_agent`, `steer_agent`,
+and `stop_agent`. A dispatcher always requires `runtime_factory:`. The static
+provider, tool pool, types, and model allowlist declare what the model may
+request. The factory constructs what one background child may actually use.
+
+`Mistri::SubAgent::Runtime` holds the provider, system prompt, exact tools, an
+optional `cleanup:` callable, and safe Agent options for one execution:
+`budget`, `max_concurrency`, `transform_context`, `compaction`, `retries`,
+`before_tool`, `after_tool`, and application `context`. `skills:` is refused in
+a background Runtime because Agent would add a `read_skill` tool outside the
+durable grant. Lifecycle keywords such as `session`, `task`, `signal`, and
+`emit` are never Agent options; the child boundary owns them. The same option
+validation applies to fixed specialists and Spawner. Spawner-level Agent
+options still apply only to inline children; put a background child's options
+on its Runtime.
+
+Mistri calls the factory inside the worker after ruling out a finished
+redelivery. While a configured child lease remains live, it also rules out an
+ordinary concurrent delivery first. It then requires the runtime provider's
+model and the unique runtime tool names to match the versioned dispatch spec
+exactly.
+Missing, additional, renamed, duplicated, or statically approval-gated runtime
+tools fail the child before a provider call or tool side effect. Runtime tools
+are reordered to the durable grant so provider prompt order is deterministic.
+Mistri calls `cleanup` exactly once for a Runtime the factory returned,
+including after validation or execution failure. A cleanup failure does not
+replace an active primary error; by itself it raises after the terminal result
+and report are durable. Use it to release per-child providers, MCP clients, or
+other connections. Mistri does not guess which objects the host owns.
+
+The model has no workspace selector. Derive resource scope from trusted host
+state and stable identifiers such as the child Session ID, not from its name,
+task, or instructions. Reconstructing a Ruby object is not itself isolation:
+the host must decide whether two runtimes use separate directories, database
+rows, credentials, MCP clients, or other backends. Use the same deterministic
+child scope on a queue retry rather than creating a random empty workspace.
+
+### Thread dispatcher
+
+`Mistri::Dispatchers::Thread` starts a Ruby thread and returns a receipt to the
+parent immediately. The runtime factory executes on that thread. The host must
+still construct fresh or deliberately shared dependencies; a Proc can close
+over any object, and Mistri does not pretend to inspect its closure. The Thread
+dispatcher is useful for development and short work in a process whose
+lifetime the host controls. It is not a durable job queue.
+
+### Queue dispatcher
+
+A production host can dispatch the serializable spec to its queue:
+
+```ruby
+dispatcher = lambda do |spec, _in_process_runner|
+  RunMistriChildJob.perform_later(spec)
+end
+```
+
+The spec is a deeply owned, immutable, bounded JSON Hash containing a spec
+version, child and parent Session IDs, worker type, model-written instructions,
+task, exact tool names, and model ID. The identical canonical spec is stored in
+the child Session before dispatch. `run_dispatched` compares the complete queue
+copy with that durable grant before checking a finished result, constructing a
+Runtime, or routing a report. A changed grant, task, model, name, or parent ID
+raises `Mistri::DispatchGrantError` and leaves the legitimate child untouched.
+The unchanged queue item cannot heal: configure the job system to discard it
+and alert an operator. The class is reserved for Mistri's stored-grant binding;
+a runtime factory must not use it as an application signal. Versioned specs
+reject unknown fields.
+
+Unversioned 0.5 queue specs remain executable because their child entries did
+not store a comparable grant. That compatibility cannot retroactively prove
+their queue copy or report routing. Drain or inspect those jobs before relying
+on the versioned boundary.
+
+The spec contains no providers, tools, workspaces, credentials, or callbacks.
+If queue execution needs a tenant or account ID, put that trusted identifier
+beside the spec in the host's job envelope and reauthorize it in the worker; do
+not add fields to the spec or put live application objects inside it.
+
+The job invokes the same host registry locally, then enters the shared child
+lifecycle:
+
+```ruby
+Mistri::SubAgent.run_dispatched(
+  spec,
+  store: mistri_store,
+  emit: event_sink,
+  runtime_factory: HostAgents.method(:runtime_for),
+)
+```
+
+The factory itself is host code and is never serialized. Existing jobs may
+continue to pass directly reconstructed `provider:`, `system:`, and `tools:` to
+`run_dispatched`; Mistri applies the same exact model and capability checks.
+Prefer the factory form because it runs after the stored terminal check and,
+with a configured lock adapter, successful child-lease acquisition. It avoids
+constructing credentials, connections, or workspaces for a finished delivery
+and for an ordinary concurrent delivery while that lease remains live.
+
+An exception raised while the queue's factory is constructing dependencies is
+retryable by default: `run_dispatched` releases the lease, leaves no terminal,
+and re-raises so the queue can retry. Runtime contract mismatches are terminal.
+On a queue's final attempt, pass `retry_factory_errors: false` to record and
+report the construction failure before the exception re-raises. The flag does
+not decide whether the job system retries or discards the exception. The
+in-process runner already uses terminal behavior because Thread and Inline have
+no durable retry owner.
+
+The factory boundary applies to dispatched children. Inline spawns and fixed
+specialists continue to use the provider and Tool objects supplied by the host;
+parallel inline calls may therefore share whatever those objects close over.
+That is deliberate host policy, not an isolation guarantee.
+
+## Reports and control
+
+A background spawn returns a truthful receipt based on the child's stored
+status. When the child reaches a terminal state, it writes its result to its own
+session and delivers one typed report into the parent inbox.
+
+An inactive queued or interrupted cancellation owns that durable inbox delivery
+while it holds the child lease, so the parent receives the stopped report even
+if the queue never starts or retries the job. The callback-only
+`:subagent_report` event is not emitted for that host-initiated path because
+`Child#stop` has no event sink; the durable parent inbox is authoritative.
+If that cross-session inbox append raises, the stopped terminal remains
+durable. Repeating `Child#stop` or `stop_agent` retries the report under the
+child lease and sequentially deduplicates an earlier successful delivery.
+
+The parent folds that report at its next turn boundary as a labeled message.
+The `:subagent_report` event closes the worker's live UI lane. Duplicate report
+delivery is dropped by child Session ID when redeliveries are sequential. The
+current check is not an atomic uniqueness constraint, so a queue must serialize
+delivery or deduplicate concurrent attempts in host storage.
+
+Host code and the management tools use the same `Mistri::Child` facade:
+
+```ruby
+child = parent_session.children.first
+
+child.status                   # :queued, :running, :interrupted, :done, :stopped, :failed
+child.report                   # terminal report when done
+child.error                    # terminal error when failed
+child.transcript(tail: 20)     # presentation-oriented recent entries
+child.say("Check pricing too") # queues a steer
+child.stop                     # durable if inactive, cooperative if running
+```
+
+`read_agent` with `wait: true` waits for a terminal, including across an
+interrupted worker's later queue retry or cancellation. Abort and timeout still
+end the wait in band.
+
+Stopping requires a lock adapter. A queued or interrupted child that has no
+current lease owner is terminalized and reported immediately under a lease. If
+a runner already owns the lease, the cross-process flag requests its
+cooperative abort instead.
+
+Child events forwarded into the parent stream carry an `origin` such as
+`Corgi#ab12cd34`. `session.transcript(include_children: true)` uses the same
+labels when rebuilding lanes from the store.
+
+Like `Session#transcript`, a child transcript only strips inline image bytes. It
+is not an authorization or redaction boundary; authorize and redact it before
+exposing it.
+
+## Provider concurrency
+
+Several spawn calls in one parent turn are tool calls and can begin
+concurrently. Actual model requests depend on provider instances:
+
+- Inline calls sharing one built-in provider object serialize through that
+  provider's transport.
+- A background Runtime factory decides whether children receive independent or
+  deliberately shared providers. Distinct instances are required when their
+  model calls must overlap.
+- An inline typed Definition with its own model builds a provider for that
+  worker. A background typed worker records the model identity and relies on
+  the Runtime factory to construct it.
+
+This distinction avoids promising network fan-out when only tool scheduling is
+parallel.
+
+## Approval
+
+A child cannot suspend and wait for a human. It must return a report to its
+parent.
+
+Mistri rejects statically approval-gated tools when a SubAgent or Spawner is
+built. A predicate gate cannot always be detected statically; if one triggers at
+runtime, Mistri denies and settles the call, fails the child, and leaves no open
+approval.
+
+Gate the delegation itself instead:
+
+```ruby
+reviewer = Mistri::SubAgent.new(
+  name: "external_reviewer",
+  description: "Sends material to the external review service.",
+  provider: reviewer_provider,
+  tools: [external_review],
+  needs_approval: true,
+)
+```
+
+## Lock adapters
+
+Cross-process liveness and stop requests require a shared lock adapter. Configure
+one at boot:
+
+```ruby
+# One process, including the thread dispatcher:
+Mistri.locks = Mistri::Locks::Memory.new
+```
+
+Rails cache support is optional and must be required explicitly:
+
+```ruby
+require "mistri/locks/rails_cache"
+
+Mistri.locks = Mistri::Locks::RailsCache.new(cache: Rails.cache)
+```
+
+The cache must implement atomic `unless_exist` writes and be shared by every
+worker process. A local memory cache is not a cross-process adapter.
+
+A custom adapter implements:
+
+```text
+acquire(key, ttl:) -> boolean
+renew(key, ttl:)
+release(key)
+held?(key) -> boolean
+set_flag(key, ttl:)
+flag?(key) -> boolean
+clear_flag(key)
+```
+
+The current lease is a best-effort duplicate-suppression and liveness signal,
+not an ownership token or exactly-once fence. It stores no holder identity. A
+process stalled beyond the TTL can resume after another process acquires the
+same key, and unconditional renewal or release cannot distinguish those
+generations.
+
+Queue jobs must therefore keep child work idempotent or reconcilable. A held
+lease suppresses an ordinary redelivery while the first worker is healthy; an
+expired lease allows a retry of a child that appears interrupted. A finished
+child's terminal entry makes a later matching delivery a no-op. Calling
+`Child#stop` while the child is interrupted competes for the lease and, when it
+wins, replaces that possible retry with a durable stopped terminal.
+
+Without an adapter:
+
+- inline and dispatched work can still run;
+- a non-terminal started child reads `:running`, because no shared liveness
+  signal exists;
+- `Child#stop` cannot send a cross-process request;
+- queue redeliveries receive no lease-based suppression.
+
+## Capacity is advisory
+
+`max_children` counts the parent's currently live children before spawning. It
+is a useful model-facing limit, but the read-then-create sequence is not an
+atomic distributed admission control. Concurrent parent runners are already
+outside the Session execution contract, and independent callers can race the
+count.
+
+If worker capacity is a hard operational limit, enforce it atomically in the
+host queue, database, or scheduler. Keep `max_children` as the in-band guidance
+the model sees.
+
+## Related guides
+
+- [Sessions and control](sessions.md)
+- [Tool contracts](tool-contracts.md)
+- [Reliability](reliability.md)
+- [Upgrading](../UPGRADING.md)