phronomy 0.26.0 → 0.27.0

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.

data/docs/decisions/051-execution-outcome-worker-ownership.md

@@ -0,0 +1,151 @@
+# ADR-051: Execution Outcome 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),
+[030-agent-handoff-domain-and-durable-responsibility](030-agent-handoff-domain-and-durable-responsibility.md),
+[047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md)
+and [050-approval-resume-snapshot-and-commit-ownership](050-approval-resume-snapshot-and-commit-ownership.md).
+
+## Problem
+
+ExecutionCoordinator owned both EventLoop execution control and Offload result
+persistence. HandoffExecutionCoordinator overrode outcome selection and depended
+on its parent's transaction helpers. Extracting only one side would preserve
+that hidden dependency or accidentally change Handoff precedence. Moving the
+long bodies unchanged would also leave persistence policy mixed with individual
+record fields.
+
+## Decision
+
+### Select and persist outcomes in operation workers
+
+`Agent::ExecutionOutcomeCommitter#commit_outcome` selects completion, failure,
+approval suspension or owned-child waiting from a captured command. It handles
+persistence exceptions through the existing operation-specific readback rules.
+`Agent::HandoffOutcomeCommitter` specializes that selection and atomic Source
+transfer, sharing ordinary completion, failure and suspension persistence.
+Handoff selection retains its separate callback/error/suspension/transfer order;
+it does not acquire the ordinary worker's child-coordination wait branch.
+
+HandoffExecutionCoordinator retains its class identity and inheritance, but now
+only selects the Handoff worker. This selection is internal, not a public SPI.
+Coordinator captures input, submits the worker, validates the returned revision
+and session, applies live state and delivers results. Worker code never calls
+back into Coordinator. Command state and intermediate results remain local to
+one operation; workers hold only Agent service context and Persistence.
+
+Agent context is still required by the existing coordination hook, error
+translation, saved Manifest reader and transcript materializer. This is not a
+claim that all Agent references or dependency cycles have been removed.
+`WorkerInputRestricted` marks both worker types; it is not a recursive validator
+of arbitrary application-owned values.
+
+### Keep transactions visible in the purpose-level methods
+
+`commit_completed` encodes completion records, appends Journal, saves Execution
+and coordination, advances Root and materializes the caller-facing transcript
+inside one transaction, then constructs the result. Record fields and repository
+arguments belong to its helpers. Transcript materialization stays inside the
+transaction so failure rolls back the transition.
+
+`commit_failed_outcome` persists audit-only records and the translated failure.
+The Context revision stays unchanged because none of those records is a Context
+candidate. Completion and Handoff advance Context only if the appended records
+contain a candidate. Suspension retains its records in Execution working state,
+advances Root to suspended and does not append Journal or advance Context.
+
+`commit_handed_off` validates Source routing and cancellation, persists projected
+Context, transfers routing to a deterministic Target execution ID, and saves
+Source Journal, Execution and Root in one transaction. Target definition lookup
+uses the transaction view; the existing saved Manifest reader keeps its service
+context. Target completion/failure stabilizes routing inside its own existing
+terminal transaction. No Provider/Tool dispatch or application delivery moves
+into these workers.
+
+### Preserve the distinct readback contracts
+
+| Operation | Existing confirmation rule after an exception | Consequence |
+| --- | --- | --- |
+| Ordinary/Handoff terminal | Same Agent, terminal Execution, expected revision + 1; then load saved Root, Journal and result | Reuse the persisted outcome; do not write a second terminal transition |
+| Child-coordination wait | Complete saved Execution payload equals the intended waiting record | Return that nonterminal wait; active status alone does not establish a match |
+| Approval suspension | It is nonterminal, so terminal readback does not confirm it | Propagate uncertain completion to the owner |
+
+Terminal confirmation is deliberately not changed to DispatchPreparation's
+full intended-payload comparison. Missing, active, mismatched or unreadable
+results do not authorize another write. Readback errors retain their existing
+propagation behavior. Recovered success retains the existing smaller result
+shape; recovered failures use `RecoverySupport.error_from_failure`, including
+its generic Phronomy::Error representation. This extraction does not normalize
+those results or introduce a stronger commit-certainty protocol.
+
+### Preserve EventLoop result authority and delivery
+
+The owner still waits for physical work quiescence before terminal persistence.
+A stale result changes no live state, admission or Task. Completed/failed/Handoff
+results release ownership and deliver their existing events before settling
+waiters. Suspension retains admission and leaves the original Task pending;
+exact observers receive the existing approval-required failure. Child waiting
+releases ownership and fails waiters with recovery required.
+
+A worker error for ordinary execution retains recovery_required admission and
+pending waiters. The existing coordination-metadata error path releases the
+owner and fails waiters. Those branches are not merged into unconditional cleanup.
+Live Handoff request/Manifest delivery handles remain outside the worker command.
+
+### Internal types
+
+ExecutionOutcomeCommitter owns `Command`, `Outcome`, `TerminalView` and
+`HandoffTerminalView`. Coordinator retains its previous constant paths as aliases
+to the same classes. All four member lists stay unchanged; their canonical Ruby
+names change. TerminalDelivery and TerminalCommitReady remain owner-local.
+These types are internal and are not serialized by class name. Public API, saved
+schemas, Agent/Handoff Coordinator identity and caller selection remain unchanged.
+
+## Guarantees and verification
+
+Using [ADR-018](018-durability-guarantees-and-failure-model.md):
+
+| Subject / property | Provider | Failure / boundary | Result |
+| --- | --- | --- | --- |
+| Terminal or Handoff transition atomicity (G5), stale write rejection (G8) | Existing transaction and repository CAS | F0/F2; no new framework X0 | CONDITIONAL on conforming Persistence backend |
+| No second terminal write after uncertain response | Operation-specific worker readback and owner recovery path | F1; no new worker X0 | YES; no stronger outcome-certainty guarantee |
+| Current execution alone may apply worker results | Existing EventLoop owner/revision/session guards | F2/F3 and delayed completion | YES within the same Runtime ownership contract |
+| Logical continuation from saved Source/Target state (G4) | Existing Handoff recovery and exact Target identity | F4; later execution can cross X0 | CONDITIONAL on existing recovery contracts |
+| Cross-process exclusion (G7), external duplicate prevention (G9), exactly once (G10) | No new protocol added | F1/F2/F4 across X0 | NO new guarantee |
+
+Behavior tests exercise completion/rejection, failure categories, suspension,
+transaction rollback, Root CAS, response loss and readback mismatches/failures,
+child waiting, atomic Source transfer, routing conflict/cancellation and Target
+completion/failure. Existing suites cover physical quiescence, stale results,
+callback policy, approval recovery and durable Handoff recovery. Unit fault
+injections do not represent real process loss or live external service failures.
+Architecture guards now inspect the actual workers and disallow repository
+reloads in Coordinator without the old terminal-helper exceptions.
+
+## Owner-control review (2026-09-22)
+
+The fifth stage keeps one execution owner and makes its remaining result paths
+read as validation, state application and continuation/delivery. Preparation
+recovery separates failed-outcome settlement from session restart. Approval
+resume separates committed-state installation and tracing from FSM entry.
+Terminal results retain visible outcome selection while private methods handle
+the distinct waiting, suspension, completion, Handoff and failure deliveries.
+Only the identical execution/admission release is shared across terminal paths.
+Initial preparation snapshot construction is named explicitly; start/resume
+admission flags, submission flags and their rescue decisions remain together.
+
+No transaction, authority condition, failure policy, public type or class owner
+changes. Direct Ready delivery tests run on the real EventLoop/ExecutionRegistry
+and check stale-result isolation, state-before-notification, notification-before-
+settlement, fallback waiters, suspension, uncertainty and recovery/resume failure
+boundaries. These tests also pass against the preceding implementation, documenting
+preserved behavior rather than a new contract. F0/F1/F3 are injected locally;
+no new X0 operation or stronger F4 guarantee is claimed.
+
+## Remaining work
+
+The execution-owner decomposition and final readability review are implemented.
+Tool restoration, SharedState, Storage domain responsibilities and Workflow
+terminal ownership remain separate work items. Further owner splitting needs a
+concrete responsibility or failure-boundary reason; file length alone is not one.

