phronomy 0.25.0 → 0.27.0

data/docs/decisions/045-worker-input-restriction-ownership.md

@@ -0,0 +1,100 @@
+# ADR-045: Worker Input Restriction Ownership
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-21
+**Refines**: [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md)
+and [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md)
+
+## Problem
+
+Tool authorization snapshots exclude framework-managed live objects from value
+data and application behavior handles. `ToolInvocation` identified those objects
+by enumerating 18 Agent, Workflow and execution types. The Agent-side boundary
+therefore depended on concrete Workflow types solely to reject them as input.
+
+Moving that list into a shared helper would retain the wrong ownership. Treating
+all frozen objects or all callables as safe would weaken the existing boundary;
+rejecting all opaque application objects would break ACS-11.
+
+## Decision
+
+1. The execution boundary owns the internal, methodless
+   `Concurrency::WorkerInputRestricted` marker in `engine/concurrency/`.
+   It declares that instances of an owning type are excluded from the existing
+   authorization worker value/behavior boundary. It contains no feature list,
+   registration mechanism, class-name matching, constant lookup or callbacks.
+2. Each previously restricted type directly includes the marker in its own
+   definition. WorkflowContext includes it as a module so implementations and
+   their subclasses retain the restriction. Other classes pass it through
+   normal Ruby inheritance. Nested types are marked only when they were in
+   the original rejection set; marking FSMSession does not mark every nested
+   class, so its EventSink opts in separately.
+3. `ToolInvocation` checks only `is_a?(Concurrency::WorkerInputRestricted)`.
+   Recursive Hash-key/value and Array traversal, String copying/freezing,
+   exception type/messages and behavior-handle checks remain unchanged.
+   Frozen marked instances remain restricted.
+4. Each owner explicitly requires the small marker file. The marker can load
+   alone without Agent, Workflow, Runtime or application bootstrap. Normal,
+   preloaded, repeated and eager application loading retain marker identity
+   and do not create settings or start Runtime. The marker adds no methods to
+   public APIs; the existing API snapshot is not regenerated.
+
+## Existing restriction inventory
+
+| Owner | Types that include the marker |
+|---|---|
+| Agent execution/state | `Agent::Base`, `AgentRoot`, `AgentExecution`, `AgentInvocation`, `ToolInvocation`, `JournalProjection`, `ExecutionCoordinator` (all under Agent) |
+| Agent capability | `Agent::Context::Capability::Base` |
+| Workflow | `Workflow`, `WorkflowRunner`, `WorkflowContext` |
+| Execution | `Runtime`, `TaskResult`, `EventLoop`, `FSMSession`, `FSMSession::EventSink` |
+| Concurrency | `Concurrency::CancellationToken`, `Concurrency::OffloadPool` |
+
+These are the same 18 root types as the previous predicate. Regression tests
+retain this inventory to prevent an accidentally unmarked existing type from
+becoming admissible. Future framework types subject to this boundary must opt
+in at their owning definition and add an input-boundary test.
+
+## Scope and compatibility
+
+This marker is internal classification, not a public safety certification or
+serialization SPI. It does not reject all Runnable implementations, all
+Phronomy objects, class/module objects, or every worker command. Other operation
+snapshots and OffloadPool APIs are unchanged.
+
+Application-owned opaque values and behavior handles remain permitted by
+identity. Their instance variables, callback receivers and closure captures
+are not traversed. Applications remain responsible for worker safety under
+the existing ACS-11 contract. The marker is not a security sandbox.
+
+The ancestry of the 18 types intentionally gains one methodless module.
+Public methods, constructors, value copying, events, ownership, cancellation,
+transaction boundaries, persistence formats and exception behavior are
+unchanged. No F1 uncertain-commit reconciliation, F4 recovery, external-effect
+rollback or exactly-once guarantee is added.
+
+## Dependency interpretation
+
+The Agent-to-Workflow execution dependency disappears. Workflow types and
+Agent types instead refer downward to an execution-boundary contract.
+Existing Engine types refer within the execution foundation. Explicit
+marker loading adds require edges; it does not move feature references into
+the marker. A methodless include is still a real source dependency.
+
+This completes the specific A-E reverse-dependency proposals. It does not
+eliminate all directory/file cycles, Storage's domain-specific repository
+names, or FSMSession's Workflow terminal persistence responsibilities.
+
+## Verification
+
+Verify the 18-type inventory for direct instances and subclasses, frozen and
+unfrozen, root values, Hash keys/values, nested Arrays and all three behavior
+handle names. Exercise actual authorization command capture for Workflow,
+WorkflowRunner and WorkflowContext via context/policy/facts/requirement paths,
+and reject a marked value returned from a facts callable. Preserve opaque
+application data, callables and unmarked Runnable/Outcome values.
+
+Also verify a new marked type without changing the evaluator, standalone and
+normal/preloaded/eager loading, no Workflow type references in Agent source,
+and the marker's absence of feature knowledge. Run the existing snapshot
+boundary suite, full and integration tests, style, unchanged API snapshot,
+RBS, annotations and examples against the candidate core.

