@wowyuarm/dsh-agent-team 0.1.7 → 0.1.9

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

@@ -17,8 +17,12 @@ function emptyProjection() {
     return { byRequest: new Map(), byOperation: new Map(), ordered: [], channels: new Map(), members: new Map(), memberships: new Map(),
         claims: new Map(), messages: [], tasks: new Map(), threads: new Map(), attention: new Map(), directMarkers: new Map(), activityMarkers: new Map(),
         orderedFacts: [], factsByThread: new Map(), channelRefByThread: new Map(), mentionsByMessage: new Map(), messageCountByThread: new Map(),
-        attentionByThread: new Map() };
+        attentionByThread: new Map(), previousSessions: new Map(), rolloverSeeds: new Map() };
 }
+const EMPTY_PROGRESS_NUDGE_TARGETS = Object.freeze({
+    progress: Object.freeze([]),
+    claim: Object.freeze([]),
+});
 /** Exhaustiveness guard for the closed operation union: adding a kind must update every dispatch. */
 function assertUnhandledKind(operation) {
     throw new Error(`agent-team ledger does not handle operation kind '${operation.kind}'`);
@@ -243,9 +247,211 @@ export class AgentTeamLedger {
             return this.committed(this.memberResult(operation));
         });
     }
+    /**
+     * Move one enabled Member onto its next context generation as itself. The
+     * actor is the calling Member — the Host executes the transition but is
+     * never the business actor — and the durable data records only the
+     * verifiable envelope (previous/new Session anchors, the successful handoff
+     * tool-result seq, checkpoint seed lineage, trigger). The private handoff
+     * prose stays in the Member's own Session log. An exact retry resolves to
+     * the recorded outcome; the same requestId with different data collides.
+     */
+    rolloverMemberSession(request) {
+        return this.enqueue(async () => {
+            const existing = this.state.byRequest.get(request.requestId);
+            if (existing !== undefined) {
+                this.assertSameMemberSessionRolledOver(existing, request);
+                return this.resolved(this.memberResult(existing));
+            }
+            if (request.actor.kind !== 'member')
+                throw new Error('Member session rollover requires Member authority');
+            const prior = this.requireMember(request.memberId);
+            if (request.actor.memberId !== request.memberId)
+                throw new Error(`Agent Member '${prior.handle}' cannot roll over another Member's Session`);
+            if (prior.state !== 'enabled')
+                throw new Error(`Agent Member '${prior.handle}' is ${prior.state}; only enabled Members can roll over their Session`);
+            if (prior.sessionId === request.newSessionId)
+                throw new Error(`Agent Member '${prior.handle}' already runs Session '${request.newSessionId}'`);
+            if (prior.sessionId !== request.previousSessionId)
+                throw new Error(`Agent Member '${prior.handle}' is no longer bound to Session '${request.previousSessionId}'`);
+            if ((request.checkpointRef !== undefined) !== (request.sourceSessionId !== undefined))
+                throw new Error('rollover checkpoint fields must appear together');
+            if (request.sourceSessionId !== undefined && request.sourceThroughSeq === undefined)
+                throw new Error('rollover checkpoint seed requires a through sequence');
+            if (request.sourceThroughSeq !== undefined && request.sourceSessionId === undefined)
+                throw new Error('rollover through sequence requires a source Session');
+            const member = Object.freeze({ ...prior, sessionId: request.newSessionId });
+            const operation = Object.freeze({
+                ...this.operationBase(request, this.nextSequence()), kind: 'team/member-session-rolled-over',
+                data: Object.freeze({
+                    member,
+                    previousSessionId: request.previousSessionId,
+                    newSessionId: request.newSessionId,
+                    handoffEventSeq: request.handoffEventSeq,
+                    trigger: request.trigger,
+                    ...(request.sourceSessionId === undefined ? {} : { sourceSessionId: request.sourceSessionId }),
+                    ...(request.sourceThroughSeq === undefined ? {} : { sourceThroughSeq: request.sourceThroughSeq }),
+                    ...(request.checkpointRef === undefined ? {} : { checkpointRef: request.checkpointRef }),
+                }),
+            });
+            await this.table.put(operation.operationId, operation);
+            this.apply(operation);
+            return this.committed(this.memberResult(operation));
+        });
+    }
     getMember(memberId) {
         return this.state.members.get(memberId);
     }