data/docs/decisions/052-tool-invocation-restoration-ownership.md

@@ -0,0 +1,92 @@
+# ADR-052: Tool Invocation Restoration Ownership
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-22
+**Refines**: [046-agent-responsibility-layout-and-shared-records](046-agent-responsibility-layout-and-shared-records.md)
+and [047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md).
+
+## Problem
+
+InvocationRestorer decoded saved Tool batches and directly assigned
+ToolInvocation's status, result, authorization decision and approval evidence.
+Moving restoration into its own module in ADR-046 left that knowledge of another
+object's representation intact. ADR-047 explicitly retained it as separate work.
+A change to ToolInvocation's state representation therefore required Recovery to
+track its instance variables as well as the saved format.
+
+## Decision
+
+Keep the existing classes and introduce the internal
+`ToolInvocation#restore_state!(status:, result: nil, approval_item: nil)` operation.
+It is Ruby-public for the Recovery caller and classified `@api private`; it is
+not an Application extension SPI. Its input is materialized semantic state,
+not an Execution record or a persistence repository.
+
+InvocationRestorer retains saved snapshot key normalization, Tool Call and Tool
+lookup, construction of ordinary or missing-Tool invocations, and matching the
+approval item by invocation ID. It converts the saved status to a Symbol and
+passes the saved result and matched approval item to the newly constructed
+ToolInvocation. No ToolInvocation instance variable is assigned by Recovery.
+The separate AgentInvocation batch-ID assignment is outside this change.
+
+ToolInvocation owns the supported-state dispatch and approval evidence copy:
+
+| Saved state | Existing behavior retained |
+| --- | --- |
+| awaiting_approval | Validate arguments unless already terminal, restore require_approval and the waiting state |
+| authorized | Validate arguments unless already terminal, restore allow and the authorized state |
+| completed | Restore the saved result, including nil or false, and completed state |
+| rejected | Restore rejection and its decision |
+| failed | Restore the existing generic Tool preflight failure |
+| cancelled | Restore cancellation |
+| Other state | Raise ExecutionRehydrationRequiredError before applying approval evidence |
+
+The entry method reads as saved-state application followed by saved approval
+evidence application. Private methods contain each operation's implementation.
+Evidence copying preserves the existing immutable facts and reason semantics,
+including an explicit nil facts value. A missing approval item leaves constructor
+defaults intact. Saved display evidence is not a new policy evaluation input.
+
+The caller supplies a newly constructed invocation before session installation.
+This is not a general rollback or arbitrary live-state replacement interface.
+The existing EventLoop ownership and continuation validation remain unchanged.
+The old internal `InvocationRestorer.restore_tool_snapshot!` entry is removed;
+no forwarding compatibility wrapper is introduced for this private helper.
+
+## Compatibility and limits
+
+No public API, RBS contract, saved schema, approval decision, external replay
+eligibility, missing-Tool rule, or callback sequence changes. The existing
+validation behavior is retained, including the handling of current Tool
+validation errors and missing definitions; this refactor does not add a new
+schema-migration or saved-state validation policy. It does not restore arbitrary
+Application Tool instance variables.
+
+Restoration itself does not run authorization policy, execute a Tool, acquire a
+Runtime, perform persistence I/O or notify listeners. This does not suppress the
+existing recovery installation notification of an outstanding approval request.
+Load-time notification and later approval/rejection dispatch keep their existing
+owners. External outcome-unknown resolution and framework operation recovery
+remain with RecoveryCoordinator and the execution owner.
+
+Under [018-durability-guarantees-and-failure-model](018-durability-guarantees-and-failure-model.md),
+this change concerns operation-local reconstruction from already materialized
+facts. Unsupported input is an F0 rejection without X0 dispatch by this operation.
+Same logical execution resumption after F4 remains CONDITIONAL on the existing
+confirmed saved state and operation-specific recovery contract. F1 outcome
+resolution is unchanged. No new external-effect exactly-once guarantee follows.
+
+## Verification
+
+Replace tests that mock another object's instance-variable writes with real
+ToolInvocation behavior tests. Run identical assertions against the old owner
+boundary and the new operation. Cover all six states, unsupported states, saved
+results, missing definitions, immutable approval evidence, and dispatch gating
+before and after approval. Existing restart tests exercise approval and rejection
+through actual recovery installation and session continuation. Run the ordinary
+and integration suites, API snapshot, annotations, RBS, examples and SQLite
+persistence checks. No test count implies a stronger F4 or X0 guarantee.
+
+SharedState coordination ownership, Storage domain responsibilities and Workflow
+terminal persistence remain separate work. This decision completes only the Tool
+restoration ownership item carried forward by ADR-047.

