Temporary Agent Execution Refactor Spec

Current authority: AgentExecution is the canonical in-memory Entity instance and owner of the Agent execution process. Instantiating the Entity is sufficient to make it the active in-memory authority for that run. Terminal is optional transport. Live process state is modeled through AgentExecution process state rather than a separate runtime doctrine.

This is the working spec for the current AgentExecution clean sweep.

It is temporary on purpose. It exists to prevent implementation drift while the refactor is in flight. When the code converges, fold the useful parts back into the permanent architecture register and delete this file.

Current Cleanup Rule

  • Converge Repository and AgentExecution first.
  • Keep AgentExecution narrow and canonical while deprecated Mission, Task, or workflow-era compatibility surfaces converge to it.
  • Keep this spec focused on owner-independent AgentExecution runtime convergence. Mission-owned compatibility cleanup is evidence and follow-up debt, not part of this spec’s implementation scope.
  • AgentExecutionSchema.ts stays canonical-only.
  • Any remaining live process-state or event vocabulary belongs behind AgentExecution and private daemon runtime helpers as implementation detail.
  • If a consumer still requires compatibility-only fields such as task labels, working directory projections, or duplicate lifecycle aliases, treat that as consumer debt to remove rather than a reason to expand the Entity schema.

Owner-Independence Rule

AgentExecution must be completely owner-independent. A Mission-scoped or task-scoped execution is only one instance of the same Entity contract under an explicit owner reference; it is not a Mission child model, Mission runtime row, workflow projection, or task lifecycle surrogate.

This spec may use Mission code as diagnostic evidence when it reveals owner leakage, but it must not solve Mission-specific behavior inline. Mission cleanup belongs in a separate Mission adherence slice. That slice should make Mission act only as an owning Entity and workflow consumer: it may request AgentExecution creation, store or reference AgentExecution ids, react to accepted owner effects, and project owner-facing status, but it must not define AgentExecution runtime shape, duplicate lifecycle aliases, parse runtime overlays as canonical AgentExecution data, or route terminal behavior through Mission-only fields.

The current checked-in Mission implementation is therefore a consumer-convergence blocker, not authority for AgentExecution design. Examples of Mission interference include Mission holding AgentExecutionRuntimeType[], importing runtime event helper types, constructing new AgentExecution(...) from Mission-held compatibility overlays, and persisting terminal/log paths through workflow-era AgentExecution runtime records. Those call sites should be removed or redirected after AgentExecution exposes the owner-independent launch, terminal attachment, message, journal, and observation seams.

OGM Agent Relation Rule

AgentExecution follows the canonical OGM storage and hydration pattern.

  • AgentExecutionStorageSchema persists the selected Agent by agentId only. That field is a direct reference to the Agent Entity, not embedded Agent data, not an adapter id alias, and not adapter data.
  • AgentExecutionSchema may expose a hydrated agent field validated by AgentSchema when callers need the related Agent as part of the complete AgentExecution boundary shape. The hydrated agent field reflects current Agent catalogue data.
  • The hydrated agent field is serializable Agent Entity data. It is not an Agent class instance and does not contain an AgentAdapter instance.
  • The Entity factory and model catalogue must materialize same-name storage-computed or fetched Entity fields through the target field’s <RelatedEntity>Schema. AgentExecution must not need constructor-specific glue to turn AgentStorageSchema rows into AgentSchema data.
  • AgentExecution does not require a materialized agent: Agent property unless AgentExecution behavior actually needs Agent Entity behavior. Hydrated data.agent is enough for catalogue display and current Agent metadata.
  • AgentExecution runtime behavior needs the selected AgentAdapter. AgentExecution may expose a non-serialized agentAdapter runtime capability property instantiated from the selected Agent by Entity behavior or daemon runtime composition. That property is not OGM-hydrated Entity data.
  • AgentExecution may exist in a read-only hydrated state without agentAdapter. Runtime methods that launch, deliver messages, parse provider output, provision structured transport, or otherwise require provider translation must require an attached agentAdapter and fail loudly when it is missing.
  • Launch-time immutable Agent details belong in separate AgentExecution-owned audit fields only when they are needed for reproducibility or durable execution explanation; they must not overload the hydrated agent relation.

