clawmates/docs/NEXT-SESSION.md

# Where this left off — 2026-08-21

Read `CAPABILITY-REVIEW.md` for the system picture,
`TOOL-CALL-ARCHITECTURE.md` for how mission tools actually work (and the two
wrong theories that preceded it), and `SKILL-USE-BASELINE.md` for the
measurement — noting that its Trigger column is now out of date in a good way
(see "Next, in order" §2).

## State of the tree

Everything is pushed. `main` is at `5a11fae`; the fork's
`merge/upstream-v0.8.4` is at `be9c34b1c`. Local suite green: **107 test
binaries, 412 lib tests**, frontend builds.

**CI is green and production is current.** Run 507 passed `test` and `build`,
and gw-04 rolled to it. Production also runs `clawmates-runtime:hooks` for
per-mission containers (see below).

## Container-tier tool gate + telemetry — SHIPPED 2026-08-21

The tier that actually runs missions now has both, verified end to end on a
real mission (locally first, then deployed):

```
tool.call   10    Bash 6, Read 3, Write 1
file.touch   4    research/tapproof.md
```

That is the first time the container tier has ever been observable.

**How, after `stream-json` failed.** Claude Code runs its tools inside its own
subprocess, so they never reach ZeroClaw's executor and never become a
`TurnEvent::ToolCall`. Hooks bypass that entirely: `claude -p --settings <doc>`
honours `PreToolUse` and `PostToolUse`, so the gate blocks and the tap records
without ZeroClaw being involved at all.

Pieces: `--settings` on `claude_cli` (fork `be9c34b1c`),
`container_tool_hooks` writes both hook scripts and one settings document into
the mission container, `set_claude_cli_settings` points the provider at it, and
`phase_runner::drain_finished_container_phases` collects the tap into
`mission_events` (idempotent by truncation — no cursor column).

**Production state:** server on `f6e6037`;
`CLAWMATES_RUNTIME_IMAGE=clawmates-runtime:hooks` in `/opt/clawmates/.env`
(backup at `.env.bak.prehooks`; rollback = restore it and recreate). Note that
host uses **legacy `docker-compose`**, not the v2 plugin.

**Not yet observed in production** — no prod mission has run since the flip.
Prod auth is Clerk, so a mission cannot be launched from here by password. The
check when one runs:

```
ssh gw-04 'docker logs clawmates_server_1 2>&1 | grep -E "per-mission runtime image|drained .* tool call"'
```

### Three bugs the live test found, all the same shape

Each left every other link looking correct:

1. The settings document pointed `PostToolUse` at a path the installer never
   wrote. Claude Code does not complain about a missing hook command — it
   records nothing. A test now compares the document's commands against the
   files the installer creates.
2. The mission container uses `CLAWMATES_RUNTIME_IMAGE`, not the shared
   `clawmates-runtime` container — it was on an older image whose daemon schema
   had no `settings` field, so the prop write returned `404 path_not_found`.
3. The drain used `connect_with_local_defaults()`; the server reaches Docker
   through a **socket proxy**, so it failed — and returned `Ok(())` silently.

### CI: build failures were disk, not code

Runs 503–506 failed at `build` with an unreadable log, and the first casualty
was a **docs-only** commit. Cause: building runtime images by hand on gw-04
competes with CI for the same 150G volume; the frontend image build lost.
`docker builder prune` reclaimed 34GB (22G → 57G free) and the next run went
green. The build job now writes breadcrumbs, a `df -h` snapshot, and which
services actually pushed — the failing runs had pushed `server`, aborted on
`frontend`, and left `:latest` unmoved, which surfaced three steps later as
"the deploy did not happen".

**Operational note:** do not build images by hand on gw-04 while CI may run.

## Next, in order

1. **Watch the first production mission.** Nothing has run since the runtime
   flip, so the container-tier gate and tap are proven locally and unproven in
   prod. Prod auth is Clerk, so a mission cannot be launched from here.
   ```
   ssh gw-04 'docker logs clawmates_server_1 2>&1 | grep -E "per-mission runtime image|drained .* tool call"'
   ssh gw-04 'docker exec <cm-runtime-mission-…> cat /root/toolhooks/tap/tools.jsonl | head'
   ```
   If tools appear in `mission_events`, the loop is closed. If not, check the
   three failure shapes listed above — each looked correct from every other
   angle.

