@wowyuarm/dsh-agent-team 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowyuarm/dsh-agent-team",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "A persistent agent team for long-running collaboration in DeepSeek Harness",
   "repository": {
     "type": "git",
@@ -8,6 +8,7 @@
   },
   "private": false,
   "type": "module",
+  "packageManager": "pnpm@11.7.0",
   "files": [
     "cordis.patch.yml",
     "packages/agent-team/lib/**/*",

package/packages/agent-team/README.md

@@ -16,13 +16,13 @@ Every operation record carries a positive global sequence, unique operation and
 
 `storage-domain` validates every record at the durable read boundary and rejects a backend unit stamped with another version. The Team updates its projection only after `KvTable.put()` resolves. Its Fiber owns the Domain handle; disposal rejects new Service calls through Cordis removal, drains accepted Domain writes, and closes the backend unit before the name can reopen.
 
-Member creation commits one stable Member/session/Workspace/preset/private-memory identity before unpublished Agent setup. Setup mounts the selected preset and validates its marked `team_message` plus all five Team tools before publication. Failure leaves only that Member unavailable. Suspend waits for the owned `AgentHandle` to stop; resume and Host remount restore the exact persisted session.
+Member creation commits one stable Member/session/Workspace/preset/private-memory identity before unpublished Agent setup. Setup mounts the selected preset and validates its marked `team_message` plus all eight Team tools before publication. Failure leaves only that Member unavailable. Suspend waits for the owned `AgentHandle` to stop; resume and Host remount restore the exact persisted session.
 
 Archival is the reversible third state between suspend and remove, for Members and Channels alike. `archiveMember` commits `team/member-archived`, disposes the live session while keeping private memory and the Session log on disk, archives the Session from grouping surfaces, and releases the Member's active Claims with public `claims_released` Activities plus Attention/marker cleanup. `archiveChannel` commits `team/channel-archived` with the same release shape across every owner on the Channel's Threads. Memberships survive both forms — hidden state, not departure. Archived entities are gone from every Team API surface: projections, ref resolution (their Task refs stop resolving, so message bodies render plain text), and ref-addressed reads (`readThread`/`threadHistory`/`threadObservations`/`listClaims` reject with an explicit archived error) — while the facts stay complete in the ledger for replay and a future restore; that boundary is the archival-vs-remove divide. Removal from archived stays available as the data hygiene path; there is no restore entry point yet (mirroring archived dsh sessions).
 
 Members optionally carry durable capability intent (`capabilities.tools.allow`, `capabilities.skills.allow`). It flows verbatim through every lifecycle operation, replays unchanged after Host restart, and commits without known-name validation so Harness upgrades can never break old ledgers; divergence from known names surfaces at activation as derived, non-persisted `capabilityWarnings`. `tools.allow` is a deliberate interface reservation (no UI write path today) that future Runtime Revision manifest orchestration depends on. Edits follow absent-clears semantics like `model`: a caller that does not manage capabilities must echo the stored value back or its edit clears the override.
 
-Activation applies `tools.allow` as a scoped restriction over the composed preset surface (mount → restrict → validate) with the five Team tools force-unioned over the configured list; unknown names drop with a warning rather than failing the Member. A live allow-list edit swaps the restriction at a turn boundary in the same Session — idle Members apply immediately, and an edit racing a running turn waits for it while later lifecycle operations queue behind the wait. Restriction failures isolate to that Member's activation diagnostic.
+Activation applies `tools.allow` as a scoped restriction over the composed preset surface (mount → restrict → validate) with the eight Team tools force-unioned over the configured list; unknown names drop with a warning rather than failing the Member. A live allow-list edit swaps the restriction at a turn boundary in the same Session — idle Members apply immediately, and an edit racing a running turn waits for it while later lifecycle operations queue behind the wait. Restriction failures isolate to that Member's activation diagnostic.
 
 Skills are Member-private: the preset has no shared skill-filesystem row, and the Host registers one provider per Member that scans exactly the plugin's bundled read-only core skills (`packages/agent-team/core-skills/` — the `member-skill-manager` meta skill that owns all skill craft guidance) plus that Member's writable `skills/` directory under its private memory path (default roots excluded). Installing is writing into the Member's own directory — directory form `skills/<name>/SKILL.md` with optional references and scripts, or a flat `.md` — and there is deliberately no upload Remote. The persona itself only states the private-space physical facts; the meta skill's description routes skill-management work to it. `skills.allow` filters the catalog through a live selection ref swapped at the same turn boundary; the filesystem watcher feeds discovery after a self-install.
 
@@ -40,7 +40,9 @@ M1 supports one Host writer. The ledger is permanent and has no snapshot or comp
 
 The bundle consumes the Host's existing singleton providers; it does not mount replacements for `agents`, default model selection, `tools`, `fs`, `sandboxPolicy`, Session store/persistence, Workspace registry, or storage. Load those Host services once, then mount this Service and its invariant companion. The Team Web Client is the only Human control surface.
 
-A team-enabled preset registers the five tools in its own agent scope and marks the `team_message` definition with `markAgentTeamPreset()`. Preset rows must resolve `ctx.agentTeam` when executing, not statically inject it: the Host mounts member presets while it restores Members during its own activation, so a row that declares `agentTeam` as a dependency cannot activate and fails every startup restore. Duplicate scoped tool names fail during unpublished setup and make only that Member unavailable. Duplicate Host service providers remain a composition error and should be removed rather than layered.
+A team-enabled preset registers the eight tools in its own agent scope and marks the `team_message` definition with `markAgentTeamPreset()`. Preset rows must resolve `ctx.agentTeam` when executing, not statically inject it: the Host mounts member presets while it restores Members during its own activation, so a row that declares `agentTeam` as a dependency cannot activate and fails every startup restore. Duplicate scoped tool names fail during unpublished setup and make only that Member unavailable. Duplicate Host service providers remain a composition error and should be removed rather than layered.
+
+Member context self-management rides the same lifecycle owner. The `context_rollover` and `context_checkpoint` tools only validate and conclude/anchor the turn; one `ContextManagementCoordinator` watches Member Session events, derives rollover and checkpoint intent from the durable successful `tool/call`+`tool/result` pairs, and executes the swap through the serialized lifecycle queue: wait for true idle, recheck the owned-jobs guard, dispose and archive the old Session (never delete), commit the idempotent `team/member-session-rolled-over` operation (Member actor, self-scoped, no handoff prose), activate a genuinely fresh Session — or a seeded Session for a checkpoint return, with the exact completed-turn prefix — then deliver the handoff and any carried non-Team input. Identity, model, private memory, skills, Claims, and Attention survive; process state is reconstructible from the durable log after a crash, including a handoff reconstructed from the ledger-recorded previous Session when a restart lands between the rollover commit and the new Session's activation. A second Host-owned coordinator (`pressure-policy.ts`) owns context pressure: budget thresholds from the live route's context window, one handoff-budget notice per generation, forced in-place compaction with fail-closed verification at the hard limit, and one bounded compact-and-retry for provider context-overflow; accepted-Task auto compaction is retired. The Human-side clear-context Remote remains a hidden migration escape hatch with no visible Client entry point.
 
 ## Model Experience
 

package/packages/agent-team/README.zh.md

@@ -16,13 +16,13 @@ Service 使用 `ctx.storageDomain`、`ctx.workspaceRegistry`、`ctx.agents`、`c
 
 `storage-domain` 在持久读取处校验每条 record，并拒绝被其他版本标记的 backend unit。Team 只在 `KvTable.put()` 完成后更新 projection。其 Fiber 持有 Domain handle；dispose 通过 Cordis 移除拒绝新的 Service 调用，排空已接受的 Domain write，并在名称可重新打开前关闭 backend unit。
 
-创建 Member 时，先提交稳定的 Member/session/Workspace/preset/private-memory 身份，再执行 unpublished Agent setup。Setup 挂载指定 preset，并在发布前检查带 marker 的 `team_message` 和全部五个 Team tools。失败只把该 Member 标为 unavailable。Suspend 等待所属 `AgentHandle` 完全停止；resume 和 Host remount 恢复同一个持久 session。
+创建 Member 时，先提交稳定的 Member/session/Workspace/preset/private-memory 身份，再执行 unpublished Agent setup。Setup 挂载指定 preset，并在发布前检查带 marker 的 `team_message` 和全部八个 Team tools。失败只把该 Member 标为 unavailable。Suspend 等待所属 `AgentHandle` 完全停止；resume 和 Host remount 恢复同一个持久 session。
 
 归档（archival）是介于 suspend 与 remove 之间的可逆第三态，Member 与 Channel 通用。`archiveMember` 提交 `team/member-archived`，dispose 活跃 session（私有记忆与 Session log 留在磁盘），把 Session 从分组面归档，并释放该 Member 的活跃 Claim（公开 `claims_released` Activity + Attention/marker 清理）。`archiveChannel` 提交 `team/channel-archived`，对该频道全部 Threads 上所有 owner 做同样的释放。两种归档都保留 Memberships——是隐藏而非离开。归档实体在所有 Team API 面上"默认不存在"：投影、ref 解析（其 Task ref 不再解析，消息正文渲染为纯文本）、按 ref 的读取（`readThread`/`threadHistory`/`threadObservations`/`listClaims` 以明确的 archived 错误拒绝）——而事实在 ledger 中完整保留，供重放与未来恢复；这条边界正是归档与 remove 的分界。从归档态 remove 仍可用（数据卫生路径）；本轮有意不提供恢复入口（对齐 dsh session 归档现状）。
 
 Member 可携带持久能力意图（`capabilities.tools.allow`、`capabilities.skills.allow`）。它随全部 lifecycle operation 原样流转，Host restart 后原样重放，commit 时不做已知名校验（Harness 升级不会破坏旧 ledger）；与已知名的偏差在 activation 时派生为不持久化的 `capabilityWarnings`。`tools.allow` 是有意的接口预留（当前无 UI 写入路径），供后续 Runtime Revision manifest 编排依赖。编辑语义与 `model` 一致（absent 即清除）：不管理 capabilities 的调用方必须回传已存储的值，否则其编辑会清掉该覆盖。
 
-Activation 把 `tools.allow` 作为 scoped restriction 应用在已组合的 preset 面上（mount → restrict → validate），五个 Team tools 在配置之上强制并集；未知名 drop + warning，不使 Member 失败。对 live Member 的 allow-list 编辑在 turn 边界同 Session 换装 restriction——idle 立即生效，与 running turn 竞争的编辑等待其结束，后续 lifecycle 操作在该等待之后排队。restriction 失败只隔离为该 Member 的 activation diagnostic。
+Activation 把 `tools.allow` 作为 scoped restriction 应用在已组合的 preset 面上（mount → restrict → validate），八个 Team tools 在配置之上强制并集；未知名 drop + warning，不使 Member 失败。对 live Member 的 allow-list 编辑在 turn 边界同 Session 换装 restriction——idle 立即生效，与 running turn 竞争的编辑等待其结束，后续 lifecycle 操作在该等待之后排队。restriction 失败只隔离为该 Member 的 activation diagnostic。
 
 Skills 是 Member 私有的：preset 不带共享 skill-filesystem row，Host 为每个 Member 注册一个 provider，只扫插件内置的只读 core skills（`packages/agent-team/core-skills/`——`member-skill-manager` meta skill，全部 skill 写作/安装/credentials 引导都在它里面）加该 Member 可写的私有 `skills/` 目录（排除默认 roots）。安装就是往自己目录写——目录形态 `skills/<name>/SKILL.md` + 可选 references/scripts，或平铺 `.md`——有意不提供上传 Remote。persona 只陈述私有空间物理事实，meta skill 的 description 负责"涉及 skill 管理工作时先读我"。`skills.allow` 通过同一 turn 边界换装的 live selection ref 过滤 catalog；自装后的发现由 filesystem watcher 驱动。
 
@@ -40,7 +40,9 @@ M1 支持单个 Host writer。Ledger 永久保留，不提供 snapshot 或 compa
 
 Bundle 使用 Host 已有的 singleton provider，不重复挂载 `agents`、默认模型选择、`tools`、`fs`、`sandboxPolicy`、Session store/persistence、Workspace registry 或 storage 的替代实现。Host services 只挂载一次，再挂载本 Service 及 invariant companion。`/team` 等 Human control 是独立 Consumer。
 
-Team-enabled preset 在自身 Agent scope 注册五个工具，并用 `markAgentTeamPreset()` 标记 `team_message` definition。Preset row 应在执行时读取 `ctx.agentTeam`，不能声明静态 inject：Host 在自身激活期间恢复 Member 时就会挂载成员 preset，声明依赖 `agentTeam` 的 row 无法激活，会让每次启动恢复失败。Scoped tool 重名会在 unpublished setup 阶段失败，只使对应 Member unavailable。Host service provider 重复则仍是 composition error，应删除重复行，不做叠加。
+Team-enabled preset 在自身 Agent scope 注册八个工具，并用 `markAgentTeamPreset()` 标记 `team_message` definition。Preset row 应在执行时读取 `ctx.agentTeam`，不能声明静态 inject：Host 在自身激活期间恢复 Member 时就会挂载成员 preset，声明依赖 `agentTeam` 的 row 无法激活，会让每次启动恢复失败。Scoped tool 重名会在 unpublished setup 阶段失败，只使对应 Member unavailable。Host service provider 重复则仍是 composition error，应删除重复行，不做叠加。
+
+Member 上下文自主管理复用同一 lifecycle owner。`context_rollover` 与 `context_checkpoint` 工具只做校验并结束/锚定 turn；单一 `ContextManagementCoordinator` 监听 Member Session 事件，从 durable 的成功 `tool/call`+`tool/result` 对派生 rollover 与 checkpoint 意图，并经串行 lifecycle queue 执行换窗：等真正 idle、复查 owned-jobs guard、dispose 并归档旧 Session（绝不删除）、提交幂等的 `team/member-session-rolled-over` operation（Member actor、仅限自身、不写 handoff 正文）、激活全新 Session——checkpoint 回返则以精确 completed-turn 前缀作 seed——再送达 handoff 与携带的非 Team 输入。身份、模型、私有记忆、skills、Claims 和 Attention 全部保留；进程内状态在崩溃后可从 durable log 重建，包括重启落在 rollover commit 与新 Session 激活之间时，从 ledger 记录的上一 Session 重建 handoff。第二个 Host 持有的 coordinator（`pressure-policy.ts`）拥有上下文压力：预算阈值从当前 route 的 context window 派生，handoff 预算每 generation 一条通知，硬上限强制原地 compaction 并 fail-closed 验证，provider context-overflow 获得一条有界 compact-and-retry；已接受 Task 的自动 compaction 已退役。Host 侧 clear-context Remote 保留为无可见 Client 入口的迁移逃生门。
 
 ## Model Experience
 

package/packages/agent-team/core-skills/member-skill-manager/SKILL.md

@@ -7,6 +7,8 @@ description: Create, install, revise, or retire this Member's private skills, in
 
 A skill preserves a reusable way of working. It is not a memory, a personal preference, or a record of one event.
 
+Skills are private to this Member — no other human or agent can read this directory. When a Team message or your session output needs the method, restate the relevant content there; citing a skill by name does not transfer it to anyone.
+
 ## Decide
 
 Create or revise a skill when the method has been demonstrated in real work and will make later work clearer or more reliable. Keep one-off work, changing facts, and personal continuity in this Member's notes and memory index instead.

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

@@ -24,15 +24,25 @@ export function attachmentPayloadPath(attachmentId, name) {
 export function newAttachmentId() {
     return randomUUID();
 }
-/** Strip path separators, control characters, and leading dots from one client-supplied name. */
+/** Strip path separators, control characters, Windows-illegal characters, reserved device names, and leading dots from one client-supplied name. */
 export function sanitizeFileName(raw) {
-    // oxlint-disable-next-line no-control-regex -- strip ASCII control characters from client filenames.
-    const cleaned = raw.replaceAll(/[\\/\u0000-\u001f\u007f]/g, '').replaceAll(/^\.+/g, '').trim().slice(0, 180);
+    // oxlint-disable no-control-regex -- strip ASCII control characters, separators, and Windows-reserved characters from client filenames.
+    const cleaned = raw
+        .replaceAll(/[\\/:*?"<>|\u0000-\u001f\u007f]/g, '')
+        .replaceAll(/^\.+/g, '')
+        .trim()
+        .slice(0, 180)
+        .replace(/[\s.]+$/g, '');
+    // oxlint-enable no-control-regex
     if (cleaned === '')
         return 'attachment';
     // The metadata sidecar owns 'meta.json' inside every entry directory; a
     // payload with that name would be clobbered by the sidecar and unreadable.
-    return /^meta\.json$/i.test(cleaned) ? `_${cleaned}` : cleaned;
+    if (/^meta\.json$/i.test(cleaned))
+        return `_${cleaned}`;
+    // Win32 CreateFile resolves these device names (with or without an
+    // extension) as hardware, so the payload write would fail or alias a device.
+    return /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i.test(cleaned) ? `_${cleaned}` : cleaned;
 }
 /** Extension-derived media types for agent-supplied files; unknown types stay generic. */
 const PATH_MEDIA_TYPES = {

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

@@ -0,0 +1,379 @@
+/**
+ * Context-management coordinator: the one deep module that turns a Member's
+ * successful `context_rollover` tool result into its next private context
+ * generation.
+ *
+ * Authority split (see docs/architecture.md):
+ * - the Team ledger owns the Member→Session binding and rollover audit;
+ * - the Session log projection owns intent, checkpoints, and delivery state;
+ * - this coordinator owns only process locks and is always reconstructible.
+ *
+ * The coordinator reacts exclusively after the successful `tool/result` is
+ * durably appended — never inside a tool body — so a render/finalize failure
+ * can never outrun result durability. The actual swap waits for the
+ * containing turn to end and the Agent to be idle, captures later input so no
+ * old-generation model request opens, and then reuses the Member lifecycle:
+ * commit rollover operation → dispose old Agent → archive old Session →
+ * create/activate the new generation → deliver the handoff first.
+ * @module @wowyuarm/dsh-agent-team/context-management
+ */
+import { SessionId as SessionIdBrand } from '@deepseek-ai/dsh-session';
+import { createHash } from 'node:crypto';
+import { createCheckpointContinuationMessage, createHandoffMessage } from "./context-source.js";
+import { CONTEXT_CHECKPOINT_TOOL_NAME, CONTEXT_ROLLOVER_TOOL_NAME, continuationDelivered, foldContextProjection, } from "./context-projection.js";
+/** Plugin identity of the Agent Team Host, for recognizing own notices. */
+const AGENT_TEAM_PLUGIN_ID = '@wowyuarm/dsh-agent-team';
+/** Stable summary of the one-shot rollover pressure notice (ticket 03 wires delivery). */
+export const CONTEXT_PRESSURE_NOTICE_SUMMARY = 'Context pressure: prepare a handoff';
+export class ContextManagementCoordinator {
+    options;
+    members = new Map();
+    capturedInput = new Map();
+    /** Per-member latch for the in-process scheduling→delivery window. */
+    scheduledContinuations = new Set();
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Whether one Member has a pending or in-flight rollover; tools use this to reject. */
+    isTransitioning(memberId) {
+        return this.members.has(memberId);
+    }
+    /**
+     * Root `session/event` observer for Member Sessions. The store's dispatch
+     * carrier is untagged, so the Host maps session ids to Members and calls
+     * this for every Member event. All reactions are gated on the projection
+     * state, which itself only records successful durable pairs.
+     */
+    onSessionEvent(memberId, agent, event) {
+        if (this.disposed)
+            return;
+        if (event.type === 'tool/result') {
+            this.onToolResult(memberId, agent, event);
+            return;
+        }
+        if (event.type === 'user/message') {
+            this.onUserMessage(memberId, agent, event);
+            return;
+        }
+        if (event.type === 'turn/end') {
+            this.onTurnEnd(memberId, agent);
+        }
+    }
+    /** Build the first handoff message of one generation; the lifecycle delivers it. */
+    handoffMessageFor(plan) {
+        return createHandoffMessage({
+            handoff: plan.handoff,
+            previousSessionId: plan.previousSessionId,
+            newSessionId: plan.newSessionId,
+            trigger: plan.trigger,
+            handoffEventSeq: plan.handoffEventSeq,
+            ...(plan.checkpointRef === undefined ? {} : { checkpointRef: plan.checkpointRef }),
+            ...(plan.relatedFiles.length === 0 ? {} : { relatedFiles: plan.relatedFiles }),
+        });
+    }
+    /**
+     * Whether one Agent's pending transition requires the admission gate: a
+     * pending rollover must stop old-generation turns from admitting queued
+     * input. The gate arms only for the old-generation Agent instance — the
+     * new generation activates mid-swap and must be free to consume the
+     * handoff and carried input immediately.
+     */
+    needsAdmissionGate(agent) {
+        const memberId = this.options.memberForAgent(agent)?.memberId;
+        if (memberId === undefined)
+            return false;
+        return this.members.get(memberId)?.agent === agent;
+    }
+    /**
+     * Capture the inbox messages queued for an old generation at its turn-stop
+     * boundary: non-Team input is preserved verbatim for delivery after the
+     * handoff; stale Team notices are dropped because the new generation
+     * rederives the Inbox from ledger facts. Removing them from the inbox lets
+     * the turn close cleanly instead of admitting another old-generation step.
+     */
+    captureQueuedInput(agent) {
+        const memberId = this.options.memberForAgent(agent)?.memberId;
+        if (memberId === undefined)
+            return [];
+        if (this.members.get(memberId)?.agent !== agent)
+            return [];
+        const removed = [...agent.inbox.nextStep, ...agent.inbox.nextTurn];
+        for (const message of removed)
+            agent.inbox.remove(message.id);
+        return this.captureInput(agent, removed);
+    }
+    /**
+     * Capture messages a racing pre-step already claimed from the inbox before
+     * rejecting that old-generation step. A rejected step's claimed message is
+     * otherwise neither discarded nor re-emitted, so the gate preserves it here.
+     */
+    captureClaimedInput(agent, messages) {
+        return this.captureInput(agent, messages);
+    }
+    captureInput(agent, messages) {
+        const memberId = this.options.memberForAgent(agent)?.memberId;
+        if (memberId === undefined)
+            return [];
+        if (this.members.get(memberId)?.agent !== agent)
+            return [];
+        const preserved = [];
+        for (const message of messages) {
+            if (this.isTeamNotice(message))
+                continue;
+            preserved.push(message);
+        }
+        if (preserved.length > 0)
+            this.capturedInput.set(memberId, [...(this.capturedInput.get(memberId) ?? []), ...preserved]);
+        return preserved;
+    }
+    /** Drain the captured input of one Member for delivery after the handoff. */
+    drainCapturedInput(memberId) {
+        const captured = this.capturedInput.get(memberId) ?? [];
+        this.capturedInput.delete(memberId);
+        return captured;
+    }
+    /** Whether one queued message is a Team-owned notice the rederived Inbox replaces. */
+    isTeamNotice(message) {
+        const source = message.source;
+        return source.kind === 'plugin' && source.plugin === AGENT_TEAM_PLUGIN_ID;
+    }
+    /** Drop one Member's bookkeeping; the Host calls this on dispose/removal. */
+    stopTracking(memberId) {
+        this.members.delete(memberId);
+        this.capturedInput.delete(memberId);
+    }
+    dispose() {
+        this.disposed = true;
+        this.members.clear();
+        this.capturedInput.clear();
+    }
+    onToolResult(memberId, agent, event) {
+        if (event.data.error !== undefined)
+            return;
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return;
+        const state = this.options.projectionForMember(memberId, member.sessionId);
+        if (state?.pending === null || state === undefined)
+            return;
+        const pending = state.pending;
+        // React only to the intent's own result landing durably, and only once.
+        if (pending.resultSeq !== event.seq)
+            return;
+        if (this.members.has(memberId))
+            return;
+        this.members.set(memberId, {
+            agent,
+            intent: {
+                toolCallId: pending.toolCallId,
+                resultSeq: pending.resultSeq,
+                turn: pending.turn,
+                handoff: pending.handoff,
+                ...(pending.checkpointRef === undefined ? {} : { checkpointRef: pending.checkpointRef }),
+                relatedFiles: pending.relatedFiles,
+            },
+            turnEnded: false,
+        });
+    }
+    onUserMessage(memberId, _agent, event) {
+        // Quiet-continuation delivery bookkeeping is projection-owned; the
+        // coordinator only repairs a crash gap after restart, which the Host
+        // performs through repairContinuations during activation.
+        void memberId;
+        void event;
+    }
+    onTurnEnd(memberId, agent) {
+        // Checkpoint continuations first: a turn that resolved checkpoints owes
+        // each of them exactly one quiet next-turn follow-up. The projection's
+        // continuations state deduplicates across restarts; this in-memory latch
+        // closes the same-process window between scheduling and the delivery
+        // event landing in the log.
+        this.scheduleCheckpointContinuations(memberId, agent);
+        const transition = this.members.get(memberId);
+        if (transition === undefined || transition.turnEnded)
+            return;
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined || transition.agent !== agent)
+            return;
+        transition.turnEnded = true;
+        // Wait for true idle (the turn-end event fires before the driver fully
+        // converges), then perform the swap off the session-event dispatch path.
+        void agent.whenIdle().then(() => {
+            if (this.disposed)
+                return;
+            const current = this.members.get(memberId);
+            if (current === undefined || current !== transition)
+                return;
+            if (this.options.agentForMember(memberId) !== agent)
+                return;
+            void this.performTransition(memberId, member, transition);
+        }, error => {
+            this.options.log(`context rollover idle wait failed: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
+            this.members.delete(memberId);
+        });
+    }
+    /**
+     * Quiet follow-ups for checkpoints resolved by the turn that just ended.
+     * A successful `context_checkpoint` result concludes its turn; the Host
+     * continues work in the next turn with one host-generated notice. The
+     * projection folds delivery (the continuation user/message event), so a
+     * restart repairs a missing follow-up through repairContinuations without
+     * duplicating a delivered one; this live path latches per checkpoint in
+     * memory for the scheduling window.
+     */
+    scheduleCheckpointContinuations(memberId, agent) {
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return;
+        const state = this.options.projectionForMember(memberId, member.sessionId);
+        if (state === undefined)
+            return;
+        for (const checkpoint of state.checkpoints) {
+            if (checkpoint.turnEndSeq === -1)
+                continue;
+            if (continuationDelivered(state, checkpoint.checkpointRef))
+                continue;
+            const latch = `${memberId}:${checkpoint.checkpointRef}`;
+            if (this.scheduledContinuations.has(latch))
+                continue;
+            this.scheduledContinuations.add(latch);
+            // The turn/end observer fires inside the session append publication
+            // (a synchronous followup would reenter the publishing append), and a
+            // next-turn message queued while the driver is still converging never
+            // latches a wake — the loop replays only maintenance/abort latches. So
+            // the continuation waits for true idle, then queues its own turn: the
+            // same discipline the rollover path uses.
+            void agent.whenIdle().then(() => {
+                if (this.disposed)
+                    return;
+                try {
+                    agent.followup(createCheckpointContinuationMessage(checkpoint.checkpointRef));
+                }
+                catch (error) {
+                    this.scheduledContinuations.delete(latch);
+                    this.options.log(`context continuation scheduling failed: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
+                }
+            }, () => {
+                this.scheduledContinuations.delete(latch);
+            });
+        }
+    }
+    async performTransition(memberId, member, transition) {
+        // Stable rollover identity derives from the previous Session and the
+        // successful tool call: a result seq is session-local and would collide
+        // across generations. Both inputs are unconstrained strings (provider
+        // call ids carry arbitrary lengths and characters; Session ids are
+        // caller-branded), so the pair is JSON-encoded — no delimiter can alias
+        // across the two fields — and hashed to a fixed-length url-safe hex
+        // digest instead of being embedded verbatim: the derived Session id and
+        // request id stay bounded and collision-resistant.
+        const stableKey = createHash('sha256').update(JSON.stringify([member.sessionId, transition.intent.toolCallId])).digest('hex');
+        const newSessionId = SessionIdBrand(`agent-team-rollover-${stableKey}`);
+        const plan = {
+            previousSessionId: member.sessionId,
+            newSessionId,
+            handoff: transition.intent.handoff,
+            handoffEventSeq: transition.intent.resultSeq,
+            trigger: 'model',
+            relatedFiles: transition.intent.relatedFiles,
+            ...(transition.intent.checkpointRef === undefined ? {} : { checkpointRef: transition.intent.checkpointRef }),
+            requestId: `agent-team:rollover:${stableKey}`,
+            carriedInput: this.drainCapturedInput(memberId),
+        };
+        const swap = this.options.executeTransition(memberId, plan);
+        transition.swapping = swap;
+        try {
+            await swap;
+            this.members.delete(memberId);
+        }
+        catch (error) {
+            this.options.log(`context rollover failed, leaving the previous generation recoverable: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
+            this.members.delete(memberId);
+        }
+    }
+    /**
+     * Crash-recovery hook the Host runs during Member activation: re-derive
+     * pending intent from the projection and finish a transition that a restart
+     * interrupted after the successful result was durable.
+     */
+    recoverPendingTransition(memberId, agent, sessionId) {
+        if (this.disposed || this.members.has(memberId))
+            return;
+        const state = this.options.projectionForMember(memberId, sessionId);
+        if (state?.pending === null || state === undefined)
+            return;
+        const pending = state.pending;
+        if (pending.turnEndSeq === -1) {
+            // The containing turn never ended durably; treat the intent as still
+            // waiting and observe the live events from here.
+            this.members.set(memberId, {
+                agent,
+                intent: {
+                    toolCallId: pending.toolCallId,
+                    resultSeq: pending.resultSeq,
+                    turn: pending.turn,
+                    handoff: pending.handoff,
+                    ...(pending.checkpointRef === undefined ? {} : { checkpointRef: pending.checkpointRef }),
+                    relatedFiles: pending.relatedFiles,
+                },
+                turnEnded: false,
+            });
+            return;
+        }
+        // The turn already ended before the crash; the Agent is idle at
+        // activation, so the swap can proceed directly.
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return;
+        const transition = {
+            agent,
+            intent: {
+                toolCallId: pending.toolCallId,
+                resultSeq: pending.resultSeq,
+                turn: pending.turn,
+                handoff: pending.handoff,
+                ...(pending.checkpointRef === undefined ? {} : { checkpointRef: pending.checkpointRef }),
+                relatedFiles: pending.relatedFiles,
+            },
+            turnEnded: true,
+        };
+        this.members.set(memberId, transition);
+        void this.performTransition(memberId, member, transition);
+    }
+    /**
+     * Crash-recovery for quiet continuations: schedule the follow-up for one
+     * resolved checkpoint exactly once when the result was durable but the
+     * delivery never landed. The projection's continuations state is the
+     * durable delivery record — a checkpoint whose delivery event exists in the
+     * log is never re-scheduled.
+     */
+    repairContinuations(agent, state) {
+        if (this.disposed)
+            return;
+        const memberId = this.options.memberForAgent(agent)?.memberId;
+        if (memberId === undefined)
+            return;
+        for (const checkpoint of state.checkpoints) {
+            if (checkpoint.turnEndSeq === -1)
+                continue;
+            if (continuationDelivered(state, checkpoint.checkpointRef))
+                continue;
+            const latch = `${memberId}:${checkpoint.checkpointRef}`;
+            if (this.scheduledContinuations.has(latch))
+                continue;
+            this.scheduledContinuations.add(latch);
+            try {
+                agent.followup(createCheckpointContinuationMessage(checkpoint.checkpointRef));
+            }
+            catch (error) {
+                this.scheduledContinuations.delete(latch);
+                this.options.log(`context continuation repair failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}
+/** Tool names this module owns; the preset validation requires all of them. */
+export const CONTEXT_TOOL_NAMES = Object.freeze([CONTEXT_CHECKPOINT_TOOL_NAME, CONTEXT_ROLLOVER_TOOL_NAME, 'context_timeline']);
+/** Re-exported for Host wiring: cold-fold helper for archived ancestors. */
+export { foldContextProjection };