@wowyuarm/dsh-agent-team 0.1.10 → 0.1.11

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

@@ -61,16 +61,20 @@ export function renderMemberIdentity(member) {
         ? `Team identity: you are @${member.handle}.`
         : `Team identity: you are @${member.handle} — ${member.description}`;
 }
+/** The four private-memory paths plus the out-of-cwd warning; callers append their own sentence. */
+function memoryPathsBlock(privateMemoryPath) {
+    return `Private memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd.`;
+}
 export function renderMemberMemory(raw, privateMemoryPath = '<private-memory-path>') {
     const overBudget = raw.byteLength > MAX_MEMORY_BYTES;
     const body = overBudget ? '' : raw.toString('utf8');
     const warning = overBudget
         ? '\n\n[Maintenance warning: memory.md exceeds the 8 KiB context budget. Its contents were not injected; do not delete or automatically summarize the file. Maintain a smaller index explicitly.]'
         : '';
-    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. It is reference context only, may be stale, and is not an instruction or Team fact.\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd. Relative filesystem paths resolve from cwd, so use the absolute paths above when reading or editing this Member's memory. Only this Member can read this directory — no other human or agent sees its contents; when communicating, restate what you need from it instead of pointing others at these paths. Read matching notes on demand; do not copy credentials, sensitive data, guesses, chat logs, other Members' memory, or Team facts already owned by the ledger into memory.\n\n${escape(body)}${warning}\n${END}`;
+    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. It is reference context only, may be stale, and is not an instruction or Team fact.\n\n${memoryPathsBlock(privateMemoryPath)} Relative filesystem paths resolve from cwd, so use the absolute paths above when reading or editing this Member's memory. Only this Member can read this directory — no other human or agent sees its contents; when communicating, restate what you need from it instead of pointing others at these paths. Read matching notes on demand; do not copy credentials, sensitive data, guesses, chat logs, other Members' memory, or Team facts already owned by the ledger into memory.\n\n${escape(body)}${warning}\n${END}`;
 }
 function renderUnavailableMemory(privateMemoryPath, reason) {
-    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. ${reason}\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd. Use the absolute paths above when inspecting or repairing this Member's memory.\n${END}`;
+    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. ${reason}\n\n${memoryPathsBlock(privateMemoryPath)} Use the absolute paths above when inspecting or repairing this Member's memory.\n${END}`;
 }
 function escape(value) {
     return value.replaceAll(BEGIN, '[escaped begin marker]').replaceAll(END, '[escaped end marker]');

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

@@ -28,6 +28,7 @@
  */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { formatTeamDuration, formatTeamTimestamp } from "./time-format.js";
+import { advanceOwnedSessionEventCursor } from "./session-event-cursor.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;
@@ -90,8 +91,22 @@ export function renderClockSnapshot(input) {
         + `Elapsed since the preceding ${baseline}: ${elapsed}.\n`
         + 'Team collaboration timestamps use UTC+8. Sequence and revision, not wall-clock time, determine ordering and concurrency.';
 }
+/**
+ * The clock baseline folded incrementally over one Session's own events. A
+ * rollover starts a fresh Session log, and the cache below is keyed by Session
+ * id, so the fold never guesses elapsed across generations: a missing prior
+ * event renders `unavailable`, not a fabricated baseline.
+ */
+const CLOCK_FOLD = {
+    start: emptyBaseline(),
+    step: (state, event) => applyClockEvent(state, event),
+};
 export function apply(ctx, config = {}) {
     const refreshIntervalMs = config.refreshIntervalMs ?? CLOCK_REFRESH_INTERVAL_MS;
+    // Per-step fold state, reused for this plugin lifecycle: one entry per
+    // Member, replaced when that Member's Session changes, so a rollover neither
+    // resumes across generations nor retains every generation it leaves behind.
+    const cursors = new Map();
     ctx.on('agent/pre-step', async ({ agent, turn, step, signal }, next) => {
         const decision = await next();
         if (decision.kind === 'reject' || signal.aborted)
@@ -102,13 +117,13 @@ export function apply(ctx, config = {}) {
         const host = ctx.get('agentTeam');
         if (host === undefined)
             return decision;
-        if (host.memberForAgent(agent) === undefined)
+        const member = host.memberForAgent(agent);
+        if (member === 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());
+        const owned = advanceOwnedSessionEventCursor(cursors.get(member.memberId), agent.session.id, CLOCK_FOLD, agent.session.ownEvents(), agent.session.inheritedEventCount);
+        cursors.set(member.memberId, owned);
+        const baseline = owned.cursor.value;
         // 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))

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

@@ -18,6 +18,26 @@ 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";
+import { advanceOwnedSessionEventCursor } from "./session-event-cursor.js";
+/**
+ * Whether this Session's own span already carries the pressure notice: either
+ * surfaced as a `user/message` or still queued in a durable
+ * `agent/inbox/spliced` insert. Expressed as a fold rather than a scan because
+ * the answer is monotone — once delivered it stays delivered for the
+ * generation — so the cursor only ever has to read events it has not seen.
+ */
+export const PRESSURE_NOTICE_FOLD = {
+    start: false,
+    step: (delivered, event) => {
+        if (delivered)
+            return true;
+        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;
+    },
+};
 /** One pressure-notice text; concise, structured, and inside the reserve. */
 export function contextPressureNoticeText(input) {
     const claims = input.activeClaims.length === 0 ? 'none' : input.activeClaims.join(', ');
@@ -41,6 +61,14 @@ export class PressurePolicyCoordinator {
      * Process-only by design: a restart re-earns one sequence per chain.
      */
     overflowRetries = new Map();
+    /**
+     * Whether the one-shot notice was already delivered, folded incrementally per
+     * Member. The scan below is a monotone "has this ever happened" fold over the
+     * Session's own events, so a cursor can replace re-scanning the whole log on
+     * every step; identity guarding falls back to a cold fold when the Member's
+     * Session changed under the entry.
+     */
+    noticeSeen = new Map();
     disposed = false;
     constructor(options) {
         this.options = options;
@@ -55,14 +83,10 @@ export class PressurePolicyCoordinator {
      * 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;
+    noticeDelivered(agent, memberId) {
+        const owned = advanceOwnedSessionEventCursor(this.noticeSeen.get(memberId), agent.session.id, PRESSURE_NOTICE_FOLD, agent.session.ownEvents(), agent.session.inheritedEventCount);
+        this.noticeSeen.set(memberId, owned);
+        return owned.cursor.value;
     }
     dispose() {
         this.disposed = true;
@@ -98,7 +122,7 @@ export class PressurePolicyCoordinator {
             const outcome = await this.enforceHardLimit(agent, member.memberId, member.sessionId, signal);
             return outcome ? { kind: 'continue' } : { kind: 'reject' };
         }
-        if (usageTokens >= handoffAt && !this.noticeDelivered(agent)) {
+        if (usageTokens >= handoffAt && !this.noticeDelivered(agent, member.memberId)) {
             const notice = createUserMessage({
                 content: [{ type: 'text', text: contextPressureNoticeText({
                             usageTokens, handoffAt, hardLimit,

package/packages/agent-team/lib/session-event-cursor.js

@@ -0,0 +1,116 @@
+/**
+ * Incremental Session-log fold with an identity guard.
+ *
+ * Several Host projections are pure left folds over one Member Session's own
+ * events: context intent, the clock baseline, and the one-shot pressure
+ * notice. Folding the whole log on every event makes each of them cost
+ * O(session length) per step, so a long Session gets steadily slower. This
+ * module keeps the fold value together with how far it has consumed the log,
+ * so a step folds only the tail that arrived since — the same idiom the
+ * Harness Session itself uses for its own derived folds.
+ *
+ * The module is deliberately Session-agnostic: it takes a plain event array
+ * plus the log offset that array starts at, so a caller (including a
+ * measurement harness) can drive it without constructing a Session.
+ *
+ * Correctness rests on the log being append-only, which it is: Session logs
+ * have no truncation API, `seq` is the log index, and `seq === log.length` is
+ * a documented contiguity contract. A Session adopts a different log only by
+ * being constructed from another seed, which replaces the whole slice rather
+ * than editing one position.
+ *
+ * The guard covers the observable ways that contract can break: a changed
+ * `logFrom`, a shorter log, a different event type at the anchor. Each
+ * re-folds from `logFrom`, so a fork, resume, or rollover degrades to the cost
+ * of a cold fold and never to a wrong picture.
+ *
+ * Named residual: the guard anchors on `(seq, type)`, so an event replaced in
+ * place by another of the SAME type at the SAME seq is not detected, and the
+ * cursor would keep its old value and fold only the tail. Reaching that state
+ * requires a caller to violate the append-only contract above — reading one
+ * Session's cursor against a log someone rewrote in place. A content-sensitive
+ * anchor would not close it either: only the anchor position is re-read, so a
+ * swap at any earlier folded position passes a boundary digest just as
+ * silently, while costing a payload digest on every advance. Closing it
+ * properly means fingerprinting every folded event, which is the full refold
+ * this module exists to avoid; if the contract ever changes, that is the fix.
+ * @module @wowyuarm/dsh-agent-team/session-event-cursor
+ */
+/**
+ * Open a cursor for a log slice that starts at `logFrom` (a Session's
+ * `inheritedEventCount` for its own events, or 0 for a full log). Nothing is
+ * consumed yet, so the first {@link advanceSessionEventCursor} folds the whole
+ * slice.
+ */
+export function initSessionEventCursor(fold, logFrom = 0) {
+    return { value: fold.start, foldedThrough: logFrom, logFrom, anchor: null };
+}
+/**
+ * Fold the log tail that arrived since the cursor stopped and return the
+ * advanced cursor; the same reference comes back when there is nothing new.
+ *
+ * `events` is the slice starting at `logFrom`, and `logEnd` is the EXCLUSIVE
+ * end offset of that slice in the owning log — the same coordinate space as
+ * `logFrom`, not `events.length`. An inherited Session's own events start at
+ * its `inheritedEventCount`, so for a 14-event log with 10 inherited events
+ * the slice is `events[0..4]` spanning `logFrom = 10` to `logEnd = 14`. This
+ * mirrors the Session's own `snapshotEvents(fromSeq, toSeqExclusive)`.
+ *
+ * Both offsets are passed explicitly rather than read from the cursor so the
+ * caller states the log it is folding, which is also what makes the fallback
+ * below decidable.
+ */
+export function advanceSessionEventCursor(cursor, events, logFrom, logEnd, fold) {
+    if (logEnd !== logFrom + events.length) {
+        // The slice and the log it claims to describe disagree, so the tail it is
+        // missing is indistinguishable from events that were never there. Refuse
+        // rather than fold a shape the caller did not state.
+        throw new RangeError(`session event cursor: ${events.length} events cannot span [${logFrom}, ${logEnd})`);
+    }
+    // Resume only from a position the log can still justify. Every other case
+    // re-folds from `logFrom`: one path handles truncation, a changed fork
+    // prefix, and a rebuilt log alike, so no caller has to classify them.
+    const resumable = cursor.logFrom === logFrom
+        && cursor.foldedThrough >= logFrom
+        && cursor.foldedThrough <= logEnd
+        && (cursor.foldedThrough === logFrom || anchorMatches(cursor, events));
+    const from = resumable ? cursor.foldedThrough : logFrom;
+    if (from === logEnd)
+        return cursor;
+    let value = resumable ? cursor.value : fold.start;
+    for (let index = from; index < logEnd; index += 1)
+        value = fold.step(value, events[index - logFrom]);
+    return { value, foldedThrough: logEnd, logFrom, anchor: anchorOf(events[logEnd - 1 - logFrom]) };
+}
+/**
+ * Whether the event the cursor stopped on still occupies that position with
+ * the type it had. The position is checked as well as the type because `seq`
+ * is a log index: an event that moved is a different event.
+ */
+function anchorMatches(cursor, events) {
+    const anchor = cursor.anchor;
+    if (anchor === null)
+        return false;
+    const seen = events[anchor.seq - cursor.logFrom];
+    return seen !== undefined && seen.seq === anchor.seq && seen.type === anchor.type;
+}
+/** The identity a cursor anchors on when it stops at the last consumed event. */
+function anchorOf(event) {
+    if (event === undefined)
+        return null;
+    return { seq: event.seq, type: event.type };
+}
+/**
+ * Advance one owner's fold and answer with the entry to store back, so every
+ * caller keeps the same one-entry-per-owner invariant.
+ *
+ * `events` is that Session's whole own-events slice starting at `logFrom` (its
+ * `inheritedEventCount`), so the slice's end is the log's end. The cursor is
+ * resumed only while `owned` still belongs to `sessionId`; every other case
+ * starts cold at `logFrom`, which is the same degradation the cursor's own
+ * guard performs for a rewritten log.
+ */
+export function advanceOwnedSessionEventCursor(owned, sessionId, fold, events, logFrom) {
+    const cursor = owned !== undefined && owned.sessionId === sessionId ? owned.cursor : initSessionEventCursor(fold, logFrom);
+    return { sessionId, cursor: advanceSessionEventCursor(cursor, events, logFrom, logFrom + events.length, fold) };
+}

package/packages/agent-team/lib/session-remediation.js

@@ -266,11 +266,6 @@ function physicalParentSession(rows) {
     const parent = rows[0]?.parentSession;
     return typeof parent === 'string' ? parent : undefined;
 }
-/**
- * The startup remediation pass. Never throws to its caller: a failed or
- * partial walk logs and leaves the completion cache unrecorded, so the next
- * start retries exactly the Members that need it.
- */
 export class SessionRemediation {
     ctx;
     persistence;
@@ -303,29 +298,43 @@ export class SessionRemediation {
         for (const member of members) {
             if (member.state !== 'enabled')
                 continue;
-            if (this.cacheStillValid(member))
+            const outcome = await this.remediateMember(member);
+            if (outcome.cacheHit)
                 continue;
             walked += 1;
-            let repairedCount = 0;
-            let untouchedCount = 0;
-            try {
-                const summary = await this.remediateLineage(member);
-                repairedCount = summary.repaired;
-                untouchedCount = summary.untouched;
-            }
-            catch (error) {
-                // Unexpected per-Member failure: log and leave the cache unrecorded.
-                this.ctx.logger.warn(`agent-team: legacy Session remediation for member '${member.handle}' did not complete: ${error instanceof Error ? error.message : String(error)}`);
-                continue;
-            }
-            repaired += repairedCount;
-            untouched += untouchedCount;
-            await this.recordCompletion(member);
+            repaired += outcome.repaired;
+            untouched += outcome.untouched;
         }
         if (walked > 0) {
             this.ctx.logger.info(`agent-team: legacy Session remediation walked ${walked} member lineage(s): ${repaired} artifact(s) repaired, ${untouched} left untouched`);
         }
     }
+    /**
+     * Remediate one Member's lineage; the bounded in-place heal a restart
+     * performs after an activation refused on a session. `completed` with zero
+     * repairs is the deterministic nothing-to-do answer (a finished walk found
+     * nothing provably this plugin's, or the cache already covered the Member);
+     * `completed: false` means the walk itself failed and a later attempt
+     * should retry. Never throws.
+     */
+    async remediateMember(member) {
+        if (member.state !== 'enabled' || this.cacheStillValid(member))
+            return { repaired: 0, untouched: 0, completed: true, cacheHit: true };
+        try {
+            const summary = await this.remediateLineage(member);
+            // A walk that failed a repair is not evidence of a clean lineage: it is
+            // left uncached so the next start retries exactly this Member, and it
+            // reports `completed: false` so no caller reads it as the deterministic
+            // nothing-to-do answer.
+            if (summary.failed === 0)
+                await this.recordCompletion(member);
+            return { repaired: summary.repaired, untouched: summary.untouched, completed: summary.failed === 0, cacheHit: false };
+        }
+        catch (error) {
+            this.ctx.logger.warn(`agent-team: legacy Session remediation for member '${member.handle}' did not complete: ${error instanceof Error ? error.message : String(error)}`);
+            return { repaired: 0, untouched: 0, completed: false, cacheHit: false };
+        }
+    }
     /** Whether the cached walk still covers this Member under the current format. */
     cacheStillValid(member) {
         const record = this.table?.get(member.memberId);
@@ -360,6 +369,7 @@ export class SessionRemediation {
     async remediateLineage(member) {
         let repaired = 0;
         let untouched = 0;
+        let failed = 0;
         const seen = new Set();
         let sessionId = member.sessionId;
         for (let depth = 0; sessionId !== undefined && !seen.has(sessionId) && depth < MAX_LINEAGE_DEPTH; depth += 1) {
@@ -369,9 +379,11 @@ export class SessionRemediation {
                 repaired += 1;
             else if (outcome.status === 'left-untouched')
                 untouched += 1;
+            else if (outcome.status === 'repair-failed')
+                failed += 1;
             sessionId = outcome.parentSession === undefined ? undefined : outcome.parentSession;
         }
-        return { repaired, untouched };
+        return { repaired, untouched, failed };
     }
     /** Remediate one lineage Session: verify readability, and repair when the refusal is this plugin's legacy source shape. */
     async remediateOne(sessionId, member) {
@@ -409,7 +421,7 @@ export class SessionRemediation {
         }
         catch (readError) {
             this.ctx.logger.warn(`agent-team: could not decode the stored artifact of Session '${sessionId}' (${basename(path)}): ${readError instanceof Error ? readError.message : String(readError)}`);
-            return { status: 'left-untouched', parentSession: undefined, reason: 'artifact undecodable' };
+            return { status: 'repair-failed', parentSession: undefined, reason: 'artifact undecodable' };
         }
         const parentSession = physicalParentSession(rows);
         if (!rows.some(row => containsLegacySource(row))) {
@@ -423,7 +435,7 @@ export class SessionRemediation {
         }
         catch (proofError) {
             this.ctx.logger.warn(`agent-team: Session '${sessionId}' of member '${member.handle}' still refuses after the legacy source rewrite (${proofError instanceof Error ? proofError.message : String(proofError)}); leaving it untouched`);
-            return { status: 'left-untouched', parentSession, reason: 'residual refusal after rewrite' };
+            return { status: 'repair-failed', parentSession, reason: 'residual refusal after rewrite' };
         }
         try {
             const published = await this.publishSibling(path, encodeCurrentArtifact(artifact));
@@ -434,7 +446,7 @@ export class SessionRemediation {
         }
         catch (publishError) {
             this.ctx.logger.warn(`agent-team: could not publish the remediated sibling for Session '${sessionId}' (${basename(path)}): ${publishError instanceof Error ? publishError.message : String(publishError)}`);
-            return { status: 'left-untouched', parentSession, reason: 'publish failed' };
+            return { status: 'repair-failed', parentSession, reason: 'publish failed' };
         }
         // Success is proven by the storage layer itself, not by our own writer.
         try {
@@ -448,7 +460,7 @@ export class SessionRemediation {
         }
         catch (verifyError) {
             this.ctx.logger.warn(`agent-team: the remediated sibling for Session '${sessionId}' was published but still refuses: ${verifyError instanceof Error ? verifyError.message : String(verifyError)}`);
-            return { status: 'left-untouched', parentSession, reason: 'sibling refused after publish' };
+            return { status: 'repair-failed', parentSession, reason: 'sibling refused after publish' };
         }
         this.ctx.logger.info(`agent-team: repaired legacy source kinds in Session '${sessionId}' of member '${member.handle}' by publishing a current-format sibling; the original artifact is untouched`);
         return { status: 'repaired', parentSession };

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

@@ -216,6 +216,47 @@ const claimOperation = (kind) => z.object({
         inbox: inboxDeltaSchema,
     }).strict(),
 }).strict();
+/**
+ * The five departure-fact collections a releasing operation persists. All four
+ * release kinds carry this snapshot under their own `kind` literal and their own
+ * identifying fields; the durable half that must stay identical lives here once,
+ * so a new release kind cannot silently drop or invent a field.
+ */
+const releaseSnapshotFields = {
+    claims: z.array(claimSchema),
+    activities: z.array(claimsReleasedActivitySchema),
+    tasks: z.array(taskSchema),
+    threads: z.array(threadSchema),
+    inbox: inboxDeltaSchema,
+};
+/** The receipt form every new read writes: the progress it made and the Inbox delta it consumed. */
+const threadReadReceiptDataSchema = z.object({
+    workspaceId: workspaceIdSchema,
+    memberId: memberIdSchema,
+    threadRef: threadRefSchema,
+    taskRef: taskRefSchema.optional(),
+    readThroughSequence: z.number().int().nonnegative(),
+    inbox: inboxDeltaSchema,
+}).strict().transform(omitUndefined);
+/**
+ * The pre-receipt Thread-read snapshot. Still accepted so a ledger written
+ * before the receipt form keeps opening; both shapes are strict, so a stored
+ * record parses as exactly one of them.
+ */
+const threadReadSnapshotDataSchema = z.object({
+    workspaceId: workspaceIdSchema,
+    memberId: memberIdSchema,
+    task: taskSchema.optional(),
+    thread: threadSchema,
+    claims: z.array(claimSchema),
+    anchor: messageSchema,
+    anchorMentions: z.array(memberIdSchema),
+    facts: z.array(readFactSchema),
+    readThroughSequence: z.number().int().nonnegative(),
+    remainingUnreadCount: z.number().int().nonnegative(),
+    attention: attentionSchema.optional(),
+    inbox: inboxDeltaSchema,
+}).strict().transform(omitUndefined);
 /** Closed Agent Team operation union before occurrence stamping. */
 const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
     z.object({
@@ -258,11 +299,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         kind: z.literal('team/member-archived'),
         data: z.object({
             member: memberSchema,
-            claims: z.array(claimSchema),
-            activities: z.array(claimsReleasedActivitySchema),
-            tasks: z.array(taskSchema),
-            threads: z.array(threadSchema),
-            inbox: inboxDeltaSchema,
+            ...releaseSnapshotFields,
         }).strict(),
     }).strict(),
     z.object({
@@ -324,11 +361,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
             workspaceId: workspaceIdSchema,
             channelRef: channelRefSchema,
             memberId: memberIdSchema,
-            claims: z.array(claimSchema),
-            activities: z.array(claimsReleasedActivitySchema),
-            tasks: z.array(taskSchema),
-            threads: z.array(threadSchema),
-            inbox: inboxDeltaSchema,
+            ...releaseSnapshotFields,
         }).strict(),
     }).strict(),
     z.object({
@@ -338,11 +371,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         data: z.object({
             workspaceId: workspaceIdSchema,
             channel: channelSchema,
-            claims: z.array(claimSchema),
-            activities: z.array(claimsReleasedActivitySchema),
-            tasks: z.array(taskSchema),
-            threads: z.array(threadSchema),
-            inbox: inboxDeltaSchema,
+            ...releaseSnapshotFields,
         }).strict(),
     }).strict(),
     z.object({
@@ -419,20 +448,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         ...operationBase,
         previousOperationId: operationIdSchema.nullable(),
         kind: z.literal('team/thread-read'),
-        data: z.object({
-            workspaceId: workspaceIdSchema,
-            memberId: memberIdSchema,
-            task: taskSchema.optional(),
-            thread: threadSchema,
-            claims: z.array(claimSchema),
-            anchor: messageSchema,
-            anchorMentions: z.array(memberIdSchema),
-            facts: z.array(readFactSchema),
-            readThroughSequence: z.number().int().nonnegative(),
-            remainingUnreadCount: z.number().int().nonnegative(),
-            attention: attentionSchema.optional(),
-            inbox: inboxDeltaSchema,
-        }).strict().transform(omitUndefined),
+        data: z.union([threadReadReceiptDataSchema, threadReadSnapshotDataSchema]),
     }).strict(),
     z.object({
         ...operationBase,
@@ -440,11 +456,7 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         kind: z.literal('team/member-removed'),
         data: z.object({
             member: memberSchema,
-            claims: z.array(claimSchema),
-            activities: z.array(claimsReleasedActivitySchema),
-            tasks: z.array(taskSchema),
-            threads: z.array(threadSchema),
-            inbox: inboxDeltaSchema,
+            ...releaseSnapshotFields,
         }).strict(),
     }).strict(),
     z.object({

package/packages/agent-team/lib/stored-session-reader.js

@@ -0,0 +1,138 @@
+/**
+ * The Team's single seam for reading stored Sessions.
+ *
+ * Every per-Session read the Host performs goes through here: one
+ * `open → read → close` cycle whose handle lifecycle is guaranteed closed,
+ * and whose failures are normalized into the five categories consumers choose
+ * policy by. Callers never touch a `SessionHandle`, an artifact path, a
+ * format generation, or Harness error message text.
+ *
+ * The reader owns reading and classification only — not Member lifecycle,
+ * Agent create/resume, UI, ledger, or remediation (which reads raw artifact
+ * bytes through its own repair path).
+ *
+ * Classification notes: the shipped JSONL backend throws its
+ * `corrupt session log` family as plain `Error`s, so corruption is detected by
+ * that stable message prefix (an upstream gap; if the text ever changes the
+ * failure degrades to `unknown`, which consumers treat conservatively —
+ * blocking rather than silently skipping). Typed refusals are also matched
+ * through `error.cause` chains because the Harness agent layer wraps
+ * persistence failures during resume.
+ * @module @wowyuarm/dsh-agent-team/stored-session-reader
+ */
+import { SessionFormatUnsupportedError, SessionPersistenceCorruptionError, SessionPersistenceNotFoundError, } from '@deepseek-ai/dsh-session-persistence';
+/**
+ * A call site's session-read failure, carrying the typed classification so
+ * activation can route the diagnostic without re-matching error text.
+ */
+export class StoredSessionReadError extends Error {
+    failure;
+    constructor(message, failure) {
+        super(message);
+        this.failure = failure;
+        this.name = 'StoredSessionReadError';
+    }
+}
+/** How deep to follow `error.cause` chains looking for a typed session failure. */
+const MAX_CAUSE_DEPTH = 4;
+/** The JSONL backend's stable corruption-message prefix (plain `Error`s, not typed). */
+const CORRUPT_SESSION_LOG_TEXT = /corrupt session log/;
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The deterministic session-shaped classification of one error value:
+ * typed Harness failures plus the corruption message family. A system error
+ * code is deliberately NOT matched here — outside the reader an fs error may
+ * come from unrelated work (private memory, attachment cache), so only the
+ * reader itself, where the failed operation is known to be a session read,
+ * may classify an fs error as `io`.
+ */
+function sessionClassOf(error) {
+    if (error instanceof SessionPersistenceNotFoundError)
+        return { kind: 'missing' };
+    if (error instanceof SessionFormatUnsupportedError) {
+        return { kind: 'refused', ...(error.location === undefined ? {} : { location: error.location }) };
+    }
+    if (error instanceof SessionPersistenceCorruptionError)
+        return { kind: 'corrupt' };
+    if (error instanceof Error && CORRUPT_SESSION_LOG_TEXT.test(error.message))
+        return { kind: 'corrupt' };
+    return undefined;
+}
+/** The first session-shaped classification in an error's cause chain, with the matched error for its message. */
+function sessionClassInChain(error) {
+    let current = error;
+    for (let depth = 0; current !== undefined && current !== null && depth <= MAX_CAUSE_DEPTH; depth += 1) {
+        const classified = sessionClassOf(current);
+        if (classified !== undefined)
+            return { classified, matched: current };
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return undefined;
+}
+/**
+ * Classify any failure as a stored-Session read failure. Total: unmatched
+ * errors become `unknown`, and a direct system error code becomes `io` —
+ * call this only where the failed operation is known to be a session read.
+ */
+export function classifyStoredSessionFailure(error, sessionId) {
+    const inChain = sessionClassInChain(error);
+    if (inChain !== undefined) {
+        return { kind: inChain.classified.kind, sessionId, detail: messageOf(inChain.matched), ...('location' in inChain.classified ? { location: inChain.classified.location } : {}) };
+    }
+    if (error !== null && typeof error === 'object' && typeof error.code === 'string') {
+        return { kind: 'io', sessionId, detail: messageOf(error) };
+    }
+    return { kind: 'unknown', sessionId, detail: messageOf(error) };
+}
+/**
+ * The session-shaped failure carried by an arbitrary error, when it carries
+ * one at all: deterministic markers (typed classes, the corruption message
+ * family) are matched through the cause chain; transient fs errors are not —
+ * outside the reader they are not provably session-related. Activation uses
+ * this to route diagnostics; `undefined` means the failure is not
+ * session-shaped.
+ */
+export function sessionFailureOf(error, sessionId) {
+    const inChain = sessionClassInChain(error);
+    if (inChain === undefined)
+        return undefined;
+    return { kind: inChain.classified.kind, sessionId, detail: messageOf(inChain.matched), ...('location' in inChain.classified ? { location: inChain.classified.location } : {}) };
+}
+/** Read stored Sessions through one seam: full validated reads with normalized failures. */
+export class StoredSessionReader {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Read one stored Session completely. The handle is closed on every path;
+     * any failure of open, read, or close is returned as its normalized
+     * category, never thrown.
+     */
+    async read(sessionId) {
+        try {
+            const handle = await this.ctx.sessionPersistence.open(sessionId, 'read');
+            try {
+                const { events } = await handle.read();
+                return { ok: true, inspection: { header: handle.header, inheritedEventCount: handle.inheritedEventCount, events } };
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            return { ok: false, failure: classifyStoredSessionFailure(error, sessionId) };
+        }
+    }
+    /**
+     * Whether one stored Session has durable persisted content, decided through
+     * `stat`: the backend reports a still-draining session through its pending
+     * header, so this is the existence probe activation relies on. Only the
+     * missing case returns `false`; unexpected errors propagate as before.
+     */
+    async exists(sessionId) {
+        return (await this.ctx.sessionPersistence.stat(sessionId)) !== undefined;
+    }
+}