@celestea/studio 2.7.1

package/dist/store/sessions.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Session listing / creation / transcript reader (`src/workspaces.rs:1092-1221,1459-1501`).
+ *
+ * A "session" is a directory holding `cli-main.jsonl`. The id is
+ * `<workspace-basename>/<dir>`; the `worker:<sid>` space is served by the engine
+ * (RuntimeAdapter) instead.
+ *
+ * W880: NEW sessions land in `<CELESTEA_HOME>/workspaces/<ws>/sessions/<dir>`
+ * (outside the workspace). `resolve()`/`list()` still read the two legacy
+ * layouts (slice-A `<ws>/.celestea/sessions/`, then `<ws>/`) with the canonical
+ * container winning. W791: the ARCHIVED sessions (canonical
+ * `<home>/.../archive/<dir>`, legacy `<ws>/.celestea-archived/<dir>`, see
+ * `session-ops.ts`) are a second source of the same row shape — `listArchived()`
+ * — because `list()` skips dot-directories by design.
+ *
+ * The transcript endpoint is a pure projection of the append-only log
+ * (`projectMessages` from `@celestea/session`), stopping at the first
+ * unparsable line so a torn tail is dropped rather than reported.
+ */
+import type { StudioMessage } from "@celestea/core";
+import type { SessionWorkspace } from "@celestea/runtime";
+import { type StoreResult } from "./result.js";
+import { type SessionMode } from "./mode.js";
+import { type SessionMeta } from "./session-meta.js";
+import { type WorkspacesStore } from "./workspaces.js";
+export interface ResolvedSession {
+    workspace: string;
+    session: string;
+    /** Canonical `<workspace>/<session>`. */
+    id: string;
+    wsPath: string;
+    dir: string;
+}
+/**
+ * W768 — THE single resolution of a session's workspace.
+ *
+ * Everything that needs to know "which workspace is this session in" goes
+ * through here: the system prompt's `{{workspace}}` / `{{workspace_dir}}`
+ * variables AND the per-session sandbox cwd / path-guard root. They used to be
+ * two independent derivations (a store lookup for the prompt, a process-wide env
+ * knob for the tools), which is exactly how the prompt ended up naming one
+ * workspace while `pwd` reported another.
+ *
+ * Pure projection of the store's own record: no second lookup, no re-parsing of
+ * the session id, nothing that could disagree with `resolve()`.
+ */
+export declare function sessionWorkspaceOf(resolved: ResolvedSession | null): SessionWorkspace | null;
+/**
+ * W779 T2 — the session's DISPLAY name.
+ *
+ * `session.json.title` when the session declared one (the original, un-sanitized
+ * title), else the directory name WITHOUT its `-<secs>.<nanos>[-N]` creation
+ * suffix. ONE rule, used by `list()` and by `branch()`'s default title, so the
+ * GUI never has to know how a session directory is named.
+ */
+export declare function displayTitle(meta: SessionMeta | null, dirName: string): string;
+export interface SessionRow {
+    id: string;
+    workspace: string;
+    /**
+     * W779 T2: the display name — `session.json.title`, else the directory name
+     * with its creation suffix stripped (never `main-1789192174.492000000`).
+     */
+    title: string;
+    model: string | null;
+    /**
+     * W729: the session's working mode. A session without `session.json.mode`
+     * (and every worker row) reads as `standard` — the P0 default (K8/M3).
+     */
+    mode: SessionMode;
+    size: number;
+    modified: number;
+    active: boolean;
+    /**
+     * W791: present (and `true`) ONLY on rows produced by `listArchived()` — the
+     * default listing never carries the key, so the frozen response body of
+     * `GET /api/sessions` is unchanged for every pre-W791 client.
+     */
+    archived?: true;
+    /**
+     * W513 row kind: `session` = a filesystem session directory, `worker` = an
+     * engine-memory worker conversation (`workspace: "engine"`).
+     */
+    kind?: "session" | "worker";
+    /** W513: this session has an in-flight turn (its OWN slot, not the process's). */
+    busy?: boolean;
+}
+export interface SessionCreateRequest {
+    workspace?: string;
+    title: string;
+    model?: string;
+    prompt?: string;
+    /** W729: optional at creation; absent = `standard` and NOT written (K8). */
+    mode?: string;
+}
+export declare class SessionsStore {
+    private readonly ws;
+    private readonly now;
+    constructor(ws: WorkspacesStore, now?: () => number);
+    /**
+     * Every filesystem session plus the engine rows handed in by the caller.
+     *
+     * W877 (slice A): sessions are scanned in BOTH layouts — the new
+     * `<ws>/.celestea/sessions/` root first, then the legacy workspace root. A
+     * directory name present in both is emitted ONCE and the new-layout row wins.
+     * Dot-directories stay invisible in either root (that is what keeps
+     * `.celestea`, `.celestea-archived` and `.celestea-trash` out of the
+     * default listing).
+     */
+    list(extra?: readonly SessionRow[]): SessionRow[];
+    /**
+     * W791 (B1): every ARCHIVED session of every registered workspace.
+     *
+     * Archiving MOVES a session directory to `<ws>/.celestea-archived/<name>` and
+     * keeps its id (`<wsName>/<session>`) — it is the same session, parked in a
+     * hidden sibling. `list()` deliberately skips dot-directories, so before this
+     * method the ONLY endpoint that could name an archived session was
+     * `unarchive`; the GUI's archive panel (`?archived=1`) and the
+     * delete-an-archived-session path both need to enumerate them.
+     *
+     * The rows have EXACTLY the shape `list()` produces — same id/workspace/title/
+     * model/mode/size/modified derivation, same sort — plus `archived: true` and
+     * `active: false` (an archived session can never be the active one: archiving
+     * refuses the active session).
+     */
+    listArchived(): SessionRow[];
+    /** One row of the frozen shape (shared by `list` and `listArchived`). */
+    private rowOf;
+    /**
+     * Registry lookup + sanitization. The physical dir is probed in BOTH layouts
+     * (W877 slice A): the new `<ws>/.celestea/sessions/<session>` wins when it
+     * exists, the legacy `<ws>/<session>` is the fallback, and when NEITHER exists
+     * the new layout is returned so every write path stays consistent with
+     * `create()`. No registry entry is created here.
+     */
+    resolve(id: string): StoreResult<ResolvedSession>;
+    /** A real live session dir: a directory holding the session log. */
+    private isSessionDir;
+    /** Resolve + require the session directory to hold a log file. */
+    require(id: string): StoreResult<ResolvedSession>;
+    private pickWorkspace;
+    /** POST /api/sessions — create a session dir; NEVER activates it. */
+    create(req: SessionCreateRequest): StoreResult<string>;
+    /**
+     * `<base>`, then `<base>-1`, `<base>-2`, … until the name is free, returned
+     * inside `writeRoot`.
+     *
+     * `writeRoot` defaults to the canonical container (`create()`), while
+     * `rename`/`branch` pass the parent of the session's CURRENT dir so a session
+     * is renamed inside the layer it already lives in.
+     *
+     * Collision detection spans EVERY live-session layer: a name already taken by
+     * a legacy session must not be minted again in the canonical container (and
+     * vice versa), because `list()` and `resolve()` would then have two different
+     * physical dirs for one id.
+     */
+    uniqueDir(wsPath: string, base: string, writeRoot?: string): string;
+    /** Transcript projection: torn tail dropped, no pairing logic. */
+    messages(resolved: ResolvedSession): StudioMessage[];
+    /** POST /api/clear — truncate the log (no backup, no 409 guard). */
+    truncate(resolved: ResolvedSession): StoreResult<void>;
+}

