From Authored Workspace to a Controlled Run
In holaOS, the workspace is the input to an agent run, not simply the folder in which a process happens to start. This chapter focuses on the boundary between authored workspace state and runtime-generated execution state. Understanding that boundary lets you predict which changes affect every future run, which changes are compiled only when a run begins, and where to look when a tool, prompt, or result is wrong.
The distinction is easy to miss because both kinds of state can appear as ordinary files. A workspace contains instructions, app declarations, skills, and model-related settings that a person can edit. It also contains runtime-owned records for sessions, outputs, queues, continuity, and memory. holaOS keeps these categories separate because they have different owners and different lifetimes.
What the workspace author owns
The authored part of a workspace expresses how the environment should behave. AGENTS.md is the standing instruction surface: the place for rules that should apply on every run, such as the role the agent is playing, a preferred voice, or a non-negotiable guardrail. workspace.yaml is the runtime plan: it identifies the active agent and records the apps, skills, workspace commands, and MCP policy that make up the workspace's intended capability surface.
Apps and skills are not equivalent entries in that plan. An app is a runtime-managed capability package with its own manifest; a skill is reusable instruction material that can be loaded when a task needs it. MCP configuration describes structured tool servers and their visibility rules. A command is an explicit workspace capability. Keeping these concepts separate means an author can change the operating policy without rewriting an app, or add a narrow skill without making its instructions part of every prompt.
The workspace also has a runtime-owned perimeter around those authored files. Session records, request snapshots, staged attachments, output associations, and continuity projections help the runtime execute and resume work, but they are not standing policy. Durable memory is separate again: it contains knowledge meant to be recalled later, not every transient detail of the latest session. The result is not a single “agent state” file. It is a set of surfaces whose ownership and lifetime are explicit.
A useful way to test the distinction is to ask what a change is trying to accomplish. Changing AGENTS.md changes a standing rule. Adding an application entry changes which domain capability the runtime should manage. Editing an MCP allowlist changes which external tool surface may be projected. Updating a session snapshot does not express a new policy; it preserves execution truth for resumption. These changes may all be stored near one another, but treating them as interchangeable would make later behavior difficult to explain.
That separation has a practical consequence for editing. If an operator changes AGENTS.md, edits a skill, adds an app declaration, or changes MCP policy, the change belongs to authored workspace state. The runtime will read and compile it for a subsequent run. It does not retroactively rewrite the package already handed to an active harness. A current run is therefore a snapshot of a particular workspace interpretation, not a continuously mutable view of every file on disk.
The runtime also does not treat every file in the workspace as an automatic prompt input. Its reference collection is deliberately narrow: it starts from the workspace plan, loads the standing instruction file and the application manifests referenced by the plan, and then stages other surfaces explicitly when the run requires them. That prevents an arbitrary cache, build artifact, or unrelated document from becoming implicit agent context merely because it happens to sit below the workspace root.
MCP policy illustrates why authored configuration needs interpretation rather than blind copying. A workspace must use mcp_registry for its MCP contract; the older tool_registry shape is explicitly unsupported. If an allowlist contains tool ids, those ids are qualified as server.tool and must point to enabled configured servers. If the allowlist is omitted or empty, the configured enabled servers remain available for runtime discovery. The two configurations may look similar to a reader scanning YAML, but they create different execution surfaces.
That difference is also a choice about predictability. An explicit allowlist gives the runtime concrete references it can validate and carry into the run. Discovery mode is useful when the server's catalog is not known ahead of time, but it asks the host to discover more at runtime. A team that wants a narrow, reviewable action surface should prefer explicit references where the environment supports them; a team that needs a flexible server must accept that configuration alone will not enumerate every concrete tool before the host connects.
Application declarations have their own consistency rules. The app id in workspace.yaml must match the id in the referenced runtime manifest, and the managed app must declare an MCP port. These rules are not stylistic preferences. Without them, the runtime could attach a manifest to the wrong app or have no reliable endpoint at which to discover the app's tools. A structured workspace plan is valuable precisely because it rejects ambiguous intent before an agent starts acting on it.
How the runtime compiles one run
Once a request arrives, holaOS turns those authored surfaces and the relevant runtime state into a run-specific package. The process can be understood as six linked stages.
First, the runtime collects the references it needs. It reads workspace.yaml, follows the application manifest paths declared there, and loads the standing instruction material. The result is a bounded input set, not an indiscriminate copy of the workspace. This is the point at which a malformed plan, missing app manifest, duplicate application id, or mismatched app identity can stop the run before the harness is involved.
Reference collection is not the same as granting the model universal filesystem authority. It tells the runtime which authored material participates in the plan. Later capability staging and host boundary rules decide which files, tools, and app endpoints the executor can actually use. That layered design is important for long-lived workspaces, where generated files and logs can greatly outnumber the policy and configuration that should shape a run.
Second, it compiles the workspace plan. The runtime interprets the authored configuration into structured results: general agent configuration, resolved prompts, resolved MCP servers and tool references, an MCP catalog, resolved applications, an allowlist, and a configuration checksum. The checksum is a compact identity for the authored configuration that participated in the plan. It gives the runtime and operator a way to notice that the execution environment changed without pretending that a checksum explains why the change was desirable.
This compile step is where MCP policy becomes operational. With an explicit allowlist, the runtime checks the server-qualified ids and carries concrete tool references forward. With no explicit allowlist, it carries the enabled server configuration and leaves concrete discovery to the host. In either case, the runtime has made a decision about the boundary: which servers belong to the run, and whether their tool surface is constrained in advance or discovered from the server.
Third, it prepares runtime-owned capabilities. The runtime can stage browser tools, runtime tools, MCP payloads, skills, workspace commands, and application processes according to the selected harness's preparation plan. It may start a workspace MCP sidecar, map logical server ids to physical ids, bootstrap resolved apps, and merge app-provided MCP servers into the prepared set. This is where an authored declaration becomes a capability that can actually be called—or remains absent because the current session is not allowed to use it.
The word “staged” is important. A capability can exist in the workspace without being visible in every session. holaOS can give a coordination-oriented front session a smaller surface while giving a delegated execution session browser or file tools. The runtime also carries the session kind and the relevant browser configuration into this decision. The same workspace can therefore produce different run packages without having contradictory definitions of what the workspace is.
Fourth, it loads context belonging to the current execution. This includes persisted session-resume state, scratchpad metadata, recalled durable memory, current profile context, operator-surface context when browser tooling is active, and pending user-memory proposals. These inputs do not redefine the authored workspace. They tell the runtime what is happening around the workspace now and what information may be relevant to this request.
This is also where the difference between continuity and memory begins to matter operationally. A session snapshot can help an interrupted run resume, while a durable fact or procedure may be retrieved because the new request needs it. The runtime does not dump every previous turn into the prompt. It selects bounded context for the current request and keeps the rest available through the appropriate state surface.
Fifth, it projects the agent runtime configuration. The runtime assembles the system prompt, prompt sections and layers, model client, tools, workspace tool ids, skill ids, output format, checksum, and capability manifest. It also resolves the selected model before the harness starts. A request-scoped reasoning preference can travel with the run, but it is not silently turned into a new global default.
The capability manifest is the bridge between policy and execution. It describes the visible and callable surface the host should make available. That surface can include runtime-backed tools, skills, browser tools, workspace MCP, app tools, and attachments, but only when the preceding stages have authorized and prepared them. A prompt may explain how to use a capability; it should not be treated as the authority that creates one.
Sixth, it builds the harness request and records what crossed the boundary. The adapter constructs a reduced host request containing the run identity, instruction, context messages, selected model client, attachments, projected tools, skills, MCP servers and references, and workspace checksum. The runtime computes a request fingerprint and persists a sanitized request snapshot before launching the host. The host then translates that package into executor-native state and returns normalized lifecycle events.
The entire path can be pictured as a conversation among different owners of state:
The diagram does not mean that the workspace is a network service or that the operator directly controls every internal call. It identifies the ownership transitions. The operator supplies intent. The workspace supplies authored rules and references. The runtime validates, compiles, and projects. The host adapts. The executor runs. The runtime then records results and continuity so the operator can inspect what happened.
A failure at any transition has a different signature. A plan can be syntactically valid but fail because an app id does not match its manifest. An app can pass plan compilation but fail health checks when its process or MCP endpoint is unavailable. A server can be configured but produce no callable tool if it is disabled or its authorization fails. A run can have the right tools but the wrong prompt context if memory or session state was not loaded as expected. These are not variants of one generic “agent error”; they are failures at different ownership boundaries.
Why this boundary changes debugging
Suppose an agent cannot call an app tool. There are several distinct explanations. The app may not be declared, its manifest may fail validation, its process may not be healthy, its MCP server may not be connected, or the tool may not be visible to this session kind. Treating all of these as “the model failed” discards the information the architecture is designed to preserve.
The same reasoning applies to a wrong answer. If the standing policy was not loaded, inspect reference collection and prompt projection. If a recent decision was missing, inspect continuity or memory retrieval. If the prompt names a server but the host has no corresponding callable tool, inspect the projected registry rather than trusting the prose. If the tool ran and the result is not visible, inspect output association and runtime persistence.
A request snapshot helps with this diagnosis because it records the prepared state rather than only the final response. The checksum helps identify a changed authored environment. Neither is a magic audit trail: a sanitized snapshot cannot establish that an external provider behaved correctly, and a checksum cannot prove that a configuration was least-privilege. They are observability mechanisms within a larger control boundary.
Consider a small policy change. If an operator adds one qualified MCP tool to an allowlist, the current harness session does not suddenly gain it; the workspace must be compiled again. On that next run, the runtime can validate the server reference, the host can discover or materialize the permitted tool, and the request snapshot can show the new projected package. If the next run still lacks the tool, the investigation can move through those stages in order instead of guessing whether the model ignored an instruction.
This model also clarifies what “takes effect on the next run” means. Editing a workspace file changes the source from which the runtime will compile future execution state. It does not rewrite a harness session that already received its package. Restarting or retrying may therefore produce a different run for a legitimate reason: the authored contract, enabled server set, app health, or recalled context has changed. A reproducible diagnosis records which package was actually sent, not only which files appear on disk afterward.
The key idea is that a workspace in holaOS is neither a passive folder nor an all-knowing prompt. It is authored intent that the runtime compiles into a bounded, inspectable execution package. Once that package exists, the next architectural question is what the harness is allowed to vary—and why the tools visible to a main session need not be the tools visible to a delegated run.