box/docs/DIGEST-PROTOCOL.md

# Digest Protocol Runbook

How the main loop sends digests and how agents close them.

**Status:** spec (2026-10-04). Implemented in `self_main_loop.py` + `response-harvester.py`;
no new machinery — the protocol wires digests into the existing `dm.py --expect-reply`
/ `followups.json` / harvester response path.

---

## 1. Why this protocol exists

Main-loop digests (`[main-loop] N new in <agent> main chat: ...`) were being sent
with no response contract: no stable ID, no declared timeout, no nudge/escalation
policy, and no way to distinguish "seen and closed" from "ignored". Across 43
digests there were zero RESULT replies and zero measurable outcomes — not because
agents ignored them, but because nothing defined how to answer.

This protocol closes that wiring gap without inventing a new system:
- digest composer → `dm.py send --expect-reply` (followup record, timeout/nudges
  declared at send time)
- agent replies in-band with a verb: `[ACK|CLAIM|RESULT|DECLINE|NO-ACTION <id>]`
- `response-harvester.py` matches by `job_id` and records the outcome in
  `followups.json`
- the sweeper nudges/escalates only unresolved followups, per the declared policy

## 2. Digest classes

Not every digest deserves a reply demand (notification fatigue; and the standing
rule that the human only sees real decisions and escalations). The composer
already marks `[?]` (question) and `[!]` (operator-needed / urgent).

| Class | Marker | Response required? | Followup record? | Measured by |
|---|---|---|---|---|
| **ACTIONABLE** | carries `[?]` or `[!]` | **yes** | yes | delivered → acked → closed |
| **INFORMATIONAL** | neither | no | no | delivered only |

Informational digests are sent exactly as today. They are **excluded from every
reply-rate metric** — an informational digest is measured as *delivered*, full stop.
Judging informational FYI traffic by answer rate is structurally misleading.

## 3. Digest ID

Every ACTIONABLE digest gets a stable ID:

```
ml-<agent>-<YYYYMMDD-HHMMSS>
```

Example: `ml-646-20261004-213000`.

The ID is embedded visibly in the digest as `[JOB ml-...]`. This marker survives
`extract_trailing_tags` (only known canonical keys are stripped) and is picked up
by `dm_send`'s job_id regex (`\[JOB\s+([A-Za-z0-9_-]+)\]`) anywhere in the message,
so it lands in `tags["job_id"]` → the followup record. **No new dm.py flags are
needed for the ID.**

Replies match on this ID, so attribution games with `[from:X]` can never break
resolution.

## 4. Reply verbs

Printed in the contract footer of every ACTIONABLE digest (Section 7).

| Verb | Syntax | Meaning | Followup effect |
|---|---|---|---|
| `ACK` | `[ACK <id>]` | Seen, noted | status `acknowledged` — stops nudges, **not closed** |
| `CLAIM` | `[CLAIM <id>]` | I'm handling it | status `acknowledged` — stops nudges, **not closed** |
| `RESULT` | `[RESULT <id>] <result text>` | Done, result attached | status `resolved`, outcome `RESULT` — **closed** |
| `DECLINE` | `[DECLINE <id>]` | Won't act (reason optional) | status `resolved`, outcome `DECLINE` — **closed** |
| `NO-ACTION` | `[NO-ACTION <id>]` | Reviewed, nothing needed | status `resolved`, outcome `NO-ACTION` — **closed** |

Semantics:
- `ACK` vs `CLAIM`: both acknowledge. `CLAIM` signals ownership; `ACK` is just
  "seen". Use `CLAIM` when you're picking up the work so the human knows who's on it.
- `NO-ACTION` is a real answer, not a dodge. It means "I reviewed this and there
  is genuinely nothing to do." It closes the digest so it stops being counted as open.
- `DECLINE` should carry a reason when one exists (`[DECLINE ml-646-...] blocked:
  chromebox flapping`), but a bare DECLINE is still a valid close.
- `RESULT` closes only when the result text is present. An empty RESULT is a malformed
  reply — the harvester treats it as unrecognized.

Nudge interaction: `ACK`/`CLAIM` suppress further nudges but leave the followup open
until a closing verb arrives. This matches the real workflow — "I'm on it" shouldn't
trigger nags, but the loop isn't closed until there's a result.

## 5. Timeout policy

Declared at send time (standing rule: policy is part of the send, not decided later).

| Digest class | Timeout | Nudges |
|---|---|---|
| normal (marked `[?]`) | 60 min | 2 |
| urgent (marked `[!]`) | 30 min | 2 |

Implemented as `--reply-timeout {3600|1800} --reply-nudges 2` on the `dm.py send`
invocation for ACTIONABLE digests. The timeout and nudge count are stored in the
followup record; the sweeper honors them.

## 6. Nudge / escalation policy

- The sweeper nudges only followups with `status == "pending"`. Anything
  `acknowledged` or `resolved` is never re-nudged (ACKed digests getting nagged
  trains agents to ignore the protocol — verify this when wiring the sweeper).
