@wowyuarm/dsh-agent-team 0.1.10 → 0.1.11

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

@@ -47,19 +47,20 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { scopeOf } from '@deepseek-ai/dsh-scope';
 import { Session, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
-import { SessionFormatUnsupportedError } from '@deepseek-ai/dsh-session-persistence';
 import { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { ATTACHMENT_MAX_BYTES, attachmentPayloadPath, attachmentsRoot, copyPathAttachment, newAttachmentId, readAttachment, sanitizeMediaType, sweepAttachmentCache, validatePathAttachment, writeAttachment } from "./attachments.js";
 import { PressurePolicyCoordinator } from "./pressure-policy.js";
 import { ContextManagementCoordinator } from "./context-management.js";
 import { AGENT_TEAM_PLUGIN_ID, createHandoffMessage } from "./context-source.js";
-import { carriedInputOf, checkpointByRef, checkpointRefFor, foldContextProjection, isReminderNoticeSummary, timelineCandidates } from "./context-projection.js";
+import { carriedInputOf, checkpointByRef, checkpointRefFor, contextProjectionFold, foldContextProjection, isReminderNoticeSummary, timelineCandidates } from "./context-projection.js";
+import { advanceOwnedSessionEventCursor } from "./session-event-cursor.js";
 import { AGENT_TEAM_HUMAN_MEMBER_ID, AgentTeamLedger, agentTeamHumanActor } from "./ledger.js";
 import { AGENT_TEAM_TOOL_NAMES, deepCopyCapabilities, memberMemoryDirectoryName, MemberRuntime } from "./member-runtime.js";
 import { ProgressNudgeCoordinator } from "./progress-nudge.js";
 import { classifyRecoverableError, RecoveryCoordinator, RECOVERY_MAX_CONSECUTIVE_ERRORS } from "./recovery.js";
 import { SessionRemediation, handoffAlreadyInLog } from "./session-remediation.js";
+import { StoredSessionReadError, StoredSessionReader, sessionFailureOf } from "./stored-session-reader.js";
 import { agentTeamDomainSpec } from "./spec.js";
 import { formatTeamTimestamp } from "./time-format.js";
 export { agentTeamDomainSpec, agentTeamOperationSchema } from "./spec.js";
@@ -70,6 +71,17 @@ export const AGENT_TEAM_PRESET_MARKER = Symbol.for('@wowyuarm/dsh-agent-team.pre
 const INBOX_NOTICE_SUMMARY = 'Team Inbox has unread work.';
 const RECOVERY_NOTICE_SUMMARY = 'Recovery: continue your interrupted work.';
 const ORPHANED_MEMBER_DIAGNOSTIC = 'Member preset composition was lost after a reload; its tools are unavailable. Resume rebuilds the member in place.';
+/**
+ * A preset mount/validation failure during activation, carrying its own class
+ * so the activation diagnostic can route preset-composition failures (the
+ * install/runtime split failure mode) without matching message text.
+ */
+class PresetCompositionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'PresetCompositionError';
+    }
+}
 /** Longest accepted model-supplied checkpoint display name. */
 const MAX_CHECKPOINT_NAME_CHARS = 120;
 /** Default and maximum number of timeline items one query returns. */
@@ -95,6 +107,8 @@ function sameChangeScope(left, right) {
         return left.channelRef === right.channelRef;
     if (left.kind === 'thread' && right.kind === 'thread')
         return left.threadRef === right.threadRef;
+    if (left.kind === 'presence' && right.kind === 'presence')
+        return left.workspaceId === right.workspaceId;
     return false;
 }
 /** Mark the preset's `team_message` definition as an Agent Team consumer. */
@@ -261,6 +275,13 @@ let AgentTeam = (() => {
             },
             runningAgents: this.runningAgents,
         });