data/docs/decisions/046-agent-responsibility-layout-and-shared-records.md

@@ -0,0 +1,110 @@
+# ADR-046: Agent Responsibility Layout and Shared Records
+
+**Status**: Amended on the architecture refactoring branch
+**SharedState amendment**: [053-shared-state-coordination-ownership](053-shared-state-coordination-ownership.md) moves the deferred multi-Agent coordination responsibility to MultiAgent. The original placement below is retained as history.
+**Continuation amendment**: [047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md) removes the remaining Recovery-to-private-control calls and shares session registration. The original extraction scope below is retained as history.
+**Date**: 2026-09-21
+**Refines**: [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md)
+and [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md)
+
+## Problem
+
+Agent's direct directory contained 41 files with unrelated responsibilities.
+Recovery also obtained the ordinary execution coordinator solely to invoke its
+private record encoder and content writer. RecoverySupport mixed recovery
+vocabulary, durable reads, and construction of live invocations.
+
+Moving files alone does not resolve that coupling. Moving transaction decisions
+into a shared encoder would instead give it too many responsibilities.
+
+## Decision
+
+Apply and verify the changes in two stages: source placement first, then shared
+record generation and restoration responsibilities.
+
+### Source placement
+
+Collapse the following directories with Zeitwerk, preserving existing Agent
+constant names and the application entry point `require "phronomy"`:
+
+| Directory | Responsibility |
+| --- | --- |
+| `agent/lifecycle/` | Agent identity, ownership and fallback construction contract |
+| `agent/execution/` | Invocation, phase transitions, admission and execution coordination |
+| `agent/tool_execution/` | Tool invocation, authorization, approval and interception |
+| `agent/context_assembly/` | Candidate selection, budgeting and Provider context materialization |
+| `agent/journal/` | Canonical execution records and their projection |
+| `agent/handoff/` | Agent-owned Handoff contracts, state and execution coordination |
+| `agent/recovery/` | Durable recovery classification, resolution and live restoration |
+
+The three files below `recovery_coordinator/` move with their owning class into
+`recovery/recovery_coordinator/`. That directory retains its real nested Ruby
+namespace; it is not independently collapsed. Existing API, composition,
+context contracts, capabilities, concerns and persistence directories retain
+their responsibilities. `base.rb`, `async_event_api.rb` and `shared_state.rb`
+remain directly under Agent. SharedState's multi-Agent orchestration is a
+separate future ownership decision, not evidence of generic shared data.
+
+Update relative requires and source-reading regression guards. Do not provide
+old-path forwarding shims: arbitrary implementation-file requires are not a
+public partial-loading API. Existing constant identities, method signatures,
+ancestry, lifecycle extension installation and stored class names are preserved.
+
+### Shared record generation
+
+`Agent::RuntimeRecordEncoder` under `execution/` receives execution facts, the
+Agent identity, root generation, context eligibility and an existing transaction.
+It writes content and returns JournalRecord and LLMCallRecord values. Ordinary
+execution and recovery resolution both call it directly. It has no Agent live
+object, coordinator, Runtime lookup, transaction opener, journal append, execution
+save, commit/reconciliation decision or task settlement responsibility.
+The encoder belongs to execution because it interprets Tool interception and
+Provider settlement; the journal value/projection directory must not depend on
+Tool execution solely to classify those facts.
+
+Keep call sequence numbering, interception-as-success, abandoned call recording,
+Tool message duplicate detection, context eligibility, content formats and
+canonical-value failure messages. The caller still owns the transaction and
+F1 outcome reconciliation. Encoding is not a pure function because it writes
+content using that caller-owned transaction.
+
+### Saved context and live restoration
+
+`Agent::SavedContextReader` under `context_assembly/` reads persisted manifests,
+materializes projections, and obtains saved Provider output/usage. Execution
+preparation reconciliation, Handoff and Recovery consume this common reader.
+Reading occurs in the same worker/caller preparation phase as before, outside
+EventLoop state application.
+
+`Agent::InvocationRestorer` under `recovery/` constructs live Chat, AgentInvocation
+and ToolInvocation state from already-materialized facts. Suspended and resolved
+continuations share the same invocation/chat construction sequence. Tool status,
+approval facts, listener, invocation mode, coordination configuration, cancellation
+and message order are preserved. It does not perform persistence reads or decide
+which continuation to execute. RecoverySupport retains recovery metadata and
+subject vocabulary rather than forwarding to the extracted helpers.
+
+## Compatibility and limits
+
+No public API or extension SPI is changed, and the existing API snapshot is not
+regenerated. These three helpers are internal (`@api private`). Removed methods
+on the internal RecoverySupport module and ExecutionCoordinator are not public
+application contracts. No persistence schema, durability level, exactly-once
+claim, cancellation rule, external effect replay rule or ownership rule changes.
+
+ExecutionCoordinator still owns several operations and remains large. Recovery
+still calls its private continuation/terminal entry points; this decision only
+removes the record-generation and content-writing coupling. Moving directories
+reveals previously internal cycles; counts across different grouping schemes are
+not directly comparable. No claim of eliminating all Agent cycles is made.
+
+## Verification
+
+Verify the placement-only checkpoint before extracting helpers. Run ordinary
+and recovery tests, F1 response-loss and I/O-boundary checks, restart/output-filter
+coverage, full and integration suites, API byte comparison, RBS, annotations,
+style and examples. Compare the complete encoded records and captured content
+against the baseline under fixed timestamps and IDs, including success, structured
+output, failure, interception, abandoned calls, duplicate Tool messages and
+context eligibility. Verify gem packaging includes every moved/new source and
+loads without the old implementation paths.

