@wowyuarm/dsh-agent-team 0.1.11 → 0.1.12

package/packages/agent-team/lib/ledger.js

@@ -1,14 +1,21 @@
 import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import { formatTeamTimestamp } from "./time-format.js";
+import { resolveBodyMentions } from "./mentions.js";
 /** Stable Human Member identity shared by every replay of one dshHome Team. */
 export const AGENT_TEAM_HUMAN_MEMBER_ID = 'member:human';
+/**
+ * The handle the Human is addressed by in Message bodies. The body parser and
+ * the Member directory both read this one constant, so a configurable display
+ * name has a single place to land instead of a hard-coded literal per surface.
+ */
+export const AGENT_TEAM_HUMAN_HANDLE = 'human';
 /** Idempotency identity of the one Host bootstrap operation. */
 export const AGENT_TEAM_INITIALIZE_REQUEST_ID = 'agent-team:initialize:v1';
 const HUMAN_ACTOR = Object.freeze({
     kind: 'human',
     memberId: AGENT_TEAM_HUMAN_MEMBER_ID,
-    handle: 'human',
+    handle: AGENT_TEAM_HUMAN_HANDLE,
 });
 /** Resolve the one Human authority owned by this Team. */
 export function agentTeamHumanActor() {
@@ -21,26 +28,32 @@ function emptyProjection() {
         messagesByRef: new Map(),
         attentionByThread: new Map(), previousSessions: new Map(), rolloverSeeds: new Map(),
         anchorByThread: new Map(), taskNumberByTask: new Map(), taskCountByChannel: new Map(), attentionThreadsByMember: new Map(),
+        threadsByWriter: new Map(),
         directMarkersByMember: new Map(), activityMarkersByMember: new Map(), observationsByThread: new Map() };
 }
-const EMPTY_PROGRESS_NUDGE_TARGETS = Object.freeze({
-    progress: Object.freeze([]),
-    claim: Object.freeze([]),
-});
 /** Exhaustiveness guard for the closed operation union: adding a kind must update every dispatch. */
 function assertUnhandledKind(operation) {
     throw new Error(`agent-team ledger does not handle operation kind '${operation.kind}'`);
 }
 /**
- * Opening-line preview for a direct-only Human Inbox row: the Thread anchor's
- * first line, trimmed, then capped at 120 characters with an explicit mark —
- * the same bound the Thread page applies to its Task title, so the row and
- * the page it opens never disagree about what a Thread is about.
+ * Opening-line preview for a Human Inbox row: the Thread anchor's first line,
+ * trimmed, then capped at 120 characters with an explicit mark — the same bound
+ * the Thread page applies to its Task title, so the row and the page it opens
+ * never disagree about what a Thread is about.
  */
 function boundedInboxPreview(body) {
     const firstLine = body.split('\n', 1)[0]?.trim() ?? '';
     return firstLine.length > 120 ? `${firstLine.slice(0, 119)}…` : firstLine;
 }