This rule is a direct application of ADR-0001.08 and the existing Terminal/TerminalRecordingEntry pattern. The mere modeling of a related Entity field on the hydrated schema is the generic instruction to return related Entity data shape, not storage shape. It prevents AgentExecution from duplicating Agent catalogue data, prevents AgentAdapter from becoming a runtime registry, and keeps Entity relationships in schema metadata rather than hand-written daemon lookup glue.

Vocabulary Decision

Mission uses these active concepts:

  • Agent: the Mission-visible capability that can perform work.
  • AgentAdapter: the narrow provider-specific translation object owned by one Agent.
  • AgentExecution: one concrete run of one Agent under an explicit execution scope.
  • Terminal: the daemon-addressable Entity facade for one PTY-backed terminal resource.
  • TerminalRegistry: the Terminal Entity boundary registry and in-memory authority for process, screen, input, resize, exit state, and update publication.

Execution coordination belongs behind AgentExecution. Coordinating daemon code is named by its narrow mechanical job, such as process launch, terminal attachment, or observation intake.

An execution scope may be system, repository, mission, task, or artifact. Mission and task are common workflow scopes, not mandatory AgentExecution roots.

Mission does not use AgentRuntime as canonical vocabulary. The current AgentRuntime class is duplicate lifecycle vocabulary and must be deleted.

Mission does not introduce ProviderAdapter. Provider-specific translation is AgentAdapter.

Ownership Map 

entities/Agent
  Agent entity only

entities/AgentExecution
  AgentExecution entity
  AgentExecution schema and contract
  AgentExecutionProtocolTypes

entities/Terminal
  Terminal entity
  Terminal schema and contract
  TerminalRegistry

daemon/runtime/agent-execution
  narrow private launch/process helpers
  AgentExecutionLogWriter
  prompt-scoped signal instruction
  observation routing
  signal policy
  provider observation vocabulary

daemon/runtime/agent/adapters
  Copilot, Claude Code, Codex, Pi, OpenCode AgentAdapters

daemon/runtime/terminal
  TerminalScreen
  screen substrate helpers

workflow/engine
  emits execution requests
  delegates execution work to AgentExecution through the daemon execution boundary

Responsibilities

Agent

Agent belongs in packages/core/src/entities/Agent.

Agent owns:

  • agentId and display name
  • availability and capability metadata
  • configuration metadata used to select/use the Agent
  • Entity query/read surface
  • reference to exactly one AgentAdapter as runtime capability

Agent does not own:

  • PTY launch
  • TerminalRegistry
  • prompt-scoped signal instruction
  • signal policy
  • runtime output routing
  • AgentExecution lifecycle mutation
  • AgentExecution storage or hydration

AgentAdapter

AgentAdapter belongs in packages/core/src/daemon/runtime/agent/adapters.

AgentAdapter owns:

  • adapter-specific metadata validation
  • AgentLaunchConfig to command/args/env translation
  • provider-structured output parsing
  • provider-specific observation creation
  • stateless message and launch translation only

AgentAdapter does not own:

  • live execution state
  • runtime maps or process handles
  • lifecycle truth
  • TerminalRegistry or PTY process mechanics
  • prompt-scoped signal instruction
  • AgentExecution creation or mutation
  • Mission workflow state transitions
  • Open Mission behavior
  • signal promotion policy

AgentExecution Runtime Helpers

AgentExecution owns execution lifecycle. Runtime helpers behind AgentExecution may:

  • resolve the requested Agent through AgentRegistry.
  • ask the Agent’s AgentAdapter for launch translation.
  • prepare mandatory prompt-scoped signal instructions for task-scoped executions.
  • open or reconcile TerminalRegistry terminals for terminal-backed executions.
  • wire TerminalRegistry updates into AgentExecution terminal attachment state.
  • normalize adapter, protocol-marker, and terminal observations.
  • expose mechanical process launch, input, cancellation, and termination capabilities to AgentExecution.

