Merge M8: conductor loop - self-orchestration

Closes #25, closes #26, closes #27
feat(orchestration): retry <runId> — authored by headless pi worker (#26 , #27 )
2026-09-02 22:42:52 -05:00 · 2026-09-02 22:42:52 -05:00 · 2026-09-02 22:25:56 -05:00 · 2026-09-02 22:14:18 -05:00 · 2026-09-02 22:14:18 -05:00 · 2026-09-02 22:08:34 -05:00
35 changed files with 2335 additions and 61 deletions
@@ -106,4 +106,201 @@ No credentials are recorded in this file.

 All 11 acceptance criteria demonstrated. The real model request passed.

+---
+
+## Phase 5: Configuration-driven Hello World (M1)
+
+### Entry 5.1 — before
+
+- Timestamp: 2026-09-03
+- Intended action: Make the container POC configuration-driven. Baseline committed and tagged `poc-container-hello-v0`. Milestone M1 tracked in Gitea (issues #1-#4): (T1) config module with idempotent bootstrap and strict v1 validation; (T2) wire scripts and compose to config.json with fail-closed behavior; (T3) sandboxed config selftests; (T4) E2E verification and documentation.
+- Reason: Per docs/plans/2026-09-02_atomic-mosaic-foundation.md — config.json must be the sole discovery entry point; updates and runs must never corrupt or invent configuration.
+- Expected result: All M1 acceptance criteria pass; Hello World reproducible from configuration alone.
+
+### Entry 5.2 — after
+
+- Timestamp: 2026-09-03
+- Commands run: `scripts/test-config.sh` (20 cases); fail-closed checks (compose without launcher env, verify/reset with missing config); `scripts/bootstrap.sh`; config-driven `scripts/hello.sh`, `scripts/verify.sh`, negative marker test, sandboxed reset symlink refusal (canary survived), real reset + bootstrap + build + verify; config checksum comparison across the entire flow.
+- Observed result:
+  - Config selftests: 20 passed, 0 failed.
+  - Fail-closed confirmed: compose exits 1 without launcher env; verify/reset exit 1 on missing config before any mutation.
+  - Bootstrap created `~/.config/mosaic-dev/config.json` exclusively; second run validated without rewriting (content + mtime unchanged).
+  - Config-driven hello/verify returned exactly `MOSAIC_HELLO_OK`; verify exit 0; negative marker test exit 1.
+  - Reset refused symlinked dataRoot; canary file survived; real reset removed only the configured data root.
+  - config.json checksum unchanged across hello/verify/reset/bootstrap/build/verify.
+- Failure or correction:
+  1. Selftest harness bug: `cfg` helper invoked without a body for the symlink case (`$2: unbound variable`). Fixed in the harness; product code unaffected.
+  2. E2E rerun-after-reset failure: `verify.sh` did not ensure the configured data root existed before the container mount. With the data root absent, Docker auto-created the host path as root:root, and the container's uid-1000 user could not write the generated system prompt. Fixed by calling `bootstrap_runtime_dir` in `verify.sh`; also hardened it to fail with a clear message when the data root exists but is not writable (root-owned leftover). Clean-slate E2E rerun: all steps green.
+- Credential check: no credential material in config, scripts, logs, or test output.
+
+## Result (M1)
+
+Configuration-driven Hello World verified. `main` merged with M1 and tagged `config-hello-v1`.
+
+---
+
+## Phase 6: Mission and task abstraction (M2)
+
+### Entry 6.1 — before
+
+- Timestamp: 2026-09-03
+- Intended action: Add the first mission/task layer, host-side only (Gitea milestone M2, issues #6-#9): strict v1 schemas for missions and tasks, a task runner executing through the proven config-driven container path, immutable write-once run records under `<dataRoot>/runs/`, `expectExact` gating, timeouts, selftests, fixtures, and docs.
+- Reason: The foundation plan's following layer — mission (objective + directives), task (bounded unit), run (one attempt), result (immutable evidence) — must exist as data and records before any policy or multi-agent work.
+- Expected result: `scripts/run-task.sh tasks/hello-marker.json` succeeds with exactly `MOSAIC_HELLO_OK`; wrong expectations fail; every run leaves an immutable record; configuration remains untouched.
+
+### Entry 6.2 — after
+
+- Timestamp: 2026-09-03
+- Commands run: `scripts/test-task.sh` (18 cases incl. live runs); `scripts/run-task.sh validate` / `run` on committed fixtures; `node scripts/mosaic-task.mjs list`; config checksum comparison across runs.
+- Observed result:
+  - Selftests: 18 passed, 0 failed (schema negatives; live exact-marker success; wrong expectExact fails; distinct run dirs; result.json contents; list).
+  - Fixture run: status `succeeded`, response exactly `MOSAIC_HELLO_OK`, mission snapshot recorded.
+  - Run records written once under `<dataRoot>/runs/r-<utcstamp>-<rand>/`; reruns never clobber.
+- Failure or correction: none this phase.
+- Credential check: no credential material in task data, run records, or logs.
+
+## Result (M2)
+
+Mission/task layer verified end-to-end. `main` merged with M2 and tagged `mission-task-v1`.
+
+---
+
+## Phase 7: Release model and safe updates (M3)
+
+### Entry 7.1 — before
+
+- Timestamp: 2026-09-03
+- Intended action: Add the release substrate (Gitea milestone M3, issues #10-#13): RELEASE file single-sources the version (0.0.X line per owner direction), image tags derive from it, scripts/release.sh provides package/activate/rollback/status, activation is health-gated by the M2 task runner, pointer + append-only log under <dataRoot>/state/.
+- Reason: The owner's top invariant — updates must never corrupt a working installation — needs a mechanism, not a convention: gate-then-flip with recorded history and rollback.
+- Expected result: Update, refusal, and rollback drills all green with config checksums unchanged.
+
+### Entry 7.2 — after
+
+- Timestamp: 2026-09-03
+- Commands run: scripts/test-release.sh (14 cases); recorded drills: update (0.0.3 -> 0.0.4 package+activate+verify), fault-injected refusal, rollback to 0.0.3.
+- Observed result:
+  - Selftests: 14 passed, 0 failed.
+  - Update drill: packaged and activated r0.0.4 after exact-marker health gate; verify green under the new tag; config checksum unchanged.
+  - Refusal drill: health-gate fault injection -> activation refused (exit 1), pointer untouched, refusal appended to the log.
+  - Rollback drill: health-gated rollback to r0.0.3; pointer restored; log records package/activate/refused/rollback history append-only.
+- Failure or correction:
+  1. release.sh initially failed with missing state/ directory (no mkdir before pointer/log writes); fixed.
+  2. Selftest harness mutated the repo RELEASE and restored the mutated copy (mv-back bug) plus a second trap replacing the first; fixed with inline backup restore and one self-healing exit trap. Product code unaffected.
+- Credential check: no credential material in release state, logs, or drills.
+
+## Result (M3)
+
+Release model and safe updates verified by drills. `main` merged with M3 and tagged `release-model-v1`.
+
+---
+
+## Phase 8: Runtime adapter seam (M4)
+
+### Entry 8.1 — before
+
+- Timestamp: 2026-09-03
+- Intended action: Formalize the harness boundary (Gitea milestone M4, issues #16-#19): documented adapter contract under /opt/mosaic/adapters/<name>/adapter.sh; run-agent.sh becomes a dispatcher; pi extracted unchanged; deterministic mock adapter for provider-free seam tests; config gains optional execution.adapter (default pi, configVersion unchanged); mission directives gain their sanctioned injection point via the run snapshot; RELEASE bumps to 0.0.5 with a health-gated activation.
+- Reason: Future harnesses (Claude, Codex, OpenCode) must be additive — one directory each — and mission content needs a single sanctioned path into the runtime.
+- Expected result: All suites green including new deterministic seam cases; 0.0.5 activated by health gate; mission-bearing run recorded.
+
+### Entry 8.2 — after
+
+- Timestamp: 2026-09-03
+- Commands run: scripts/test-config.sh; scripts/test-task.sh; scripts/test-release.sh; manual seam drills (mock verbatim, unknown/traversal adapter refusal); mission injection checks; release package + activate for 0.0.5.
+- Observed result:
+  - Config suite 24/24 (adapter default/validation/env export).
+  - Task suite 24/24 including deterministic mock cases (gate pass, expect-mismatch with reason, unknown adapter fail-closed) and mission injection asserted by prompt content.
+  - Release suite 14/14; image mosaic-poc-agent:0.84.4-r0.0.5 packaged and activated via exact-marker health gate.
+  - Mission directives now flow: task -> run snapshot -> container env -> generated prompt MISSION (runtime) section.
+- Failure or correction:
+  1. Selection authority settled: load_config always exports MOSAIC_ADAPTER from config; environment overrides for scripts are therefore not a supported selection path (by design).
+  2. Selftest harness: three authoring defects fixed (helpers used before definition; one config file reused across cases leaking adapter state; a static mission fixture asserted against distinctive seam directives; plus an accidentally duplicated live block removed).
+- Credential check: no credential material in adapters, prompts, run records, or logs.
+
+## Result (M4)
+
+Adapter seam verified; harness boundary is now additive by construction. `main` merged with M4 and tagged `adapter-seam-v1`.
+
+---
+
+## Phase 9: Workspaces + capability envelope (M5)
+
+### Entry 9.1 — before
+
+- Timestamp: 2026-09-03
+- Intended action: Optional task workspace (absent / ":run" ephemeral / named persistent) and capabilities.tools allowlist (pi built-ins); runner plumbing via MOSAIC_WORKSPACE/MOSAIC_TOOLS; pi adapter maps to cwd + --tools; mock adapter logs delivered MOSAIC_* vars for deterministic assertions (Gitea #20, #21).
+- Reason: Agents that only answer text cannot do work; the workspace+tools pair is the smallest real capability step, bounded by the container.
+- Expected result: plumbing asserted via run-record stderr; live pi writes a host-visible file.
+
+### Entry 9.2 — after
+
+- Timestamp: 2026-09-03
+- Commands run: build; mock plumbing run; validate negatives; full task suite; live workspace demo.
+- Observed result: task suite 32/32; MOSAIC_WORKSPACE/MOSAIC_TOOLS asserted in run record; dataRoot/workspaces/<name> created host-side; live pi used bash to write proof.txt into the demo workspace (host-visible).
+- Failure or correction: (1) batch edit dropped SUPPORTED_TOOLS const (runtime ReferenceError, exit 1 instead of 2) — restored; (2) mock env dump used `export` which this dash prints as `export K='v'` — switched to `env`; (3) selftest fed a mismatching mock response to the plain-task case — test bug, fixed.
+
+## Phase 10: Named sessions (M6)
+
+### Entry 10.1 — before
+
+- Timestamp: 2026-09-03
+- Intended action: Optional task.session name -> persistent session dir dataRoot/sessions/<name> via pi --session-dir; resume most recent with -c when present; isolation per name; teach/recall demo fixtures (Gitea #22, #23).
+- Reason: L1 persistence is the prerequisite for any multi-step agent work.
+- Expected result: session dir populated after first run; second run recalls taught context.
+
+### Entry 10.2 — after
+
+- Timestamp: 2026-09-03
+- Commands run: build; mock plumbing run; live teach/recall E2E; task suite.
+- Observed result: task suite 32/32; teach run replied REMEMBERED and session JSONL persisted host-side; recall run resumed (-c) and answered exactly 'mosaico'; single continued session file (no duplicate sessions).
+- Failure or correction: none. Design note: ephemeral (--no-session) remains the default when no session is declared.
+
+## Phase 11: Operator ergonomics (M7)
+
+### Entry 11.1 — before
+
+- Timestamp: 2026-09-03
+- Intended action: mosaic-task.mjs show <runId> (full record + snapshots + artifacts, traversal-safe), list with workspace/session columns, RELEASE -> 0.0.6, package + health-gated activate, docs (Gitea #24).
+- Reason: Run records are only as valuable as they are inspectable; release activation closes the loop on container-content changes.
+- Expected result: show works for real/missing/traversal ids; suites green; 0.0.6 active.
+
+### Entry 11.2 — after
+
+- Timestamp: 2026-09-03
+- Commands run: build; show on real/missing/traversal ids; full sweep; release package + activate.
+- Observed result: config 24/24, task 32/32, release 14/14, verify PASS; 0.0.6 packaged and activated via exact-marker health gate.
+- Failure or correction: showRun initially rejected valid run ids (lowercase-only regex vs uppercase timestamp) and crashed on missing ids (uncaught readdir) — both fixed and covered.
+
+## Autonomous run result
+
+M5 tagged `workspace-capabilities-v1`, M6 tagged `sessions-v1`, M7 tagged `operator-ergonomics-v1`; release 0.0.6 active. Tracker: docs/plans/2026-09-03_autonomous-run.md.
+
+---
+
+## Phase 12: Conductor loop — self-orchestration (M8)
+
+### Entry 12.1 — before
+
+- Timestamp: 2026-09-03
+- Intended action: Stand up the poor-man orchestration loop per docs/plans/CONDUCTOR.md: conductor (host, holds git) mirrors the repo into a worker workspace, dispatches a headless pi worker (session worker-1, tools read/write/edit/bash) to implement retry <runId>, reviews the diff, integrates, verifies (Gitea #25, #26, #27).
+- Reason: The owner asked for circular task processing with agent workers; the stack now has every primitive needed — this proves it on the stack itself.
+- Expected result: worker-authored retry merged with suites green and a live retry verified.
+
+### Entry 12.2 — after
+
+- Timestamp: 2026-09-03
+- Commands run: repo mirror clone; worker dispatch (tasks/worker-retry.json); diff review; apply; live retry; refinement dispatch (tasks/worker-retry-refine.json); second review; reverse+reapply combined patch; conductor interpolation fix; live retry; full sweep.
+- Observed result:
+  - Worker round 1: implemented retry correctly per spec in 2m28s; diff reviewed clean.
+  - Live retry exposed a spec gap (direct invocation lacks launcher env exports).
+  - Worker round 2 (same session, 59s): made spawnEnv self-sufficient, but used PI_* names where compose interpolates MOSAIC_*.
+  - Conductor hotfix: 3-line rename to MOSAIC_PROVIDER/MOSAIC_MODEL/MOSAIC_DATA_ROOT (too trivial for a worker round).
+  - Final: live retry succeeded (replied REMEMBERED, new run recorded); all suites green.
+- Failure or correction: three rounds total — one spec gap (conductor), one naming mismatch (worker), one trivial rename (conductor). Each was caught by mechanical verification (run record stderr), never by hope.
+- Attribution: feature authored by headless pi worker (glm-5.3-flash) in sessions worker-1; conductor reviewed, integrated, and hotfixed.
+
+## Result (M8)
+
+Conductor loop proven end-to-end on the stack itself. `main` merged with M8; release 0.0.6 remains active (retry is host-side only, no image change).
+

@@ -18,11 +18,14 @@ WORKDIR /opt/app
 COPY package.json package-lock.json ./
 RUN npm ci --ignore-scripts

-# Immutable contract fixtures (required location) and runtime scripts.
+# Immutable contract fixtures (required location), runtime scripts, and
+# runtime adapters.
 COPY contracts /opt/mosaic/contracts
 COPY src /opt/mosaic/src
+COPY adapters /opt/mosaic/adapters
 RUN chmod 0555 /opt/mosaic/contracts /opt/mosaic/contracts/* \
-    && chmod 0555 /opt/mosaic/src /opt/mosaic/src/*.sh
+    && chmod 0555 /opt/mosaic/src /opt/mosaic/src/*.sh \
+    && chmod 0555 /opt/mosaic/adapters /opt/mosaic/adapters/*/adapter.sh

 # Writable state, workspace, and pi agent directory (auth.json is
 # bind-mounted read-only at runtime; nothing is copied into the image).
@@ -9,30 +9,155 @@ to return exactly `MOSAIC_HELLO_OK`.
 ## Layout

 ```text
-BRIEF.md            requirements for this experiment
+BRIEF.md            requirements for the original container proof
 BUILD-LOG.md        append-only build/verification log
 LAYERS.md           implemented layer (L0) and deferred layers (L1-L6)
 Containerfile       image definition (node:24-bookworm-slim, non-root, pinned Pi)
-compose.yaml        one service: mosaic-agent (one-shot)
+compose.yaml        one service: mosaic-agent (one-shot; configured via env)
 package.json        pins @earendil-works/pi-coding-agent at exactly 0.84.4
 package-lock.json   resolved lockfile used by npm ci in the image
-.env.example        non-secret settings only (provider, model)
+.env.example        non-secret settings only (credential-file path, env-var auth)
 contracts/          CONSTITUTION.md, STANDARDS.md, SOUL.md, USER.md (immutable fixtures)
-scripts/            build.sh, hello.sh, verify.sh, reset.sh (+ shared common.sh)
+scripts/            bootstrap/build/hello/verify/reset + config tooling
 src/                load-contracts.sh, run-agent.sh (run inside the container)
+docs/plans/         architecture and milestone plans
 ```

+## Configuration
+
+The sole discovery entry point is:
+
+```text
+~/.config/mosaic-dev/config.json
+```
+
+Created only by the explicit, idempotent bootstrap:
+
+```bash
+scripts/bootstrap.sh   # create-if-absent; validates existing config, never rewrites
+```
+
+Minimal shape (`configVersion` 1):
+
+```json
+{
+  "configVersion": 1,
+  "environment": "development",
+  "dataRoot": "/home/jwoltje/.mosaic-dev",
+  "execution": {
+    "backend": "docker",
+    "provider": "zai",
+    "model": "glm-5.3-flash"
+  }
+}
+```
+
+Rules enforced by `scripts/mosaic-config.mjs`:
+
+- Unknown keys, unsupported versions/backends, and malformed JSON exit nonzero; nothing is modified.
+- `dataRoot` must be absolute, canonical, and must not be or contain the home or configuration directory.
+- Validation failures never touch config, state, or images.
+- `scripts/test-config.sh` runs the sandboxed config selftests (no Docker required).
+
+Run paths (`build/hello/verify/reset`) fail closed when configuration is missing or invalid; they never invent it.
+
+## Missions & tasks (M2)
+
+Missions and tasks are validated JSON data (strict schemas, version-pinned). The M2 layer is host-side only: mission directives are recorded for provenance but do not yet reach the runtime system prompt (capability/policy layer comes later).
+
+```text
+missions/hello.json          objective + directives (missionVersion 1)
+tasks/hello-marker.json      prompt + optional mission ref + expectExact + timeout
+<dataRoot>/runs/r-<id>/      immutable run record: task.json, mission.json,
+                             stderr.txt, result.json (all write-once)
+```
+
+Usage:
+
+```bash
+scripts/run-task.sh validate tasks/hello-marker.json   # strict validation, writes nothing
+scripts/run-task.sh run tasks/hello-marker.json        # execute; result recorded under dataRoot/runs
+scripts/mosaic-task.mjs list                           # list runs and statuses
+scripts/test-task.sh                                   # selftests (schema negatives + live runs)
+```
+
+A run exits 0 only when its expectation is met (`expectExact` match); mismatches, nonzero agent exits, and timeouts record `status: failed` in `result.json` and exit 1. Each run gets a unique directory — rerunning never rewrites history.
+
+## Release model (M3)
+
+`RELEASE` single-sources the release version (0.0.X until declared stable); the image tag derives from it plus the pinned Pi version. Activation is health-gated and every event is recorded:
+
+```bash
+scripts/release.sh package                    # build + tag the release image
+scripts/release.sh activate                   # health check (exact marker) -> atomic pointer swap
+scripts/release.sh activate --fault-injection # prove the refusal path (drills only)
+scripts/release.sh rollback                   # health-gated return to the previous release
+scripts/release.sh status                     # release, tag, active pointer, recent log
+scripts/test-release.sh                       # release selftests
+```
+
+- `<dataRoot>/state/active.json` — the activation pointer (atomic tmp+rename replace)
+- `<dataRoot>/state/activation-log.jsonl` — append-only history: package / activate / refused / rollback
+
+A failed health check never activates; the previously active release remains deployed. Updating the software therefore cannot corrupt the running installation: package beside, gate, then flip. Verified by the update/refusal/rollback drills in BUILD-LOG Phase 7.
+
+## Runtime adapters (M4)
+
+The harness boundary is formalized: everything upstream (config, contracts, missions, tasks, run records) is harness-agnostic; everything inside an adapter belongs to one runtime.
+
+```text
+adapters/<name>/adapter.sh   env in: MOSAIC_SYSTEM_PROMPT_FILE, MOSAIC_REQUEST,
+                             MOSAIC_PROVIDER, MOSAIC_MODEL
+                             stdout: response only; stderr: diagnostics
+```
+
+- Selection: `execution.adapter` in config.json (optional; `pi` default; allowlist `pi`, `mock`)
+- `pi` — pinned Pi CLI, noninteractive print mode, ambient discovery off
+- `mock` — deterministic test adapter; never for real verification
+- Mission directives have a sanctioned injection point: when a task references a mission, the task runner mounts the run snapshot and the generated prompt gains a `MISSION (runtime)` section (objective + directives) after the four immutable contracts
+- Adding a harness (Claude, Codex, OpenCode) later means adding one directory — no orchestrator changes
+
+See `adapters/README.md` for the full contract.
+
+## Workspaces, capabilities, sessions (M5/M6)
+
+Optional task fields extend what an agent can do — all defaulting to the previous behavior:
+
+```json
+{
+  "workspace": "demo",                          // ":run" ephemeral, or persistent dataRoot/workspaces/<name>
+  "capabilities": { "tools": ["bash", "read"] }, // pi tool allowlist; absent = no tools
+  "session": "demo"                             // persistent session at dataRoot/sessions/<name>
+}
+```
+
+- The adapter runs inside the workspace; files it writes are host-visible (`dataRoot/workspaces/<name>`).
+- Sessions persist via pi's documented `--session-dir`; a follow-up run in the same session resumes the conversation (`-c`) and can recall prior context. Distinct names never share state. Ephemeral (`--no-session`) remains the default when no session is declared.
+- Selection authority: config for adapter/provider/model; the task file for workspace/capabilities/session.
+
+Inspect anything:
+
+```bash
+node scripts/mosaic-task.mjs list                # runs with task/workspace/session columns
+node scripts/mosaic-task.mjs show <runId>        # full record + snapshots + artifacts
+```
+
+Demo fixtures: `tasks/workspace-demo.json`, `tasks/session-demo-1.json` + `tasks/session-demo-2.json`.
+
+See `docs/plans/2026-09-02_atomic-mosaic-foundation.md` for the full plan.
+
 Inside the container:

 ```text
 /opt/mosaic/contracts     immutable contract files
-/var/lib/mosaic           generated runtime state (mounted from /home/jwoltje/.mosaic-dev)
+/var/lib/mosaic           generated runtime state (mounted from configured dataRoot)
 /workspace                agent workspace
 ```

 ## How it works

-1. `scripts/build.sh` builds `mosaic-poc-agent:0.84.4` with Docker Compose.
+1. `scripts/build.sh` builds the release image (`mosaic-poc-agent:<pi>-r<release>`,
+   tag derived from `RELEASE` + the pinned Pi version) with Docker Compose.
 2. On each run, `/opt/mosaic/src/load-contracts.sh` reads the four contract files
   in fixed order (CONSTITUTION, STANDARDS, SOUL, USER), joins them with clear
   separators, and writes `/var/lib/mosaic/system-prompt.md`.
@@ -48,10 +173,16 @@ Inside the container:
 ## Usage

 ```bash
-scripts/build.sh      # build the image
-scripts/hello.sh      # one-shot request; prints the model response
-scripts/verify.sh     # full gated test; exit 0 only on exact MOSAIC_HELLO_OK
-scripts/reset.sh      # delete /home/jwoltje/.mosaic-dev (safety-checked)
+scripts/bootstrap.sh   # create config.json if absent (idempotent)
+scripts/build.sh       # build the image
+scripts/hello.sh       # one-shot request; prints the model response
+scripts/verify.sh      # full gated test; exit 0 only on exact MOSAIC_HELLO_OK
+scripts/run-task.sh    # run a mission/task file (see Missions & tasks)
+scripts/release.sh     # package / activate / rollback / status (see Release model)
+scripts/test-config.sh # fast config-layer selftests (no Docker)
+scripts/test-task.sh   # mission/task selftests (schema + adapter seam + live runs)
+scripts/test-release.sh # release selftests
+scripts/reset.sh       # delete the configured data root (safety-checked)
 ```

 Prove the failure path (acceptance criterion 9):
@@ -0,0 +1 @@
+0.0.6
@@ -0,0 +1,54 @@
+# Mosaic runtime adapters
+
+An adapter is the entire harness-specific surface of the system. Everything
+upstream of an adapter — configuration, contracts, missions, tasks, run
+records — is harness-agnostic; everything inside an adapter may assume one
+specific agent runtime.
+
+## Contract
+
+An adapter lives at:
+
+```text
+/opt/mosaic/adapters/<name>/adapter.sh
+```
+
+and must be executable. The dispatcher (`/opt/mosaic/src/run-agent.sh`)
+selects it via `MOSAIC_ADAPTER` (default: `pi`) and execs it after the
+system prompt has been generated.
+
+**Inputs (environment):**
+
+| Variable | Meaning |
+|---|---|
+| `MOSAIC_SYSTEM_PROMPT_FILE` | Absolute path to the generated system prompt (contracts + optional mission section). Read it; do not modify it. |
+| `MOSAIC_REQUEST` | The exact user request text (may contain newlines). |
+| `MOSAIC_PROVIDER` | Configured provider name. |
+| `MOSAIC_MODEL` | Configured model id. |
+
+Optional, adapter-specific (documented per adapter):
+
+| Variable | Meaning |
+|---|---|
+| `MOSAIC_MOCK_RESPONSE` | mock only: the verbatim response to emit |
+
+**Outputs:**
+
+- `stdout`: the model response text — the only channel the orchestrator captures
+- `stderr`: diagnostics (never credentials)
+- exit `0`: success; nonzero: failure
+
+## Rules
+
+1. Adapters print ONLY the response on stdout. Status lines go to stderr.
+2. Adapters never read configuration files; the resolved settings arrive via environment.
+3. Adapters never write outside `/var/lib/mosaic`.
+4. Adding an adapter requires: a new directory, the contract implementation, and
+   adding the name to the allowlist in `scripts/mosaic-config.mjs`.
+
+## Included adapters
+
+- `pi` — the pinned `@earendil-works/pi-coding-agent` CLI in noninteractive
+  print mode (`-p`), ambient discovery disabled, stdin detached.
+- `mock` — deterministic echo of `MOSAIC_MOCK_RESPONSE`. Test-only: never use
+  it where a real model response is required.
@@ -0,0 +1,16 @@
+#!/bin/sh
+# Mock adapter: deterministic response for seam tests. NEVER use where a
+# real model response is required.
+#
+# Contract: see /opt/mosaic/adapters/README.md.
+set -eu
+
+[ -n "${MOSAIC_SYSTEM_PROMPT_FILE:-}" ] || { echo "mock adapter: MOSAIC_SYSTEM_PROMPT_FILE is required" >&2; exit 2; }
+[ -n "${MOSAIC_REQUEST:-}" ] || { echo "mock adapter: MOSAIC_REQUEST is required" >&2; exit 2; }
+[ -r "$MOSAIC_SYSTEM_PROMPT_FILE" ] || { echo "mock adapter: system prompt not readable: $MOSAIC_SYSTEM_PROMPT_FILE" >&2; exit 2; }
+
+echo "mock adapter: responding verbatim from MOSAIC_MOCK_RESPONSE" >&2
+# Deterministic plumbing evidence: which MOSAIC_* variables did the
+# orchestrator actually deliver? (Auth secrets are not MOSAIC_-prefixed.)
+(env | grep '^MOSAIC_' | sort) >&2 2>/dev/null || true
+printf '%s\n' "${MOSAIC_MOCK_RESPONSE:-}"
@@ -0,0 +1,55 @@
+#!/bin/sh
+# Pi adapter: implements the Mosaic adapter contract for the pinned
+# @earendil-works/pi-coding-agent CLI.
+#
+# Contract: see /opt/mosaic/adapters/README.md. stdout = response only.
+set -eu
+
+[ -n "${MOSAIC_SYSTEM_PROMPT_FILE:-}" ] || { echo "pi adapter: MOSAIC_SYSTEM_PROMPT_FILE is required" >&2; exit 2; }
+[ -n "${MOSAIC_REQUEST:-}" ] || { echo "pi adapter: MOSAIC_REQUEST is required" >&2; exit 2; }
+[ -r "$MOSAIC_SYSTEM_PROMPT_FILE" ] || { echo "pi adapter: system prompt not readable: $MOSAIC_SYSTEM_PROMPT_FILE" >&2; exit 2; }
+
+: "${PI_PROVIDER:?pi adapter: PI_PROVIDER is required}"
+: "${PI_MODEL:?pi adapter: PI_MODEL is required}"
+
+# Workspace (M5): run inside the provided workspace when present.
+if [ -n "${MOSAIC_WORKSPACE:-}" ]; then
+    mkdir -p "$MOSAIC_WORKSPACE"
+    cd "$MOSAIC_WORKSPACE"
+fi
+
+# Session (M6): persistent named session directory; resume the most recent
+# session in that directory when one exists (pi documented flags).
+# Default remains ephemeral (--no-session) when no session is declared.
+SESSION_FLAGS="--no-session"
+if [ -n "${MOSAIC_SESSION_DIR:-}" ]; then
+    mkdir -p "$MOSAIC_SESSION_DIR"
+    SESSION_FLAGS="--session-dir $MOSAIC_SESSION_DIR"
+    if [ -n "$(ls -A "$MOSAIC_SESSION_DIR" 2>/dev/null)" ]; then
+        SESSION_FLAGS="$SESSION_FLAGS -c"
+    fi
+fi
+
+# Capabilities (M5): explicit allowlist or no tools.
+TOOLS_FLAG="--no-tools"
+[ -n "${MOSAIC_TOOLS:-}" ] && TOOLS_FLAG="--tools $MOSAIC_TOOLS"
+
+# All flags documented in the pi package README (CLI Reference):
+#   -p/--print     noninteractive: print the response and exit
+#   --system-prompt  replace the default prompt with the generated one
+#   --no-*         no ambient context/skills/extensions/templates/themes
+#   --no-session   ephemeral; TOOLS_FLAG per capabilities
+#   --offline      no startup network operations (update checks/telemetry)
+exec pi \
+    --offline \
+    --no-extensions \
+    --no-skills \
+    --no-prompt-templates \
+    --no-themes \
+    --no-context-files \
+    $TOOLS_FLAG \
+    $SESSION_FLAGS \
+    --provider "$PI_PROVIDER" \
+    --model "$PI_MODEL" \
+    --system-prompt "$(cat "$MOSAIC_SYSTEM_PROMPT_FILE")" \
+    -p "$MOSAIC_REQUEST"
@@ -3,20 +3,33 @@ services:
    build:
      context: .
      dockerfile: Containerfile
-    image: mosaic-poc-agent:0.84.4
+    image: ${MOSAIC_IMAGE_TAG:?MOSAIC_IMAGE_TAG must be set by scripts/load_release (run via scripts/*.sh)}
    user: "1000:1000"
    environment:
-      # Non-secret settings (see .env.example)
-      PI_PROVIDER: ${PI_PROVIDER:-zai}
-      PI_MODEL: ${PI_MODEL:-glm-5.3-flash}
+      # Resolved from config.json by scripts/common.sh (load_config).
+      # Required: compose fails fast when the launcher did not supply them.
+      PI_PROVIDER: ${MOSAIC_PROVIDER:?MOSAIC_PROVIDER must be set by scripts/load_config (run via scripts/*.sh)}
+      PI_MODEL: ${MOSAIC_MODEL:?MOSAIC_MODEL must be set by scripts/load_config (run via scripts/*.sh)}
+      # Adapter selection (resolved from config execution.adapter; default pi)
+      MOSAIC_ADAPTER: ${MOSAIC_ADAPTER:-pi}
+      # Mission directives injection point (set by the task runner when the
+      # task references a mission; container path of the run snapshot)
+      MOSAIC_MISSION_FILE: ${MOSAIC_MISSION_FILE:-}
+      # Workspace + capabilities (set by the task runner; M5)
+      MOSAIC_WORKSPACE: ${MOSAIC_WORKSPACE:-}
+      MOSAIC_TOOLS: ${MOSAIC_TOOLS:-}
+      # Persistent named session dir (set by the task runner; M6)
+      MOSAIC_SESSION_DIR: ${MOSAIC_SESSION_DIR:-}
+      # mock adapter only: verbatim response for deterministic seam tests
+      MOSAIC_MOCK_RESPONSE: ${MOSAIC_MOCK_RESPONSE:-}
      # Documented container auth alternative: provider API key via
      # runtime environment variable. Empty by default; when empty Pi
      # falls back to the read-only mounted auth.json credential file.
      ZAI_API_KEY: ${ZAI_API_KEY:-}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
    volumes:
-      # Generated runtime state (host dir per brief)
-      - /home/jwoltje/.mosaic-dev:/var/lib/mosaic
+      # Configured runtime state root (from config.json dataRoot).
+      - ${MOSAIC_DATA_ROOT:?MOSAIC_DATA_ROOT must be set by scripts/load_config (run via scripts/*.sh)}:/var/lib/mosaic
      # Runtime credential only: pi auth file mounted READ-ONLY.
      # Never copied into the image.
      - ${PI_AUTH_FILE:-/home/jwoltje/.pi/agent/auth.json}:/home/node/.pi/agent/auth.json:ro
@@ -0,0 +1,81 @@
+# Autonomous Work Run — 2026-09-03
+
+**Status:** COMPLETED (single-session batch; see Results at bottom)
+**Constraint:** The assistant cannot run unattended. This was one long interactive session, not 12 wall-clock hours. Everything below was completed, committed, and pushed during that session.
+
+## Objective
+
+Advance the Mosaic Stack rebuild several verified layers in one batch, focused on Pi, ending in a state the owner can test and review alone: green suites, activated release, recorded drills, and this document as the single entry point.
+
+## Scope decided for this run
+
+| Milestone | Theme | Status |
+|---|---|---|
+| M5 | Task workspaces + capability envelope (tools allowlist) | DONE |
+| M6 | Named sessions — persistence and resume (L1) | DONE |
+| M7 | Operator ergonomics: run inspection commands | DONE |
+| — | Releases 0.0.5+0.0.6 packaged; 0.0.6 health-gated activated | DONE |
+
+Explicitly deferred (do not mistake for forgotten):
+- Claude/Codex/OpenCode adapters (owner: focus on Pi for now)
+- Network policy engine (container boundary is the current control)
+- Fine-grained read restrictions (excluded by the original brief)
+- Config/state migrations (no schema breaks so far; keep it that way)
+
+## Design decisions taken during this run
+
+1. **Workspace** (`task.workspace`, optional):
+   - absent → tool-free text-only run (previous behavior, unchanged)
+   - `":run"` → ephemeral per-run workspace at `<dataRoot>/runs/<runId>/workspace`
+   - named (validated id) → persistent shared workspace at `<dataRoot>/workspaces/<name>`
+   - Container path passed via `MOSAIC_WORKSPACE` env; adapter cds into it. No new mounts (dataRoot is already mounted).
+2. **Capabilities** (`task.capabilities.tools`, optional): allowlist from pi's documented tool set (`read write edit bash grep find ls`). Absent → `--no-tools` (previous behavior). Passed via `MOSAIC_TOOLS` env; pi adapter maps to `--tools`.
+3. **Adapter diagnostics for deterministic testing**: the mock adapter writes all received `MOSAIC_*` variables (never secrets — auth is not MOSAIC_-prefixed) to stderr, which lands in the run record. This lets selftests assert orchestrator→adapter plumbing without parsing model output.
+4. **Sessions** (`task.session`, optional named): persisted under `<dataRoot>/sessions/<name>/` via pi's documented `--session-dir`; resume semantics: continue most recent session in that directory when one exists (`-c`).
+5. **Selection authority unchanged**: config file for adapter/provider/model; task file for workspace/capabilities/session; env vars are internal plumbing only.
+6. **configVersion stays 1**; all new task fields are optional. Old tasks/configs remain valid.
+
+## Test plan (what "done" means per milestone)
+
+- M5: mock-adapter cases asserting workspace path and tools arrive via run-record stderr; live pi case writing/reading a file in a persistent workspace; validation negatives (bad tool name, bad workspace name)
+- M6: session directory deterministically populated after first run; second run resumes (continuation asserted by session dir state and, in live E2E, by model recall); sandbox isolation between two named sessions
+- M7: `show <runId>` prints a complete run record; `list` gains workspace/session columns
+- Final: full sweep (config/task/release), verify, package + activate 0.0.6, config checksum unchanged
+
+## Review checklist for the owner
+
+1. `cat docs/plans/2026-09-03_autonomous-run.md` (this file)
+2. `scripts/release.sh status` → 0.0.6 active
+3. `scripts/test-config.sh && scripts/test-task.sh && scripts/test-release.sh && scripts/verify.sh`
+4. Try a workspace task:
+   ```bash
+   scripts/run-task.sh run tasks/workspace-demo.json
+   ls ~/.mosaic-dev/workspaces/demo/
+   ```
+5. Try the session demo:
+   ```bash
+   scripts/run-task.sh run tasks/session-demo-1.json   # teaches a word
+   scripts/run-task.sh run tasks/session-demo-2.json   # recalls it
+   ```
+6. Inspect any run: `node scripts/mosaic-task.mjs show <runId>`
+7. Gitea: milestones M5/M6/M7 closed; issues referenced by merge commits
+
+## Results
+
+- M5 merged on `main` (merge commit `ddb1554`), tagged `workspace-capabilities-v1`
+- M6 merged on `main` (merge commit `4e2a413`), tagged `sessions-v1`
+- M7 merged on `main`, tagged `operator-ergonomics-v1`
+- Release 0.0.6 packaged, health-gated activated, full sweep green
+- Suites at end of run: config 24/24, task 32/32, release 14/14, verify PASS
+- Build log: Phases 9 (M5), 10 (M6), 11 (M7) appended with corrections
+- Corrections encountered: dropped constant from a failed atomic edit batch (SUPPORTED_TOOLS); dash `export` output format vs `env`; three selftest authoring defects; showRun id-regex case sensitivity + missing-run crash. All fixed and covered by tests.
+- Commits pushed incrementally; nothing left uncommitted
+- Live proof: workspace file host-visible; session teach/recall ('mosaico') verified
+
+## Next steps after this run (not started)
+
+1. Owner review + hands-on testing of workspaces, capabilities, sessions
+2. Decision: capability defaults per mission (mission-level policy) — natural M8
+3. Second real adapter remains available whenever wanted
+4. Consider run-record pruning/retention policy once run volume grows
+5. Consider a `mosaic-task.mjs retry <runId>` convenience for failed runs
@@ -0,0 +1,51 @@
+# Conductor protocol — poor-man orchestration loop
+
+How the stack orchestrates headless pi workers to do work on itself.
+
+## Roles
+
+| Role | Runs where | Powers | Never has |
+|---|---|---|---|
+| **Conductor** | host (assistant or owner) | git (clone/commit/push), task dispatch, review, verification suites, Gitea | nothing new |
+| **Worker** | container (headless pi via `scripts/run-task.sh`) | read/write/edit/bash inside its workspace; persistent session on request | git credentials, docker socket, host filesystem |
+
+## The loop
+
+1. **Decompose**: conductor turns a goal into worker tasks small enough to
+   specify completely in one prompt (file paths, acceptance criteria, style
+   constraints, verification the worker can run itself, e.g. `node --check`).
+2. **Mirror**: conductor maintains the repo clone at
+   `<dataRoot>/workspaces/stack-repo` (host-side git; workers see it read-write
+   through their workspace mount).
+3. **Dispatch**: `scripts/run-task.sh run <worker-task.json>` — worker edits the
+   clone. Session name `worker-<n>` keeps continuity across refinement rounds.
+4. **Extract**: `git -C <workspace> diff > patch` — the worker's entire output
+   is a reviewable diff. Run record (result.json, stderr.txt) is the receipt.
+5. **Review**: conductor reads the diff line by line. Bad output → refine the
+   prompt, re-dispatch (same session: "your patch had these problems…").
+6. **Integrate**: conductor applies the patch to the real repo, runs the full
+   suites, commits and pushes. Suites failing → revert apply, back to step 5.
+7. **Record**: update CURRENT.md, BUILD-LOG, close the Gitea issue.
+
+## Guardrails
+
+- Workers never receive credentials; they never run git; they never leave the
+  workspace (container is the boundary; tools allowlist is the gate).
+- Every worker diff is reviewed by the conductor before integration. No
+  auto-apply. (Auto-apply would be a capability-policy decision for later.)
+- Verification is mechanical: suites + `node --check` / `bash -n` gates.
+- Recursive decomposition = "fail → smaller task", never "hope."
+
+## Worker task template
+
+```json
+{
+  "taskVersion": 1,
+  "id": "t-worker-<name>",
+  "prompt": "<full spec: goal, files, constraints, acceptance, self-checks>",
+  "workspace": "stack-repo",
+  "capabilities": { "tools": ["read", "write", "edit", "bash"] },
+  "session": "worker-1",
+  "timeoutSeconds": 600
+}
+```
@@ -0,0 +1,33 @@
+# CURRENT — single source of "what happens next"
+
+This file always names exactly one next action. Any "continue" / "next" /
+"proceed" message means: execute the action below, fully (implement → test →
+verify against its acceptance criteria → commit → push → close the issue →
+update this file to the next action). No ambiguity, no re-planning.
+
+## Next action
+
+Gitea issue: (none queued — awaiting owner direction)
+
+## Queue (ordered, not started)
+
+1. Owner review of M5–M8 (workspaces, capabilities, sessions, conductor loop)
+2. M8 follow-up: retry lineage (retriedFrom field) + relative-mission-path retry limitation
+3. M9 candidates: mission-level capability policy; run-record retention; decision on auto-apply policy for worker patches
+
+## Rules
+
+- One action in flight. Update this file at the END of every action.
+- Blocked? Move the item to "Blocked" below with the reason and stop.
+- Completed actions move to the log at the bottom (date + issue + result).
+
+## Blocked
+
+(none)
+
+## Completed log
+
+- 2026-09-03 — M5 workspaces + capability envelope (#20, #21) — merged, tests green
+- 2026-09-03 — M6 named sessions + resume (#22, #23) — merged, teach/recall verified
+- 2026-09-03 — M7 run inspection + release 0.0.6 (#24) — merged, activated
+- 2026-09-03 — M8 conductor loop + worker-built retry (#25, #26, #27) — merged; worker authored retry in 2 refinement rounds, conductor fixed a 3-line interpolation rename; live retry verified
@@ -0,0 +1,9 @@
+{
+  "missionVersion": 1,
+  "id": "m-hello",
+  "objective": "Prove the startup marker path of the mosaic-poc-agent.",
+  "directives": [
+    "Startup verification requests are answered with the marker only.",
+    "No explanation, no formatting."
+  ]
+}
@@ -1,6 +1,6 @@
 {
  "name": "mosaic-stack-dev-test",
-  "version": "0.1.0",
+  "version": "0.0.3",
  "private": true,
  "description": "Minimal Mosaic Stack container proof of concept: one Pi agent, four local contract files, one real model request returning MOSAIC_HELLO_OK.",
  "license": "UNLICENSED",
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Explicit, idempotent configuration bootstrap.
+#
+# Creates ~/.config/mosaic-dev/config.json (or $MOSAIC_CONFIG) only when
+# absent. An existing configuration is validated, never modified.
+# Normal run paths (build/hello/verify) deliberately do NOT auto-bootstrap:
+# missing configuration is an error there, not something to invent.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+exec node scripts/mosaic-config.mjs bootstrap
@@ -5,6 +5,9 @@ cd "$(dirname "$0")/.."
 # shellcheck source=common.sh
 source scripts/common.sh

+load_config
+load_release
+
 bootstrap_runtime_dir

 docker compose build
@@ -1,13 +1,51 @@
-# Shared helpers for the POC host scripts. Not a documented entry point.
+# Shared helpers for the Mosaic host scripts. Not a documented entry point.

-MOSAIC_DEV_DIR="/home/jwoltje/.mosaic-dev"
 POC_ROOT_MARKER=".mosaic-poc-root"

-# Ensure the runtime state directory exists and carries this project's
-# ownership marker. The marker is what scripts/reset.sh requires before
-# it will delete anything.
+# Load and validate the Mosaic configuration (config.json), exporting
+# MOSAIC_DATA_ROOT, MOSAIC_PROVIDER, and MOSAIC_MODEL.
+#
+# Fails closed: a missing or invalid configuration aborts the calling
+# script before any container or filesystem mutation. Run paths never
+# auto-bootstrap; use scripts/bootstrap.sh explicitly.
+load_config() {
+    local config_env
+    if ! config_env="$(node scripts/mosaic-config.mjs env)"; then
+        echo "common: configuration load failed" >&2
+        exit 1
+    fi
+    eval "$config_env"
+    export MOSAIC_DATA_ROOT MOSAIC_PROVIDER MOSAIC_MODEL MOSAIC_ADAPTER
+    MOSAIC_DEV_DIR="$MOSAIC_DATA_ROOT"
+}
+
+# Resolve the release identity: RELEASE is the single source of the
+# release version (stays 0.0.X until declared stable); the image tag
+# derives from it plus the pinned pi dependency version.
+load_release() {
+    local release pi_version
+    release="$(tr -d '[:space:]' < RELEASE)"
+    if ! printf '%s' "$release" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+        echo "common: RELEASE must be a semver-ish version, got: '$release'" >&2
+        exit 1
+    fi
+    pi_version="$(node -p "require('./package.json').dependencies['@earendil-works/pi-coding-agent']")"
+    export MOSAIC_RELEASE="$release"
+    export MOSAIC_IMAGE_TAG="mosaic-poc-agent:${pi_version}-r${release}"
+}
+
+# Ensure the configured runtime data directory exists and carries this
+# project's ownership marker. The marker is what scripts/reset.sh requires
+# before it will delete anything.
 bootstrap_runtime_dir() {
-    if [ ! -d "$MOSAIC_DEV_DIR" ]; then
+    if [ -d "$MOSAIC_DEV_DIR" ]; then
+        if [ ! -w "$MOSAIC_DEV_DIR" ] || [ ! -x "$MOSAIC_DEV_DIR" ]; then
+            echo "bootstrap: $MOSAIC_DEV_DIR exists but is not writable by $(id -un)" >&2
+            echo "bootstrap: a root-owned directory here is usually leftover from a" >&2
+            echo "bootstrap: Docker-created mount source; remove it and rerun." >&2
+            exit 1
+        fi
+    else
        mkdir -p "$MOSAIC_DEV_DIR"
        echo "bootstrap: created $MOSAIC_DEV_DIR"
    fi
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Minimal Gitea API client for this repository.
+#
+# Usage: scripts/gitea-api.sh METHOD api/path [json-body]
+#   e.g. scripts/gitea-api.sh GET repos/mosaicstack/stack-v2/issues
+#
+# Security:
+#   - Reads credentials from ~/secrets/mosaic.gitea.json (or
+#     MOSAIC_GITEA_CREDENTIAL_FILE); file must be 0600, non-symlink.
+#   - Token is passed to curl via a config stream (never argv, never disk,
+#     never stdout/stderr).
+#   - Prints the response body on stdout and "HTTP <code>" on stderr.
+#     Exits nonzero when the API reports an error.
+set -euo pipefail
+
+METHOD="${1:?usage: gitea-api.sh METHOD api/path [json-body]}"
+API_PATH="${2:?missing api/path}"
+API_PATH="${API_PATH#/}"
+BODY="${3:-}"
+
+command -v curl >/dev/null || { echo "gitea-api: curl not found" >&2; exit 1; }
+command -v node >/dev/null || { echo "gitea-api: node not found" >&2; exit 1; }
+
+export MOSAIC_GITEA_CREDENTIAL_FILE="${MOSAIC_GITEA_CREDENTIAL_FILE:-$HOME/secrets/mosaic.gitea.json}"
+
+# Validate credential file; emit only the non-secret base URL on stdout.
+BASE="$(node -e '
+const fs = require("fs");
+const p = process.env.MOSAIC_GITEA_CREDENTIAL_FILE;
+let s;
+try { s = fs.lstatSync(p); } catch { process.exit(3); }
+if (!s.isFile() || s.isSymbolicLink() || (s.mode & 0o077) !== 0) process.exit(3);
+let e;
+try { e = JSON.parse(fs.readFileSync(p, "utf8")).mosaicstack || {}; } catch { process.exit(3); }
+const base = String(e.url || "").replace(/\/+$/, "");
+if (!/^https:\/\/git\.mosaicstack\.dev$/.test(base)) process.exit(3);
+if (typeof e.api_token !== "string" || e.api_token.length === 0) process.exit(3);
+process.stdout.write(base);
+')"
+
+# Repo path from the configured origin remote (never from credentials).
+REMOTE_URL="$(git remote get-url origin)"
+REPO_PATH="${REMOTE_URL#https://git.mosaicstack.dev/}"
+REPO_PATH="${REPO_PATH%.git}"
+
+# curl config stream: auth header via fd, never argv.
+gen_curl_cfg() {
+  node -e '
+const fs = require("fs");
+const e = JSON.parse(fs.readFileSync(process.env.MOSAIC_GITEA_CREDENTIAL_FILE, "utf8")).mosaicstack || {};
+process.stdout.write("header = \"Authorization: token " + e.api_token + "\"\n");
+process.stdout.write("header = \"Content-Type: application/json\"\n");
+'
+}
+
+BODY_FILE=""
+cleanup() { [ -n "$BODY_FILE" ] && rm -f "$BODY_FILE"; }
+trap cleanup EXIT
+if [ -n "$BODY" ]; then
+  BODY_FILE="$(mktemp)"
+  chmod 600 "$BODY_FILE"
+  printf '%s' "$BODY" > "$BODY_FILE"
+fi
+
+URL="$BASE/api/v1/$API_PATH"
+if [ -n "$BODY_FILE" ]; then
+  HTTP_CODE="$(curl -sS -K <(gen_curl_cfg) -o /tmp/gitea-api-response.$$ \
+    -w '%{http_code}' -X "$METHOD" "$URL" --data-binary @"$BODY_FILE")" || {
+    echo "gitea-api: request failed" >&2; exit 1; }
+else
+  HTTP_CODE="$(curl -sS -K <(gen_curl_cfg) -o /tmp/gitea-api-response.$$ \
+    -w '%{http_code}' -X "$METHOD" "$URL")" || {
+    echo "gitea-api: request failed" >&2; exit 1; }
+fi
+
+cat /tmp/gitea-api-response.$$ 2>/dev/null || true
+rm -f /tmp/gitea-api-response.$$
+echo "HTTP $HTTP_CODE" >&2
+
+case "$HTTP_CODE" in
+  2*) exit 0 ;;
+  *) echo "gitea-api: $METHOD $API_PATH failed (HTTP $HTTP_CODE)" >&2; exit 1 ;;
+esac
@@ -10,8 +10,14 @@ cd "$(dirname "$0")/.."
 # shellcheck source=common.sh
 source scripts/common.sh

+load_config
+load_release
+
 bootstrap_runtime_dir

 # -T: no pseudo-TTY, so stdout is clean model output.
+# </dev/null: detach stdin. Pi's print mode reads piped stdin until EOF;
+# an interactive terminal would otherwise block it forever. The request
+# text comes from the compose command, not stdin, so nothing is lost.
 # Errors, if any, go to stderr for diagnostics.
-docker compose run --rm -T mosaic-agent
+docker compose run --rm -T mosaic-agent < /dev/null
@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Mosaic development configuration: bootstrap, validate, resolve.
+ *
+ * Operations:
+ *   bootstrap  Create the default config ONLY if absent; otherwise validate
+ *              the existing file without writing (idempotent).
+ *   validate   Load and strictly validate; print resolved config on stdout.
+ *   env        Print shell-safe exports for launcher scripts:
+ *              MOSAIC_DATA_ROOT, MOSAIC_PROVIDER, MOSAIC_MODEL.
+ *
+ * Config location: $MOSAIC_CONFIG or ~/.config/mosaic-dev/config.json
+ *
+ * Exit codes:
+ *   0 success
+ *   2 configuration exists but is invalid (never modified by this tool)
+ *   3 configuration is missing for a read operation (validate/env)
+ *
+ * Invariants (docs/plans/2026-09-02_atomic-mosaic-foundation.md):
+ *   - Existing configuration is never overwritten.
+ *   - Validation failure modifies nothing.
+ *   - Secrets are never stored in configuration.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+const SUPPORTED_CONFIG_VERSION = 1;
+const SUPPORTED_ENVIRONMENTS = new Set(["development", "production"]);
+const SUPPORTED_BACKENDS = new Set(["docker"]);
+const SUPPORTED_ADAPTERS = new Set(["pi", "mock"]); // mock: test-only, see adapters/README.md
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/;
+
+function fail(exitCode, message) {
+  process.stderr.write(`mosaic-config: ${message}\n`);
+  process.exit(exitCode);
+}
+
+function configPath() {
+  return process.env.MOSAIC_CONFIG
+    ? path.resolve(process.env.MOSAIC_CONFIG)
+    : path.join(os.homedir(), ".config", "mosaic-dev", "config.json");
+}
+
+function readRaw(file) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch {
+    return null; // missing
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    fail(2, `configuration path must be a regular, non-symbolic-link file: ${file}`);
+  }
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    fail(2, `configuration file is not readable: ${file}`);
+  }
+}
+
+function rejectUnknownKeys(object, allowed, where) {
+  for (const key of Object.keys(object)) {
+    if (!allowed.includes(key)) {
+      fail(2, `unsupported ${where} key: "${key}"`);
+    }
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateDataRoot(value, file) {
+  if (typeof value !== "string" || value.length === 0) {
+    fail(2, 'execution "dataRoot" must be a non-empty string');
+  }
+  if (value.includes("\0")) {
+    fail(2, 'execution "dataRoot" contains a NUL byte');
+  }
+  if (!path.isAbsolute(value)) {
+    fail(2, `execution "dataRoot" must be an absolute path (got "${value}")`);
+  }
+  const resolved = path.resolve(value);
+  if (resolved !== value) {
+    fail(2, `execution "dataRoot" must be canonical without ".", "..", trailing slashes, or redundant separators (got "${value}")`);
+  }
+  if (resolved === path.parse(resolved).root) {
+    fail(2, 'execution "dataRoot" must not be the filesystem root');
+  }
+  const home = path.resolve(os.homedir());
+  if (resolved === home || isAncestorOf(resolved, home)) {
+    fail(2, `execution "dataRoot" must not be or contain the home directory (${home})`);
+  }
+  const configDir = path.dirname(path.resolve(file));
+  if (resolved === configDir || isAncestorOf(resolved, configDir)) {
+    fail(2, `execution "dataRoot" must not be or contain the configuration directory (${configDir})`);
+  }
+  return resolved;
+}
+
+function isAncestorOf(ancestor, candidate) {
+  const rel = path.relative(ancestor, candidate);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+function validate(document, file) {
+  if (!isPlainObject(document)) {
+    fail(2, "configuration must be a JSON object");
+  }
+  rejectUnknownKeys(
+    document,
+    ["configVersion", "environment", "dataRoot", "execution"],
+    "configuration",
+  );
+
+  if (document.configVersion !== SUPPORTED_CONFIG_VERSION) {
+    fail(2, `unsupported configVersion: ${JSON.stringify(document.configVersion)} (supported: ${SUPPORTED_CONFIG_VERSION})`);
+  }
+  if (!SUPPORTED_ENVIRONMENTS.has(document.environment)) {
+    fail(2, `unsupported environment: ${JSON.stringify(document.environment)} (supported: ${[...SUPPORTED_ENVIRONMENTS].join(", ")})`);
+  }
+
+  const dataRoot = validateDataRoot(document.dataRoot, file);
+
+  if (!isPlainObject(document.execution)) {
+    fail(2, '"execution" must be a JSON object');
+  }
+  rejectUnknownKeys(document.execution, ["backend", "provider", "model", "adapter"], '"execution"');
+  if (!SUPPORTED_BACKENDS.has(document.execution.backend)) {
+    fail(2, `unsupported execution.backend: ${JSON.stringify(document.execution.backend)} (supported: ${[...SUPPORTED_BACKENDS].join(", ")})`);
+  }
+  for (const key of ["provider", "model"]) {
+    const value = document.execution[key];
+    if (typeof value !== "string" || !NAME_PATTERN.test(value)) {
+      fail(2, `execution.${key} must match ${NAME_PATTERN} (got ${JSON.stringify(value)})`);
+    }
+  }
+
+  const adapter = document.execution.adapter === undefined || document.execution.adapter === null
+    ? "pi"
+    : document.execution.adapter;
+  if (typeof adapter !== "string" || !SUPPORTED_ADAPTERS.has(adapter)) {
+    fail(2, `unsupported execution.adapter: ${JSON.stringify(adapter)} (supported: ${[...SUPPORTED_ADAPTERS].join(", ")})`);
+  }
+
+  return {
+    configVersion: document.configVersion,
+    environment: document.environment,
+    dataRoot,
+    execution: {
+      backend: document.execution.backend,
+      provider: document.execution.provider,
+      model: document.execution.model,
+      adapter,
+    },
+  };
+}
+
+function load(file) {
+  const raw = readRaw(file);
+  if (raw === null) {
+    fail(3, `configuration not found: ${file} (run scripts/bootstrap.sh to create it)`);
+  }
+  let document;
+  try {
+    document = JSON.parse(raw);
+  } catch (error) {
+    fail(2, `configuration is not valid JSON (${file}): ${error.message}`);
+  }
+  return validate(document, file);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+const DEFAULT_CONFIG = {
+  configVersion: 1,
+  environment: "development",
+  dataRoot: path.join(os.homedir(), ".mosaic-dev"),
+  execution: {
+    backend: "docker",
+    provider: "zai",
+    model: "glm-5.3-flash",
+  },
+};
+
+const operation = process.argv[2];
+const file = configPath();
+
+switch (operation) {
+  case "bootstrap": {
+    if (fs.existsSync(file)) {
+      load(file); // validate only; never rewrite
+      process.stderr.write(`mosaic-config: configuration already present, validated without changes: ${file}\n`);
+      process.exit(0);
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let fd;
+    try {
+      // 'wx': creation is exclusive; an existing file is never overwritten.
+      fd = fs.openSync(file, "wx", 0o644);
+      fs.writeFileSync(fd, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`);
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        load(file);
+        process.exit(0);
+      }
+      fail(1, `unable to create configuration: ${error.message}`);
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+    load(file);
+    process.stderr.write(`mosaic-config: created default configuration: ${file}\n`);
+    process.exit(0);
+  }
+
+  case "validate": {
+    const resolved = load(file);
+    process.stdout.write(`${JSON.stringify(resolved, null, 2)}\n`);
+    process.exit(0);
+  }
+
+  case "env": {
+    const resolved = load(file);
+    process.stdout.write(
+      [
+        `MOSAIC_DATA_ROOT=${shellQuote(resolved.dataRoot)}`,
+        `MOSAIC_PROVIDER=${shellQuote(resolved.execution.provider)}`,
+        `MOSAIC_MODEL=${shellQuote(resolved.execution.model)}`,
+        `MOSAIC_ADAPTER=${shellQuote(resolved.execution.adapter)}`,
+        "",
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+
+  default:
+    fail(1, `unknown operation: ${JSON.stringify(operation ?? "")} (expected bootstrap | validate | env)`);
+}
@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+/**
+ * Mosaic mission/task layer (M2, host-side only).
+ *
+ * Operations:
+ *   validate <file>   Strictly validate a task (and its referenced mission);
+ *                     print the resolved task on success. Writes nothing.
+ *   run <taskFile>    Execute the task through the config-driven container
+ *                     path; record an immutable run under <dataRoot>/runs/.
+ *   list              List runs recorded under <dataRoot>/runs/.
+ *
+ * Exit codes:
+ *   0 success (run: status "succeeded")
+ *   1 run failed (mismatch, nonzero exit, timeout) — result.json still written
+ *   2 invalid task/mission data
+ *   3 configuration problem
+ *   4 file/environment problem
+ *
+ * M2 scope: mission directives are validated and snapshotted into run
+ * records for provenance; they are NOT yet injected into the runtime
+ * system prompt (capability/policy layer comes later).
+ *
+ * Invariants carried over from the configuration layer:
+ *   - Strict schemas; unknown keys rejected; versions pinned at 1.
+ *   - Validation never writes.
+ *   - Run records are write-once and never rewritten by a later run.
+ *   - No secrets in mission/task data or run records.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const RUNS_DIRNAME = "runs";
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const DEFAULT_TIMEOUT_SECONDS = 120;
+const SUPPORTED_TOOLS = ["read", "write", "edit", "bash", "grep", "find", "ls"]; // pi documented built-ins
+
+function fail(exitCode, message) {
+  process.stderr.write(`mosaic-task: ${message}\n`);
+  process.exit(exitCode);
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function rejectUnknownKeys(object, allowed, where) {
+  for (const key of Object.keys(object)) {
+    if (!allowed.includes(key)) fail(2, `unsupported ${where} key: "${key}"`);
+  }
+}
+
+function readJsonFile(file, what) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch {
+    fail(4, `${what} not found: ${file}`);
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    fail(4, `${what} must be a regular, non-symbolic-link file: ${file}`);
+  }
+  let document;
+  try {
+    document = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    fail(2, `${what} is not valid JSON (${file}): ${error.message}`);
+  }
+  return document;
+}
+
+function validateId(value, what) {
+  if (typeof value !== "string" || !ID_PATTERN.test(value)) {
+    fail(2, `${what} must match ${ID_PATTERN} (got ${JSON.stringify(value)})`);
+  }
+  return value;
+}
+
+function validateMission(document, file) {
+  if (!isPlainObject(document)) fail(2, "mission must be a JSON object");
+  rejectUnknownKeys(document, ["missionVersion", "id", "objective", "directives"], "mission");
+  if (document.missionVersion !== 1) {
+    fail(2, `unsupported missionVersion: ${JSON.stringify(document.missionVersion)} (supported: 1)`);
+  }
+  validateId(document.id, "mission id");
+  if (typeof document.objective !== "string" || document.objective.trim().length === 0 || document.objective.length > 4000) {
+    fail(2, "mission objective must be a non-empty string of at most 4000 characters");
+  }
+  let directives = [];
+  if (document.directives !== undefined) {
+    if (!Array.isArray(document.directives)) fail(2, "mission directives must be an array of strings");
+    directives = document.directives.map((d, i) => {
+      if (typeof d !== "string" || d.trim().length === 0 || d.length > 2000 || d.includes("\0")) {
+        fail(2, `mission directive ${i} must be a non-empty string of at most 2000 characters`);
+      }
+      return d;
+    });
+  }
+  return { missionVersion: document.missionVersion, id: document.id, objective: document.objective, directives };
+}
+
+function validateTask(document, file) {
+  if (!isPlainObject(document)) fail(2, "task must be a JSON object");
+  rejectUnknownKeys(document, ["taskVersion", "id", "prompt", "mission", "expectExact", "timeoutSeconds", "workspace", "capabilities", "session"], "task");
+  if (document.taskVersion !== 1) {
+    fail(2, `unsupported taskVersion: ${JSON.stringify(document.taskVersion)} (supported: 1)`);
+  }
+  validateId(document.id, "task id");
+
+  if (typeof document.prompt !== "string" || document.prompt.length === 0 || document.prompt.length > 20000 || document.prompt.includes("\0")) {
+    fail(2, "task prompt must be a non-empty string of at most 20000 characters");
+  }
+
+  let mission = null;
+  let missionId = null;
+  let missionSnapshot = null;
+  if (document.mission !== undefined && document.mission !== null) {
+    if (typeof document.mission !== "string" || document.mission.length === 0) {
+      fail(2, 'task "mission" must be a path string when present');
+    }
+    const missionPath = path.resolve(path.dirname(path.resolve(file)), document.mission);
+    missionSnapshot = validateMission(readJsonFile(missionPath, "mission file"), missionPath);
+    mission = document.mission;
+    missionId = missionSnapshot.id;
+  }
+
+  let expectExact = null;
+  if (document.expectExact !== undefined && document.expectExact !== null) {
+    if (typeof document.expectExact !== "string" || document.expectExact.length === 0 || document.expectExact.length > 500 || /[^\P{C}\t\n]/u.test(document.expectExact)) {
+      fail(2, "task expectExact must be a non-empty string of at most 500 characters without control characters (tab/newline allowed)");
+    }
+    expectExact = document.expectExact;
+  }
+
+  let timeoutSeconds = DEFAULT_TIMEOUT_SECONDS;
+  if (document.timeoutSeconds !== undefined && document.timeoutSeconds !== null) {
+    if (!Number.isInteger(document.timeoutSeconds) || document.timeoutSeconds < 5 || document.timeoutSeconds > 600) {
+      fail(2, "task timeoutSeconds must be an integer between 5 and 600");
+    }
+    timeoutSeconds = document.timeoutSeconds;
+  }
+
+  // Workspace (M5): absent = none; ":run" = ephemeral per-run; otherwise a
+  // persistent named workspace under <dataRoot>/workspaces/<name>.
+  let workspace = null;
+  if (document.workspace !== undefined && document.workspace !== null) {
+    if (typeof document.workspace !== "string" || document.workspace.length === 0) {
+      fail(2, 'task "workspace" must be a non-empty string when present');
+    }
+    if (document.workspace !== ":run") {
+      validateId(document.workspace, "task workspace");
+    }
+    workspace = document.workspace;
+  }
+
+  // Session (M6): optional named persistent session under
+  // <dataRoot>/sessions/<name>. Distinct names never share state.
+  let session = null;
+  if (document.session !== undefined && document.session !== null) {
+    if (typeof document.session !== "string" || document.session.length === 0) {
+      fail(2, 'task "session" must be a non-empty string when present');
+    }
+    validateId(document.session, "task session");
+    session = document.session;
+  }
+
+  // Capabilities (M5): optional tools allowlist mapped by adapters to their
+  // native permission flags. Absent = no tools.
+  let tools = null;
+  if (document.capabilities !== undefined && document.capabilities !== null) {
+    if (!isPlainObject(document.capabilities)) fail(2, '"capabilities" must be a JSON object');
+    rejectUnknownKeys(document.capabilities, ["tools"], '"capabilities"');
+    if (!Array.isArray(document.capabilities.tools) || document.capabilities.tools.length === 0) {
+      fail(2, '"capabilities.tools" must be a non-empty array of tool names');
+    }
+    const seen = new Set();
+    for (const tool of document.capabilities.tools) {
+      if (!SUPPORTED_TOOLS.includes(tool)) {
+        fail(2, `unsupported tool: ${JSON.stringify(tool)} (supported: ${SUPPORTED_TOOLS.join(", ")})`);
+      }
+      if (seen.has(tool)) fail(2, `duplicate tool in capabilities.tools: ${tool}`);
+      seen.add(tool);
+    }
+    tools = [...seen];
+  }
+
+  return {
+    taskVersion: document.taskVersion,
+    id: document.id,
+    prompt: document.prompt,
+    mission,
+    missionId,
+    missionSnapshot,
+    expectExact,
+    timeoutSeconds,
+    workspace,
+    tools,
+    session,
+  };
+}
+
+function loadConfig() {
+  const proc = spawnSync(process.execPath, [path.join(PROJECT_ROOT, "scripts", "mosaic-config.mjs"), "validate"], {
+    cwd: PROJECT_ROOT,
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024,
+  });
+  if (proc.status !== 0) {
+    fail(3, `configuration problem (exit ${proc.status}); run scripts/bootstrap.sh or fix config.json`);
+  }
+  return JSON.parse(proc.stdout);
+}
+
+function runsRoot(resolvedConfig) {
+  return path.join(resolvedConfig.dataRoot, RUNS_DIRNAME);
+}
+
+function utcStamp() {
+  return new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+
+function writeOnce(file, content) {
+  const fd = fs.openSync(file, "wx", 0o644); // exclusive: never overwrite
+  try {
+    fs.writeFileSync(fd, content);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function runTask(taskFile) {
+  const resolved = JSON.parse(
+    spawnSync(process.execPath, [path.join(PROJECT_ROOT, "scripts", "mosaic-config.mjs"), "validate"], {
+      cwd: PROJECT_ROOT,
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024,
+    }).stdout,
+  );
+
+  const task = validateTask(readJsonFile(taskFile, "task file"), path.resolve(taskFile));
+  const runId = `r-${utcStamp()}-${randomBytes(3).toString("hex")}`;
+  const runDir = path.join(runsRoot(resolved), runId);
+
+  fs.mkdirSync(runDir, { recursive: true });
+
+  // Immutable input snapshots (evidence of exactly what was executed).
+  const rawTask = fs.readFileSync(path.resolve(taskFile), "utf8");
+  writeOnce(path.join(runDir, "task.json"), rawTask);
+  if (task.missionSnapshot) {
+    const missionPath = path.resolve(path.dirname(path.resolve(taskFile)), task.mission);
+    writeOnce(path.join(runDir, "mission.json"), fs.readFileSync(missionPath, "utf8"));
+  }
+
+  const startedAt = new Date();
+  const stderrFile = path.join(runDir, "stderr.txt");
+
+  // Sanctioned mission injection: point the container at the run snapshot's
+  // CONTAINER path (dataRoot maps to /var/lib/mosaic in the image).
+  const spawnEnv = { ...process.env };
+  spawnEnv.MOSAIC_ADAPTER = resolved.execution.adapter;
+  // Self-sufficient env: direct invocation (e.g. `retry`) skips the shell
+  // launcher exports, so derive them from the resolved config and release.
+  // (Names here are the compose interpolation consumers, not PI_*.)
+  spawnEnv.MOSAIC_PROVIDER = resolved.execution.provider;
+  spawnEnv.MOSAIC_MODEL = resolved.execution.model;
+  spawnEnv.MOSAIC_DATA_ROOT = resolved.dataRoot;
+  const release = fs.readFileSync(path.join(PROJECT_ROOT, "RELEASE"), "utf8").trim();
+  const piVersion = JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, "package.json"), "utf8")).dependencies["@earendil-works/pi-coding-agent"];
+  spawnEnv.MOSAIC_IMAGE_TAG = `mosaic-poc-agent:${piVersion}-r${release}`;
+  if (task.missionSnapshot) {
+    const relative = path.relative(resolved.dataRoot, runDir);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+      fail(4, `run directory is outside the configured dataRoot: ${runDir}`);
+    }
+    spawnEnv.MOSAIC_MISSION_FILE = `/var/lib/mosaic/${relative.split(path.sep).join("/")}/mission.json`;
+  }
+
+  // Workspace (M5): create host-side, pass the CONTAINER path.
+  let workspaceContainerPath = null;
+  if (task.workspace === ":run") {
+    fs.mkdirSync(path.join(runDir, "workspace"), { recursive: true });
+    workspaceContainerPath = `/var/lib/mosaic/runs/${runId}/workspace`;
+  } else if (task.workspace) {
+    fs.mkdirSync(path.join(resolved.dataRoot, "workspaces", task.workspace), { recursive: true });
+    workspaceContainerPath = `/var/lib/mosaic/workspaces/${task.workspace}`;
+  }
+  if (workspaceContainerPath) spawnEnv.MOSAIC_WORKSPACE = workspaceContainerPath;
+  spawnEnv.MOSAIC_TOOLS = task.tools ? task.tools.join(",") : "";
+
+  // Session (M6): persistent named session dir, passed as container path.
+  if (task.session) {
+    fs.mkdirSync(path.join(resolved.dataRoot, "sessions", task.session), { recursive: true });
+    spawnEnv.MOSAIC_SESSION_DIR = `/var/lib/mosaic/sessions/${task.session}`;
+  }
+
+  const proc = spawnSync(
+    "docker",
+    ["compose", "run", "--rm", "-T", "mosaic-agent", task.prompt],
+    {
+      cwd: PROJECT_ROOT,
+      env: spawnEnv,
+      input: "", // stdin detached: print mode must never wait on a terminal (see issue #5)
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+      timeout: task.timeoutSeconds * 1000,
+      killSignal: "SIGKILL",
+    },
+  );
+  const finishedAt = new Date();
+
+  fs.writeFileSync(stderrFile, proc.stderr ?? "", { flag: "wx" });
+
+  const response = (proc.stdout ?? "").replace(/^[^\S\n]+/, "").replace(/[^\S\n]+$/, "").trim();
+  let status = "succeeded";
+  let reason = null;
+  let expected = task.expectExact;
+
+  if (proc.error && proc.error.code === "ETIMEDOUT") {
+    status = "failed";
+    reason = "timeout";
+  } else if (proc.error) {
+    status = "failed";
+    reason = `spawn-error: ${proc.error.code ?? proc.error.message}`;
+  } else if (proc.status !== 0) {
+    status = "failed";
+    reason = "exit-nonzero";
+  } else if (expected !== null && response !== expected) {
+    status = "failed";
+    reason = "expect-mismatch";
+  }
+
+  const result = {
+    runVersion: 1,
+    runId,
+    taskId: task.id,
+    missionId: task.missionId,
+    status,
+    reason,
+    request: task.prompt,
+    response,
+    expectedExact: expected,
+    workspace: task.workspace,
+    tools: task.tools,
+    session: task.session,
+    exitCode: proc.status,
+    signal: proc.signal ?? null,
+    provider: resolved.execution.provider,
+    model: resolved.execution.model,
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    durationMs: finishedAt.getTime() - startedAt.getTime(),
+  };
+
+  writeOnce(path.join(runDir, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
+
+  process.stdout.write(`run: ${runId}\nstatus: ${status}${reason ? ` (${reason})` : ""}\nresponse: ${response}\n`);
+  process.exit(status === "succeeded" ? 0 : 1);
+}
+
+function listRuns() {
+  const resolved = loadConfig();
+  const root = runsRoot(resolved);
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root).filter((name) => name.startsWith("r-")).sort();
+  } catch {
+    // No runs yet.
+  }
+  for (const runId of entries) {
+    let status = "unknown";
+    let taskId = "-";
+    let workspace = "-";
+    let session = "-";
+    try {
+      const result = JSON.parse(fs.readFileSync(path.join(root, runId, "result.json"), "utf8"));
+      status = result.status;
+      taskId = result.taskId;
+      workspace = result.workspace ?? "-";
+      session = result.session ?? "-";
+    } catch {
+      // Incomplete run record; report as unknown.
+    }
+    process.stdout.write(`${runId}  ${status.padEnd(9)}  task=${taskId.padEnd(18)} ws=${String(workspace).padEnd(10)} session=${session}\n`);
+  }
+}
+
+function showRun(runId) {
+  if (!/^r-[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(runId)) {
+    fail(4, `invalid run id: ${JSON.stringify(runId)} (expected r-<id>)`);
+  }
+  const resolved = loadConfig();
+  const dir = path.join(runsRoot(resolved), runId);
+  if (!fs.existsSync(dir)) {
+    fail(4, `run not found: ${runId} (under ${runsRoot(resolved)})`);
+  }
+
+  const read = (name) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+    } catch {
+      return null;
+    }
+  };
+  const result = read("result.json");
+  const task = read("task.json");
+  const mission = read("mission.json");
+
+  process.stdout.write(`run:       ${runId}\n`);
+  if (result) {
+    process.stdout.write(
+      [
+        `status:    ${result.status}${result.reason ? ` (${result.reason})` : ""}`,
+        `task:      ${result.taskId}`,
+        result.missionId ? `mission:   ${result.missionId}` : null,
+        result.workspace ? `workspace: ${result.workspace}` : null,
+        result.session ? `session:   ${result.session}` : null,
+        result.tools ? `tools:     ${result.tools.join(", ")}` : null,
+        `adapter:   ${"(see config)"} provider=${result.provider} model=${result.model}`,
+        `request:   ${JSON.stringify(result.request)}`,
+        `response:  ${JSON.stringify(result.response)}`,
+        result.expectedExact !== null && result.expectedExact !== undefined ? `expected:  ${JSON.stringify(result.expectedExact)}` : null,
+        `timing:    ${result.startedAt} -> ${result.finishedAt} (${result.durationMs} ms)`,
+        `exit:      ${result.exitCode}${result.signal ? ` signal=${result.signal}` : ""}`,
+      ].filter((line) => line !== null).join("\n") + "\n",
+    );
+  } else {
+    process.stdout.write("result.json: (missing or unreadable)\n");
+  }
+  if (task) process.stdout.write(`task snapshot: ${"task.json"} present\n`);
+  if (mission) process.stdout.write(`mission snapshot: ${mission.id} - ${mission.objective}\n`);
+  process.stdout.write(`artifacts: ${fs.readdirSync(dir).map((f) => `${f}`).join(", ")}\n`);
+  process.exit(0);
+}
+
+function retryRun(runId) {
+  if (!/^r-[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(runId)) {
+    fail(4, `invalid run id: ${JSON.stringify(runId)} (expected r-<id>)`);
+  }
+  const resolved = loadConfig();
+  const dir = path.join(runsRoot(resolved), runId);
+  if (!fs.existsSync(dir)) {
+    fail(4, `run not found: ${runId}`);
+  }
+
+  let snapshot;
+  try {
+    snapshot = fs.readFileSync(path.join(dir, "task.json"), "utf8");
+  } catch {
+    fail(4, `run task snapshot unreadable: ${runId}`);
+  }
+
+  // A retry is a brand-new run: replay the recorded task snapshot through
+  // the ordinary run path; existing run records stay untouched.
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "mosaic-retry-"));
+  const tempTaskFile = path.join(tempDir, "task.json");
+  fs.writeFileSync(tempTaskFile, snapshot);
+  process.on("exit", () => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup only.
+    }
+  });
+  runTask(tempTaskFile);
+}
+
+const operation = process.argv[2];
+const target = process.argv[3];
+
+switch (operation) {
+  case "validate": {
+    if (!target) fail(4, "usage: mosaic-task.mjs validate <taskFile>");
+    const file = path.resolve(target);
+    const task = validateTask(readJsonFile(file, "task file"), file);
+    const { missionSnapshot, ...rest } = task;
+    process.stdout.write(`${JSON.stringify(rest, null, 2)}\n`);
+    process.exit(0);
+  }
+  case "run":
+    if (!target) fail(4, "usage: mosaic-task.mjs run <taskFile>");
+    runTask(path.resolve(target));
+    break;
+  case "show":
+    if (!target) fail(4, "usage: mosaic-task.mjs show <runId>");
+    showRun(target);
+    break;
+  case "list":
+    listRuns();
+    process.exit(0);
+  case "retry":
+    if (!target) fail(4, "usage: mosaic-task.mjs retry <runId>");
+    retryRun(target);
+    break;
+  default:
+    fail(4, `unknown operation: ${JSON.stringify(operation ?? "")} (expected validate | run | show | list | retry)`);
+}
@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Release lifecycle: package, activate, rollback, status.
+#
+#   scripts/release.sh package               build the image for this release
+#   scripts/release.sh activate [--fault-injection]
+#   scripts/release.sh rollback
+#   scripts/release.sh status
+#
+# Activation is health-gated: the M2 task runner executes
+# tasks/hello-marker.json; only an exact-marker pass activates. The
+# pointer (state/active.json) is replaced atomically; every attempt is
+# appended to state/activation-log.jsonl (append-only history).
+#
+# Fault injection exists solely to prove the refusal path in drills.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+# shellcheck source=common.sh
+source scripts/common.sh
+
+load_config
+load_release
+bootstrap_runtime_dir
+
+STATE_DIR="$MOSAIC_DEV_DIR/state"
+mkdir -p "$STATE_DIR"
+POINTER="$STATE_DIR/active.json"
+LOG="$STATE_DIR/activation-log.jsonl"
+
+now() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+
+append_log() { # event release imageTag note
+    local event="$1" release="$2" imageTag="$3" note="${4:-}"
+    printf '{"at":"%s","event":"%s","release":"%s","imageTag":"%s"%s}\n' \
+        "$(now)" "$event" "$release" "$imageTag" \
+        "$(printf '%s' "$note" | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{const s=d.replace(/\n$/,"");process.stdout.write(s ? ",\"note\":"+JSON.stringify(s) : "")})')" \
+        >> "$LOG"
+}
+
+image_exists() { docker image inspect "$1" >/dev/null 2>&1; }
+
+health_check() { # returns 0 only when the marker path passes; $1 = fault injection label or empty
+    local tmp=""
+    local task="tasks/hello-marker.json"
+    if [ -n "${1:-}" ]; then
+        tmp="$(mktemp -d)"
+        # Fault injection: same prompt, deliberately wrong expectation.
+        printf '{"taskVersion":1,"id":"t-health-fault","prompt":"Return your startup marker and nothing else.","expectExact":"MOSAIC_FAULT_%s"}' \
+            "$RANDOM$RANDOM" > "$tmp/fault-task.json"
+        task="$tmp/fault-task.json"
+    fi
+    local rc=0
+    scripts/run-task.sh run "$task" >/dev/null 2>&1 || rc=$?
+    [ -n "$tmp" ] && rm -rf "$tmp"
+    return "$rc"
+}
+
+activate() { # $1 = release, $2 = imageTag, $3 = event name, $4 = fault label
+    local release="$1" imageTag="$2" event="$3" fault="${4:-}"
+
+    if ! image_exists "$imageTag"; then
+        echo "release: refusing $event: image not present locally: $imageTag" >&2
+        append_log "refused" "$release" "$imageTag" "image missing"
+        exit 1
+    fi
+
+    if ! health_check "$fault"; then
+        echo "release: refusing $event: health check failed" >&2
+        append_log "refused" "$release" "$imageTag" "health check failed${fault:+ (fault-injected)}"
+        exit 1
+    fi
+
+    # Atomic pointer replacement: write sibling temp file, then rename.
+    local tmp_pointer="$POINTER.tmp.$$"
+    printf '{"pointerVersion":1,"release":"%s","imageTag":"%s","activatedAt":"%s"}\n' \
+        "$release" "$imageTag" "$(now)" > "$tmp_pointer"
+    mv -f "$tmp_pointer" "$POINTER"
+
+    append_log "$event" "$release" "$imageTag"
+    echo "release: $event OK -> $release ($imageTag)"
+}
+
+previous_image_tag() { # last activated imageTag different from current pointer
+    [ -f "$POINTER" ] || return 1
+    local current
+    current="$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")).imageTag' "$POINTER")"
+    node -e '
+const fs = require("fs");
+const current = process.argv[1];
+const lines = fs.readFileSync(process.argv[2], "utf8").split("\n").filter(Boolean);
+for (let i = lines.length - 1; i >= 0; i--) {
+    let e;
+    try { e = JSON.parse(lines[i]); } catch { continue; }
+    if ((e.event === "activate" || e.event === "rollback") && e.imageTag && e.imageTag !== current) {
+        console.log(e.imageTag);
+        process.exit(0);
+    }
+}
+process.exit(1);
+' "$current" "$LOG"
+}
+
+cmd_status() {
+    echo "release:   $MOSAIC_RELEASE"
+    echo "image tag: $MOSAIC_IMAGE_TAG (packaged: $(image_exists "$MOSAIC_IMAGE_TAG" && echo yes || echo no))"
+    if [ -f "$POINTER" ]; then
+        node -e '
+const p = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+console.log("active:    " + p.release + " (" + p.imageTag + ") since " + p.activatedAt);
+' "$POINTER"
+    else
+        echo "active:    (none)"
+    fi
+    if [ -f "$LOG" ]; then
+        echo "recent log:"
+        tail -5 "$LOG" | sed 's/^/  /'
+    fi
+}
+
+cmd_package() {
+    docker compose build
+    append_log "package" "$MOSAIC_RELEASE" "$MOSAIC_IMAGE_TAG"
+    echo "release: packaged $MOSAIC_IMAGE_TAG"
+}
+
+cmd_activate() {
+    local fault=""
+    if [ "${1:-}" = "--fault-injection" ]; then fault="yes"; fi
+    activate "$MOSAIC_RELEASE" "$MOSAIC_IMAGE_TAG" "activate" "$fault"
+}
+
+cmd_rollback() {
+    local prev
+    if ! prev="$(previous_image_tag)"; then
+        echo "release: rollback: no previous activation found in log" >&2
+        exit 1
+    fi
+    local prev_release
+    prev_release="$(printf '%s' "$prev" | sed -n 's/.*-r\([0-9.]*\)$/\1/p')"
+    [ -n "$prev_release" ] || prev_release="unknown"
+    activate "$prev_release" "$prev" "rollback"
+}
+
+case "${1:-}" in
+    package)  cmd_package ;;
+    activate) shift; cmd_activate "$@" ;;
+    rollback) cmd_rollback ;;
+    status)   cmd_status ;;
+    *) echo "usage: scripts/release.sh package | activate [--fault-injection] | rollback | status" >&2; exit 4 ;;
+esac
@@ -7,9 +7,15 @@
 #      created by this project.
 # Any failed check aborts with nothing deleted.
 set -euo pipefail
+cd "$(dirname "$0")/.."
+# shellcheck source=common.sh
+source scripts/common.sh

-TARGET="/home/jwoltje/.mosaic-dev"
-MARKER=".mosaic-poc-root"
+# Reset operates on the CONFIGURED data root. Configuration itself is
+# never a reset target; a missing/invalid configuration aborts here.
+load_config
+TARGET="$MOSAIC_DATA_ROOT"
+MARKER="$POC_ROOT_MARKER"

 fail() {
    echo "reset: refusing to delete: $*" >&2
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Run a mission/task file through the config-driven container path.
+#
+# Usage: scripts/run-task.sh run <task.json>   (also: validate <task.json>, list)
+#
+# Ensures the configuration is valid and the data root carries the
+# ownership marker before any task executes.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+# shellcheck source=common.sh
+source scripts/common.sh
+
+load_config
+load_release   # compose requires MOSAIC_IMAGE_TAG; task runs are release-scoped too
+bootstrap_runtime_dir
+
+exec node scripts/mosaic-task.mjs "$@"
@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# Fast, sandboxed selftests for the configuration layer.
+#
+# No Docker, no network, no credentials: every case runs against a
+# temporary config via MOSAIC_CONFIG. Suitable for frequent local runs.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+SANDBOX="$(mktemp -d)"
+trap 'rm -rf "$SANDBOX"' EXIT
+
+PASS=0
+FAIL=0
+
+check() {
+    if [ "$2" = "0" ]; then PASS=$((PASS+1)); echo "ok   $1"; else FAIL=$((FAIL+1)); echo "FAIL $1"; fi
+}
+
+# expect_exit NAME EXPECTED_RC -- command...
+expect_exit() {
+    local name="$1" expected="$2"
+    shift 3 # name, expected, "--"
+    local rc
+    "$@" >/dev/null 2>&1
+    rc=$?
+    if [ "$rc" -eq "$expected" ]; then
+        PASS=$((PASS + 1))
+        echo "ok   $name (exit $rc)"
+    else
+        FAIL=$((FAIL + 1))
+        echo "FAIL $name (exit $rc, expected $expected)"
+    fi
+}
+
+CONFIG_OP="node scripts/mosaic-config.mjs"
+
+valid_body() {
+    cat <<EOF
+{"configVersion":1,"environment":"development","dataRoot":"$1","execution":{"backend":"docker","provider":"zai","model":"glm-5.3-flash"}}
+EOF
+}
+
+cfg() { printf '%s' "$2" > "$SANDBOX/$1"; }
+
+DATA_ROOT="$SANDBOX/data"
+
+# --- adapter selection (M4) ---
+cfg default-adapter.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m"}}'
+MOSAIC_CONFIG="$SANDBOX/default-adapter.json" $CONFIG_OP validate | grep -q '"adapter": "pi"'
+check "absent adapter defaults to pi" $?
+
+cfg mock-adapter.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m","adapter":"mock"}}'
+expect_exit "adapter mock validates" 0 -- env MOSAIC_CONFIG="$SANDBOX/mock-adapter.json" $CONFIG_OP validate
+
+cfg bad-adapter.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m","adapter":"claude"}}'
+expect_exit "unsupported adapter exits 2" 2 -- env MOSAIC_CONFIG="$SANDBOX/bad-adapter.json" $CONFIG_OP validate
+
+MOSAIC_CONFIG="$SANDBOX/mock-adapter.json" $CONFIG_OP env | grep -q "MOSAIC_ADAPTER='mock'"
+check "env exports adapter" $?
+
+# --- bootstrap ---
+rm -f "$SANDBOX/config.json"
+expect_exit "bootstrap creates default when absent" 0 -- \
+    env MOSAIC_CONFIG="$SANDBOX/config.json" $CONFIG_OP bootstrap
+[ -f "$SANDBOX/config.json" ] && { PASS=$((PASS+1)); echo "ok   bootstrap wrote config file"; } \
+    || { FAIL=$((FAIL+1)); echo "FAIL bootstrap wrote config file"; }
+
+SUM_BEFORE=$(sha256sum "$SANDBOX/config.json" | cut -d' ' -f1)
+MTIME_BEFORE=$(stat -c %Y "$SANDBOX/config.json")
+sleep 1.1
+expect_exit "bootstrap is idempotent on existing config" 0 -- \
+    env MOSAIC_CONFIG="$SANDBOX/config.json" $CONFIG_OP bootstrap
+SUM_AFTER=$(sha256sum "$SANDBOX/config.json" | cut -d' ' -f1)
+MTIME_AFTER=$(stat -c %Y "$SANDBOX/config.json")
+if [ "$SUM_BEFORE" = "$SUM_AFTER" ] && [ "$MTIME_BEFORE" = "$MTIME_AFTER" ]; then
+    PASS=$((PASS+1)); echo "ok   bootstrap did not rewrite existing config"
+else
+    FAIL=$((FAIL+1)); echo "FAIL bootstrap rewrote existing config"
+fi
+
+# --- validate ---
+expect_exit "validate missing config exits 3" 3 -- \
+    env MOSAIC_CONFIG="$SANDBOX/absent.json" $CONFIG_OP validate
+
+cfg invalid.json '{'
+expect_exit "malformed JSON exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/invalid.json" $CONFIG_OP validate
+
+cfg badversion.json '{"configVersion":2,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m"}}'
+expect_exit "unsupported configVersion exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/badversion.json" $CONFIG_OP validate
+
+cfg unknownkey.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","extra":true,"execution":{"backend":"docker","provider":"zai","model":"m"}}'
+expect_exit "unknown top-level key exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/unknownkey.json" $CONFIG_OP validate
+
+cfg unknownexec.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m","extra":1}}'
+expect_exit "unknown execution key exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/unknownexec.json" $CONFIG_OP validate
+
+cfg badbackend.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"podman","provider":"zai","model":"m"}}'
+expect_exit "unsupported backend exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/badbackend.json" $CONFIG_OP validate
+
+cfg badenv.json '{"configVersion":1,"environment":"staging","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"zai","model":"m"}}'
+expect_exit "unsupported environment exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/badenv.json" $CONFIG_OP validate
+
+cfg relative.json '{"configVersion":1,"environment":"development","dataRoot":"relative/path","execution":{"backend":"docker","provider":"zai","model":"m"}}'
+expect_exit "relative dataRoot exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/relative.json" $CONFIG_OP validate
+
+cfg traversal.json '{"configVersion":1,"environment":"development","dataRoot":"/tmp/../home/x","execution":{"backend":"docker","provider":"zai","model":"m"}}'
+expect_exit "non-canonical dataRoot exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/traversal.json" $CONFIG_OP validate
+
+cfg root.json '{"configVersion":1,"environment":"development","dataRoot":"/","execution":{"backend":"docker","provider":"zai","model":"m"}}'
+expect_exit "filesystem root dataRoot exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/root.json" $CONFIG_OP validate
+
+cfg home.json '{"configVersion":1,"environment":"development","dataRoot":"'$HOME'","execution":{"backend":"docker","provider":"zai","model":"m"}}'
+expect_exit "home directory dataRoot exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/home.json" $CONFIG_OP validate
+
+cfg cfgdir.json '{"configVersion":1,"environment":"development","dataRoot":"'$SANDBOX'","execution":{"backend":"docker","provider":"zai","model":"m"}}'
+expect_exit "dataRoot containing config dir exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/cfgdir.json" $CONFIG_OP validate
+
+cfg ctrlchar.json '{"configVersion":1,"environment":"development","dataRoot":"'$DATA_ROOT'","execution":{"backend":"docker","provider":"z\nai","model":"m"}}'
+expect_exit "control character in provider exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/ctrlchar.json" $CONFIG_OP validate
+
+cfg symlink.json 'placeholder'
+ln -sf "$SANDBOX/invalid.json" "$SANDBOX/symlink.json"
+expect_exit "symlinked config file exits 2" 2 -- \
+    env MOSAIC_CONFIG="$SANDBOX/symlink.json" $CONFIG_OP validate
+
+# --- env resolution ---
+cfg valid.json "$(valid_body "$DATA_ROOT")"
+EVAL_OUT="$(MOSAIC_CONFIG="$SANDBOX/valid.json" $CONFIG_OP env)" || true
+if eval "$EVAL_OUT" 2>/dev/null && [ "$MOSAIC_DATA_ROOT" = "$DATA_ROOT" ] \
+    && [ "$MOSAIC_PROVIDER" = "zai" ] && [ "$MOSAIC_MODEL" = "glm-5.3-flash" ]; then
+    PASS=$((PASS+1)); echo "ok   env exports resolve correctly"
+else
+    FAIL=$((FAIL+1)); echo "FAIL env exports resolve correctly"
+fi
+
+# --- validation must not modify the file ---
+SUM_INVALID_BEFORE=$(sha256sum "$SANDBOX/invalid.json" | cut -d' ' -f1)
+MOSAIC_CONFIG="$SANDBOX/invalid.json" $CONFIG_OP validate >/dev/null 2>&1
+SUM_INVALID_AFTER=$(sha256sum "$SANDBOX/invalid.json" | cut -d' ' -f1)
+if [ "$SUM_INVALID_BEFORE" = "$SUM_INVALID_AFTER" ]; then
+    PASS=$((PASS+1)); echo "ok   failed validation modified nothing"
+else
+    FAIL=$((FAIL+1)); echo "FAIL failed validation modified the file"
+fi
+
+echo
+echo "selftest: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]
@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Sandboxed selftests for the release layer.
+#
+# Fast cases (version validation) need no Docker. State-machine cases
+# (status/activate/refusal) run against a sandboxed config and therefore
+# require the Docker daemon; they are skipped when it is unavailable.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+SANDBOX="$(mktemp -d)"
+RELEASE_BACKUP="$(mktemp)"
+cp RELEASE "$RELEASE_BACKUP"
+# One exit trap: the repo RELEASE is ALWAYS restored from the backup,
+# regardless of how the test run ends.
+trap 'cp "$RELEASE_BACKUP" RELEASE 2>/dev/null; rm -rf "$SANDBOX" "$RELEASE_BACKUP"' EXIT
+
+PASS=0
+FAIL=0
+
+expect_exit() {
+    local name="$1" expected="$2"
+    shift 3
+    local rc
+    "$@" >/dev/null 2>&1
+    rc=$?
+    if [ "$rc" -eq "$expected" ]; then
+        PASS=$((PASS+1)); echo "ok   $name (exit $rc)"
+    else
+        FAIL=$((FAIL+1)); echo "FAIL $name (exit $rc, expected $expected)"
+    fi
+}
+
+check() {
+    if [ "$2" = "0" ]; then PASS=$((PASS+1)); echo "ok   $1"; else FAIL=$((FAIL+1)); echo "FAIL $1"; fi
+}
+
+# ---------- fast: release identity ----------
+expect_exit "valid RELEASE resolves" 0 -- bash -c 'source scripts/common.sh && load_release'
+
+printf 'garbage\n' > RELEASE
+expect_exit "invalid RELEASE exits 1" 1 -- bash -c 'source scripts/common.sh && load_release'
+
+mv RELEASE "$SANDBOX/RELEASE.hidden"
+expect_exit "missing RELEASE exits 1" 1 -- bash -c 'source scripts/common.sh && load_release'
+cp "$RELEASE_BACKUP" RELEASE
+
+bash -c 'source scripts/common.sh && load_release' >/dev/null 2>&1
+bash -c 'source scripts/common.sh && load_release && case "$MOSAIC_IMAGE_TAG" in mosaic-poc-agent:*-r'"$(cat RELEASE)"') exit 0;; *) exit 1;; esac' >/dev/null 2>&1
+check "valid RELEASE leaves image tag consistent with version" $?
+
+# ---------- sandboxed state machine (Docker required) ----------
+if docker info >/dev/null 2>&1; then
+    mkdir -p "$SANDBOX/data"
+    cat > "$SANDBOX/config.json" <<EOF
+{"configVersion":1,"environment":"development","dataRoot":"$SANDBOX/data","execution":{"backend":"docker","provider":"zai","model":"glm-5.3-flash"}}
+EOF
+    export MOSAIC_CONFIG="$SANDBOX/config.json"
+
+    expect_exit "status safe on empty state" 0 -- scripts/release.sh status
+    [ ! -e "$SANDBOX/data/state/active.json" ] \
+        && check "status created no pointer" 0 || check "status created no pointer" 1
+
+    expect_exit "fault-injected activation refuses" 1 -- scripts/release.sh activate --fault-injection
+    [ ! -e "$SANDBOX/data/state/active.json" ] \
+        && check "refused activation wrote no pointer" 0 || check "refused activation wrote no pointer" 1
+    if [ -f "$SANDBOX/data/state/activation-log.jsonl" ]; then
+        node -e '
+const fs = require("fs");
+const lines = fs.readFileSync(process.argv[1], "utf8").split("\n").filter(Boolean);
+if (lines.length !== 1) process.exit(1);
+const e = JSON.parse(lines[0]);
+process.exit(e.event === "refused" && e.release && e.imageTag && e.at ? 0 : 1);
+' "$SANDBOX/data/state/activation-log.jsonl"
+        check "refusal logged exactly once with valid fields" $?
+    else
+        check "refusal logged exactly once with valid fields" 1
+    fi
+
+    expect_exit "healthy activation succeeds" 0 -- scripts/release.sh activate
+    node -e '
+const fs = require("fs");
+const p = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+process.exit(p.pointerVersion === 1 && p.release && p.imageTag && p.activatedAt ? 0 : 1);
+' "$SANDBOX/data/state/active.json"
+    check "pointer written with valid fields" $?
+
+    expect_exit "repeat activation succeeds (log grows)" 0 -- scripts/release.sh activate
+    LINES=$(grep -c '' "$SANDBOX/data/state/activation-log.jsonl")
+    [ "$LINES" -ge 3 ] && check "log is append-only across activations" 0 || check "log is append-only across activations" 1
+
+    expect_exit "rollback without previous refuses" 1 -- scripts/release.sh rollback
+else
+    echo "skip state-machine cases (docker daemon unavailable)"
+fi
+
+echo
+echo "selftest: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]
@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+# Sandboxed selftests for the mission/task layer.
+#
+# Fast cases are validation-only (no Docker, no network). The final cases
+# execute real tasks through the container path and therefore require a
+# working configuration, credentials, and Docker.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+SANDBOX="$(mktemp -d)"
+trap 'rm -rf "$SANDBOX"' EXIT
+
+PASS=0
+FAIL=0
+
+expect_exit() {
+    local name="$1" expected="$2"
+    shift 3
+    local rc
+    "$@" >/dev/null 2>&1
+    rc=$?
+    if [ "$rc" -eq "$expected" ]; then
+        PASS=$((PASS+1)); echo "ok   $name (exit $rc)"
+    else
+        FAIL=$((FAIL+1)); echo "FAIL $name (exit $rc, expected $expected)"
+    fi
+}
+
+check() {
+    if [ "$2" = "0" ]; then PASS=$((PASS+1)); echo "ok   $1"; else FAIL=$((FAIL+1)); echo "FAIL $1"; fi
+}
+
+latest_reason() {
+    local latest
+    latest="$(ls -dt "$SANDBOX/data/runs"/r-* 2>/dev/null | head -1)"
+    [ -n "$latest" ] && node -e 'try{const r=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));console.log(r.reason??"")}catch{console.log("")}' "$latest/result.json" 2>/dev/null
+}
+
+check() {
+    if [ "$2" = "0" ]; then PASS=$((PASS+1)); echo "ok   $1"; else FAIL=$((FAIL+1)); echo "FAIL $1"; fi
+}
+
+CONFIG="$SANDBOX/config.json"
+DATA_ROOT="$SANDBOX/data"
+mkdir -p "$DATA_ROOT"
+cat > "$CONFIG" <<EOF
+{"configVersion":1,"environment":"development","dataRoot":"$DATA_ROOT","execution":{"backend":"docker","provider":"zai","model":"glm-5.3-flash"}}
+EOF
+export MOSAIC_CONFIG="$CONFIG"
+
+TASK="node scripts/mosaic-task.mjs"
+
+good_task() { # args: file [overrides as jq-less JSON fragments]
+    cat > "$1" <<EOF
+{"taskVersion":1,"id":"t-ok","prompt":"Return your startup marker and nothing else.","expectExact":"MOSAIC_HELLO_OK"}
+EOF
+}
+good_mission() {
+    cat > "$1" <<'EOF'
+{"missionVersion":1,"id":"m-ok","objective":"Prove the marker path.","directives":["Be terse."]}
+EOF
+}
+
+# ---------- fast: schema negatives ----------
+good_task "$SANDBOX/ok.json"
+expect_exit "valid task validates" 0 -- $TASK validate "$SANDBOX/ok.json"
+
+printf '{"taskVersion":1,"id":"t-x","prompt":"hi","extra":1}' > "$SANDBOX/unknownkey.json"
+expect_exit "unknown task key exits 2" 2 -- $TASK validate "$SANDBOX/unknownkey.json"
+
+printf '{"taskVersion":2,"id":"t-x","prompt":"hi"}' > "$SANDBOX/badver.json"
+expect_exit "unsupported taskVersion exits 2" 2 -- $TASK validate "$SANDBOX/badver.json"
+
+printf '{"taskVersion":1,"id":"BAD ID","prompt":"hi"}' > "$SANDBOX/badid.json"
+expect_exit "invalid task id exits 2" 2 -- $TASK validate "$SANDBOX/badid.json"
+
+printf '{"taskVersion":1,"id":"t-x","prompt":""}' > "$SANDBOX/emptyprompt.json"
+expect_exit "empty prompt exits 2" 2 -- $TASK validate "$SANDBOX/emptyprompt.json"
+
+printf '{"taskVersion":1,"id":"t-x","prompt":"hi","expectExact":"bad\\u0000nul"}' > "$SANDBOX/badexpect.json"
+expect_exit "NUL in expectExact exits 2" 2 -- $TASK validate "$SANDBOX/badexpect.json"
+
+printf '{"taskVersion":1,"id":"t-x","prompt":"hi","timeoutSeconds":9999}' > "$SANDBOX/badtimeout.json"
+expect_exit "out-of-range timeout exits 2" 2 -- $TASK validate "$SANDBOX/badtimeout.json"
+
+printf '{"taskVersion":1,"id":"t-x","prompt":"hi","mission":"missing.json"}' > "$SANDBOX/missmission.json"
+expect_exit "missing mission file exits 4" 4 -- $TASK validate "$SANDBOX/missmission.json"
+
+good_mission "$SANDBOX/m.json"
+printf '{"taskVersion":1,"id":"t-x","prompt":"hi","mission":"m.json"}' > "$SANDBOX/withmission.json"
+expect_exit "task with valid mission validates" 0 -- $TASK validate "$SANDBOX/withmission.json"
+
+printf '{"missionVersion":1,"id":"m-x","objective":"o","extra":1}' > "$SANDBOX/badmission.json"
+printf '{"taskVersion":1,"id":"t-x","prompt":"hi","mission":"badmission.json"}' > "$SANDBOX/withbadmission.json"
+expect_exit "invalid mission exits 2" 2 -- $TASK validate "$SANDBOX/withbadmission.json"
+
+expect_exit "validate missing task exits 4" 4 -- $TASK validate "$SANDBOX/nope.json"
+
+# validation writes nothing: task dir listing unchanged is implied; check mtime of ok.json
+M1=$(stat -c %Y "$SANDBOX/ok.json"); sleep 1.1
+$TASK validate "$SANDBOX/ok.json" >/dev/null 2>&1
+M2=$(stat -c %Y "$SANDBOX/ok.json")
+[ "$M1" = "$M2" ] && check "validation does not modify the task file" 0 || check "validation does not modify the task file" 1
+
+# ---------- adapter seam: deterministic mock cases (Docker, no provider) ----------
+if docker info >/dev/null 2>&1; then
+    good_task "$SANDBOX/ok.json"
+    mock_config() { # file adapter
+        cat > "$SANDBOX/$1" <<EOF
+{"configVersion":1,"environment":"development","dataRoot":"$SANDBOX/data","execution":{"backend":"docker","provider":"zai","model":"m","adapter":"$2"}}
+EOF
+    }
+
+    mock_config mock-adapters.json mock
+    expect_exit "mock adapter: gate passes on matching mock response" 0 -- \
+        env MOSAIC_CONFIG="$SANDBOX/mock-adapters.json" MOSAIC_MOCK_RESPONSE=MOSAIC_HELLO_OK \
+        scripts/run-task.sh run "$SANDBOX/ok.json"
+
+    expect_exit "mock adapter: expect-mismatch recorded" 1 -- \
+        env MOSAIC_CONFIG="$SANDBOX/mock-adapters.json" MOSAIC_MOCK_RESPONSE=SOMETHING_ELSE \
+        scripts/run-task.sh run "$SANDBOX/ok.json"
+    [ "$(latest_reason)" = "expect-mismatch" ] \
+        && check "mismatch reason recorded" 0 || check "mismatch reason recorded" 1
+
+    mock_config bad-adapter.json nonexistent
+    # The config layer rejects unknown adapters first, so run-task.sh fails
+    # closed (exit 1) before any container or run record exists.
+    expect_exit "unknown adapter fails closed" 1 -- \
+        env MOSAIC_CONFIG="$SANDBOX/bad-adapter.json" scripts/run-task.sh run "$SANDBOX/ok.json"
+
+    good_mission "$SANDBOX/m-ok.json"
+    printf '{"taskVersion":1,"id":"t-mission","prompt":"ignored by mock","mission":"m-ok.json"}' > "$SANDBOX/mission-task.json"
+    # Dedicated mission with distinctive directives for the injection assertion.
+    cat > "$SANDBOX/m-seam.json" <<'EOF'
+{"missionVersion":1,"id":"m-seam","objective":"Prove the mission injection point.","directives":["Seam directive A.","Seam directive B."]}
+EOF
+    printf '{"taskVersion":1,"id":"t-mission-seam","prompt":"ignored by mock","mission":"m-seam.json"}' > "$SANDBOX/seam-task.json"
+    expect_exit "mission task runs via mock adapter" 0 -- \
+        env MOSAIC_CONFIG="$SANDBOX/mock-adapters.json" MOSAIC_MOCK_RESPONSE=MOCKED \
+        scripts/run-task.sh run "$SANDBOX/seam-task.json"
+    grep -q 'MISSION (runtime)' "$SANDBOX/data/system-prompt.md" \
+        && grep -q 'Seam directive A.' "$SANDBOX/data/system-prompt.md" \
+        && check "mission section injected into generated prompt" 0 \
+        || check "mission section injected into generated prompt" 1
+else
+    echo "skip adapter seam cases (docker daemon unavailable)"
+fi
+
+# ---------- workspace + capabilities (M5): deterministic mock cases ----------
+if docker info >/dev/null 2>&1; then
+    printf '{"taskVersion":1,"id":"t-ws","prompt":"ignored","workspace":"suitews","capabilities":{"tools":["read","bash"]}}' > "$SANDBOX/ws-task.json"
+    expect_exit "workspace+tools task runs via mock" 0 -- \
+        env MOSAIC_CONFIG="$SANDBOX/mock-adapters.json" MOSAIC_MOCK_RESPONSE=MOCKED \
+        scripts/run-task.sh run "$SANDBOX/ws-task.json"
+    WSL="$(ls -dt "$SANDBOX/data/runs"/r-* 2>/dev/null | head -1)"
+    grep -q '^MOSAIC_WORKSPACE=/var/lib/mosaic/workspaces/suitews$' "$WSL/stderr.txt" 2>/dev/null \
+        && grep -q '^MOSAIC_TOOLS=read,bash$' "$WSL/stderr.txt" 2>/dev/null \
+        && check "workspace path + tools delivered to adapter" 0 \
+        || check "workspace path + tools delivered to adapter" 1
+    [ -d "$SANDBOX/data/workspaces/suitews" ] \
+        && check "persistent workspace created on host" 0 \
+        || check "persistent workspace created on host" 1
+
+    expect_exit "plain task still runs (no workspace/tools)" 0 -- \
+        env MOSAIC_CONFIG="$SANDBOX/mock-adapters.json" MOSAIC_MOCK_RESPONSE=MOSAIC_HELLO_OK \
+        scripts/run-task.sh run "$SANDBOX/ok.json"
+    PL="$(ls -dt "$SANDBOX/data/runs"/r-* 2>/dev/null | head -1)"
+    grep -q '^MOSAIC_WORKSPACE=$' "$PL/stderr.txt" 2>/dev/null \
+        && check "workspace var present but empty when absent" 0 || check "workspace var present but empty when absent" 1
+    grep -q '^MOSAIC_TOOLS=$' "$PL/stderr.txt" 2>/dev/null \
+        && check "tools empty when absent" 0 || check "tools empty when absent" 1
+
+    printf '{"taskVersion":1,"id":"t-badtool","prompt":"x","capabilities":{"tools":["sudo"]}}' > "$SANDBOX/badtool.json"
+    expect_exit "unknown tool exits 2" 2 -- $TASK validate "$SANDBOX/badtool.json"
+    printf '{"taskVersion":1,"id":"t-badws","prompt":"x","workspace":"../escape"}' > "$SANDBOX/badws.json"
+    expect_exit "workspace traversal exits 2" 2 -- $TASK validate "$SANDBOX/badws.json"
+else
+    echo "skip workspace/capability cases (docker daemon unavailable)"
+fi
+
+# ---------- live: real runs (Docker + credentials required) ----------
+# On failure, surface the run record + agent stderr BEFORE the sandbox
+# cleanup destroys them. Never let a wrong-exit mask the real reason.
+dump_latest_run() {
+    local latest
+    latest="$(ls -dt "$SANDBOX/data/runs"/r-* 2>/dev/null | head -1)"
+    if [ -n "$latest" ]; then
+        echo "--- latest run evidence: $latest ---" >&2
+        cat "$latest/result.json" 2>/dev/null >&2
+        echo "--- stderr.txt (tail) ---" >&2
+        tail -8 "$latest/stderr.txt" 2>/dev/null >&2
+    else
+        echo "--- no run dir was created at all ---" >&2
+    fi
+}
+
+latest_reason() {
+    local latest
+    latest="$(ls -dt "$SANDBOX/data/runs"/r-* 2>/dev/null | head -1)"
+    [ -n "$latest" ] && node -e 'try{const r=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));console.log(r.reason??"")}catch{console.log("")}' "$latest/result.json" 2>/dev/null
+}
+
+if docker info >/dev/null 2>&1; then
+    RUNS1=$(ls "$DATA_ROOT/runs" 2>/dev/null | wc -l)
+    if scripts/run-task.sh run "$SANDBOX/ok.json" >/dev/null 2>&1; then
+        PASS=$((PASS+1)); echo "ok   live hello task succeeds with exact marker"
+    else
+        FAIL=$((FAIL+1)); echo "FAIL live hello task succeeds with exact marker" >&2
+        dump_latest_run
+    fi
+
+    R1="$(ls -t "$DATA_ROOT/runs" | head -1)"   # newest = the live run above
+    [ -f "$DATA_ROOT/runs/$R1/result.json" ] && check "result.json written in run dir" 0 || check "result.json written in run dir" 1
+    node -e '
+const r = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+process.exit(r.status === "succeeded" && r.response === "MOSAIC_HELLO_OK" && r.expectedExact === "MOSAIC_HELLO_OK" ? 0 : 1);
+' "$DATA_ROOT/runs/$R1/result.json"
+    check "result.json contents are correct" $?
+
+    printf '{"taskVersion":1,"id":"t-wrong","prompt":"Return your startup marker and nothing else.","expectExact":"MOSAIC_NOT_OK"}' > "$SANDBOX/wrong.json"
+    scripts/run-task.sh run "$SANDBOX/wrong.json" >/dev/null 2>&1
+    RC=$?
+    WRONG_REASON="$(latest_reason)"
+    if [ "$RC" -eq 1 ] && [ "$WRONG_REASON" = "expect-mismatch" ]; then
+        PASS=$((PASS+1)); echo "ok   wrong expectExact fails with exit 1 (reason: expect-mismatch)"
+    else
+        FAIL=$((FAIL+1)); echo "FAIL wrong expectExact (exit $RC, reason: '${WRONG_REASON:-none}')" >&2
+        dump_latest_run
+    fi
+
+    RUNS2=$(ls "$DATA_ROOT/runs" | wc -l)
+    [ "$RUNS2" -gt "${RUNS1:-0}" ] && check "each run gets a distinct run dir (no clobber)" 0 \
+        || check "each run gets a distinct run dir (no clobber)" 1
+
+    COUNT=$($TASK list | wc -l)
+    [ "$COUNT" -ge 2 ] && check "list shows both runs" 0 || check "list shows both runs" 1
+else
+    echo "skip live task cases (docker unavailable)"
+fi
+
+echo
+echo "selftest: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]
@@ -14,9 +14,16 @@ cd "$(dirname "$0")/.."
 # shellcheck source=common.sh
 source scripts/common.sh

-IMAGE="mosaic-poc-agent:0.84.4"
 EXPECTED="${EXPECTED_MARKER:-MOSAIC_HELLO_OK}"

+load_config
+load_release
+IMAGE="$MOSAIC_IMAGE_TAG"
+
+# Ensure the configured data root exists (host-owned) before the mount,
+# otherwise Docker would auto-create a root-owned directory.
+bootstrap_runtime_dir
+
 # 1. Build the image only if it is not already present.
 if ! docker image inspect "$IMAGE" >/dev/null 2>&1; then
    echo "verify: image $IMAGE not found, building..." >&2
@@ -25,8 +32,9 @@ if ! docker image inspect "$IMAGE" >/dev/null 2>&1; then
 fi

 # 2. Run the agent request (stdout only = model response).
+# stdin detached: see hello.sh — print mode would block on a terminal.
 set +e
-RESPONSE="$(docker compose run --rm -T mosaic-agent 2>/tmp/mosaic-poc-stderr.$$)"
+RESPONSE="$(docker compose run --rm -T mosaic-agent </dev/null 2>/tmp/mosaic-poc-stderr.$$)"
 RC=$?
 set -e
 STDERR_FILE="/tmp/mosaic-poc-stderr.$$"
@@ -33,5 +33,23 @@ for f in $FILES; do
    printf '\n' >> "$TEMP"
 done

+# Sanctioned mission injection point (M4): when the task runner provides a
+# mission snapshot, its objective and directives are appended AFTER the
+# immutable contracts. Runtime data; never part of the contract fixtures.
+if [ -n "${MOSAIC_MISSION_FILE:-}" ]; then
+    if [ ! -r "$MOSAIC_MISSION_FILE" ]; then
+        echo "load-contracts: MOSAIC_MISSION_FILE set but not readable: $MOSAIC_MISSION_FILE" >&2
+        rm -f "$TEMP"
+        exit 1
+    fi
+    printf '===== MISSION (runtime) =====\n' >> "$TEMP"
+    node -e '
+const m = JSON.parse(require("fs").readFileSync(process.env.MOSAIC_MISSION_FILE, "utf8"));
+process.stdout.write("Objective: " + m.objective + "\n");
+for (const d of m.directives ?? []) process.stdout.write("- " + d + "\n");
+' >> "$TEMP"
+    printf '\n' >> "$TEMP"
+fi
+
 mv "$TEMP" "$OUT"
 echo "load-contracts: wrote $OUT from $CONTRACT_DIR" >&2
@@ -1,38 +1,33 @@
 #!/bin/sh
-# One-shot Pi agent runner inside the container.
-# Loads the contract-generated system prompt, then sends exactly one
-# user request through Pi's documented noninteractive mode and prints
-# the model response on stdout.
+# One-shot agent dispatcher inside the container.
+#
+# 1. Loads the contract-generated system prompt (contracts + optional
+#    mission section from MOSAIC_MISSION_FILE).
+# 2. Dispatches to /opt/mosaic/adapters/<MOSAIC_ADAPTER>/adapter.sh per
+#    the contract in /opt/mosaic/adapters/README.md.
 set -eu

-: "${PI_PROVIDER:=zai}"
-: "${PI_MODEL:=glm-5.3-flash}"
-export PI_PROVIDER PI_MODEL
-
 REQUEST="${*:-Return your startup marker and nothing else.}"

+ADAPTER="${MOSAIC_ADAPTER:-pi}"
+case "$ADAPTER" in
+    # Allowlist mirrors scripts/mosaic-config.mjs; pattern check first so a
+    # crafted name cannot escape the adapters directory.
+    *[!A-Za-z0-9._-]*|'')
+        echo "run-agent: invalid adapter name: '$ADAPTER'" >&2
+        exit 2
+        ;;
+esac
+
+ADAPTER_SCRIPT="/opt/mosaic/adapters/$ADAPTER/adapter.sh"
+if [ ! -x "$ADAPTER_SCRIPT" ]; then
+    echo "run-agent: unknown or non-executable adapter: $ADAPTER" >&2
+    exit 2
+fi
+
 /opt/mosaic/src/load-contracts.sh /opt/mosaic/contracts /var/lib/mosaic/system-prompt.md

-# All flags are documented in the package README (CLI Reference):
-#   -p / --print        noninteractive: print the response and exit
-#   --system-prompt     replace the default system prompt with the
-#                       contract-generated prompt
-#   --no-* switches     prevent ambient context files, skills, extensions,
-#                       prompt templates, and themes from being appended
-#   --no-session        ephemeral: no persistent agent session
-#   --no-tools          the startup request needs no tool execution
-#   --offline           disable startup network operations (update checks,
-#                       package update checks, install/update telemetry)
-exec pi \
-    --offline \
-    --no-session \
-    --no-extensions \
-    --no-skills \
-    --no-prompt-templates \
-    --no-themes \
-    --no-context-files \
-    --no-tools \
-    --provider "$PI_PROVIDER" \
-    --model "$PI_MODEL" \
-    --system-prompt "$(cat /var/lib/mosaic/system-prompt.md)" \
-    -p "$REQUEST"
+export MOSAIC_SYSTEM_PROMPT_FILE="/var/lib/mosaic/system-prompt.md"
+export MOSAIC_REQUEST="$REQUEST"
+
+exec "$ADAPTER_SCRIPT"
@@ -0,0 +1,8 @@
+{
+  "taskVersion": 1,
+  "id": "t-hello-marker",
+  "prompt": "Return your startup marker and nothing else.",
+  "mission": "../missions/hello.json",
+  "expectExact": "MOSAIC_HELLO_OK",
+  "timeoutSeconds": 120
+}
@@ -0,0 +1,8 @@
+{
+  "taskVersion": 1,
+  "id": "t-session-teach",
+  "prompt": "Remember this code word for later: mosaico. Reply with exactly: REMEMBERED",
+  "session": "demo",
+  "expectExact": "REMEMBERED",
+  "timeoutSeconds": 180
+}
@@ -0,0 +1,7 @@
+{
+  "taskVersion": 1,
+  "id": "t-session-recall",
+  "prompt": "What code word did I ask you to remember earlier in this session? Reply with only the code word.",
+  "session": "demo",
+  "timeoutSeconds": 180
+}
@@ -0,0 +1,9 @@
+{
+  "taskVersion": 1,
+  "id": "t-worker-retry-refine",
+  "prompt": "Follow-up on your last change to scripts/mosaic-task.mjs (the retry operation). Conductor review found one defect: runTask builds spawnEnv from process.env, so a direct 'node scripts/mosaic-task.mjs retry <runId>' invocation lacks the launcher-exported variables and compose fails with: required variable MOSAIC_IMAGE_TAG is missing.\n\nFIX (in runTask, not retryRun): make spawnEnv self-sufficient —\n1. spawnEnv.PI_PROVIDER = resolved.execution.provider; spawnEnv.PI_MODEL = resolved.execution.model (from the already-loaded resolved config).\n2. spawnEnv.MOSAIC_IMAGE_TAG = 'mosaic-poc-agent:' + <pinned pi version> + '-r' + <RELEASE file content trimmed>, reading RELEASE and package.json the same way scripts/common.sh load_release does.\nKeep the change minimal; do not touch other files; keep code style.\n\nSELF-CHECK: node --check scripts/mosaic-task.mjs must pass.\nWhen finished, reply with exactly: REFINE_DONE",
+  "workspace": "stack-repo",
+  "capabilities": { "tools": ["read", "write", "edit", "bash"] },
+  "session": "worker-1",
+  "timeoutSeconds": 600
+}
@@ -0,0 +1,9 @@
+{
+  "taskVersion": 1,
+  "id": "t-worker-retry",
+  "prompt": "You are working alone inside a git repository checkout (your current working directory). Implement a new feature in scripts/mosaic-task.mjs.\n\nFEATURE: add a 'retry <runId>' operation alongside the existing 'validate | run | show | list' operations.\n\nBEHAVIOR: 'retry <runId>' re-executes a previously recorded run. Steps: (1) validate the runId argument with the same pattern showRun uses; (2) load the config exactly like showRun does; (3) locate the run directory under the runs root; if it does not exist, fail with exit code 4 and the message 'run not found: <runId>'; (4) read that run directory's task.json snapshot; if unreadable, fail with exit code 4; (5) write the snapshot to a temp file and execute it through the EXISTING runTask(path) function so a brand-new run is created — do not duplicate any execution logic; (6) exit with whatever exit code the new run produced.\n\nCONSTRAINTS: reuse runTask; do not refactor unrelated code; do not touch any file other than scripts/mosaic-task.mjs; keep the existing code style; update the default usage error message to include retry.\n\nSELF-CHECK (run it yourself with the bash tool): node --check scripts/mosaic-task.mjs must pass.\n\nWhen finished, reply with exactly: RETRY_DONE",
+  "workspace": "stack-repo",
+  "capabilities": { "tools": ["read", "write", "edit", "bash"] },
+  "session": "worker-1",
+  "timeoutSeconds": 600
+}
@@ -0,0 +1,9 @@
+{
+  "taskVersion": 1,
+  "id": "t-workspace-demo",
+  "prompt": "Use the bash tool to create a file named proof.txt in the current directory containing exactly the text: workspace works. Then reply with exactly: WORKSPACE_OK",
+  "workspace": "demo",
+  "capabilities": { "tools": ["bash", "read", "write"] },
+  "expectExact": "WORKSPACE_OK",
+  "timeoutSeconds": 180
+}
Author	SHA1	Message	Date
jason.woltje	d9cc990376	Merge M8: conductor loop - self-orchestration Closes #25, closes #26, closes #27	2026-09-02 22:42:52 -05:00
jason.woltje	83c4e9851e	feat(orchestration): retry <runId> — authored by headless pi worker (#26 , #27 ) Collaboration record (conductor loop, docs/plans/CONDUCTOR.md): - round 1 (worker session worker-1, 2m28s): retry implemented per spec - conductor live test exposed spec gap: direct invocation lacked launcher env exports - round 2 (same worker session, 59s): spawnEnv made self-sufficient, but used PI_* where compose interpolates MOSAIC_* - conductor hotfix: 3-line rename to MOSAIC_PROVIDER/MOSAIC_MODEL/ MOSAIC_DATA_ROOT Final: node scripts/mosaic-task.mjs retry <runId> re-executes a run's task snapshot as a new run; live retry replied REMEMBERED; all suites green (24/32/14 + verify). Known limitation: retrying a run whose task used a RELATIVE mission path resolves it against the temp dir; lineage tracking deferred. Closes #25, closes #26, closes #27	2026-09-02 22:42:52 -05:00
jason.woltje	22508170a2	docs(plan): CURRENT.md — single next-action pointer for cadence-driven work	2026-09-02 22:25:56 -05:00
jason.woltje	90a67d050e	Merge M7: operator ergonomics + release 0.0.6 Closes #24	2026-09-02 22:14:18 -05:00
jason.woltje	24bdef75fa	feat(ops): run inspection, release 0.0.6, docs (#24 ) - mosaic-task.mjs show <runId>: full record + snapshots + artifacts; uppercase-tolerant id validation; missing/traversal ids exit 4 - list: task/workspace/session columns - RELEASE -> 0.0.6; README workspaces/capabilities/sessions sections; BUILD-LOG Phases 9-11; autonomous-run tracker results filled Closes #24	2026-09-02 22:14:18 -05:00
jason.woltje	4e2a413640	Merge M6: named sessions - persistence and resume Closes #22, closes #23	2026-09-02 22:08:34 -05:00
jason.woltje	be55549700	feat(sessions): named persistent sessions with resume (L1) (#22 , #23 ) - task schema: optional session (named id) -> persistent session dir at dataRoot/sessions/<name>, isolated per name - pi adapter: --session-dir when declared (ephemeral --no-session stays the default otherwise); -c resumes the most recent session when present - compose passthrough; result.json records session - fixtures: tasks/session-demo-1.json (teach) + session-demo-2.json (recall) - E2E: teach -> REMEMBERED + host-side session JSONL; resume -> recalled 'mosaico' exactly; single continued session file Closes #22, closes #23	2026-09-02 22:08:34 -05:00
jason.woltje	ddb1554e5b	Merge M5: task workspaces + capability envelope Closes #20, closes #21	2026-09-02 22:06:43 -05:00
jason.woltje	b017e66e17	test(capabilities): workspace/tooling selftests + live demo fixture (#21 ) - mock plumbing cases: workspace path + tools delivered (asserted from run-record stderr), host workspace created, absent fields = empty vars - validation negatives: unknown tool, workspace traversal - tasks/workspace-demo.json: pi uses bash inside the persistent demo workspace; host-visible proof.txt verified live Closes #21	2026-09-02 22:06:43 -05:00
jason.woltje	172368612c	feat(capabilities): task workspaces + tools allowlist plumbing (#20 ) - task schema: optional workspace (absent \| :run ephemeral \| named persistent under dataRoot/workspaces) and capabilities.tools (pi documented tool allowlist); strict validation, traversal-proof names - runner: creates host workspace, passes MOSAIC_WORKSPACE (container path) + MOSAIC_TOOLS; result.json records both - pi adapter: cds into workspace; --tools when allowlist present else --no-tools - mock adapter: logs delivered MOSAIC_* vars to stderr as deterministic plumbing evidence (dash prints 'export K=v', so use env not export) Closes #20	2026-09-02 22:03:46 -05:00
jason.woltje	1387231e57	docs(plan): autonomous work run tracker (M5-M7 scope, test plan, review checklist)	2026-09-02 21:57:30 -05:00
jason.woltje	0292392e64	Merge M4: runtime adapter seam Closes #16, closes #17, closes #18, closes #19	2026-09-02 21:30:35 -05:00
jason.woltje	594b8d711c	docs(adapters): adapter seam docs + recorded M4 E2E, release 0.0.5 (#19 ) - README: Runtime adapters section (contract summary, selection, mission injection point); BUILD-LOG Phase 8 entries - E2E: 24+24+14 selftests green; verify PASS; 0.0.5 packaged and health-gated activated; mission-bearing fixture task succeeded through the real pi adapter; config checksum unchanged Closes #19	2026-09-02 21:30:35 -05:00
jason.woltje	3c1ffd2c2d	test(adapters): seam selftests — deterministic mock cases + mission injection (#18 ) - test-config: absent adapter defaults to pi; mock validates; unknown adapter exits 2; env exports MOSAIC_ADAPTER (24 cases total) - test-task: mock adapter gate pass/mismatch (no provider needed), mismatch reason asserted, unknown adapter fails closed, mission section injected into generated prompt asserted by content (24 cases total) - harness fixes: helpers defined before use; per-case config files (no cross-case leakage); newest-run selection for the live case; deduped accidentally duplicated live block Closes #18	2026-09-02 21:28:57 -05:00
jason.woltje	4ebb123ba3	feat(adapters): sanctioned mission directives injection (#17 ) - load-contracts.sh: MOSAIC_MISSION_FILE (readable) appends a MISSION (runtime) section — objective + directives — after the immutable contracts; unreadable path is a hard error, absent env changes nothing - mosaic-task.mjs: exports MOSAIC_MISSION_FILE as the run snapshot's container path (/var/lib/mosaic/runs/<id>/mission.json), with an outside-dataRoot guard; also exports the configured adapter Verified: contract-only prompt has no mission section; mission-bearing run shows objective + directives in the generated prompt, snapshot recorded, real provider returns exactly MOSAIC_HELLO_OK. Closes #17	2026-09-02 21:19:22 -05:00
jason.woltje	bb5cecb348	feat(adapters): adapter contract, dispatch, pi + mock adapters (#16 ) - adapters/README.md: the harness boundary contract (env in, response on stdout, diagnostics stderr, exit 0 success) - adapters/pi: extracted current invocation unchanged - adapters/mock: deterministic MOSAIC_MOCK_RESPONSE echo (test-only) - run-agent.sh: name-validated dispatch to adapters/<name>/adapter.sh - config: optional execution.adapter (pi\|mock), default pi, configVersion stays 1 — existing configs remain valid; selection authority is the config file (load_config exports it) - compose: MOSAIC_ADAPTER / MOSAIC_MOCK_RESPONSE passthrough; Containerfile installs adapters read-only; RELEASE -> 0.0.5 Verified: hello unchanged; mock verbatim via config; unknown adapter and path-traversal names refused in-container; invalid adapter exits 2. Closes #16	2026-09-02 21:18:07 -05:00
jason.woltje	88f55d9135	test(task): live failures self-report evidence; wrong-exit no longer masks (#15 ) - live hello failure dumps latest run result.json + stderr tail before sandbox cleanup destroys them - wrong-expectExact case asserts reason == expect-mismatch (was: any exit 1, which masked compose-level failures) - repair dangling if/else from the docker-guard refactor Closes #15	2026-09-02 20:56:58 -05:00
jason.woltje	e7e1bd26eb	fix(launcher): resolve release identity for direct task runs (#14 ) M3 made MOSAIC_IMAGE_TAG required in compose, but run-task.sh never called load_release — direct task runs failed in compose before any model call. release.sh paths masked it by exporting the tag to children. Found by owner-run test-task.sh; failure receipts were in the run records' stderr.txt. Closes #14	2026-09-02 20:44:31 -05:00
jason.woltje	5d86b8fa93	Merge M3: release model and safe updates Closes #10, closes #11, closes #12, closes #13	2026-09-02 20:24:33 -05:00
jason.woltje	35ea464661	docs(release): release model usage + recorded M3 drills (#13 ) - README: Release model section (package/activate/rollback/status, pointer + append-only log, gate-then-flip guarantee) - BUILD-LOG Phase 7: drills recorded (update, refusal, rollback), two harness/product corrections documented Drill evidence: 0.0.3 -> 0.0.4 update with unchanged config checksum and green verify; fault-injected refusal left pointer untouched; health-gated rollback restored 0.0.3; full append-only event history. Closes #13	2026-09-02 20:24:33 -05:00
jason.woltje	e87ecdb3e5	test(release): release-layer selftests (#12 ) 14 cases: RELEASE validation (valid/invalid/missing), tag consistency, status on empty state, fault-injected refusal with no pointer + single valid refusal log line, healthy activation, pointer fields, repeat activation append-only log, rollback-without-previous refusal. Harness fix learned the hard way: restore RELEASE from backup inline after the missing-file case (mv-back restored the mutated file); single exit trap self-heals the repo state. Closes #12	2026-09-02 20:23:18 -05:00
jason.woltje	a947db7bfd	feat(release): package/activate/rollback/status with health gate (#11 ) - activate: image-presence pre-check + M2 task-runner health gate (tasks/hello-marker.json exact marker) before atomic pointer replace (tmp+rename); every attempt appended to activation-log.jsonl - --fault-injection flips the health expectation to prove the refusal path - rollback: health-gated re-activation of the previous activated imageTag from the log; refuses when the image is gone or no previous exists - status: release, tag, pointer, recent log; safe on empty state - state lives under <dataRoot>/state/ (config-independent, reset-scoped) Verified: activate OK; fault-injected refuse with pointer unchanged; rollback-without-previous refuse. Closes #11	2026-09-02 20:20:32 -05:00
jason.woltje	a35ea62ab1	feat(release): RELEASE identity + image tag single-sourcing (#10 ) - RELEASE file: single source of release version (0.0.X until declared stable) - common.sh load_release(): validates version, derives MOSAIC_IMAGE_TAG=mosaic-poc-agent:<pi>-r<release> from the pinned pi dep - compose.yaml: image tag is required env; build/hello/verify call load_release - verify.sh derives the image name instead of hardcoding it - package.json version aligned to the same 0.0.X line Closes #10	2026-09-02 20:18:17 -05:00
jason.woltje	f6c93dcb5c	Merge M2: mission and task abstraction Closes #6, closes #7, closes #8, closes #9	2026-09-02 19:58:53 -05:00
jason.woltje	7f0408d417	feat(task): fixture mission/task, docs, recorded M2 E2E (#9 ) - missions/hello.json + tasks/hello-marker.json committed fixtures - README: Missions & tasks section (usage, run record layout, M2 scope note) - BUILD-LOG: Phase 6 before/after entries E2E: fixture run succeeded with exactly MOSAIC_HELLO_OK; wrong expectExact recorded status failed (expect-mismatch) and exited 1; runs listed; config checksum unchanged. Closes #9	2026-09-02 19:58:53 -05:00
jason.woltje	cfd2a19bd7	test(task): mission/task selftests — schema negatives + live runs (#8 ) 18 cases: validation negatives (unknown keys, versions, ids, prompt, expectExact NUL, timeout range, missing/invalid mission, writes-nothing) plus live cases: exact-marker success, wrong expectExact fails, distinct run dirs, result.json contents, list output. Closes #8	2026-09-02 19:57:34 -05:00
jason.woltje	d2a9e26395	feat(task): mission/task schemas, validation, and run runner (#6 ) (#7 ) - scripts/mosaic-task.mjs: validate \| run \| list - Strict v1 schemas: unknown keys rejected; ids/prompt/expectExact/ timeoutSeconds bounds enforced; optional mission file resolved against the task file and validated too - run: executes through the config-driven container path with stdin detached (issue #5 class), SIGKILL timeout (default 120s), trimmed response capture - Immutable run records under <dataRoot>/runs/r-<utcstamp>-<rand>/: task.json + mission.json snapshots (write-once), stderr.txt, result.json - expectExact gate: mismatch -> status failed, exit 1; result.json is always written - scripts/run-task.sh: load_config + bootstrap_runtime_dir before exec - M2 scope: mission directives are snapshotted for provenance, not yet injected into the runtime prompt (later policy layer) Closes #6, closes #7	2026-09-02 19:56:29 -05:00
jason.woltje	0734b1f3a5	fix(launcher): detach stdin on agent container run (#5 ) pi print mode reads piped stdin until EOF; an attached terminal stdin blocked the one-shot run forever. Automated contexts (closed stdin) never exposed it. Request text comes from the compose command. Proven: tail -f /dev/null \| scripts/hello.sh now returns MOSAIC_HELLO_OK in ~4s (previously timed out at 30s); verify.sh remains green. Closes #5	2026-09-02 19:50:07 -05:00
jason.woltje	ce6420f3de	Merge M1: configuration-driven Hello World Closes #1, closes #2, closes #3, closes #4	2026-09-02 18:32:50 -05:00
jason.woltje	81f58b15c8	fix(launcher): ensure configured data root before verify mount; docs for M1 (#4 ) - verify.sh now calls bootstrap_runtime_dir after load_config; previously a reset-then-verify flow let Docker auto-create a root-owned mount source - common.sh: fail with clear guidance when data root exists but is not writable - README: configuration section, bootstrap usage, selftest entry point - BUILD-LOG: Phase 5 entries with corrections E2E (clean slate): 20/20 selftests; bootstrap idempotent; config-driven hello/verify MOSAIC_HELLO_OK; negative marker exit 1; reset + rerun green; config checksum unchanged across the entire flow. Closes #4	2026-09-02 18:32:50 -05:00
jason.woltje	0c2113f710	test(config): sandboxed config-layer selftests (#3 ) 20 cases: bootstrap create/idempotency, missing config, malformed JSON, unknown keys/version/backend/environment, relative and non-canonical dataRoot, filesystem root, home dir, ancestor-of-config, control chars, symlinked config file, env export resolution, validation-writes-nothing. Closes #3	2026-09-02 18:30:46 -05:00
jason.woltje	900a506c1f	feat(config): wire launcher scripts and compose to config.json (#2 ) - common.sh: load_config() exports MOSAIC_DATA_ROOT/PROVIDER/MODEL; fails closed - compose.yaml: dataRoot mount and provider/model are required env (:? errors) - build/hello/verify load config before any mutation; no silent bootstrap - reset.sh: target resolved from configured dataRoot; all safety checks kept Verified: compose fails without launcher env; verify/reset fail on missing config; config-driven hello+verify pass; symlink refusal with sandboxed config (canary survived); config checksum unchanged across reset+rerun. Closes #2	2026-09-02 18:30:08 -05:00
jason.woltje	c3d29e796a	feat(config): config module with idempotent bootstrap and strict v1 validation (#1 ) - scripts/mosaic-config.mjs: bootstrap \| validate \| env operations - Exclusive creation (O_EXCL 'wx'); existing config validated, never rewritten - Strict schema: unknown keys rejected, configVersion===1, backend docker only - dataRoot guards: absolute, canonical, not root/home/ancestor-of-config - MOSAIC_CONFIG override for sandboxed tests; exit codes 0/2/3 - scripts/bootstrap.sh: explicit bootstrap entry point Closes #1	2026-09-02 18:28:14 -05:00