- After the declared nudges are exhausted and the timeout passes, the followup is
  **escalated**, not retried forever:
  - **Phase 1:** the sweeper's existing escalation path (DM to the escalate target
    declared at send time via `--reply-escalate`).
  - **Phase 2:** route to the registered `main-loop brain` sidechat for triage.
    The brain is registered in `job-sidechats.json` as `main-loop brain` and is
    name-resolvable, so no hardcoded UUIDs are needed.
- `stale` = still `pending` past timeout + nudges → escalated.

Digest routing must use sidechat **names** (`646 tasks`, `main-loop brain`) via the
existing name resolution — never hardcoded thread UUIDs (see the stale-UUID lesson
in AGENTS.md).

Note: the harvester only monitors threads registered in `job-sidechats.json`.
`opm/heartbeat` is not registered (digests there resolve via fuzzy search), so
digest replies there would never resolve. **Route opm's digests to the registered
`main-loop brain` sidechat instead of `heartbeat`** — cleaner separation
(brain = triage workspace, heartbeat = heartbeats) and zero new registrations.

## 7. In-band contract footer

The digest budget is 600 chars, so the footer is compact. Actionable digests trim
message previews from 5 to 3 to fit it:

```
[main-loop] [JOB ml-646-20261004-213000] 3 new in 646 main chat — reply needed:
- human: <preview> [?]
Reply: [ACK id] seen | [CLAIM id] mine | [RESULT id] done | [DECLINE id] | [NO-ACTION id]
```

The footer is the primary contract. This doc is the reference.

## 8. Example exchange

```
# opm → 646 tasks (ACTIONABLE, --expect-reply --reply-timeout 3600 --reply-nudges 2)

[from:opm] [id:a6579a8d] [main-loop] [JOB ml-646-20261004-213000] 3 new in 646 main chat — reply needed:
- human: should we archive the stale pipe-7d2896 thread? [?]
- opm: propose yes, it's superseded by the brain channel [?]
Reply: [ACK id] seen | [CLAIM id] mine | [RESULT id] done | [DECLINE id] | [NO-ACTION id]

# 646 picks it up

[from:646] [CLAIM ml-646-20261004-213000] reviewing now

→ followup status: acknowledged (nudges suppressed, loop still open)

# 646 finishes

[from:646] [RESULT ml-646-20261004-213000] archived pipe-7d2896 via muse-cli; brain channel is canonical

→ followup status: resolved, outcome: RESULT (loop closed)
```

A shorter close:

```
# pip sees an informational-with-a-question, reviews, nothing to do

[from:pip] [NO-ACTION ml-pip-20261004-214500] reviewed — nothing needed, timer stagger already handles it

→ followup status: resolved, outcome: NO-ACTION (loop closed)
```

## 9. Metrics

Source of truth: `followups.json` (`outcome` field, written by the harvester).

| Metric | Definition |
|---|---|
| **delivered** | `dm.py` reported `verified:true` with placement confirmed for the digest message (see dm-log) |
| **acked** | outcome ∈ {`ACK`, `CLAIM`} |
| **closed** | outcome ∈ {`RESULT`, `DECLINE`, `NO-ACTION`} |
| **stale** | still `pending` past timeout + nudges → escalated |
| **closure_rate** | `closed / actionable_delivered` |

Rules:
- Informational digests are excluded from every rate. They are measured as
  delivered, full stop.
- Actionable digests are measured as closed. A digest that is ACKed but never
  resolved counts as open until a closing verb arrives.
- `delivered` requires the placement confirmation, not just the `verified:true`
  flag (see the AGENTS.md placement-blindness lesson).

Reporting: `self_main_loop.py` `status` exposes `digest_health()` counts
(delivered/acked/closed/stale), surfaced through the existing Box
`main-loop/status` API. No new endpoint needed in phase 1.

## 10. Implementation notes

- `dm.py` — **no changes.** `--expect-reply`, job_id extraction from `[JOB …]`,
  followup registration, and placement verification already exist and are tested.
- `response-harvester.py` — extend the reply regex to verb-aware matching:
  `\[(ACK|CLAIM|RESULT|DECLINE|NO-ACTION)\s+([A-Za-z0-9_-]+)\]`; on match, resolve
  by job_id and record `outcome`. `ACK`/`CLAIM` → `acknowledged`;
  `RESULT`/`DECLINE`/`NO-ACTION` → `resolved` + outcome.
- `self_main_loop.py` — `compose_digest` classifies actionable vs informational;
  actionable embeds `[JOB ml-…]` + footer; `send_prompt` passes
  `--expect-reply --reply-timeout {3600|1800} --reply-nudges 2` for actionable only.
- Sweeper — verify it nudges only `status == "pending"` (no code change expected).

All changes follow review-then-commit. No new daemons, no new state files beyond
the existing `followups.json`.

---

*Companion docs: `DM-SPEC.md` (DM format), `THREAD-BOOKKEEPING.md` (pin/archive),
`WARP-EGRESS-FIX.md` (partition handling).*