@cjhyy/code-shell-core 0.6.0-rc.8 → 0.7.0-beta.1

package/dist/runtime/background-shell.js

@@ -23,16 +23,16 @@
  * 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 { mkdirSync, writeFileSync, rmSync, existsSync, readdirSync, readFileSync } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
 import { utf8SafeCutLength } from "./utf8-cut.js";
-import { resolveSpawnTarget, buildSandboxEnv, mergeShellEnv, killProcessGroup, groupAlive, defaultShellBinary } from "./spawn-common.js";
+import { resolveSpawnTarget, buildSandboxEnv, mergeShellEnv, killProcessGroup, groupAlive, defaultShellBinary, } from "./spawn-common.js";
 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). */
@@ -46,11 +46,10 @@ function nextShellId() {
     // Short, collision-resistant enough within a process: counter + base36 of
     // a monotonic-ish value. Avoids Date.now()/Math.random() (banned in some
     // contexts and unnecessary here).
-    return `bg_${shellCounter.toString(36)}${(shellCounter * 2654435761 % 0xffffff).toString(36)}`;
+    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,
@@ -78,7 +77,11 @@ export class BackgroundShellManager {
         // the bg-shells root — refuse rather than trust the caller. Mirrors
         // SessionManager.assertSafeSessionId without importing across the layer.
         const sid = opts.sessionId;
-        if (typeof sid !== "string" || sid.length === 0 || sid.includes("..") || sid.includes("/") || sid.includes("\\")) {
+        if (typeof sid !== "string" ||
+            sid.length === 0 ||
+            sid.includes("..") ||
+            sid.includes("/") ||
+            sid.includes("\\")) {
             return { ok: false, error: `invalid sessionId for background shell` };
         }
         // Per-session soft cap (fork-bomb guard, §7).
@@ -220,9 +223,7 @@ export class BackgroundShellManager {
     }
     enqueueExitNotification(sh) {
         const ok = sh.exitCode === 0;
-        const exitDesc = sh.signal
-            ? `signal ${sh.signal}`
-            : `exit ${sh.exitCode ?? "?"}`;
+        const exitDesc = sh.signal ? `signal ${sh.signal}` : `exit ${sh.exitCode ?? "?"}`;
         notificationQueue.enqueue({
             agentId: sh.shellId,
             // English description is the agent-facing wakeup text. The UI ignores
@@ -234,7 +235,9 @@ export class BackgroundShellManager {
             status: ok ? "completed" : "failed",
             workKind: "shell",
             command: sh.command,
-            error: ok ? undefined : `Background shell ${sh.shellId} exited with ${exitDesc}. Use BashOutput("${sh.shellId}") to inspect.`,
+            error: ok
+                ? undefined
+                : `Background shell ${sh.shellId} exited with ${exitDesc}. Use BashOutput("${sh.shellId}") to inspect.`,
             enqueuedAt: Date.now(),
         }, sh.sessionId);
     }
@@ -267,6 +270,9 @@ export class BackgroundShellManager {
             .filter((s) => s.sessionId === sessionId)
             .map((s) => this.toPublic(s));
     }
+    list() {
+        return [...this.shells.values()].map((s) => this.toPublic(s));
+    }
     /**
      * Read a shell's output. `mode=incremental` (default) returns text since the
      * agent's last read; `mode=all` returns the full retained buffer. Output is
@@ -420,7 +426,9 @@ export class BackgroundShellManager {
                     try {
                         rmSync(path, { force: true });
                     }
-                    catch { /* ignore */ }
+                    catch {
+                        /* ignore */
+                    }
                     continue;
                 }
                 // Skip ones we already track in-process (this worker's own).
@@ -434,7 +442,9 @@ export class BackgroundShellManager {
                     try {
                         rmSync(path, { force: true });
                     }
-                    catch { /* ignore */ }
+                    catch {
+                        /* ignore */
+                    }
                 }
             }
         }

package/dist/runtime/safe-spawn.js

@@ -35,7 +35,7 @@
  */
 import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
-import { resolveSpawnTarget, defaultShellBinary, killChildTree } from "./spawn-common.js";
+import { resolveSpawnTarget, defaultShellBinary, killChildTree, killProcessGroup } from "./spawn-common.js";
 export const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
 export const DEFAULT_IO_DRAIN_GRACE_MS = 100;
 const TIMEOUT_SIGKILL_GRACE_MS = 2000;
@@ -71,9 +71,21 @@ export function safeSpawnShell(command, opts) {
         shell,
         sandbox: opts.sandbox,
     });
-    return runLifecycle({ file, args, opts, cleanup, resolveMs: elapsedMs(resolveStartedAt) });
+    // Shell commands run free-form LLM strings that routinely background
+    // grandchildren (`pytest &`, `sh → npm → node`). Spawn as a process-group
+    // leader (detached) so a timeout/abort kill reaches the WHOLE subtree, not
+    // just the direct shell — otherwise an orphaned grandchild keeps the
+    // inherited stdout pipe open and Node's `close` never fires (the hang).
+    return runLifecycle({
+        file,
+        args,
+        opts,
+        cleanup,
+        resolveMs: elapsedMs(resolveStartedAt),
+        detached: true,
+    });
 }