package/dist/store/sessions.js

@@ -0,0 +1,307 @@
+/**
+ * Session listing / creation / transcript reader (`src/workspaces.rs:1092-1221,1459-1501`).
+ *
+ * A "session" is a directory holding `cli-main.jsonl`. The id is
+ * `<workspace-basename>/<dir>`; the `worker:<sid>` space is served by the engine
+ * (RuntimeAdapter) instead.
+ *
+ * W880: NEW sessions land in `<CELESTEA_HOME>/workspaces/<ws>/sessions/<dir>`
+ * (outside the workspace). `resolve()`/`list()` still read the two legacy
+ * layouts (slice-A `<ws>/.celestea/sessions/`, then `<ws>/`) with the canonical
+ * container winning. W791: the ARCHIVED sessions (canonical
+ * `<home>/.../archive/<dir>`, legacy `<ws>/.celestea-archived/<dir>`, see
+ * `session-ops.ts`) are a second source of the same row shape — `listArchived()`
+ * — because `list()` skips dot-directories by design.
+ *
+ * The transcript endpoint is a pure projection of the append-only log
+ * (`projectMessages` from `@celestea/session`), stopping at the first
+ * unparsable line so a torn tail is dropped rather than reported.
+ */
+import { readFileSync } from "node:fs";
+import { parseSessionJsonl, projectMessages } from "@celestea/session";
+import { isDirectory, isFile, listEntries, statOf, writeFileRaw, removeDir, ensureDir } from "./fs-json.js";
+import { badRequest, errText, fail, notFound, ok } from "./result.js";
+import { DEFAULT_SESSION_MODE, parseMode, validateMode } from "./mode.js";
+import { readSessionMeta, writeSessionMeta } from "./session-meta.js";
+import { archiveRoots, baseName, liveDirCandidates, sessionDirName, sanitizeComponent, sessionRoots, sessionsRoot, stripCreationSuffix, workspaceBasename } from "./session-id.js";
+import { validateModelName, validatePromptId } from "./validate.js";
+import { SESSION_FILE } from "./workspaces.js";
+/**
+ * W768 — THE single resolution of a session's workspace.
+ *
+ * Everything that needs to know "which workspace is this session in" goes
+ * through here: the system prompt's `{{workspace}}` / `{{workspace_dir}}`
+ * variables AND the per-session sandbox cwd / path-guard root. They used to be
+ * two independent derivations (a store lookup for the prompt, a process-wide env
+ * knob for the tools), which is exactly how the prompt ended up naming one
+ * workspace while `pwd` reported another.
+ *
+ * Pure projection of the store's own record: no second lookup, no re-parsing of
+ * the session id, nothing that could disagree with `resolve()`.
+ */
+export function sessionWorkspaceOf(resolved) {
+    if (resolved === null)
+        return null;
+    return { name: resolved.workspace, path: resolved.wsPath };
+}
+/**
+ * W779 T2 — the session's DISPLAY name.
+ *
+ * `session.json.title` when the session declared one (the original, un-sanitized
+ * title), else the directory name WITHOUT its `-<secs>.<nanos>[-N]` creation
+ * suffix. ONE rule, used by `list()` and by `branch()`'s default title, so the
+ * GUI never has to know how a session directory is named.
+ */
+export function displayTitle(meta, dirName) {
+    const declared = meta?.title ?? "";
+    return declared === "" ? stripCreationSuffix(dirName) : declared;
+}
+export class SessionsStore {
+    ws;
+    now;
+    constructor(ws, now = Date.now) {
+        this.ws = ws;
+        this.now = now;
+    }
+    /**
+     * Every filesystem session plus the engine rows handed in by the caller.
+     *
+     * W877 (slice A): sessions are scanned in BOTH layouts — the new
+     * `<ws>/.celestea/sessions/` root first, then the legacy workspace root. A
+     * directory name present in both is emitted ONCE and the new-layout row wins.
+     * Dot-directories stay invisible in either root (that is what keeps
+     * `.celestea`, `.celestea-archived` and `.celestea-trash` out of the
+     * default listing).
+     */
+    list(extra = []) {
+        const active = this.ws.activeSession();
+        const rows = [];
+        for (const w of this.ws.registry().workspaces) {
+            const name = workspaceBasename(w.path) ?? w.path;
+            const seen = new Set();
+            // Canonical container FIRST, then the slice-A transitional root, then the
+            // oldest workspace root. Only a REAL session (a dir holding the log)
+            // shadows a lower layer: a stray empty dir must not hide a live session.
+            for (const root of sessionRoots(w.path)) {
+                for (const e of listEntries(root)) {
+                    if (!e.isDir || e.name.startsWith(".") || seen.has(e.name))
+                        continue;
+                    const log = `${root}/${e.name}/${SESSION_FILE}`;
+                    if (!isFile(log))
+                        continue;
+                    seen.add(e.name);
+                    const row = this.rowOf(name, e.name, readSessionMeta(`${root}/${e.name}`), statOf(log));
+                    rows.push({ ...row, active: active === row.id });
+                }
+            }
+        }
+        rows.push(...extra);
+        rows.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        return rows;
+    }
+    /**
+     * W791 (B1): every ARCHIVED session of every registered workspace.
+     *
+     * Archiving MOVES a session directory to `<ws>/.celestea-archived/<name>` and
+     * keeps its id (`<wsName>/<session>`) — it is the same session, parked in a
+     * hidden sibling. `list()` deliberately skips dot-directories, so before this
+     * method the ONLY endpoint that could name an archived session was
+     * `unarchive`; the GUI's archive panel (`?archived=1`) and the
+     * delete-an-archived-session path both need to enumerate them.
+     *
+     * The rows have EXACTLY the shape `list()` produces — same id/workspace/title/
+     * model/mode/size/modified derivation, same sort — plus `archived: true` and
+     * `active: false` (an archived session can never be the active one: archiving
+     * refuses the active session).
+     */
+    listArchived() {
+        const rows = [];
+        for (const w of this.ws.registry().workspaces) {
+            const name = workspaceBasename(w.path) ?? w.path;
+            const seen = new Set();
+            for (const root of archiveRoots(w.path)) {
+                for (const e of listEntries(root)) {
+                    if (!e.isDir || e.name.startsWith(".") || seen.has(e.name))
+                        continue;
+                    const log = `${root}/${e.name}/${SESSION_FILE}`;
+                    if (!isFile(log))
+                        continue;
+                    seen.add(e.name);
+                    rows.push({ ...this.rowOf(name, e.name, readSessionMeta(`${root}/${e.name}`), statOf(log)), archived: true });
+                }
+            }
+        }
+        rows.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        return rows;
+    }
+    /** One row of the frozen shape (shared by `list` and `listArchived`). */
+    rowOf(workspace, dirName, meta, st) {
+        return {
+            id: `${workspace}/${dirName}`,
+            workspace,
+            kind: "session",
+            title: displayTitle(meta, dirName),
+            model: meta?.model ?? null,
+            mode: meta?.mode ?? DEFAULT_SESSION_MODE,
+            size: st?.size ?? 0,
+            modified: st?.modified ?? 0,
+            active: false,
+        };
+    }
+    /**
+     * Registry lookup + sanitization. The physical dir is probed in BOTH layouts
+     * (W877 slice A): the new `<ws>/.celestea/sessions/<session>` wins when it
+     * exists, the legacy `<ws>/<session>` is the fallback, and when NEITHER exists
+     * the new layout is returned so every write path stays consistent with
+     * `create()`. No registry entry is created here.
+     */
+    resolve(id) {
+        const slash = id.trim().indexOf("/");
+        if (slash <= 0)
+            return badRequest(`invalid session id '${id}': expected '<workspace>/<session>'`);
+        const wsName = id.trim().slice(0, slash);
+        const wsPath = this.ws.workspacePath(wsName);
+        if (wsPath === undefined)
+            return notFound(`unknown workspace '${wsName}'`);
+        const session = sanitizeComponent(id.trim().slice(slash + 1));
+        if (session === "" || session === "." || session === ".." || session.startsWith(".")) {
+            return badRequest(`invalid session id '${id}'`);
+        }
+        // W880: the canonical candidate lives under CELESTEA_HOME, OUTSIDE the
+        // workspace, so the old `startsWith(wsPath/)` guard no longer applies. The
+        // session segment is already sanitized (no separators, never hidden) and
+        // every candidate is derived from the registered wsPath, so the result
+        // cannot escape either root.
+        const candidates = liveDirCandidates(wsPath, session);
+        const dir = candidates.find((c) => this.isSessionDir(c)) ?? candidates[0];
+        return ok({ workspace: wsName, session, id: `${wsName}/${session}`, wsPath, dir });
+    }
+    /** A real live session dir: a directory holding the session log. */
+    isSessionDir(dir) {
+        return isDirectory(dir) && isFile(`${dir}/${SESSION_FILE}`);
+    }
+    /** Resolve + require the session directory to hold a log file. */
+    require(id) {
+        const res = this.resolve(id);
+        if (!res.ok)
+            return res;
+        if (!isDirectory(res.value.dir) || !isFile(`${res.value.dir}/${SESSION_FILE}`)) {
+            return notFound(`unknown session '${id}'`);
+        }
+        return res;
+    }
+    pickWorkspace(requested) {
+        const asked = (requested ?? "").trim();
+        if (asked !== "")
+            return asked;
+        const active = this.ws.activeSession();
+        if (active !== null && active.includes("/"))
+            return active.slice(0, active.indexOf("/"));
+        const first = this.ws.registry().workspaces[0];
+        return first === undefined ? null : workspaceBasename(first.path);
+    }
+    /** POST /api/sessions — create a session dir; NEVER activates it. */
+    create(req) {
+        const wsName = this.pickWorkspace(req.workspace);
+        if (wsName === null)
+            return notFound(`unknown workspace '${(req.workspace ?? "").trim()}'`);
+        const wsPath = this.ws.workspacePath(wsName);
+        if (wsPath === undefined)
+            return notFound(`unknown workspace '${wsName}'`);
+        if (!isDirectory(wsPath))
+            return notFound(`workspace path '${wsPath}' is not accessible`);
+        if (req.title.trim() === "")
+            return badRequest("title must not be empty");
+        const base = sanitizeComponent(req.title);
+        if (base.startsWith(".") || base === "") {
+            return badRequest(`title '${req.title}' sanitizes to the hidden name '${base}'`);
+        }
+        const model = req.model ?? "";
+        if (model !== "") {
+            const bad = validateModelName(model);
+            if (bad !== null)
+                return badRequest(`invalid model: ${bad}`);
+        }
+        const prompt = req.prompt ?? "";
+        if (prompt !== "") {
+            const bad = validatePromptId(prompt);
+            if (bad !== null)
+                return badRequest(`invalid prompt: ${bad}`);
+        }
+        const mode = req.mode ?? "";
+        if (mode !== "") {
+            const bad = validateMode(mode);
+            if (bad !== null)
+                return badRequest(bad);
+        }
+        // W880: NEW sessions land in <CELESTEA_HOME>/workspaces/<ws>/sessions/
+        // (ensureDir below creates the container recursively); the id stays
+        // <wsName>/<dirName>. Nothing is created under the workspace root.
+        const dir = this.uniqueDir(wsPath, sessionDirName(req.title, this.now()));
+        try {
+            ensureDir(dir);
+            writeFileRaw(`${dir}/${SESSION_FILE}`, "");
+        }
+        catch (e) {
+            return fail(500, `create failed: ${errText(e)}`);
+        }
+        try {
+            // W779 T2: the ORIGINAL title (trimmed, CJK/spaces preserved) is what the
+            // GUI shows; the directory name stays the sanitized+timestamped form.
+            writeSessionMeta(dir, {
+                title: req.title.trim(),
+                model,
+                prompt,
+                ...(mode === "" ? {} : { mode: parseMode(mode) ?? DEFAULT_SESSION_MODE }),
+            });
+        }
+        catch (e) {
+            removeDir(dir);
+            return fail(500, `meta write failed: ${errText(e)}`);
+        }
+        // W885: the directory's own basename, per the platform (a win32 realpath
+        // returns backslashes, so `lastIndexOf("/")` produced the whole path —
+        // W883 E2).
+        return ok(`${wsName}/${baseName(dir)}`);
+    }
+    /**
+     * `<base>`, then `<base>-1`, `<base>-2`, … until the name is free, returned
+     * inside `writeRoot`.
+     *
+     * `writeRoot` defaults to the canonical container (`create()`), while
+     * `rename`/`branch` pass the parent of the session's CURRENT dir so a session
+     * is renamed inside the layer it already lives in.
+     *
+     * Collision detection spans EVERY live-session layer: a name already taken by
+     * a legacy session must not be minted again in the canonical container (and
+     * vice versa), because `list()` and `resolve()` would then have two different
+     * physical dirs for one id.
+     */
+    uniqueDir(wsPath, base, writeRoot = sessionsRoot(wsPath)) {
+        const roots = [writeRoot, ...sessionRoots(wsPath)];
+        let name = base;
+        let n = 1;
+        while (roots.some((root) => isFile(`${root}/${name}/${SESSION_FILE}`) || isDirectory(`${root}/${name}`))) {
+            name = `${base}-${n}`;
+            n += 1;
+            if (n > 1000)
+                break;
+        }
+        return `${writeRoot}/${name}`;
+    }
+    /** Transcript projection: torn tail dropped, no pairing logic. */
+    messages(resolved) {
+        const text = readFileSync(`${resolved.dir}/${SESSION_FILE}`, "utf8");
+        return projectMessages(parseSessionJsonl(text).events);
+    }
+    /** POST /api/clear — truncate the log (no backup, no 409 guard). */
+    truncate(resolved) {
+        try {
+            writeFileRaw(`${resolved.dir}/${SESSION_FILE}`, "");
+            return ok(undefined);
+        }
+        catch (e) {
+            return fail(500, errText(e));
+        }
+    }
+}