data/docs/decisions/047-recovered-execution-continuation-contract.md

@@ -0,0 +1,116 @@
+# ADR-047: Recovered Execution Continuation Contract
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-21
+**Refines**: [046-agent-responsibility-layout-and-shared-records](046-agent-responsibility-layout-and-shared-records.md),
+[024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md)
+and [028-preparing-recovery-replay-contract](028-preparing-recovery-replay-contract.md).
+
+## Problem
+
+Recovery chose a continuation from saved facts but also registered its Agent FSM
+and reached five private ExecutionCoordinator entry points through `send`.
+Initial execution, approval resume, framework Tool recovery and resolved-result
+recovery independently wired parent session completion. Recovery therefore had
+to understand the execution owner's terminal and session implementation.
+
+## Decision
+
+### Recovery describes the continuation; execution validates and starts it
+
+Use the execution owner's existing `deliver_on_event_loop` boundary with two
+internal command types:
+
+- `RecoverPreparationCommand` identifies the installed execution and expected
+  revision, with separate execution and load completion observers.
+- `ContinueRecoveredCommand` supplies that identity/revision, a semantic
+  continuation, the restored invocation, its materialized projection, the
+  execution observer and a failure when applicable.
+
+Recovery still classifies saved facts, requests factual resolution, materializes
+saved inputs off EventLoop and restores live invocations on EventLoop. It no
+longer registers an Agent FSM, supplies FSM state/event names, owns its terminal
+callback, or names private execution-control methods.
+
+The execution owner validates EventLoop affinity, coordinator/Agent ownership,
+current revision, nonterminal execution and absence of an installed FSM. It
+also checks the continuation's saved phase and invocation identity before any
+replacement, admission change or session dispatch. A mismatched continuation
+must not replace or release another lifecycle's state. Stale initial preparation
+fails both observers without releasing that newer lifecycle.
+
+The execution owner interprets the six continuation intents:
+
+| Intent | Execution-owned action |
+| --- | --- |
+| Approval rejection | Resume the saved rejected approval and its Tool sessions |
+| Framework Tool batch | Resume the authorized framework Tool sessions |
+| Saved framework calls | Enter ordinary Provider-result handling |
+| Saved Provider output | Enter ordinary Provider-result/output-filter handling |
+| Saved Tool results | Enter ordinary Tool-result/follow-up handling |
+| Resolved failure | Enter the ordinary terminal persistence barrier |
+
+Delivery is synchronous within the existing EventLoop turn. This is an internal
+handover, not an additional queued turn or an Offload operation. Commands are
+process-local controls, not persisted records or an application extension SPI.
+The existing private terminal/preparation methods remain private.
+
+### One owner wires Agent and Tool sessions
+
+`Agent::ExecutionSessionRunner` owns parent session registration, resumed session
+construction, resumed child registration and parent completion wiring. Ordinary
+initial execution, approval resume and recovery use it. It reports completion
+through an execution-owner-supplied callback; the owner delivers an internal
+`SessionFinishedCommand` to itself, including the concrete FSM incarnation and
+invocation. This preserves Handoff coordinator dispatch without making the
+runner depend on the coordinator's concrete class or command definitions.
+
+The coordinator retains admission, completion observers, stale-callback checks,
+physical-quiescence waiting, terminal snapshot creation and persistence. The
+runner performs no persistence I/O, saved-fact interpretation, retry decision or
+caller-facing result settlement. Parent registration precedes child registration
+as before. Its live Runtime/callback handles carry the existing worker-input
+restriction marker.
+
+## Compatibility and failure model
+
+Public API snapshots, RBS contracts, stored formats, recovery subjects, approval
+decisions and external replay eligibility remain unchanged. A restored rejected
+approval now registers its internal execution observer at the same pre-session
+boundary used by the other continuation intents; terminal settlement still
+occurs only through the coordinator's existing barrier.
+
+Under [018-durability-guarantees-and-failure-model](018-durability-guarantees-and-failure-model.md):
+
+| Subject / property | Provider and condition | Failure / boundary | Result |
+| --- | --- | --- | --- |
+| Current live execution: reject stale or foreign continuation before state replacement | Execution-owner identity/revision/FSM validation on EventLoop | F2/F3; no X0 dispatch by rejected command | YES |
+| Caller completion follows the authoritative terminal outcome | Existing coordinator terminal barrier and quiescence checks; runner reports FSM completion only | F0/F1/F3; existing external effects remain outside transaction | YES under the existing Persistence contract |
+| Confirmed recovery state: resume the same logical execution | Recovery classification/materialization plus the execution owner; replay-safe preparation or resolved external facts are required | F1/F4; X0 may have occurred before recovery | CONDITIONAL on the existing operation-specific recovery contract |
+| Arbitrary external-effect exactly-once execution | No new external idempotency or transaction protocol | F1/F4 across X0 | NO new guarantee |
+
+The command boundary is process-local validation, not cross-process exclusion.
+No broader exactly-once or automatic replay claim follows from this change.
+
+## Verification and remaining work
+
+Exercise rejected commands on a real EventLoop/ExecutionRegistry: wrong owner,
+coordinator, revision, installed FSM, terminal state, invocation identity and
+continuation phase. Verify both preparation observers and a late session
+completion. Existing recovery, approval, F1/F4, output-filter, cancellation,
+Handoff and full-suite tests cover valid dispatch and terminal behavior.
+
+ExecutionCoordinator still owns preparation, causal barriers, admission and
+terminal operations. This decision removes Recovery's private control coupling
+and duplicated session wiring; it does not complete decomposition of that class.
+Tool snapshot restoration's direct field coupling, SharedState ownership,
+Storage domain responsibilities and Workflow terminal persistence remain
+separate work.
+
+## Tool restoration amendment (2026-09-22)
+
+[052-tool-invocation-restoration-ownership](052-tool-invocation-restoration-ownership.md)
+completes the direct Tool field coupling item above. ToolInvocation owns saved
+state application; Recovery retains decoding and identity matching. The original
+scope and historical remaining-work statement above are preserved. SharedState,
+Storage domain responsibilities and Workflow terminal persistence remain open.

