{
  "id": "page:docs-agent-reference-runtime-and-layout",
  "_kind": "Page",
  "_file": "wiki/docs/agent-reference/runtime-and-layout.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-reference/runtime-and-layout.md",
    "sourceKind": "repo-docs",
    "title": "Runtime And Layout",
    "displayName": "Runtime And Layout",
    "slug": "docs/agent-reference/runtime-and-layout",
    "articlePath": "wiki/docs/agent-reference/runtime-and-layout.md",
    "article": "\n# Runtime And Layout\n\nThis page is the short runtime model for contributors who need to reason about replay, run state, or journal repair.\n\n## Deterministic Replay Loop\n\nThe core orchestration flow spans the SDK runtime and storage layers:\n\n1. Acquire `run.lock`.\n2. Build the replay engine from `run.json`, the journal, and the derived state cache.\n3. Import the process entrypoint.\n4. Run the process inside `withProcessContext(...)`.\n5. When the process requests an unresolved effect, the runtime throws an effect-pending exception instead of executing side effects inline.\n6. External orchestration resolves effects and posts results through `babysitter task:post`.\n7. The next iteration replays resolved effects and advances deterministically.\n\nRelevant source roots:\n\n- [`packages/sdk/src/runtime/`](../../packages/sdk/src/runtime)\n- [`packages/sdk/src/storage/`](../../packages/sdk/src/storage)\n- [`packages/sdk/src/tasks/`](../../packages/sdk/src/tasks)\n\n## Run Directory Layout\n\nDefault layout under the active runs root:\n\n```text\n<runsRoot>/<runId>/\n├── run.json\n├── inputs.json\n├── run.lock\n├── journal/\n├── tasks/<effectId>/\n├── state/state.json\n├── blobs/\n└── process/\n```\n\nUse the active runs root from [Command Surfaces](./command-surfaces.md): global `~/.a5c/runs` by default, repo-local only when configured or when probing legacy runs.\n\n## Bare Runs and Process Assignment\n\nA run can be created without `--entry`, producing a **bare run** whose `entrypoint.importPath` is `\"bare-run\"`. Bare runs reserve a run directory and journal but cannot be iterated until a process is attached.\n\nTo attach a process, use:\n\n```bash\nbabysitter run:assign-process <runDir> --entry <path>#<export> [--process-id <id>] --json\n```\n\nThis updates `run.json` via `writeRunMetadata()` and appends a `PROCESS_ASSIGNED` journal event. After assignment the run can proceed through normal `run:iterate` cycles. The `orchestrateIteration` runtime guards against iterating a bare run that has not yet been assigned a process.\n\nThe `instructions:babysit-skill` command dynamically reports existing bare runs so that the orchestrating agent can decide whether to assign a process or create a new run.\n\n## Journal Event Model\n\nThe event stream is append-only and centers on:\n\n- `RUN_CREATED`\n- `PROCESS_ASSIGNED`\n- `EFFECT_REQUESTED`\n- `EFFECT_RESOLVED`\n- `RUN_COMPLETED`\n- `RUN_FAILED`\n\nThe state cache is derived data. If it drifts from the journal, repair with `run:rebuild-state`. If journal entries are malformed or partially written, use `run:repair-journal` carefully after inspecting the affected run.\n\n## Effects\n\nProcesses request work through `ProcessContext` intrinsics such as:\n\n- `ctx.task()`\n- `ctx.breakpoint()`\n- `ctx.sleepUntil()`\n- `ctx.orchestratorTask()`\n- `ctx.hook()`\n- `ctx.parallel.all()` and `ctx.parallel.map()`\n\nThose APIs are part of the SDK runtime contract, not ad hoc process behavior. Changes here need replay, serialization, and state-cache discipline.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}