Those helpers are private implementation capabilities behind AgentExecution. If a future live lookup table becomes necessary, it remains implementation detail and must not become a second public execution model. Lifecycle policy, message routing, terminal behavior, and execution state shape stay with AgentExecution. AgentAdapter stays stateless within this split and must not become a hidden execution runtime.

AgentExecution

AgentExecution belongs in packages/core/src/entities/AgentExecution.

AgentExecution owns:

  • execution identity
  • selected Agent reference through persisted agentId and optional hydrated Agent data
  • explicit execution scope
  • durable execution state
  • context and log references
  • progress and attention state
  • terminal handle reference
  • terminal-backed execution state transitions from terminal output and exit events
  • structured message surface
  • post-launch message delivery and observation intake coordination
  • protocol payloads, snapshots, references, prompts, commands, and events

AgentExecution does not own:

  • node-pty
  • TerminalRegistry lookup
  • process spawning or killing
  • prompt-scoped signal instruction
  • adapter output parsing
  • persisted AgentAdapter state or adapter schema data
  • signal policy application
  • workflow task ownership

Terminal And TerminalRegistry

Terminal Entity and TerminalRegistry belong in packages/core/src/entities/Terminal.

Terminal owns:

  • daemon command/query contract for terminal read and input
  • terminal snapshot shape exposed across Entity remote boundaries
  • generic terminal input and resize command validation
  • TerminalRegistry as the live in-memory registry for terminal IO and update publication

Terminal does not own:

  • AgentExecution lifecycle state
  • Agent adapter launch translation
  • Mission workflow state
  • provider output parsing

TerminalRegistry owns:

  • terminal registration
  • open, attach, read, resize, input, kill, and update publication
  • process lease
  • screen state
  • exit state
  • terminal snapshot/update events

Daemon runtime terminal modules under packages/core/src/daemon/runtime/terminal own only screen substrate behavior. TerminalRegistry owns live Terminal process leases, PTY IO, snapshots, and update publication. Agent execution modules may bind to TerminalRegistry terminals through AgentExecution terminal attachment behavior while terminal truth stays with Terminal.

Terminal may carry owner metadata for an AgentExecution, Mission, task, repository, or system operation. Owner metadata does not make Terminal a Mission Entity.

Active Refactor Decisions

  1. AgentExecutionProtocolTypes belongs in entities/AgentExecution.
  2. AgentExecutionProtocolTypes must define explicit AgentExecutionScope for system, repository, mission, task, and artifact execution.
  3. Delete daemon/runtime/agent/AgentExecutionProtocolTypes.ts and move active imports to the canonical Entity boundary.
  4. Delete daemon/runtime/agent/AgentRuntime.ts.
  5. Replace daemon/runtime/agent/AgentAdapter.ts with the narrow adapter contract.
  6. Move lifecycle, TerminalRegistry, prompt-scoped signal instruction, signal policy, and live AgentExecution mutation out of entities/Agent/AgentAdapter.ts.
  7. Split or rename daemon/runtime/agent/adapters/AgentPtyAdapter.ts because the current name hides executor responsibilities.
  8. Move configured runtime construction out of entities/Agent/AgentRegistry.ts into daemon composition or another private runtime collaborator.
  9. Extract TerminalRegistry and process supervision out of entities/AgentExecution/AgentExecution.ts into the Terminal Entity boundary, with a private runtime collaborator coordinating lifecycle use.
  10. Promote Terminal to a first-class Entity so AgentExecution and Open Mission surfaces no longer import agent runtime glue to read or write terminal state.

Removed Swamp

