Docs/Supervision (zirv ctx)

Verbs

Declarative worker workspaces#

The harness runtime can prepare a repeatable worker environment before the worker receives its first turn. Repository-owned .zirv/ctx.toml may declare only inert requirements:

[[workspace]]
name = "backend"
mcp_servers = ["linear"]
skills = [{ id = "systematic-debugging" }]

Clone URLs and shell commands are executable on the operator's machine, so they are accepted only from ~/.zirv/ctx.toml:

[[workspace]]
name = "backend-with-dependencies"
git = [
  { repo = "https://github.com/example/api-contracts.git", branch = "main", dir = "deps/api-contracts" },
]
setup = ["cargo fetch", "cargo build --workspace"]

zirv ctx agent claude "implement the API change" --worktree --workspace backend-with-dependencies

With --worktree, extra repositories and setup commands run inside the fresh linked worktree. Without it, the explicit --workdir or current checkout is the workspace root. Repositories are cloned in declaration order and setup commands run sequentially after every clone is ready. Each successful setup step is recorded append-only by checkout, index and command digest, so retrying a failed setup skips only unchanged successes; a changed command reruns. A failed clone or setup command aborts the delegation; the worker never starts. Clones time out after five minutes and each setup step after ten minutes. Both run with credentials, all ZIRV_* authority/session variables, and inherited git-control variables removed from their environment. Existing clone directories are accepted only when their origin and current branch match the declaration, and symlinks in any destination component are refused. Because materialization happens before the worker harness, executable workspaces require an unexpired writing, shell, network, and root-path delegation envelope; Zirv refuses them when it cannot enforce a narrower grant.

mcp_servers contains names only—never commands, endpoints, or secrets. Zirv checks the final routed harness's own MCP configuration (including Claude --mcp-config/.mcp.json and Codex mcp_servers configuration) and refuses the delegation if any name is absent. Claude project MCP files and disable settings follow the headless launch's normal precedence; Codex project config is counted only below a path the operator's user config marks trusted. A workspace with MCP requirements runs inline on the validated harness with cross-harness fallback disabled for that launch. skills are resolved through the normal SkillRegistry, including version pins and dependencies, and are attached as labelled instructions that grant no authority. A delegation manifest may name an AgentManifest with agent: <id>; its skills are defaults only, and an explicit workspace skills list replaces them. This does not apply the manifest's model, role, or runtime settings; its read-only and required capability constraints still gate the launch.

Workspace arrays from the operator and repository layers are additive. Names must be unique, unknown fields are rejected, git destinations must be relative children outside .zirv, and the repository layer cannot replace an operator-defined workspace. Repository entries containing git or setup are rejected as security errors; selecting a workspace name is deliberately not treated as authorization because an autonomous seat can select one too.