+/**
+ * How many Threads one Workspace's 「最近活跃」 slice may carry. It bounds what
+ * the Host hands over, not what the reader sees: the Client merges every
+ * visible Workspace's slice and trims the merged list to its own visible bound
+ * (`RECENT_ROWS_LIMIT`), which must stay at or below this one so no Workspace
+ * is cut short before the merge. The unread slice keeps its own `limit`
+ * request field.
+ */
+const RECENT_INBOX_LIMIT = 10;
 /**
  * Whether one operation's Inbox delta would change nothing. A read that finds
  * no unread fact for its reader and no marker to consume produces exactly this
@@ -439,80 +452,6 @@ export class AgentTeamLedger {
         }
         return active.sort((a, b) => a.claimRef.localeCompare(b.claimRef));
     }
-    /**
-     * Current progress-nudge candidacy for one Member: threads whose Thread
-     * progress reminder applies (active Claim, or following a taskless Thread)
-     * and tasks where the Claim reminder applies (following a still-`todo` Task
-     * with no Claim history for this Member). A deep read-only projection — the
-     * caller never re-derives attention, claim, task-resolution, or channel
-     * archive state. Archived channels and resolved tasks produce no candidacy;
-     * results are ordered by Thread revision descending, then threadRef.
-     */
-    progressNudgeTargets(memberId) {
-        const member = this.state.members.get(memberId);
-        if (member === undefined || member.state !== 'enabled')
-            return EMPTY_PROGRESS_NUDGE_TARGETS;
-        const progress = [];
-        const claim = [];
-        const seenProgress = new Set();
-        for (const claimRecord of this.state.claims.values()) {
-            if (claimRecord.owner !== memberId || claimRecord.state !== 'active')
-                continue;
-            const task = this.state.tasks.get(claimRecord.taskRef);
-            const thread = this.state.threads.get(claimRecord.threadRef);
-            if (task === undefined || thread === undefined || task.resolution !== 'open')
-                continue;
-            if (this.state.channels.get(task.channelRef)?.state === 'archived')
-                continue;
-            if (seenProgress.has(claimRecord.threadRef))
-                continue;
-            seenProgress.add(claimRecord.threadRef);
-            progress.push({ reason: 'active-claim', threadRef: claimRecord.threadRef, taskRef: claimRecord.taskRef });
-        }
-        for (const [threadRef, followers] of this.state.attentionByThread) {
-            if (!followers.has(memberId))
-                continue;
-            const thread = this.state.threads.get(threadRef);
-            if (thread === undefined)
-                continue;
-            const channelRef = this.state.channelRefByThread.get(threadRef);
-            if (channelRef === undefined || this.state.channels.get(channelRef)?.state === 'archived')
-                continue;
-            if (thread.taskRef === undefined) {
-                if (!seenProgress.has(threadRef)) {
-                    seenProgress.add(threadRef);
-                    progress.push({ reason: 'taskless-follower', threadRef });
-                }
-                continue;
-            }
-            // Claim reminder: only still-`todo` tasks with zero lifetime claims by
-            // this Member; once claimed (any state) the Member moved into the
-            // progress-reminder regime.
-            if (this.hasLifetimeClaimOnTask(memberId, thread.taskRef))
-                continue;
-            const task = this.state.tasks.get(thread.taskRef);
-            if (task === undefined || task.resolution !== 'open' || this.deriveTaskStatus(task.taskRef, this.state.claims.values()) !== 'todo')
-                continue;
-            claim.push({ threadRef, taskRef: thread.taskRef });
-        }
-        const byThreadRevision = (left, right) => {
-            const leftRevision = this.state.threads.get(left.threadRef)?.revision ?? 0;
-            const rightRevision = this.state.threads.get(right.threadRef)?.revision ?? 0;
-            return rightRevision - leftRevision || (left.threadRef < right.threadRef ? -1 : left.threadRef > right.threadRef ? 1 : 0);
-        };
-        return Object.freeze({
-            progress: Object.freeze(progress.sort(byThreadRevision)),
-            claim: Object.freeze(claim.sort(byThreadRevision)),
-        });
-    }
-    /** Whether this Member has ever held a Claim on the Task, in any state. */
-    hasLifetimeClaimOnTask(memberId, taskRef) {
-        for (const claim of this.state.claims.values()) {
-            if (claim.owner === memberId && claim.taskRef === taskRef)
-                return true;
-        }
-        return false;
-    }
     listMembers() {
         return Object.freeze([...this.state.members.values()]);
     }
