System is the authoritative singleton Entity for Open Mission system-scoped configuration. It owns the persisted singleton record addressed by system:singleton, mirrors that record to the Open Mission config document, provides the System-scoped entry points for Terminal creation and Terminal input routing, and exposes the canonical SystemSchema read for control-mode callers.

System does not own daemon health sampling. The operator-facing diagnostic read model is SystemStatusSnapshotSchema in packages/core/src/entities/System/SystemSchema.ts, and the assembly logic lives in packages/core/src/entities/System/SystemStatus.ts behind the daemon system.status request. That snapshot is a separate point-in-time read model, not the System Entity itself.

Authority

Definition

System represents the Open Mission system-scoped singleton record. The durable row is intentionally narrow: canonical id, Repository and Mission filesystem roots, shared Agent defaults, optional ghBinary, and the package version recorded when the singleton row was created. The hydrated SystemSchema is currently the same field set as storage plus base Entity timestamps and optional command descriptors.

GitHub App deployment credentials are not stored in the System row. Under ADR 0004.05, GitHub App credentials are deployment-scoped environment secrets, while Repository authorization for unattended GitHub operations is Repository-scoped installation binding. The current System record therefore remains a non-secret configuration boundary.

The singleton record is repo-external but still daemon-owned. System.ensureRecord() creates the row lazily from the Open Mission config document when missing, persists it through the Entity factory, and mirrors accepted changes back to config through writeOpenMissionConfig(...). The Entity therefore owns the canonical system-scoped config boundary, while the settings file remains an external persistence/document seam.

Current Doctrine Audit

Check Status Notes
ADR 0001.01 canonical self-identity Aligned System uses one canonical singleton id, system:singleton. Filesystem roots remain operational data, not self-identity.
ADR 0001.02 class/schema/contract split Aligned System.ts, SystemSchema.ts, and SystemContract.ts now own behavior, schemas, and contract metadata separately.
ADR 0001.02 canonical hydrated/storage naming Aligned SystemSchema is the hydrated Entity boundary and SystemStorageSchema is the persisted row. Legacy alias-style SystemDataSchema and SystemReadSchema are gone.
ADR 0001.05 identity-only read targeting Aligned SystemContract.methods.read now uses EntityIdSchema directly and addresses the singleton by top-level id.
ADR 0001.08 narrow storage versus hydrated read Aligned SystemStorageSchema stores only singleton config fields and timestamps. Diagnostic status material remains in SystemStatusSnapshotSchema, not in SystemStorageSchema.
Contract-declared events Aligned SystemContract declares no public Entity events, and the implementation does not publish any.
Entity-specification schema metadata discipline Mostly aligned SystemSchema.ts carries meaningful .meta({ description }) coverage across the current exported schema surface and storage-facing zod-surreal descriptions on SystemStorageSchema.

Responsibilities

Area System owns
Identity Canonical singleton Entity id system:singleton.
Persisted config repositoriesRoot, missionsRoot, shared Agent defaults, optional ghBinary, package version, and base Entity timestamps.
Lazy creation Building the default singleton row from readOpenMissionConfig() or getDefaultOpenMissionConfig() when the persisted row is missing.
Config mirroring Writing accepted singleton changes back through writeOpenMissionConfig(...).
Shared Agent defaults System-scoped default adapter, enabled adapters, optional mode, optional model, and optional reasoning effort.
Deployment boundary Excluding deployment secrets such as GitHub App private keys from the persisted singleton record.
System-scoped Terminal entry Building a Terminal launch request rooted at repositoriesRoot and owned by the System Entity.
Package version read Reading the current package version for bootstrap comparison against the stored singleton record.

Non-Responsibilities

Neighbor System does not own
SystemStatusSnapshotSchema Point-in-time daemon, host, runtime, and GitHub status sampling. That is a separate snapshot helper surface, not System Entity truth.
GitHub App deployment secrets App id, private key, client secret, and webhook secret remain deployment configuration outside the persisted singleton row.
Repository Repository discovery, Repository initialization, Repository control state, and Mission preparation.
AgentExecution Execution lifecycle, process ownership, message delivery, runtime health, and journal truth.
Terminal PTY runtime state, screen state, recording rows, and transport event publication.
Daemon transport IPC request routing for system.status, entity.query, or entity.command.

Major Seams And Boundaries

Boundary What crosses the System boundary What stays outside
Entity transport Canonical singleton id plus method-specific payloads validated by SystemContract. Daemon dispatch wiring and UI command composition.
Config document seam System reads defaults from and mirrors accepted writes to the Open Mission config document. The document parser and filesystem adapter implementation details.
Terminal delegation System.createTerminal converts System-owned intent into a TerminalInputSchema request with System ownership metadata. PTY lifecycle, live screen state, recording append semantics, and Terminal events.
Status snapshot seam SystemStatus.ts reads config, current GitHub auth/status inputs, daemon runtime inputs, and host diagnostics to build SystemStatusSnapshotSchema. Persisted singleton SystemStorageSchema, deployment secrets, and Entity transport semantics.