The implementation had overlapping lifecycle concepts:

  • entities/Agent/AgentAdapter.ts: concrete PTY/signal lifecycle implementation in an Entity folder.
  • daemon/runtime/agent/AgentRuntime.ts: duplicate lifecycle abstraction.
  • daemon/runtime/agent/AgentAdapter.ts: duplicate lifecycle abstraction with adapter naming.
  • daemon/runtime/agent/adapters/AgentPtyAdapter.ts: runtime-side copy that still owns lifecycle behavior under an adapter name.

The target is one public lifecycle owner: AgentExecution, with TerminalRegistry inside the Terminal Entity boundary as terminal authority. Any daemon launcher or coordinator remains private runtime machinery and must not force parallel AgentExecution type families back into the Entity schema.

Implementation Sequence

  1. Keep AgentExecutionProtocolTypes in entities/AgentExecution and ensure all active imports use that path.
  2. Add explicit AgentExecutionScope before completing private runtime launch coordination so the implementation does not bake in Mission/task assumptions.
  3. Delete AgentRuntime and update tests/fakes to stop extending it.
  4. Rewrite runtime-side AgentAdapter as the narrow provider translation contract.
  5. Move PTY/signal lifecycle behavior behind a private daemon runtime collaborator instead of leaving it inside deprecated compatibility surfaces.
  6. Reduce provider adapter files to launch translation and output parsing.
  7. Make workflow and daemon control call the converged AgentExecution launch boundary.
  8. Remove the Entity-side concrete AgentAdapter implementation.
  9. Extract remaining TerminalRegistry/process supervision out of AgentExecution Entity into the Terminal Entity boundary.
  10. Promote Terminal to a first-class Entity and route AgentExecution terminal reads/input through that Entity.

Execute this sequence as a clean convergence: one canonical name, one active import path, and one lifecycle path at each step.

Current Status Matrix 2026-05-18

This section supersedes the 2026-05-15 audit below. The prior audit correctly identified a half-migrated tree, but several of its specific claims are now stale. In particular, the current tree does implement canonical scope and several schema types that the earlier audit still marked as missing.

Verified Evidence

  • The active tree under packages/core/src/daemon/runtime/agent-execution contains adapter code, testing helpers, event helpers, and the MCP stub. It does not contain a checked-in AgentExecutionRegistry implementation.
  • The active AgentExecution implementation still owns direct process spawning and in-memory process snapshots in packages/core/src/entities/AgentExecution/AgentExecution.ts.
  • Focused Vitest runs currently fail before test execution because the workspace cannot resolve @flying-pillow/zod-surreal during module loading.
  • pnpm run check in packages/core currently fails immediately on the TypeScript 6 baseUrl deprecation in packages/core/tsconfig.json, so the current branch does not provide a green package-level validation signal for this refactor slice.

Current Realization Summary

