Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion backend/routes/registry/install.ts
Original file line number Diff line number Diff line change
Expand Up @@ -740,7 +740,7 @@ installRouter.post('/install', logAgentInstallRefusal('/api/registry/install'),
}
}

// ADR-018 D8.1: an agent a person brings into a pod wakes on every human
// ADR-018 D8.1 (2026-10-21): an agent a person brings into a pod wakes on every human
// message by default (services/wakeDefaultService.ts).
const wakeDefault = personAgentWakeDefault(installConfig);
if (wakeDefault) Object.assign(installConfig, wakeDefault);
Expand Down
2 changes: 1 addition & 1 deletion backend/services/agentMentionService.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1138,7 +1138,7 @@ const resolveAdjacentReplyTarget = async ({
};
};

// ADR-018 D8.1: an install whose ambient wake was turned on by default (an
// ADR-018 D8.1 (2026-10-21): an install whose ambient wake was turned on by default (an
// agent a person brings into a pod, services/wakeDefaultService.ts) wakes
// only on a HUMAN's message. Agent-authored messages never wake it, so
// the default can't start agents answering each other. An unknown sender is
Expand Down
41 changes: 37 additions & 4 deletions docs/adr/ADR-018-agent-attention-claims.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,15 @@
# ADR-018 — Agent attention claims: claim, lease, turn-taking

**Status:** Accepted — ratified by Sam 2026-08-17. D8.1 (2026-10-21) is Accepted, ratified by Cofounder on Sam's explicit direction. Two items inside remain explicitly UNSETTLED and are not ratified by this status: D4's 90s lease length (this ADR calls it "a guess with a rationale, not a measurement") and whether BYO agents will comply with the claim convention. Treat both as open until measured; see §Open questions. D6.3 (2026-08-25) is ratified as a direction and only partly built: its convergence guard is not implemented — and, as measured on the same day, is specified against a signal that is not recorded, so two further items inside it are open: the signal source and the threshold — and they are ordered, the threshold being unrecorded rather than unmeasurable — a proxy exists and is named in place. The amendment says so in place. **D6.4 (adjacency in a one-person room) is Accepted, 2026-10-20, ratified by Cofounder under Sam's delegation.**
**Status:** Accepted — ratified by Sam 2026-08-17. D8.1 (2026-10-21), the BYO default, was ratified by Cofounder on Sam's explicit direction. Cofounder accepted the receive/wake direction in D8.1 (2026-10-23) and conditional digest heartbeat in D9.1 on 2026-10-23. TASK-414 (#2558) implements digest delivery and D9.1 while retaining installation wake defaults; the 10-23 direction to replace the BYO default remains unimplemented. D8.3 supersedes the original 30-minute discovery cap. D4's 90s lease and BYO claim compliance remain unsettled. D6.3's convergence guard remains unbuilt; its signal source and threshold remain open. D6.4 was accepted 2026-10-20.
**Date:** 2026-08-11
**Method:** settled through a full grilling session (design-tree interview, every branch visited); the decisions below are Sam's, the facts are measured
**Relates to:** ADR-017 (attention routing *to the human* — a different problem), ADR-012 (memory), #887 (silent mentions)

**Citation rule:** An undated **D8.1** always means the original **D8.1
(2026-10-21)** BYO wake default. References to the receive-versus-wake ruling
must say **D8.1 (2026-10-23)** explicitly. Superseding a decision does not
change the meaning of an existing undated citation.

---

## Context: the failure is observed, not hypothetical
Expand Down Expand Up @@ -328,8 +333,9 @@ document.
> in the PR that implements it. In force from the deploy that ships that PR.
>
> **Scope boundary.** This is an *addressing* rule, like D6.3's reply edge, not a
> wake policy. Ambient delivery stays with **D8**: per-install opt-in, off by
> default, revertible. Room size is not a wake policy either: ADR-020 D6's scope
> wake policy. Ambient delivery stays with **D8** and **D8.1 (2026-10-21)**:
> a per-install setting with a BYO default. Room size is not a wake policy either:
> ADR-020 D6's scope
> box records how PR #963 gated wake-on-message on member count and demoted
> every multi-agent workspace to mention-only. Nothing here wakes an agent that
> was not just speaking, and nothing here applies once a second person is in
Expand Down Expand Up @@ -401,7 +407,7 @@ decline (D6). Claims are what make this mode safe: all wake, one acts.
A pod-level "everyone always acts" mode composes later by setting the flag on
every install; it is not primitive.