package/dist/store/validate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Host-side field validation shared by several endpoints.
+ *
+ * The host validates before it hands anything to the engine, and the
+ * error strings are contract text (`contracts/endpoints.json` errors[]), so
+ * they live here verbatim instead of being re-typed per handler.
+ */
+export declare const MODEL_MAX_LEN = 128;
+export declare function validateModelName(model: string): string | null;
+export declare function validatePromptId(id: string): string | null;
+export declare function isHttpUrl(url: string): boolean;
+/** `parse_effort`: "" / "off" (case-insensitive) clears the effort. */
+export declare function parseEffort(raw: string | null | undefined): string | null | undefined;

package/dist/store/validate.js

@@ -0,0 +1,38 @@
+/**
+ * Host-side field validation shared by several endpoints.
+ *
+ * The host validates before it hands anything to the engine, and the
+ * error strings are contract text (`contracts/endpoints.json` errors[]), so
+ * they live here verbatim instead of being re-typed per handler.
+ */
+/** Model ids are deliberately lax: `[A-Za-z0-9._-:/@]`, at most 128 chars. */
+const MODEL_CHARS = /^[A-Za-z0-9._\-:/@]*$/;
+export const MODEL_MAX_LEN = 128;
+export function validateModelName(model) {
+    if (model.length > MODEL_MAX_LEN)
+        return `invalid model name: '${model}' exceeds ${MODEL_MAX_LEN} characters`;
+    for (const ch of model) {
+        if (!MODEL_CHARS.test(ch)) {
+            return `invalid model name '${model}': character ${JSON.stringify(ch)} is not allowed (only [A-Za-z0-9._-:/@]; no spaces, brackets or control characters)`;
+        }
+    }
+    return null;
+}
+const PROMPT_ID = /^[A-Za-z0-9._-]{1,128}$/;
+export function validatePromptId(id) {
+    return PROMPT_ID.test(id) ? null : "prompt id must be 1-128 chars of [A-Za-z0-9._-]";
+}
+export function isHttpUrl(url) {
+    return url.startsWith("http://") || url.startsWith("https://");
+}
+/** `parse_effort`: "" / "off" (case-insensitive) clears the effort. */
+export function parseEffort(raw) {
+    if (raw === null)
+        return null;
+    if (raw === undefined)
+        return undefined;
+    const v = raw.trim();
+    if (v === "" || v.toLowerCase() === "off")
+        return null;
+    return v;
+}