Area Status Current reality
Canonical AgentExecution schema and storage realized AgentExecutionSchema.ts defines canonical storage/data shape, journal linkage, message registry, transport state, MCP availability, explicit scope, launch config, prompts, commands, signal decisions, and terminal event payloads.
Canonical AgentExecution entity basics realized AgentExecution.ts implements identity creation, canonical data creation, launch-scope owner derivation, lifecycle transition mutation, read/resolve, process start/stop/wait, journal row append, and sendMessage(...) acknowledgement.
AgentExecution contract/event helpers partially realized AgentExecutionContract.ts exposes read and sendMessage, and exports createAgentExecutionDataChangedEvent(...) plus terminal-event helpers, but it does not yet expose the richer mutation/query surface implied by the accepted ADR family.
Terminal Entity boundary realized Terminal.ts and TerminalRegistry.ts are first-class. TerminalRegistry owns PTY lifecycle, screen state, input, resize, kill, lease cleanup, runtime supervision projection, and terminal recording listener publication.
Agent connection testing partially realized Agent.testConnection exists as a class-level Entity command, but the current tester is still a shallow availability probe rather than the bounded launch smoke test described by the ADR.
Runtime coordination doctrine partial, spec corrected There is no checked-in AgentExecutionRegistry in the active tree, and the spec should not require one. The instantiated AgentExecution is the current in-memory authority. The remaining parallel-runtime problem is distributed across AgentExecution, AgentAdapter, AgentRegistry, and Mission/workflow compatibility overlays, with AgentAdapter still carrying runtime behavior that should move into AgentExecution.
Mission owner independence failing consumer Mission still stores workflow-owned AgentExecution rows with task ids, terminal recording paths, and owner-facing projection fields; imports runtime event types; and reconstructs canonical AgentExecution instances from Mission-held projected data. This is Mission consumer debt and must not widen AgentExecution schema.
Journal semantics partial, first typed record set active Durable journal identity and ordered rows exist, and active rows now use explicit type families for journal.header, message.accepted, message.delivery, observation.recorded, decision.recorded, state.changed, activity.updated, owner-effect.recorded, and projection.recorded. sendMessage(...) writes accepted-message and turn-state records through this path, and replay can hydrate core semantic state with duplicate detection for messages and observations. The observation-to-decision-to-owner-effect pipeline is still not active.
Terminal attachment seam partial, focused path green AgentExecution now exposes canonical live terminal open, attach, read, input, and update-reflection behavior against TerminalRegistry without widening durable AgentExecution storage. Runtime adapters now open terminals through this seam, and active AgentExecution/workflow test fixtures now use canonical Terminal handle id rather than handle-level terminalName. Mission callers still need to finish converging onto owner-independent Entity references rather than Mission runtime rows.
Observation and signal routing partial, first intake seam active AgentExecution.recordObservation(...) now provides a transport-neutral normalized observation intake seam with per-instance duplicate handling, decision journaling, and small AgentExecution-owned state effects for input requests, blockers, and progress. Owner-effect routing and durable replay-backed duplicate lookup are still missing, and there is no separate checked-in routing collaborator yet.
MCP structured transport stub only OpenMissionMcpServer exists, but registerAccess(...), listTools(...), and callTool(...) are placeholders.
Semantic operations not implemented The accepted doctrine exists, but there is no active AgentExecutionSemanticOperations path in the checked-in tree.
Timeline and rich interaction projection partial, backend projection foundation active The active tree now has AgentExecution-owned timeline item schemas and journal-to-timeline projection coverage for the typed journal record set. The projection is derived from journal rows and is not yet exposed as persisted AgentExecution read-model state or rendered in Open Mission components.

Spec And ADR Coverage

Doctrine surface Status Notes
Temporary refactor spec stale in parts, still directionally valid The convergence direction is still correct, but prior claims about missing scope and missing contract helpers are no longer true.
ADR 0006.01 vocabulary and ownership partially realized Canonical names and boundaries exist, but runtime still carries a parallel snapshot model and AgentExecution still performs direct child_process.spawn(...).
ADR 0006.02 explicit journal partially realized Durable journal identity and ordering exist; rich semantic journal content does not.
ADR 0006.03 descriptor-defined messages partially realized Message descriptor and registry schemas exist; descriptor-driven runtime delivery and outcomes do not.
ADR 0006.04 prompt-scoped signals not materially implemented No active stdout marker instruction, parsing, de-duplication, or observation normalization path is present.
ADR 0006.05 structured interaction vocabulary partially realized in types Lifecycle, attention, activity, scope, transport, and signal-decision schemas exist; runtime observation and decision flow do not.
ADR 0006.06 MCP message transport stub only Server class exists, but transport behavior is not implemented.
ADR 0006.07 logs as daemon audit material partially realized Semantic journal and terminal recording lanes are structurally separate. Terminal recording persistence now has TerminalRegistry-backed writer coordination, but storage is currently supplied by Mission as one backend.
ADR 0006.08 interaction journal persistence partially realized Surreal persistence is real; replay-grade semantic journal discipline is not.
ADR 0006.09 semantic operations not implemented No active operation catalog or invocation path.
ADR 0006.10 structured-first with terminal capability partially realized Terminal capability exists; structured-first canonical interaction path is still incomplete.
ADR 0006.11 runtime-owned model selection mostly realized Static model catalog authority is gone from Agent Entity data; runtime /model descriptor behavior is not yet implemented.
ADR 0006.12 Agent connection tests implemented shallowly Correct Entity command seam exists, but the runtime probe is not yet the full bounded smoke path.
ADR 0006.13 narrowed typed journal ledger partially realized Journal kind typing exists, but the accepted record families are still much narrower than doctrine requires.

