@wowyuarm/dsh-agent-team 0.1.6 → 0.1.8

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

@@ -19,6 +19,10 @@ function emptyProjection() {
         orderedFacts: [], factsByThread: new Map(), channelRefByThread: new Map(), mentionsByMessage: new Map(), messageCountByThread: new Map(),
         attentionByThread: 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}'`);
@@ -97,7 +101,7 @@ export class AgentTeamLedger {
                 this.assertJoinableMember(request.workspaceId, memberId);
             const sequence = this.nextSequence();
             const channel = Object.freeze({
-                channelRef: this.ref('channel'), workspaceId: request.workspaceId, name, description, createdAtSequence: sequence,
+                channelRef: this.ref('channel'), workspaceId: request.workspaceId, name, description, createdAtSequence: sequence, state: 'active',
             });
             const operation = Object.freeze({
                 ...this.operationBase(request, sequence), kind: 'team/channel-created',
@@ -121,7 +125,7 @@ export class AgentTeamLedger {
             const description = request.description.trim();
             if (name === '')
                 throw new Error('channel name must not be empty');
-            const channel = Object.freeze({ ...this.requireChannel(request.workspaceId, request.channelRef), name, description });
+            const channel = Object.freeze({ ...this.requireActiveChannel(request.workspaceId, request.channelRef), name, description });
             const operation = Object.freeze({
                 ...this.operationBase(request, this.nextSequence()), kind: 'team/channel-updated',
                 data: Object.freeze({ workspaceId: request.workspaceId, channel }),
@@ -150,7 +154,7 @@ export class AgentTeamLedger {
             // still drivable through its DM view, and joins Channels later.
             const channelRefs = this.normalizeUnique(request.channelRefs, 'initial Member Channels');
             for (const channelRef of channelRefs)
-                this.requireChannel(request.workspaceId, channelRef);
+                this.requireActiveChannel(request.workspaceId, channelRef);
             this.assertHandleAvailable(request.workspaceId, handle);
             this.assertModelSelection(request.member.model);
             this.assertCapabilities(request.member.capabilities);
@@ -180,6 +184,8 @@ export class AgentTeamLedger {
             const prior = this.requireMember(request.memberId);
             if (prior.state === 'inactive')
                 throw new Error(`Agent Member '${prior.memberId}' is inactive and can no longer be edited`);
+            if (prior.state === 'archived')
+                throw new Error(`Agent Member '${prior.memberId}' is archived and can no longer be edited`);
             const handle = request.handle.trim();
             const description = request.description.trim();
             if (handle === '')
@@ -244,6 +250,80 @@ export class AgentTeamLedger {
     getMember(memberId) {
         return this.state.members.get(memberId);
     }
+    /**
+     * 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()]);
     }
@@ -255,7 +335,7 @@ export class AgentTeamLedger {
                 return this.resolved(this.joinResult(existing));
             }
             this.assertHumanActor(request.actor);
-            const channel = this.requireChannel(request.workspaceId, request.channelRef);
+            const channel = this.requireActiveChannel(request.workspaceId, request.channelRef);
             const member = this.requireMember(request.memberId);
             if (member.workspaceId !== request.workspaceId)
                 throw new Error('Member and Channel must belong to one Workspace');
@@ -307,6 +387,48 @@ export class AgentTeamLedger {
             return this.committed(this.channelMemberRemovalResult(operation));
         });
     }
+    /**
+     * Archive one Channel: hidden from every surface, facts kept recoverable.
+     * Every active Claim on the Channel's Threads releases with one public
+     * Activity per (owner, Thread), and every Member's Attention and markers
+     * for those Threads clear — a hidden Channel must not leave Tasks stuck in
+     * progress behind it or phantom unread counts.
+     */
+    archiveChannel(request) {
+        return this.enqueue(async () => {
+            const existing = this.state.byRequest.get(request.requestId);
+            if (existing !== undefined) {
+                this.assertSameChannelArchival(existing, request);
+                return this.resolved(this.channelArchivalResult(existing));
+            }
+            this.assertHumanActor(request.actor);
+            const channel = this.requireChannel(request.workspaceId, request.channelRef);
+            if (channel.state === 'archived')
+                throw new Error(`Channel '${channel.channelRef}' is already archived`);
+            const nextChannel = Object.freeze({ ...channel, state: 'archived' });
+            const threadRefs = this.channelThreadRefs(channel.channelRef);
+            const releasedClaims = [...this.state.claims.values()]
+                .filter(claim => claim.state === 'active' && threadRefs.has(claim.threadRef))
+                .map(claim => Object.freeze({ ...claim, state: 'released' }));
+            const nextClaims = new Map(this.state.claims);
+            for (const claim of releasedClaims)
+                nextClaims.set(claim.claimRef, claim);
+            const sequence = this.nextSequence();
+            const owners = [...new Set(releasedClaims.map(claim => claim.owner))].sort();
+            const activities = Object.freeze(owners.flatMap(owner => this.releaseSummaries(releasedClaims.filter(claim => claim.owner === owner), owner, sequence)));
+            const threads = this.threadsForActivities(activities);
+            const tasks = this.tasksForClaims(releasedClaims, nextClaims);
+            const inbox = this.channelArchivalInbox(threadRefs);
+            const operation = Object.freeze({
+                ...this.operationBase(request, sequence), kind: 'team/channel-archived',
+                data: Object.freeze({ workspaceId: request.workspaceId, channel: nextChannel,
+                    claims: Object.freeze(releasedClaims), activities, tasks, threads, inbox }),
+            });
+            await this.table.put(operation.operationId, operation);
+            this.apply(operation);
+            return this.committed(this.channelArchivalResult(operation));
+        });
+    }
     sendMessage(request) {
         return this.enqueue(async () => {
             const recipients = this.normalizeRecipients(request.actor, request.recipients);
@@ -316,7 +438,7 @@ export class AgentTeamLedger {
                 return this.resolved(this.messageResult(existing));
             }
             const actor = this.assertActorForWorkspace(request.actor, request.workspaceId);
-            const channel = this.requireChannel(request.workspaceId, request.channelRef);
+            const channel = this.requireActiveChannel(request.workspaceId, request.channelRef);
             if (actor.kind === 'member')
                 this.requireMemberChannel(this.requireMember(actor.memberId), channel.channelRef);
             const body = request.body.trim();
@@ -474,7 +596,7 @@ export class AgentTeamLedger {
             else {
                 if (request.direction !== undefined)
                     throw new Error(`${request.action} action does not accept direction`);
-                const previous = request.claimRef === undefined ? undefined : this.state.claims.get(request.claimRef);
+                const previous = request.claimRef === undefined ? undefined : this.state.claims.get(this.requireRefKey(this.state.claims, request.claimRef, 'claim', 'Claim'));
                 if (previous === undefined) {
                     throw new Error(`unknown Claim '${request.claimRef ?? ''}'${request.claimRef === undefined ? '' : this.unknownRefHint(request.claimRef, 'claim', 'Claim')}`);
                 }
@@ -589,7 +711,9 @@ export class AgentTeamLedger {
             const activities = this.releaseSummaries(releasedClaims, member.memberId, sequence);
             const threads = this.threadsForActivities(activities);
             const tasks = this.tasksForClaims(releasedClaims, projectedClaims);
-            const threadRefs = new Set([...this.state.tasks.values()].map(task => task.threadRef));
+            // The Member leaves entirely, so Attention and markers clear on every
+            // Thread — taskless ones too — matching the replay validator's scope.
+            const threadRefs = new Set(this.state.threads.keys());
             const inbox = this.removeMemberThreadInbox(member.memberId, threadRefs);
             const operation = Object.freeze({
                 ...this.operationBase(request, sequence), kind: 'team/member-removed',
@@ -601,6 +725,49 @@ export class AgentTeamLedger {
             return this.committed(this.removalResult(operation));
         });
     }
+    /**
+     * Archive one Member: hidden from every surface, data kept recoverable.
+     * The release shape matches removal — active Claims release with public
+     * Activities and the Member's Attention/markers clear — because a hidden
+     * Member must not leave Tasks stuck in progress or phantom unread counts.
+     */
+    archiveMember(request) {
+        return this.enqueue(async () => {
+            const existing = this.state.byRequest.get(request.requestId);
+            if (existing !== undefined) {
+                this.assertSameArchival(existing, request);
+                return this.resolved(this.archivalResult(existing));
+            }
+            this.assertHumanActor(request.actor);
+            const member = this.requireMember(request.memberId);
+            if (member.state === 'inactive')
+                throw new Error(`Agent Member '${member.memberId}' is already inactive`);
+            if (member.state === 'archived')
+                throw new Error(`Agent Member '${member.memberId}' is already archived`);
+            const nextMember = Object.freeze({ ...member, state: 'archived' });
+            const releasedClaims = [...this.state.claims.values()].filter(claim => claim.owner === member.memberId && claim.state === 'active')
+                .map(claim => Object.freeze({ ...claim, state: 'released' }));
+            const projectedClaims = new Map(this.state.claims);
+            for (const claim of releasedClaims)
+                projectedClaims.set(claim.claimRef, claim);
+            const sequence = this.nextSequence();
+            const activities = this.releaseSummaries(releasedClaims, member.memberId, sequence);
+            const threads = this.threadsForActivities(activities);
+            const tasks = this.tasksForClaims(releasedClaims, projectedClaims);
+            // The Member leaves entirely, so Attention and markers clear on every
+            // Thread — taskless ones too — matching the replay validator's scope.
+            const threadRefs = new Set(this.state.threads.keys());
+            const inbox = this.removeMemberThreadInbox(member.memberId, threadRefs);
+            const operation = Object.freeze({
+                ...this.operationBase(request, sequence), kind: 'team/member-archived',
+                data: Object.freeze({ member: nextMember, claims: Object.freeze(releasedClaims), activities, tasks, threads, inbox }),
+            });
+            await this.table.put(operation.operationId, operation);
+            this.apply(operation);
+            this.confirmations.clear();
+            return this.committed(this.archivalResult(operation));
+        });
+    }
     changeAttention(request) {
         return this.enqueue(async () => {
             const existing = this.state.byRequest.get(request.requestId);
@@ -808,7 +975,7 @@ export class AgentTeamLedger {
                     memberId: next.memberId, action: 'follow' }));
             }
         }
-        return Object.freeze({ items: Object.freeze(observations.slice(-limit)) });
+        return Object.freeze({ items: Object.freeze(observations.slice(-limit)), followers: Object.freeze([...current.keys()]) });
     }
     /** Every operation carrying an inbox delta drives the Inbox projection; the payload shape decides, not a per-kind list. */
     attentionDelta(operation) {
@@ -857,8 +1024,13 @@ export class AgentTeamLedger {
         const numbers = this.taskNumbers(workspaceId);
         const resolved = [];
         for (const taskRef of taskRefs) {
-            const task = this.state.tasks.get(taskRef);
-            if (task === undefined || this.state.channels.get(task.channelRef)?.workspaceId !== workspaceId)
+            const key = this.uniqueRefKey(this.state.tasks, taskRef, 'task');
+            const task = key === undefined ? undefined : this.state.tasks.get(key);
+            const channel = task === undefined ? undefined : this.state.channels.get(task.channelRef);
+            // Archived Channels do not exist on Team API surfaces: their Tasks stop
+            // resolving, so live message bodies render the refs as plain
+            // non-navigable text through the existing unknown-ref path.
+            if (task === undefined || channel?.workspaceId !== workspaceId || channel?.state === 'archived')
                 continue;
             resolved.push(Object.freeze({ taskRef: task.taskRef, channelRef: task.channelRef, threadRef: task.threadRef, taskNumber: numbers.get(task.taskRef) ?? 0 }));
         }
@@ -880,7 +1052,7 @@ export class AgentTeamLedger {
                 throw new Error('Member cannot view another Workspace');
         }
         if (request.channelRef !== undefined) {
-            this.requireChannel(request.workspaceId, request.channelRef);
+            this.requireActiveChannel(request.workspaceId, request.channelRef);
             if (memberId !== undefined && !this.isChannelMember(request.channelRef, memberId))
                 throw new Error(`Agent Member '${memberId}' is not authorized for Channel '${request.channelRef}'`);
         }
@@ -891,12 +1063,14 @@ export class AgentTeamLedger {
                 throw new Error(`unknown Thread ref '${request.threadRef}'`);
             if (this.state.channels.get(channelRef)?.workspaceId !== request.workspaceId)
                 throw new Error(`Thread '${request.threadRef}' does not belong to Workspace '${request.workspaceId}'`);
+            this.assertThreadChannelActive(channelRef);
             if (request.channelRef !== undefined && channelRef !== request.channelRef)
                 throw new Error(`Thread '${request.threadRef}' does not belong to Channel '${request.channelRef}'`);
             if (memberId !== undefined && !this.isChannelMember(channelRef, memberId))
                 throw new Error(`Agent Member '${memberId}' is not authorized for Channel '${channelRef}'`);
         }
         const channels = [...this.state.channels.values()].filter(channel => channel.workspaceId === request.workspaceId
+            && channel.state !== 'archived'
             && (memberId === undefined || this.isChannelMember(channel.channelRef, memberId)));
         const channelRefs = new Set(channels.map(channel => channel.channelRef));
         const allFacts = this.state.orderedFacts.filter(fact => {
@@ -931,7 +1105,10 @@ export class AgentTeamLedger {
         return Object.freeze({
             humanMemberId: initialization.data.humanMemberId,
             channels: Object.freeze(channels),
-            members: Object.freeze([...this.state.memberships.entries()].filter(([channelRef]) => channelRefs.has(channelRef)).flatMap(([channelRef, ids]) => [...ids].filter(id => this.state.members.get(id)?.state !== 'inactive').sort().map(memberId => Object.freeze({ channelRef, memberId })))),
+            members: Object.freeze([...this.state.memberships.entries()].filter(([channelRef]) => channelRefs.has(channelRef)).flatMap(([channelRef, ids]) => [...ids].filter(id => {
+                const state = this.state.members.get(id)?.state;
+                return state !== 'inactive' && state !== 'archived';
+            }).sort().map(memberId => Object.freeze({ channelRef, memberId })))),
             tasks: Object.freeze(visibleTasks),
             threads: Object.freeze([...this.state.threads.values()].filter(thread => {
                 const channelRef = this.channelRefForThread(thread.threadRef);
@@ -981,6 +1158,20 @@ export class AgentTeamLedger {
             case 'team/member-updated':
             case 'team/member-removed':
                 return [{ kind: 'workspace', workspaceId: operation.data.member.workspaceId }];
+            case 'team/member-archived': {
+                // Claim releases are thread-visible facts: open Channel and Thread
+                // pages refetch alongside the workspace-wide roster change.
+                const channelByTask = new Map(operation.data.tasks.map(task => [task.taskRef, task.channelRef]));
+                const scopes = [{ kind: 'workspace', workspaceId: operation.data.member.workspaceId }];
+                for (const activity of operation.data.activities) {
+                    scopes.push({ kind: 'thread', threadRef: activity.threadRef });
+                    const channelRef = channelByTask.get(activity.taskRef);
+                    if (channelRef !== undefined && !scopes.some(scope => scope.kind === 'channel' && scope.channelRef === channelRef)) {
+                        scopes.push({ kind: 'channel', channelRef });
+                    }
+                }
+                return scopes;
+            }
             case 'team/channel-member-added':
                 return [{ kind: 'workspace', workspaceId: operation.data.workspaceId }, { kind: 'channel', channelRef: operation.data.channelRef }];
             case 'team/channel-member-removed': {
@@ -998,6 +1189,15 @@ export class AgentTeamLedger {
                 }
                 return scopes;
             }
+            case 'team/channel-archived': {
+                const scopes = [
+                    { kind: 'workspace', workspaceId: operation.data.workspaceId },
+                    { kind: 'channel', channelRef: operation.data.channel.channelRef },
+                ];
+                for (const activity of operation.data.activities)
+                    scopes.push({ kind: 'thread', threadRef: activity.threadRef });
+                return scopes;
+            }
             case 'team/message-sent':
             case 'team/thread-replied':
                 return [{ kind: 'channel', channelRef: operation.data.message.channelRef }, { kind: 'thread', threadRef: operation.data.message.threadRef }];
@@ -1062,7 +1262,9 @@ export class AgentTeamLedger {
             case 'team/thread-attention-changed':
                 return [operation.data.thread.threadRef];
             case 'team/channel-member-removed':
+            case 'team/channel-archived':
             case 'team/member-removed':
+            case 'team/member-archived':
                 return operation.data.activities.map(activity => activity.threadRef);
             case 'team/initialized':
             case 'team/channel-created':
@@ -1209,7 +1411,8 @@ export class AgentTeamLedger {
             assertHuman();
             const prior = projection.channels.get(operation.data.channel.channelRef);
             if (prior === undefined || prior.workspaceId !== operation.data.workspaceId
-                || operation.data.channel.workspaceId !== prior.workspaceId || operation.data.channel.createdAtSequence !== prior.createdAtSequence) {
+                || operation.data.channel.workspaceId !== prior.workspaceId || operation.data.channel.createdAtSequence !== prior.createdAtSequence
+                || operation.data.channel.state !== prior.state) {
                 throw new Error('invalid Channel update');
             }
             return;
@@ -1217,7 +1420,7 @@ export class AgentTeamLedger {
         if (operation.kind === 'team/member-updated') {
             assertHuman();
             const prior = projection.members.get(operation.data.member.memberId);
-            if (prior === undefined || prior.state === 'inactive' || operation.data.member.state !== prior.state
+            if (prior === undefined || prior.state === 'inactive' || prior.state === 'archived' || operation.data.member.state !== prior.state
                 || operation.data.member.sessionId !== prior.sessionId || operation.data.member.workspaceId !== prior.workspaceId
                 || operation.data.member.presetId !== prior.presetId
                 || operation.data.member.privateMemoryPath !== prior.privateMemoryPath)
@@ -1250,6 +1453,18 @@ export class AgentTeamLedger {
             this.validateReleaseCleanup(operation.data, projection, member.memberId, threadRefs, operation.sequence, refs);
             return;
         }
+        if (operation.kind === 'team/channel-archived') {
+            assertHuman();
+            const prior = projection.channels.get(operation.data.channel.channelRef);
+            if (prior === undefined || prior.state !== 'active' || operation.data.channel.state !== 'archived'
+                || operation.data.channel.workspaceId !== prior.workspaceId || operation.data.workspaceId !== prior.workspaceId
+                || operation.data.channel.name !== prior.name || operation.data.channel.description !== prior.description
+                || operation.data.channel.createdAtSequence !== prior.createdAtSequence)
+                throw new Error('invalid Channel archival');
+            const threadRefs = new Set([...projection.threads.keys()].filter(threadRef => this.channelRefForThreadFrom(projection, threadRef) === prior.channelRef));
+            this.validateChannelArchivalCleanup(operation.data, projection, threadRefs, operation.sequence, refs);
+            return;
+        }
         if (operation.kind === 'team/member-removed') {
             assertHuman();
             const prior = projection.members.get(operation.data.member.memberId);
@@ -1259,6 +1474,15 @@ export class AgentTeamLedger {
             this.validateReleaseCleanup(operation.data, projection, prior.memberId, threadRefs, operation.sequence, refs);
             return;
         }
+        if (operation.kind === 'team/member-archived') {
+            assertHuman();
+            const prior = projection.members.get(operation.data.member.memberId);
+            if (prior === undefined || (prior.state !== 'enabled' && prior.state !== 'suspended') || operation.data.member.state !== 'archived' || !this.sameMemberIdentity(prior, operation.data.member))
+                throw new Error('invalid Member archival');
+            const threadRefs = new Set(projection.threads.keys());
+            this.validateReleaseCleanup(operation.data, projection, prior.memberId, threadRefs, operation.sequence, refs);
+            return;
+        }
         if (operation.kind === 'team/thread-attention-changed') {
             const actor = operation.actor.kind === 'member' ? assertMember() : (assertHuman(), undefined);
             if (operation.data.memberId !== operation.actor.memberId)
@@ -1581,6 +1805,68 @@ export class AgentTeamLedger {
             throw new Error('invalid Member inbox cleanup');
         this.validateInboxDelta(data.inbox, projection, refs);
     }
+    /** Replay validation of one Channel archival's release snapshot across every owner. */
+    validateChannelArchivalCleanup(data, projection, threadRefs, sequence, refs) {
+        const releasedClaims = [...projection.claims.values()]
+            .filter(claim => claim.state === 'active' && threadRefs.has(claim.threadRef))
+            .map(claim => Object.freeze({ ...claim, state: 'released' }));
+        if (data.claims.length !== releasedClaims.length || data.claims.some((claim, index) => {
+            const expected = releasedClaims[index];
+            return expected === undefined || !this.sameClaim(expected, claim);
+        }))
+            throw new Error('invalid released Claim projection');
+        // One activity per (owner, Thread), owners sorted like the commit path.
+        const byOwner = new Map();
+        for (const claim of releasedClaims) {
+            const byThread = byOwner.get(claim.owner) ?? new Map();
+            byOwner.set(claim.owner, byThread);
+            byThread.set(claim.threadRef, [...(byThread.get(claim.threadRef) ?? []), claim]);
+        }
+        const expectedActivities = [...byOwner.keys()].sort().flatMap(owner => [...byOwner.get(owner).entries()].map(([threadRef, claims]) => ({
+            kind: 'claims_released', taskRef: claims[0].taskRef, threadRef, actor: owner, sequence,
+            claimRefs: claims.map(claim => claim.claimRef).sort(),
+        })));
+        if (data.activities.length !== expectedActivities.length || data.activities.some((activity, index) => {
+            const expected = expectedActivities[index];
+            return expected === undefined || activity.kind !== expected.kind || activity.taskRef !== expected.taskRef
+                || activity.threadRef !== expected.threadRef || activity.actor !== expected.actor || activity.sequence !== expected.sequence
+                || !this.sameList(activity.claimRefs, expected.claimRefs);
+        }))
+            throw new Error('invalid released Claim activities');
+        for (const claim of data.claims) {
+            const prior = projection.claims.get(claim.claimRef);
+            if (prior === undefined)
+                throw new Error('invalid released Claim reference');
+        }
+        for (const activity of data.activities)
+            this.addRef(refs, activity.activityRef);
+        const projectedClaims = new Map(projection.claims);
+        for (const claim of releasedClaims)
+            projectedClaims.set(claim.claimRef, claim);
+        const expectedTasks = [...new Set(releasedClaims.map(claim => claim.taskRef))].map(taskRef => {
+            const task = projection.tasks.get(taskRef);
+            return Object.freeze({ ...task, status: this.deriveResolvedTaskStatus(task, projectedClaims.values()) });
+        });
+        const expectedThreads = expectedActivities.map(activity => {
+            const thread = projection.threads.get(activity.threadRef);
+            return Object.freeze({ ...thread, revision: sequence });
+        });
+        if (!isDeepStrictEqual(data.tasks, expectedTasks) || !isDeepStrictEqual(data.threads, expectedThreads)) {
+            throw new Error('invalid released Claim Task or Thread projection');
+        }
+        // Attention and marker cleanup covers EVERY Member on the archived Threads.
+        const expectedAttention = [...projection.attention.values()]
+            .filter(attention => threadRefs.has(attention.threadRef))
+            .map(attention => ({ memberId: attention.memberId, threadRef: attention.threadRef }));
+        const expectedMarkers = [...projection.directMarkers.values()]
+            .filter(marker => threadRefs.has(marker.threadRef));
+        const expectedActivityMarkers = [...projection.activityMarkers.values()]
+            .filter(marker => threadRefs.has(marker.threadRef));
+        const expectedInbox = this.inboxDelta([], expectedAttention, [], expectedMarkers, [], expectedActivityMarkers);
+        if (!isDeepStrictEqual(data.inbox, expectedInbox))
+            throw new Error('invalid Channel archival inbox cleanup');
+        this.validateInboxDelta(data.inbox, projection, refs);
+    }
     validateMessageInbox(operation, projection) {
         const { message, mentions } = operation.data;
         const mentionedAgents = mentions.filter(memberId => projection.members.has(memberId));
@@ -1612,7 +1898,7 @@ export class AgentTeamLedger {
         if (memberId === AGENT_TEAM_HUMAN_MEMBER_ID)
             return true;
         const member = projection.members.get(memberId);
-        return member !== undefined && member.state !== 'inactive'
+        return member !== undefined && member.state !== 'inactive' && member.state !== 'archived'
             && projection.channels.get(channelRef)?.workspaceId === member.workspaceId
             && this.isChannelMemberFrom(projection, channelRef, memberId);
     }
@@ -1679,6 +1965,22 @@ export class AgentTeamLedger {
             this.applyInboxDelta(target, operation.data.inbox);
             return;
         }
+        if (operation.kind === 'team/channel-archived') {
+            // Archival keeps Memberships: hidden state, not departure — a future
+            // restore returns every Member to the Channel. Visibility filters by
+            // channel state instead.
+            target.channels.set(operation.data.channel.channelRef, operation.data.channel);
+            for (const claim of operation.data.claims)
+                target.claims.set(claim.claimRef, claim);
+            for (const activity of operation.data.activities)
+                this.appendActivityFact(target, activity);
+            for (const task of operation.data.tasks)
+                target.tasks.set(task.taskRef, task);
+            for (const thread of operation.data.threads)
+                target.threads.set(thread.threadRef, thread);
+            this.applyInboxDelta(target, operation.data.inbox);
+            return;
+        }
         if (operation.kind === 'team/member-removed') {
             target.members.set(operation.data.member.memberId, operation.data.member);
             for (const membership of target.memberships.values())
@@ -1694,6 +1996,22 @@ export class AgentTeamLedger {
             this.applyInboxDelta(target, operation.data.inbox);
             return;
         }
+        if (operation.kind === 'team/member-archived') {
+            // Archival keeps Memberships: hidden state, not departure — a future
+            // restore returns the Member to its Channels. Visibility filters by
+            // member state instead.
+            target.members.set(operation.data.member.memberId, operation.data.member);
+            for (const claim of operation.data.claims)
+                target.claims.set(claim.claimRef, claim);
+            for (const activity of operation.data.activities)
+                this.appendActivityFact(target, activity);
+            for (const task of operation.data.tasks)
+                target.tasks.set(task.taskRef, task);
+            for (const thread of operation.data.threads)
+                target.threads.set(thread.threadRef, thread);
+            this.applyInboxDelta(target, operation.data.inbox);
+            return;
+        }
         if (operation.kind === 'team/thread-promoted') {
             this.appendActivityFact(target, operation.data.activity);
             target.tasks.set(operation.data.task.taskRef, operation.data.task);
@@ -1944,6 +2262,14 @@ export class AgentTeamLedger {
         const activityMarkers = [...this.state.activityMarkers.values()].filter(marker => marker.memberId === memberId && threadRefs.has(marker.threadRef));
         return this.inboxDelta([], removed, [], markers, [], activityMarkers);
     }
+    /** Attention and marker cleanup for EVERY Member on the given Threads. */
+    channelArchivalInbox(threadRefs) {
+        const removed = [...this.state.attention.values()].filter(attention => threadRefs.has(attention.threadRef))
+            .map(attention => Object.freeze({ memberId: attention.memberId, threadRef: attention.threadRef }));
+        const markers = [...this.state.directMarkers.values()].filter(marker => threadRefs.has(marker.threadRef));
+        const activityMarkers = [...this.state.activityMarkers.values()].filter(marker => threadRefs.has(marker.threadRef));
+        return this.inboxDelta([], removed, [], markers, [], activityMarkers);
+    }
     inboxDelta(set = [], removed = [], addedMarkers = [], removedMarkers = [], addedActivityMarkers = [], removedActivityMarkers = []) {
         return Object.freeze({
             attention: Object.freeze({ set: Object.freeze(set), removed: Object.freeze(removed) }),
@@ -2019,7 +2345,7 @@ export class AgentTeamLedger {
             if (memberId === AGENT_TEAM_HUMAN_MEMBER_ID)
                 continue;
             const member = this.requireMember(memberId);
-            if (member.state === 'inactive' || member.workspaceId !== channel.workspaceId || !this.isChannelMember(channel.channelRef, memberId)) {
+            if (member.state === 'inactive' || member.state === 'archived' || member.workspaceId !== channel.workspaceId || !this.isChannelMember(channel.channelRef, memberId)) {
                 throw new Error(`Agent Member '${memberId}' is not authorized for Channel '${channel.channelRef}'`);
             }
         }
@@ -2070,6 +2396,9 @@ export class AgentTeamLedger {
     threadForActor(actor, workspaceId, taskRef) {
         const task = this.requireTask(workspaceId, taskRef);
         const thread = this.requireThread(task.threadRef);
+        // Archived Channels do not exist on Team API surfaces: their Tasks and
+        // Claims are unreachable for reads (listClaims) as for writes.
+        this.assertThreadChannelActive(task.channelRef);
         if (actor.kind === 'member')
             this.requireMemberChannel(this.requireMember(actor.memberId), task.channelRef);
         return { task, thread };
@@ -2183,13 +2512,55 @@ export class AgentTeamLedger {
             throw new Error('agent-team operation lacks enabled Member authority');
         return member;
     }
-    /** Agents sometimes strip the branded prefix when echoing refs; point at the fix instead of a bare lookup failure. */
+    /** Shortest accepted UUID abbreviation after the branded prefix. */
+    static MIN_REF_UUID_PREFIX = 6;
+    isRefAbbreviationTail(tail) {
+        return tail.length >= AgentTeamLedger.MIN_REF_UUID_PREFIX && /^[0-9a-f]+$/i.test(tail);
+    }
+    /**
+     * Full map key for one branded ref, tolerating a unique UUID abbreviation.
+     * Exact refs win; an abbreviated ref (prefix plus at least 6 hex chars,
+     * hyphens ignored) resolves only when it matches exactly one key. Returns
+     * undefined for unknown or ambiguous refs so lenient callers can degrade
+     * without throwing.
+     */
+    uniqueRefKey(map, ref, prefix) {
+        if (map.has(ref))
+            return ref;
+        const tail = ref.startsWith(`${prefix}:`) ? ref.slice(prefix.length + 1).replaceAll('-', '') : undefined;
+        if (tail === undefined || !this.isRefAbbreviationTail(tail))
+            return undefined;
+        const lower = tail.toLowerCase();
+        const candidates = [...map.keys()].filter(key => key.slice(prefix.length + 1).replaceAll('-', '').startsWith(lower));
+        return candidates.length === 1 ? candidates[0] : undefined;
+    }
+    /** uniqueRefKey with the established unknown/ambiguous error contract and hints. */
+    requireRefKey(map, ref, prefix, label) {
+        const key = this.uniqueRefKey(map, ref, prefix);
+        if (key !== undefined)
+            return key;
+        const tail = ref.startsWith(`${prefix}:`) ? ref.slice(prefix.length + 1).replaceAll('-', '') : undefined;
+        if (tail !== undefined && this.isRefAbbreviationTail(tail)) {
+            const lower = tail.toLowerCase();
+            const candidates = [...map.keys()].filter(candidate => candidate.slice(prefix.length + 1).replaceAll('-', '').startsWith(lower));
+            if (candidates.length > 1) {
+                throw new Error(`ambiguous ${label} ref '${ref}' matches ${candidates.map(candidate => `'${candidate}'`).join(', ')}; reuse a longer prefix or the full ref exactly as returned by Team tools`);
+            }
+        }
+        throw new Error(`unknown ${label} ref '${ref}'${this.unknownRefHint(ref, prefix, label)}`);
+    }
+    /** Agents strip the branded prefix or abbreviate UUIDs when echoing refs; point at the fix instead of a bare lookup failure. */
     unknownRefHint(ref, prefix, label) {
-        return ref.startsWith(`${prefix}:`) ? ''
-            : ` A ${label} ref must start with '${prefix}:'; reuse the full ref exactly as returned by Team tools ('${prefix}:${ref}').`;
+        if (!ref.startsWith(`${prefix}:`)) {
+            return ` A ${label} ref must start with '${prefix}:'; reuse the full ref exactly as returned by Team tools ('${prefix}:${ref}').`;
+        }
+        const tail = ref.slice(prefix.length + 1).replaceAll('-', '');
+        return this.isRefAbbreviationTail(tail)
+            ? ` No ${label} matches this UUID prefix; reuse the full ref exactly as returned by Team tools.`
+            : ` A ${label} ref needs at least 6 hex characters after '${prefix}:', or the full ref exactly as returned by Team tools.`;
     }
     requireTask(workspaceId, taskRef) {
-        const task = this.state.tasks.get(taskRef);
+        const task = this.state.tasks.get(this.requireRefKey(this.state.tasks, taskRef, 'task', 'Task'));
         if (task === undefined)
             throw new Error(`unknown Task ref '${taskRef}'${this.unknownRefHint(taskRef, 'task', 'Task')}`);
         if (this.state.channels.get(task.channelRef)?.workspaceId !== workspaceId)
@@ -2197,7 +2568,7 @@ export class AgentTeamLedger {
         return task;
     }
     requireThread(threadRef) {
-        const thread = this.state.threads.get(threadRef);
+        const thread = this.state.threads.get(this.requireRefKey(this.state.threads, threadRef, 'thread', 'Thread'));
         if (thread === undefined)
             throw new Error(`unknown Thread ref '${threadRef}'${this.unknownRefHint(threadRef, 'thread', 'Thread')}`);
         return thread;
@@ -2220,13 +2591,15 @@ export class AgentTeamLedger {
         let thread;
         let task;
         if (request.threadRef !== undefined) {
-            thread = projection.threads.get(request.threadRef);
+            const threadKey = this.requireRefKey(projection.threads, request.threadRef, 'thread', 'Thread');
+            thread = projection.threads.get(threadKey);
             if (thread === undefined)
                 throw new Error(`unknown Thread ref '${request.threadRef}'${this.unknownRefHint(request.threadRef, 'thread', 'Thread')}`);
             task = thread.taskRef === undefined ? undefined : projection.tasks.get(thread.taskRef);
         }
         if (request.taskRef !== undefined) {
-            const byTask = projection.tasks.get(request.taskRef);
+            const taskKey = this.requireRefKey(projection.tasks, request.taskRef, 'task', 'Task');
+            const byTask = projection.tasks.get(taskKey);
             if (byTask === undefined)
                 throw new Error(`unknown Task ref '${request.taskRef}'${this.unknownRefHint(request.taskRef, 'task', 'Task')}`);
             if (task !== undefined && task.taskRef !== byTask.taskRef)
@@ -2245,20 +2618,40 @@ export class AgentTeamLedger {
             throw new Error(`Thread '${thread.threadRef}' has no Channel`);
         if (projection.channels.get(channelRef)?.workspaceId !== workspaceId)
             throw new Error(`Thread '${thread.threadRef}' does not belong to Workspace '${workspaceId}'`);
+        // Archived Channels do not exist on Team API surfaces: their Threads are
+        // unreachable by ref, for reads as for writes. Replay stays honest —
+        // operations predating the archival resolve against the then-active
+        // Channel because replay applies in sequence.
+        if (projection.channels.get(channelRef)?.state === 'archived') {
+            throw new Error(`Channel '${channelRef}' is archived and no longer accepts Team work`);
+        }
         if (task !== undefined && task.channelRef !== channelRef)
             throw new Error(`Task '${task.taskRef}' does not belong to Thread '${thread.threadRef}'`);
         return { ...(task === undefined ? {} : { task }), thread, channelRef };
     }
     requireChannel(workspaceId, channelRef) {
-        const channel = this.state.channels.get(channelRef);
+        const channel = this.state.channels.get(this.requireRefKey(this.state.channels, channelRef, 'channel', 'Channel'));
         if (channel === undefined)
             throw new Error(`unknown Channel ref '${channelRef}'${this.unknownRefHint(channelRef, 'channel', 'Channel')}`);
         if (channel.workspaceId !== workspaceId)
             throw new Error(`Channel '${channelRef}' does not belong to Workspace '${workspaceId}'`);
         return channel;
     }
+    /** Guard for every mutating or Channel-scoped surface flow: archived Channels reject. */
+    requireActiveChannel(workspaceId, channelRef) {
+        const channel = this.requireChannel(workspaceId, channelRef);
+        if (channel.state === 'archived')
+            throw new Error(`Channel '${channelRef}' is archived and no longer accepts Team work`);
+        return channel;
+    }
+    /** Thread-mutation guard: the Channel owning the Thread must still be active. */
+    assertThreadChannelActive(channelRef) {
+        if (this.state.channels.get(channelRef)?.state === 'archived') {
+            throw new Error(`Channel '${channelRef}' is archived and no longer accepts Team work`);
+        }
+    }
     requireMember(memberId) {
-        const member = this.state.members.get(memberId);
+        const member = this.state.members.get(this.requireRefKey(this.state.members, memberId, 'member', 'Agent Member'));
         if (member === undefined)
             throw new Error(`unknown Agent Member '${memberId}'`);
         return member;
@@ -2393,6 +2786,11 @@ export class AgentTeamLedger {
             || operation.data.workspaceId !== request.workspaceId || operation.data.channelRef !== request.channelRef || operation.data.memberId !== request.memberId)
             this.throwRequestCollision(request.requestId);
     }
+    assertSameChannelArchival(operation, request) {
+        if (operation.kind !== 'team/channel-archived' || !this.sameActor(operation.actor, request.actor)
+            || operation.data.workspaceId !== request.workspaceId || operation.data.channel.channelRef !== request.channelRef)
+            this.throwRequestCollision(request.requestId);
+    }
     assertSameDm(operation, request) {
         if (operation.kind !== 'team/dm-sent' || !this.sameActor(operation.actor, request.actor)
             || operation.data.workspaceId !== request.workspaceId
@@ -2448,6 +2846,11 @@ export class AgentTeamLedger {
             || operation.data.member.memberId !== request.memberId)
             this.throwRequestCollision(request.requestId);
     }
+    assertSameArchival(operation, request) {
+        if (operation.kind !== 'team/member-archived' || !this.sameActor(operation.actor, request.actor)
+            || operation.data.member.memberId !== request.memberId)
+            this.throwRequestCollision(request.requestId);
+    }
     assertSameAttention(operation, request) {
         if (operation.kind !== 'team/thread-attention-changed' || !this.sameActor(operation.actor, request.actor)
             || operation.data.workspaceId !== request.workspaceId
@@ -2538,6 +2941,10 @@ export class AgentTeamLedger {
         return Object.freeze({ receipt: this.receipt(operation), channelRef: operation.data.channelRef, memberId: operation.data.memberId,
             releasedClaims: operation.data.claims, removedAttention: operation.data.inbox.attention.removed });
     }
+    channelArchivalResult(operation) {
+        return Object.freeze({ receipt: this.receipt(operation), channel: operation.data.channel,
+            releasedClaims: operation.data.claims });
+    }
     messageResult(operation) {
         return Object.freeze(this.committedMessageResult(operation));
     }
@@ -2578,6 +2985,10 @@ export class AgentTeamLedger {
         return Object.freeze({ receipt: this.receipt(operation), member: operation.data.member,
             releasedClaims: operation.data.claims, removedAttention: operation.data.inbox.attention.removed });
     }
+    archivalResult(operation) {
+        return Object.freeze({ receipt: this.receipt(operation), member: operation.data.member,
+            releasedClaims: operation.data.claims, removedAttention: operation.data.inbox.attention.removed });
+    }
     operationBase(request, sequence) {
         return { sequence, operationId: this.createOperationId(), requestId: request.requestId, occurredAt: this.createOccurredAt(),
             actor: Object.freeze({ ...request.actor }), previousOperationId: this.state.ordered.at(-1)?.operationId ?? null };