package/dist/store/workspaces.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `workspaces.json` (v2) registry store — `contracts/data-files/workspaces.schema.json`,
+ * `src/workspaces.rs:122-140,794-970`.
+ *
+ * Frozen format facts honored here:
+ *   - NO version field; the workspace KEY is the registered path's folder
+ *     basename and is never stored;
+ *   - v1 `{"name":…}` rows are tolerated and ignored; `active_session` is
+ *     rewritten to the basename on load (idempotent);
+ *   - unknown fields are tolerated, a malformed file is a HARD error (the
+ *     unreadable registry is never overwritten with an empty one);
+ *   - write = pretty JSON -> `<file>.json.tmp` -> rename (atomic, no fsync).
+ */
+import { type StoreResult } from "./result.js";
+export declare const SESSION_FILE = "cli-main.jsonl";
+export interface RegistryWorkspace {
+    path: string;
+}
+export interface RegistryData {
+    workspaces: RegistryWorkspace[];
+    active_session: string | null;
+}
+export interface WorkspaceRow {
+    name: string;
+    path: string;
+    /** LIVE session dirs only (archived / trashed dirs are not counted). */
+    sessions: number;
+}
+export interface WorkspacesView {
+    workspaces: WorkspaceRow[];
+    active_session: string | null;
+}
+export declare class WorkspacesStore {
+    private readonly file;
+    private data;
+    constructor(file: string);
+    /** Snapshot of the registry (callers must not mutate it). */
+    registry(): RegistryData;
+    activeSession(): string | null;
+    workspacePath(name: string): string | undefined;
+    private persist;
+    /** Persist `active_session`; the caller owns the 500 wording. */
+    setActiveSession(id: string | null): StoreResult<void>;
+    /**
+     * Count LIVE session dirs of a workspace across EVERY layer (W880): the
+     * canonical `<CELESTEA_HOME>/.../sessions`, the slice-A
+     * `<ws>/.celestea/sessions` and the oldest workspace root. A name present in
+     * more than one layer is counted ONCE (the canonical copy wins), matching
+     * `SessionsStore.list()`; missing a layer is how the GUI's workspace session
+     * count silently drops to 0.
+     */
+    countSessions(path: string): number;
+    view(): WorkspacesView;
+    /** POST /api/workspaces — register only; the folder is never touched. */
+    register(rawPath: string): StoreResult<string>;
+    /** POST /api/workspaces/{name}/delete — deregister only. */
+    deregister(name: string): StoreResult<void>;
+    batchDelete(names: readonly string[]): {
+        deleted: number;
+        failed: Array<{
+            name: string;
+            error: string;
+        }>;
+    };
+    /** POST /api/workspaces/{name}/rename — really renames the FOLDER. */
+    renameWorkspace(name: string, newName: string): StoreResult<void>;
+}