@cjhyy/code-shell-core 0.6.0-rc.9 → 0.7.0

package/dist/session/memory.js

@@ -12,7 +12,11 @@
  *              auto-extracted entries (extract-memories output). LLM may
  *              only modify these through permission-gated tool calls.
  *   - dream/   The dream pipeline's workspace. The LLM is free to add /
- *              merge / delete entries here; user/ is read-only to dream.
+ *              merge / delete entries here. The dream loop may ALSO maintain
+ *              user/ entries whose origin is `auto` or `dream` (dedup/merge/
+ *              improve), but origin:`manual` user entries — things the user
+ *              explicitly asked to remember — are never touched by dream.
+ *              See dream-consolidation.ts (the origin guard at ~:240).
  *
  * MEMORY.md is the index file (one per scope).
  *
@@ -22,6 +26,18 @@
 import { mkdirSync, existsSync, readFileSync, writeFileSync, readdirSync, renameSync, statSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { createHash, randomUUID } from "node:crypto";
+function frontmatterLine(key, value) {
+    return `${key}: ${JSON.stringify(value)}\n`;
+}
+function parseFrontmatterValue(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
 /**
  * Drop memories older than `maxAgeDays` (by file mtime) for context injection
  * (TODO 8.1). A non-positive/undefined maxAge means no filtering. Entries with
@@ -33,7 +49,10 @@ export function filterByAge(entries, maxAgeDays, now = Date.now()) {
         return entries;
     const cutoff = now - maxAgeDays * 24 * 60 * 60 * 1000;
     // Pinned memories never age out of injection — that's the point of the pin.
-    return entries.filter((e) => e.pinned || !e.updatedAt || e.updatedAt >= cutoff);
+    return entries.filter((e) => {
+        const updatedMs = e.mtimeMs ?? (e.updatedAt ? new Date(e.updatedAt).getTime() : Number.NaN);
+        return e.pinned || !Number.isFinite(updatedMs) || updatedMs <= 0 || updatedMs >= cutoff;
+    });
 }
 export function resolveMemoryBaseDir(override) {
     if (override)
@@ -83,37 +102,75 @@ export class MemoryManager {
         // no flat .md files and this becomes a no-op.
         this.migrateFlatLayout();
     }
-    getMemoryDir() { return this.memoryDir; }
-    getScope() { return this.scope; }
+    getMemoryDir() {
+        return this.memoryDir;
+    }
+    getScope() {
+        return this.scope;
+    }
     /**
-     * Save a memory entry. Creates the file and updates the index.
+     * Save a memory entry. New entries get a stable id and `<id>.md`; entries
+     * carrying an existing id update that file even when name changes.
      */
-    save(entry) {
-        const fileName = this.slugify(entry.name) + ".md";
-        const filePath = join(this.memoryDir, fileName);
+    save(entry, opts = {}) {
         const nowIso = new Date().toISOString();
-        // Overwrite = UPDATE: preserve the original `created` and accumulated
-        // `usageCount` of the file being replaced (only `created` is load-bearing
-        // for TTL; carrying usageCount avoids resetting a popular memory's score).
-        // explicit entry fields win over the existing file (lets callers force a value).
-        const existing = existsSync(filePath) ? this.loadFile(fileName) : null;
-        const created = entry.created ?? existing?.created ?? nowIso;
-        const usageCount = entry.usageCount ?? existing?.usageCount ?? 0;
-        const lastUsed = entry.lastUsed ?? existing?.lastUsed ?? created;
+        const inputId = entry.id;
+        const syntheticLegacy = inputId ? this.parseSyntheticLegacyId(inputId) : null;
+        const existing = inputId && !syntheticLegacy
+            ? (this.findById(inputId) ?? null)
+            : syntheticLegacy && syntheticLegacy.scope === this.scope
+                ? this.loadFile(syntheticLegacy.fileName)
+                : null;
+        const id = inputId && !syntheticLegacy ? inputId : this.generateId();
+        const fileName = existing?.fileName ?? this.availableFileNameForId(id);
+        const filePath = join(this.memoryDir, fileName);
+        const origin = opts.forceOrigin ?? entry.origin ?? existing?.origin ?? "manual";
+        const pinned = entry.pinned ?? existing?.pinned;
+        const createdAt = entry.createdAt ?? entry.created ?? existing?.createdAt ?? nowIso;
+        const useCount = entry.useCount ?? entry.usageCount ?? existing?.useCount ?? 0;
+        const lastUsedAt = entry.lastUsedAt ?? entry.lastUsed ?? existing?.lastUsedAt ?? createdAt;
         const originProject = entry.originProject ?? existing?.originProject;
-        // pinned/origin are written only when meaningful so legacy-shaped files
-        // stay byte-identical for unpinned manual saves. Lifecycle fields are
-        // always written now (created/lastUsed/usageCount) — they're how TTL works.
+        const promotionKey = entry.promotionKey ?? existing?.promotionKey;
+        const originProjects = entry.originProjects ?? existing?.originProjects;
+        const evidenceCount = entry.evidenceCount ?? existing?.evidenceCount;
+        const firstSeenAt = entry.firstSeenAt ?? existing?.firstSeenAt;
+        const lastSeenAt = entry.lastSeenAt ?? existing?.lastSeenAt;
+        const promotionReason = entry.promotionReason ?? existing?.promotionReason;
+        const promotionStatus = entry.promotionStatus ?? existing?.promotionStatus;
+        const promotionSourceId = entry.promotionSourceId ?? existing?.promotionSourceId;
+        const contentChanged = existing != null &&
+            (existing.name !== entry.name ||
+                existing.description !== entry.description ||
+                existing.type !== entry.type ||
+                existing.content !== entry.content);
+        const incrementUpdateCount = opts.incrementUpdateCount !== false && contentChanged;
+        const updateCount = (entry.updateCount ?? existing?.updateCount ?? 0) + (incrementUpdateCount ? 1 : 0);
+        const updatedAt = incrementUpdateCount
+            ? nowIso
+            : (entry.updatedAt ?? existing?.updatedAt ?? nowIso);
         const content = `---\n` +
-            `name: ${entry.name}\n` +
-            `description: ${entry.description}\n` +
-            `type: ${entry.type}\n` +
-            (entry.pinned ? `pinned: true\n` : "") +
-            (entry.origin ? `origin: ${entry.origin}\n` : "") +
-            (originProject ? `originProject: ${originProject}\n` : "") +
-            `created: ${created}\n` +
-            `lastUsed: ${lastUsed}\n` +
-            `usageCount: ${usageCount}\n` +
+            frontmatterLine("id", id) +
+            frontmatterLine("name", entry.name) +
+            frontmatterLine("description", entry.description) +
+            frontmatterLine("type", entry.type) +
+            frontmatterLine("origin", origin) +
+            (pinned ? frontmatterLine("pinned", true) : "") +
+            (originProject ? frontmatterLine("originProject", originProject) : "") +
+            (promotionKey ? frontmatterLine("promotionKey", promotionKey) : "") +
+            (originProjects && originProjects.length > 0
+                ? frontmatterLine("originProjects", originProjects)
+                : "") +
+            (typeof evidenceCount === "number" ? frontmatterLine("evidenceCount", evidenceCount) : "") +
+            (firstSeenAt ? frontmatterLine("firstSeenAt", firstSeenAt) : "") +
+            (lastSeenAt ? frontmatterLine("lastSeenAt", lastSeenAt) : "") +
+            (promotionReason ? frontmatterLine("promotionReason", promotionReason) : "") +
+            (promotionStatus ? frontmatterLine("promotionStatus", promotionStatus) : "") +
+            (promotionSourceId ? frontmatterLine("promotionSourceId", promotionSourceId) : "") +
+            frontmatterLine("createdAt", createdAt) +
+            frontmatterLine("updatedAt", updatedAt) +
+            frontmatterLine("lastUsedAt", lastUsedAt) +
+            frontmatterLine("useCount", useCount) +
+            frontmatterLine("updateCount", updateCount) +
             `---\n\n` +
             `${entry.content}\n`;
         writeFileSync(filePath, content, "utf-8");
@@ -140,6 +197,25 @@ export class MemoryManager {
         }
         return entries;
     }
+    findById(id) {
+        return this.loadAll().find((e) => e.id === id);
+    }
+    find(nameOrFileOrId) {
+        return this.loadAll().find((e) => e.id === nameOrFileOrId || e.name === nameOrFileOrId || e.fileName === nameOrFileOrId);
+    }
+    isOwnedBy(entry, allowedOrigins) {
+        if (!entry)
+            return false;
+        return allowedOrigins.includes(entry.origin ?? "manual");
+    }
+    deleteIfOwned(nameOrFileOrId, allowedOrigins) {
+        const entry = this.find(nameOrFileOrId);
+        if (!entry)
+            return "not_found";
+        if (!this.isOwnedBy(entry, allowedOrigins))
+            return "protected";
+        return this.delete(entry.id ?? entry.fileName) ? "deleted" : "not_found";
+    }
     /**
      * Load a single memory file.
      */
@@ -165,32 +241,128 @@ export class MemoryManager {
                 return null;
             const frontmatter = frontmatterMatch[1];
             const content = frontmatterMatch[2].trim();
-            const name = frontmatter.match(/name:\s*(.+)/)?.[1]?.trim() ?? fileName;
-            const description = frontmatter.match(/description:\s*(.+)/)?.[1]?.trim() ?? "";
-            const type = (frontmatter.match(/type:\s*(.+)/)?.[1]?.trim() ?? "project");
-            const pinned = frontmatter.match(/pinned:\s*(.+)/)?.[1]?.trim() === "true";
+            const readRaw = (key) => frontmatter.match(new RegExp(`^${key}:\\s*(.*)$`, "m"))?.[1]?.trim();
+            const readValue = (key) => {
+                const raw = readRaw(key);
+                return raw === undefined ? undefined : parseFrontmatterValue(raw);
+            };
+            const read = (key) => {
+                const value = readValue(key);
+                if (value === undefined || value === null)
+                    return undefined;
+                if (Array.isArray(value))
+                    return value.map(String).join(",");
+                return String(value);
+            };
+            const readList = (key) => {
+                const raw = readRaw(key);
+                if (raw !== undefined && raw.length > 0) {
+                    const value = parseFrontmatterValue(raw);
+                    if (Array.isArray(value)) {
+                        const values = value.map((item) => String(item)).filter(Boolean);
+                        return values.length > 0 ? values : undefined;
+                    }
+                    if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) {
+                        const values = value
+                            .slice(1, -1)
+                            .split(",")
+                            .map((item) => item.trim().replace(/^["']|["']$/g, ""))
+                            .filter(Boolean);
+                        return values.length > 0 ? values : undefined;
+                    }
+                    return [String(value)];
+                }
+                const block = frontmatter.match(new RegExp(`^${key}:\\s*\\n((?:\\s+-\\s+.*\\n?)*)`, "m"));
+                if (block?.[1]) {
+                    const values = block[1]
+                        .split(/\n/)
+                        .map((line) => line.match(/^\s+-\s+(.+)\s*$/)?.[1]?.trim())
+                        .filter((value) => Boolean(value));
+                    return values.length > 0 ? values : undefined;
+                }
+                return undefined;
+            };
+            const readNumber = (key) => {
+                const value = readValue(key);
+                if (value === undefined || value === null || value === "")
+                    return undefined;
+                if (typeof value === "number")
+                    return Number.isFinite(value) ? value : undefined;
+                const parsed = parseInt(String(value), 10);
+                return Number.isFinite(parsed) ? parsed : undefined;
+            };
+            const readBoolean = (key) => {
+                const value = readValue(key);
+                return value === true || value === "true";
+            };
+            const id = read("id") ?? `legacy:${scope}:${fileName}`;
+            const name = read("name") ?? fileName;
+            const description = read("description") ?? "";
+            const type = (read("type") ?? "project");
+            const pinned = readBoolean("pinned");
             // Anchor with ^…/m so `origin:` doesn't accidentally match the
             // `originProject:` line (and vice-versa).
-            const originRaw = frontmatter.match(/^origin:\s*(.+)/m)?.[1]?.trim();
-            const origin = originRaw === "auto" || originRaw === "manual" ? originRaw : undefined;
-            const originProject = frontmatter.match(/^originProject:\s*(.+)/m)?.[1]?.trim() || undefined;
-            let updatedAt = 0;
+            const originRaw = read("origin");
+            const origin = originRaw === "auto" || originRaw === "manual" || originRaw === "dream"
+                ? originRaw
+                : "manual";
+            const originProject = read("originProject") || undefined;
+            let mtimeMs = 0;
             try {
-                updatedAt = statSync(filePath).mtimeMs;
+                mtimeMs = statSync(filePath).mtimeMs;
             }
             catch {
                 // mtime best-effort; 0 = unknown (never filtered out by maxAge).
             }
             // Lifecycle fields. Legacy files lack them → fall back to mtime so a TTL
             // sweep treats them as "last used = file age" rather than "never used".
-            const mtimeIso = updatedAt > 0 ? new Date(updatedAt).toISOString() : undefined;
-            const created = frontmatter.match(/created:\s*(.+)/)?.[1]?.trim() || mtimeIso;
-            const lastUsed = frontmatter.match(/lastUsed:\s*(.+)/)?.[1]?.trim() || created;
-            const usageRaw = frontmatter.match(/usageCount:\s*(\d+)/)?.[1];
-            const usageCount = usageRaw ? parseInt(usageRaw, 10) : 0;
+            const mtimeIso = mtimeMs > 0 ? new Date(mtimeMs).toISOString() : undefined;
+            const createdAt = read("createdAt") ?? read("created") ?? mtimeIso;
+            const updatedAt = read("updatedAt") ?? mtimeIso ?? createdAt;
+            const lastUsedAt = read("lastUsedAt") ?? read("lastUsed") ?? createdAt;
+            const useRaw = read("useCount") ?? read("usageCount");
+            const updateRaw = read("updateCount");
+            const useCount = useRaw ? parseInt(useRaw, 10) : 0;
+            const updateCount = updateRaw ? parseInt(updateRaw, 10) : 0;
+            const promotionKey = read("promotionKey");
+            const originProjects = readList("originProjects");
+            const evidenceCount = readNumber("evidenceCount");
+            const firstSeenAt = read("firstSeenAt");
+            const lastSeenAt = read("lastSeenAt");
+            const promotionReason = read("promotionReason");
+            const promotionStatusRaw = read("promotionStatus");
+            const promotionStatus = promotionStatusRaw === "pending" || promotionStatusRaw === "rejected"
+                ? promotionStatusRaw
+                : undefined;
+            const promotionSourceId = read("promotionSourceId");
             return {
-                name, description, type, content, fileName, scope,
-                updatedAt, pinned, origin, usageCount, lastUsed, created, originProject,
+                id,
+                name,
+                description,
+                type,
+                content,
+                fileName,
+                scope,
+                updatedAt,
+                mtimeMs,
+                pinned,
+                origin,
+                useCount,
+                updateCount,
+                lastUsedAt,
+                createdAt,
+                usageCount: useCount,
+                lastUsed: lastUsedAt,
+                created: createdAt,
+                originProject,
+                promotionKey,
+                originProjects,
+                evidenceCount,
+                firstSeenAt,
+                lastSeenAt,
+                promotionReason,
+                promotionStatus,
+                promotionSourceId,
             };
         }
         catch {
@@ -204,7 +376,7 @@ export class MemoryManager {
      */
     delete(nameOrFile) {
         const entries = this.loadAll();
-        const entry = entries.find((e) => e.name === nameOrFile || e.fileName === nameOrFile);
+        const entry = entries.find((e) => e.id === nameOrFile || e.name === nameOrFile || e.fileName === nameOrFile);
         if (!entry)
             return false;
         try {
@@ -228,21 +400,25 @@ export class MemoryManager {
      * never ages out. Idempotent-safe: missing entry → false, no throw.
      */
     recordRecall(nameOrFile, now = new Date()) {
-        const entry = this.loadAll().find((e) => e.name === nameOrFile || e.fileName === nameOrFile);
+        const entry = this.loadAll().find((e) => e.id === nameOrFile || e.name === nameOrFile || e.fileName === nameOrFile);
         if (!entry)
             return false;
         try {
             this.save({
+                id: entry.id,
                 name: entry.name,
                 description: entry.description,
                 type: entry.type,
                 content: entry.content,
                 pinned: entry.pinned,
                 origin: entry.origin,
-                created: entry.created,
-                usageCount: (entry.usageCount ?? 0) + 1,
-                lastUsed: now.toISOString(),
-            });
+                createdAt: entry.createdAt,
+                updatedAt: entry.updatedAt,
+                useCount: (entry.useCount ?? 0) + 1,
+                updateCount: entry.updateCount,
+                lastUsedAt: now.toISOString(),
+                originProject: entry.originProject,
+            }, { incrementUpdateCount: false });
             return true;
         }
         catch {
@@ -265,7 +441,7 @@ export class MemoryManager {
                 continue; // stable types are exempt
             if (e.pinned)
                 continue; // pinned exempt
-            const lastUsedMs = e.lastUsed ? new Date(e.lastUsed).getTime() : NaN;
+            const lastUsedMs = e.lastUsedAt ? new Date(e.lastUsedAt).getTime() : NaN;
             // Unknown lastUsed (unparseable) → keep, never prune on missing data.
             if (!Number.isFinite(lastUsedMs))
                 continue;
@@ -277,13 +453,14 @@ export class MemoryManager {
         return pruned;
     }
     /**
-     * Approve a pending memory: move it from the pending scope into the user scope
-     * of the SAME memory root (pending only ever exists at the global root — the
-     * approval门 only gates global writes). Must be called on a pending-scope
-     * manager. Returns the new user filename, or null if not found / wrong scope.
+     * Approve a pending memory: move it from the pending scope into the global
+     * dream scope of the SAME memory root. Pending only ever exists at the global
+     * root; approval gates whether a suggested global dream becomes injected.
+     * Must be called on a pending-scope manager. Returns the new global dream
+     * filename, or null if not found / wrong scope.
      *
-     * 审批门 (用户拍板): the only path that moves an auto-extracted memory into the
-     * curated, injected global user store.
+     * 审批门 (用户拍板): the only path that moves a suggested global dream into the
+     * injected global dream store.
      */
     approvePending(nameOrFile) {
         return this.movePending(nameOrFile, "global");
@@ -295,27 +472,86 @@ export class MemoryManager {
     demotePending(nameOrFile) {
         return this.movePending(nameOrFile, "project");
     }
-    /** Shared move for approve(→global user)/demote(→origin-project user). */
+    /**
+     * Reject a pending global-dream suggestion. The project dream entry stays in
+     * place, but is marked so the same source is not suggested again.
+     */
+    rejectPending(nameOrFile) {
+        if (this.scope !== "pending")
+            return false;
+        const entry = this.find(nameOrFile);
+        if (!entry)
+            return false;
+        if (entry.originProject) {
+            const projectDream = new MemoryManager({
+                baseDir: this.baseDir,
+                projectDir: entry.originProject,
+                scope: "dream",
+            });
+            const source = (entry.promotionSourceId ? projectDream.findById(entry.promotionSourceId) : undefined) ??
+                projectDream.loadAll().find((candidate) => candidate.name === entry.name);
+            if (source && source.origin !== "manual") {
+                projectDream.save({
+                    id: source.id,
+                    name: source.name,
+                    description: source.description,
+                    type: source.type,
+                    content: source.content,
+                    origin: source.origin ?? "dream",
+                    pinned: source.pinned,
+                    createdAt: source.createdAt,
+                    updatedAt: source.updatedAt,
+                    lastUsedAt: source.lastUsedAt,
+                    useCount: source.useCount,
+                    updateCount: source.updateCount,
+                    originProject: source.originProject,
+                    originProjects: source.originProjects,
+                    evidenceCount: source.evidenceCount,
+                    firstSeenAt: source.firstSeenAt,
+                    lastSeenAt: source.lastSeenAt,
+                    promotionReason: entry.promotionReason ?? source.promotionReason,
+                    promotionStatus: "rejected",
+                }, { incrementUpdateCount: false, forceOrigin: source.origin ?? "dream" });
+            }
+        }
+        return this.delete(entry.id ?? entry.name);
+    }
+    /** Shared move for approve(→global dream)/demote(→origin-project user). */
     movePending(nameOrFile, dest) {
         if (this.scope !== "pending")
             return null;
-        const entry = this.loadAll().find((e) => e.name === nameOrFile || e.fileName === nameOrFile);
+        const entry = this.find(nameOrFile);
         if (!entry)
             return null;
-        const targetMgr = dest === "project" && entry.originProject
-            ? new MemoryManager({ baseDir: this.baseDir, projectDir: entry.originProject, scope: "user" })
-            : new MemoryManager({ baseDir: this.baseDir, scope: "user" }); // global, or fallback
+        const targetMgr = dest === "global"
+            ? new MemoryManager({ baseDir: this.baseDir, scope: "dream" })
+            : dest === "project" && entry.originProject
+                ? new MemoryManager({
+                    baseDir: this.baseDir,
+                    projectDir: entry.originProject,
+                    scope: "user",
+                })
+                : new MemoryManager({ baseDir: this.baseDir, scope: "user" }); // demote fallback
+        const destinationOrigin = dest === "global" ? "dream" : (entry.origin ?? "auto");
         const fileName = targetMgr.save({
             name: entry.name,
             description: entry.description,
             type: entry.type,
             content: entry.content,
-            origin: entry.origin ?? "auto",
-            created: entry.created,
-            lastUsed: entry.lastUsed,
-            usageCount: entry.usageCount,
-            // originProject is no longer needed once it has landed in a real store.
-        });
+            origin: destinationOrigin,
+            createdAt: entry.createdAt,
+            updatedAt: entry.updatedAt,
+            lastUsedAt: entry.lastUsedAt,
+            useCount: entry.useCount,
+            updateCount: entry.updateCount,
+            originProjects: entry.originProjects ?? (entry.originProject ? [entry.originProject] : []),
+            evidenceCount: entry.evidenceCount,
+            firstSeenAt: entry.firstSeenAt,
+            lastSeenAt: entry.lastSeenAt,
+            promotionReason: entry.promotionReason,
+            // originProject/promotionSourceId are no longer needed once it has landed
+            // in a real store.
+        }, { forceOrigin: destinationOrigin });
         this.delete(entry.name); // soft-delete the pending copy
         return fileName;
     }
@@ -337,9 +573,11 @@ export class MemoryManager {
             content: entry.content,
             origin: entry.origin,
             pinned: entry.pinned,
-            created: entry.created,
-            lastUsed: entry.lastUsed,
-            usageCount: entry.usageCount,
+            createdAt: entry.createdAt,
+            updatedAt: entry.updatedAt,
+            lastUsedAt: entry.lastUsedAt,
+            useCount: entry.useCount,
+            updateCount: entry.updateCount,
         });
         this.delete(entry.name); // remove from the project store
         return fileName;
@@ -517,16 +755,41 @@ export class MemoryManager {
         for (const [fileName, meta] of cache) {
             lines.push(`- [${meta.name}](${fileName}) — ${meta.description}`);
         }
-        const content = lines.length > 0
-            ? lines.join("\n") + "\n"
-            : "(no memories stored)\n";
+        const content = lines.length > 0 ? lines.join("\n") + "\n" : "(no memories stored)\n";
         writeFileSync(this.indexPath, content, "utf-8");
     }
-    slugify(text) {
-        return text
+    generateId() {
+        return `mem_${randomUUID().replace(/-/g, "")}`;
+    }
+    availableFileNameForId(id) {
+        let attempt = 0;
+        while (attempt < 100) {
+            const fileName = this.fileNameForId(id, attempt);
+            const existing = this.loadFile(fileName);
+            if (!existing || existing.id === id)
+                return fileName;
+            attempt++;
+        }
+        throw new Error(`Unable to allocate a memory filename for id "${id}"`);
+    }
+    fileNameForId(id, collisionAttempt = 0) {
+        if (collisionAttempt === 0 && /^[a-z0-9][a-z0-9_.-]*$/.test(id) && !id.includes("..")) {
+            return `${id}.md`;
+        }
+        const safeStem = id
             .toLowerCase()
-            .replace(/[^a-z0-9]+/g, "-")
-            .replace(/^-|-$/g, "")
-            .slice(0, 60);
+            .replace(/[^a-z0-9_.-]/g, "_")
+            .replace(/_+/g, "_")
+            .replace(/^[._-]+|[._-]+$/g, "")
+            .slice(0, 80) || "memory";
+        const hashInput = collisionAttempt === 0 ? id : `${id}:${collisionAttempt}`;
+        const hash = createHash("sha256").update(hashInput).digest("hex").slice(0, 12);
+        return `${safeStem}-${hash}.md`;
+    }
+    parseSyntheticLegacyId(id) {
+        const match = id.match(/^legacy:(user|dream|pending):(.+)$/);
+        if (!match)
+            return null;
+        return { scope: match[1], fileName: match[2] };
     }
 }

package/dist/session/session-manager.d.ts

@@ -1,12 +1,25 @@
 /**
  * Session lifecycle manager.
  */
-import type { SessionState } from "../types.js";
+import type { SessionState, SessionWorkspace } from "../types.js";
 import { Transcript } from "./transcript.js";
 export interface SessionBundle {
     state: SessionState;
     transcript: Transcript;
 }
+export type SessionWorkspaceResumeResolution = {
+    ok: true;
+    cwd: string;
+    workspace: SessionWorkspace;
+    message?: string;
+    reason?: "main" | "worktree" | "legacy" | "worktree_missing_branch_gone";
+} | {
+    ok: false;
+    cwd: string;
+    workspace: SessionWorkspace;
+    message: string;
+    reason: "worktree_missing_branch_exists";
+};
 /**
  * Validate a session ID before it is joined into a filesystem path.
  *
@@ -57,6 +70,27 @@ export declare class SessionManager {
      * caller treats "no recoverable cwd" the same as "not given".
      */
     readCwd(sessionId: string): string | undefined;
+    /**
+     * Disk-only workspace pointer reader. Legacy sessions written before
+     * `workspace` existed are treated as main-workspace sessions rooted at
+     * `state.cwd`; the read is intentionally non-mutating.
+     */
+    getSessionWorkspace(sessionId: string): SessionWorkspace | undefined;
+    /**
+     * Persist the current session workspace pointer without changing legacy
+     * `cwd`. P1 will teach ToolContext to resolve cwd from this field; for P0 it
+     * is a safety pointer and resume breadcrumb.
+     */
+    setSessionWorkspace(sessionId: string, workspace: SessionWorkspace): void;
+    recordWorkspaceHandoff(sessionId: string, from: SessionWorkspace | undefined, to: SessionWorkspace): void;
+    /**
+     * Resolve the cwd a resumed session must run in from its persisted workspace
+     * pointer. A missing worktree directory is never silently treated as the main
+     * repo: if the branch still exists callers get a blocking recreate message;
+     * if the branch is gone the workspace pointer is reset to main and a warning
+     * message is returned for the host to surface before continuing.
+     */
+    resolveSessionWorkspaceForResume(sessionId: string): Promise<SessionWorkspaceResumeResolution>;
     /**
      * Cheap "does this session have a persisted goal?" probe — reads only
      * state.json, NOT the transcript (like readCwd). A persistent goal lives ONLY