@evandu/super-pi 0.1.133 → 0.1.135

package/dist/server/index.js

@@ -137,7 +137,10 @@ const paths = {
 const runtime = process.env.SUPER_PI_RUNTIME === "welcome"
     ? new WelcomeRuntime()
     : new PiRpcRuntime(join(dataDir, "pi-sessions"), undefined, { dir: initialAgentDirs, promptDir: agentPromptDir }, { endpoint: taskEndpoint, execEndpoint, todoEndpoint, workflowEndpoint, questionEndpoint, toolsEndpoint, documentsEndpoint, scheduledTaskEndpoint, uploadsDir });
-const broadcaster = new WsBroadcaster(() => store.snapshot());
+// THE CLIENT GETS THE VISIBLE STATE, NOT THE WHOLE STORE. `clientState()` is `snapshot()` minus the
+// workspaces that were taken out of the sidebar - they are still in the store (that is what lets the
+// same folder be added back with its history), but they are not part of the app any more.
+const broadcaster = new WsBroadcaster(() => store.clientState());
 const memory = new ActiveMemory(join(dataDir, "memories"), store, runtime);
 process.env.SUPER_PI_MEMORY_ENDPOINT = `http://${internalHost}:${port}/api/memory/tool`;
 if (runtime instanceof PiRpcRuntime)
@@ -243,7 +246,7 @@ const nameIndexes = new Map();
 runService.setNameIndexes(nameIndexes);
 const conversationService = new ConversationService(store, runtime, subagents, broadcaster, catalogService, runService, extensionUiService, initialAgentDirs);
 conversationService.setMemory(memory);
-const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, initialAgentDirs);
+const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, initialAgentDirs);
 /**
  * The terminal, constructed before `serverContext` because that object carries the two predicates
  * `/api/terminal` answers with.

package/dist/server/knowledge-embedding-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/knowledge-embedding-worker.js

@@ -0,0 +1,27 @@
+import { parentPort } from "node:worker_threads";
+let extractor;
+let loading;
+async function load(request) {
+    if (extractor)
+        return extractor;
+    loading ??= (async () => {
+        const specifier = "@huggingface/transformers";
+        const transformers = await import(specifier);
+        transformers.env.localModelPath = request.modelRoot;
+        transformers.env.allowRemoteModels = false;
+        extractor = await transformers.pipeline("feature-extraction", request.model, { dtype: "q8" });
+        return extractor;
+    })();
+    return loading;
+}
+parentPort?.on("message", async (request) => {
+    try {
+        const run = await load(request);
+        const output = await run(request.texts, { pooling: "cls", normalize: true });
+        const buffer = output.data.buffer;
+        parentPort?.postMessage({ id: request.id, data: output.data, dims: output.dims }, [buffer]);
+    }
+    catch (error) {
+        parentPort?.postMessage({ id: request.id, error: error instanceof Error ? error.message : String(error) });
+    }
+});

package/dist/server/knowledge-vectors.d.ts

@@ -59,8 +59,10 @@ export type VectorDocument = {
  */
 export declare class VectorIndex {
     private readonly directory;
-    private extractor?;
-    private loading?;
+    private worker?;
+    private workerSequence;
+    private workerReady;
+    private workerPending;
     private failure?;
     private cache;
     private pending;
@@ -91,7 +93,7 @@ export declare class VectorIndex {
      * weights turns a failure mode into a file, and makes the feature work on a machine that has never
      * been online since it was installed.
      */
-    private load;
+    private ensureWorker;
     private embed;
     /** Vectors already stored for one workspace, keyed by document then chunk index. */
     private read;

package/dist/server/knowledge-vectors.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { Worker } from "node:worker_threads";
 /**
  * The model, and the only one this feature can use.
  *
@@ -78,8 +79,10 @@ export function cosine(a, b) {
  */
 export class VectorIndex {
     directory;
-    extractor;
-    loading;
+    worker;
+    workerSequence = 0;
+    workerReady = false;
+    workerPending = new Map();
     failure;
     cache = new Map();
     pending = new Set();
@@ -100,7 +103,7 @@ export class VectorIndex {
     enabled() { return process.env.SUPER_PI_KNOWLEDGE_EMBEDDINGS !== "0"; }
     status(indexed) {
         return {
-            enabled: this.enabled(), ready: Boolean(this.extractor), indexed, error: this.failure,
+            enabled: this.enabled(), ready: this.workerReady, indexed, error: this.failure,
             // Whether the shipped weights are on disk, reported before the model is ever loaded: "the
             // package was built without its assets" and "the model failed to load" are different problems.
             bundled: existsSync(this.bundledModel()),
@@ -119,57 +122,56 @@ export class VectorIndex {
      * weights turns a failure mode into a file, and makes the feature work on a machine that has never
      * been online since it was installed.
      */
-    load() {
-        if (this.extractor)
-            return Promise.resolve(this.extractor);
+    ensureWorker() {
+        if (this.worker)
+            return this.worker;
         if (this.failure)
-            return Promise.resolve(undefined);
-        this.loading ??= (async () => {
-            try {
-                if (!existsSync(this.bundledModel()))
-                    throw new Error(`随包分发的模型缺失：${this.bundledModel()}`);
-                // THE SPECIFIER GOES THROUGH A VARIABLE, and that is deliberate. Written as a literal,
-                // `tsc` resolves it while compiling - so a machine whose optional install skipped this package
-                // could not build the server at all, which makes an "optional" dependency mandatory in the
-                // only sense that matters to a person who installed it. Node resolves the variable at RUN time
-                // instead, where its absence is already handled: the throw below is the same branch that
-                // handles a missing model.
-                const specifier = "@huggingface/transformers";
-                const { pipeline, env } = await import(specifier);
-                // The library resolves `<localModelPath>/<model id>/onnx/...`, which is why the vendored tree
-                // keeps the `Xenova/bge-small-zh-v1.5` directory rather than being flattened.
-                env.localModelPath = this.bundledModel();
-                env.allowRemoteModels = false;
-                this.extractor = await pipeline("feature-extraction", KNOWLEDGE_MODEL, { dtype: "q8" });
-                return this.extractor;
-            }
-            catch (error) {
-                this.failure = error instanceof Error ? error.message : String(error);
-                console.warn(`Super Pi: 语义检索不可用，将只用关键词检索：${this.failure}`);
-                return undefined;
-            }
-            finally {
-                this.loading = undefined;
+            return undefined;
+        if (!existsSync(this.bundledModel())) {
+            this.failure = `随包分发的模型缺失：${this.bundledModel()}`;
+            return undefined;
+        }
+        const worker = new Worker(new URL("./knowledge-embedding-worker.js", import.meta.url));
+        worker.unref();
+        worker.on("message", (message) => {
+            const pending = this.workerPending.get(message.id);
+            if (!pending)
+                return;
+            this.workerPending.delete(message.id);
+            if (message.error || !message.data || !message.dims) {
+                this.failure = message.error ?? "向量 worker 返回了无效结果";
+                pending.resolve(null);
+                return;
             }
-        })();
-        return this.loading;
+            this.workerReady = true;
+            const dimension = message.dims.at(-1) ?? 0;
+            pending.resolve(Array.from({ length: message.dims[0] ?? 0 }, (_, row) => Array.from(message.data.slice(row * dimension, (row + 1) * dimension))));
+        });
+        const fail = (error) => {
+            this.failure = error.message;
+            for (const pending of this.workerPending.values())
+                pending.resolve(null);
+            this.workerPending.clear();
+            this.worker = undefined;
+            this.workerReady = false;
+        };
+        worker.on("error", fail);
+        worker.on("exit", (code) => { if (code !== 0)
+            fail(new Error(`向量 worker 异常退出（${code}）`)); });
+        this.worker = worker;
+        return worker;
     }
     async embed(texts) {
         if (!texts.length || !this.enabled())
             return null;
-        const extractor = await this.load();
-        if (!extractor)
+        const worker = this.ensureWorker();
+        if (!worker)
             return null;
-        try {
-            const output = await extractor(texts, { pooling: "cls", normalize: true });
-            const dimension = output.dims[output.dims.length - 1];
-            return Array.from({ length: output.dims[0] }, (_, row) => Array.from(output.data.slice(row * dimension, (row + 1) * dimension)));
-        }
-        catch (error) {
-            this.failure = error instanceof Error ? error.message : String(error);
-            console.warn(`Super Pi: 生成向量失败，将只用关键词检索：${this.failure}`);
-            return null;
-        }
+        const id = ++this.workerSequence;
+        return new Promise((resolvePromise) => {
+            this.workerPending.set(id, { resolve: resolvePromise });
+            worker.postMessage({ id, texts, modelRoot: this.bundledModel(), model: KNOWLEDGE_MODEL });
+        });
     }
     /** Vectors already stored for one workspace, keyed by document then chunk index. */
     async read(workspaceId, documentId) {

package/dist/server/knowledge.d.ts

@@ -125,6 +125,7 @@ export declare class KnowledgeBase {
     private indexes;
     private serial;
     constructor(directory: string, store: Store, runtime?: KnowledgeRuntime | undefined, vectors?: VectorIndex | undefined);
+    private hasWorkspace;
     /** `SUPER_PI_KNOWLEDGE_ENABLED=0` turns the whole feature off, the same way memory turns off. */
     enabled(): boolean;
     /** The opaque workspace identity on disk, encoded. Paths never come from the model or the request. */

package/dist/server/knowledge.js

@@ -253,13 +253,17 @@ export class KnowledgeBase {
         this.runtime = runtime;
         this.vectors = vectors;
     }
+    hasWorkspace(workspaceId) {
+        const store = this.store;
+        return store.hasWorkspace ? store.hasWorkspace(workspaceId) : store.snapshot().workspaces.some(workspace => workspace.id === workspaceId);
+    }
     /** `SUPER_PI_KNOWLEDGE_ENABLED=0` turns the whole feature off, the same way memory turns off. */
     enabled() { return process.env.SUPER_PI_KNOWLEDGE_ENABLED !== "0"; }
     /** The opaque workspace identity on disk, encoded. Paths never come from the model or the request. */
     folder(workspaceId) { return join(this.directory, Buffer.from(workspaceId).toString("hex")); }
     file(workspaceId, documentId) { return join(this.folder(workspaceId), `${documentId}.json`); }
     requireWorkspace(workspaceId) {
-        if (!this.store.snapshot().workspaces.some(workspace => workspace.id === workspaceId))
+        if (!this.hasWorkspace(workspaceId))
             throw new Error("工作区不存在");
     }
     async locked(work) {
@@ -710,7 +714,7 @@ export class KnowledgeBase {
         const identity = this.capabilities.get(token);
         // The workspace is re-checked against the store, so a token minted before a workspace was deleted
         // cannot keep serving its documents afterwards.
-        if (!identity || !this.store.snapshot().workspaces.some(workspace => workspace.id === identity.workspaceId))
+        if (!identity || !this.hasWorkspace(identity.workspaceId))
             throw new Error("知识库授权已失效");
         return identity;
     }

package/dist/server/persistence/sqlite-state-repository.d.ts

@@ -1,6 +1,5 @@
 import type { AppState } from "../types.js";
 import type { AppStateRepository, StateTransaction } from "./app-state-repository.js";
-/** SQLite snapshot adapter with row-level writes for streamed messages and runs. */
 export declare class SqliteStateRepository implements AppStateRepository {
     private readonly db;
     constructor(path: string);

package/dist/server/persistence/sqlite-state-repository.js

@@ -1,5 +1,24 @@
 import { DatabaseSync } from "node:sqlite";
 /** SQLite snapshot adapter with row-level writes for streamed messages and runs. */
+/**
+ * THE ROW THAT SAYS "THIS CONVERSATION'S ARRAY IS EMPTY".
+ *
+ * A missing row in `message_order` used to mean two different things: "this conversation was never
+ * written incrementally" AND "this conversation's array was emptied". The loader could only read the
+ * first one, so a conversation whose LAST message was withdrawn fell back to the base snapshot - and
+ * the withdrawn message came back, carrying `delivery: "waiting"`, to be handed to the model by the
+ * next turn. A withdrawal is the last act of "take back what I have not sent yet", and it did not
+ * survive a restart (ledger TEST-041).
+ *
+ * A sentinel row says the difference. It is marked by a NEGATIVE POSITION - a real message's
+ * position is never negative - so it is never mistaken for one, and the loader reads it as "empty"
+ * rather than as "not written". (The marker is the position and NOT the id on purpose: a NUL in the
+ * id would be truncated by SQLite's TEXT handling, and the row would stop being recognisable.)
+ */
+const EMPTY_ARRAY_POSITION = -1;
+/** The id that goes with the sentinel row. It never becomes a message: the loader drops every row
+ *  whose position is negative, and this row's position IS negative. */
+const EMPTY_ARRAY_SENTINEL_ID = "empty-array";
 export class SqliteStateRepository {
     db;
     constructor(path) {
@@ -58,7 +77,12 @@ export class SqliteStateRepository {
             // was last rewritten - the placeholder an assistant message was born with, not what it streamed.
             const ordered = this.db.prepare("SELECT id,position,json FROM message_order WHERE conversation=? ORDER BY position").all(conversation.id);
             if (ordered.length) {
-                conversation.messages = ordered.map((row) => overrides.get(String(row.id)) ?? JSON.parse(String(row.json)));
+                // Rows EXIST, so this conversation was written incrementally and these rows are authoritative -
+                // including the sentinel, which says the array is empty. The sentinel is not a message and
+                // never becomes one.
+                conversation.messages = ordered
+                    .filter((row) => Number(row.position) >= 0)
+                    .map((row) => overrides.get(String(row.id)) ?? JSON.parse(String(row.json)));
             }
             else {
                 if (!Array.isArray(conversation.messages))
@@ -163,6 +187,12 @@ export class SqliteStateRepository {
                         upsertMessage.run(conversationId, message.id, json);
                         insertOrdered.run(conversationId, message.id, position, json);
                     });
+                    // An EMPTY ARRAY MUST BE WRITTEN DOWN, or "no rows" will read as "never written" and the
+                    // loader will fall back to the base snapshot - which still holds the message the person
+                    // just withdrew (ledger TEST-041).
+                    if (transaction.messages.length === 0) {
+                        insertOrdered.run(conversationId, EMPTY_ARRAY_SENTINEL_ID, EMPTY_ARRAY_POSITION, "[]");
+                    }
                 }
                 else {
                     const nextIds = new Set(transaction.messages.map((message) => message.id));
@@ -185,6 +215,12 @@ export class SqliteStateRepository {
                         if (positions.get(message.id) !== position)
                             upsertOrder.run(conversationId, message.id, position, json);
                     });
+                    // The LAST MESSAGE GONE leaves the order table with no rows, and no rows read as "never
+                    // written" - so the loader would fall back to the base snapshot and hand the withdrawn
+                    // message back to the model. The sentinel says the array is empty (ledger TEST-041).
+                    if (transaction.messages.length === 0) {
+                        upsertOrder.run(conversationId, EMPTY_ARRAY_SENTINEL_ID, EMPTY_ARRAY_POSITION, "[]");
+                    }
                 }
                 // The stamp is WRITTEN, not cleared. Opening a turn moves `updatedAt`, and this is the only write
                 // that can record it; clearing the overlay instead would leave the reopened conversation reporting

package/dist/server/providers.d.ts

@@ -284,3 +284,16 @@ export declare function fetchRemoteModels(input: {
     apiKey?: string;
     api?: string;
 }): Promise<DiscoveredModel[]>;
+/**
+ * THE ANSWER, READ.
+ *
+ * Split out of `fetchRemoteModels` so that the part worth asserting - what a provider's answer MEANS -
+ * can be tested without a network in between. A remote provider answers in three shapes (a bare array,
+ * `{data: [...]}` for OpenAI, `{models: [...]}` for Ollama), and each entry names itself with `id`,
+ * `name` or `model`; what the panel shows next to it - whether the model reasons, whether it takes
+ * images - is inferred from the name, because that is all most providers tell us.
+ *
+ * `fetchRemoteModels` is the transport; this is the reading. Keeping them apart means the reading can
+ * be pinned exactly, and a slow machine can never turn a parsing question into a timeout.
+ */
+export declare function parseRemoteModels(payload: unknown): DiscoveredModel[];

package/dist/server/providers.js

@@ -741,6 +741,7 @@ export async function fetchRemoteModels(input) {
         candidates.push(`${cleanBase}/v1/models`, `${cleanBase}/models`);
     }
     let lastError = "";
+    let lastCause;
     let payload = null;
     for (const candidate of candidates) {
         try {
@@ -758,11 +759,35 @@ export async function fetchRemoteModels(input) {
         }
         catch (error) {
             lastError = error instanceof Error ? error.message : String(error);
+            lastCause = error;
         }
     }
     if (!payload) {
-        throw new Error(`无法从远程服务获取模型列表 (${lastError || "请求超时或无法连接"})`);
-    }
+        // THE CAUSE, NOT JUST "fetch failed". `fetch` reports every transport-level problem - a refused
+        // connection, a reset, an aborted timeout - as the same one-word "fetch failed", so a user staring
+        // at 「无法从远程服务获取模型列表 (fetch failed)」 learns nothing and neither does the log. The
+        // cause is where the truth is: "The operation was aborted due to timeout" and "connect
+        // ECONNREFUSED" are two different problems with two different fixes.
+        const cause = lastCause instanceof Error
+            ? (lastCause.cause instanceof Error ? lastCause.cause.message : lastCause.cause instanceof Object && lastCause.cause !== null ? String(lastCause.cause.code ?? "") : undefined)
+            : undefined;
+        throw new Error(`无法从远程服务获取模型列表 (${lastError || "请求超时或无法连接"}${cause ? `：${cause}` : ""})`);
+    }
+    return parseRemoteModels(payload);
+}
+/**
+ * THE ANSWER, READ.
+ *
+ * Split out of `fetchRemoteModels` so that the part worth asserting - what a provider's answer MEANS -
+ * can be tested without a network in between. A remote provider answers in three shapes (a bare array,
+ * `{data: [...]}` for OpenAI, `{models: [...]}` for Ollama), and each entry names itself with `id`,
+ * `name` or `model`; what the panel shows next to it - whether the model reasons, whether it takes
+ * images - is inferred from the name, because that is all most providers tell us.
+ *
+ * `fetchRemoteModels` is the transport; this is the reading. Keeping them apart means the reading can
+ * be pinned exactly, and a slow machine can never turn a parsing question into a timeout.
+ */
+export function parseRemoteModels(payload) {
     const rawList = Array.isArray(payload)
         ? payload
         : Array.isArray(payload.data)

package/dist/server/runtime.js

@@ -941,7 +941,46 @@ export class PiRpcRuntime {
                 const promptOptions = images?.length
                     ? { images: images, preflightResult: () => traceLatency(conversation.id, "session.prompt.accepted", latencyStartedAt, promptSize()) }
                     : { preflightResult: () => traceLatency(conversation.id, "session.prompt.accepted", latencyStartedAt, promptSize()) };
+                // A STOP THAT ARRIVED WHILE THIS SESSION WAS BEING BUILT MUST NOT SEND THE PROMPT.
+                //
+                // The window between "the person pressed stop" and "the prompt goes out" is the whole session
+                // build: Pi's resource loader, the extensions, the transcript, the model lookup - seconds, on a
+                // cold session. The abort listener above already noticed the cancellation, but `session.abort()`
+                // on a session that has not started running is a no-op, so nothing stopped the prompt that was
+                // about to be sent: the model was asked a question the person had already cancelled, and it
+                // answered it - which is why pressing stop looked like it "took effect" only once the reply was
+                // over.
+                //
+                // So the cancellation is checked HERE, at the last moment before the prompt goes out, and a
+                // cancelled turn ends with no question asked at all.
+                //
+                // `turnController.signal.aborted` is the OTHER half of the same fact: the turn's own controller
+                // is what `abortTurn()` trips, and it is tripped by the very same cancellation. Both are checked
+                // because they are tripped by different readers - one by the person, one by Pi's abort.
+                if (signal.aborted || turnController.signal.aborted) {
+                    queue.push({ kind: "end" });
+                    return;
+                }
                 await session.prompt(prompt, promptOptions);
+                // THE CANCELLATION MAY HAVE ARRIVED WHILE PI WAS PREPARING THE PROMPT.
+                //
+                // `session.prompt()` is not one step: it runs Pi's input handlers (the extensions' hooks -
+                // Super Pi's own memory search is one of them), the compaction check and the auth check before
+                // the agent's run starts. An abort that lands in that window finds a session that has NOT
+                // started running, so Pi's abort has nothing to abort - and the prompt goes on to the model,
+                // which answers a question the person cancelled.
+                //
+                // The run IS started by the time `prompt()` resolves, so the abort is said AGAIN here. The
+                // second one is the one that lands.
+                if (signal.aborted) {
+                    // The same 5s backstop `runtime.stop` uses: a wedged session must not hang the turn forever.
+                    await Promise.race([
+                        session.abort().catch((error) => {
+                            console.warn(`PiRpcRuntime: aborting the session of ${conversation.id} after a late cancellation threw: ${error instanceof Error ? error.message : "unknown error"}`);
+                        }),
+                        new Promise((resolvePromise) => setTimeout(resolvePromise, 5_000)),
+                    ]);
+                }
                 // `prompt()` RETURNING IS NOT THE TURN ENDING. Pi's `prompt` resolves when the message has
                 // been ACCEPTED and the run has been started; the agent is still streaming, still executing
                 // tools, still settling. A turn that ended here would release the reader while the model was
@@ -1437,6 +1476,13 @@ export class PiRpcRuntime {
             const imagePayloads = this.options.uploadsDir && images?.length
                 ? await loadConversationImages(this.options.uploadsDir, conversation.id, images)
                 : undefined;
+            // A STOP THAT ARRIVED WHILE THE CHILD WAS STARTING MUST NOT SEND THE PROMPT.
+            //
+            // The same gap the session path has, and the same reason: `abort` above writes an `abort`
+            // command to a child that has not been given anything yet, so it does nothing - and the prompt
+            // went out anyway, and the model answered a question the person had already cancelled.
+            if (signal.aborted)
+                return;
             channel.write({ id: "prompt", type: "prompt", message: prompt, ...(imagePayloads?.length ? { images: imagePayloads } : {}) });
             traceLatency(conversation.id, "prompt.sent", latencyStartedAt);
             let settled = false;

package/dist/server/store.d.ts

@@ -11,6 +11,16 @@ import type { AppState, Conversation, Message, MessageDelivery, MessageImage, Mo
  *  disk, or a failed write would leave a conversation whose model context is silently empty. The runtime is
  *  therefore handed the id and the store is handed the same one back. See `ForkRequest.forkedConversationId`. */
 export declare function newConversationId(): string;
+/**
+ * ONE FOLDER, ONE KEY.
+ *
+ * The same directory reaches the app spelled several ways - `F:\code\app` and `F:/code/app/` and
+ * `f:\code\app` are one folder - and two workspaces for one folder are one project split in half.
+ * The key folds the separators and the trailing slash away, and folds case away only where the
+ * filesystem folds it too: Windows and macOS treat `F:\Code` and `f:\code` as one directory, Linux
+ * does not, and pretending otherwise would merge two real projects into one.
+ */
+export declare function workspacePathKey(path: string): string;
 /**
  * How many SETTLED sub-agent runs `state.json` keeps, so the file cannot grow without bound.
  *
@@ -101,6 +111,15 @@ export declare class Store {
     setDefaultModel(model?: ModelSelection): Promise<void>;
     setTerminalShell(shell?: import("./types.js").TerminalShell): Promise<void>;
     snapshot(): AppState;
+    /** Cheap scalar/entity reads for hot paths. Never expose the live mutable state object. */
+    hasWorkspace(workspaceId: string): boolean;
+    conversationStatus(conversationId: string): Conversation["status"] | undefined;
+    question(conversationId: string, messageId: string, index: number): ToolCallQuestion | undefined;
+    pendingQuestion(conversationId: string): {
+        messageId: string;
+        index: number;
+        question: ToolCallQuestion;
+    } | undefined;
     /**
      * Whether a conversation already holds a message with this id.
      *
@@ -126,6 +145,17 @@ export declare class Store {
         conversation: Conversation;
         workspace: Workspace;
     } | undefined;
+    /**
+     * THE PHYSICAL DIRECTORY IS THE WORKSPACE'S IDENTITY.
+     *
+     * A workspace is a folder, not a row in a table: two workspaces pointing at the same directory are
+     * the same project, and the app used to mint a fresh UUID for each one. That is what broke
+     * re-adding a workspace - the new id matched none of the conversations that belonged to that
+     * directory, so the history was unreachable (and, before the soft unmount, actually deleted).
+     *
+     * So the same folder always means the same workspace id, and the id is what the conversations
+     * point at.
+     */
     createWorkspace(name: string, path?: string): Promise<Workspace>;
     renameWorkspace(workspaceId: string, name: string): Promise<Workspace>;
     /**
@@ -151,7 +181,38 @@ export declare class Store {
         thinkingLevel?: string;
         agentId?: string | null;
     }): Promise<Workspace>;
+    /**
+     * TAKES A WORKSPACE OUT OF THE SIDEBAR. IT DOES NOT DELETE ANYTHING.
+     *
+     * This used to cascade: the workspace row AND every conversation that pointed at it were erased
+     * from the state, in one persist. That made the most natural thing a user could do - remove a
+     * workspace to tidy the sidebar, then add the same folder back - silently destroy the history of
+     * that project, and there was no way to get it back.
+     *
+     * So the removal is a SOFT UNMOUNT, the same shape as a session's archive: the workspace row
+     * stays (with `closedAt` on it), the conversations stay, the uploads stay, and nothing is
+     * broadcast for either (see `clientState`). Adding the same folder again re-opens the very same
+     * workspace - same id, same conversations - which is the whole point of the physical path being
+     * the workspace's identity.
+     *
+     * The returned list is the conversations that were STOPPED, not deleted: a turn that was still
+     * running under a workspace that just left the sidebar cannot keep burning a model session
+     * behind the user's back, and a pending question would otherwise wait for an answer that the
+     * sidebar can no longer reach.
+     */
     deleteWorkspace(workspaceId: string): Promise<string[]>;
+    /**
+     * THE STATE THE CLIENT IS ALLOWED TO SEE.
+     *
+     * `snapshot()` is the truth of what the store HOLDS; this is the truth of what is ON SCREEN. The
+     * difference is the closed workspaces: one that was removed from the sidebar is still in the store
+     * - that is exactly why re-adding the folder brings its history back - but it is not part of the
+     * app any more, so neither it nor its conversations are broadcast.
+     *
+     * Filtering HERE, in one place, rather than in every reader, is what keeps the client dumb: the
+     * sidebar renders `state.workspaces` and never has to know that a closed workspace exists.
+     */
+    clientState(): AppState;
     createConversation(workspaceId: string, configuration?: {
         agentId?: string;
         model?: ModelSelection | null;