@cjhyy/code-shell-core 0.6.0-rc.14 → 0.6.0-rc.15

package/dist/protocol/server.d.ts

@@ -50,6 +50,12 @@ export interface AgentServerOptions {
      * reopened-session path can omit it.
      */
     readActiveGoalFromDisk?: (sessionId: string) => import("../engine/goal.js").GoalConfig | undefined;
+    /**
+     * Enable the desktop workspace bridge channel. Off by default so generic
+     * protocol hosts do not emit hidden workspace approval requests they cannot
+     * service.
+     */
+    workspaceBridge?: boolean;
 }
 export declare class AgentServer {
     private readonly chatManager;
@@ -60,6 +66,7 @@ export declare class AgentServer {
     private readonly settingsReader;
     /** Disk-only active-goal reader for agent/goalGet on a non-live session. */
     private readonly readActiveGoalFromDisk;
+    private readonly workspaceBridgeEnabled;
     /**
      * Monotonic config-reload version, bumped per reloadSettings request so each
      * Engine.refreshRuntimeConfig can drop out-of-order (stale) deliveries (Q5).
@@ -178,6 +185,7 @@ export declare class AgentServer {
      */
     private handleBackgroundWork;
     private handleCloseSession;
+    private handleReleaseWorkspace;
     private handleConfigure;
     private handleQuery;
     private handleInject;
@@ -211,6 +219,8 @@ export declare class AgentServer {
      * parse into { ok, count?, error? }. Degrades to ok:false on timeout/malformed.
      */
     private requestCredentialInjectForSession;
+    private makeWorkspaceBridge;
+    private requestWorkspaceSwitchForSession;
     /**
      * Ask the client to answer a question from the agent (legacy single-engine
      * path). This intentionally has no wall-clock timeout; Stop/cancel drains

package/dist/protocol/server.js

@@ -48,6 +48,7 @@ export class AgentServer {
     settingsReader;
     /** Disk-only active-goal reader for agent/goalGet on a non-live session. */
     readActiveGoalFromDisk;
+    workspaceBridgeEnabled;
     /**
      * Monotonic config-reload version, bumped per reloadSettings request so each
      * Engine.refreshRuntimeConfig can drop out-of-order (stale) deliveries (Q5).
@@ -93,6 +94,7 @@ export class AgentServer {
         this.legacyEngine = options.engine ?? null;
         this.settingsReader = options.settingsReader ?? null;
         this.readActiveGoalFromDisk = options.readActiveGoalFromDisk ?? null;
+        this.workspaceBridgeEnabled = options.workspaceBridge === true;
         if (!this.chatManager && !this.legacyEngine) {
             throw new Error("AgentServer: either chatManager or engine must be supplied");
         }
@@ -267,6 +269,9 @@ export class AgentServer {
             case Methods.CloseSession:
                 this.handleCloseSession(req);
                 break;
+            case Methods.ReleaseWorkspace:
+                this.handleReleaseWorkspace(req);
+                break;
             case Methods.GoalExtend:
                 this.handleGoalExtend(req);
                 break;
@@ -363,7 +368,10 @@ export class AgentServer {
             session.engine.setBrowserBridge(this.makeBrowserBridge(session, sid));
             // Cookie→browser injection (InjectCredential tool): same cross-process
             // channel; main restores the cookie jar into the built-in browser.
-            session.engine.setInjectCredential((credentialId) => this.requestCredentialInjectForSession(session, sid, credentialId));
+            session.engine.setInjectCredential((credentialId, credentialScope) => this.requestCredentialInjectForSession(session, sid, credentialId, credentialScope));
+            if (this.workspaceBridgeEnabled && typeof session.engine.setWorkspaceBridge === "function") {
+                session.engine.setWorkspaceBridge(this.makeWorkspaceBridge(session, sid));
+            }
         }
         try {
             const result = await session.enqueueTurn(params.task, {
@@ -753,6 +761,28 @@ export class AgentServer {
         backgroundJobRegistry.dropForSession(params.sessionId);
         this.transport.send(createResponse(req.id, { ok: true }));
     }
+    // ─── ReleaseWorkspace ──────────────────────────────────────────
+    handleReleaseWorkspace(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        if (this.chatManager) {
+            const session = this.chatManager.get(params.sessionId);
+            if (!session) {
+                this.transport.send(createResponse(req.id, { ok: true, workspace: null }));
+                return;
+            }
+            const engine = session.engine;
+            const workspace = engine.releaseSessionWorkspace?.(params.sessionId) ?? null;
+            this.transport.send(createResponse(req.id, { ok: true, workspace }));
+            return;
+        }
+        const engine = this.legacyEngine;
+        const workspace = engine?.releaseSessionWorkspace?.(params.sessionId) ?? null;
+        this.transport.send(createResponse(req.id, { ok: true, workspace }));
+    }
     // ─── Configure ──────────────────────────────────────────────────
     handleConfigure(req) {
         const params = (req.params ?? {});
@@ -1501,7 +1531,7 @@ export class AgentServer {
             // ask and resolve with a nudge so the loop keeps making progress instead
             // of hanging. Plain interactive (no-goal) asks keep their intentional
             // no-timeout behavior — a human can take as long as they like.
-            let goalActive = false;
+            let goalActive;
             try {
                 goalActive = !!session.getGoal();
             }
@@ -1605,7 +1635,7 @@ export class AgentServer {
      * calls restoreCookiesToBrowser and replies with a JSON result string we
      * parse into { ok, count?, error? }. Degrades to ok:false on timeout/malformed.
      */
-    requestCredentialInjectForSession(session, sessionId, credentialId) {
+    requestCredentialInjectForSession(session, sessionId, credentialId, credentialScope = "full") {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
             session.pendingApprovals.set(requestId, (decision) => {
@@ -1642,13 +1672,67 @@ export class AgentServer {
                 requestId,
                 request: {
                     toolName: "__credential_action__",
-                    args: { action: "injectCookie", credentialId },
+                    args: { action: "injectCookie", credentialId, credentialScope },
                     description: `credential:inject:${credentialId}`,
                     riskLevel: "low",
                 },
             });
         });
     }
+    makeWorkspaceBridge(session, sessionId) {
+        return {
+            switch: (target) => this.requestWorkspaceSwitchForSession(session, sessionId, target),
+        };
+    }
+    requestWorkspaceSwitchForSession(session, sessionId, target) {
+        return new Promise((resolve, reject) => {
+            const requestId = nanoid(12);
+            session.pendingApprovals.set(requestId, (decision) => {
+                this.clearApprovalTimer(requestId);
+                let raw;
+                if (decision && typeof decision === "object" && "approved" in decision) {
+                    const r = decision;
+                    raw = r.approved ? r.answer : undefined;
+                }
+                else if (typeof decision === "string") {
+                    raw = decision;
+                }
+                if (raw === undefined) {
+                    reject(new Error("workspace switch declined or unavailable"));
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(raw);
+                    if ("ok" in parsed && parsed.ok === false) {
+                        reject(new Error(parsed.error ?? "workspace switch failed"));
+                        return;
+                    }
+                    resolve(parsed);
+                }
+                catch {
+                    reject(new Error("malformed workspace switch result"));
+                }
+            });
+            const timer = setTimeout(() => {
+                if (session.pendingApprovals.has(requestId)) {
+                    session.pendingApprovals.delete(requestId);
+                    this.approvalTimers.delete(requestId);
+                    reject(new Error("workspace switch timed out"));
+                }
+            }, AgentServer.APPROVAL_TIMEOUT_MS);
+            this.approvalTimers.set(requestId, timer);
+            this.notify(Methods.ApprovalRequest, {
+                sessionId,
+                requestId,
+                request: {
+                    toolName: "__workspace_action__",
+                    args: { action: "switch", target },
+                    description: `workspace:switch:${target}`,
+                    riskLevel: "low",
+                },
+            });
+        });
+    }
     /**
      * Ask the client to answer a question from the agent (legacy single-engine
      * path). This intentionally has no wall-clock timeout; Stop/cancel drains

package/dist/protocol/types.d.ts

@@ -123,6 +123,10 @@ export interface CancelParams {
 export interface CloseSessionParams {
     sessionId: string;
 }
+/** Reset a live session's workspace binding back to main. */
+export interface ReleaseWorkspaceParams {
+    sessionId: string;
+}
 /** Inject context into a session transcript. */
 export interface InjectParams {
     sessionId: string;
@@ -279,6 +283,8 @@ export declare const Methods: {
     readonly Unsteer: "agent/unsteer";
     /** Close (destroy) a session. */
     readonly CloseSession: "agent/closeSession";
+    /** Reset a session's workspace binding to main without closing it. */
+    readonly ReleaseWorkspace: "agent/releaseWorkspace";
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     readonly GoalExtend: "agent/goalExtend";
     /** Clear a session's persisted active goal (CC /goal clear). */

package/dist/protocol/types.js

@@ -41,6 +41,8 @@ export const Methods = {
     Unsteer: "agent/unsteer",
     /** Close (destroy) a session. */
     CloseSession: "agent/closeSession",
+    /** Reset a session's workspace binding to main without closing it. */
+    ReleaseWorkspace: "agent/releaseWorkspace",
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     GoalExtend: "agent/goalExtend",
     /** Clear a session's persisted active goal (CC /goal clear). */

package/dist/runtime/background-shell.js

@@ -23,7 +23,6 @@
  * worker discover and reap them (§难点1, `reapOrphansFromPidfiles`).
  */
 import { spawn } from "node:child_process";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { mkdirSync, writeFileSync, rmSync, existsSync, readdirSync, readFileSync, } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
@@ -33,6 +32,7 @@ import { RingFile } from "./ring-file.js";
 import { cleanOutput } from "./output-clean.js";
 import { notificationQueue } from "../tool-system/builtin/agent-notifications.js";
 import { logger } from "../logging/logger.js";
+import { codeShellHome } from "../session/session-manager.js";
 /** Per-session soft cap on background shells (design §7 — fork-bomb guard). */
 export const MAX_SHELLS_PER_SESSION = 16;
 /** Disk ring-file cap: keep the most recent 8MB of raw output (design §6). */
@@ -49,8 +49,7 @@ function nextShellId() {
     return `bg_${shellCounter.toString(36)}${(shellCounter * 2654435761 % 0xffffff).toString(36)}`;
 }
 function bgShellsRoot() {
-    const base = process.env.CODE_SHELL_HOME ?? process.env.HOME ?? homedir();
-    return join(base, ".code-shell", "bg-shells");
+    return join(codeShellHome(), "bg-shells");
 }
 const PORT_REGEXES = [
     /localhost:(\d{2,5})/i,

package/dist/services/auto-dream.d.ts

@@ -27,10 +27,9 @@ export declare function recordDreamComplete(): void;
 /**
  * System prompt for the auto-dream tool-call loop.
  *
- * Drives the LLM as a "memory consolidation assistant" that operates ONLY in
- * the dream scope via the MemorySave/MemoryDelete tools. The user scope is
- * read-only context — modifying it would need permission, which a background
- * dream pass cannot obtain (no UI on the call path).
+ * Drives the LLM as a "memory consolidation assistant" that operates in dream
+ * scope and may maintain dream-owned user memories. Manual user memories are
+ * read-only and protected by the dispatcher.
  */
 export declare function buildDreamSystemPrompt(): string;
 /**
@@ -39,15 +38,27 @@ export declare function buildDreamSystemPrompt(): string;
  * body. The LLM uses MemoryRead to fetch bodies for entries it wants to act on.
  */
 export declare function buildDreamUserPrompt(userMemories: Array<{
+    id?: string;
     name: string;
     type: string;
     description: string;
+    origin?: string;
+    useCount?: number;
+    updateCount?: number;
 }>, dreamMemories: Array<{
+    id?: string;
     name: string;
     type: string;
     description: string;
+    origin?: string;
+    useCount?: number;
+    updateCount?: number;
 }>, globalMemories?: Array<{
+    id?: string;
     name: string;
     type: string;
     description: string;
+    origin?: string;
+    useCount?: number;
+    updateCount?: number;
 }>): string;

package/dist/services/auto-dream.js

@@ -71,34 +71,34 @@ export function recordDreamComplete() {
 /**
  * System prompt for the auto-dream tool-call loop.
  *
- * Drives the LLM as a "memory consolidation assistant" that operates ONLY in
- * the dream scope via the MemorySave/MemoryDelete tools. The user scope is
- * read-only context — modifying it would need permission, which a background
- * dream pass cannot obtain (no UI on the call path).
+ * Drives the LLM as a "memory consolidation assistant" that operates in dream
+ * scope and may maintain dream-owned user memories. Manual user memories are
+ * read-only and protected by the dispatcher.
  */
 export function buildDreamSystemPrompt() {
     return [
         "You are a memory consolidation assistant for the CodeShell memory system.",
         "",
-        "Your job: clean up the `dream` scope by deduplicating, merging, removing stale, and improving descriptions.",
+        "Your job: clean up the `dream` scope by deduplicating, merging, removing stale, and improving descriptions, and promote only durable lessons into dream-owned `user` entries.",
         "",
         "Tools available (each takes `location`: 'global' = cross-project store, 'project' = this repo; default project):",
         "- MemoryList({ scope, location }): list memories in a scope/location",
         "- MemoryRead({ scope, location, name }): read full content of an entry",
-        "- MemorySave({ scope: 'dream', location, ... }): create or overwrite a dream entry (auto-approved)",
-        "- MemoryDelete({ scope: 'dream', location, name }): soft-delete a dream entry (auto-approved, recoverable from trash)",
+        "- MemorySave({ scope: 'dream'|'user', location, id?, ... }): create or update an entry by id",
+        "- MemoryDelete({ scope: 'dream'|'user', location, name }): soft-delete an owned entry (recoverable from trash)",
         "",
-        "Consolidate BOTH the project dream scope AND the global dream scope (pass location accordingly). Global holds cross-project lessons; keep it deduped too.",
+        "Consolidate BOTH the project dream workspace AND the global dream workspace (pass location accordingly). Global dream is a cross-project workspace, not a dumping ground for single-project progress.",
         "",
         "Rules — read carefully:",
-        "1. You may freely Save/Delete in the `dream` scope (any location). These operations DO NOT prompt the user.",
-        "2. You may NOT Save/Delete in the `user` scope from this loop — those operations require interactive permission which is not available here. Treat user-scope entries as read-only context.",
-        "3. If you find user-scope entries that look stale, surface them in your final summary text — don't try to delete them.",
-        "4. Prefer fewer, higher-quality merged entries over many similar fragments.",
-        "5. When an entry has versioned variants (e.g. `*-v1`, `*-v2`, `*-v3`), keep only the latest.",
-        "6. Be conservative: if uncertain whether two entries are truly duplicates, leave them alone.",
-        "7. Archive COMPLETED work: dream entries that only record a finished fix/task (\"已修\", \"已完成\", \"done\") and carry no reusable lesson should be deleted, or merged into one compact changelog-style entry — completed-state notes that only grow are the main source of clutter. Keep any durable lesson (root cause, pitfall, convention) by folding it into a topical entry first.",
-        "8. When you're done, stop calling tools and respond with a one-paragraph summary of what you changed.",
+        "1. You may Save/Delete dream-scope entries only when they are origin:auto or origin:dream. Never modify origin:manual; missing origin means manual.",
+        "2. You may Save user-scope entries only for durable conclusions you own. The dispatcher will force origin:dream. You may update existing user entries only when they are origin:dream or origin:auto. Never modify/delete origin:manual user entries.",
+        "3. Use MemoryList first. If the same topic already has an id, update that id instead of creating a date, version, batch, or progress variant.",
+        "4. Cluster duplicates without vectors: compare stable topic words after removing dates, versions, batch numbers, and progress/completed wording.",
+        "5. Time-sensitivity rule: entries with dates, today/yesterday, progress snapshots, completed fixes, review batches, or one-off task state should stay in dream, be merged, or be deleted. Do not promote them to user.",
+        "6. Durable lessons may be promoted to user only when they are reusable: user preferences, long-term project constraints, architecture decisions, root-cause lessons, non-obvious test/build traps, or stable references.",
+        '7. Archive COMPLETED work: dream entries that only record a finished fix/task ("已修", "已完成", "done") and carry no reusable lesson should be deleted, or merged into one compact topical entry. Keep any durable lesson by folding it into a date-free topic entry first.',
+        "8. Prefer fewer, higher-quality merged entries over many similar fragments. Be conservative: if uncertain whether two entries are truly duplicates, leave them alone.",
+        "9. When you're done, stop calling tools and respond with a one-paragraph summary of what you changed.",
     ].join("\n");
 }
 /**
@@ -107,18 +107,18 @@ export function buildDreamSystemPrompt() {
  * body. The LLM uses MemoryRead to fetch bodies for entries it wants to act on.
  */
 export function buildDreamUserPrompt(userMemories, dreamMemories, globalMemories = []) {
-    const fmt = (m) => `  - [${m.type}] ${m.name}: ${m.description}`;
+    const fmt = (m) => `  - [${m.type}] ${m.name} (id:${m.id ?? "(none)"}, origin:${m.origin ?? "manual"}, use:${m.useCount ?? 0}, updates:${m.updateCount ?? 0}): ${m.description}`;
     const listOrNone = (arr, noneMsg) => arr.length === 0 ? noneMsg : arr.map(fmt).join("\n");
     const sections = [];
-    sections.push(`Project user-scope memories (READ-ONLY context, ${userMemories.length} entries):`);
+    sections.push(`Project user-scope memories (manual is READ-ONLY; origin:dream/auto may be maintained by id, ${userMemories.length} entries):`);
     sections.push(listOrNone(userMemories, "  (none)"));
     sections.push("");
     sections.push(`Project dream-scope memories (YOUR WORKSPACE — location:'project', ${dreamMemories.length} entries):`);
     sections.push(listOrNone(dreamMemories, "  (none — you may consolidate from user-scope by re-saving curated entries into dream)"));
     sections.push("");
-    sections.push(`Global memories (cross-project — clean these too via location:'global', ${globalMemories.length} entries):`);
+    sections.push(`Global dream workspace memories (cross-project dream — clean these too via location:'global', ${globalMemories.length} entries):`);
     sections.push(listOrNone(globalMemories, "  (none)"));
     sections.push("");
-    sections.push("Begin consolidation. Use MemoryRead to inspect any entries whose names suggest duplication or staleness, then MemorySave/MemoryDelete (with the right location) to clean up.");
+    sections.push("Begin consolidation. Use MemoryRead to inspect any entries whose names suggest duplication or staleness, then MemorySave/MemoryDelete (with the right id/location/scope) to clean up.");
     return sections.join("\n");
 }

package/dist/services/dream-consolidation.d.ts

@@ -13,9 +13,8 @@
  * The loop is intentionally small and offline:
  *   - No streaming, no UI events — it runs in the background.
  *   - No permission prompts — there is no interactive backend on this path, so
- *     we hard-reject any attempt to Save/Delete in the "user" scope before
- *     dispatching. The "dream" scope is the LLM's workspace and goes through
- *     freely.
+ *     Save/Delete goes through an origin guard before dispatching. Dream may
+ *     maintain origin:dream/auto entries but never touches origin:manual.
  *   - Capped at MAX_TURNS LLM round-trips and MAX_WRITES total mutations to
  *     bound damage on misbehavior.
  */

package/dist/services/dream-consolidation.js

@@ -13,17 +13,17 @@
  * The loop is intentionally small and offline:
  *   - No streaming, no UI events — it runs in the background.
  *   - No permission prompts — there is no interactive backend on this path, so
- *     we hard-reject any attempt to Save/Delete in the "user" scope before
- *     dispatching. The "dream" scope is the LLM's workspace and goes through
- *     freely.
+ *     Save/Delete goes through an origin guard before dispatching. Dream may
+ *     maintain origin:dream/auto entries but never touches origin:manual.
  *   - Capped at MAX_TURNS LLM round-trips and MAX_WRITES total mutations to
  *     bound damage on misbehavior.
  */
 import { MemoryManager } from "../session/memory.js";
-import { buildDreamSystemPrompt, buildDreamUserPrompt, } from "./auto-dream.js";
+import { buildDreamSystemPrompt, buildDreamUserPrompt } from "./auto-dream.js";
 import { logger } from "../logging/logger.js";
 const MAX_TURNS = 8;
 const MAX_WRITES = 10;
+const FRESH_ENTRY_GRACE_MS = 10 * 60 * 1000;
 const MEMORY_TOOL_NAMES = ["MemoryList", "MemoryRead", "MemorySave", "MemoryDelete"];
 /**
  * Drive the dream-scope consolidation tool-call loop.
@@ -37,9 +37,7 @@ const MEMORY_TOOL_NAMES = ["MemoryList", "MemoryRead", "MemorySave", "MemoryDele
  */
 export async function runDreamConsolidation(input) {
     const { llmClient, toolRegistry, projectDir, sessionId } = input;
-    const memoryTools = MEMORY_TOOL_NAMES
-        .map((n) => toolRegistry.getTool(n))
-        .filter((t) => t != null);
+    const memoryTools = MEMORY_TOOL_NAMES.map((n) => toolRegistry.getTool(n)).filter((t) => t != null);
     if (memoryTools.length < MEMORY_TOOL_NAMES.length) {
         logger.warn("memory.dream_missing_tools", {
             sessionId,
@@ -52,8 +50,9 @@ export async function runDreamConsolidation(input) {
     const mm = new MemoryManager({ projectDir });
     const userMems = mm.loadScope("user");
     const dreamMems = mm.loadScope("dream");
+    const globalDreamMems = projectDir ? new MemoryManager({ scope: "dream" }).loadAll() : [];
     const systemPrompt = buildDreamSystemPrompt();
-    const userPrompt = buildDreamUserPrompt(userMems, dreamMems);
+    const userPrompt = buildDreamUserPrompt(userMems, dreamMems, globalDreamMems);
     // Strip RegisteredTool down to the shape createMessage expects.
     const toolDefs = memoryTools.map((t) => ({
         name: t.name,
@@ -120,8 +119,8 @@ export async function runDreamConsolidation(input) {
  * Execute one memory tool call inside the dream loop. Enforces the two
  * dream-loop invariants the prompt also states:
  *   - Only the 4 memory tools are dispatchable.
- *   - Save/Delete in "user" scope is refused (returned as a tool error)
- *     because dream runs without an interactive permission backend.
+ *   - Save/Delete is allowed only for origin:auto/origin:dream owned entries.
+ *     Missing origin is manual, and manual is always protected.
  */
 async function dispatchDreamTool(tc, toolRegistry, ctx, consumeWriteBudget) {
     const allowed = new Set(MEMORY_TOOL_NAMES);
@@ -130,17 +129,17 @@ async function dispatchDreamTool(tc, toolRegistry, ctx, consumeWriteBudget) {
     }
     const isWrite = tc.toolName === "MemorySave" || tc.toolName === "MemoryDelete";
     if (isWrite) {
-        const scope = tc.args?.scope;
-        if (scope !== "dream") {
-            return (`Error: dream loop may only write to scope "dream", got "${scope}". ` +
-                `User-scope changes require interactive permission, which is not available here.`);
+        const guard = checkDreamWriteGuard(tc, ctx);
+        if (!guard.ok) {
+            return guard.error;
         }
         if (!consumeWriteBudget()) {
             return "Error: dream write budget exhausted — stop calling write tools and summarize instead.";
         }
     }
     try {
-        const result = await toolRegistry.executeTool(tc.toolName, tc.args, { ctx });
+        const dreamCtx = { ...ctx, __dreamLoop: true };
+        const result = await toolRegistry.executeTool(tc.toolName, tc.args, { ctx: dreamCtx });
         if (result.isError)
             return result.error ?? `Error executing ${tc.toolName}`;
         return result.result ?? "";
@@ -149,3 +148,54 @@ async function dispatchDreamTool(tc, toolRegistry, ctx, consumeWriteBudget) {
         return `Error executing ${tc.toolName}: ${err.message}`;
     }
 }
+function checkDreamWriteGuard(tc, ctx) {
+    const scope = tc.args?.scope;
+    if (scope !== "dream" && scope !== "user") {
+        return {
+            ok: false,
+            error: `Error: dream loop may only write to scope "dream" or "user", got "${scope}".`,
+        };
+    }
+    const location = tc.args?.location === "global" ? "global" : "project";
+    const mm = new MemoryManager({
+        projectDir: location === "project" ? ctx.cwd : undefined,
+        scope,
+    });
+    const id = typeof tc.args?.id === "string" ? tc.args.id : undefined;
+    const name = typeof tc.args?.name === "string" ? tc.args.name : undefined;
+    const targetById = id ? mm.findById(id) : undefined;
+    const targetByName = name ? mm.find(name) : undefined;
+    const targets = [targetById, targetByName].filter((target, index, all) => Boolean(target) && all.findIndex((item) => item?.id === target?.id) === index);
+    const protectedTarget = targets.find((target) => target.origin === "manual" || !target.origin);
+    if (protectedTarget) {
+        return {
+            ok: false,
+            error: `Error: dream loop cannot modify origin:manual memory "${protectedTarget.name}" ` +
+                `(${location}/${scope}/${protectedTarget.id ?? protectedTarget.fileName}).`,
+        };
+    }
+    const target = targetById ?? targetByName;
+    if (!target)
+        return { ok: true };
+    if (target.origin !== "auto" && target.origin !== "dream") {
+        return {
+            ok: false,
+            error: `Error: dream loop can only modify origin:auto or origin:dream memories; ` +
+                `"${target.name}" has origin:${target.origin}.`,
+        };
+    }
+    if (tc.toolName === "MemoryDelete" && isFreshEntry(target.createdAt)) {
+        return {
+            ok: false,
+            error: `Error: dream loop cannot delete freshly-created memory "${target.name}" yet; ` +
+                "leave it for the next consolidation pass.",
+        };
+    }
+    return { ok: true };
+}
+function isFreshEntry(createdAt) {
+    if (!createdAt)
+        return false;
+    const createdMs = new Date(createdAt).getTime();
+    return Number.isFinite(createdMs) && Date.now() - createdMs < FRESH_ENTRY_GRACE_MS;
+}

package/dist/services/extract-memories.d.ts

@@ -18,17 +18,26 @@ export interface ExtractedMemory {
     description: string;
     content: string;
 }
+export interface ExistingMemorySummary {
+    id?: string;
+    name: string;
+    type: string;
+    description: string;
+    location?: "project" | "global";
+    memoryScope?: "user" | "dream";
+    origin?: "manual" | "auto" | "dream";
+    pinned?: boolean;
+    useCount?: number;
+    updateCount?: number;
+    updatedAt?: string;
+}
 /**
  * Build the prompt for extracting memories from a conversation.
  */
 export declare function buildExtractionPrompt(transcript: Array<{
     role: string;
     content: string;
-}>, existingMemories: Array<{
-    name: string;
-    type: string;
-    description: string;
-}>): string;
+}>, existingMemories: ExistingMemorySummary[]): string;
 /** Max memories to accept from a single extraction pass. Code-side cap that
  *  enforces the same limit the prompt asks for — the model occasionally
  *  ignores prompt rules, but this guarantees the cap. */

package/dist/services/extract-memories.js

@@ -12,7 +12,21 @@ export function buildExtractionPrompt(transcript, existingMemories) {
         .map((m) => `[${m.role}]: ${m.content.slice(0, 3000)}`)
         .join("\n\n");
     const existingList = existingMemories.length > 0
-        ? existingMemories.map((m) => `  - [${m.type}] ${m.name}: ${m.description}`).join("\n")
+        ? existingMemories
+            .map((m) => {
+            const meta = [
+                m.id ? `id:${m.id}` : null,
+                m.location ? `location:${m.location}` : null,
+                m.memoryScope ? `scope:${m.memoryScope}` : null,
+                m.origin ? `origin:${m.origin}` : null,
+                typeof m.useCount === "number" ? `use:${m.useCount}` : null,
+                typeof m.updateCount === "number" ? `updates:${m.updateCount}` : null,
+            ]
+                .filter(Boolean)
+                .join(", ");
+            return `  - [${m.type}] ${m.name}${meta ? ` (${meta})` : ""}: ${m.description}`;
+        })
+            .join("\n")
         : "  (none)";
     return `Analyze the following conversation and extract any information worth remembering for future sessions.
 
@@ -23,7 +37,7 @@ ${existingList}
 ${conversationText.slice(0, 30000)}
 
 ## Instructions
-Identify NEW information that should be saved as persistent memories. Categories (type):
+Identify candidate information that may be saved as persistent memories. The extractor only proposes candidates; code will route automatic candidates into dream memory first, never directly into user memory. Categories (type):
 - **user**: Information about the user's role, preferences, or expertise
 - **feedback**: Guidance about how to approach work (corrections or confirmations)
 - **project**: Non-obvious facts about ongoing work, goals, or decisions
@@ -39,7 +53,10 @@ Rules:
 - Extract AT MOST 2 memories per session. Prefer 0 to a marginal one — most sessions are noise.
 - AT MOST 1 of the extracted memories may be "global". The global layer is injected every session, so keep it tiny and high-value. If two candidates both seem global, keep the single most universal one global and make the other "project".
 - Only extract information that would be useful in FUTURE conversations
-- Do not duplicate existing memories (re-read the "Existing Memories" list above carefully)
+- Do not duplicate existing memories (re-read the "Existing Memories" list above carefully).
+- If an existing auto/dream memory has the same durable topic, reuse that topic in the candidate instead of creating a date-stamped variant; the write decision layer will update the existing id.
+- Manual user memories are read-only curated memories. Do not re-extract the same topic just because the wording or date differs.
+- Avoid dates, version stamps, batch names, and progress-snapshot suffixes in names. Names should be stable topic identifiers, not "today" variants.
 - Do not extract code patterns, file structures, or git history (derivable from code)
 - Do not extract ephemeral task details, progress snapshots, or in-flight work state — those belong in the conversation, not memory
 - Do not extract one-off research products (news reports, AI industry summaries, slide deck content, daily progress dumps) — they're done and not "durable, reusable information"

package/dist/services/global-dream-promotion.d.ts

@@ -0,0 +1,23 @@
+import type { ExtractedMemory } from "./extract-memories.js";
+export interface GlobalDreamPromotionInput {
+    candidate: ExtractedMemory;
+    projectDir?: string;
+    baseDir?: string;
+    userDirectGlobal?: boolean;
+    now?: Date;
+}
+export interface GlobalDreamPromotionResult {
+    /** No automatic write to global dream is performed; approval is required. */
+    promoted: false;
+    /** True when this call created a new pending approval item. */
+    pendingSuggested: boolean;
+    originProjects: string[];
+    evidenceCount: number;
+    projectEvidenceSaved: boolean;
+    promotionReason: string;
+}
+export declare function detectUserDirectGlobalPreference(transcript: Array<{
+    role: string;
+    content: string;
+}>): boolean;
+export declare function applyGlobalDreamPromotionGate(input: GlobalDreamPromotionInput): GlobalDreamPromotionResult;