+        /**
+         * The single seam for every per-Session stored read: handle lifecycle and
+         * failure normalization live here, so a DSH persistence-interface change is
+         * adapted once, and consumers choose policy by failure category instead of
+         * matching error text.
+         */
+        sessionReader = new StoredSessionReader(this.ctx);
         /**
          * Why one Member shows error presence, per failure source. Reads prefer
          * activation, then runtime, then compaction; slots clear independently, so
@@ -297,6 +318,14 @@ let AgentTeam = (() => {
             },
             log: message => { this.ctx.logger.warn(message); },
         });
+        /**
+         * Incremental fold state for {@link contextManagement}'s projection lookup:
+         * one entry per Member, replaced when that Member's Session changes. Keying
+         * by Member rather than by Session id is what bounds the map — a rollover
+         * that leaves the previous generation's projection behind retains it for the
+         * life of the process, and only the current Session can ever read it.
+         */
+        contextCursors = new Map();
         /**
          * Context self-management: the one deep module that turns a Member's
          * successful `context_rollover` tool result into its next private context
@@ -311,15 +340,34 @@ let AgentTeam = (() => {
                 const handle = this.handles.get(memberId);
                 if (handle === undefined || handle.agent.session.id !== sessionId)
                     return undefined;
-                return foldContextProjection(handle.agent.session.ownEvents(), handle.agent.session.inheritedEventCount, handle.agent.session.id);
+                const session = handle.agent.session;
+                // The projection is read on every successful tool result and turn end, so
+                // it folds incrementally. The entry is keyed by Member and carries the
+                // Session it was built from: this Session's log keeps growing, a rollover
+                // replaces the entry instead of resuming from its predecessor's cursor,
+                // and a rewritten log falls back to a cold fold inside the cursor.
+                const owned = advanceOwnedSessionEventCursor(this.contextCursors.get(memberId), session.id, contextProjectionFold(session.id), session.ownEvents(), session.inheritedEventCount);
+                this.contextCursors.set(memberId, owned);
+                return owned.cursor.value;
             },
             executeTransition: (memberId, plan) => this.executeMemberTransition(memberId, plan),
             log: message => { this.ctx.logger.warn(`agent-team: ${message}`); },
         });
         lifecycleTail = Promise.resolve();
         accepting = true;
-        changeVersion = 0;
+        /**
+         * Presence wake epoch: Agent running/idle/failure is runtime state with no
+         * durable fact behind it, so the presence scope counts those edge wakes in
+         * process. It never takes part in a projection waiter's comparison.
+         */
+        presenceEpoch = 0;
         changeWaiters = new Set();