-function runLifecycle({ file, args, opts, cleanup, resolveMs }) {
+function runLifecycle({ file, args, opts, cleanup, resolveMs, detached }) {
     const maxBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
     const abortGrace = opts.ioDrainGraceMs ?? DEFAULT_IO_DRAIN_GRACE_MS;
     const lifecycleStartedAt = spawnProfileEnabled() ? performance.now() : 0;
@@ -84,10 +96,19 @@ function runLifecycle({ file, args, opts, cleanup, resolveMs }) {
     }
     return new Promise((resolve) => {
         let settled = false;
+        // Declared before finish() so the spawn-failed early-return (which calls
+        // finish before these are assigned) doesn't hit a TDZ reference.
+        let timer;
+        let settleTimer;
+        let onAbort;
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (settleTimer)
+                clearTimeout(settleTimer);
             logSpawnProfile(file, args, resolveMs, elapsedMs(lifecycleStartedAt), result.reason);
             // Always release backend-allocated resources, regardless of exit path.
             // cleanup is best-effort — see seatbelt backend for rationale.
@@ -101,7 +122,7 @@ function runLifecycle({ file, args, opts, cleanup, resolveMs }) {
         };
         let child;
         try {
-            child = spawn(file, args, { cwd: opts.cwd, env: opts.env });
+            child = spawn(file, args, { cwd: opts.cwd, env: opts.env, detached });
         }
         catch (err) {
             finish(emptyResult({ reason: "spawn_failed", spawnFailed: true, error: err.message }));
@@ -115,21 +136,63 @@ function runLifecycle({ file, args, opts, cleanup, resolveMs }) {
         let stderrTruncated = false;
         let timedOut = false;
         let aborted = false;
-        const timer = setTimeout(() => {
+        let lastExitCode = null;
+        let lastExitSignal = null;
+        // Terminate the child on timeout/abort. When detached (shell mode) the
+        // child leads its own process group, so kill the WHOLE group — this reaps
+        // backgrounded grandchildren (`pytest &`, `sh → npm → node`) that a bare
+        // child.kill() would orphan. After the kill, arm a settle deadline:
+        // Node's `close` waits for every inherited stdio pipe to close, and an
+        // orphaned grandchild can hold stdout open forever, so `close` may never
+        // fire. Force a resolve via the last-seen `exit` code once the kill grace
+        // has elapsed — the promise must never hang past terminate().
+        const terminate = (graceMs) => {
+            if (detached && typeof child.pid === "number") {
+                void killProcessGroup(child.pid, { graceMs });
+            }
+            else {
+                killChildTree(child, graceMs);
+            }
+            if (settleTimer)
+                return;
+            settleTimer = setTimeout(() => {
+                finishFromExit();
+            }, graceMs + 500);
+            settleTimer.unref?.();
+        };
+        timer = setTimeout(() => {
             timedOut = true;
-            // win32: taskkill /T reaps the whole tree (a foreground `npm test`
-            // spawns node children that child.kill() alone would orphan). POSIX:
-            // SIGTERM → grace → SIGKILL. See killChildTree.
-            killChildTree(child, TIMEOUT_SIGKILL_GRACE_MS);
+            terminate(TIMEOUT_SIGKILL_GRACE_MS);
         }, opts.timeoutMs);
-        let onAbort;
         if (opts.signal) {
             onAbort = () => {
                 aborted = true;
-                killChildTree(child, abortGrace);
+                terminate(abortGrace);
             };
             opts.signal.addEventListener("abort", onAbort, { once: true });
         }
+        // Fallback finish when `close` never arrives because a killed process's
+        // orphaned grandchild still holds a stdio pipe. Uses whatever `exit` code
+        // we saw (exit fires when the direct child dies, independent of stdio).
+        const finishFromExit = () => {
+            const reason = timedOut ? "timeout" : aborted ? "aborted" : "ok";
+            finish({
+                reason,
+                stdout,
+                stderr,
+                exitCode: lastExitCode,
+                signal: lastExitSignal,
+                stdoutTruncated,
+                stderrTruncated,
+                timedOut,
+                aborted,
+                spawnFailed: false,
+            });
+        };
+        child.on("exit", (code, sig) => {
+            lastExitCode = code;
+            lastExitSignal = sig;
+        });
         child.stdout?.on("data", (chunk) => {
             if (stdoutTruncated)
                 return;

package/dist/runtime/spawn-common.js

@@ -159,6 +159,13 @@ export function resolveGitBash() {
     const override = process.env.CODE_SHELL_GIT_BASH_PATH;
     if (override && existsSync(override))
         return (gitBashCache = override);
+    // Test-only hermetic switch: skip auto-discovery entirely. Clearing PATH is
+    // NOT enough on Windows — CreateProcess always searches System32, so `where`
+    // still spawns and a CI runner's preinstalled Git for Windows would resolve a
+    // real bash.exe and defeat the fallback tests. This env flag makes the
+    // "Git Bash absent" scenario reproducible on a real Windows host.
+    if (process.env.CODE_SHELL_NO_SHELL_DISCOVERY)
+        return (gitBashCache = null) ?? undefined;
     const candidates = [];
     // (2) derive from `where git`. Git installs git.exe under either \cmd\ or
     // \bin\; bash.exe lives under the sibling \bin\. Walk up to the Git root.
@@ -194,6 +201,9 @@ export function resolvePowerShell() {
     const override = process.env.CODE_SHELL_POWERSHELL_PATH;
     if (override && existsSync(override))
         return (powerShellCache = override);
+    // Test-only hermetic switch (see resolveGitBash for why PATH-clearing fails).
+    if (process.env.CODE_SHELL_NO_SHELL_DISCOVERY)
+        return (powerShellCache = null) ?? undefined;
     const candidates = [];
     for (const exe of ["pwsh", "powershell"]) {
         try {

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;