data/docs/decisions/053-shared-state-coordination-ownership.md

@@ -0,0 +1,71 @@
+# ADR-053: SharedState Coordination Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch, 2026-09-22.
+This resolves the deferred SharedState ownership decision in
+[046-agent-responsibility-layout-and-shared-records](046-agent-responsibility-layout-and-shared-records.md).
+
+## Context
+
+SharedState creates an invocation-local findings store, equips several Agent
+definitions with read/write Tools, invokes members in declaration order, repeats
+cycles until a configured limit, and aggregates the findings. It is not an
+individual Agent's state container or execution coordinator. These responsibilities
+belong to MultiAgent, alongside the other multi-Agent coordination patterns.
+
+Its implementation also mixes cycle orchestration with individual member calls,
+and researcher instrumentation with the bodies of injected Tool definitions.
+Moving a file alone would leave those abstraction levels mixed.
+
+## Decision
+
+1. Move the implementation to `multi_agent/shared_state.rb`, exposing the
+   Experimental `Phronomy::MultiAgent::SharedState` and its nested `KnowledgeStore`.
+   Remove `Phronomy::Agent::SharedState` without an alias on this branch, following
+   the coordination ownership precedent in
+   [034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md).
+   Update examples, RBS and the [migration guide](../migrations/shared-state-multi-agent.md)
+   together. Ordinary consumers continue to `require "phronomy"`.
+2. Express invocation as termination validation, store creation, member
+   coordination and result aggregation. Express each cycle as ordered member
+   invocation followed by stopping decisions. Build the two injected Tool
+   definitions in named private methods. Keep these responsibilities in the same
+   class; no new execution manager or general coordination abstraction is needed.
+3. Preserve the DSL, method parameters, prompt text, Tool descriptions/schema,
+   cooperative execution mode, original Tool aliases, result shape and exceptions.
+   Members remain sequential; findings from an earlier member are visible to the
+   next member in the same cycle. `terminate_when` still takes precedence over
+   timeout after each complete cycle, and timeout does not interrupt a member.
+4. Preserve the generated Agent definition ID prefix
+   `Phronomy::Agent::SharedState::Instrumented/` and instrumentation version 1.
+   This string is semantic identity, not a Ruby constant lookup or old-name alias.
+   Namespace placement alone must not change the wrapped definition revision.
+
+## Consequences and limits
+
+This is a breaking rename of an Experimental public API, including the nested
+store class name. The Stable/Beta API snapshot does not enumerate SharedState;
+an unchanged snapshot does not establish complete public API compatibility.
+
+The store is still newly created for each invocation and is not durable shared
+Agent state. The coordinator adds no resume, cancellation, asynchronous execution,
+transaction, F4 or X0 guarantee. `invoke` still accepts `config:` without
+forwarding it to the member calls. Revising that behavior is a separate change.
+
+No persistence schema or saved-record migration is introduced. Individual Agent
+persistence keeps its existing rules; this move does not make the in-memory
+coordination lifetime resumable. The method extraction slightly increases source
+length and does not eliminate unrelated dependency cycles.
+
+Storage domain responsibilities and Workflow terminal ownership remain separate
+work items. This decision does not reopen the completed ExecutionCoordinator split.
+
+## Verification obligations
+
+Verify new namespace loading, absence of the old alias, repeated eager-load
+identity and no Runtime startup during loading. Exercise existing coordination,
+stopping, aggregation, Tool alias and definition identity tests. Check the full
+and integration suites, offline examples, RBS, annotations, style and built gem
+contents, including removal of the old implementation path. Record executed
+results and untested environments separately in the delivery review.

