@wowyuarm/dsh-agent-team 0.1.8 → 0.1.9

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

@@ -17,7 +17,7 @@ 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([]),
@@ -247,9 +247,137 @@ 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)
@@ -666,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);
@@ -674,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,
@@ -1155,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 }];
@@ -1275,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':
@@ -1407,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);
@@ -1640,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));
@@ -1670,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]);
@@ -1938,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') {
@@ -2216,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) {
@@ -2762,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.');
         }

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

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