Workspaces and context

Persistent workspaces

[workspace]
persist = true        # keep the disk across sleep/wake and restarts
idle_timeout = "15m"  # at least 1m

Both are off by default.

• Sleep: after idle_timeout with no governed calls, terminals or agent turns. Docker/Podman stop the container and keep volumes; Kubernetes deletes the Pod and keeps the PVC. Browser IDE sandboxes never idle-sleep. Manual POST /v1/citadels/{id}/sleep returns 409 citadel_busy while active.
• Wake: any governed call, terminal attach, turn, snapshot, fork or scheduled run wakes it under the same id.
• Restarts: tracked in workspaces.json; the control plane rebuilds the session (policy, secrets, broker) on first use.
• Every sleep and wake is logged in the audit trail.

Warning: Only the workspace disk survives a sleep. Processes, browser sessions, in-memory state and /tmp on a read-only root are lost. Keep work under /workspace.

CLI: runeward citadel sleep|wake|status <id>. MCP: runeward_sleep_citadel, runeward_wake_citadel, runeward_workspace_status.

Fork

POST /v1/citadels/{id}/fork (MCP runeward_fork_citadel) copies a workspace into a new, independent sandbox; the new run's forked_from names the source. The source policy must allow tool citadel, action fork. Only an administrator may fork into a policy not provably within the source's (Charter subsumption: policy, egress, endpoints, credentials, containment, budgets, secrets and audit settings are compared) or into larger resources. An override is recorded on the fork's run as charter_lineage = "admin-override".

Resumable agent turns

A session runs one turn at a time on one shared transcript.

MCP: runeward_start_turn, runeward_session_events, runeward_cancel_turn. A busy session returns 409 session_busy. Transcripts live in the control plane, so reconnecting with the last sequence seen loses nothing, even across restarts.

Note: Cancel does not rewind. Changes already made and output so far stay.

Agent group memory and handoffs

Each agent group (Cohort) has shared memory in control-plane state (cohort-memory/<cohort id>.json), never in a sandbox.

• Writes may set expected_version (0 = new key); a stale write fails with 409 version_conflict.
• Limits: keys 256 bytes, text 16 KiB, 16 tags, 1000 entries and 4 MiB per group; notes and briefs 8 KiB.
• Writes are attributed and logged. With [chronicle] redact on (the default), the ledger stores a SHA-256 of the text.

On the task board, use child tasks (POST .../tasks/{task}/children), handoff notes (complete and fail accept handoff) and per-agent briefs (* for all). Claiming with "context": true (MCP runeward_claim_task) returns the task, its notes, the brief, a parent summary and relevant memory.

MCP: runeward_memory_put, runeward_memory_get, runeward_memory_search, runeward_add_note, runeward_set_brief, runeward_handoff, runeward_add_child_task.

Scheduled runs

A schedule targets one sandbox or agent group (first member) and fires on a 5-field UTC cron or every interval (at least 1m). Each firing:

1. checks policy for tool schedule, action fire;
2. runs optional precheck and stops unless it exits 0;
3. starts a fresh agent session with command (plus prompt), under policy and budgets.

Missed windows are not backfilled, a firing is skipped while the last run is active, and at most 50 schedules may target one sandbox or agent group.

Operators: REST or runeward schedule create|list|get|delete|run. Agents (runeward_schedule_create, runeward_schedule_list, runeward_schedule_delete) only with:

[schedule]
self_service = true   # default false

State files

New state lives in workspaces.json, schedules.json and cohort-memory/ in the state directory; older control planes ignore them.