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

package/dist/session/memory.d.ts

@@ -19,7 +19,16 @@
  * Deletes are SOFT — files are moved to <baseDir>/memory-trash/<ISO>/<scope>/
  * rather than removed, so accidental deletions are recoverable.
  */
-export type MemoryScope = "user" | "dream";
+/**
+ * Memory scopes (storage subdirs under a memory root):
+ *  - user    user-owned; tool writes here are permission-gated
+ *  - dream   the auto-consolidation workspace (LLM free-write)
+ *  - pending 待审批门 (用户拍板): auto-extracted memories the LLM 判为"提全局"
+ *            land here (global root only) and are NOT injected. The user
+ *            approves (→ moves to user/) or rejects (→ trash) in the settings
+ *            panel. Keeps the global layer curated — nothing auto-lands global.
+ */
+export type MemoryScope = "user" | "dream" | "pending";
 export interface MemoryEntry {
     name: string;
     description: string;
@@ -27,7 +36,45 @@ export interface MemoryEntry {
     content: string;
     fileName: string;
     scope: MemoryScope;
+    /** File mtime in epoch ms — drives maxAge filtering (TODO 8.1). 0 if unknown. */
+    updatedAt?: number;
+    /**
+     * 固定/置顶 (feedback#18 方案 A): a pinned memory is exempt from maxAge
+     * injection filtering and sorts first in the injected context. UI surfaces
+     * pin/unpin; auto flows never set it.
+     */
+    pinned?: boolean;
+    /**
+     * Provenance (方案 C): "auto" = written by the end-of-session extractor,
+     * "manual" (or absent — legacy files) = written by the user/UI. Lets the
+     * UI distinguish curated memories from extractor noise.
+     */
+    origin?: "auto" | "manual";
+    /**
+     * Recall lifecycle (召回 TTL). `usageCount` increments each time MemoryRead
+     * hits this entry; `lastUsed` is the ISO timestamp of that last hit; `created`
+     * is set on first save and preserved across UPDATE. Drives recall-based TTL:
+     * a `project`-type memory not read for N days is pruned. Stored in frontmatter
+     * — no SQLite. Legacy files lacking these fields read back as
+     * {usageCount:0, lastUsed/created ← mtime}, never hidden.
+     */
+    usageCount?: number;
+    lastUsed?: string;
+    created?: string;
+    /**
+     * 审批门 (用户拍板): for `pending`-scope entries, the project cwd the memory
+     * was extracted in. On "不批准/降级" the entry falls back to THIS project's
+     * user store (not the current one). Absent → fall back to no-repo / global.
+     */
+    originProject?: string;
 }
+/**
+ * Drop memories older than `maxAgeDays` (by file mtime) for context injection
+ * (TODO 8.1). A non-positive/undefined maxAge means no filtering. Entries with
+ * an unknown mtime (updatedAt 0/undefined) are KEPT — we never hide a memory
+ * just because we couldn't read its timestamp. Pure + testable.
+ */
+export declare function filterByAge(entries: MemoryEntry[], maxAgeDays?: number, now?: number): MemoryEntry[];
 export interface MemoryManagerOptions {
     /** Project root path; when set, memories are scoped under projects/<hash>/memory. */
     projectDir?: string;
@@ -61,12 +108,57 @@ export declare class MemoryManager {
      * Load a single memory file.
      */
     private loadFile;
+    /**
+     * Parse a memory file's frontmatter + body into a MemoryEntry. Shared by both
+     * loadFile (own scope) and loadScope (cross-scope) so the parsing of every
+     * field — including the lifecycle fields — lives in exactly one place.
+     * Returns null on missing file / unparseable frontmatter.
+     */
+    private parseMemoryFile;
     /**
      * Soft-delete a memory by name or filename — moves the file into
      * <baseDir>/memory-trash/<ISO>/<scope>/ instead of unlinking it. The user
      * can recover by moving it back; we never hard-delete from this code path.
      */
     delete(nameOrFile: string): boolean;
+    /**
+     * Record a recall: a MemoryRead hit this entry. Bumps usageCount and sets
+     * lastUsed=now, rewriting only the frontmatter (content untouched). This is
+     * the signal that drives recall-based TTL — a memory that keeps getting read
+     * never ages out. Idempotent-safe: missing entry → false, no throw.
+     */
+    recordRecall(nameOrFile: string, now?: Date): boolean;
+    /**
+     * Recall-based TTL sweep. Soft-deletes `project`-type memories not read for
+     * more than `ttlDays` (by lastUsed). Stable types (user/feedback/reference)
+     * and pinned entries are NEVER pruned — only ephemeral project events age out.
+     * Returns the names pruned. ttlDays<=0 disables the sweep.
+     */
+    pruneByRecall(ttlDays: number, now?: Date): string[];
+    /**
+     * Approve a pending memory: move it from the pending scope into the user scope
+     * of the SAME memory root (pending only ever exists at the global root — the
+     * approval门 only gates global writes). Must be called on a pending-scope
+     * manager. Returns the new user filename, or null if not found / wrong scope.
+     *
+     * 审批门 (用户拍板): the only path that moves an auto-extracted memory into the
+     * curated, injected global user store.
+     */
+    approvePending(nameOrFile: string): string | null;
+    /**
+     * Demote a pending memory: 不批准升全局,但它仍是有用记忆 → 落回它来源项目的
+     * user store (originProject)。无 originProject 时落全局 user(兜底,不丢)。
+     */
+    demotePending(nameOrFile: string): string | null;
+    /** Shared move for approve(→global user)/demote(→origin-project user). */
+    private movePending;
+    /**
+     * Promote a project-level user memory to the GLOBAL user store (用户手动点
+     * "提升到全局")。Must be called on a project-scoped user manager. Copies the
+     * entry into global user/ and soft-deletes the project copy. Returns the new
+     * global filename, or null if not found.
+     */
+    promoteToGlobal(nameOrFile: string): string | null;
     /**
      * Get the MEMORY.md index content for injection into prompts.
      */
@@ -78,7 +170,29 @@ export declare class MemoryManager {
      * tagged with their origin so the model can tell user-owned from
      * dream-generated.
      */
-    buildMemoryContext(): string;
+    buildMemoryContext(opts?: {
+        maxAgeDays?: number;
+        now?: number;
+    }): string;
+    /**
+     * Two-layer injection index (用户拍板). Merges GLOBAL (cross-project
+     * experience) + PROJECT (this repo's facts) memories into a compact index —
+     * one line per entry, name + description only, NO body. The model reads a
+     * specific entry's full content on demand via MemoryRead (which records a
+     * recall → drives TTL + UI visibility).
+     *
+     * This is what fixes "global memory never shows up": global memories are now
+     * injected alongside project ones, every session, regardless of cwd.
+     *
+     * Static because it must construct two managers (global = no projectDir,
+     * project = with projectDir). `projectDir` undefined → only global is shown.
+     */
+    static buildInjectionIndex(opts: {
+        projectDir?: string;
+        baseDir?: string;
+        maxAgeDays?: number;
+        now?: number;
+    }): string;
     /**
      * Load every entry belonging to the given scope, without changing the
      * manager's own scope. Used by buildMemoryContext to merge user + dream

package/dist/session/memory.js

@@ -22,13 +22,32 @@
 import { mkdirSync, existsSync, readFileSync, writeFileSync, readdirSync, renameSync, statSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+/**
+ * Drop memories older than `maxAgeDays` (by file mtime) for context injection
+ * (TODO 8.1). A non-positive/undefined maxAge means no filtering. Entries with
+ * an unknown mtime (updatedAt 0/undefined) are KEPT — we never hide a memory
+ * just because we couldn't read its timestamp. Pure + testable.
+ */
+export function filterByAge(entries, maxAgeDays, now = Date.now()) {
+    if (!maxAgeDays || maxAgeDays <= 0)
+        return entries;
+    const cutoff = now - maxAgeDays * 24 * 60 * 60 * 1000;
+    // Pinned memories never age out of injection — that's the point of the pin.
+    return entries.filter((e) => e.pinned || !e.updatedAt || e.updatedAt >= cutoff);
+}
 export function resolveMemoryBaseDir(override) {
     if (override)
         return override;
     const fromEnv = process.env.CODE_SHELL_HOME;
     if (fromEnv && fromEnv.length > 0)
         return fromEnv;
-    return join(homedir(), ".code-shell");
+    // `process.env.HOME ?? homedir()` (NOT raw homedir()): bun caches homedir()
+    // at process start and never re-reads it, so a test's HOME override — and any
+    // code that relies on $HOME — would be ignored, and memory would read the
+    // REAL ~/.code-shell (leaking global memories into isolated tests). See the
+    // homedir()-cache trap; mirrors settings/manager.ts userHome().
+    const home = process.env.HOME ?? homedir();
+    return join(home, ".code-shell");
 }
 export class MemoryManager {
     baseDir;
@@ -72,10 +91,29 @@ export class MemoryManager {
     save(entry) {
         const fileName = this.slugify(entry.name) + ".md";
         const filePath = join(this.memoryDir, fileName);
+        const nowIso = new Date().toISOString();
+        // Overwrite = UPDATE: preserve the original `created` and accumulated
+        // `usageCount` of the file being replaced (only `created` is load-bearing
+        // for TTL; carrying usageCount avoids resetting a popular memory's score).
+        // explicit entry fields win over the existing file (lets callers force a value).
+        const existing = existsSync(filePath) ? this.loadFile(fileName) : null;
+        const created = entry.created ?? existing?.created ?? nowIso;
+        const usageCount = entry.usageCount ?? existing?.usageCount ?? 0;
+        const lastUsed = entry.lastUsed ?? existing?.lastUsed ?? created;
+        const originProject = entry.originProject ?? existing?.originProject;
+        // pinned/origin are written only when meaningful so legacy-shaped files
+        // stay byte-identical for unpinned manual saves. Lifecycle fields are
+        // always written now (created/lastUsed/usageCount) — they're how TTL works.
         const content = `---\n` +
             `name: ${entry.name}\n` +
             `description: ${entry.description}\n` +
             `type: ${entry.type}\n` +
+            (entry.pinned ? `pinned: true\n` : "") +
+            (entry.origin ? `origin: ${entry.origin}\n` : "") +
+            (originProject ? `originProject: ${originProject}\n` : "") +
+            `created: ${created}\n` +
+            `lastUsed: ${lastUsed}\n` +
+            `usageCount: ${usageCount}\n` +
             `---\n\n` +
             `${entry.content}\n`;
         writeFileSync(filePath, content, "utf-8");
@@ -107,6 +145,17 @@ export class MemoryManager {
      */
     loadFile(fileName) {
         const filePath = join(this.memoryDir, fileName);
+        if (!existsSync(filePath))
+            return null;
+        return this.loadFileFromDir(this.memoryDir, fileName, this.scope);
+    }
+    /**
+     * Parse a memory file's frontmatter + body into a MemoryEntry. Shared by both
+     * loadFile (own scope) and loadScope (cross-scope) so the parsing of every
+     * field — including the lifecycle fields — lives in exactly one place.
+     * Returns null on missing file / unparseable frontmatter.
+     */
+    parseMemoryFile(filePath, fileName, scope) {
         if (!existsSync(filePath))
             return null;
         try {
@@ -119,7 +168,30 @@ export class MemoryManager {
             const name = frontmatter.match(/name:\s*(.+)/)?.[1]?.trim() ?? fileName;
             const description = frontmatter.match(/description:\s*(.+)/)?.[1]?.trim() ?? "";
             const type = (frontmatter.match(/type:\s*(.+)/)?.[1]?.trim() ?? "project");
-            return { name, description, type, content, fileName, scope: this.scope };
+            const pinned = frontmatter.match(/pinned:\s*(.+)/)?.[1]?.trim() === "true";
+            // Anchor with ^…/m so `origin:` doesn't accidentally match the
+            // `originProject:` line (and vice-versa).
+            const originRaw = frontmatter.match(/^origin:\s*(.+)/m)?.[1]?.trim();
+            const origin = originRaw === "auto" || originRaw === "manual" ? originRaw : undefined;
+            const originProject = frontmatter.match(/^originProject:\s*(.+)/m)?.[1]?.trim() || undefined;
+            let updatedAt = 0;
+            try {
+                updatedAt = statSync(filePath).mtimeMs;
+            }
+            catch {
+                // mtime best-effort; 0 = unknown (never filtered out by maxAge).
+            }
+            // Lifecycle fields. Legacy files lack them → fall back to mtime so a TTL
+            // sweep treats them as "last used = file age" rather than "never used".
+            const mtimeIso = updatedAt > 0 ? new Date(updatedAt).toISOString() : undefined;
+            const created = frontmatter.match(/created:\s*(.+)/)?.[1]?.trim() || mtimeIso;
+            const lastUsed = frontmatter.match(/lastUsed:\s*(.+)/)?.[1]?.trim() || created;
+            const usageRaw = frontmatter.match(/usageCount:\s*(\d+)/)?.[1];
+            const usageCount = usageRaw ? parseInt(usageRaw, 10) : 0;
+            return {
+                name, description, type, content, fileName, scope,
+                updatedAt, pinned, origin, usageCount, lastUsed, created, originProject,
+            };
         }
         catch {
             return null;
@@ -149,6 +221,129 @@ export class MemoryManager {
             return false;
         }
     }
+    /**
+     * Record a recall: a MemoryRead hit this entry. Bumps usageCount and sets
+     * lastUsed=now, rewriting only the frontmatter (content untouched). This is
+     * the signal that drives recall-based TTL — a memory that keeps getting read
+     * never ages out. Idempotent-safe: missing entry → false, no throw.
+     */
+    recordRecall(nameOrFile, now = new Date()) {
+        const entry = this.loadAll().find((e) => e.name === nameOrFile || e.fileName === nameOrFile);
+        if (!entry)
+            return false;
+        try {
+            this.save({
+                name: entry.name,
+                description: entry.description,
+                type: entry.type,
+                content: entry.content,
+                pinned: entry.pinned,
+                origin: entry.origin,
+                created: entry.created,
+                usageCount: (entry.usageCount ?? 0) + 1,
+                lastUsed: now.toISOString(),
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Recall-based TTL sweep. Soft-deletes `project`-type memories not read for
+     * more than `ttlDays` (by lastUsed). Stable types (user/feedback/reference)
+     * and pinned entries are NEVER pruned — only ephemeral project events age out.
+     * Returns the names pruned. ttlDays<=0 disables the sweep.
+     */
+    pruneByRecall(ttlDays, now = new Date()) {
+        if (!ttlDays || ttlDays <= 0)
+            return [];
+        const cutoff = now.getTime() - ttlDays * 24 * 60 * 60 * 1000;
+        const pruned = [];
+        for (const e of this.loadAll()) {
+            if (e.type !== "project")
+                continue; // stable types are exempt
+            if (e.pinned)
+                continue; // pinned exempt
+            const lastUsedMs = e.lastUsed ? new Date(e.lastUsed).getTime() : NaN;
+            // Unknown lastUsed (unparseable) → keep, never prune on missing data.
+            if (!Number.isFinite(lastUsedMs))
+                continue;
+            if (lastUsedMs < cutoff) {
+                if (this.delete(e.name))
+                    pruned.push(e.name);
+            }
+        }
+        return pruned;
+    }
+    /**
+     * Approve a pending memory: move it from the pending scope into the user scope
+     * of the SAME memory root (pending only ever exists at the global root — the
+     * approval门 only gates global writes). Must be called on a pending-scope
+     * manager. Returns the new user filename, or null if not found / wrong scope.
+     *
+     * 审批门 (用户拍板): the only path that moves an auto-extracted memory into the
+     * curated, injected global user store.
+     */
+    approvePending(nameOrFile) {
+        return this.movePending(nameOrFile, "global");
+    }
+    /**
+     * Demote a pending memory: 不批准升全局,但它仍是有用记忆 → 落回它来源项目的
+     * user store (originProject)。无 originProject 时落全局 user(兜底,不丢)。
+     */
+    demotePending(nameOrFile) {
+        return this.movePending(nameOrFile, "project");
+    }
+    /** Shared move for approve(→global user)/demote(→origin-project user). */
+    movePending(nameOrFile, dest) {
+        if (this.scope !== "pending")
+            return null;
+        const entry = this.loadAll().find((e) => e.name === nameOrFile || e.fileName === nameOrFile);
+        if (!entry)
+            return null;
+        const targetMgr = dest === "project" && entry.originProject
+            ? new MemoryManager({ baseDir: this.baseDir, projectDir: entry.originProject, scope: "user" })
+            : new MemoryManager({ baseDir: this.baseDir, scope: "user" }); // global, or fallback
+        const fileName = targetMgr.save({
+            name: entry.name,
+            description: entry.description,
+            type: entry.type,
+            content: entry.content,
+            origin: entry.origin ?? "auto",
+            created: entry.created,
+            lastUsed: entry.lastUsed,
+            usageCount: entry.usageCount,
+            // originProject is no longer needed once it has landed in a real store.
+        });
+        this.delete(entry.name); // soft-delete the pending copy
+        return fileName;
+    }
+    /**
+     * Promote a project-level user memory to the GLOBAL user store (用户手动点
+     * "提升到全局")。Must be called on a project-scoped user manager. Copies the
+     * entry into global user/ and soft-deletes the project copy. Returns the new
+     * global filename, or null if not found.
+     */
+    promoteToGlobal(nameOrFile) {
+        const entry = this.loadAll().find((e) => e.name === nameOrFile || e.fileName === nameOrFile);
+        if (!entry)
+            return null;
+        const globalMgr = new MemoryManager({ baseDir: this.baseDir, scope: "user" });
+        const fileName = globalMgr.save({
+            name: entry.name,
+            description: entry.description,
+            type: entry.type,
+            content: entry.content,
+            origin: entry.origin,
+            pinned: entry.pinned,
+            created: entry.created,
+            lastUsed: entry.lastUsed,
+            usageCount: entry.usageCount,
+        });
+        this.delete(entry.name); // remove from the project store
+        return fileName;
+    }
     /**
      * Get the MEMORY.md index content for injection into prompts.
      */
@@ -164,20 +359,20 @@ export class MemoryManager {
      * tagged with their origin so the model can tell user-owned from
      * dream-generated.
      */
-    buildMemoryContext() {
-        const userEntries = this.scope === "user"
-            ? this.loadAll()
-            : this.loadScope("user");
-        const dreamEntries = this.scope === "dream"
-            ? this.loadAll()
-            : this.loadScope("dream");
+    buildMemoryContext(opts) {
+        const userEntries = filterByAge(this.scope === "user" ? this.loadAll() : this.loadScope("user"), opts?.maxAgeDays, opts?.now);
+        const dreamEntries = filterByAge(this.scope === "dream" ? this.loadAll() : this.loadScope("dream"), opts?.maxAgeDays, opts?.now);
         if (userEntries.length === 0 && dreamEntries.length === 0)
             return "";
+        // Pinned memories lead the list so the user's hand-picked context is what
+        // the model reads first (sort is stable — unpinned keep their order).
+        const pinnedFirst = (a, b) => Number(b.pinned ?? false) - Number(a.pinned ?? false);
+        userEntries.sort(pinnedFirst);
         const lines = [];
         if (userEntries.length > 0) {
             lines.push("## User memories (you own these — needs permission to modify)");
             for (const e of userEntries) {
-                lines.push(`- [${e.type}] ${e.name}: ${e.description}`);
+                lines.push(`- ${e.pinned ? "[pinned] " : ""}[${e.type}] ${e.name}: ${e.description}`);
             }
         }
         if (dreamEntries.length > 0) {
@@ -193,6 +388,50 @@ export class MemoryManager {
             lines.join("\n") +
             `\n\nTo read a specific memory, look under ${this.memoryRoot}/{user,dream}/`);
     }
+    /**
+     * Two-layer injection index (用户拍板). Merges GLOBAL (cross-project
+     * experience) + PROJECT (this repo's facts) memories into a compact index —
+     * one line per entry, name + description only, NO body. The model reads a
+     * specific entry's full content on demand via MemoryRead (which records a
+     * recall → drives TTL + UI visibility).
+     *
+     * This is what fixes "global memory never shows up": global memories are now
+     * injected alongside project ones, every session, regardless of cwd.
+     *
+     * Static because it must construct two managers (global = no projectDir,
+     * project = with projectDir). `projectDir` undefined → only global is shown.
+     */
+    static buildInjectionIndex(opts) {
+        const global = new MemoryManager({ baseDir: opts.baseDir });
+        const project = opts.projectDir
+            ? new MemoryManager({ baseDir: opts.baseDir, projectDir: opts.projectDir })
+            : null;
+        const pinnedFirst = (a, b) => Number(b.pinned ?? false) - Number(a.pinned ?? false);
+        const collect = (mm) => filterByAge([...mm.loadScope("user"), ...mm.loadScope("dream")], opts.maxAgeDays, opts.now).sort(pinnedFirst);
+        const globalEntries = collect(global);
+        const projectEntries = project ? collect(project) : [];
+        if (globalEntries.length === 0 && projectEntries.length === 0)
+            return "";
+        const fmt = (e) => `- ${e.pinned ? "[pinned] " : ""}[${e.type}] ${e.name}: ${e.description}`;
+        const lines = [];
+        if (globalEntries.length > 0) {
+            lines.push("## Global memories (apply across all projects)");
+            for (const e of globalEntries)
+                lines.push(fmt(e));
+        }
+        if (projectEntries.length > 0) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push("## Project memories (this repo)");
+            for (const e of projectEntries)
+                lines.push(fmt(e));
+        }
+        return (`# Persistent Memory (index)\n\n` +
+            `These are summaries of memories from previous sessions. Only the summary is shown here.\n` +
+            `When a memory looks relevant to the current task, read its full content with the ` +
+            `MemoryRead tool (scope = user or dream; location = global or project) before relying on it.\n\n` +
+            lines.join("\n"));
+    }
     /**
      * Load every entry belonging to the given scope, without changing the
      * manager's own scope. Used by buildMemoryContext to merge user + dream
@@ -212,24 +451,7 @@ export class MemoryManager {
         return entries;
     }
     loadFileFromDir(dir, fileName, scope) {
-        const filePath = join(dir, fileName);
-        if (!existsSync(filePath))
-            return null;
-        try {
-            const raw = readFileSync(filePath, "utf-8");
-            const frontmatterMatch = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
-            if (!frontmatterMatch)
-                return null;
-            const frontmatter = frontmatterMatch[1];
-            const content = frontmatterMatch[2].trim();
-            const name = frontmatter.match(/name:\s*(.+)/)?.[1]?.trim() ?? fileName;
-            const description = frontmatter.match(/description:\s*(.+)/)?.[1]?.trim() ?? "";
-            const type = (frontmatter.match(/type:\s*(.+)/)?.[1]?.trim() ?? "project");
-            return { name, description, type, content, fileName, scope };
-        }
-        catch {
-            return null;
-        }
+        return this.parseMemoryFile(join(dir, fileName), fileName, scope);
     }
     /**
      * Move pre-scope flat-layout entries (entries that lived directly under

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

@@ -7,6 +7,28 @@ export interface SessionBundle {
     state: SessionState;
     transcript: Transcript;
 }
+/**
+ * Validate a session ID before it is joined into a filesystem path.
+ *
+ * Internally generated IDs use `nanoid(16)` and are trusted by construction.
+ * But every public entry point (`create`'s explicitSessionId, `resume`,
+ * `exists`, `saveState`'s state.sessionId, `fork`'s sourceSessionId) accepts
+ * an ID from an outside caller — protocol clients, ChatSessionManager-driven
+ * cold starts, persisted state files — and join()'s it into `sessionsDir`.
+ * Without this check a value like "../etc/passwd" or "/tmp/x" would let the
+ * caller escape the sessions directory.
+ *
+ * Exported for direct unit testing.
+ */
+export declare function assertSafeSessionId(sessionId: unknown): asserts sessionId is string;
+/**
+ * Resolve the `.code-shell` home dir. `CODE_SHELL_HOME` overrides the default
+ * `~/.code-shell` — mirrors Codex's `CODEX_HOME`. Tests set it to a temp dir
+ * (see bunfig.toml preload) so a `new Engine()` / `new SessionManager()` with
+ * no explicit storageDir doesn't pollute the user's real ~/.code-shell/sessions
+ * with throwaway test sessions (the rm-usage/test-model sidebar junk).
+ */
+export declare function codeShellHome(): string;
 export declare class SessionManager {
     private readonly sessionsDir;
     constructor(storageDir?: string);
@@ -17,13 +39,53 @@ export declare class SessionManager {
      * nanoid. Either way the on-disk directory is materialized and the
      * state.json + transcript.jsonl files are written before return.
      */
-    create(cwd: string, model: string, provider: string, explicitSessionId?: string): SessionBundle;
+    create(cwd: string, model: string, provider: string, explicitSessionId?: string, parentSessionId?: string | null, origin?: import("../types.js").SessionOrigin): SessionBundle;
     /**
      * Whether a session directory exists on disk. Used by ChatSession-driven
      * cold starts to decide between resume vs create-with-explicit-sid
      * without catching SessionError.
      */
     exists(sessionId: string): boolean;
+    /**
+     * Cheap "what cwd is this session bound to?" probe — reads only state.json,
+     * NOT the transcript (unlike resume()). engine.run uses this to recover a
+     * resumed session's project directory when the caller omits options.cwd
+     * (e.g. a desktop host whose sidebar repo selection has drifted to null),
+     * so a project-bound session keeps loading its own agents/settings/memory
+     * instead of falling back to process.cwd(). Returns undefined for an
+     * unknown, malformed, or traversal-shaped id rather than throwing — the
+     * caller treats "no recoverable cwd" the same as "not given".
+     */
+    readCwd(sessionId: string): string | undefined;
+    /**
+     * Cheap "does this session have a persisted goal?" probe — reads only
+     * state.json, NOT the transcript (like readCwd). A persistent goal lives ONLY
+     * in state.activeGoal; it is never appended to the transcript as an event, so
+     * a session rebuilt from disk (e.g. localStorage wiped) can't recover the
+     * goal from its messages. The desktop host calls this on session load to
+     * re-surface the active-goal block + its Cancel button, which would otherwise
+     * be invisible (and thus uncancellable) after a reload of an aborted goal
+     * run. Returns undefined for an unknown / malformed / traversal-shaped id, or
+     * a session with no active goal — never throws.
+     */
+    readActiveGoal(sessionId: string): import("../engine/goal.js").GoalConfig | undefined;
+    /**
+     * Disk-only "wipe this session's persistent goal" — the counterpart to
+     * readActiveGoal. Reads state.json, removes state.activeGoal, and rewrites it
+     * atomically (via saveState). Returns true only if a goal was actually
+     * present (idempotent — clearing a session with no goal is a no-op returning
+     * false). Never throws on an unknown / malformed / traversal-shaped id
+     * (returns false), matching readActiveGoal's tolerance.
+     *
+     * Why it lives here and not only on Engine: a persistent goal can strand a
+     * session whose worker is NOT live (aborted/reloaded) — Engine.clearGoal
+     * needs a resumed in-RAM session and a matching in-flight hook, neither of
+     * which exists once the worker has exited. Hosts (the desktop bridge) call
+     * THIS to clear such a goal off disk without spinning up a full Engine.
+     * Engine.clearGoal also delegates its disk write here so the wipe logic lives
+     * in exactly one place.
+     */
+    clearActiveGoal(sessionId: string): boolean;
     resume(sessionId: string): SessionBundle;
     saveState(state: SessionState): void;
     /**