handoff-2026-07-26

Coordinator handoff — 2026-07-26

Written for the next aw-coordinator instance. Read this before `aw work ready`.

Where things stand

**Do not trust any SHA in this document — verify with `git ls-remote origin refs/heads/main`.** Main moved twice while this was being written, and a stale SHA here is exactly the kind of confident-wrong claim the rest of the file warns about.

The `default-aajc` security-remediation epic and the two independent reviews stacked on it are **done**. Eighteen findings merged and closed on 2026-07-26.

Merged today: `aamm` `aana` `aano` `aanb` `aanc` `aank` `aanl` `aanm` `aann` `aanr` `aans` `aant` `aanw` `aanx` `aaoc` `aaod` `aaoe` `aaog`.

**Both original ship blockers are closed.** Chat read-semantics (silent permanent message loss) and the identity-home class.

READ THIS FIRST — there IS a release blocker

`default-aaom`, P0, filed after the rest of this document was written.

**The channel client version was never bumped, so the server's clean cutover would 422 every deployed client.** Verified independently: the server rejects `up_to_message_id` (`routes/chat.py:1811`); the published `channel-v1.6.0` sends exactly that (`channel-core/src/api/chat.ts:101`); and `channel/package.json` on main is still `1.6.0`, byte-identical to the tag, despite 48 changed files since.

Consequence if the server ships first: every installation gets a 422 on every mark-read, messages are never marked read, and they are re-presented forever with no client-side diagnostic — the `aajy` replay shape, hitting everyone at once.

**HARD ORDERING CONSTRAINT: do not deploy the server until a channel release carrying the `message_ids` payload is published and adopted.** No gate enforces this — `release-channel-check` only verifies package.json and plugin.json agree with each other, and the tag-collision check lives in `release-channel-tag`, which only runs when you deliberately release the channel.

A correction I owe the next instance

This file originally said nothing was release-blocking. That was wrong twice over: `aaom` above, and a reproducible test failure. At `f23cebeb` — the commit that *created this file* — `TestEmbeddedTmuxGuardMatchesRepositoryGuard` was FAILING: the embedded `cmd/aw/tmux_guard.sh` compared lexical paths while `scripts/guard-bin/tmux` canonicalized. **I committed a handoff asserting a clean tree without running the suite.**

It is green now (fixed between `f23cebeb` and `f00e084e`), measured at both SHAs. But the lesson is the file's own: I asserted state instead of measuring it, in a document whose whole point is that measured claims beat confident ones.

What is NOT done, and what to do about it

**Ten open follow-ups.** I pruned six as not worth pursuing — don't re-file them; read the closure reasons, they carry measurements. Of the ten, four matter:

| task | why it matters | |---|---| | `aanq` | **`make prod-dump` is not a backup.** Data-only, no DDL, cannot restore into an empty database. Someone will rely on it in an emergency. This is the highest-value item on the board and it is not mine — it is ac-operations'. | | `aang` | **Channel event stream flaps and silently drops assignments.** Juan caught this live: agents sat idle with unread work while the roster said "active". Cross-team, observed repeatedly. | | `aaok` | Cross-runtime preflight divergence. Inert today (one unix user owns every home), **live the moment containers or per-agent users separate write access from key-read access.** Wired as a precondition onto `aaao` (m8 decomposition). | | `aanu` | Mail WAF silently drops security content — no error, no non-zero exit, message never lands. |

The rest (`aand` `aane` `aanj` `aanp` `aaof` `aaoh`) are documentation drift and P3 polish. Fine to leave.

With Juan / AC, not with you

• **`aakf` log retention.** AC owns the code (their middleware logs message

bodies AND response bodies). The open question is where production logs live and for how long — only Juan has those credentials. Storing messages in the DB is correct and was never the issue; *logging* them is.

• **Migration 011 deploy window.** `ALTER TABLE` taking an ACCESS EXCLUSIVE lock

and building an index. Wants a quiet moment. Runs inside AC's container.

• **Client release for the chat fix.** Merged but NOT released. Old published

clients break loudly against the new payload, so it needs coordinating.

Standing decisions — do not relitigate

• **Makefile-based CI, manual deploy.** Juan rebuked me for building GitHub

Actions unasked. Do not add workflows. The audits attach to the *release* path, not `make test`, because they consult an external advisory database that moves without a repo change.

• **Ship on no known defects** (Juan's bar). Live defects block; proof gaps

don't.

• **Identity-path changes need Juan's explicit approval.** A reviewer ACK is not

approval. Record the approval in the commit message.

• **Every schema change is a NEW ordered migration file.** Never edit an existing

one.

• **Releases are the coordinator's call**, executed by ac-operations.

Traps that cost real time today

1. **An idle agent does not poll.** Mail *does* wake them (measured), but if one is parked at a prompt with unread work, nothing moves. `aw workspace status` says "active" regardless — it only reflects last-seen, which any `aw` command touches. **Capture the pane.** `esc to interrupt` present = working. 2. **A completed handoff is not progress.** The queue stalls just as easily on an idle *reviewer*. Watch branches, not just developers. 3. **`tmux send-keys` with long text lands in paste mode** — needs a *second* `Enter`. Verify it submitted. 4. **`aw task` 404s intermittently** (`aagh`). Retry; it succeeds immediately. 5. **`aw mail show --message-id` cannot resolve your OWN sent mail** — returns `No messages.` with exit 0. Use `--conversation-id`. `aw mail inbox` is unread-only by default. 6. **`cp` is interactive here.** It pr