data/docs/decisions/048-dispatch-preparation-worker-ownership.md

@@ -0,0 +1,120 @@
+# ADR-048: Dispatch Preparation Worker Ownership
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-22
+**Refines**: [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md),
+[042-feature-owned-execution-state](042-feature-owned-execution-state.md)
+and [047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md).
+
+## Problem
+
+ExecutionCoordinator mixed EventLoop ownership and application result delivery
+with the Persistence operations required before Provider/Tool dispatch. Moving
+whole methods alone would leave the Provider operation mixing control steps,
+metadata representation, transactions, application policy and materialization.
+Its worker also used input/result types nested under the execution owner, which
+would create a reverse dependency after extraction.
+
+## Decision
+
+### The execution owner captures, submits and applies
+
+ExecutionCoordinator keeps current Agent/invocation/FSM validation, operation
+capture, Offload submission, Ready delivery, semantic revision/phase checks,
+snapshot acknowledgment and physical Provider/Tool dispatch. These responsibilities
+remain on their existing threads and in their existing order. Ordinary and
+recovered execution keep the same owner and continuation contract.
+
+`Agent::DispatchPreparation` owns four internal worker operations:
+
+- `prepare_provider`: stage the next call, encode runtime records, prepare the
+  Context, commit prerequisites and materialize the confirmed input.
+- `prepare_tools`: encode runtime records and save pending Tool recovery facts.
+- `reconcile_provider`: read back the execution, classify the exact saved state
+  and restore input only for the confirmed intended result.
+- `reconcile_tools`: read back and classify the exact saved state.
+
+The worker returns values and never schedules work, advances the live Registry,
+acknowledges invocation snapshots, starts Provider/Tool calls, or settles Tasks.
+It does not refer back to ExecutionCoordinator or its private methods. The
+Coordinator creates the worker with the existing Agent service context and its
+Persistence instance. Agent hooks, ContextAssembler and coordination preparation
+retain their existing service contracts; this is not removal of all Agent
+references. The worker is marked `WorkerInputRestricted` because it retains
+framework service handles. Per-operation inputs/results remain local variables.
+
+### Preserve the operation-specific persistence boundaries
+
+Provider preparation has two transactions with application hooks/ContextPolicy
+between them. The first can encode content-addressed records but does not advance
+Execution. The second rechecks the local Agent watermark, finalizes the Manifest
+and saves the Execution. Cancellation is checked after Policy and before that
+second transaction. Tool preparation retains its single transaction.
+
+Only an exception in the guarded save transaction, after an intended result was
+captured and outside the existing known-failure classes, becomes an unknown
+outcome. Encoding failures and application Policy failures do not become an
+uncertain execution save. Post-commit materialization failure returns the saved
+Execution together with an error, so the owner still applies/acknowledges the
+known committed snapshot before reporting setup failure.
+
+Reconciliation compares both revision and complete execution contents. It returns
+`committed` only for the intended state, `not_committed` only for the exact original
+state, and `conflict` otherwise. Read failures propagate. It never retries the
+write or authorizes dispatch by itself. Terminal and coordination-wait
+reconciliation remain separate and retain their different acceptance criteria.
+
+The watermark rule remains owned by Persistence's `assert_agent_watermark!`.
+The worker and the remaining initial-preparation code only map captured Root
+fields to that contract; neither implements a second version of the rule.
+
+### Names describe the purpose; bodies describe its immediate steps
+
+The Provider entry reads as stage, encode, prepare Context, commit, materialize.
+Private helpers own metadata keys, record fields and value construction. The
+Coordinator's dispatch entry reads as validate, capture, submit. Transaction
+and rescue scopes stay explicit in the operations that own them. We do not use
+one-line delegation chains or a generic execution framework to reduce line counts.
+
+### Types belong to the operation boundary
+
+DispatchPreparation owns Provider/Tool commands, reconciliation commands and
+their results. ExecutionCoordinator retains its existing eight nested constant
+paths as aliases to these types; Ready messages and live delivery remain in the
+Coordinator. Its private uncertainty exception constant is also an alias.
+
+The aliases preserve construction, members and shared type identity, but the
+canonical Ruby class names now belong to DispatchPreparation. These are internal,
+process-local types, not persisted records or public extension contracts. This
+change makes no promise to preserve their former reflected names. Product API
+snapshots, saved formats, public exception contracts and recovery eligibility
+remain unchanged.
+
+## Failure model and verification
+
+Using [018-durability-guarantees-and-failure-model](018-durability-guarantees-and-failure-model.md):
+
+| Subject / property | Provider and condition | Failure / boundary | Result |
+| --- | --- | --- | --- |
+| Current execution: apply only a matching preparation result | Existing EventLoop owner, revision and FSM checks | F2/F3; no new X0 dispatch from stale results | YES, unchanged |
+| Provider/Tool dispatch: confirmed durable prerequisites precede physical dispatch | Operation-specific commit/readback plus owner apply; conforming Persistence is required | F0/F1; this barrier precedes the next X0 call | CONDITIONAL on confirming the intended durable state and current live ownership |
+| Application Policy: no preparation transaction held while it executes | Explicit separation of encoding, Policy and save | F0/F3; application-defined side effects remain its responsibility | YES for the framework-owned transaction boundary |
+| Confirmed records: restart readability and continuation | Existing Persistence and Recovery contracts | F4; replay or resolution depends on the external operation | CONDITIONAL, no broader resumption guarantee |
+| Arbitrary external-effect exactly-once execution | No new external protocol or distributed exclusion | F1/F4 across X0 | NO new guarantee |
+
+Existing causal-durability tests now invoke the owning worker instead of private
+Coordinator persistence methods. Architecture guards inspect the complete worker,
+including helpers, while keeping checks on EventLoop apply. Behavioral probes
+exercise Policy outside transactions, post-Policy watermark/cancellation checks,
+encoding-response loss, post-commit materialization failure, reconciliation read
+failure, materialization failure after confirmation, and same-revision content
+conflicts. Existing valid Agent/Tool execution, Recovery and Handoff suites cover
+the production wiring. Public API, loading and gem-content checks remain required.
+
+## Remaining work
+
+Initial preparation, approval snapshot isolation, and normal/Handoff outcome
+persistence are separate stages. The approval Hash/Mutex is not moved into this
+worker. The existing Coordinator and Handoff terminal machinery are unchanged.
+This stage improves responsibility and abstraction boundaries; it does not claim
+to remove every Agent dependency cycle or finish Coordinator decomposition.

