Runtime and Control Plane

Agent Runtime Responsibilities

The agent app owns runtime mechanics: claims, backend calls, manifest loading, workspace hydration and sync, harness invocation, event normalization, heartbeats, and graceful shutdown. The backend owns policy and canonical transitions.

Depend on TAgentHarness, not Codex SDK types. Normalize provider events at the adapter boundary.

Context Manifest

The manifest contains runtime configuration, static MCP keys, organization integration IDs, missing required-integration markers, authorization epoch, context files, and declared output directories. It never contains provider credentials.

Context construction must page every filtered repository collection before selecting relevant dependencies, durability, human items, actions, task descendants, or integrations. Do not filter a single first page in memory: a valid item beyond that page would disappear from the run snapshot.

Task runs receive a bounded summary of prior attempts plus selected retained artifacts. Acceptance criteria and failed completion evidence prioritize which artifacts are hydrated. Files appear read-only beneath attempts/{runId}/outputs/; trajectories, logs, workspace locations, and raw provider payloads do not.

Treat every manifest loaded from object storage as untrusted persisted input. Validate paths, expected sizes, hashes, roles, and read-only/output contracts before hydration.

When a task run starts, copy every selected mutable organization Context file to run-owned object storage before writing the manifest. Instructions and skills from a pinned agent-pack revision, retained prior-attempt output, and other already-immutable sources may remain referenced in place. This preserves the exact mutable boot bytes without duplicating immutable content.

The owner-facing run-context API is a separate allowlisted projection of the manifest. It returns only target path, display name, role, detected media type, size, and availability, then serves an exact recorded path through the authenticated content boundary. The runtime snapshot is redacted before delivery. Never expose source object keys, hashes, prompts, runtime or tool configuration, integration grants, output directories, leases, or operational locations. Legacy canonical Context may be served only when its current bytes match the manifest’s recorded SHA-256; otherwise retain the entry as unavailable.

Task workers pass a 100 changed-file ceiling to terminal workspace sync. The workspace manager must inventory and validate the full candidate set before its first object-store write. Chat sync does not use this task-only ceiling.

Worker Leases

The backend owns both the heartbeat cadence and lease duration. A worker submits its identity and fencing token when it starts an attempt; the start response supplies the absolute lease deadline and heartbeat interval. Heartbeats renew that backend-issued deadline. Worker input cannot choose or extend the lease duration.

RUN_HEARTBEAT_INTERVAL_MS defaults to 60 seconds and RUN_LEASE_DURATION_MS defaults to 130 seconds on the backend; the lease must be longer than the heartbeat interval. Worker calls to the backend are independently bounded by BACKEND_REQUEST_TIMEOUT_MS, which defaults to 30 seconds. Failure to persist a heartbeat aborts local execution, while runbeat closes an attempt as soon as its canonical PostgreSQL lease expires.

Run Outcome Ownership

Successful execution has one writer. After the harness returns, the worker synchronizes declared outputs, derives sanitized receipts, and sends the exact final response and uploaded artifact list to run completion. The backend creates the immutable execution outcome and applies the task transition in that same transaction.

Agents use oblivectl task outcome submit only for semantic branches such as a plan, review verdict, verification report, promotion, human or action interrupt, learning result, or classified failure. Execution-scoped authorization rejects agent-authored execution outcomes. If a legacy or trusted service-staged execution outcome already exists, completion still requires exact equality with the worker-retained result.

Add Harness Behavior

1. Extend the provider-neutral interface only for a real cross-adapter need.
2. Keep Codex-specific configuration in the Codex adapter.
3. Preserve trace, revision, lease, authorization, and cancellation semantics.
4. Normalize events into existing agent runtime contracts.
5. Add adapter and runtime tests.
6. Update the developer guide when the public extension contract changes.

Add an oblivectl Command

oblivectl is the only authenticated state-changing/control-plane CLI available to agents. The trusted chat/worker process keeps the global service token; the model process receives only a short-lived capability bound to its organization, profile, and exact task run or chat turn.

1. Confirm the workflow is a backend-owned mutation rather than a filesystem operation.
2. Add a typed command parser in packages/oblivectl.
3. Extend its backend client with the smallest request/response contract.
4. Read organization, profile, task, run, and snapshot identity from hydrated context; read only the execution capability from the session environment.
5. Add or update the backend service-authenticated endpoint.
6. Preserve version, lease, ownership, and transition fencing.
7. Produce complete observable output suitable for the calling skill.
8. Update the oblivectl agent skill and command reference.
9. Update backend OpenAPI documentation.
10. Add CLI, client, route, and lifecycle tests.

Department execution capabilities may read only their department’s tasks and mutate only their owned tasks in the active root. Operator executions coordinate within the active root. Chat turns may perform organization-level control-plane work only in response to the active user turn.

Codex event normalization forwards actual provider events only. Do not manufacture compaction events; persistent chat resumes its real harness session, while ephemeral task runs start fresh.

In local authentication mode, the harness adapter may recover one credential failure only when the deployment synchronizer installed a generation newer than the failed attempt and the provider stream emitted no item event. Harmless session/turn-start events are buffered across that retry. Any item event fences replay because a command, tool, message, or file effect may already have started. An unrecovered chat failure exposes an actionable, redacted authentication message; an unrecovered task attempt is non-retryable until an administrator updates the deployment credential.

Every new run receives a backend-built safe integration snapshot. Existing runs are not hot-patched. Material changes advance the organization authorization epoch, so a stale execution cannot continue through the integration gateway and must restart from the current snapshot. The snapshot reports control-plane readiness only and must not trigger a live provider health call.

A task-completion verify run is narrower than ordinary execution. Its manifest selects the read-only sandbox, disables network and web search, supplies no output directories, MCP servers, or integration IDs, and exposes only retained evidence. Backend authorization rejects task mutations, human questions, schedules, Context promotion, and worker-owned execution outcomes from that run. It may submit only its exact verification report; the backend owns merge, repair, human escalation, and closure.

Do not add agent-facing wrappers for ordinary reads or declared-output writes when native filesystem access and deterministic validation are sufficient.

contextctl

contextctl verify is intentionally local and read-only. It validates staged structured Context. It must not read files on behalf of the agent, write files, create manifests, call the network, or promote canonical state.