+    /**
+     * The retired Session this Member most recently left through a renewal or
+     * rollover — the lineage parent a crash between the durable binding commit
+     * and the new Session's activation must reconstruct a handoff from. Read
+     * from the audit projection; the Member record itself only names the
+     * current Session.
+     */
+    previousSessionForMember(memberId) {
+        return this.state.previousSessions.get(memberId);
+    }
+    /**
+     * The latest session transition this Member committed: the retired Session
+     * and the target it moved onto, through either a renewal or a rollover.
+     * Crash recovery binds carried-input redelivery to the recorded target —
+     * the CURRENT Session being that target proves the old generation's
+     * unconsumed input still belongs here, regardless of whether the handoff
+     * itself already landed.
+     */
+    lastTransitionForMember(memberId) {
+        const previousSessionId = this.state.previousSessions.get(memberId);
+        const member = this.state.members.get(memberId);
+        if (previousSessionId === undefined || member === undefined)
+            return undefined;
+        return { previousSessionId, targetSessionId: member.sessionId };
+    }
+    /**
+     * The Thread a Task overlay lives on, or undefined for an unknown or
+     * archived-Channel Task. Read-only input for attributing claim-mutation
+     * boundaries to the Thread whose context they entered.
+     */
+    threadForTask(taskRef) {
+        const task = this.state.tasks.get(taskRef);
+        if (task === undefined)
+            return undefined;
+        return this.state.channels.get(task.channelRef)?.state === 'archived' ? undefined : task.threadRef;
+    }
+    /**
+     * The seed envelope of this Member's most recent rollover, when that
+     * rollover was a checkpoint return: the recorded source Session, the
+     * exclusive end of its seeded prefix, and the checkpoint ref. A fresh
+     * rollover clears the envelope. Crash recovery reads this to rebuild the
+     * child generation from the recorded seed instead of an empty context.
+     */
+    rolloverSeedForMember(memberId, targetSessionId) {
+        const seed = this.state.rolloverSeeds.get(memberId);
+        // Bind the envelope to its recorded target: a later renewal or fresh
+        // rollover that reused or replaced the binding must never consume an
+        // older generation's seed.
+        return seed?.targetSessionId === targetSessionId ? seed : undefined;
+    }
+    /**
+     * Count one Member's active Claims on open Tasks in active Channels — the
+     * read-only input to the checkpoint single-Thread coverage guard: with
+     * more than one, a rewind cannot be proven to stay inside one Thread.
+     */
+    activeClaimCountForMember(memberId) {
+        return this.activeClaimsForMember(memberId).length;
+    }
+    /**
+     * One Member's active Claims on open Tasks in active Channels, oldest
+     * first — the read-only input for the pressure notice's Claim labels.
+     */
+    activeClaimsForMember(memberId) {
+        const active = [];
+        for (const claim of this.state.claims.values()) {
+            if (claim.owner !== memberId || claim.state !== 'active')
+                continue;
+            const task = this.state.tasks.get(claim.taskRef);
+            if (task === undefined || task.resolution !== 'open')
+                continue;
+            if (this.state.channels.get(task.channelRef)?.state === 'archived')
+                continue;
+            active.push(claim);
+        }
+        return active.sort((a, b) => a.claimRef.localeCompare(b.claimRef));
+    }
+    /**
+     * Current progress-nudge candidacy for one Member: threads whose Thread
+     * progress reminder applies (active Claim, or following a taskless Thread)
+     * and tasks where the Claim reminder applies (following a still-`todo` Task
+     * with no Claim history for this Member). A deep read-only projection — the
+     * caller never re-derives attention, claim, task-resolution, or channel
+     * archive state. Archived channels and resolved tasks produce no candidacy;
+     * results are ordered by Thread revision descending, then threadRef.
+     */
+    progressNudgeTargets(memberId) {
+        const member = this.state.members.get(memberId);
+        if (member === undefined || member.state !== 'enabled')
+            return EMPTY_PROGRESS_NUDGE_TARGETS;
+        const progress = [];
+        const claim = [];
+        const seenProgress = new Set();
+        for (const claimRecord of this.state.claims.values()) {
+            if (claimRecord.owner !== memberId || claimRecord.state !== 'active')
+                continue;
+            const task = this.state.tasks.get(claimRecord.taskRef);
+            const thread = this.state.threads.get(claimRecord.threadRef);
+            if (task === undefined || thread === undefined || task.resolution !== 'open')
+                continue;
+            if (this.state.channels.get(task.channelRef)?.state === 'archived')
+                continue;
+            if (seenProgress.has(claimRecord.threadRef))
+                continue;
+            seenProgress.add(claimRecord.threadRef);
+            progress.push({ reason: 'active-claim', threadRef: claimRecord.threadRef, taskRef: claimRecord.taskRef });
+        }
+        for (const [threadRef, followers] of this.state.attentionByThread) {
+            if (!followers.has(memberId))
+                continue;
+            const thread = this.state.threads.get(threadRef);
+            if (thread === undefined)
+                continue;
+            const channelRef = this.state.channelRefByThread.get(threadRef);
+            if (channelRef === undefined || this.state.channels.get(channelRef)?.state === 'archived')
+                continue;
+            if (thread.taskRef === undefined) {
+                if (!seenProgress.has(threadRef)) {
+                    seenProgress.add(threadRef);
+                    progress.push({ reason: 'taskless-follower', threadRef });
+                }
+                continue;
+            }
+            // Claim reminder: only still-`todo` tasks with zero lifetime claims by
+            // this Member; once claimed (any state) the Member moved into the
+            // progress-reminder regime.
+            if (this.hasLifetimeClaimOnTask(memberId, thread.taskRef))
+                continue;
+            const task = this.state.tasks.get(thread.taskRef);
+            if (task === undefined || task.resolution !== 'open' || this.deriveTaskStatus(task.taskRef, this.state.claims.values()) !== 'todo')
+                continue;
+            claim.push({ threadRef, taskRef: thread.taskRef });
+        }
+        const byThreadRevision = (left, right) => {
+            const leftRevision = this.state.threads.get(left.threadRef)?.revision ?? 0;
+            const rightRevision = this.state.threads.get(right.threadRef)?.revision ?? 0;
+            return rightRevision - leftRevision || (left.threadRef < right.threadRef ? -1 : left.threadRef > right.threadRef ? 1 : 0);
+        };
+        return Object.freeze({
+            progress: Object.freeze(progress.sort(byThreadRevision)),
+            claim: Object.freeze(claim.sort(byThreadRevision)),
+        });
+    }
+    /** Whether this Member has ever held a Claim on the Task, in any state. */
+    hasLifetimeClaimOnTask(memberId, taskRef) {
+        for (const claim of this.state.claims.values()) {
+            if (claim.owner === memberId && claim.taskRef === taskRef)
+                return true;
+        }
+        return false;
+    }
     listMembers() {
         return Object.freeze([...this.state.members.values()]);
     }