data/docs/decisions/049-initial-preparation-worker-ownership.md

@@ -0,0 +1,111 @@
+# ADR-049: Initial Preparation Worker Ownership
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-22
+**Refines**: [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md),
+[042-feature-owned-execution-state](042-feature-owned-execution-state.md),
+[047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md)
+and [048-dispatch-preparation-worker-ownership](048-dispatch-preparation-worker-ownership.md).
+
+## Problem
+
+ExecutionCoordinator still owned initial durable admission, application filtering,
+Context preparation, failure persistence and replay of saved preparation inputs.
+Its ordinary start and preparing-recovery paths shared persistence work with
+EventLoop admission, live state and completion delivery. Simply relocating that
+work would leave long methods mixing representation details and control steps.
+
+## Decision
+
+### Preparation owns persistence; the execution owner owns live control
+
+`Agent::InitialPreparation` owns `prepare(Command)` and `recover(RecoveryCommand)`.
+Its Command and Result retain the fields of the former Coordinator-owned types.
+Coordinator keeps their old constant paths as aliases. Their canonical Ruby names
+change; these are internal process-local types, not saved or public API records.
+
+Coordinator retains replay-eligibility capture, Runtime admission, live-owner
+checks, Offload submission, completion messages, stale-result validation, live
+Agent/Registry updates, session registration and Task/listener settlement.
+Preparing recovery captures the execution, root and journal records in an explicit
+RecoveryCommand. Result tasks and load completion handles stay on EventLoop.
+The worker does not call back into Coordinator or initiate Provider/Tool dispatch.
+
+The worker is marked `WorkerInputRestricted` and holds existing Agent services and
+Persistence. It keeps operation state in local variables. This does not remove all
+Agent service references or make arbitrary application input/config values deeply
+immutable. Approval snapshot isolation remains a later stage.
+
+### Preserve admission outcomes and operation-specific failure boundaries
+
+Input extraction precedes durable admission. An extraction failure returns
+`not_established`. During admission, durable busy returns `recovery_required`;
+the existing known-conflict/validation exception set returns `not_established`;
+other exceptions return `outcome_unknown`. The execution owner preserves the
+corresponding Runtime admission release or fail-closed behavior.
+
+Durable admission still creates Execution and advances AgentRoot together, after
+validating Team/Subagent/Handoff reservation ownership in the same transaction.
+Splitting those ownership checks into named helpers changes no acceptance rule.
+
+For admitted preparation the body reads as filter, stage input, prepare Context,
+commit, and materialize. Hooks and ContextPolicy run outside the commit
+transaction. Cancellation is checked before filtering, before assembly and after
+Policy. The commit revalidates the Agent watermark after Policy returns.
+
+The failure base advances from preparing Execution to active Execution only after
+the active commit has returned successfully. A lost active-commit response leaves
+the old revision as the failure base. If the active commit did occur, the existing
+failure transaction conflicts and rolls back its Journal append; the worker does
+not return an unconfirmed terminal result or add a new retry/readback policy.
+
+A post-commit materialization error is terminalized from the known active
+revision. Failure persistence atomically appends audit records, saves terminal
+Execution and advances AgentRoot. A failure in that transaction, including lost
+response, escapes to the execution owner; it is not converted into a confirmed
+terminal Result. This initial-preparation contract intentionally differs from
+DispatchPreparation's operation-specific uncertain-outcome reconciliation.
+
+`Agent::ExecutionFailure` owns the existing pure error-to-status and status-to-audit
+kind mappings. Both initial failure persistence and the remaining terminal worker
+use it, avoiding duplicated classification rules. It owns no transaction, live
+state or result delivery. Normal/Handoff terminal transaction behavior is unchanged.
+
+### Recovery consumes saved inputs without admitting another execution
+
+The worker first checks the replayable marker, reads current input and rebuilds
+config from the saved invocation mode, coordination services and optional canonical
+Hash durable_context. The recovered config and durable context remain frozen.
+Read failures or invalid durable context escape before admitted preparation;
+they do not trigger a failure commit or a speculative retry.
+
+Ordinary start and recovery use the same admitted-preparation operation and Result.
+Recovery keeps the same execution identity and does not call durable admission.
+Runtime-only approval/listener state is not reconstructed. Existing Coordinator
+validation and recovery delivery remain authoritative.
+
+## Guarantees and verification
+
+Using [018-durability-guarantees-and-failure-model](018-durability-guarantees-and-failure-model.md):
+
+| Subject / property | Provider | Failure / boundary | Result |
+| --- | --- | --- | --- |
+| Same-process Agent starts: fail closed for uncertain/busy admission | Existing Runtime registry plus worker outcome classification | F0/F1/F4; before framework Provider/Tool X0 | YES, unchanged |
+| Initial preparation: stale root/revision rejection | Persistence watermark/CAS and failure transaction rollback | F1/F2/F3; before framework Provider/Tool X0 | CONDITIONAL on conforming Persistence |
+| Failure transition: Journal, Execution and Root commit together | Existing Persistence transaction | F0/F1; atomicity does not imply response certainty | CONDITIONAL on conforming backend; no new certainty guarantee |
+| Preparing recovery: continue the same execution | Existing replay eligibility, saved inputs and owner validation | F4; application preparation may run again | CONDITIONAL on the existing replay-safe preparation contract |
+| Arbitrary application or external effects: exactly once | No new exclusion/idempotency protocol | F1/F4 across application-defined X0 | NO new guarantee |
+
+Behavioral tests cover transaction ordering, pre-admission extraction failure,
+known admission failure, lost admission/active/failure commit responses,
+post-commit materialization failure, cancellation and watermark changes after
+Policy, blocked input and replay input restoration/validation/read failure.
+Architecture guards include all new worker helpers and exclude control/delivery
+dependencies. Existing normal execution, Team/Subagent/Handoff and recovery suites
+cover the owner wiring and unchanged coordination checks.
+
+## Remaining work
+
+Approval snapshot isolation and approval persistence, followed by normal/Handoff
+outcome worker extraction, remain separate stages. This stage does not finish
+Coordinator decomposition or remove all Agent dependency cycles.