Converged Facts

  • AgentExecutionScope is implemented and canonical in the checked-in tree.
  • AgentExecution owns launch-scope owner derivation and canonical lifecycle mutation instead of leaving those details in the AgentAdapter or any separate runtime wrapper.
  • AgentExecutionContract does export daemon event helper constructors.
  • The narrow Surreal-backed OGM storage path for agent_execution and agent_execution_journal is real and should remain stable while runtime convergence continues.
  • Terminal is already the strongest runtime boundary in this tree; AgentExecution is not.
  • No checked-in AgentExecutionRegistry exists in the active tree, and this spec no longer treats that absence as divergence.
  • Instantiating AgentExecution is currently the active in-memory registration mechanism for a live execution instance.
  • Terminal recording persistence now has owner-independent writer coordination; Mission currently supplies one storage backend for that writer.

Remaining Gaps That Actually Control Delivery

  • Parallel runtime truth still exists, but it is distributed across AgentExecution, AgentAdapter, AgentRegistry, and Mission/workflow compatibility overlays rather than concentrated in a separate AgentExecutionRegistry.
  • AgentAdapter is not yet implemented as the intended stateless seam; it still carries live execution maps, start/reconcile methods, and lifecycle mutations that belong to AgentExecution.
  • Mission currently behaves like a privileged AgentExecution owner and compatibility projection rather than a normal owner-independent consumer.
  • The process-owner boundary is not yet clean: AgentExecution owns lifecycle semantically, but still directly spawns OS processes.
  • AgentExecution now has an active canonical terminal-attachment path, runtime adapter terminal launch goes through it, and workflow transport/event fixtures use Terminal handle id. Mission projection callers still need to converge further.
  • There is now a typed journal record set plus replay/projection foundation, and the first observation-to-decision-to-journal intake seam is active. The owner-effect portion of the pipeline is still missing.
  • MCP and semantic operations are present as accepted doctrine but not active runtime behavior.
  • Terminal recording persistence now has TerminalRegistry-backed coordination for attached AgentExecutions through an owner-independent writer. Mission currently supplies one storage backend, but recording coordination is no longer constructed around Mission-named methods.

What OGM Storage Can Safely Assume Now

  • Surreal table registration for agent_execution and agent_execution_journal is real and usable.
  • Repository-owned Entity persistence for the current AgentExecutionStorageSchema is real and should not be reshaped casually during runtime convergence.
  • The current in-memory process snapshot in AgentExecution.ts is still runtime convenience, not durable Entity truth.
  • Storage should stay canonical and narrow while runtime compatibility callers converge downward to the Entity contract.

Dependency-Ordered Implementation Checklist

Use this checklist as the execution gate for the remaining refactor. The sequence is deliberate: later steps depend on earlier ones being made explicit and true.

Current Sequencing Decision 2026-05-17

The narrowed Slice 4 terminal attachment seam is now implemented for the focused Entity/Terminal path. The next implementation work should return to the dependency order: reduce remaining distributed runtime truth, split Mission adherence cleanup, and clean the process-owner boundary.

This was not a jump around the dependency order. Slices 2 and 3 identified the active architectural pressure: distributed runtime truth still exists across multiple compatibility surfaces, Mission is still a compatibility consumer, and process mechanics are not cleanly separated. The smallest dependency-respecting move was to add the owner-independent terminal attachment seam first, because it gives adapter, workflow, and Mission callers a canonical place to converge toward.

