@wowyuarm/dsh-agent-team 0.2.0 → 0.2.1

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

@@ -50,15 +50,17 @@ 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 { 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 z from '@deepseek-ai/schemastery';
+import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { ATTACHMENT_MAX_BYTES, attachmentPayloadPath, attachmentsRoot, copyPathAttachment, pathAttachmentId, readAttachment, removeAttachment, sanitizeMediaType, sweepAttachmentCache, validatePathAttachment, writeRequestScopedAttachment } from "./attachments.js";
 import { reportEnvironment } from "./environment-check.js";
 import { HUMAN_PROFILE_DEFAULT_NAME, HUMAN_PROFILE_REPO_URL, HUMAN_PROFILE_SETTINGS_NAMESPACE, HUMAN_PROFILE_SETTINGS_SCHEMA, HUMAN_PROFILE_VERSION, assertValidHumanName, normalizeHumanName, parseLegacyHumanProfile, planLegacyAdoption } from "./human-profile.js";
 import { humanAvatarsRoot, readHumanAvatar, removeHumanAvatar, writeHumanAvatar } from "./human-avatar.js";
 import { createHumanUpdateChecker } from "./human-update-check.js";
-import { PressurePolicyCoordinator } from "./pressure-policy.js";
-import { CONTEXT_CONTINUITY_PROJECTION_KEY, readContextTimeline } from '@wowyuarm/dsh-context-continuity';
-import { createTeamContextManagement, TEAM_CONTEXT_CODEC } from "./context-continuity-host.js";
+import { AgentTeamInvariantError } from "./invariant.js";
+import { createTeamContextManagement, TeamPressurePolicy, TEAM_CONTEXT_CODEC, TEAM_PRESSURE_GATE_SCHEMA } from "./context-continuity-host.js";
+import { CONTEXT_CONTINUITY_PROJECTION_KEY, DEFAULT_GATE_IDLE_MS, DEFAULT_GATE_TOKENS, readContextTimeline } from '@wowyuarm/dsh-context-continuity';
+import { TeamContextJudge } from "./context-judge.js";
 import { AGENT_TEAM_PLUGIN_ID, isAgentTeamSource } from "./context-source.js";
 import { boundaryByRef, carriedInputOf, checkpointByRef, checkpointRefFor, createTeamContextProjectionConfig, createTeamContextProjectionDefinition, foldTeamContextProjection, retainedTopicsThrough, TeamContextProjectionHost } from "./context-projection.js";
 import { AGENT_TEAM_HUMAN_MEMBER_ID, AgentTeamLedger, agentTeamHumanActor } from "./ledger.js";
@@ -106,6 +108,19 @@ const CONTEXT_HARD_LIMIT_CAP = 256_000;
 const CONTEXT_HANDOFF_AT_CAP = 200_000;
 const CONTEXT_HANDOFF_RESERVE = 8_000;
 const CONTEXT_SAFE_OUTPUT_RESERVE = 16_000;
+/**
+ * The budget Team gives the long-gap gate's judge when the row states none.
+ *
+ * The engine's own default is five seconds, which is sized for a judge beside
+ * the Host. A hosted endpoint answers in up to about four seconds, and the gate
+ * hands the judge one second less than this deadline, so that default turns a
+ * slow-but-working judge into a coin flip — and the deployment that meets this
+ * problem is the one least able to diagnose it. Ten seconds leaves room for the
+ * slow tail while still bounding the wait on the path that starts a turn. A
+ * deployment that wants another number still sets `gate.judgeTimeoutMs`, which
+ * stays a row field.
+ */
+const TEAM_JUDGE_TIMEOUT_DEFAULT_MS = 10_000;
 /**
  * Usage at or above which an acknowledged acceptance advises a fresh
  * rollover instead of keeping the context; capped by the route's effective
@@ -173,6 +188,29 @@ export class AgentTeamDmDeliveryError extends Error {
         this.name = 'AgentTeamDmDeliveryError';
     }
 }
+/**
+ * The judge's fields as one row form. Every one is volatile, because that is
+ * what makes the settings service offer them and what lets a key written in the
+ * Team settings surface mount the judge without restarting the Host; the key
+ * alone is a secret, so a read reports that it is set and never its value.
+ */
+const TEAM_JUDGE_SETTINGS_SCHEMA = z.object({
+    apiKey: z.string().role('secret').volatile().description('API key for the relatedness judge. Setting one enables jev-backed context management; clearing it disables it.'),
+    apiKeyEnv: z.string().volatile().description('Environment variable holding the key, when the key is not stated here. Default: TYPESAFE_API_KEY'),
+    model: z.string().volatile().description('Model id sent with every judgement. Default: the jev plugin\'s own default.'),
+    apiBase: z.string().volatile().description('Endpoint base the judgements go to. Default: the jev plugin\'s own default.'),
+});
+/**
+ * The Host row's whole schema: the profile fields verbatim, so their volatility
+ * and defaults stay owned by {@link HUMAN_PROFILE_SETTINGS_SCHEMA}, plus the
+ * gate and the judge. A patch layer that targets this row replaces its whole
+ * config, so the parts are declared together here and nowhere else.
+ */
+export const TEAM_HOST_ROW_SETTINGS_SCHEMA = z.object({
+    ...HUMAN_PROFILE_SETTINGS_SCHEMA.dict,
+    gate: TEAM_PRESSURE_GATE_SCHEMA,
+    jev: TEAM_JUDGE_SETTINGS_SCHEMA,
+});
 let AgentTeam = (() => {
     let _classSuper = TypertRemoteService;
     let _instanceExtraInitializers = [];
@@ -197,6 +235,7 @@ let AgentTeam = (() => {
     let _sendMessage_decorators;
     let _putAttachment_decorators;
     let _getAttachment_decorators;
+    let _contextJudgeForClient_decorators;
     let _environmentForClient_decorators;
     let _humanProfileForClient_decorators;
     let _putHumanAvatar_decorators;
@@ -234,6 +273,7 @@ let AgentTeam = (() => {
             _sendMessage_decorators = [Remote('sendMessage')];
             _putAttachment_decorators = [Remote('putAttachment')];
             _getAttachment_decorators = [Remote('getAttachment')];
+            _contextJudgeForClient_decorators = [Remote('contextJudge')];
             _environmentForClient_decorators = [Remote('environment')];
             _humanProfileForClient_decorators = [Remote('humanProfile')];
             _putHumanAvatar_decorators = [Remote('putHumanAvatar')];
@@ -268,6 +308,7 @@ let AgentTeam = (() => {
             __esDecorate(this, null, _sendMessage_decorators, { kind: "method", name: "sendMessage", static: false, private: false, access: { has: obj => "sendMessage" in obj, get: obj => obj.sendMessage }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _putAttachment_decorators, { kind: "method", name: "putAttachment", static: false, private: false, access: { has: obj => "putAttachment" in obj, get: obj => obj.putAttachment }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getAttachment_decorators, { kind: "method", name: "getAttachment", static: false, private: false, access: { has: obj => "getAttachment" in obj, get: obj => obj.getAttachment }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _contextJudgeForClient_decorators, { kind: "method", name: "contextJudgeForClient", static: false, private: false, access: { has: obj => "contextJudgeForClient" in obj, get: obj => obj.contextJudgeForClient }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _environmentForClient_decorators, { kind: "method", name: "environmentForClient", static: false, private: false, access: { has: obj => "environmentForClient" in obj, get: obj => obj.environmentForClient }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _humanProfileForClient_decorators, { kind: "method", name: "humanProfileForClient", static: false, private: false, access: { has: obj => "humanProfileForClient" in obj, get: obj => obj.humanProfileForClient }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _putHumanAvatar_decorators, { kind: "method", name: "putHumanAvatar", static: false, private: false, access: { has: obj => "putHumanAvatar" in obj, get: obj => obj.putHumanAvatar }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -284,7 +325,7 @@ let AgentTeam = (() => {
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         config = __runInitializers(this, _instanceExtraInitializers);
-        static Config = HUMAN_PROFILE_SETTINGS_SCHEMA;
+        static Config = TEAM_HOST_ROW_SETTINGS_SCHEMA;
         static inject = [
             'storageDomain',
             'workspaceRegistry',
@@ -333,6 +374,16 @@ let AgentTeam = (() => {
          */
         memberFailures = new Map();
         pressurePolicy;
+        /**
+         * The gate thresholds the pressure policy reads, and the only copy of them:
+         * refreshed in place from the row's volatile config, never replaced, so the
+         * engine's per-step read sees a settings edit without a remount. It starts at
+         * Team's own judge budget and the constructor's refresh replaces that with the
+         * row's, so the budget is never absent at any point a step could read it.
+         */
+        gate = { judgeTimeoutMs: TEAM_JUDGE_TIMEOUT_DEFAULT_MS };
+        /** The long-gap gate's judge: this Host's own `jev` mount, reconciled with the row. */
+        contextJudge;
         notifiedInbox = new Map();
         attachmentGcTimer;
         /**
@@ -398,21 +449,38 @@ let AgentTeam = (() => {
         constructor(ctx, config) {
             super(ctx, 'agentTeam');
             this.config = config;
-            this.pressurePolicy = new PressurePolicyCoordinator({
+            this.refreshGate();
+            this.contextJudge = new TeamContextJudge(this.ctx, {
+                config: () => this.judgeConfig(),
+                deadlineMs: () => this.gate.judgeTimeoutMs ?? TEAM_JUDGE_TIMEOUT_DEFAULT_MS,
+            });
+            this.pressurePolicy = new TeamPressurePolicy({
                 agentForMember: memberId => this.handles.get(memberId)?.agent,
-                memberForAgent: agent => {
-                    const member = this.memberForAgent(agent);
-                    return member === undefined ? undefined : { memberId: member.memberId, sessionId: agent.id };
-                },
-                compactionForAgent: agent => this.ctx.agentPresets.serviceFor(agent, 'compaction'),
                 limitsForAgent: agent => this.routeLimitsForAgent(agent),
+                compactionForAgent: agent => {
+                    const engine = this.compactionForAgent(agent);
+                    return engine === undefined ? undefined : { reduce: (reason, signal) => engine.compactIfNeeded(agent, reason, signal) };
+                },
                 activeClaimLabels: memberId => this.activeClaimLabels(memberId),
                 runningJobLabels: memberId => this.runningJobLabels(memberId),
-                failed: (memberId, _sessionId, diagnostic) => {
+                // Deployment policy: the row's own gate config, whose omitted fields the
+                // engine answers with its own defaults. This object is this Host's one
+                // copy, refreshed in place on every settings write, so an edit reaches the
+                // next step judged instead of the next mount.
+                gate: this.gate,
+                /**
+                 * The relatedness judge of the long-gap gate: the service this Host
+                 * mounts from its own row's key, or one a deployment mounted itself. No
+                 * key and no other mount leaves the gate off — a missing judge is a
+                 * deployment choice, never a failure — and the read is lazy, so a key
+                 * written after this Host mounted still answers on the next step.
+                 */
+                judgeForAgent: () => this.contextJudge.judge(),
+                failed: (memberId, diagnostic) => {
                     this.setMemberFailure(memberId, 'compaction', diagnostic);
                     this.emitAutoCompactionChanged(memberId);
                 },
-                log: message => { this.ctx.logger.warn(`agent-team: ${message}`); },
+                log: (message, memberId) => { this.ctx.logger.warn(`agent-team: ${message} (member ${this.memberLabel(memberId)})`); },
             });
             // Human profile: this Host row's own Config (name + avatarRef, both
             // volatile), so the settings service derives its form from the schema and
@@ -425,7 +493,41 @@ let AgentTeam = (() => {
                 settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, this.ctx.fiber));
                 this.adoptLegacyHumanProfile();
             });
-            this.ctx.on('loader/volatile-update', () => { this.syncHumanHandle(); });
+            this.ctx.on('loader/volatile-update', () => {
+                this.syncHumanHandle();
+                // The whole row is volatile, so every write the settings surface makes is
+                // one reconciliation. The gate comes first: the judge's own budget is
+                // derived from the gate's deadline, so a write that raises both must not
+                // be reconciled against the deadline it replaced.
+                this.refreshGate();
+                void this.contextJudge.sync().catch(error => {
+                    this.ctx.logger.warn('agent-team: the relatedness judge could not be reconciled: %s', error instanceof Error ? error.message : String(error));
+                });
+            });
+        }
+        /** The Host row's judge settings, as one plain config for the mount. */
+        judgeConfig() {
+            return {
+                apiKey: this.config.jev.apiKey.get(),
+                apiKeyEnv: this.config.jev.apiKeyEnv.get(),
+                model: this.config.jev.model.get(),
+                apiBase: this.config.jev.apiBase.get(),
+            };
+        }
+        /**
+         * Copy the row's gate thresholds into the one gate object the pressure policy
+         * holds. Called once at construction and again on every volatile update, so
+         * the policy always reads the thresholds the settings document states.
+         *
+         * Two fields pass through as the row states them, and the engine answers an
+         * omitted one with its own default. The judge's budget does not: a judge is
+         * reached over a network, so Team answers for that number itself rather than
+         * making every deployment discover the engine's local-call default.
+         */
+        refreshGate() {
+            this.gate.tokens = this.config.gate.tokens.get();
+            this.gate.idleMs = this.config.gate.idleMs.get();
+            this.gate.judgeTimeoutMs = this.config.gate.judgeTimeoutMs.get() ?? TEAM_JUDGE_TIMEOUT_DEFAULT_MS;
         }
         /** Current human display name; the single source for team_view and @ matching. */
         humanHandle() {
@@ -536,6 +638,10 @@ let AgentTeam = (() => {
         }
         /** Open the durable ledger and restore every enabled Member independently. */
         async [Service.init]() {
+            // The judge is mounted from the row's own key before the first step can be
+            // judged: a deployment that states one gets the gate from its first turn,
+            // and one that states none keeps the gate off without a failure.
+            await this.contextJudge.sync();
             // The continuity projection registers once per Host: the framework keeps
             // one unit per projection key and drives it for every Session, so Team's
             // fold is session-agnostic and the state carries the identity it folds.
@@ -548,10 +654,10 @@ let AgentTeam = (() => {
                     return;
                 const message = error instanceof Error ? error.message : String(error);
                 this.setMemberFailure(member.memberId, 'runtime', message);
-                const kind = classifyRecoverableError(message);
+                const kind = classifyRecoverableError(error);
                 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.recovery.onError(member.memberId, error);
                 this.emitMemberPresenceChanged(member);
             });
             this.ctx.on('agent/status', ({ agent, status }) => {
@@ -601,7 +707,7 @@ let AgentTeam = (() => {
                 // A successful assistant response ends any open provider-overflow
                 // recovery sequence for this Member.
                 if (event.type === 'assistant/message')
-                    this.pressurePolicy.onAssistantMessage(handle.agent);
+                    this.pressurePolicy.onAssistantMessage(memberId);
                 // Context management reacts only after a successful durable tool/result;
                 // the projection (not this listener) decides what that means.
                 this.contextManagement.onSessionEvent(memberId, handle.agent, event);
@@ -641,10 +747,35 @@ let AgentTeam = (() => {
             const persistedSessions = new Set((await this.persistedSessionHeaders()).map(snapshot => snapshot.header.id));
             await this.sweepWorkspaceParticipations(ledger);
             for (const member of ledger.listMembers()) {
-                if (member.state === 'enabled')
-                    await this.activateMember(member, undefined, persistedSessions);
-                else if (member.state === 'inactive')
-                    await this.memberRuntime.cleanupRemovedMember(member);
+                if (member.state === 'enabled') {
+                    // A renewal or rollover that committed but never finished leaves no
+                    // live handle to reveal it: startup derives the outstanding effects
+                    // from the ledger and the registry's archive set. A Workspace fault
+                    // must not keep the Member from running on its recorded binding, so
+                    // the ordinary activation path still runs when the retire half cannot
+                    // be finished here.
+                    try {
+                        await this.finishMemberTransition(member.memberId, { knownSessions: persistedSessions });
+                    }
+                    catch (error) {
+                        this.ctx.logger.warn(`agent-team: could not finish the recorded Session transition for member '${member.handle}': ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    if (!this.handles.has(member.memberId))
+                        await this.activateMember(member, undefined, persistedSessions);
+                }
+                else {
+                    // Every other durable state converges through the same effect table
+                    // its operation runs after the commit, so a crash or a failed call
+                    // between commit and effect is finished here. One Member's fault
+                    // must not fail the boot: it is logged and retried at the next
+                    // startup, where the call that failed may have healed.
+                    try {
+                        await this.convergeMemberEffects(member);
+                    }
+                    catch (error) {
+                        this.ctx.logger.warn(`agent-team: could not converge member '${member.handle}' to its '${member.state}' state: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
             }
         }
         /**
@@ -834,13 +965,13 @@ let AgentTeam = (() => {
                 return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(stored), workspaceIds: ledger.workspacesOf(stored.memberId) });
             });
         }
-        /** Commit suspended intent, then wait for the owned AgentHandle to become quiescent. */
+        /** Commit suspended intent, then run the suspended row of the effect table: the owned AgentHandle is disposed, the Session stays. */
         async suspendMember(request) {
             return this.enqueueLifecycle(async () => {
                 const result = await this.requireLedger().suspendMember({ ...request, actor: agentTeamHumanActor() });
                 if (result.committed)
                     this.emitCommitted(result.value.receipt);
-                await this.disposeMemberSession(request.memberId, result.value.member);
+                await this.convergeMemberEffects(result.value.member);
                 return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(result.value.member) });
             });
         }
@@ -866,7 +997,9 @@ let AgentTeam = (() => {
          * continuation prompt into its live session, rebuild it after an orphaned
          * preset composition, or re-run activation when no live session exists.
          * Runtime-only — no ledger operation, no suspend. Taking over manually also
-         * cancels any pending automatic recovery episode.
+         * cancels any pending automatic recovery episode. A non-enabled Member
+         * still holding a live handle is an interrupted suspend/archive/remove,
+         * not a stalled one; recovery finishes that cleanup instead of nudging it.
          */
         async recoverMember(request) {
             this.requireAccepting();
@@ -874,9 +1007,36 @@ let AgentTeam = (() => {
             if (member === undefined || !this.requireLedger().participatesIn(request.memberId, request.workspaceId))
                 throw new Error(`unknown Member '${request.memberId}' in workspace '${request.workspaceId}'`);
             this.recovery.stopTracking(request.memberId);
+            const handle = this.handles.get(request.memberId);
+            // A committed renewal or rollover whose retire or activation never finished
+            // is what leaves a Member with no live generation on its binding, or with
+            // the retired generation still live: this explicit recovery path finishes
+            // that recorded transition rather than restarting a Session the ledger has
+            // already moved off. Every other stranded case keeps its old behavior.
+            const stranded = handle === undefined || handle.agent.id !== member.sessionId;
+            if (stranded && member.state === 'enabled' && this.requireLedger().lastTransitionForMember(request.memberId) !== undefined) {
+                this.ctx.logger.info(`agent-team: finishing the recorded Session transition for member '${member.handle}'`);
+                const settled = await this.enqueueLifecycle(async () => {
+                    await this.finishMemberTransition(request.memberId);
+                    return this.requireLedger().getMember(request.memberId) ?? member;
+                });
+                return Object.freeze({ status: this.memberStatus(settled) });
+            }
+            // A live handle on a non-enabled Member is the residue of a suspend,
+            // archive, or removal whose disposal failed after its commit: the
+            // durable state already says no live generation, so explicit recovery
+            // re-runs that state's effects rather than feeding the stray generation
+            // a resume prompt or rebuilding it as if it were enabled.
+            if (member.state !== 'enabled' && handle !== undefined) {
+                this.ctx.logger.info(`agent-team: finishing the interrupted ${member.state} cleanup for member '${member.handle}'`);
+                const settled = await this.enqueueLifecycle(async () => {
+                    await this.convergeMemberEffects(member);
+                    return this.requireLedger().getMember(request.memberId) ?? member;
+                });
+                return Object.freeze({ status: this.memberStatus(settled) });
+            }
             // An orphaned composition cannot be steered: its tools are gone, so a
             // continuation prompt reaches an inert Member. Rebuild the Agent in place.
-            const handle = this.handles.get(request.memberId);
             if (handle !== undefined && this.ctx.agentPresets.composedPreset(handle.agent.ctx) === undefined) {
                 this.ctx.logger.info(`agent-team: rebuilding member '${member.handle}' after its preset composition was orphaned by a reload`);
                 await this.reactivateMember(request.memberId);
@@ -920,27 +1080,50 @@ let AgentTeam = (() => {
                     throw new Error(`unknown Member '${request.memberId}' in workspace '${request.workspaceId}'`);
                 if (stored.state !== 'enabled')
                     throw new Error(`Agent Member '${stored.handle}' is ${stored.state}; only enabled Members can start from a new context`);
-                const active = this.handles.get(request.memberId);
-                if (active === undefined)
-                    throw new Error(`Agent Member '${stored.handle}' has no active session to clear`);
-                if (this.runningAgents.has(active.agent.id))
-                    throw new Error(`Agent Member '${stored.handle}' is still running; wait for the current turn to end before starting from a new context`);
-                const previousSessionId = stored.sessionId;
                 // The fresh id derives from the requestId, so a retried identical
                 // request mints the same id and the ledger dedupes it instead of
                 // colliding; the format matches addMember's `agent-team-<uuid>`.
                 const sessionId = SessionId(`agent-team-${request.requestId}`);
+                // A renewal this request already committed IS the desired binding: its
+                // retire or activation effects may still be outstanding, so finish them
+                // first, then answer with the recorded result either way. A repeat never
+                // commits a second binding, and never reports an effect that did not run
+                // as though it had — the status below carries that truth.
+                if (this.requireLedger().hasCommitted(request.requestId)) {
+                    try {
+                        await this.finishMemberTransition(request.memberId);
+                    }
+                    catch (error) {
+                        this.ctx.logger.warn(`agent-team: could not finish the recorded context renewal for member '${stored.handle}': ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    const recorded = await this.requireLedger().renewMemberSession({ ...request, sessionId, actor: agentTeamHumanActor() });
+                    const current = this.requireLedger().getMember(request.memberId) ?? stored;
+                    return Object.freeze({ receipt: recorded.value.receipt, status: this.memberStatus(current) });
+                }
+                const active = this.handles.get(request.memberId);
+                if (active === undefined) {
+                    // With no live generation to retire, an earlier transition may be what
+                    // left the Member here; finishing it is what lets this request run at
+                    // all. With none, the ordinary no-session refusal below stands.
+                    await this.finishMemberTransition(request.memberId);
+                }
+                const retiring = this.handles.get(request.memberId);
+                if (retiring === undefined)
+                    throw new Error(`Agent Member '${stored.handle}' has no active session to clear`);
+                if (this.runningAgents.has(retiring.agent.id))
+                    throw new Error(`Agent Member '${stored.handle}' is still running; wait for the current turn to end before starting from a new context`);
                 const result = await this.requireLedger().renewMemberSession({ ...request, sessionId, actor: agentTeamHumanActor() });
-                if (result.committed)
-                    this.emitCommitted(result.value.receipt);
-                else {
-                    // A retried identical request already renewed this Member; report the
-                    // recorded outcome without another dispose/reactivate cycle.
-                    return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(result.value.member) });
+                if (!result.committed) {
+                    // Another caller recorded this requestId between the check above and
+                    // the write; report its recorded outcome as the retry path does.
+                    const current = this.requireLedger().getMember(request.memberId) ?? stored;
+                    return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(current) });
                 }
+                this.emitCommitted(result.value.receipt);
                 const renewed = result.value.member;
-                await this.retireMemberGeneration(request.memberId, active, previousSessionId);
-                await this.activateMember(renewed, undefined, undefined, previousSessionId);
+                // This request retired the previous generation itself, so the activation
+                // is planned rather than recovered: pass the fork parent it just left.
+                await this.finishMemberTransition(renewed.memberId, { forkedFrom: stored.sessionId });
                 const reactivated = this.handles.get(request.memberId);
                 if (reactivated === undefined) {
                     // Reactivation failed; the activation diagnostic carries the reason and
@@ -950,6 +1133,79 @@ let AgentTeam = (() => {
                 return Object.freeze({ receipt: result.value.receipt, status: this.memberStatus(renewed) });
             });
         }
+        /**
+         * Finish one Member's committed Session transition, whichever half a failure
+         * interrupted. The ledger already records the binding the Member should run
+         * and the Session it left, so only external effects remain and each is
+         * derived fresh: a generation still live on the old Session is retired, the
+         * retired Session is archived once the registry does not yet report it
+         * archived, and the target activates when no live generation runs it.
+         *
+         * A live handle alone never decides completion — disposal can succeed and
+         * leave the archive half owed — so the registry's own archive set is the
+         * evidence for that step.
+         *
+         * `forkedFrom` marks a PLANNED in-process activation (the caller just
+         * retired that Session in this same request): `activateMember` reads its
+         * absence as a recovered Session that may never have materialized and runs
+         * the handoff-reconstruction path. Startup, retry, and explicit recovery
+         * therefore leave it unset; only the request that committed the transition
+         * supplies it.
+         *
+         * Callers must already hold the lifecycle queue (or run before any other
+         * lifecycle work): this method does not re-enter it.
+         */
+        async finishMemberTransition(memberId, options) {
+            const member = this.requireLedger().getMember(memberId);
+            if (member === undefined || member.state !== 'enabled')
+                return;
+            const transition = this.requireLedger().lastTransitionForMember(memberId);
+            if (transition === undefined)
+                return;
+            const live = this.handles.get(memberId);
+            if (live !== undefined && live.agent.id !== member.sessionId) {
+                await this.retireMemberGeneration(memberId, live, live.agent.id);
+            }
+            if (!this.ctx.workspaceRegistry.archivedSessionIds.includes(transition.previousSessionId)) {
+                await this.ctx.workspaceRegistry.archiveSession(transition.previousSessionId);
+            }
+            if (this.handles.get(memberId) === undefined) {
+                await this.activateMember(member, undefined, options?.knownSessions, options?.forkedFrom);
+            }
+        }
+        /**
+         * Converge one Member's external effects onto its durable lifecycle state
+         * — the single effect table every lifecycle operation runs right after its
+         * commit and startup re-runs for every non-enabled Member:
+         *
+         * - `suspended`: no live handle; the Session and private memory stay.
+         * - `archived`: no live handle; the Session is hidden from grouping
+         *   surfaces while its log and private memory stay on disk.
+         * - `inactive`: no live handle; the Session is archived and the private
+         *   memory deleted — removeMember's cleanup primitives.
+         *
+         * `enabled` has no entry here: its effects belong to the recorded Session
+         * transition and activation. Every step is derived from the durable state
+         * and safe to repeat — the registry's archive set decides whether the
+         * hide half is owed, disposal tolerates an absent handle, and removal
+         * cleanup force-tolerates an already-cleaned target — so a repeat after a
+         * crash or a failed call runs exactly the owed steps and never a second
+         * durable write. Callers must already hold the lifecycle queue (or run
+         * before any other lifecycle work, as startup does).
+         */
+        async convergeMemberEffects(member) {
+            if (member.state === 'enabled')
+                return;
+            await this.disposeMemberSession(member.memberId, member);
+            if (member.state === 'archived') {
+                if (!this.ctx.workspaceRegistry.archivedSessionIds.includes(member.sessionId)) {
+                    await this.ctx.workspaceRegistry.archiveSession(member.sessionId);
+                }
+            }
+            else if (member.state === 'inactive') {
+                await this.memberRuntime.cleanupRemovedMember(member);
+            }
+        }
         /**
          * Retire one Member's previous generation after its durable binding moved
          * onto a new Session id: drop the old handle's transient state, dispose the
@@ -1179,8 +1435,7 @@ let AgentTeam = (() => {
                 const result = await this.requireLedger().removeMember({ ...request, actor: agentTeamHumanActor() });
                 if (result.committed)
                     this.emitCommitted(result.value.receipt);
-                await this.disposeMemberSession(request.memberId, result.value.member);
-                await this.memberRuntime.cleanupRemovedMember(result.value.member);
+                await this.convergeMemberEffects(result.value.member);
                 return result.value;
             });
         }
@@ -1195,8 +1450,7 @@ let AgentTeam = (() => {
                 const result = await this.requireLedger().archiveMember({ ...request, actor: agentTeamHumanActor() });
                 if (result.committed)
                     this.emitCommitted(result.value.receipt);
-                await this.disposeMemberSession(request.memberId, result.value.member);
-                await this.ctx.workspaceRegistry.archiveSession(result.value.member.sessionId);
+                await this.convergeMemberEffects(result.value.member);
                 return result.value;
             });
         }
@@ -1258,15 +1512,18 @@ let AgentTeam = (() => {
         /**
          * Resolve uploaded ids and agent-supplied absolute paths into one attachment
          * metadata list. Paths are all validated before anything is copied, so one
-         * rejection leaves the cache untouched and the message uncommitted.
+         * rejection leaves the cache untouched and the message uncommitted. Each copy
+         * takes the id its request derives, so a retry converges on the entry the
+         * first attempt prepared instead of writing an orphan.
          */
         async resolveMessageAttachments(request) {
             const fromPaths = [];
             if (request.attachmentPaths !== undefined && request.attachmentPaths.length > 0) {
                 for (const absolutePath of request.attachmentPaths)
                     await validatePathAttachment(absolutePath);
-                for (const absolutePath of request.attachmentPaths)
-                    fromPaths.push(Object.freeze(await copyPathAttachment(attachmentsRoot(), absolutePath)));
+                for (const [index, absolutePath] of request.attachmentPaths.entries()) {
+                    fromPaths.push(Object.freeze(await copyPathAttachment(attachmentsRoot(), absolutePath, pathAttachmentId(request.requestId, index), request.requestId)));
+                }
             }
             return [...fromPaths, ...await this.prepareAttachments(request.attachments)];
         }
@@ -1294,7 +1551,12 @@ let AgentTeam = (() => {
             const lines = metadata.map(attachment => `[attachment] ${attachmentPayloadPath(attachment.attachmentId, attachment.name)}`);
             return `${trimmed}\n${lines.join('\n')}`;
         }
-        /** Upload one composer attachment into the cache; bytes are immutable once written. */
+        /**
+         * Upload one composer attachment into the cache; bytes are immutable once
+         * written. The requestId is the idempotency key: a retried upload derives
+         * the same cache id and replays the original result, while reusing that key
+         * for a different payload is refused as a request collision.
+         */
         async putAttachment(request) {
             this.requireAccepting();
             this.requireWorkspace(request.workspaceId);
@@ -1304,16 +1566,45 @@ let AgentTeam = (() => {
             if (bytes.byteLength > ATTACHMENT_MAX_BYTES)
                 throw new Error(`attachment exceeds the ${ATTACHMENT_MAX_BYTES} byte limit`);
             const mediaType = sanitizeMediaType(request.mediaType);
-            const attachmentId = newAttachmentId();
-            return Object.freeze(await writeAttachment(attachmentsRoot(), attachmentId, request.name, mediaType, bytes));
+            return Object.freeze(await writeRequestScopedAttachment(attachmentsRoot(), request.requestId, request.name, mediaType, bytes));
         }
-        /** Read one cached attachment back for client display; gone entries throw and the UI degrades to a chip. */
+        /**
+         * Read one cached attachment back for client display. A gone entry is the
+         * one expected failure on this path, so it carries the stable
+         * `team/attachment-not-found` code the Client branches on; anything else
+         * (unreadable metadata, filesystem trouble) stays an unknown Host error.
+         */
         async getAttachment(request) {
             const stored = await readAttachment(attachmentsRoot(), request.attachmentId);
             if (stored === undefined)
-                throw new Error(`attachment '${request.attachmentId}' is no longer cached`);
+                throw new RemoteError('team/attachment-not-found', `attachment '${request.attachmentId}' is no longer cached`, { attachmentId: request.attachmentId });
             return Object.freeze({ name: stored.name, mediaType: stored.mediaType, byteSize: stored.byteSize, bytesBase64: stored.bytes.toString('base64') });
         }
+        /**
+         * The long-gap gate's judge, as the Team settings surface states it: whether
+         * a judge is reachable, why not when none is, and the thresholds in force.
+         * The judge's own fields (key presence, endpoint, model) ride the settings
+         * document this row already publishes, so nothing here restates them; the
+         * gate's thresholds are row configuration the settings document deliberately
+         * omits, which is why the Host resolves an omitted field here rather than
+         * letting a second copy of those numbers exist. Two of the three fall back to
+         * the engine's own default; the judge's budget falls back to Team's, because
+         * that is the number the gate itself is given.
+         */
+        contextJudgeForClient(_request) {
+            const status = this.contextJudge.status();
+            const gate = this.gate;
+            return Object.freeze({
+                ...status,
+                gate: Object.freeze({
+                    tokens: gate.tokens ?? DEFAULT_GATE_TOKENS,
+                    idleMs: gate.idleMs ?? DEFAULT_GATE_IDLE_MS,
+                    // No fallback here: this number is the one the gate is given, so a
+                    // second default could only ever disagree with the gate in force.
+                    judgeTimeoutMs: gate.judgeTimeoutMs,
+                }),
+            });
+        }
         /**
          * Human profile read for the settings page and footnote: name + avatar
          * reference from this Host row's live Config plus version facts. Human-scoped
@@ -1541,8 +1832,8 @@ let AgentTeam = (() => {
                 const taskBoundaryThreshold = Math.min(ACCEPT_TASK_BOUNDARY_THRESHOLD, limits.handoffAt);
                 if (limits.usageTokens >= limits.handoffAt) {
                     return Object.freeze({ usageTokens: limits.usageTokens, taskBoundaryThreshold, handoffAt: limits.handoffAt, hardLimit: limits.hardLimit,
-                        action: 'handoff-now',
-                        guidance: 'You are at or above the handoff budget. Finish the current atomic action and unsettled evidence, then call context_rollover with a fresh handoff now.' });
+                        action: 'compact-now',
+                        guidance: 'You are at or above the handoff budget. Finish the current atomic action and unsettled evidence, then call context_compact with a summary you write yourself — that shortens this generation in place, keeps your recent work verbatim, and is the default. Roll over only when the work has turned a page.' });
                 }
                 if (limits.usageTokens >= taskBoundaryThreshold) {
                     return Object.freeze({ usageTokens: limits.usageTokens, taskBoundaryThreshold, handoffAt: limits.handoffAt, hardLimit: limits.hardLimit,
@@ -1972,6 +2263,16 @@ let AgentTeam = (() => {
                 this.ctx.logger.info(`agent-team: redelivered ${redelivered} carried input message(s) for member '${this.memberLabel(member.memberId)}' after the rollover crash recovery`);
             return redelivered;
         }
+        /**
+         * The compaction capability in one Member Agent's preset scope, or undefined
+         * when its composition mounts none. Both the pressure policy (the hard limit)
+         * and the engine's `context_compact` tool ask through here, so which realm
+         * holds the engine is stated once: a preset revision publishes services
+         * behind its own isolate, which `agent.ctx.get` cannot see from outside.
+         */
+        compactionForAgent(agent) {
+            return this.ctx.agentPresets.serviceFor(agent, 'compaction');
+        }
         /**
          * Agent-only checkpoint request validation: the tool calls this inside its
          * own running turn. Like `context_rollover`, the tool performs no side effect —
@@ -2007,10 +2308,10 @@ let AgentTeam = (() => {
         async contextTimelineForAgent(agent, request) {
             const member = this.memberForAgent(agent);
             if (member === undefined || member.state !== 'enabled')
-                throw new Error('context_timeline requires an active Team Member');
+                throw new Error('context_status requires an active Team Member');
             const limit = request.limit === undefined ? DEFAULT_TIMELINE_LIMIT : Math.trunc(request.limit);
             if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_TIMELINE_LIMIT)
-                throw new Error(`context_timeline limit must be between 1 and ${MAX_TIMELINE_LIMIT}`);
+                throw new Error(`context_status limit must be between 1 and ${MAX_TIMELINE_LIMIT}`);
             const meter = agent.ctx.get('tokenMeter');
             const measurement = meter?.measure(agent.session);
             const usageTokens = measurement?.totalTokens ?? 0;
@@ -2225,7 +2526,7 @@ let AgentTeam = (() => {
             if (request.checkpointRef === undefined)
                 return { mode: 'fresh' };
             if (!/^(context-checkpoint-[0-9a-f]{64}|team-boundary-[0-9a-f]{64})$/.test(request.checkpointRef))
-                throw new Error('checkpointRef must be an opaque ref exactly as returned by context_timeline');
+                throw new Error('checkpointRef must be an opaque ref exactly as returned by context_status');
             // Full current-state prevalidation through the ONE resolver the swap
             // itself uses: a ref that is fabricated, unattributable, nonshrinking,
             // unmeasurable, over-budget, or blocked by multiple active Claims
@@ -2278,25 +2579,69 @@ let AgentTeam = (() => {
         }
         /** Shared Task-creation commit: resolve uploads into metadata lines and append through the ledger. */
         async sendMessageAs(actor, request) {
-            const metadata = await this.resolveMessageAttachments(request);
-            const result = await this.requireLedger().sendMessage({
-                ...request, body: this.appendAttachmentLines(request.body, metadata),
-                ...(metadata.length === 0 ? {} : { resolvedAttachments: metadata }),
-                actor,
-            });
-            this.emitCommittedOutcome(result);
-            return result.value;
+            try {
+                const metadata = await this.resolveMessageAttachments(request);
+                const result = await this.requireLedger().sendMessage({
+                    ...request, body: this.appendAttachmentLines(request.body, metadata),
+                    ...(metadata.length === 0 ? {} : { resolvedAttachments: metadata }),
+                    actor,
+                });
+                this.emitCommittedOutcome(result);
+                return result.value;
+            }
+            catch (error) {
+                await this.dropUnreferencedPrepared(request, error);
+                throw error;
+            }
         }
         /** Shared existing-Thread reply commit: same upload resolution and outcome emission. */
         async replyAs(actor, request) {
-            const metadata = await this.resolveMessageAttachments(request);
-            const result = await this.requireLedger().reply({
-                ...request, body: this.appendAttachmentLines(request.body, metadata),
-                ...(metadata.length === 0 ? {} : { resolvedAttachments: metadata }),
-                actor,
-            });
-            this.emitCommittedOutcome(result);
-            return result.value;
+            try {
+                const metadata = await this.resolveMessageAttachments(request);
+                const result = await this.requireLedger().reply({
+                    ...request, body: this.appendAttachmentLines(request.body, metadata),
+                    ...(metadata.length === 0 ? {} : { resolvedAttachments: metadata }),
+                    actor,
+                });
+                this.emitCommittedOutcome(result);
+                return result.value;
+            }
+            catch (error) {
+                await this.dropUnreferencedPrepared(request, error);
+                throw error;
+            }
+        }
+        /**
+         * After a failed message or reply attempt, remove the cache entries this
+         * attempt could have prepared — the request-stable path copies — unless a
+         * committed Message references them. The ledger's own reference set is the
+         * guard, so a post-commit failure or a colliding retry can never delete bytes
+         * a stored Message still points at; uploads are untouched, because an
+         * unreferenced upload is a legitimate state the GC owns. Cleanup failures are
+         * logged and never mask the original error.
+         */
+        async dropUnreferencedPrepared(request, cause) {
+            const prepared = (request.attachmentPaths ?? []).map((_, index) => pathAttachmentId(request.requestId, index));
+            if (prepared.length === 0)
+                return;
+            let referenced;
+            try {
+                referenced = this.requireLedger().referencedAttachmentIds();
+            }
+            catch (failure) {
+                this.ctx.logger.warn(`agent-team: could not consult the attachment reference set after a failed message attempt (${String(cause)}): ${String(failure)}`);
+                return;
+            }
+            for (const attachmentId of prepared) {
+                if (referenced.has(attachmentId))
+                    continue;
+                try {
+                    await removeAttachment(attachmentsRoot(), attachmentId);
+                }
+                catch (failure) {
+                    this.ctx.logger.warn(`agent-team: could not drop unreferenced prepared attachment '${attachmentId}' after a failed message attempt: ${String(failure)}`);
+                }
+            }
         }
         /** Fence one Human Remote call: accepting Host, known Workspace, Human actor. */
         humanCall(workspaceId) {
@@ -2417,12 +2762,26 @@ let AgentTeam = (() => {
                             this.contextManagement.captureClaimedInput(agent, messages);
                             return { kind: 'reject' };
                         }
-                        // Team pressure policy rides the same pre-step seam after the
+                        // The engine's pressure policy rides the same pre-step seam after the
                         // admission gate: the handoff-budget notice steers into the running
-                        // turn, and the hard limit forces compaction before the request is
+                        // turn, the hard limit forces a reduction before the request is
                         // forwarded — failing closed blocks the step instead of submitting
-                        // over the Team limit. Missing route capacity is an explicit reject.
-                        const pressure = await this.pressurePolicy.onPreStep(agent, signal);
+                        // over the limit — and a step arriving into a large context after a
+                        // long gap may be held instead of admitted.
+                        const member = this.memberForAgent(agent);
+                        const pressure = member === undefined
+                            ? { kind: 'continue' }
+                            : await this.pressurePolicy.onPreStep(member.memberId, messages, signal);
+                        if (pressure.kind === 'hold') {
+                            // The gate kept the messages this step had claimed, and its one
+                            // rollover instruction is already steered into their place. Arming
+                            // the hold and keeping those messages are one call; the coordinator
+                            // owns both exits from here — the input comes back once the driver
+                            // converges, or rides into the next generation if the rollover
+                            // lands — so this turn ends with nothing further to do.
+                            this.contextManagement.holdClaimedInput(agent, messages);
+                            return { kind: 'reject' };
+                        }
                         if (pressure.kind === 'reject')
                             return { kind: 'reject' };
                         const decision = await next();
@@ -2431,10 +2790,11 @@ let AgentTeam = (() => {
                         this.contextManagement.captureClaimedInput(agent, messages);
                         return { kind: 'reject' };
                     });
-                    // Provider context-overflow recovery: one bounded compact-and-retry
-                    // sequence per failure chain through the Team-owned policy.
+                    // Provider context-overflow recovery: one bounded reduce-and-retry
+                    // sequence per failure chain through the engine's policy.
                     agentCtx.on('agent/request-error', async ({ agent, failure, signal }, next) => {
-                        const retry = await this.pressurePolicy.onRequestError(agent, failure, signal);
+                        const member = this.memberForAgent(agent);
+                        const retry = member !== undefined && await this.pressurePolicy.onRequestError(member.memberId, failure, signal);
                         if (retry)
                             return { kind: 'retry' };
                         return next();
@@ -2735,42 +3095,67 @@ let AgentTeam = (() => {
                 throw new Error('agent-team service is shutting down');
         }
         emitCommitted(receipt) {
-            this.ctx.emit('agent-team/committed', { receipt });
+            // Everything below runs after the ledger append, so nothing here may turn
+            // a committed operation into a failed Remote call. Each effect that runs
+            // third-party code — Cordis listeners, change waiters, agent wakes — goes
+            // through `afterCommit`; the ordering itself is unchanged: listeners,
+            // then Client invalidation, then the participation notice, then wakes.
+            this.afterCommit('commit listener dispatch', () => this.ctx.emit('agent-team/committed', { receipt }));
             const operation = this.ledger?.getOperation(receipt.operationId);
             if (operation === undefined) {
-                this.emitChanged();
+                this.afterCommit('change invalidation', () => this.emitChanged());
                 return;
             }
             const ledger = this.requireLedger();
-            this.emitChanged(ledger.changeScopesOf(operation));
+            this.afterCommit('change invalidation', () => this.emitChanged(ledger.changeScopesOf(operation)));
             if (operation.kind === 'team/member-workspace-joined' || operation.kind === 'team/member-workspace-left') {
-                const agent = this.handles.get(operation.data.memberId)?.agent;
-                if (agent !== undefined) {
+                this.afterCommit('participation notice', () => {
+                    const agent = this.handles.get(operation.data.memberId)?.agent;
+                    if (agent === undefined)
+                        return;
                     const path = this.ctx.workspaceRegistry.get(operation.data.workspaceId)?.path;
                     const text = `Team participation changed: you have ${operation.kind === 'team/member-workspace-joined' ? 'joined' : 'left'} Workspace ${operation.data.workspaceId}${path === undefined ? ' (path unavailable)' : ` (${JSON.stringify(path)})`}.\nCurrent Workspace ids: ${ledger.workspacesOf(operation.data.memberId).join(', ')}. This replaces earlier participation information. Your Session and cwd have not moved.`;
                     const notice = createUserMessage({ content: [{ type: 'text', text }],
                         source: { kind: AGENT_TEAM_PLUGIN_ID, form: 'notice', summary: 'Team Workspace participation changed' } });
-                    try {
-                        if (agent.status === 'idle' || agent.inbox.nextTurn.some(message => message.source.kind === 'user'))
-                            agent.followup(notice);
-                        else
-                            agent.steer(notice);
-                    }
-                    catch (error) {
-                        // Notification delivery cannot roll back a committed participation.
-                        this.ctx.logger.warn(`agent-team: participation notice not delivered: ${error instanceof Error ? error.message : String(error)}`);
-                    }
-                }
+                    // Delivered from durable facts; a failed wake cannot roll back the
+                    // committed participation — the next notice rederives it.
+                    if (agent.status === 'idle' || agent.inbox.nextTurn.some(message => message.source.kind === 'user'))
+                        agent.followup(notice);
+                    else
+                        agent.steer(notice);
+                });
             }
             for (const memberId of ledger.affectedMembersOf(operation)) {
                 const handle = this.handles.get(memberId);
                 if (handle !== undefined)
-                    this.notifyMember(handle.agent);
+                    this.afterCommit(`notification for '${this.memberLabel(memberId)}'`, () => this.notifyMember(handle.agent));
             }
             // Task acceptance no longer schedules standalone auto compaction: it is
             // a semantic checkpoint/context cue (delivered as ordinary Team
             // notification), and the Team pressure policy owns compaction entry.
         }
+        /**
+         * Run one effect that follows the ledger append. The operation is durable by
+         * the time this runs, so a delivery or listener failure degrades to a log
+         * line: the Remote answer stays the committed result instead of a false
+         * rollback, and an Inbox wake that failed clears its own signature, so the
+         * next commit touching that Member rederives the same durable facts and
+         * retries without appending a second operation.
+         *
+         * An invariant divergence is the deliberate exception — the invariant
+         * companion re-raises it on the caller's frame precisely to stay loud, and
+         * swallowing it would silence a failed integrity check.
+         */
+        afterCommit(label, effect) {
+            try {
+                effect();
+            }
+            catch (error) {
+                if (error instanceof AgentTeamInvariantError)
+                    throw error;
+                this.ctx.logger.warn(`agent-team: post-commit ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         /** Model-visible active-Claim labels for the pressure notice. */
         activeClaimLabels(memberId) {
             const ledger = this.ledger;