docs: AGENTS.md - session recovery shim, invariants canon, session registry

- AGENTS.md at root: pi loads it automatically at every session start
  (conductor-level sessions; workers deliberately exclude it via
  --no-context-files). Deliberately short: invariants, session protocol,
  role model, command surface, data map, pointers - depth stays in docs/.
- docs/SESSIONS.md: append-only session registry, mandatory per session.
- Recovery rule encoded: compaction/restart loses nothing - AGENTS.md +
  CURRENT.md + git log + suites reconstruct state; never guess.

AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md — Mosaic Stack rebuild (`mosaicstack/stack-v2`)
+
+Operational context for any agent session working in this repository.
+Read top to bottom; it is deliberately short — depth lives in the files it
+points to, not here.
+
+## What this repository is
+
+A standalone rebuild of Mosaic Stack: a file-based, fail-closed
+orchestration foundation that dispatches sandboxed headless pi workers to do
+real work, with immutable run records as evidence. Thirteen-plus tagged
+milestones (`git tag -l`) from `poc-container-hello-v0` to today; suites
+green at every step. Not production software — a proven foundation.
+
+## Non-negotiable invariants (the canon)
+
+1. **Root is bootstrap-only.** First-class system configuration lives at the
+   repository root; everything else gets a dedicated directory (`roles/`,
+   `contracts/`, `missions/`, `tasks/`, `docs/`). Do not add new files to root.
+2. **Configuration**: `~/.config/mosaic-dev/config.json` is the sole system
+   config — created only by `scripts/bootstrap.sh`, never overwritten,
+   fail-closed on any problem. Repo-scoped role authority lives in
+   `roles/*.json` (versioned, reviewed commits only).
+3. **Secrets** never enter the repository or container images; auth is
+   runtime-only (read-only mount or environment variable).
+4. **Contracts** (`contracts/`) are immutable and image-baked. Missions and
+   tasks are declarative JSON with strict schemas.
+5. **Run records** under `<dataRoot>/runs/` are write-once evidence — never
+   rewritten, only pruned via `prune` with a receipt.
+6. **Fail closed**: missing or invalid config/policy refuses the operation.
+   Never improvise around a refusal; diagnose it.
+7. **Policy**: missions govern tasks (least-privilege intersection — a task
+   narrows, never widens). Role authority is declared in `roles/` and changes
+   only via reviewed commits.
+8. **Git**: commit only after suites are green; push only `main`; never
+   force-push. `scripts/conductor-apply.sh` commits locally — push stays an
+   explicit act.
+9. **Append-only logs**: BUILD-LOG.md (phases), `activation-log.jsonl`,
+   `.pruned.log`, docs/SESSIONS.md. Corrections are new entries, never edits.
+
+## Session protocol (mandatory)
+
+- **Register** your session in `docs/SESSIONS.md` — one append-only line
+  (date, actor, scope, outcome). Never rewrite or remove entries.
+- **Cadence**: read `docs/plans/CURRENT.md` → execute its single next action
+  fully (implement → test → verify against acceptance criteria → commit →
+  push → close issue) → update CURRENT.md → register in SESSIONS.md.
+- "next" means one action. A batch mandate ("run the queue") repeats the
+  loop until green or blocked. Blocked means stop and report, never improvise.
+- Substantial work gets a Gitea issue and a BUILD-LOG phase entry
+  (before/after, with corrections recorded honestly).
+
+## Role model
+
+- **Conductor**: a system-scoped role — not an agent, not a daemon. Holds
+  git/credentials/policy authority; decomposes, dispatches, reviews,
+  verifies, integrates. Protocol: `docs/plans/CONDUCTOR.md`. Exists only
+  when invoked; push is never automatic.
+- **Workers**: headless pi via `scripts/run-task.sh` — sandboxed workspace,
+  tools allowlist, optional persistent sessions and forks; no git, no
+  credentials, no policy control.
+- Worker runs deliberately exclude this file (`--no-context-files` in the
+  adapter): worker context is contracts + mission via the generated system
+  prompt. This file is for conductor-level sessions.
+
+## Command surface
+
+`scripts/bootstrap.sh` (idempotent) · `build.sh` · `hello.sh` ·
+`verify.sh` · `run-task.sh run <task.json>` · `release.sh
+package|activate|rollback|status` · `reset.sh` (**danger**: wipes the data
+root; triple-safety-checked) · `mosaic-task.mjs validate|run|show|list|retry|prune` ·
+suites: `test-config.sh`, `test-task.sh`, `test-release.sh`,
+`test-conductor.sh`.
+
+## Data map (canon)
+
+- `~/.config/mosaic-dev/config.json` — system config (user-authored; never
+  auto-written).
+- `<dataRoot>` (from config; default `~/.mosaic-dev`):
+  - `runs/` — write-once run evidence (`result.json`, snapshots, `stderr.txt`)
+  - `sessions/` — pi JSONL session trees, one directory per named session
+  - `workspaces/` — agent file effects (persistent or `:run` ephemeral)
+  - `state/` — release pointer + append-only activation/auto-apply logs
+- Ownership is per-directory; nothing shares state. Directory map and
+  lifecycle rules: README.md "Data map" section.
+
+## Pointers (depth lives here)
+
+- `docs/plans/CURRENT.md` — THE next action (single source of "what now")
+- `docs/plans/CONDUCTOR.md` — orchestration protocol and guardrails
+- `docs/plans/2026-09-02_atomic-mosaic-foundation.md` — architecture, invariants
+- `docs/plans/2026-09-03_autonomous-run.md` — batch-run tracker
+- `BUILD-LOG.md` — append-only build/verification history with corrections
+- `LAYERS.md` — implemented vs deferred layers
+- `docs/SESSIONS.md` — session registry
+- `adapters/README.md` — the harness adapter contract
+- `roles/` — role contracts (conductor, future agent/coder/reviewer)
+
+## Recovery rule
+
+Compacted, restarted, or new? Nothing that matters is lost: this file +
+`docs/plans/CURRENT.md` + `git log --oneline -10` + the suites reconstruct
+the full state. **Never guess** — verify with the suites; the run records
+and logs hold the receipts.
+
+## Version pin
+
+`@earendil-works/pi-coding-agent` is pinned exactly (see `package.json` /
+`RELEASE`); never install unversioned. Release identity: `RELEASE` file
+(0.0.X until declared stable); image tags derive from it.