@@ -620,12 +559,6 @@ export class AgentTeamLedger {
     }
     sendMessage(request) {
         return this.enqueue(async () => {
-            const recipients = this.normalizeRecipients(request.actor, request.recipients);
-            const existing = this.state.byRequest.get(request.requestId);
-            if (existing !== undefined) {
-                this.assertSameMessage(existing, request, recipients);
-                return this.resolved(this.messageResult(existing));
-            }
             const actor = this.assertActorForWorkspace(request.actor, request.workspaceId);
             const channel = this.requireActiveChannel(request.workspaceId, request.channelRef);
             if (actor.kind === 'member')
@@ -633,6 +566,15 @@ export class AgentTeamLedger {
             const body = request.body.trim();
             if (body === '')
                 throw new Error('message body must not be empty');
+            // Recipients are resolved before the request-id lookup: the stored
+            // operation carries the merged set, so a retry has to re-derive the same
+            // list for the collision check to prove it is the same request.
+            const recipients = this.mergeBodyMentions(actor.memberId, channel.channelRef, body, this.normalizeRecipients(request.actor, request.recipients));
+            const existing = this.state.byRequest.get(request.requestId);
+            if (existing !== undefined) {
+                this.assertSameMessage(existing, request, recipients);
+                return this.resolved(this.messageResult(existing));
+            }
             this.assertMentionTargets(channel, recipients);
             // Top-level Task creation is open to every actor: mentioned Members join
             // the new Thread as followers. Only existing-Thread invitations stay
@@ -667,32 +609,38 @@ export class AgentTeamLedger {
     }
     reply(request) {
         return this.enqueue(async () => {
-            const recipients = this.normalizeRecipients(request.actor, request.recipients);
-            const existing = this.state.byRequest.get(request.requestId);
-            if (existing !== undefined) {
-                this.assertSameReply(existing, request, recipients);
-                return this.resolved(this.replyResult(existing));
-            }
             const actor = this.assertActorForWorkspace(request.actor, request.workspaceId);
             const { task, thread, channelRef } = this.threadContextForActor(actor, request.workspaceId, request);
             const body = request.body.trim();
             if (body === '')
                 throw new Error('message body must not be empty');
-            this.assertMentionTargets(this.requireChannel(request.workspaceId, channelRef), recipients);
+            const channel = this.requireChannel(request.workspaceId, channelRef);
+            const recipients = this.mergeBodyMentions(actor.memberId, channelRef, body, this.normalizeRecipients(actor, request.recipients));
+            const existing = this.state.byRequest.get(request.requestId);
+            if (existing !== undefined) {
+                this.assertSameReply(existing, request, recipients);
+                return this.resolved(this.replyResult(existing, this.undeliverableRecipients(actor, thread.threadRef, recipients)));
+            }
+            this.assertMentionTargets(channel, recipients);
             const deferred = this.deferredThreadWrite(actor.memberId, task, thread, request.baseRevision);
             if (deferred !== undefined)
                 return this.resolved(deferred);
             if (task?.resolution === 'closed')
                 throw new Error(`Task '${task.taskRef}' is closed; reopen it before replying`);
-            const unfollowedAgents = recipients.filter(memberId => this.state.members.has(memberId) && !this.isFollowing(thread.threadRef, memberId));
-            if (unfollowedAgents.length > 0 && actor.kind === 'member') {
-                return this.resolved(this.memberNotFollowing(request.workspaceId, channelRef, unfollowedAgents, task, thread));
-            }
-            if (unfollowedAgents.length > 0 && request.confirmationToken === undefined) {
-                return this.resolved(this.issueConfirmation(request.actor, request.workspaceId, channelRef, body, recipients, task, thread));
+            // An Agent cannot invite into an existing Thread, so a body mention the
+            // Thread has never carried is dropped and reported back rather than
+            // failing the send. The Human keeps the confirmation step, which is what
+            // actually grants the invitation.
+            const undelivered = this.undeliverableRecipients(actor, thread.threadRef, recipients);
+            const delivered = undelivered.length === 0 ? recipients : recipients.filter(memberId => !undelivered.includes(memberId));
+            const unfollowedAgents = delivered.filter(memberId => this.state.members.has(memberId) && !this.isFollowing(thread.threadRef, memberId));
+            // A Member that once took part in this Thread is delivered to directly:
+            // re-joining a Thread it already belongs to is not an invitation.
+            if (unfollowedAgents.length > 0 && actor.kind === 'human' && request.confirmationToken === undefined) {
+                return this.resolved(this.issueConfirmation(request.actor, request.workspaceId, channelRef, body, delivered, task, thread));
             }
             if (request.confirmationToken !== undefined) {
-                this.consumeConfirmation(request.confirmationToken, request.actor, request.workspaceId, channelRef, task, thread, body, recipients);
+                this.consumeConfirmation(request.confirmationToken, request.actor, request.workspaceId, channelRef, task, thread, body, delivered);
             }
             const sequence = this.nextSequence();
             const base = this.operationBase(request, sequence);
@@ -704,15 +652,15 @@ export class AgentTeamLedger {
             });
             const nextThread = Object.freeze({ ...thread, revision: sequence });
             const started = unfollowedAgents.map(memberId => this.startAttention(memberId, thread.threadRef, sequence));
-            const inbox = this.messageInboxDelta(message, request.actor.memberId, recipients, started);
+            const inbox = this.messageInboxDelta(message, request.actor.memberId, delivered, started);
             const operation = Object.freeze({
                 ...base, kind: 'team/thread-replied',
                 data: Object.freeze({ workspaceId: request.workspaceId, baseRevision: request.baseRevision,
-                    mentions: recipients, message, ...(task === undefined ? {} : { task }), thread: nextThread, inbox }),
+                    mentions: delivered, message, ...(task === undefined ? {} : { task }), thread: nextThread, inbox }),
             });
             await this.table.put(operation.operationId, operation);
             this.apply(operation);
-            return this.committed(this.replyResult(operation));
+            return this.committed(this.replyResult(operation, undelivered));
         });
     }
     promoteThread(request) {
@@ -1085,16 +1033,21 @@ export class AgentTeamLedger {
         const limit = request.limit ?? 50;
         if (!Number.isInteger(limit) || limit < 1 || limit > 100)
             throw new Error('inbox limit must be an integer between 1 and 100');
-        // The Human direct-only slice serves the Client's mention queue: rows show
-        // only Threads with an unread mention, `totalUnreadCount` collapses to the
-        // direct total so a badge on this call cannot bypass follow unread, and
-        // each row carries its Channel display name plus the Thread's opening line
-        // so the Client renders without a Channel view per row. The ordinary
-        // (agent-facing) projection stays body-free.
-        const directOnly = request.directOnly === true;
-        const taskNumbers = directOnly ? this.taskNumbers(request.workspaceId) : undefined;
+        // One unread slice serves every reader: Threads the reader follows or
+        // holds a marker on, admitted whenever they hold an unread fact — mentions
+        // are counted inside it (`directCount`), never a separate admission rule.
+        // Every row carries its rendering material — Channel display name, Task
+        // ordinal, opening line, and the person the row's instant came from — so the
+        // Client renders a row without a Channel or Member view per row. Carrying
+        // the opening line on the agent-facing projection is
+        // safe: model-visible notifications read the refs and the facts, never this.
+        // A Human reader additionally receives the separate 「最近活跃」 slice below;
+        // `items` stays exactly the unread queue for every reader, so the badge
+        // totals and the agent-facing `team_inbox` result cannot drift with it.
+        const taskNumbers = this.taskNumbers(request.workspaceId);
         const items = [];
-        for (const threadRef of this.inboxCandidateThreads(authorized.memberId, directOnly)) {
+        const unreadThreads = new Set();
+        for (const threadRef of this.inboxCandidateThreads(authorized.memberId)) {
             const thread = this.state.threads.get(threadRef);
             if (thread === undefined)
                 continue;
@@ -1108,42 +1061,118 @@ export class AgentTeamLedger {
             const unread = this.unreadFor(authorized.memberId, thread.threadRef);
             if (unread.length === 0)
                 continue;
+            unreadThreads.add(thread.threadRef);
             const task = thread.taskRef === undefined ? undefined : this.state.tasks.get(thread.taskRef);
             const directCount = unread.filter(item => item.direct).length;
-            if (directOnly && directCount === 0)
-                continue;
             const attention = this.attentionFor(authorized.memberId, thread.threadRef);
             // Same snapshot, same source as newestSequence: the instant hangs off
             // the newest unread fact itself, never a second lookup that could
             // observe a different commit between the two reads.
             const newest = unread.at(-1).fact;
-            const taskNumber = directOnly && task !== undefined ? taskNumbers?.get(task.taskRef) : undefined;
+            const taskNumber = task === undefined ? undefined : taskNumbers.get(task.taskRef);
             items.push(Object.freeze({ channelRef,
-                ...(directOnly ? { channelName: this.state.channels.get(channelRef)?.name ?? '' } : {}),
+                channelName: this.state.channels.get(channelRef)?.name ?? '',
                 ...(task === undefined ? {} : { task }), ...(taskNumber === undefined ? {} : { taskNumber }), thread,
                 unreadCount: unread.length, directCount,
-                ...(directOnly ? { previewText: boundedInboxPreview(this.threadAnchor(thread.threadRef).body) } : {}),
-                newestSequence: newest.sequence, newestOccurredAt: newest.occurredAt, ...(attention === undefined ? {} : { attention }) }));
+                previewText: boundedInboxPreview(this.threadAnchor(thread.threadRef).body),
+                newestSequence: newest.sequence, newestOccurredAt: newest.occurredAt,
+                newestActor: this.inboxActorFor(newest), claimOwners: this.liveClaimOwners(task),
+                ...(attention === undefined ? {} : { attention }) }));
         }
         items.sort((left, right) => right.directCount - left.directCount || right.newestSequence - left.newestSequence || left.thread.threadRef.localeCompare(right.thread.threadRef));
         const selected = items.slice(0, limit);
-        return Object.freeze({ items: Object.freeze(selected),
-            totalUnreadCount: directOnly
-                ? items.reduce((sum, item) => sum + item.directCount, 0)
-                : items.reduce((sum, item) => sum + item.unreadCount, 0),
+        const recent = authorized.kind === 'human'
+            ? this.recentInboxItems(authorized.memberId, request.workspaceId, unreadThreads, taskNumbers)
+            : Object.freeze([]);
+        return Object.freeze({ items: Object.freeze(selected), recent,
+            totalUnreadCount: items.reduce((sum, item) => sum + item.unreadCount, 0),
             totalDirectCount: items.reduce((sum, item) => sum + item.directCount, 0) });
     }
+    /**
+     * The one person a row names: whoever committed the fact that row's instant
+     * came from — a Message's sender, an activity's actor — resolved to the handle
+     * the row draws. Resolving it here is what spares every Client row a Member
+     * view of its own, and a Member the roster no longer names still reads as
+     * themselves through their raw id rather than as nobody.
+     */
+    inboxActorFor(fact) {
+        return this.memberActor(fact.kind === 'message' ? fact.message.sender : fact.activity.actor);
+    }
+    /** One Member as a row draws them: the id carries the identity hue, the handle the initial. */
+    memberActor(memberId) {
+        return Object.freeze({ memberId, name: this.state.members.get(memberId)?.handle ?? memberId });
+    }
+    /**
+     * The people a Task still has on it, resolved the way a row draws them: owners
+     * of its live Claims, in claim order, deduped. A released Claim is not work,
+     * and a done or closed Task keeps its Claims as history rather than as
+     * presence — deliberately the same rule the Channel feed applies to the same
+     * Task, so 「谁在这个 Task 上」 never acquires a second definition.
+     */
+    liveClaimOwners(task) {
+        if (task === undefined || (task.status !== 'in_progress' && task.status !== 'in_review'))
+            return Object.freeze([]);
+        const owners = [];
+        for (const claim of this.claimsForTask(task.taskRef)) {
+            if (claim.state === 'released' || owners.includes(claim.owner))
+                continue;
+            owners.push(claim.owner);
+        }
+        return Object.freeze(owners.map(owner => this.memberActor(owner)));
+    }
+    /**
+     * The Human Inbox's 「最近活跃」 slice: the Threads this reader has written in
+     * — the durable way back into work instead of a mention-only queue.
+     * Participation is the whole admission rule: a reader who replied to somebody
+     * else's Thread is here whether or not they follow it, and so is one who
+     * started a Thread nobody has answered yet, because starting one is writing
+     * its anchor. Attention deliberately plays no part — it decides what notifies
+     * a reader (a reply does not implicitly follow a Thread), and reading it here
+     * as well is what once hid every Thread a reader had replied to without
+     * following. A Thread the reader later unfollowed stays: they did take part
+     * in it, and unfollowing stops the notifications, not the record. Every
+     * Thread still holding unread is excluded because the queue above already
+     * carries it, and the slice is newest-activity first, bounded by
+     * `RECENT_INBOX_LIMIT`. Rows are the same shape as unread rows with every
+     * count at zero — they are the same row to render.
+     */
+    recentInboxItems(memberId, workspaceId, unreadThreads, taskNumbers) {
+        const recent = [];
+        for (const threadRef of this.state.threadsByWriter.get(memberId) ?? []) {
+            if (unreadThreads.has(threadRef))
+                continue;
+            const thread = this.state.threads.get(threadRef);
+            if (thread === undefined)
+                continue;
+            const channelRef = this.channelRefForThread(thread.threadRef);
+            if (channelRef === undefined)
+                continue;
+            if (this.state.channels.get(channelRef)?.workspaceId !== workspaceId)
+                continue;
+            const facts = this.state.factsByThread.get(thread.threadRef) ?? [];
+            const newest = facts.at(-1);
+            if (newest === undefined)
+                continue;
+            const task = thread.taskRef === undefined ? undefined : this.state.tasks.get(thread.taskRef);
+            const taskNumber = task === undefined ? undefined : taskNumbers.get(task.taskRef);
+            recent.push(Object.freeze({ channelRef,
+                channelName: this.state.channels.get(channelRef)?.name ?? '',
+                ...(task === undefined ? {} : { task }), ...(taskNumber === undefined ? {} : { taskNumber }), thread,
+                unreadCount: 0, directCount: 0,
+                previewText: boundedInboxPreview(this.threadAnchor(thread.threadRef).body),
+                newestSequence: newest.sequence, newestOccurredAt: newest.occurredAt,
+                newestActor: this.inboxActorFor(newest), claimOwners: this.liveClaimOwners(task) }));
+        }
+        recent.sort((left, right) => right.newestSequence - left.newestSequence || left.thread.threadRef.localeCompare(right.thread.threadRef));
+        return Object.freeze(recent.slice(0, RECENT_INBOX_LIMIT));
+    }
     /**
      * Threads that can hold unread facts for one reader, from the per-reader
      * derived indexes: Attention follows plus direct and activity markers.
      * Every unread source is covered — ordinary unread requires Attention, and
-     * marker unread requires a marker — so no full Thread scan is needed. The
-     * direct-only slice needs only the direct-marker threads, since a row
-     * requires at least one direct unread.
+     * marker unread requires a marker — so no full Thread scan is needed.
      */
-    inboxCandidateThreads(memberId, directOnly) {
-        if (directOnly)
-            return this.state.directMarkersByMember.get(memberId)?.keys() ?? [];
+    inboxCandidateThreads(memberId) {
         const refs = new Set();
         for (const source of [this.state.attentionThreadsByMember.get(memberId), this.state.directMarkersByMember.get(memberId), this.state.activityMarkersByMember.get(memberId)]) {
             for (const threadRef of source?.keys() ?? [])
@@ -1839,7 +1868,10 @@ export class AgentTeamLedger {
             if (isThreadReadSnapshot(data)) {
                 // The pre-receipt form froze the whole picture, so its expected value
                 // is re-derived the same way it was written: from this record's prior
-                // projection only, never from the live one.
+                // projection only, never from the live one. That shape stays frozen —
+                // a field added after it, like the orientation count, is not compared
+                // here, because no stored legacy record carries it and inventing one
+                // would reject every upgrade of a ledger written before the field.
                 const expected = this.prepareReadFrom(projection, data.memberId, data.workspaceId, target);
                 const expectedData = Object.freeze({ workspaceId: data.workspaceId, memberId: data.memberId,
                     ...(expected.task === undefined ? {} : { task: expected.task }), thread: expected.thread, claims: expected.claims, anchor: expected.anchor,
@@ -2196,7 +2228,7 @@ export class AgentTeamLedger {
         // Top-level mentions are open to every actor; only a Member reply may not
         // pull an unfollowed Member into an existing Thread.
         if (operation.actor.kind === 'member' && operation.kind === 'team/thread-replied'
-            && mentionedAgents.some(memberId => !this.isFollowingFrom(projection, message.threadRef, memberId))) {
+            && mentionedAgents.some(memberId => !this.everParticipatedFrom(projection, message.threadRef, memberId))) {
             throw new Error('invalid Agent mention projection');
         }
         const started = operation.kind === 'team/message-sent'
@@ -2420,6 +2452,11 @@ export class AgentTeamLedger {
         // The ref index is written in this same step, so it is exactly the set of
         // replayed Messages: a validator lookup can never reach a later record.
         target.messagesByRef.set(message.messageRef, message);
+        // Participation is indexed per writer as the fact lands, so the Human
+        // recent slice asks who wrote where without scanning the whole ledger.
+        const written = target.threadsByWriter.get(message.sender) ?? new Set();
+        written.add(message.threadRef);
+        target.threadsByWriter.set(message.sender, written);
     }
     appendActivityFact(target, activity, occurredAt) {
         const fact = Object.freeze({ kind: 'activity', sequence: activity.sequence, activity, occurredAt });
@@ -2596,9 +2633,21 @@ export class AgentTeamLedger {
         const combined = [...background.map(fact => this.readFactFrom(projection, memberId, fact, false)), ...receipt.unread.slice(0, 20)]
             .sort((left, right) => left.fact.sequence - right.fact.sequence);
         const remainingUnreadCount = this.remainingUnreadAfter(projection, memberId, receipt);
+        // What this bounded read leaves behind it: the Thread facts that precede the
+        // watermark it reaches, which is where this reader now stands in the Thread
+        // and how much of it that position has never shown it. Anchoring on the
+        // watermark rather than on the response's own oldest fact is what keeps a
+        // returning reader honest — the background window starts at the Thread's
+        // first fact whenever the Thread is short enough to fit it, so measuring
+        // from the response would report nothing behind a reader that has in fact
+        // never read the Thread. Derived from the projection the read resolved
+        // against, like every other field of this picture, so a replay re-derives
+        // the same number.
+        const earlierFactCount = this.threadFactsFrom(projection, thread.threadRef)
+            .filter(fact => fact.sequence < receipt.readThroughSequence).length;
         return Object.freeze({ ...receipt, claims: task === undefined ? Object.freeze([]) : this.claimsForTaskFrom(projection, task.taskRef), anchor,
             anchorMentions: projection.mentionsByMessage.get(anchor.messageRef) ?? [],
-            facts: Object.freeze(combined), remainingUnreadCount });
+            facts: Object.freeze(combined), remainingUnreadCount, earlierFactCount });
     }
     readFactFrom(projection, memberId, fact, unread) {
         return Object.freeze({ fact, unread, direct: fact.kind === 'message'
@@ -2854,10 +2903,6 @@ export class AgentTeamLedger {
             }
         }
     }
-    memberNotFollowing(workspaceId, channelRef, memberIds, task, thread) {
-        return Object.freeze({ kind: 'member_not_following', workspaceId, channelRef, memberIds: Object.freeze(memberIds),
-            ...(task === undefined ? {} : { taskRef: task.taskRef }), ...(thread === undefined ? {} : { threadRef: thread.threadRef, revision: thread.revision }) });
-    }
     unreadRequired(task, thread, unread) {
         return Object.freeze({ kind: 'unread_required', ...(task === undefined ? {} : { taskRef: task.taskRef }), threadRef: thread.threadRef,
             revision: thread.revision, unreadCount: unread.length, directCount: unread.filter(item => item.direct).length });
@@ -2917,10 +2962,11 @@ export class AgentTeamLedger {
         return undefined;
     }
     /** Commit projections shared by the Message-sent and Thread-replied results. */
-    committedMessageResult(operation) {
+    committedMessageResult(operation, undelivered = []) {
         return { kind: 'committed', receipt: this.receipt(operation), message: operation.data.message,
             ...(operation.data.task === undefined ? {} : { task: operation.data.task }), thread: operation.data.thread, attention: operation.data.inbox.attention.set,
-            directMarkers: operation.data.inbox.directMarkers.added };
+            directMarkers: operation.data.inbox.directMarkers.added,
+            ...(undelivered.length === 0 ? {} : { undeliveredMentions: undelivered }) };
     }
     threadAnchor(threadRef) {
         return this.threadAnchorFrom(this.state, threadRef);
@@ -3193,6 +3239,68 @@ export class AgentTeamLedger {
             throw new Error(`${label} contains duplicate Member refs`);
         return Object.freeze([...unique].sort());
     }
+    /**
+     * Names a Message body may address in one Channel: every live Member of that
+     * Channel plus the Human. A name outside this set stays prose, which is what
+     * keeps an incidental name-drop from reaching someone the Channel cannot
+     * deliver to.
+     */
+    mentionCandidatesFor(channelRef) {
+        const candidates = [{ memberId: AGENT_TEAM_HUMAN_MEMBER_ID, handle: AGENT_TEAM_HUMAN_HANDLE }];
+        for (const member of this.state.members.values()) {
+            if (member.state === 'inactive' || member.state === 'archived')
+                continue;
+            if (!this.isChannelMember(channelRef, member.memberId))
+                continue;
+            candidates.push({ memberId: member.memberId, handle: member.handle });
+        }
+        return Object.freeze(candidates);
+    }
+    /**
+     * Merge the `@Handle` mentions authored in `body` into an explicit recipient
+     * set. Body mentions are the primary channel now: an Agent has no recipient
+     * parameter to forget, and the same scan serves Human input typed by hand.
+     * The result stays a plain recipient set, so every downstream projection —
+     * delivery markers, chip rendering, confirmation — is unchanged.
+     */
+    mergeBodyMentions(sender, channelRef, body, explicit) {
+        const candidates = this.mentionCandidatesFor(channelRef);
+        const resolution = resolveBodyMentions(body, candidates, sender);
+        // `@all` stands for its expansion as of this write: the Member set is
+        // snapshotted into the recipient list, so a later roster change cannot
+        // retroactively alter what this operation delivered.
+        const authored = resolution.all ? candidates.map(candidate => candidate.memberId) : resolution.memberIds;
+        const merged = new Set([...explicit, ...authored]);
+        merged.delete(sender);
+        return Object.freeze([...merged].sort());
+    }
+    /**
+     * Whether one Member has ever held Attention on one Thread. Committed Inbox
+     * deltas append a follow/unfollow observation, and the live index covers the
+     * Thread-creating Message whose initial Attention is never observed — so the
+     * two together answer "was this Member ever part of this Thread" without
+     * adding a second durable authority.
+     */
+    everParticipated(threadRef, memberId) {
+        return this.everParticipatedFrom(this.state, threadRef, memberId);
+    }
+    everParticipatedFrom(projection, threadRef, memberId) {
+        if (this.isFollowingFrom(projection, threadRef, memberId))
+            return true;
+        return (projection.observationsByThread.get(threadRef) ?? []).some(observation => observation.memberId === memberId);
+    }
+    /**
+     * Split the Agent recipients an existing Thread cannot deliver to: those the
+     * body named that the Thread has never carried. The send still commits — a
+     * text mention must never fail the write — and the author is told through the
+     * result, because inviting a Member into an existing Thread stays a Human
+     * decision.
+     */
+    undeliverableRecipients(actor, threadRef, recipients) {
+        if (actor.kind !== 'member')
+            return Object.freeze([]);
+        return Object.freeze(recipients.filter(memberId => this.state.members.has(memberId) && !this.everParticipated(threadRef, memberId)));
+    }
     normalizeDirection(direction) {
         return direction.normalize('NFKC').trim().replace(/\s+/gu, ' ').toLowerCase();
     }
@@ -3463,8 +3571,8 @@ export class AgentTeamLedger {
     messageResult(operation) {
         return Object.freeze(this.committedMessageResult(operation));
     }
-    replyResult(operation) {
-        return Object.freeze(this.committedMessageResult(operation));
+    replyResult(operation, undelivered = []) {
+        return Object.freeze(this.committedMessageResult(operation, undelivered));
     }
     claimResult(operation) {
         const attention = operation.data.inbox.attention.set.find(candidate => candidate.memberId === operation.data.claim.owner);
@@ -3494,6 +3602,7 @@ export class AgentTeamLedger {
         return Object.freeze({ ...(prepared.task === undefined ? {} : { task: prepared.task }), thread: prepared.thread,
             claims: prepared.claims, anchor: prepared.anchor, anchorMentions: prepared.anchorMentions, facts: prepared.facts,
             readThroughSequence: prepared.readThroughSequence, remainingUnreadCount: prepared.remainingUnreadCount,
+            earlierFactCount: prepared.earlierFactCount,
             ...(prepared.attention === undefined ? {} : { attention: prepared.attention }),
             consumedDirectMarkers: prepared.inbox.directMarkers.removed });
     }