Contract Methods

Method Kind Input schema Result schema Behavior Likely callers Side effects
read query EntityIdSchema SystemSchema Resolves the singleton System Entity by canonical id, lazily creating it when absent, and returns the hydrated singleton data. Daemon bootstrap in packages/core/src/daemon/DaemonIpcServer.ts, control-mode entity reads, tests. May create and persist the singleton row and mirror it to the config document.
configure mutation SystemConfigureSchema SystemSchema Updates filesystem-root and optional ghBinary settings on the singleton record and mirrors the result to config. It does not accept deployment secrets such as GitHub App credentials. Control-mode System settings surfaces and tests through entity.command or direct class calls. Persists the singleton row and writes the config document.
configureAgent mutation AgentOwnerSettingsSchema SystemSchema Updates shared system-scoped Agent defaults while preserving or clearing model settings according to adapter changes, then mirrors the result to config. Control-mode System settings surfaces and tests through entity.command or direct class calls. Persists the singleton row and writes the config document.
readTerminal query EntityIdSchema TerminalSchema Delegates to Terminal.read(...) for one existing Terminal id. System-scoped terminal readers, daemon entity query dispatch, tests. None beyond Terminal hydration.
createTerminal mutation TerminalLaunchOptionsSchema TerminalSchema Builds a System-owned Terminal launch request with workingDirectory = repositoriesRoot and delegates Terminal creation. Control-mode terminal launch surfaces and daemon entity command dispatch. Persists and launches a Terminal through the Terminal Entity boundary.
sendTerminalInput mutation TerminalSendInputSchema TerminalSchema Delegates raw keyboard or resize input to the Terminal Entity by canonical Terminal id. Terminal control surfaces routed through the System command entry. Causes Terminal-owned PTY input delivery and any resulting Terminal recording/event side effects.

readCurrentPackageVersion() is a class helper used by daemon bootstrap, not a contract method. It belongs to the System class because it supports System bootstrap comparison logic, but it is not part of the remote Entity contract.

Events

SystemContract currently declares no public Entity events.

That absence is important: operator-facing status refresh is distributed through the daemon system.status request and snapshot polling paths, not through a System Entity event family. If a future public System event is needed, the payload must be declared in packages/core/src/entities/System/SystemSchema.ts and registered in packages/core/src/entities/System/SystemContract.ts rather than being invented in daemon status helpers.

Property Groups

Group Property Type / schema Role
Identity id EntityIdSchema Canonical singleton System Entity id.
Filesystem scope repositoriesRoot string Root path used for Repository discovery and the default System-owned Terminal working directory.
Filesystem scope missionsRoot string Root path where Mission worktrees are materialized.
Shared Agent defaults defaultAgentAdapter AgentOwnerSettingsSchema.shape.defaultAgentAdapter Default Agent adapter for system-scoped work.
Shared Agent defaults enabledAgentAdapters AgentOwnerSettingsSchema.shape.enabledAgentAdapters Enabled adapter list for system-scoped work.
Shared Agent defaults defaultAgentMode optional AgentOwnerSettingsSchema.shape.defaultAgentMode Optional default AgentExecution launch mode.
Shared Agent defaults defaultModel optional AgentOwnerSettingsSchema.shape.defaultModel Optional default model name for system-scoped Agent launches.
Shared Agent defaults defaultReasoningEffort optional AgentOwnerSettingsSchema.shape.defaultReasoningEffort Optional default reasoning effort for system-scoped Agent launches.
External tool config ghBinary optional string Optional GitHub CLI override used by the current CLI-backed status and compatibility checks.
Package metadata packageVersion string Package version recorded when the singleton row was created.
Timestamps createdAt, updatedAt DateTimeSchema Base Entity storage timestamps.

commands may appear on hydrated SystemSchema because it comes from the shared EntitySchema base, but System.ts does not currently define a dedicated command-view method or public System UI metadata. The singleton row itself does not persist command descriptors.

Schema And Subschema Map

Schema Purpose
SystemStorageSchema Canonical persisted singleton system row.
SystemSchema Canonical hydrated singleton Entity boundary shape returned by System.read, configure, and configureAgent.
SystemSettingsUpdateSchema / SystemConfigureSchema Method-specific mutation input for filesystem root and ghBinary changes. GitHub App secrets remain outside this schema.
SystemRepositoriesSettingsSchema Narrow Repository-discovery settings shape derived from the singleton configuration.
SystemStatusConfigSchema Config subsection included in the non-Entity SystemStatusSnapshotSchema.
GitHubSystemStateSchema Current GitHub status subsection of the snapshot. The present implementation is still CLI-backed for this diagnostic path.
DaemonSystemStateSchema Daemon process diagnostics subsection of the status snapshot.
HostSystemStateSchema Host platform and memory diagnostics subsection of the status snapshot.
RuntimeSystemStateSchema Runtime supervision, AgentExecution, runtime lease, and SurrealDB counts in the status snapshot.
SystemDiagnosticsStateSchema Sampling metadata for the status snapshot cache.
SystemStatusSnapshotSchema Point-in-time system status read model returned by daemon system.status. This is not the System Entity boundary.

