feat(agent): interactive TUI launcher + identity + TOOLS.md (#35)

- scripts/agent.sh <name>: launches interactive pi TUI in the container
  with contracts + optional mission + agent identity + named session +
  optional workspace/tools; the Mosaic alternative to vanilla pi
- pi adapter: MOSAIC_INTERACTIVE branch (clean TUI, no -p, no initial
  prompt); headless exec rebuilt via positional args (no word-splitting
  on the request); MOSAIC_AGENT_NAME optional in headless
- loader: AGENT IDENTITY section when the launcher names the agent
- compose: fixed command removed (request defaults live in run-agent.sh);
  MOSAIC_INTERACTIVE/MOSAIC_AGENT_NAME passthrough
- docs/TOOLS.md: full on-demand tool reference; AGENTS.md routes to it
- RELEASE -> 0.0.8 (container change); build verified

Closes #35

docs/TOOLS.md

@@ -0,0 +1,85 @@
+# TOOLS.md — command and tool reference
+
+On-demand reference for agent sessions (conductors, bootstrapping agents,
+reviewers). `AGENTS.md` routes here; this file carries the depth: usage,
+inputs/outputs, exit codes, and safety notes for every entry point.
+
+Reading guide: all entry points are `scripts/*.sh` (bash) or invoked via
+`node scripts/mosaic-task.mjs` (node). Every script fails closed — missing
+or invalid configuration/policy refuses the operation with a nonzero exit
+and changes nothing.
+
+## Lifecycle
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/bootstrap.sh` | Create `~/.config/mosaic-dev/config.json` if absent | Idempotent; existing config validated, never rewritten |
+| `scripts/build.sh` | Build the release image | Tag derived from `RELEASE` + pinned pi version |
+| `scripts/hello.sh` | One-shot startup request | Prints model response on stdout |
+| `scripts/verify.sh` | Full gated test | Exit 0 only on exact `MOSAIC_HELLO_OK`; `EXPECTED_MARKER` overrides for negative drills |
+
+## Tasks (missions, runs, evidence)
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/run-task.sh run <task.json>` | Execute a task | Immutable run record under `<dataRoot>/runs/` |
+| `scripts/run-task.sh validate <task.json>` | Strict validation | Writes nothing |
+| `node scripts/mosaic-task.mjs show <runId>` | Inspect a run | Full record + snapshots + artifacts |
+| `node scripts/mosaic-task.mjs list` | List runs | task/workspace/session columns |
+| `node scripts/mosaic-task.mjs retry <runId>` | Re-execute a run's snapshot | New run dir; `retriedFrom` lineage recorded |
+| `node scripts/mosaic-task.mjs prune [--keep=N] [--yes]` | Retention | Dry-run default; receipt in `runs/.pruned.log` |
+
+Task fields: `prompt` (required), `mission` (path), `expectExact`,
+`timeoutSeconds` (5–600), `workspace` (`:run` or named), `capabilities.tools`
+(allowlist: read write edit bash grep find ls), `session`,
+`sessionForkFrom` (requires `session`). Mission fields: `objective`,
+`directives[]`, optional governing `capabilities.tools`. Policy: a task may
+narrow a mission's tools, never widen; empty intersection = tool-free run.
+
+## Agent (interactive TUI)
+
+```bash
+scripts/agent.sh <name> [--mission <file>] [--workspace <ws>] [--session <s>] [--tools <list>]
+```
+
+Launches an interactive pi TUI inside the container with the four immutable
+contracts + optional mission + agent identity as its system prompt,
+persistent named session, optional workspace. Exit with `/quit`.
+
+## Release
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/release.sh package` | Build + tag the release image | Tag: `mosaic-poc-agent:<pi>-r<release>` |
+| `scripts/release.sh activate` | Health gate → atomic pointer swap | `--fault-injection` proves the refusal path |
+| `scripts/release.sh rollback` | Health-gated return to previous | Refuses if image missing |
+| `scripts/release.sh status` | Release, tag, active pointer, log | Safe on empty state |
+
+## Conductor (worker patches)
+
+```bash
+scripts/conductor-apply.sh <runId> [--dry-run]
+```
+
+Auto-applies a worker's patch under `roles/conductor-policy.json`:
+succeeded run → clean target tree → path allowlist → syntax gates →
+apply → policy suites → attribution commit. Any failure reverts.
+Push is never automatic.
+
+## Maintenance
+
+| Command | Purpose | Notes |
+|---|---|---|
+| `scripts/reset.sh` | Delete the data root | Triple-safety-checked (path, symlink, ownership marker) |
+| `scripts/test-config.sh` | Config selftests (no Docker) | 24 cases |
+| `scripts/test-task.sh` | Task selftests + live cases | 58 cases |
+| `scripts/test-release.sh` | Release selftests | 14 cases |
+| `scripts/test-conductor.sh` | Auto-apply selftests (sandboxed) | 17 cases |
+| `scripts/gitea-api.sh <METHOD> <path> [body]` | Gitea API helper | Token never on argv/stdout |
+
+## Exit-code convention
+
+`0` success · `1` operation failed · `2` invalid data/configuration ·
+`3` configuration missing for a read operation · `4` usage/file/environment
+problem. Scripts print diagnostics on stderr; model responses (and only
+model responses) on stdout.