@wowyuarm/dsh-agent-team 0.1.8 → 0.1.10

package/packages/agent-team/lib/member-context.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SessionLogOffset } from '@deepseek-ai/dsh-session';
+import { memberMemoryDirectoryPath } from "./member-runtime.js";
 export const name = 'wowyuarm-agent-team-member-context';
 const MAX_MEMORY_BYTES = 8 * 1024;
 const BEGIN = '<team-member-private-memory>';
@@ -20,12 +21,15 @@ export function apply(ctx) {
         const member = host.memberForAgent(agent);
         if (member === undefined)
             return decision;
+        // The sanitized path is authoritative: activation migrated any legacy
+        // colon directory onto it before this member could run a step.
+        const memoryPath = memberMemoryDirectoryPath(member);
         let memory;
         try {
-            memory = renderMemberMemory(await readFile(`${member.privateMemoryPath}/memory.md`), member.privateMemoryPath);
+            memory = renderMemberMemory(await readFile(`${memoryPath}/memory.md`), memoryPath);
         }
         catch (error) {
-            memory = renderUnavailableMemory(member.privateMemoryPath, error.code === 'ENOENT'
+            memory = renderUnavailableMemory(memoryPath, error.code === 'ENOENT'
                 ? 'memory.md is absent; the private memory index is empty.'
                 : 'memory.md is currently unreadable; do not use any earlier private memory context.');
         }

package/packages/agent-team/lib/member-runtime.js

@@ -13,7 +13,7 @@
  *
  * @module @wowyuarm/dsh-agent-team/member-runtime
  */
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { scopeOf } from '@deepseek-ai/dsh-scope';
@@ -32,6 +32,9 @@ export const AGENT_TEAM_TOOL_NAMES = Object.freeze([
     'team_message',
     'team_claim',
     'team_view',
+    'context_rollover',
+    'context_checkpoint',
+    'context_timeline',
 ]);
 /** Copy a Remote-supplied capability overlay into owned frozen storage. */
 export function deepCopyCapabilities(capabilities) {
@@ -41,6 +44,31 @@ export function deepCopyCapabilities(capabilities) {
         ...(capabilities.skills === undefined ? {} : { skills: copyAllow(capabilities.skills.allow) }),
     };
 }
+/**
+ * Filesystem directory segment for one Member's private memory namespace.
+ * The `member:<uuid>` ref is a durable ledger identity and must never appear
+ * in a path: Windows rejects `:` in a path segment (NTFS parses it as an
+ * Alternate Data Stream separator), which made Member activation fail at its
+ * first `mkdir` on Windows (issue #7).
+ */
+export function memberMemoryDirectoryName(memberId) {
+    return memberId.replaceAll(':', '-');
+}
+/** The sanitized absolute private-memory path for one Member, regardless of what the ledger recorded. */
+export function memberMemoryDirectoryPath(member) {
+    // Sanitize per segment: only a segment that actually contains the ledger's
+    // member identity colon needs rewriting, and the recorded final segment is
+    // the only place it can appear. The drive-letter colon of a Windows
+    // absolute prefix is not a member identity and must survive untouched, so
+    // a colon-free final segment keeps the recorded path verbatim even when
+    // earlier segments carry colons.
+    const separator = Math.max(member.privateMemoryPath.lastIndexOf('/'), member.privateMemoryPath.lastIndexOf('\\'));
+    const finalSegment = separator === -1 ? member.privateMemoryPath : member.privateMemoryPath.slice(separator + 1);
+    if (!finalSegment.includes(':'))
+        return member.privateMemoryPath;
+    const prefix = separator === -1 ? '' : member.privateMemoryPath.slice(0, separator + 1);
+    return prefix + memberMemoryDirectoryName(member.memberId);
+}
 /** Per-Member runtime state; the four maps dispose together with each Member. */
 export class MemberRuntime {
     deps;
@@ -165,10 +193,12 @@ export class MemberRuntime {
      * scope layer (the traceable-service seam, like the tool restriction):
      * bundled read-only core skills plus this Member's own private directory,
      * with the live selection ref that later capability edits swap in place.
+     * The sanitized directory is authoritative: activateMember migrated any
+     * legacy colon directory onto it before the provider mounted.
      */
     mountMemberSkillProvider(member, agentCtx, selection) {
         this.skillProviderDisposals.set(member.memberId, memberSkills.mountMemberSkillProvider(agentCtx, {
-            skillsDirectory: join(member.privateMemoryPath, 'skills'),
+            skillsDirectory: join(memberMemoryDirectoryPath(member), 'skills'),
             bundledSkillsDirectory: BUNDLED_SKILLS_DIRECTORY,
             selection,
         }));
@@ -183,8 +213,29 @@ export class MemberRuntime {
      * first-run memory.md scaffold. The Member-private skills directory starts
      * empty; the per-Member provider scans exactly this root (default roots
      * excluded).
+     *
+     * Existing installs recorded the pre-fix colon directory in the ledger, and
+     * `privateMemoryPath` is a durable Member fact the renewal path cannot
+     * rewrite: when the legacy directory exists it is renamed onto the sanitized
+     * path once (same-parent rename, atomic), so existing private memory
+     * survives instead of being silently orphaned.
+     *
+     * A colon-form twin directory is also merged when it exists: a Member may
+     * have written files under the ledger identity spelling (the branded
+     * `member:<uuid>` ref is what every Team tool result shows, so a
+     * hand-assembled path carries the colon). Linux accepts the segment
+     * silently — two directories for one Member — while Windows would have
+     * failed the write outright. The twin is never a durable-Member-Fact
+     * candidate: only the files the Member actually wrote there are worth
+     * keeping, and `memory.md` cannot merge, so the sanitized copy always wins
+     * and twin-only notes/skills are moved in without overwriting.
      */
-    async initializePrivateMemory(path) {
+    async initializePrivateMemory(path, legacyPath) {
+        if (legacyPath !== undefined && legacyPath !== path)
+            await migrateLegacyMemoryDirectory(legacyPath, path);
+        const twinPath = twinMemoryDirectoryPath(path);
+        if (twinPath !== undefined)
+            await mergeTwinMemoryDirectory(twinPath, path);
         await mkdir(join(path, 'notes'), { recursive: true });
         await mkdir(join(path, 'skills'), { recursive: true });
         try {
@@ -197,9 +248,14 @@ export class MemberRuntime {
     }
     /** Irreversibly remove one Member: archive its Session and delete its private namespace. */
     async cleanupRemovedMember(member) {
+        // The ledger path may still name the legacy colon directory (never
+        // activated after the fix): remove both spellings; rm is force-tolerant
+        // of the one that does not exist.
+        const sanitized = memberMemoryDirectoryPath(member);
         const results = await Promise.allSettled([
             this.deps.ctx.workspaceRegistry.archiveSession(member.sessionId),
-            rm(member.privateMemoryPath, { recursive: true, force: true }),
+            rm(sanitized, { recursive: true, force: true }),
+            ...(sanitized === member.privateMemoryPath ? [] : [rm(member.privateMemoryPath, { recursive: true, force: true })]),
         ]);
         const failures = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
         if (failures.length > 0)
@@ -227,3 +283,102 @@ export class MemberRuntime {
         this.capabilityWarnings.clear();
     }
 }
+/**
+ * One-time in-place migration of a pre-fix colon-named private memory
+ * directory onto its sanitized path. A sanitized target that already exists
+ * wins (idempotent across restarts and partially migrated installs); a legacy
+ * source that never existed is simply the fresh-install case.
+ */
+async function migrateLegacyMemoryDirectory(legacyPath, path) {
+    let legacy;
+    try {
+        legacy = await stat(legacyPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!legacy.isDirectory())
+        throw new Error(`legacy Member memory path '${legacyPath}' exists but is not a directory`);
+    try {
+        await stat(path);
+        return; // Sanitized directory already present: migration already done or a new install.
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await rename(legacyPath, path);
+}
+/** The colon-form twin path of one sanitized Member memory directory, when the segment form admits one. */
+function twinMemoryDirectoryPath(sanitizedPath) {
+    const separator = Math.max(sanitizedPath.lastIndexOf('/'), sanitizedPath.lastIndexOf('\\'));
+    const prefix = separator === -1 ? '' : sanitizedPath.slice(0, separator + 1);
+    const finalSegment = separator === -1 ? sanitizedPath : sanitizedPath.slice(separator + 1);
+    // Only the exact sanitized identity segment (`member-<uuid>`) has a colon
+    // twin (`member:<uuid>`); any other segment shape has no identity mapping.
+    if (!/^member-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(finalSegment))
+        return undefined;
+    return `${prefix}member:${finalSegment.slice('member-'.length)}`;
+}
+/** The colon-twin trace name for one conflicting file: `note.md` → `note.colon-twin.md`. */
+function colonTwinTraceName(name) {
+    const dot = name.lastIndexOf('.');
+    return dot <= 0 ? `${name}.colon-twin` : `${name.slice(0, dot)}.colon-twin${name.slice(dot)}`;
+}
+/**
+ * Merge a hand-created colon-form twin directory into the sanitized Member
+ * memory directory. Unlike the ledger legacy migration this is a merge, not a
+ * rename: the sanitized directory is the Member's live root (the injected
+ * paths and the skill provider point at it), so on a same-path conflict the
+ * live root's copy wins and the twin's losing copy is preserved beside it
+ * under a `.colon-twin` name instead of being silently discarded. Twin-only
+ * files move in under their own names; the emptied twin directory is then
+ * removed so the drift cannot silently recur.
+ */
+async function mergeTwinMemoryDirectory(twinPath, path) {
+    let twin;
+    try {
+        twin = await stat(twinPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return;
+    }
+    if (!twin.isDirectory())
+        return;
+    await mergeDirectoryContents(twinPath, path);
+    await rm(twinPath, { recursive: true, force: true });
+}
+/** Recursively move every twin file into the live root; an existing live file wins, its twin copy traced beside it. */
+async function mergeDirectoryContents(source, target) {
+    await mkdir(target, { recursive: true });
+    for (const entry of await readdir(source, { withFileTypes: true })) {
+        const sourcePath = join(source, entry.name);
+        const targetPath = join(target, entry.name);
+        if (entry.isDirectory()) {
+            await mergeDirectoryContents(sourcePath, targetPath);
+        }
+        else if (entry.isFile()) {
+            // rename(2) silently REPLACES an existing target on POSIX (the EEXIST
+            // error only exists on Windows, where the colon twin cannot exist at
+            // all), so a collision must be detected, not caught: probe the target
+            // first. Activation is the single serialized writer, so the
+            // probe-to-rename window has no concurrent writer to race.
+            let liveFilePresent = true;
+            try {
+                await stat(targetPath);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                liveFilePresent = false;
+            }
+            // The live root stays authoritative; the twin's losing copy stays
+            // traceable beside it instead of being silently discarded.
+            await rename(sourcePath, liveFilePresent ? join(target, colonTwinTraceName(entry.name)) : targetPath);
+        }
+    }
+}

package/packages/agent-team/lib/member-time-context.js

@@ -0,0 +1,126 @@
+/**
+ * Team Member turn-level clock context.
+ *
+ * The first model step of every eligible Team Member turn appends one
+ * durable, source-attributed clock snapshot: the current instant in the
+ * fixed Team coordination zone (UTC+8), the elapsed time since the
+ * preceding model-visible event, and the ordering authority note. Later
+ * steps of the same turn stay quiet unless the turn runs longer than the
+ * refresh interval, in which case one snapshot lands per elapsed interval —
+ * a tool-dense turn of quick steps produces exactly one line, while a turn
+ * that outlives the interval still shows its real span. The snapshot is an
+ * observation, never ledger authority: sequence and revision, not
+ * wall-clock time, order Team facts.
+ *
+ * This plugin deliberately does not mount the shipped
+ * `@deepseek-ai/dsh-time-context`: its browser-zone policy asks the model to
+ * confirm dates with the user whenever a request carries no unique browser
+ * zone, which is the normal case for background Member wakes (Inbox, DM,
+ * recovery, continuation). The Team coordination zone is fixed instead. If
+ * the harness grows a public non-browser/canonical-zone policy, retire this
+ * row in favor of configuring that plugin.
+ *
+ * State is folded from the Member Session's own events — the same
+ * manual-fold pattern the Host's context projection uses — so restart,
+ * request reconstruction, and compaction all derive identical baselines
+ * without a second durable store.
+ * @module @wowyuarm/dsh-agent-team/member-time-context
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { formatTeamDuration, formatTeamTimestamp } from "./time-format.js";
+export const name = 'wowyuarm-agent-team-member-time-context';
+/** Default minimum spacing between two snapshots within one turn, in ms. */
+export const CLOCK_REFRESH_INTERVAL_MS = 1_800_000;
+function emptyBaseline() {
+    return { lastMessageTime: null, lastInjectionTime: null, lastTurnInjectionTime: null, openTurn: -1 };
+}
+/**
+ * Fold one session event into the clock baseline. Uninterested events return
+ * the same state reference.
+ * @internal exported for tests.
+ */
+export function applyClockEvent(state, event) {
+    switch (event.type) {
+        case 'turn/start':
+            return event.data.turn === state.openTurn ? state
+                : { ...state, lastTurnInjectionTime: null, openTurn: event.data.turn };
+        case 'turn/end':
+            return state.openTurn === -1 ? state : { ...state, lastTurnInjectionTime: null, openTurn: -1 };
+        case 'user/message': {
+            const source = event.data.source;
+            const injected = source.kind === 'plugin' && source.plugin === name;
+            const withMessage = state.lastMessageTime === event.time ? state : { ...state, lastMessageTime: event.time };
+            if (!injected)
+                return withMessage;
+            return { ...withMessage, lastInjectionTime: event.time, lastTurnInjectionTime: event.time };
+        }
+        case 'assistant/message':
+        case 'tool/result':
+            return state.lastMessageTime === event.time ? state : { ...state, lastMessageTime: event.time };
+        default:
+            return state;
+    }
+}
+/** Fold a whole event log into the clock baseline. @internal exported for tests. */
+export function foldClockBaseline(events) {
+    let state = emptyBaseline();
+    for (const event of events)
+        state = applyClockEvent(state, event);
+    return state;
+}
+/**
+ * Whether this step should append a clock snapshot: the first step of a turn
+ * always does (every wake starts with a fresh instant), and a later step
+ * does only when the turn has run longer than the refresh interval since
+ * the last landed snapshot. Skipped steps produce nothing and never
+ * backfill — their span folds into the next snapshot's elapsed.
+ * @internal exported for tests.
+ */
+export function shouldSampleClock(step, now, baseline, refreshIntervalMs) {
+    if (step === 1)
+        return true;
+    return baseline.lastTurnInjectionTime === null || now - baseline.lastTurnInjectionTime >= refreshIntervalMs;
+}
+/** Render one durable clock snapshot text. @internal exported for tests. */
+export function renderClockSnapshot(input) {
+    // A wall-clock rollback clamps elapsed to 0s without rewriting history.
+    const elapsed = input.previous === undefined ? 'unavailable' : formatTeamDuration(input.now - input.previous);
+    const baseline = input.step === 1 ? 'model-visible event' : 'step context';
+    return `Team clock sampled while preparing turn ${input.turn}, step ${input.step}: ${formatTeamTimestamp(new Date(input.now).toISOString())}\n`
+        + `Elapsed since the preceding ${baseline}: ${elapsed}.\n`
+        + 'Team collaboration timestamps use UTC+8. Sequence and revision, not wall-clock time, determine ordering and concurrency.';
+}
+export function apply(ctx, config = {}) {
+    const refreshIntervalMs = config.refreshIntervalMs ?? CLOCK_REFRESH_INTERVAL_MS;
+    ctx.on('agent/pre-step', async ({ agent, turn, step, signal }, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject' || signal.aborted)
+            return decision;
+        // The Host service is resolved at step time, never through plugin inject
+        // (same reason as member-context: the row mounts while the Host itself
+        // is still restoring Members).
+        const host = ctx.get('agentTeam');
+        if (host === undefined)
+            return decision;
+        if (host.memberForAgent(agent) === undefined)
+            return decision;
+        const now = Date.now();
+        // A rollover starts a fresh Session log, so the fold never guesses
+        // elapsed across generations: a missing prior event renders
+        // `unavailable`, not a fabricated baseline.
+        const baseline = foldClockBaseline(agent.session.ownEvents());
+        // Turn-first-step always samples; later steps sample only at the refresh
+        // interval, so a quick tool-dense turn stays at one line.
+        if (!shouldSampleClock(step, now, baseline, refreshIntervalMs))
+            return decision;
+        const previous = step === 1
+            ? baseline.lastMessageTime ?? undefined
+            : baseline.lastTurnInjectionTime ?? undefined;
+        const text = renderClockSnapshot({ now, turn, step, previous });
+        const message = createUserMessage({
+            content: [{ type: 'text', text }],
+            source: { kind: 'plugin', plugin: name, form: 'snapshot', sections: [{ name, text }] },
+        });
+        return { kind: 'enter', messages: [...decision.messages, message] };
+    }, { prepend: true });
+}

package/packages/agent-team/lib/pressure-policy.js

@@ -0,0 +1,199 @@
+/**
+ * Team-owned context pressure policy.
+ *
+ * The Team preset mounts `compaction-basic` with `auto: false`; this
+ * coordinator owns both policy entry points instead — the proactive handoff
+ * notice near the effective handoff budget and the forced CompactionEngine
+ * reduction before any request at or above the effective hard limit — while
+ * reusing the public CompactionEngine implementation. The hard-limit
+ * translation lives in exactly one method; no caller re-derives it.
+ *
+ * Fail-closed rule: at the hard limit, a compaction that no-ops, throws, is
+ * cancelled, or does not advance the durable surface must block the model
+ * request (reject the step) rather than knowingly submit over the Team limit.
+ * A blocked Member keeps its log and reports a recoverable error.
+ * @module @wowyuarm/dsh-agent-team/pressure-policy
+ */
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { CONTEXT_PRESSURE_NOTICE_SUMMARY } from "./context-management.js";
+import { AGENT_TEAM_PLUGIN_ID } from "./context-source.js";
+/** One pressure-notice text; concise, structured, and inside the reserve. */
+export function contextPressureNoticeText(input) {
+    const claims = input.activeClaims.length === 0 ? 'none' : input.activeClaims.join(', ');
+    const jobs = input.runningJobs.length === 0 ? 'none' : `${input.runningJobs.length} running (collect or stop them before switching)`;
+    return [
+        `Context pressure: ${input.usageTokens} tokens measured; the handoff budget is ${input.handoffAt} and the hard limit is ${input.hardLimit}.`,
+        `Active Claims: ${claims}. Owner jobs: ${jobs}.`,
+        'Finish the current atomic action, then call context_rollover with a handoff covering your objective, verified facts, and external side effects — a fresh context is the default path. Record anything durable in your private memory/notes first.',
+    ].join(' ');
+}
+/** Whether one user message is this policy's one-shot pressure notice. */
+function isPressureNotice(message) {
+    const source = message.source;
+    return source?.plugin === AGENT_TEAM_PLUGIN_ID
+        && source?.summary === CONTEXT_PRESSURE_NOTICE_SUMMARY;
+}
+export class PressurePolicyCoordinator {
+    options;
+    /**
+     * Retry budget per agent for the current provider-overflow sequence.
+     * Process-only by design: a restart re-earns one sequence per chain.
+     */
+    overflowRetries = new Map();
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * The one-shot pressure notice is durable Session evidence, not process
+     * state: a `CONTEXT_PRESSURE_NOTICE_SUMMARY` notice already surfaced as a
+     * `user/message`, or still queued in a durable `agent/inbox/spliced`
+     * insert (a steered notice surfaces only at the next step boundary, and a
+     * Host restart replays the splice before surfacing), marks the current
+     * generation as already notified. A resume or restart stays quiet; a
+     * rollover starts a fresh Session whose own event span has no notice yet,
+     * which is exactly the documented re-arm.
+     */
+    noticeDelivered(agent) {
+        for (const event of agent.session.ownEvents()) {
+            if (event.type === 'user/message' && isPressureNotice(event.data))
+                return true;
+            if (event.type === 'agent/inbox/spliced' && event.data.inserted.some(isPressureNotice))
+                return true;
+        }
+        return false;
+    }
+    dispose() {
+        this.disposed = true;
+        this.overflowRetries.clear();
+    }
+    /** A successful assistant response ends any open overflow-recovery sequence. */
+    onAssistantMessage(agent) {
+        this.overflowRetries.delete(agent);
+    }
+    /**
+     * Pre-step policy for one Member agent: below the handoff budget nothing
+     * happens; at the handoff budget one structured notice per generation is
+     * steered into the running turn; at the hard limit the request is forced
+     * through compaction first and fails closed when that cannot be proven.
+     * Returns the decision for the step: `continue` forwards, `reject` blocks.
+     */
+    async onPreStep(agent, signal) {
+        if (this.disposed || signal.aborted)
+            return { kind: 'continue' };
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return { kind: 'continue' };
+        const limits = await this.options.limitsForAgent(agent);
+        if (limits === undefined) {
+            // A missing route capacity must be explicit, never an accidental
+            // unlimited policy: reject the step with a recoverable diagnostic.
+            const diagnostic = 'context pressure policy: the routed model capacity is unknown; refusing to forward a request without a bounded context budget';
+            this.options.failed(member.memberId, member.sessionId, diagnostic);
+            return { kind: 'reject' };
+        }
+        const { usageTokens, hardLimit, handoffAt } = limits;
+        if (usageTokens >= hardLimit) {
+            const outcome = await this.enforceHardLimit(agent, member.memberId, member.sessionId, signal);
+            return outcome ? { kind: 'continue' } : { kind: 'reject' };
+        }
+        if (usageTokens >= handoffAt && !this.noticeDelivered(agent)) {
+            const notice = createUserMessage({
+                content: [{ type: 'text', text: contextPressureNoticeText({
+                            usageTokens, handoffAt, hardLimit,
+                            activeClaims: this.options.activeClaimLabels(member.memberId),
+                            runningJobs: this.options.runningJobLabels(member.memberId),
+                        }) }],
+                source: { kind: 'plugin', plugin: AGENT_TEAM_PLUGIN_ID, form: 'notice', summary: CONTEXT_PRESSURE_NOTICE_SUMMARY },
+            });
+            try {
+                agent.steer(notice);
+            }
+            catch (error) {
+                this.options.log(`context pressure notice failed: ${error instanceof Error ? error.message : String(error)} (member ${member.memberId})`);
+            }
+            return { kind: 'notice' };
+        }
+        return { kind: 'continue' };
+    }
+    /**
+     * Provider-overflow recovery: one bounded compact-and-retry sequence per
+     * open failure chain. Returns whether the request may retry once.
+     */
+    async onRequestError(agent, failure, signal) {
+        if (this.disposed || signal.aborted)
+            return false;
+        if (failure.code !== CONTEXT_WINDOW_EXCEEDED_CODE)
+            return false;
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return false;
+        const retries = this.overflowRetries.get(agent) ?? 0;
+        if (retries >= 1)
+            return false;
+        const engine = this.options.compactionForAgent(agent);
+        if (engine === undefined)
+            return false;
+        const generation = agent.session.surface.replaceGeneration;
+        try {
+            await engine.compactIfNeeded(agent, 'context-overflow', signal);
+        }
+        catch (error) {
+            // Durable prune progress before a later summary failure justifies the
+            // single retry; cancellation never does.
+            if (!signal.aborted && agent.session.surface.replaceGeneration > generation) {
+                this.overflowRetries.set(agent, retries + 1);
+                return true;
+            }
+            this.options.log(`context-overflow recovery failed: ${error instanceof Error ? error.message : String(error)} (member ${member.memberId})`);
+            return false;
+        }
+        if (signal.aborted || agent.session.surface.replaceGeneration <= generation)
+            return false;
+        this.overflowRetries.set(agent, retries + 1);
+        return true;
+    }
+    /**
+     * The one Team hard-limit translation: force a CompactionEngine reduction
+     * in the current Agent/Session and prove it advanced the durable surface
+     * (or measurably reduced pressure) before continuing. Background jobs are
+     * untouched — compaction never cancels or discards them.
+     * @returns whether the request may proceed.
+     */
+    async enforceHardLimit(agent, memberId, sessionId, signal) {
+        const engine = this.options.compactionForAgent(agent);
+        if (engine === undefined) {
+            const diagnostic = 'context hard limit reached and compaction is unavailable in the Member scope; the request was blocked';
+            this.options.failed(memberId, sessionId, diagnostic);
+            return false;
+        }
+        const meter = agent.ctx.get('tokenMeter');
+        const before = meter?.measure(agent.session)?.totalTokens ?? Number.POSITIVE_INFINITY;
+        const generation = agent.session.surface.replaceGeneration;
+        let result;
+        try {
+            result = await engine.compactIfNeeded(agent, 'context-overflow', signal);
+        }
+        catch (error) {
+            const diagnostic = `context hard limit compaction failed: ${error instanceof Error ? error.message : String(error)}; the request was blocked`;
+            this.options.failed(memberId, sessionId, diagnostic);
+            return false;
+        }
+        if (signal.aborted)
+            return false;
+        const after = meter?.measure(agent.session)?.totalTokens ?? Number.POSITIVE_INFINITY;
+        const surfaceAdvanced = agent.session.surface.replaceGeneration > generation;
+        const pressureReduced = meter === undefined ? false : after < before;
+        if (!surfaceAdvanced && !pressureReduced) {
+            // No-op or unchanged replacement generation: fail closed rather than
+            // knowingly submit over the Team limit.
+            const diagnostic = result === null
+                ? 'context hard limit reached and no compactable range exists; the request was blocked'
+                : 'context hard limit compaction produced no measurable reduction; the request was blocked';
+            this.options.failed(memberId, sessionId, diagnostic);
+            return false;
+        }
+        return true;
+    }
+}

package/packages/agent-team/lib/progress-nudge.js

@@ -22,7 +22,7 @@
  * @module @wowyuarm/dsh-agent-team/progress-nudge
  */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
-const PROGRESS_NUDGE_PLUGIN_ID = '@wowyuarm/dsh-agent-team';
+import { AGENT_TEAM_PLUGIN_ID, isCheckpointContinuationMessage } from "./context-source.js";
 /** Notice summary for every nudge this Coordinator injects. */
 export const PROGRESS_NUDGE_NOTICE_SUMMARY = 'Progress visibility reminder';
 export const PROGRESS_NUDGE_TOOL_CALLS_START = 20;
@@ -39,7 +39,7 @@ export function isPublicCommunicationOperationKind(kind) {
 /** Whether one message is a nudge notice this module injected. */
 export function isProgressNudgeNotice(message) {
     const source = message.source;
-    return source.kind === 'plugin' && source.plugin === PROGRESS_NUDGE_PLUGIN_ID
+    return source.kind === 'plugin' && source.plugin === AGENT_TEAM_PLUGIN_ID
         && source.form === 'notice' && source.summary === PROGRESS_NUDGE_NOTICE_SUMMARY;
 }
 /**
@@ -218,7 +218,7 @@ export class ProgressNudgeCoordinator {
         const claimTargets = claimDue ? freshClaimTargets : [];
         const notice = createUserMessage({
             content: [{ type: 'text', text: nudgeNoticeText(state.silentToolCalls, progressTargets, claimTargets) }],
-            source: { kind: 'plugin', plugin: PROGRESS_NUDGE_PLUGIN_ID, form: 'notice', summary: PROGRESS_NUDGE_NOTICE_SUMMARY },
+            source: { kind: 'plugin', plugin: AGENT_TEAM_PLUGIN_ID, form: 'notice', summary: PROGRESS_NUDGE_NOTICE_SUMMARY },
         });
         const pending = {
             messageId: notice.id,
@@ -268,7 +268,15 @@ export class ProgressNudgeCoordinator {
     hasBlockingNotice(agent) {
         for (const message of [...agent.inbox.nextStep, ...agent.inbox.nextTurn]) {
             const source = message.source;
-            if (source.kind !== 'plugin' || source.plugin !== PROGRESS_NUDGE_PLUGIN_ID || source.form !== 'notice')
+            if (source.kind !== 'plugin' || source.plugin !== AGENT_TEAM_PLUGIN_ID)
+                continue;
+            // A queued checkpoint continuation is a pending wake that outranks a
+            // nudge exactly as the notice families above do. It rides the snapshot
+            // form (it must carry its checkpoint ref in a section), so it cannot be
+            // recognized by the notice summary check below.
+            if (isCheckpointContinuationMessage(message))
+                return true;
+            if (source.form !== 'notice')
                 continue;
             if (source.summary !== PROGRESS_NUDGE_NOTICE_SUMMARY)
                 return true;