2. **Now that tool calls are observable, redo the Skill-Use measurement.**
   `docs/SKILL-USE-BASELINE.md` reports Trigger as `not_observable` on the
   container tier because there was no tool evidence. There is now.
   `mission_events` carries `tool.call` and `file.touch` per phase, so
   Trigger can be scored from behaviour instead of prose — which is what the
   paper actually measures. This is the single highest-value follow-up: it
   turns the baseline from "the first honest number" into a real one.

3. **Give the microVM tier the same treatment, or retire the difference.** It
   has the gate and a tap already, but by a different route (`vm_tool_tap`
   installs into the guest, `microvm_executor` drains inside the turn). Two
   mechanisms for one job is how they drift. Worth folding onto
   `container_tool_hooks` once the fleet is back — tank and morpheus have been
   offline for over a week, so the microVM tier cannot be tested at all today.

4. **Deploy the door** (`docs/TOOL-CALL-ARCHITECTURE.md` §3). Config, not code:
   `/zeroclaw-data/clawmates-mcp.json` plus a door-shaped provider alias. Now
   less urgent than it looked — the gate no longer depends on it — but it is
   still the precondition for `clawmates_skills` being reachable, and therefore
   for skills moving from inlined bodies to progressive disclosure.

5. **Pull upstream's egress policy** — `0db7d999a feat(plugins): add shared
   egress policy foundation (#9137)`. We are ~220 commits behind; this is the
   one item identified as worth taking, and it is defence for a problem we have
   not solved.

**Dropped from this list:** "give the direct-session tier a tap". That tier is
dormant — `CLAWMATES_MISSION_EXECUTOR` is unset in production, so it never
runs. Checking that before building for it saved the work.

## Open decisions that are yours

- **Self-authoring scope.** Agents now apply their own `skill_candidate` items
  with no human click (`CLAWMATES_SKILL_SELF_AUTHORING=0` restores the gate).
  `identity_refinement` and `brain_consolidation` still wait for a human,
  because they change what an agent IS rather than adding a procedure it can
  consult. Say if you want those autonomous too.
- **Skill-Use Compliance coverage.** Most skills still score `not_applicable` —
  we cannot tell whether they changed anything. `small-focused-commits` and
  `tdd-red-green-refactor` are the next candidates and both need the repository
  diff rather than the turn text.

## Deliberately not done

- **The mission executor swap** (running turns through `ProviderExecutor` or the
  chat `Runtime`). The blockers are structural, not wiring: `cm-runtime`'s
  `files` tool rejects absolute paths *by construction*, `shell` runs in a
  per-agent sandbox with no mission mount, `ToolContext` carries no path or VM
  handle, and approvals key on `(session_id, message_id)`. The cheap fixes
  deliver what it was wanted for.
- **`cm-brain` offline tests** — 6 of 9 need live `clawbrainhub.com`. Stubbing
  means reproducing an external registry protocol we have no spec for.
- **Graph memory / `clawhdf5-agent`** — in the workspace manifest, used by no
  crate. Measure against a baseline before migrating.

## Operational facts that cost time to learn

- The Gitea **actions-log API returns 403** for the token in
  `deploy/compose/.env`. Every CI failure this week was debugged blind because
  of it. Steps now write to `/tmp/ci-logs` on the runner host as a workaround;
  **a token with the `actions` scope** remains the highest-value thing to
  obtain.
- **gw-04 uses legacy `docker-compose`**, not the v2 plugin. `docker compose`
  fails there.
- **Do not build images by hand on gw-04 while CI may run** — same 150G volume,
  and the frontend image build is what loses.
- The server reaches Docker through a **socket proxy** (`DOCKER_HOST`). Use
  `container_exec::connect()`, never `connect_with_local_defaults()`.
- Prod auth is **Clerk**; the bootstrap password in `deploy/compose/.env` works
  only against the local stack.

## Two corrections made this session, worth remembering

- **"Missions can't call tools at all" was wrong.** They call `Bash` and `Write`
  with permissions pre-accepted. The gap was observing and gating, not having.
- **Raw test counts are a bad coverage metric.** They pointed at `cm-safety`,
  whose seven tests already covered its critical paths, and missed a Slack
  replay hole that let one captured request authenticate forever.

The recurring shape, now seven times over: **a claim in a comment or a doc,
believed and never checked.** Every significant finding this session came from
running the thing rather than reading about it.