@@ -518,7 +724,7 @@ export class AgentTeamLedger {
             else {
                 if (request.direction !== undefined)
                     throw new Error(`${request.action} action does not accept direction`);
-                const previous = request.claimRef === undefined ? undefined : this.state.claims.get(request.claimRef);
+                const previous = request.claimRef === undefined ? undefined : this.state.claims.get(this.requireRefKey(this.state.claims, request.claimRef, 'claim', 'Claim'));
                 if (previous === undefined) {
                     throw new Error(`unknown Claim '${request.claimRef ?? ''}'${request.claimRef === undefined ? '' : this.unknownRefHint(request.claimRef, 'claim', 'Claim')}`);
                 }
@@ -588,6 +794,15 @@ export class AgentTeamLedger {
                     : claim);
             const releasedClaims = claims.filter(claim => claim.state === 'released' && this.state.claims.get(claim.claimRef)?.state === 'active');
             const completedClaims = claims.filter(claim => claim.state === 'done' && this.state.claims.get(claim.claimRef)?.state === 'active');
+            // Every done Claim at commit time — pre-finished and atomically
+            // completed alike — is the acceptance discriminator: the one list
+            // accept markers deliver from, so a normal accept no longer stays
+            // silent about the Members whose work it accepted. Sorted lexically
+            // so replay validation compares stably regardless of claim-ref
+            // generation order.
+            const acceptedClaims = request.action === 'accept'
+                ? claims.filter(claim => claim.state === 'done').sort((left, right) => left.claimRef.localeCompare(right.claimRef))
+                : [];
             const resolution = request.action === 'reopen' ? 'open' : request.action === 'accept' ? 'accepted' : 'closed';
             const status = resolution === 'accepted' ? 'done' : resolution === 'closed' ? 'closed'
                 : this.deriveTaskStatus(task.taskRef, claims);
@@ -596,12 +811,13 @@ export class AgentTeamLedger {
             const activity = Object.freeze({ activityRef: this.ref('activity'), kind: request.action,
                 taskRef: task.taskRef, threadRef: task.threadRef, actor: request.actor.memberId, sequence,
                 ...(releasedClaims.length === 0 ? {} : { releasedClaimRefs: Object.freeze(releasedClaims.map(claim => claim.claimRef)) }),
-                ...(completedClaims.length === 0 ? {} : { completedClaimRefs: Object.freeze(completedClaims.map(claim => claim.claimRef)) }) });
+                ...(completedClaims.length === 0 ? {} : { completedClaimRefs: Object.freeze(completedClaims.map(claim => claim.claimRef)) }),
+                ...(request.action === 'accept' ? { acceptedClaimRefs: Object.freeze(acceptedClaims.map(claim => claim.claimRef)) } : {}) });
             const inbox = request.action === 'close'
                 ? this.closeThreadInbox(activity, thread.threadRef)
                 : request.action === 'reopen'
                     ? this.reopenThreadInbox(activity, thread.threadRef)
-                    : this.acceptThreadInbox(activity, thread.threadRef, completedClaims.map(claim => claim.owner));
+                    : this.acceptThreadInbox(activity, thread.threadRef, acceptedClaims.map(claim => claim.owner));
             const operation = Object.freeze({
                 ...this.operationBase(request, sequence), kind: 'team/task-changed',
                 data: Object.freeze({ workspaceId: request.workspaceId, baseRevision: request.baseRevision,
@@ -897,7 +1113,7 @@ export class AgentTeamLedger {
                     memberId: next.memberId, action: 'follow' }));
             }
         }
-        return Object.freeze({ items: Object.freeze(observations.slice(-limit)) });
+        return Object.freeze({ items: Object.freeze(observations.slice(-limit)), followers: Object.freeze([...current.keys()]) });
     }
     /** Every operation carrying an inbox delta drives the Inbox projection; the payload shape decides, not a per-kind list. */
     attentionDelta(operation) {
@@ -946,7 +1162,8 @@ export class AgentTeamLedger {
         const numbers = this.taskNumbers(workspaceId);
         const resolved = [];
         for (const taskRef of taskRefs) {
-            const task = this.state.tasks.get(taskRef);
+            const key = this.uniqueRefKey(this.state.tasks, taskRef, 'task');
+            const task = key === undefined ? undefined : this.state.tasks.get(key);
             const channel = task === undefined ? undefined : this.state.channels.get(task.channelRef);
             // Archived Channels do not exist on Team API surfaces: their Tasks stop
             // resolving, so live message bodies render the refs as plain
@@ -1076,6 +1293,7 @@ export class AgentTeamLedger {
             case 'team/member-session-restarted':
             case 'team/member-context-cleared':
             case 'team/member-session-renewed':
+            case 'team/member-session-rolled-over':
             case 'team/member-updated':
             case 'team/member-removed':
                 return [{ kind: 'workspace', workspaceId: operation.data.member.workspaceId }];
@@ -1196,6 +1414,7 @@ export class AgentTeamLedger {
             case 'team/member-session-restarted':
             case 'team/member-context-cleared':
             case 'team/member-session-renewed':
+            case 'team/member-session-rolled-over':
             case 'team/member-updated':
             case 'team/channel-member-added':
             case 'team/thread-read':
@@ -1328,6 +1547,29 @@ export class AgentTeamLedger {
                 throw new Error('invalid Member session renewal');
             return;
         }
+        if (operation.kind === 'team/member-session-rolled-over') {
+            // The rollover's business actor is the calling Member itself; the Host
+            // only executes the recorded transition. Authorization is self-scoped:
+            // the actor must be the enabled target Member on its currently bound
+            // Session, and the recorded transition moves exactly the sessionId.
+            const actorMember = assertMember();
+            const prior = projection.members.get(operation.data.member.memberId);
+            if (actorMember.memberId !== operation.data.member.memberId)
+                throw new Error('rolled-over Member must match its actor');
+            if (prior === undefined || prior.state !== 'enabled'
+                || prior.sessionId !== operation.data.previousSessionId
+                || operation.data.member.sessionId !== operation.data.newSessionId
+                || operation.data.member.sessionId === operation.data.previousSessionId
+                || !this.sameMemberFacts(prior, operation.data.member))
+                throw new Error('invalid Member session rollover');
+            if (operation.data.sourceSessionId !== undefined && operation.data.sourceThroughSeq === undefined)
+                throw new Error('rolled-over checkpoint seed requires a through sequence');
+            if (operation.data.sourceThroughSeq !== undefined && operation.data.sourceSessionId === undefined)
+                throw new Error('rolled-over through sequence requires a source Session');
+            if ((operation.data.checkpointRef !== undefined) !== (operation.data.sourceSessionId !== undefined))
+                throw new Error('rolled-over checkpoint fields must appear together');
+            return;
+        }
         if (operation.kind === 'team/channel-updated') {
             assertHuman();
             const prior = projection.channels.get(operation.data.channel.channelRef);
@@ -1561,13 +1803,24 @@ export class AgentTeamLedger {
             const expectedCompletedClaimRefs = operation.data.claims
                 .filter(claim => projection.claims.get(claim.claimRef)?.state === 'active' && claim.state === 'done')
                 .map(claim => claim.claimRef);
+            // New-shape accepts carry the acceptance discriminator: every done
+            // Claim at commit time, sorted. Legacy accepts predate it; the
+            // recorded wake semantics for them stay completed-only (the old rule)
+            // so every existing ledger replays unchanged.
+            const expectedAcceptedClaimRefs = operation.data.claims
+                .filter(claim => claim.state === 'done')
+                .map(claim => claim.claimRef)
+                .sort((left, right) => left.localeCompare(right));
             if (task.resolution !== expectedResolution || task.status !== expectedStatus
                 || (activity.kind !== 'close' && activity.releasedClaimRefs !== undefined)
                 || (activity.kind !== 'accept' && activity.completedClaimRefs !== undefined)
+                || (activity.kind !== 'accept' && activity.acceptedClaimRefs !== undefined)
                 || (activity.kind === 'close' && !this.sameList(activity.releasedClaimRefs ?? [], operation.data.claims
                     .filter(claim => projection.claims.get(claim.claimRef)?.state === 'active' && claim.state === 'released')
                     .map(claim => claim.claimRef)))
-                || !this.sameList(activity.completedClaimRefs ?? [], expectedCompletedClaimRefs)) {
+                || !this.sameList(activity.completedClaimRefs ?? [], expectedCompletedClaimRefs)
+                || (activity.kind === 'accept' && activity.acceptedClaimRefs !== undefined
+                    && !this.sameList(activity.acceptedClaimRefs, expectedAcceptedClaimRefs))) {
                 throw new Error('invalid Task state transition');
             }
             const priorClaims = [...projection.claims.values()].filter(claim => claim.taskRef === task.taskRef).sort((left, right) => left.claimRef.localeCompare(right.claimRef));
@@ -1591,7 +1844,10 @@ export class AgentTeamLedger {
                 ? this.closeThreadInboxFrom(projection, activity, thread.threadRef)
                 : activity.kind === 'reopen'
                     ? this.reopenThreadInboxFrom(projection, activity, thread.threadRef)
-                    : this.acceptThreadInboxFrom(projection, activity, thread.threadRef, expectedCompletedClaimRefs);
+                    // Presence of the discriminator picks the wake rule: new accepts
+                    // wake every done owner; legacy records keep the completed-only
+                    // delta exactly as recorded.
+                    : this.acceptThreadInboxFrom(projection, activity, thread.threadRef, activity.acceptedClaimRefs !== undefined ? activity.acceptedClaimRefs : expectedCompletedClaimRefs);
             if (!isDeepStrictEqual(operation.data.inbox, expectedInbox))
                 throw new Error('invalid Task inbox projection');
             this.validateInboxDelta(operation.data.inbox, projection, refs, [], [], [activity]);
@@ -1859,6 +2115,25 @@ export class AgentTeamLedger {
         }
         if (operation.kind === 'team/member-session-renewed') {
             target.members.set(operation.data.member.memberId, operation.data.member);
+            target.previousSessions.set(operation.data.member.memberId, operation.data.previousSessionId);
+            // A Human-side renewal is always a fresh start: a stale checkpoint
+            // seed from an earlier rollover must never re-seed it.
+            target.rolloverSeeds.delete(operation.data.member.memberId);
+            return;
+        }
+        if (operation.kind === 'team/member-session-rolled-over') {
+            target.members.set(operation.data.member.memberId, operation.data.member);
+            target.previousSessions.set(operation.data.member.memberId, operation.data.previousSessionId);
+            // A checkpoint return records its seed envelope: a crash between this
+            // commit and the new Session's activation rebuilds the child from the
+            // recorded source instead of an empty context.
+            const { sourceSessionId, sourceThroughSeq, checkpointRef } = operation.data;
+            if (sourceSessionId !== undefined && sourceThroughSeq !== undefined && checkpointRef !== undefined) {
+                target.rolloverSeeds.set(operation.data.member.memberId, { targetSessionId: operation.data.newSessionId, sourceSessionId, sourceThroughSeq, checkpointRef });
+            }
+            else {
+                target.rolloverSeeds.delete(operation.data.member.memberId);
+            }
             return;
         }
         if (operation.kind === 'team/channel-updated') {
@@ -2137,22 +2412,24 @@ export class AgentTeamLedger {
         return this.inboxDelta([], removed, [], [...projection.directMarkers.values()].filter(marker => marker.threadRef === threadRef), activityMarkers, [...projection.activityMarkers.values()].filter(marker => marker.threadRef === threadRef));
     }
     /**
-     * Early acceptance completes open Claims inside the accept operation; their
-     * owners learn about it through activity markers regardless of whether they
-     * still follow the Thread. Plain accepts (no completed Claims) stay silent.
+     * Acceptance notifies every done Claim owner — pre-finished (the normal
+     * flow) and atomically completed (early acceptance) alike — through
+     * activity markers regardless of whether they still follow the Thread.
+     * The actor never notifies itself. Legacy records without the acceptance
+     * discriminator keep the old completed-only wake semantics on replay.
      */
-    acceptThreadInbox(activity, threadRef, completedOwners) {
-        if (completedOwners.length === 0)
+    acceptThreadInbox(activity, threadRef, acceptedOwners) {
+        if (acceptedOwners.length === 0)
             return this.inboxDelta();
-        const recipients = [...new Set(completedOwners)].filter(memberId => memberId !== activity.actor);
+        const recipients = [...new Set(acceptedOwners)].filter(memberId => memberId !== activity.actor);
         const markers = recipients.map(memberId => Object.freeze({ memberId, threadRef,
             activityRef: activity.activityRef, sequence: activity.sequence }));
         return this.inboxDelta([], [], [], [], markers);
     }
-    acceptThreadInboxFrom(projection, activity, threadRef, completedClaimRefs) {
-        if (completedClaimRefs.length === 0)
+    acceptThreadInboxFrom(projection, activity, threadRef, claimRefs) {
+        if (claimRefs.length === 0)
             return this.inboxDelta();
-        const owners = completedClaimRefs.map(claimRef => projection.claims.get(claimRef)?.owner).filter(owner => owner !== undefined);
+        const owners = claimRefs.map(claimRef => projection.claims.get(claimRef)?.owner).filter(owner => owner !== undefined);
         return this.acceptThreadInbox(activity, threadRef, owners);
     }
     reopenThreadInbox(activity, threadRef) {
@@ -2433,13 +2710,55 @@ export class AgentTeamLedger {
             throw new Error('agent-team operation lacks enabled Member authority');
         return member;
     }
-    /** Agents sometimes strip the branded prefix when echoing refs; point at the fix instead of a bare lookup failure. */
+    /** Shortest accepted UUID abbreviation after the branded prefix. */
+    static MIN_REF_UUID_PREFIX = 6;
+    isRefAbbreviationTail(tail) {
+        return tail.length >= AgentTeamLedger.MIN_REF_UUID_PREFIX && /^[0-9a-f]+$/i.test(tail);
+    }
+    /**
+     * Full map key for one branded ref, tolerating a unique UUID abbreviation.
+     * Exact refs win; an abbreviated ref (prefix plus at least 6 hex chars,
+     * hyphens ignored) resolves only when it matches exactly one key. Returns
+     * undefined for unknown or ambiguous refs so lenient callers can degrade
+     * without throwing.
+     */
+    uniqueRefKey(map, ref, prefix) {
+        if (map.has(ref))
+            return ref;
+        const tail = ref.startsWith(`${prefix}:`) ? ref.slice(prefix.length + 1).replaceAll('-', '') : undefined;
+        if (tail === undefined || !this.isRefAbbreviationTail(tail))
+            return undefined;
+        const lower = tail.toLowerCase();
+        const candidates = [...map.keys()].filter(key => key.slice(prefix.length + 1).replaceAll('-', '').startsWith(lower));
+        return candidates.length === 1 ? candidates[0] : undefined;
+    }
+    /** uniqueRefKey with the established unknown/ambiguous error contract and hints. */
+    requireRefKey(map, ref, prefix, label) {
+        const key = this.uniqueRefKey(map, ref, prefix);
+        if (key !== undefined)
+            return key;
+        const tail = ref.startsWith(`${prefix}:`) ? ref.slice(prefix.length + 1).replaceAll('-', '') : undefined;
+        if (tail !== undefined && this.isRefAbbreviationTail(tail)) {
+            const lower = tail.toLowerCase();
+            const candidates = [...map.keys()].filter(candidate => candidate.slice(prefix.length + 1).replaceAll('-', '').startsWith(lower));
+            if (candidates.length > 1) {
+                throw new Error(`ambiguous ${label} ref '${ref}' matches ${candidates.map(candidate => `'${candidate}'`).join(', ')}; reuse a longer prefix or the full ref exactly as returned by Team tools`);
+            }
+        }
+        throw new Error(`unknown ${label} ref '${ref}'${this.unknownRefHint(ref, prefix, label)}`);
+    }
+    /** Agents strip the branded prefix or abbreviate UUIDs when echoing refs; point at the fix instead of a bare lookup failure. */
     unknownRefHint(ref, prefix, label) {
-        return ref.startsWith(`${prefix}:`) ? ''
-            : ` A ${label} ref must start with '${prefix}:'; reuse the full ref exactly as returned by Team tools ('${prefix}:${ref}').`;
+        if (!ref.startsWith(`${prefix}:`)) {
+            return ` A ${label} ref must start with '${prefix}:'; reuse the full ref exactly as returned by Team tools ('${prefix}:${ref}').`;
+        }
+        const tail = ref.slice(prefix.length + 1).replaceAll('-', '');
+        return this.isRefAbbreviationTail(tail)
+            ? ` No ${label} matches this UUID prefix; reuse the full ref exactly as returned by Team tools.`
+            : ` A ${label} ref needs at least 6 hex characters after '${prefix}:', or the full ref exactly as returned by Team tools.`;
     }
     requireTask(workspaceId, taskRef) {
-        const task = this.state.tasks.get(taskRef);
+        const task = this.state.tasks.get(this.requireRefKey(this.state.tasks, taskRef, 'task', 'Task'));
         if (task === undefined)
             throw new Error(`unknown Task ref '${taskRef}'${this.unknownRefHint(taskRef, 'task', 'Task')}`);
         if (this.state.channels.get(task.channelRef)?.workspaceId !== workspaceId)
@@ -2447,7 +2766,7 @@ export class AgentTeamLedger {
         return task;
     }
     requireThread(threadRef) {
-        const thread = this.state.threads.get(threadRef);
+        const thread = this.state.threads.get(this.requireRefKey(this.state.threads, threadRef, 'thread', 'Thread'));
         if (thread === undefined)
             throw new Error(`unknown Thread ref '${threadRef}'${this.unknownRefHint(threadRef, 'thread', 'Thread')}`);
         return thread;
@@ -2470,13 +2789,15 @@ export class AgentTeamLedger {
         let thread;
         let task;
         if (request.threadRef !== undefined) {
-            thread = projection.threads.get(request.threadRef);
+            const threadKey = this.requireRefKey(projection.threads, request.threadRef, 'thread', 'Thread');
+            thread = projection.threads.get(threadKey);
             if (thread === undefined)
                 throw new Error(`unknown Thread ref '${request.threadRef}'${this.unknownRefHint(request.threadRef, 'thread', 'Thread')}`);
             task = thread.taskRef === undefined ? undefined : projection.tasks.get(thread.taskRef);
         }
         if (request.taskRef !== undefined) {
-            const byTask = projection.tasks.get(request.taskRef);
+            const taskKey = this.requireRefKey(projection.tasks, request.taskRef, 'task', 'Task');
+            const byTask = projection.tasks.get(taskKey);
             if (byTask === undefined)
                 throw new Error(`unknown Task ref '${request.taskRef}'${this.unknownRefHint(request.taskRef, 'task', 'Task')}`);
             if (task !== undefined && task.taskRef !== byTask.taskRef)
@@ -2507,7 +2828,7 @@ export class AgentTeamLedger {
         return { ...(task === undefined ? {} : { task }), thread, channelRef };
     }
     requireChannel(workspaceId, channelRef) {
-        const channel = this.state.channels.get(channelRef);
+        const channel = this.state.channels.get(this.requireRefKey(this.state.channels, channelRef, 'channel', 'Channel'));
         if (channel === undefined)
             throw new Error(`unknown Channel ref '${channelRef}'${this.unknownRefHint(channelRef, 'channel', 'Channel')}`);
         if (channel.workspaceId !== workspaceId)
@@ -2528,7 +2849,7 @@ export class AgentTeamLedger {
         }
     }
     requireMember(memberId) {
-        const member = this.state.members.get(memberId);
+        const member = this.state.members.get(this.requireRefKey(this.state.members, memberId, 'member', 'Agent Member'));
         if (member === undefined)
             throw new Error(`unknown Agent Member '${memberId}'`);
         return member;
@@ -2639,6 +2960,16 @@ export class AgentTeamLedger {
             || operation.data.member.memberId !== request.memberId || operation.data.member.sessionId !== request.sessionId)
             this.throwRequestCollision(request.requestId);
     }
+    assertSameMemberSessionRolledOver(operation, request) {
+        if (operation.kind !== 'team/member-session-rolled-over' || !this.sameActor(operation.actor, request.actor)
+            || operation.data.member.memberId !== request.memberId || operation.data.member.sessionId !== request.newSessionId
+            || operation.data.previousSessionId !== request.previousSessionId || operation.data.handoffEventSeq !== request.handoffEventSeq
+            || operation.data.trigger !== request.trigger
+            || operation.data.sourceSessionId !== request.sourceSessionId
+            || operation.data.sourceThroughSeq !== request.sourceThroughSeq
+            || operation.data.checkpointRef !== request.checkpointRef)
+            this.throwRequestCollision(request.requestId);
+    }
     assertSameChannelUpdate(operation, request) {
         if (operation.kind !== 'team/channel-updated' || !this.sameActor(operation.actor, request.actor)
             || operation.data.workspaceId !== request.workspaceId || operation.data.channel.channelRef !== request.channelRef

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.');
         }
@@ -63,7 +67,7 @@ export function renderMemberMemory(raw, privateMemoryPath = '<private-memory-pat
     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. 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\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}`;
 }
 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}`;