data/docs/decisions/054-workflow-terminal-save-single-owner.md

@@ -0,0 +1,76 @@
+# ADR-054: One Workflow Terminal Save Implementation
+
+## Status and scope
+
+Accepted on the architecture refactoring branch, 2026-09-22.
+Amends only the Workflow recovery prepend requirement in
+[038-responsibility-based-source-layout](038-responsibility-based-source-layout.md).
+The durable barrier in
+[026-workflow-runtime-admission-and-durable-terminal-barrier](026-workflow-runtime-admission-and-durable-terminal-barrier.md)
+and the receiver ownership in
+[042-feature-owned-execution-state](042-feature-owned-execution-state.md)
+remain unchanged.
+
+## Problem
+
+WorkflowRunner defines terminal save submission, but WorkflowRecovery defines
+the same method and is prepended during application loading. It never calls
+`super`. The active implementation reconciles uncertain save outcomes against
+durable pre/post state; the shadowed implementation does not. Reading or editing
+the Runner alone can therefore target code that is not actually used.
+
+## Decision
+
+Move the currently active submission and F1 reconciliation into WorkflowRunner.
+Delete the shadowed implementation, the private WorkflowRecovery module and its
+explicit installation. Do not introduce a new class or compatibility alias for
+the removed private override.
+
+Express terminal save submission as admission marking, immutable command
+construction, Offload submission and session-local result delivery. Named private
+methods own saving/reconciliation and delivery separately. The existing Command
+and Result Data classes retain their identity and members.
+
+The worker saves once. Portable ConflictError, NotFoundError, SerializationError
+and UnsupportedBackendError remain known failures without readback. Other save
+errors use the existing authoritative snapshot comparison: exact post-state is
+success, pre-state preserves the original failure, and conflict or failed
+readback remains outcome-unknown. No automatic save retry is introduced.
+
+The existing session sink receives `workflow_terminal_persistence_result`.
+Offload completion errors still become outcome-unknown, and rejected sink
+delivery retains its existing warning. Runner still marks admission and captures
+the snapshot on EventLoop; workers only use that captured command for persistence.
+
+## Compatibility and guarantees
+
+This is an internal ownership/readability change. Public Workflow/Persistence
+APIs, Backend SPI, snapshots, revisions, error messages and the session event
+protocol are unchanged. Removing the prepend can make WorkflowRunner load lazily
+under ordinary `require "phronomy"`; first access and eager loading must retain
+the same recovery behavior without starting Runtime.
+
+F1 save certainty remains CONDITIONAL on authoritative readback matching the
+existing expected pre-state or intended post-state rules. It is not established
+merely by receiving an exception. F0 portable failures follow the existing known
+failure path. Runtime release, success notification and Task settlement still
+wait for EventLoop-owned session acceptance; uncertain outcomes keep the existing
+recovery-required behavior. F4 readability depends on the backend retaining
+confirmed data. X0 external effects are outside this save, and this change adds
+no execution replay, distributed ownership or exactly-once guarantee.
+
+FSMSession still owns interpretation of the Workflow terminal persistence
+event. Moving that policy out of Engine is a separate next step; this decision
+does not claim that the entire Workflow terminal ownership issue is resolved.
+Storage's fixed repository slots and Agent watermark also remain separate work.
+
+## Verification
+
+Characterize the effective submission path before and after the change, including
+immutable snapshots, known errors, F1 post/pre/conflicting/unreadable outcomes,
+single-save behavior and failed Offload completion delivery. Preserve existing
+real-runtime tests for delayed save, stream barriers, admission release and
+uncertain outcomes. Verify ordinary/eager loading without the override, full and
+integration suites, API/RBS/annotations/style, offline examples and built gem
+contents. Keep results from tests actually run distinct from unavailable live
+Provider or database-server evidence.