For follow-up work after this terminal seam:

  • Do not widen AgentExecutionSchema.ts with timeline, MCP, semantic-operation, Mission-only, task-label, working-directory, or lifecycle-alias fields.
  • Do not attempt the full Mission adherence cleanup in this slice.
  • Do not attempt MCP, semantic operations, observation routing, or rich projection in this slice.
  • Do not make TerminalRegistry or AgentAdapter the lifecycle truth owner.
  • Keep direct AgentExecution.startProcess(...) only as a temporary local-process smoke path until the process-owner slice replaces or delegates it deliberately.
  • Continue using the canonical terminal attachment behavior and the minimal runtime coordination needed for terminal-backed AgentExecution launch, attach, input/read routing, terminal update reflection, and terminal recording persistence.

Completion of this narrowed Slice 4 leaves Slice 2 simpler because terminal state no longer needs to live in a separate compatibility execution model.

Slice 0: Keep This Spec Truthful

  • Replace the stale 2026-05-15 status audit with a current matrix.
  • Mark which doctrine surfaces are realized, partial, stubbed, or absent.
  • Update this matrix whenever a checked-in change materially moves an ADR-backed seam.

Slice 1: Lock The Canonical AgentExecution Contract

  • Keep entities/AgentExecution/AgentExecutionSchema.ts as the only canonical public schema family for AgentExecution state.
  • Explicitly decide which current fields are canonical Entity truth versus runtime-only compatibility projections.
  • Do not add timeline, MCP-tool, or semantic-operation projections to canonical schema until the runtime path that owns them exists in the active tree.
  • Preserve current OGM storage shape unless a separate accepted storage decision requires change.

Slice 2: Remove Parallel Runtime Truth

  • Keep this slice focused on reduction after the canonical terminal attachment seam exists; do not delete compatibility fields before active callers have a canonical replacement path.
  • Remove compatibility-only task labels, working-directory projections, and duplicate lifecycle aliases from compatibility runtime snapshots instead of promoting them canonically onto AgentExecution.
  • Stop treating compatibility runtime data as a second public execution model across Mission, workflow, and daemon publication paths.
  • Do not introduce AgentExecutionRegistry as a standing architectural seam unless a concrete checked-in use case requires it and doctrine is updated first.
  • Remove live execution maps, start/reconcile methods, and lifecycle mutations from AgentAdapter so it becomes a stateless translation seam.
  • Do not make Mission compatibility needs the replacement public model; Mission must converge down to owner-independent AgentExecution references and Entity contract calls.

Slice 2A: Split Mission Cleanup Out Of This Spec

  • Create a separate Mission adherence cleanup slice for removing Mission-owned AgentExecution runtime overlays, Mission-only terminal/log projections, and direct parsing of compatibility runtime data as canonical AgentExecution.
  • Keep this AgentExecution spec focused on owner-independent seams: process ownership, terminal attachment, message delivery, journal records, observations, and owner effects.
  • Use Mission failures as regression evidence only; do not add Mission-shaped fields or methods to AgentExecution to satisfy those callers.

Slice 3: Clean The Process-Owner Boundary

  • Decide whether AgentExecution keeps direct process spawning temporarily or delegates process mechanics immediately to a private runtime collaborator: keep direct startProcess(...) only as a temporary local-process smoke path while terminal-backed launch moves through TerminalRegistry in narrowed Slice 4.
  • Keep AgentExecution as lifecycle owner regardless of which mechanical launch helper is used.
  • Do not let TerminalRegistry or AgentAdapter become lifecycle truth owners.
  • Keep AgentAdapter methods pure over explicit inputs and outputs rather than adapter-held mutable runtime state.