data/docs/decisions/050-approval-resume-snapshot-and-commit-ownership.md

@@ -0,0 +1,98 @@
+# ADR-050: Approval Resume Snapshot and Commit Ownership
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-22
+**Refines**: [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md),
+[047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md)
+and [049-initial-preparation-worker-ownership](049-initial-preparation-worker-ownership.md).
+
+## Problem
+
+Approval resume captured a Tool batch into a Coordinator Hash keyed by execution
+ID before validating the current approval request. A worker later removed that
+entry under a Mutex. Two queued requests could overwrite or consume each other's
+snapshot even though the worker commands belonged to distinct operations.
+The outer frozen Array also shared mutable String values with the invocation.
+The command did not completely describe the recovery facts it would persist.
+
+## Decision
+
+### Validate and capture on EventLoop
+
+ExecutionCoordinator validates the live Agent owner, suspended Execution and
+approval request ID before capturing the invocation's canonical Tool snapshot.
+It copies and recursively freezes that value tree with `Values::Immutable.copy`
+and stores it directly in the operation's `tool_batch_snapshot` field. An absent
+invocation gives nil; a present invocation with no children gives a frozen empty
+Array. No shared approval snapshot Hash or Mutex remains in either owner.
+
+This applies to canonical recovery facts only. Arbitrary application objects in
+config, listener or callback state do not acquire a new deep-copy contract.
+The general RecoverySupport snapshot builder keeps its existing contract.
+
+Snapshot isolation was implemented and behaviorally verified before extracting
+the persistence operation, so the concurrency fix can be reviewed independently
+of the ownership change.
+
+### Persist the captured decision in an operation worker
+
+`Agent::ApprovalResumeCommit#commit` reads as validate the approval target, stage
+the captured recovery facts, then persist the decision. Its helpers own record
+fields, metadata representation and repository calls. It holds only the Agent ID
+and Persistence; all operation state is local. It is `WorkerInputRestricted`.
+
+The existing transaction still writes approval decision Content, adds the
+approval_decided record to Execution working records, saves active/resuming
+Execution with its expected revision and advances AgentRoot with its expected
+revision. Staging metadata preserves the original execution revision so the
+durable transition advances it exactly once. A nil snapshot preserves existing
+metadata; an empty snapshot replaces the previous Tool batch.
+
+Coordinator retains Runtime admission, Offload submission, completion messages,
+late-result validation, live-state replacement, completion waiters, tracing and
+SessionRunner resumption. Rejection before Offload submission restores suspended
+admission. A commit error keeps admission recovery_required. A late result for
+an advanced or cancelled Execution fails only the approval observer and does not
+start a session. Existing duplicate-approval acceptance and CAS rules are unchanged.
+
+The worker does not read back uncertain results, retry a transaction, contact
+Provider/Tool adapters or invoke application callbacks. A lost commit response
+escapes as an error; the owner follows the existing recovery-required path.
+Persistence atomicity must not be presented as certainty about that response.
+
+### Internal type compatibility
+
+Command and Result are owned by ApprovalResumeCommit. Coordinator retains
+`ResumeCommitCommand` and `ResumeCommitResult` as aliases to those exact classes.
+Their canonical Ruby names change to `ApprovalResumeCommit::Command` and
+`ApprovalResumeCommit::Result`. Command appends the required internal field
+`tool_batch_snapshot`; Result retains its existing members. Internal positional
+construction/reflection is consequently not unchanged. These types are neither
+public API nor durable records. Saved schema and public approval API stay unchanged.
+
+## Guarantees and verification
+
+Using [ADR-018](018-durability-guarantees-and-failure-model.md):
+
+| Subject / property | Provider | Failure / boundary | Result |
+| --- | --- | --- | --- |
+| Queued approval operation retains its captured facts | EventLoop validation and independent immutable Command values | F0/F2/F3; before Provider/Tool X0 | YES for canonical Tool snapshot values |
+| Approval transition is atomic (G5), stale writes are rejected (G8) | Existing Persistence transaction and Execution/Root CAS | F2; no framework X0 in this worker | CONDITIONAL on conforming backend |
+| Unknown approval commit is not treated as confirmed resumption | Worker error propagation and owner recovery_required admission | F1; no new worker X0 | YES; no new commit certainty or readback guarantee |
+| Restored approval waiting continues the same execution (G4) | Existing recovery reconstruction and validated resume path | F4; later Tool work may cross X0 | CONDITIONAL on existing recovery/integration contracts |
+| Cross-process exclusion (G7), external duplicate prevention (G9), exactly once (G10) | No new protocol supplied by this change | F1/F2/F4 across X0 | NO new guarantee |
+
+Tests cover mutation after capture, reversed worker order, stale and invalid
+requests, rejected submission, empty/absent batches, successive approvals,
+approval/denial persistence, Execution and Root conflicts, transaction response
+loss and stale results after cancellation or a newer approval. Existing recovery
+integration tests restore approval waiting and resume both approval and denial.
+The unit fault injections are not a hard-process-loss or real external-service test.
+Architecture guards inspect the worker helpers for live-control dependencies.
+
+## Remaining work
+
+Normal terminal persistence and Handoff terminal persistence remain coupled in
+ExecutionCoordinator and its subclass. They are the next extraction stage and
+must be designed together. This change does not complete Coordinator decomposition
+or eliminate Agent dependency cycles.