ERD 

erDiagram
  SYSTEM {
    string id PK
    string repositoriesRoot
    string missionsRoot
    string defaultAgentAdapter
    array enabledAgentAdapters
    string defaultAgentMode
    string defaultModel
    string defaultReasoningEffort
    string ghBinary
    string packageVersion
    string createdAt
    string updatedAt
  }

  TERMINAL {
    string id PK
    object owner
    string workingDirectory
  }

  SYSTEM ||--o{ TERMINAL : requests_system_owned_terminal

The persisted graph is intentionally small. System owns one singleton row and may create System-owned Terminal rows, but diagnostic status remains a separate snapshot model rather than an embedded child Entity family on SystemSchema.

Main Runtime Flows

Singleton Read And Lazy Creation 

flowchart TD
  A[Caller reads system:singleton] --> B[System.read]
  B --> C[System.resolve]
  C --> D[System.ensureRecord]
  D --> E{Stored row exists?}
  E -- yes --> F[Return hydrated SystemSchema]
  E -- no --> G[Read config defaults]
  G --> H[Build SystemStorageSchema]
  H --> I[Persist singleton row]
  I --> J[Mirror accepted row to config]
  J --> F

Configuration Update 

flowchart TD
  A[configure or configureAgent] --> B[Parse method-specific schema]
  B --> C[Ensure singleton record]
  C --> D[Merge accepted fields into current SystemSchema]
  D --> E[toStorage via System.save]
  E --> F[Persist SystemStorageSchema]
  F --> G[Mirror accepted state to config]
  G --> H[Return hydrated SystemSchema]

System-Owned Terminal Creation 

flowchart TD
  A[createTerminal] --> B[Parse TerminalLaunchOptionsSchema]
  B --> C[Ensure singleton System]
  C --> D[Build TerminalInputSchema]
  D --> E[owner.entityName = System]
  D --> F[owner.entityId = system:singleton]
  D --> G[workingDirectory = repositoriesRoot]
  E --> H[Delegate to Terminal.create]
  F --> H
  G --> H
  H --> I[Return TerminalSchema]

Status Snapshot Read Model 

flowchart TD
  A[Daemon request system.status] --> B[DaemonIpcServer]
  B --> C[readSystemStatus]
  C --> D[Read config and ghBinary]
  C --> E[Probe GitHub CLI auth state]
  C --> F[Merge daemon runtime inputs]
  C --> G[Sample host memory and load]
  D --> H[Assemble SystemStatusSnapshotSchema]
  E --> H
  F --> H
  G --> H
  H --> I[Return system status snapshot]

This last flow is intentionally documented on the System page because operators often encounter it together with System settings. It is still a separate snapshot surface, not a SystemContract method and not the canonical System Entity read.

Relation And Collaborator Reference

Collaborator Direction of authority Why it matters
Open Mission config document helpers in packages/core/src/settings/OpenMissionInstall.ts System consumes them as persistence/document seams. System reads defaults from config and mirrors accepted singleton writes back to config.
Terminal in packages/core/src/entities/Terminal/Terminal.ts System delegates Terminal behavior to Terminal. System can create or address a System-owned Terminal, but Terminal remains the owner of PTY lifecycle and recording.
Daemon bootstrap in packages/core/src/daemon/DaemonIpcServer.ts Daemon consumes System.read(...) and readCurrentPackageVersion(). Bootstrap ensures the singleton exists and compares stored versus current package version.
SystemStatus.ts in packages/core/src/entities/System/SystemStatus.ts Separate snapshot helper consumes config and daemon runtime inputs. It builds operator-facing status without redefining System Entity truth.
Daemon system.status route in packages/core/src/daemon/DaemonIpcServer.ts Daemon-owned request surface. This is how browser and native hosts obtain SystemStatusSnapshotSchema.

Cross-Control Checklist

Surface Status Notes
Class vs schema Aligned System.ts hydrates SystemSchema and narrows persisted output through toStorage().
Class vs contract Aligned Contract methods map directly to implemented class methods, and singleton reads use canonical id.
Schema vs ADR 0001.08 Aligned Diagnostic status remains a separate snapshot model instead of widening SystemStorageSchema.
Event discipline Aligned No public System Entity events are declared or published.
Docs vs implementation Aligned This page now distinguishes the singleton Entity from the system.status snapshot helper instead of collapsing them into one concept.

Implementation Findings To Carry Forward

  • Keep SystemStorageSchema narrow. Do not move daemon health or runtime supervision snapshot fields into the persisted singleton row.
  • Keep the singleton addressed by canonical system:singleton rather than reintroducing empty read wrappers or path-based targeting.
  • Keep Terminal lifecycle delegated to Terminal; System should continue owning only the System-scoped launch intent and owner linkage.
  • Keep SystemStatusSnapshotSchema documented and implemented as a true snapshot read model. It is not a second public name for SystemSchema.