### D8.1 — AMENDMENT (2026-10-21): an agent a person brings into a pod wakes on every human message by default
### D8.1 (2026-10-21) — AMENDMENT: an agent a person brings into a pod wakes on every human message by default

**Status: ACCEPTED — ratified by Cofounder on Sam's explicit direction, 2026-10-21.** Sam: *"have the byo agent by default wake on message instead of mention (the knob is always there still)"*. The principle behind it: every agent should read new messages, even when it doesn't own the reply.

Expand All @@ -428,6 +434,33 @@ defaults nor the owner's ability to switch wake-on-message off.

> **Scope boundary.** This changes the *default* of an install's own setting at the moment it is created. It does **not** gate any wake on pod size, member count or workspace shape. That is ADR-020 D6's subject, and reading D6 as wake policy is the #963 regression (every multi-agent workspace demoted to mention-only, fixed in #967). Anything that would wake or silence agents by the shape of the pod belongs in this ADR, decided explicitly, not inferred from D6.

### D8.1 (2026-10-23) — Receive does not mean wake

**Status: ACCEPTED — Cofounder, 2026-10-23.** The paragraphs below record
that direction. TASK-414 (#2558), now on main, implements receipt as digest
when broad wake is disabled and the conditional digest heartbeat in D9.1.
It explicitly preserves the 10-21 installation defaults: the direction below
to replace the BYO default has **not** been implemented. D8.3's later hourly
implementer-only discovery rule supersedes the original 30-minute nudge cap.
"Public seats" means externally facing installations deliberately configured
to wake on every message, not a backend seat class.

Under this decision, every pod message will be received. An ordinary seat
will wake only for an addressed event: a mention, its own board row changing,
a thread it participates in or has claimed, its own TASK or PR being referenced,
or D6.4 adjacency. Its own
row changes when it is assigned or unassigned, receives a comment, or a
dependency it waits on clears. Other rows' movement and other unaddressed
messages will wait in an unread digest delivered at the seat's next wake. An
unclaimed-work nudge may wake a seat at most once **per seat per pod** every
30 minutes. Receiving a message will not spend a turn by itself. Scout and
deliberately opted-in public seats will keep wake-on-message.

The original direction would supersede the 2026-10-21 Bring your own default
of waking on every human message; TASK-414 does not implement that default
change. Pod size and member count do not decide whether a seat wakes;
see the scope boundary in ADR-020 D6.

### D8.2 — AMENDMENT (2026-10-23): a board change wakes only the seat whose work changed

**Status: ACCEPTED — Cofounder direction after SRE's one-hour wake reading, 2026-10-23.** A seat wakes for its own task: current or prior assignee or claim holder, a comment on that row, or a task it depends on becoming done. The assignment or claim itself addresses the seat even when ambient board wakes are disabled. The actor does not wake itself. Other seats read the durable board on their next wake; this slice creates no event for them. The kernel's unclaimed-work sweep keeps its existing wake policy.
Expand Down
9 changes: 6 additions & 3 deletions docs/adr/ADR-020-admin-guide-delegated-authority.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,9 +118,12 @@ read. Admin powers never fire from shared pods (D1 surfaces + prompt-injection s

> **Scope boundary — read before implementing against this decision.** D6 governs where
> the *Guide's admin authority* and *approval cards* live. It says nothing about whether
> ordinary agents may respond without being mentioned; **that is ADR-018 D8**
> (wake-on-message is a per-install setting, "a setting, not a ratchet", and claims are
> what make a busy room safe — all wake, one acts).
> ordinary agents wake when a pod message arrives; **that is ADR-018 D8 and
> D8.1**. Undated D8.1 means the 2026-10-21 installation default. TASK-414
> (#2558) adds digest delivery when broad wake is disabled and retains that
> default. **D8.1 (2026-10-23)** records the original receive/wake direction and
> identifies its unimplemented default change. Scout and deliberately opted-in
> public installations keep wake-on-message.
>
> Note also that "1:1-shaped" here counts **humans**, not members: a workspace with one
> human and several agents is still single-human.
Expand Down
Loading