Slice 4: Implement Terminal Attachment As The First Missing Runtime Seam

  • Add canonical AgentExecution.attachTerminal(...) behavior that records the attached terminal handle/reference as AgentExecution-owned current runtime state without making raw Terminal state canonical AgentExecution storage truth.
  • Add canonical AgentExecution methods or contract helpers for terminal read/input/update reflection only to the extent needed by terminal-backed execution control.
  • Route terminal open/attach/reconcile work through TerminalRegistry while keeping Terminal truth inside the Terminal Entity boundary. Open and attach are implemented on AgentExecution, and workflow event/transport handles now use canonical Terminal id; reconcile still needs caller convergence.
  • Move terminal handle fabrication out of AgentAdapter/compatibility paths and into the AgentExecution launch/attachment coordination path for runtime adapter launch.
  • Wire TerminalRegistry terminal updates to AgentExecution terminal attachment state and event helpers without introducing a second public terminal projection model. AgentExecution update reflection exists; daemon/runtime subscription convergence remains.
  • Replace the no-op AgentExecutionTerminalRecordingWriter with real coordination for terminal recording persistence.
  • Add focused tests for attach existing terminal, open terminal for an AgentExecution owner, read/send terminal input through the canonical path, terminal exit lifecycle reflection, and terminal recording persistence.
  • Converge active AgentExecution, workflow, and SystemStatus test fixtures from handle-level terminalName to canonical Terminal handle id, leaving terminalName only as launch/display metadata.
  • Leave Mission-owned runtime overlay cleanup to Slice 2A unless a small call-site redirect is required to prove the terminal attachment seam.

Slice 5: Build One Observation Entry Point Before Adding More Transports

  • Implement one transport-neutral observation intake path for structured incoming material.
  • Add duplicate/idempotency handling before state mutation and owner effects for the active in-memory AgentExecution instance.
  • Add one policy decision seam that produces journal rows before applying current-state changes.
  • Route accepted owner effects through the owning Entity path rather than through ad hoc runtime side effects.
  • Deepen duplicate/idempotency handling with persisted journal lookup or replay hydration before MCP retries become production-sensitive.

Slice 6: Expand The Journal Only As Runtime Behavior Demands It

  • Add journal record families for accepted messages, delivery attempts/outcomes, accepted observations, decisions, state changes, owner effects, and projection materialization.
  • Decide whether bounded transport evidence should be represented as its own journal family or only through observation/projection payload references before adding another journal family.
  • Keep every canonical AgentExecution state mutation paired with a corresponding journal entry in the same accepted write path.
  • Do not widen journal taxonomy speculatively beyond the runtime behavior that actually exists.

Slice 7: Implement MCP Message Transport After Observation Routing Exists

  • Replace the placeholder OpenMissionMcpServer behavior with real execution-scoped access registration, tool listing, and tool dispatch.
  • Make the first MCP slice message transport only.
  • Reuse canonical message schemas and owner routing; do not create MCP-local copies of payload law.

Slice 8: Add Semantic Operations As A Separate Follow-Up Slice

  • Implement an explicit AgentExecutionSemanticOperations boundary after MCP message transport works.
  • Keep operations read-only and scope-bound.
  • Record bounded daemon-observed journal entries for accepted semantic reads.

Slice 9: Deepen Agent Connection Testing Without Polluting AgentExecution

  • Keep Agent.testConnection as the canonical readiness probe command surface.
  • Upgrade AgentConnectionTester from shallow availability checking to a bounded launch smoke test when runtime convergence is stable enough.
  • Do not create managed AgentExecution records for connection tests.

Slice 10: Add Projection Surfaces Last

  • Add an AgentExecution-owned backend timeline projection foundation over the typed journal record set.
  • Expose timeline projection through the AgentExecution read model only after the read-model/storage split is explicit enough to avoid treating projection as durable truth.
  • Reintroduce rich Open Mission timeline rendering only after the canonical observation and journal path exists in the active tree.
  • Keep projection derived from accepted journal/state truth rather than as a parallel runtime source of meaning.

Working Conclusion

AgentExecution is not primarily blocked by entity storage. It is blocked by the remaining center of the runtime doctrine: distributed runtime-truth reduction, Mission consumer cleanup, process-owner separation, observation routing, decisioning, journal discipline, and transport convergence beyond the focused Terminal seam. The narrow Entity/storage base is real. The next slices should stabilize that base, remove parallel runtime truth, and only then add MCP, semantic operations, and projection surfaces.