+        /**
+         * The startup-opened remediation instance, held for the restart heal: the
+         * completion-cache domain may only be opened once per plugin lifecycle, so
+         * the restart path reuses this instance instead of opening its own.
+         */
+        remediation;
         constructor(ctx) {
             super(ctx, 'agentTeam');
             this.pressurePolicy = new PressurePolicyCoordinator({
@@ -351,7 +399,7 @@ let AgentTeam = (() => {
                 if (kind !== undefined)
                     this.ctx.logger.warn(`agent-team: member '${member.handle}' hit a recoverable ${kind} error; recording a consecutive error occurrence`);
                 this.recovery.onError(member.memberId, message);
-                this.emitChanged([{ kind: 'workspace', workspaceId: member.workspaceId }]);
+                this.emitPresenceChanged(member.workspaceId);
             });
             this.ctx.on('agent/status', ({ agent, status }) => {
                 const member = this.memberForAgent(agent);
@@ -363,7 +411,7 @@ let AgentTeam = (() => {
                     const recovered = this.clearMemberFailure(member.memberId, 'runtime');
                     if (recovered)
                         this.notifiedInbox.delete(member.memberId);
-                    this.emitChanged([{ kind: 'workspace', workspaceId: member.workspaceId }]);
+                    this.emitPresenceChanged(member.workspaceId);
                     // A rollover/recovery in flight delivers its own sequenced
                     // rederived Inbox after the handoff and carried input; a status-driven
                     // steer here would claim the handoff turn's next step and leapfrog
@@ -373,14 +421,14 @@ let AgentTeam = (() => {
                 }
                 // A turn that ends without an error closes any automatic recovery episode.
                 // The idle transition is itself presence-affecting (working → available),
-                // so it must wake workspace watchers exactly like the running transition
+                // so it must wake presence watchers exactly like the running transition
                 // above; without this wake, cached Client member rows keep showing the
                 // Member as working after every turn until an unrelated change arrives.
                 if (status === 'idle' && member !== undefined) {
                     if (this.memberFailures.get(member.memberId)?.runtime === undefined) {
                         this.recovery.onCleanTurnEnd(member.memberId);
                     }
-                    this.emitChanged([{ kind: 'workspace', workspaceId: member.workspaceId }]);
+                    this.emitPresenceChanged(member.workspaceId);
                 }
             });
             // Progress nudges count every `tool/call` of each Member Session. The
@@ -410,6 +458,7 @@ let AgentTeam = (() => {
             const domain = await this.ctx.storageDomain.open(agentTeamDomainSpec);
             this.ctx.effect(() => async () => {
                 this.accepting = false;
+                this.remediation = undefined;
                 this.recovery.dispose();
                 this.progressNudge.dispose();
                 this.contextManagement.dispose();
@@ -439,6 +488,7 @@ let AgentTeam = (() => {
             // startup — the next start retries exactly what the cache does not cover.
             try {
                 const remediation = new SessionRemediation(this.ctx, this.ctx.sessionPersistence, await SessionRemediation.open(this.ctx));
+                this.remediation = remediation;
                 await remediation.remediateEnabledMembers(ledger.listMembers());
             }
             catch (error) {
@@ -463,7 +513,7 @@ let AgentTeam = (() => {
          * generation over it.
          */
         async sessionPersisted(sessionId) {
-            return (await this.ctx.sessionPersistence.stat(sessionId)) !== undefined;
+            return this.sessionReader.exists(sessionId);
         }
         /** Resolve one exact live Agent to its durable Team Member; forks do not inherit identity. */
         memberForAgent(agent) {
@@ -501,8 +551,9 @@ let AgentTeam = (() => {
             if (!Number.isInteger(request.afterVersion) || request.afterVersion < 0)
                 throw new Error('afterVersion must be a non-negative integer');
             const scope = this.validateChangeScope(request.scope);
-            if (this.changeVersion > request.afterVersion || !this.accepting)
-                return Object.freeze({ version: this.changeVersion });
+            const version = this.changeVersionOf(scope);
+            if (version > request.afterVersion || !this.accepting)
+                return Object.freeze({ version });
             return new Promise((resolve, reject) => {
                 let settled = false;
                 const waiter = {
@@ -521,7 +572,7 @@ let AgentTeam = (() => {
                         return;
                     settled = true;
                     this.changeWaiters.delete(waiter);
-                    resolve(Object.freeze({ version: this.changeVersion }));
+                    resolve(Object.freeze({ version: this.changeVersionOf(scope) }));
                 }, 25_000);
                 const onAbort = () => {
                     if (settled)
@@ -659,6 +710,23 @@ let AgentTeam = (() => {
                 if (member.state !== 'enabled')
                     throw new Error(`Agent Member '${member.handle}' is ${member.state}; only enabled Members can be restarted`);
                 this.ctx.logger.info(`agent-team: restarting member '${member.handle}' after a failed activation`);
+                // A deterministic session refusal may be repairable in place: run the
+                // same bounded startup remediation for this one Member before retrying
+                // activation, so the restart heals instead of replaying the failure.
+                const activation = this.memberFailures.get(request.memberId)?.activation;
+                if (activation !== undefined && activation.class === 'session-refused' && this.remediation !== undefined) {
+                    const outcome = await this.remediation.remediateMember(member);
+                    if (outcome.repaired > 0) {
+                        this.ctx.logger.info(`agent-team: repaired ${outcome.repaired} refused Session artifact(s) for member '${member.handle}'; retrying activation`);
+                    }
+                    else if (outcome.completed) {
+                        // The walk finished and nothing was provably this plugin's to fix:
+                        // a retry would fail identically. Mark the refusal non-remediable
+                        // so the surface stops offering restart and says why.
+                        this.markRefusalNonRemediable(request.memberId);
+                        return Object.freeze({ status: this.memberStatus(member) });
+                    }
+                }
                 await this.reactivateMember(request.memberId);
                 return Object.freeze({ status: this.memberStatus(member) });
             }
@@ -1078,7 +1146,7 @@ let AgentTeam = (() => {
                 this.emitCommitted(result.value.receipt);
             return result.value;
         }
-        /** Host-only Human Inbox projection; the Web Client does not consume it. */
+        /** Human Inbox projection; the Web Client consumes the direct-only slice as its mention queue. */
         inbox(request) {
             this.requireWorkspace(request.workspaceId);
             return this.requireLedger().inbox(agentTeamHumanActor(), request);
@@ -1087,8 +1155,10 @@ let AgentTeam = (() => {
         async readThread(request) {
             const actor = this.humanCall(request.workspaceId);
             const result = await this.requireLedger().readThread({ ...request, actor });
-            if (result.committed)
-                this.emitCommitted(result.value.receipt);
+            // A read that made no progress commits no operation and carries no receipt.
+            const receipt = result.committed ? result.value.receipt : undefined;
+            if (receipt !== undefined)
+                this.emitCommitted(receipt);
             return result.value;
         }
         /** Human-only durable Attention observations for one Thread. */
@@ -1147,8 +1217,10 @@ let AgentTeam = (() => {
         async readThreadForAgent(agent, request) {
             const actor = this.memberCall(agent, request.workspaceId);
             const result = await this.requireLedger().readThread({ ...request, actor });
-            if (result.committed)
-                this.emitCommitted(result.value.receipt);
+            // A read that made no progress commits no operation and carries no receipt.
+            const receipt = result.committed ? result.value.receipt : undefined;
+            if (receipt !== undefined)
+                this.emitCommitted(receipt);
             const value = result.value;
             // Private read-time enrich: an acceptance the reader just acknowledged is
             // a natural Task boundary, so the Host prices the reader's context once,
@@ -1265,6 +1337,16 @@ let AgentTeam = (() => {
         validateLedger() {
             this.requireLedger().validate();
         }
+        /**
+         * Validate the durable ledger for the invariant's mount check. The
+         * constructor already re-derived every durable record against its own
+         * scratch projection, so this adopts that conclusion once while nothing has
+         * committed since; every other call, and every commit-driven validation,
+         * replays the whole table again.
+         */
+        validateLedgerAtMount() {
+            this.requireLedger().validateAtMount();
+        }
         /**
          * Effective context-pressure budget for one Member's current route:
          * `hardLimit = min(256K, routeWindow - outputReserve)` and
@@ -1362,20 +1444,13 @@ let AgentTeam = (() => {
                     live = false;
                 }
                 else {
-                    try {
-                        const handle = await this.ctx.sessionPersistence.open(sessionId, 'read');
-                        try {
-                            events = (await handle.read()).events;
-                            inheritedEventCount = handle.inheritedEventCount;
-                            parentSession = handle.header.parentSession;
-                        }
-                        finally {
-                            await handle.close();
-                        }
-                    }
-                    catch (error) {
-                        throw new Error(`checkpoint '${checkpointRef}' could not be resolved: its source Session is unreadable (${error instanceof Error ? error.message : String(error)})`);
+                    const read = await this.sessionReader.read(sessionId);
+                    if (!read.ok) {
+                        throw new StoredSessionReadError(`checkpoint '${checkpointRef}' could not be resolved: its source Session is unreadable (${read.failure.kind}: ${read.failure.detail})`, read.failure);
                     }
+                    events = read.inspection.events;
+                    inheritedEventCount = read.inspection.inheritedEventCount;
+                    parentSession = read.inspection.header.parentSession;
                 }
                 // Fold the source with its inherited cut respected: inherited events
                 // are resolved history in that source, never fresh intent; checkpoints
@@ -1452,20 +1527,15 @@ let AgentTeam = (() => {
                 ?? this.requireLedger().previousSessionForMember(member.memberId);
             if (previousSessionId === undefined)
                 return;
-            let inspection;
-            try {
-                const handle = await this.ctx.sessionPersistence.open(previousSessionId, 'read');
-                try {
-                    inspection = { events: (await handle.read()).events, inheritedEventCount: handle.inheritedEventCount };
-                }
-                finally {
-                    await handle.close();
-                }
-            }
-            catch (error) {
-                this.ctx.logger.warn(`agent-team: rollover handoff reconstruction could not read the previous Session '${previousSessionId}': ${error instanceof Error ? error.message : String(error)}`);
+            const previousRead = await this.sessionReader.read(previousSessionId);
+            if (!previousRead.ok) {
+                // Best-effort recovery: the handoff intent stays lost with the
+                // unreadable previous Session, but the Member still activates.
+                const failure = previousRead.failure;
+                this.ctx.logger.warn(`agent-team: rollover handoff reconstruction could not read the previous Session '${previousSessionId}' (${failure.kind}): ${failure.detail}`);
                 return;
             }
+            const inspection = previousRead.inspection;
             const state = foldContextProjection(inspection.events, inspection.inheritedEventCount, previousSessionId);
             if (state.pending === null)
                 return;
@@ -1494,19 +1564,12 @@ let AgentTeam = (() => {
          * downgrade to a blank child.
          */
         async recordedCheckpointPrefix(seed) {
-            let inspection;
-            try {
-                const handle = await this.ctx.sessionPersistence.open(seed.sourceSessionId, 'read');
-                try {
-                    inspection = { events: (await handle.read()).events, inheritedEventCount: handle.inheritedEventCount };
-                }
-                finally {
-                    await handle.close();
-                }
-            }
-            catch (error) {
-                throw new Error(`the recorded checkpoint-return seed source Session '${seed.sourceSessionId}' is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+            const seedRead = await this.sessionReader.read(seed.sourceSessionId);
+            if (!seedRead.ok) {
+                const failure = seedRead.failure;
+                throw new StoredSessionReadError(`the recorded checkpoint-return seed source Session '${seed.sourceSessionId}' is unreadable (${failure.kind}): ${failure.detail}`, failure);
             }
+            const inspection = seedRead.inspection;
             const through = Number(seed.sourceThroughSeq);
             if (!Number.isSafeInteger(through) || through < 0 || through > inspection.events.length) {
                 throw new Error(`the recorded checkpoint-return seed cut ${through} is not a valid prefix of Session '${seed.sourceSessionId}'`);
@@ -1555,23 +1618,14 @@ let AgentTeam = (() => {
             }
             let inspectionEvents;
             let inspectionInherited;
-            try {
-                const handle = await this.ctx.sessionPersistence.open(transition.previousSessionId, 'read');
-                try {
-                    inspectionEvents = (await handle.read()).events;
-                    inspectionInherited = handle.inheritedEventCount;
-                }
-                finally {
-                    await handle.close();
-                }
-            }
-            catch (error) {
-                const detail = error instanceof Error ? error.message : String(error);
+            const previousRead = await this.sessionReader.read(transition.previousSessionId);
+            if (!previousRead.ok) {
+                const failure = previousRead.failure;
                 // Log-corruption class: bounded fail-open. The current Session's own
                 // fold is intact and the Host repairs the retired log's torn tail; a
                 // corrupted retired generation must not permanently block activation.
-                if (/corrupt session log/.test(detail)) {
-                    this.ctx.logger.warn(`agent-team: previous Session '${transition.previousSessionId}' holding carried input for member '${this.memberLabel(member.memberId)}' is corrupt: ${detail}; skipping the replay`);
+                if (failure.kind === 'corrupt') {
+                    this.ctx.logger.warn(`agent-team: previous Session '${transition.previousSessionId}' holding carried input for member '${this.memberLabel(member.memberId)}' is corrupt: ${failure.detail}; skipping the replay`);
                     return 0;
                 }
                 // Deterministic released-format refusal: the retired artifact is refused
@@ -1580,12 +1634,14 @@ let AgentTeam = (() => {
                 // Member no longer runs in into permanent unavailability — the exact
                 // failure class this hardening removes. Genuine IO and unknown failures
                 // stay fail-closed so carried input is never dropped silently.
-                if (error instanceof SessionFormatUnsupportedError) {
-                    this.ctx.logger.warn(`agent-team: previous Session '${transition.previousSessionId}' holding carried input for member '${this.memberLabel(member.memberId)}' is refused by the session-format migration: ${detail}; skipping the replay`);
+                if (failure.kind === 'refused') {
+                    this.ctx.logger.warn(`agent-team: previous Session '${transition.previousSessionId}' holding carried input for member '${this.memberLabel(member.memberId)}' is refused by the session-format migration: ${failure.detail}; skipping the replay`);
                     return 0;
                 }
-                throw new Error(`the previous Session '${transition.previousSessionId}' holding the Member's carried input is unreadable: ${detail}`);
+                throw new StoredSessionReadError(`the previous Session '${transition.previousSessionId}' holding the Member's carried input is unreadable (${failure.kind}): ${failure.detail}`, failure);
             }
+            inspectionEvents = previousRead.inspection.events;
+            inspectionInherited = previousRead.inspection.inheritedEventCount;
             const state = foldContextProjection(inspectionEvents, inspectionInherited, transition.previousSessionId);
             const carried = carriedInputOf(state);
             if (carried.length === 0)
@@ -1659,6 +1715,7 @@ let AgentTeam = (() => {
             // persisted logs; the same projection definition folds every source.
             const items = [];
             const seen = new Set();
+            let incompleteFrom;
             let sessionId = member.sessionId;
             let live = true;
             let guard = 0;
@@ -1676,23 +1733,19 @@ let AgentTeam = (() => {
                     live = false;
                 }
                 else {
-                    try {
-                        const handle = await this.ctx.sessionPersistence.open(sessionId, 'read');
-                        try {
-                            const { events } = await handle.read();
-                            state = foldContextProjection(events, handle.inheritedEventCount, sessionId);
-                            sourceEvents = events;
-                            sourceSessionId = sessionId;
-                            sessionId = handle.header.parentSession;
-                        }
-                        finally {
-                            await handle.close();
-                        }
-                    }
-                    catch {
-                        // An unreadable ancestor ends the lineage walk here.
+                    const read = await this.sessionReader.read(sessionId);
+                    if (!read.ok) {
+                        // An unreadable ancestor ends the lineage walk here — recorded in
+                        // the result, never silent, and never a Member-availability fact.
+                        incompleteFrom = { sessionId, reason: `${read.failure.kind}: ${read.failure.detail}` };
                         sessionId = undefined;
                     }
+                    else {
+                        state = foldContextProjection(read.inspection.events, read.inspection.inheritedEventCount, sessionId);
+                        sourceEvents = read.inspection.events;
+                        sourceSessionId = sessionId;
+                        sessionId = read.inspection.header.parentSession;
+                    }
                 }
                 if (state === undefined)
                     break;
@@ -1713,7 +1766,7 @@ let AgentTeam = (() => {
                 if (items.length >= limit)
                     break;
             }
-            return { usageTokens, hardLimit, handoffAt, items };
+            return { usageTokens, hardLimit, handoffAt, items, ...(incompleteFrom === undefined ? {} : { incompleteFrom }) };
         }
         /**
          * Replayed measurement of one lineage source: the live current Session
@@ -1729,19 +1782,16 @@ let AgentTeam = (() => {
                 return undefined;
             if (live)
                 return meter.measure(agent.session)?.totalTokens;
+            // 0.1.5 removed borrowSession: rebuild a detached Session from the
+            // stored log so the seed's retained cost is priced by the SOURCE's own
+            // replay, never the current generation's. An unreadable source or a
+            // failing meter is unmeasurable and prices as UNKNOWN.
+            const read = await this.sessionReader.read(sessionId);
+            if (!read.ok)
+                return undefined;
             try {
-                // 0.1.5 removed borrowSession: rebuild a detached Session from the
-                // stored log so the seed's retained cost is priced by the SOURCE's own
-                // replay, never the current generation's.
-                const handle = await this.ctx.sessionPersistence.open(sessionId, 'read');
-                try {
-                    const { events } = await handle.read();
-                    const session = Session.create(sessionId, events, handle.header, handle.inheritedEventCount);
-                    return meter.measure(session)?.totalTokens;
-                }
-                finally {
-                    await handle.close();
-                }
+                const session = Session.create(sessionId, read.inspection.events, read.inspection.header, read.inspection.inheritedEventCount);
+                return meter.measure(session)?.totalTokens;
             }
             catch {
                 return undefined;
@@ -2097,9 +2147,17 @@ let AgentTeam = (() => {
                 // `swap` is bound by the provider at activation (no-op until then).
                 const skillSelection = { current: member.capabilities?.skills?.allow, swap: () => { } };
                 const setup = async (agentCtx, agent) => {
-                    await this.ctx.agentPresets.mount(agentCtx, member.presetId);
-                    this.memberRuntime.applyMemberToolPolicy(agentCtx, member);
-                    this.validateMemberPreset(agentCtx);
+                    try {
+                        await this.ctx.agentPresets.mount(agentCtx, member.presetId);
+                        this.memberRuntime.applyMemberToolPolicy(agentCtx, member);
+                        this.validateMemberPreset(agentCtx);
+                    }
+                    catch (error) {
+                        // Tag composition failures with their own class: the activation
+                        // diagnostic routes preset-composition (install/runtime split)
+                        // failures by type, not by matching message text.
+                        throw new PresetCompositionError(error instanceof Error ? error.message : String(error), { cause: error });
+                    }
                     installModelSelection(agentCtx, selected);
                     // Admission gate for pending context rollovers: once a successful
                     // context_rollover result is durable, queued input must not open another
@@ -2276,11 +2334,11 @@ let AgentTeam = (() => {
                 this.memberRuntime.forgetMember(member.memberId);
                 const message = error instanceof Error ? error.message : String(error);
                 this.ctx.logger.warn(`agent-team: activation failed for member '${this.memberLabel(member.memberId)}': ${message}`);
-                this.setMemberFailure(member.memberId, 'activation', message);
+                this.setActivationDiagnostic(member.memberId, this.activationDiagnosticOf(error, member.sessionId));
             }
             finally {
                 // Activation only changes this Workspace's presence projection.
-                this.emitChanged([{ kind: 'workspace', workspaceId: member.workspaceId }]);
+                this.emitPresenceChanged(member.workspaceId);
             }
         }
         /**
@@ -2368,13 +2426,13 @@ let AgentTeam = (() => {
             // new binding as active — a Client following the row would otherwise open
             // a Session that does not exist yet.
             if (handle.agent.id !== member.sessionId)
-                return Object.freeze({ member, availability: 'unavailable', presence: 'unavailable', diagnostic: 'context rollover in progress' });
+                return Object.freeze({ member, availability: 'unavailable', presence: 'unavailable', diagnostic: { class: 'rollover', detail: 'context rollover in progress' } });
             if (this.ctx.agentPresets.composedPreset(handle.agent.ctx) === undefined) {
-                return Object.freeze({ member, availability: 'active', presence: 'error', diagnostic: ORPHANED_MEMBER_DIAGNOSTIC });
+                return Object.freeze({ member, availability: 'active', presence: 'error', diagnostic: { class: 'preset-composition', detail: ORPHANED_MEMBER_DIAGNOSTIC } });
             }
             const runtimeError = failures?.runtime ?? failures?.compaction;
             if (runtimeError !== undefined)
-                return Object.freeze({ member, availability: 'active', presence: 'error', diagnostic: runtimeError });
+                return Object.freeze({ member, availability: 'active', presence: 'error', diagnostic: { class: 'runtime', detail: runtimeError } });
             // Capability warnings are runtime-derived at activation (handles-scoped,
             // like failures): absent while capabilities resolve cleanly.
             const capabilityWarnings = this.memberRuntime.capabilityWarningsFor(member.memberId);
@@ -2388,6 +2446,37 @@ let AgentTeam = (() => {
             failures[slot] = message;
             this.memberFailures.set(memberId, failures);
         }
+        /** Store one structured activation diagnostic; runtime/compaction slots stay plain messages. */
+        setActivationDiagnostic(memberId, diagnostic) {
+            const failures = this.memberFailures.get(memberId) ?? {};
+            failures.activation = Object.freeze(diagnostic);
+            this.memberFailures.set(memberId, failures);
+        }
+        /**
+         * Route one activation failure to its diagnostic class: preset composition
+         * failures by their own error class, session failures by the seam's typed
+         * classification (our call sites carry it directly; a Harness resume
+         * failure carries it through the cause chain), everything else as an
+         * unclassified activation failure.
+         */
+        activationDiagnosticOf(error, sessionId) {
+            if (error instanceof PresetCompositionError)
+                return { class: 'preset-composition', detail: error.message };
+            const failure = error instanceof StoredSessionReadError ? error.failure : sessionFailureOf(error, sessionId);
+            if (failure !== undefined) {
+                const shared = { detail: failure.detail, ...(failure.location === undefined ? {} : { location: failure.location }), sessionId: failure.sessionId };
+                return failure.kind === 'refused' ? { class: 'session-refused', ...shared } : { class: 'session-unreadable', ...shared };
+            }
+            return { class: 'activation', detail: error instanceof Error ? error.message : String(error) };
+        }
+        /** Mark a session-refused activation diagnostic as proven non-remediable. */
+        markRefusalNonRemediable(memberId) {
+            const failures = this.memberFailures.get(memberId);
+            const activation = failures?.activation;
+            if (activation === undefined || activation.class !== 'session-refused')
+                return;
+            failures.activation = Object.freeze({ ...activation, remediable: false });
+        }
         clearMemberFailure(memberId, slot) {
             const failures = this.memberFailures.get(memberId);
             if (failures === undefined || failures[slot] === undefined)
@@ -2462,7 +2551,17 @@ let AgentTeam = (() => {
         }
         emitAutoCompactionChanged(memberId) {
             const workspaceId = this.ledger?.getMember(memberId)?.workspaceId;
-            this.emitChanged(workspaceId === undefined ? undefined : [{ kind: 'workspace', workspaceId }]);
+            if (workspaceId === undefined)
+                return;
+            this.emitPresenceChanged(workspaceId);
+        }
+        /**
+         * Presence-only invalidation: Agent running/idle/activation/failure changes
+         * alter no durable projection, so only members/presence subscribers wake —
+         * the workspace catalog and the scope-less Inbox subscriptions stay parked.
+         */
+        emitPresenceChanged(workspaceId) {
+            this.emitChanged([{ kind: 'presence', workspaceId }]);
         }
         /** Wake from durable unread state with bounded facts for direct and state-changing work. */
         notifyMember(agent, sequenced = false) {
@@ -2646,21 +2745,45 @@ let AgentTeam = (() => {
          * Wake waiters for one committed or lifecycle change. Undefined broadcasts
          * to everyone; an empty scope list invalidates nobody because no shared
          * projection changed; otherwise global and matching scoped waiters wake.
+         * Presence-only scopes sit outside that: they change no durable projection,
+         * so only matching presence waiters wake and the scope-less Inbox
+         * subscriptions stay parked.
+         *
+         * Each woken waiter receives the version of its own scope's domain, so a
+         * wake can never hand a projection waiter a presence number or the other way
+         * around. Nothing here advances the projection version.
          */
         emitChanged(scopes) {
-            this.changeVersion += 1;
+            const touchesProjection = scopes === undefined || scopes.some(scope => scope.kind !== 'presence');
+            const touchesPresence = scopes !== undefined && scopes.some(scope => scope.kind === 'presence');
+            if (!touchesProjection && !touchesPresence)
+                return;
+            if (touchesPresence)
+                this.presenceEpoch += 1;
             for (const waiter of this.changeWaiters) {
                 const waiterScope = waiter.scope;
-                if (scopes !== undefined && (waiterScope === undefined ? scopes.length === 0 : !scopes.some(scope => sameChangeScope(scope, waiterScope))))
+                if (scopes !== undefined && (waiterScope === undefined ? !touchesProjection : !scopes.some(scope => sameChangeScope(scope, waiterScope))))
                     continue;
                 this.changeWaiters.delete(waiter);
-                waiter.wake(this.changeVersion);
+                waiter.wake(this.changeVersionOf(waiterScope));
             }
         }
+        /**
+         * The cursor domain of one scope: presence scopes count process-local edge
+         * wakes, every other scope compares against the durable ledger position of
+         * the newest shared-projection commit. The two domains are deliberately
+         * separate, so a presence edge cannot invalidate a projection subscriber and
+         * a private read invalidates no one.
+         */
+        changeVersionOf(scope) {
+            if (scope?.kind === 'presence')
+                return this.presenceEpoch;
+            return this.ledger?.projectionSequence() ?? 0;
+        }
         validateChangeScope(scope) {
             if (scope === undefined)
                 return undefined;
-            const ref = scope.kind === 'workspace' ? scope.workspaceId : scope.kind === 'channel' ? scope.channelRef : scope.threadRef;
+            const ref = scope.kind === 'workspace' || scope.kind === 'presence' ? scope.workspaceId : scope.kind === 'channel' ? scope.channelRef : scope.threadRef;
             if (typeof ref !== 'string' || ref.length === 0)
                 throw new Error(`change scope of kind '${scope.kind}' requires a non-empty ref`);
             return scope;