@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.0

package/dist/ops/ops-engine.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
-import { blockSchemas, operationSchema, validateBlockProps, validateByJsonSchemaLike, isChrome, mapSemanticThemeTokens, generateItemId } from "@avocadostudio-ai/shared";
+import { blockSchemas, operationSchema, validateBlockProps, findManifestSchemaIssue, isChrome, isInBlockCatalogue, catalogueBlockTypes, mapSemanticThemeTokens, generateItemId, isRichTextDoc, fromMarkdown, mergeRichTextDoc } from "@avocadostudio-ai/shared";
 import { normalizeRouteCandidate } from "../nlp/intent-helpers.js";
 import { pageIdFromSlug, pageTitleFromSlug } from "../nlp/plan-normalizer.js";
 import { OperationError, toErrorDetail as _unifiedToErrorDetail } from "../errors.js";
 import { isDemoModeEnabled, enforceDemoOps } from "../demo-mode.js";
 import { computePublishDiff } from "../publish/diff-engine.js";
 import { acquireSessionLock } from "../state/session-lock.js";
-import { getSessionDraft, orderSlugsHomeFirst, setPage, getPage, getSiteConfig, setSiteConfig } from "../state/session-state.js";
+import { getSessionDraft, orderSlugsHomeFirst, setPage, getPage, getSiteConfig, setSiteConfig, getSessionCapabilities } from "../state/session-state.js";
 // ---------------------------------------------------------------------------
 // Passthrough Zod schema cache — avoids allocating a new ZodObject per call
 // ---------------------------------------------------------------------------
@@ -29,6 +29,34 @@ function _sanitizeListItemImageAlt(item) {
     }
     return obj;
 }
+/**
+ * Bring a patch value up to the shape the prop is actually stored in.
+ *
+ * A rich-text prop can hold either a markdown string or a ProseMirror document
+ * — an integration whose CMS has real rich text (Portable Text, Contentful) maps
+ * it to the document form so nothing is flattened. The planner does not know
+ * which: it was asked to rewrite some prose, and prose to a planner is a string.
+ * Writing that string straight into a document-valued prop replaces the document
+ * with a `string`, which the renderer cannot draw and the CMS adapter cannot
+ * publish.
+ *
+ * So a string landing on a document-valued prop is parsed into a document and
+ * merged with what was there: stored `_key`s carry over, so the CMS sees an
+ * update rather than a wholesale replacement, and any block markdown cannot
+ * express — an embedded entry, a product card — is put back rather than deleted
+ * by a text edit that never mentioned it.
+ *
+ * Returns `undefined` when nothing needs coercing, including when the patch is
+ * itself a document: that came from the editor, which owns the whole value, and
+ * restoring blocks the user deliberately deleted would fight them.
+ */
+function _coerceRichTextValue(oldVal, newVal) {
+    if (!isRichTextDoc(oldVal))
+        return undefined;
+    if (typeof newVal !== "string")
+        return undefined;
+    return mergeRichTextDoc(fromMarkdown(newVal), oldVal);
+}
 function _getPassthroughSchema(blockType) {
     const cached = _passthroughSchemaCache.get(blockType);
     if (cached)
@@ -243,6 +271,58 @@ export function buildDeterministicRepairFeedback(reason) {
         .filter((line) => line.length > 0)
         .join(" ");
 }
+/**
+ * Refuse operations the site behind this session has said it cannot honour.
+ *
+ * Checked once for the whole batch, before anything is staged, because ops are
+ * atomic: a batch containing one refused op must not half-apply, and telling
+ * the caller after four of five ops have been written is telling them too
+ * late.
+ *
+ * This is the half of the capability gate that matters. Omitting a tool from
+ * the MCP list makes one client honest and leaves /chat, /ops, the editor and
+ * Puck producing the same unpublishable pages — they never pass through the
+ * MCP server. Every write path reaches here.
+ *
+ * Silence is permission, so this is inert for every integration that has not
+ * declared a capability: nothing changes until an adapter says `false`.
+ */
+function _assertOperationsPermitted(session, ops) {
+    const caps = getSessionCapabilities(session);
+    if (caps.createPages && caps.deletePages && caps.structuralEdits)
+        return;
+    const refuse = (opName, why) => {
+        throw new OperationError(`This site cannot ${why} (operation "${opName}"). Its content adapter has declared the ` +
+            `capability unavailable, so the change would apply to the draft and then fail to publish.`, { category: "unsupported_by_site" });
+    };
+    for (const op of ops) {
+        if (!caps.createPages && (op.op === "create_page" || op.op === "duplicate_page")) {
+            // duplicate_page mints an identity just as surely as create_page does;
+            // the CMS has no document behind the new slug either way.
+            refuse(op.op, "create pages");
+        }
+        if (!caps.deletePages && op.op === "remove_page")
+            refuse(op.op, "delete pages");
+        if (!caps.structuralEdits && _changesBlockStructure(op)) {
+            refuse(op.op, "change which blocks a page has");
+        }
+    }
+}
+/**
+ * Narrower than `isStructuralOperation` on purpose: that predicate also counts
+ * `add_item`/`remove_item`/`move_item`, and adding a row to a list is an
+ * ordinary array write inside one block's props. Any adapter that projects the
+ * CMS's own keys can publish it. What a `structuralEdits: false` site cannot
+ * take is a change to the *set and order of blocks* — the case that motivates
+ * the flag is language variants sharing one block structure, where every text
+ * edit is fine and no insertion is.
+ */
+function _changesBlockStructure(op) {
+    return (op.op === "add_block" ||
+        op.op === "remove_block" ||
+        op.op === "move_block" ||
+        op.op === "duplicate_block");
+}
 export function isStructuralOperation(op) {
     return (op.op === "add_block" ||
         op.op === "remove_block" ||
@@ -320,6 +400,93 @@ function _resolveBlockIndex(blocks, blockId, fuzzyMatches) {
     }
     return -1;
 }
+/**
+ * Drop an adapter's provenance keys from a block that is being copied.
+ *
+ * A projected block carries the adapter's answer to "which upstream thing is
+ * this", and the adapter routes the write by it: Paintball Arena Bern marks a
+ * block with `props._sectionId` and publishes anything carrying one into the
+ * *shared section document* rather than into the page. Copied verbatim onto a
+ * duplicate, the first edit to that duplicate's hero is written back into the
+ * section every other page renders. A copy has no upstream document yet, and
+ * saying nothing is the only honest answer available.
+ *
+ * Shallow on purpose, and the nesting is not an oversight. A rich-text prop
+ * holds a document whose nodes carry the stored `attrs._key`s that let a CMS
+ * patch a paragraph instead of replacing the field, plus the raw `_type`/`_key`
+ * blocks markdown cannot express, kept so a text edit does not delete an
+ * embedded entry. Those are content, and a recursive strip would delete the
+ * identity that makes a CMS patch rather than rewrite.
+ *
+ * But shallow is a limit, not a guarantee: an adapter may mark list rows too —
+ * PBA tags an individual button and card with its source key — and those
+ * survive a duplicate. The key that routes a write to another document
+ * (`_sectionId`) is top-level, so the damage this was written to stop is
+ * stopped. The rest waits for an adapter that can say which of its own keys
+ * are identity, rather than us guessing by depth.
+ *
+ * Deliberately the opposite of `update_props`, which keeps undeclared `_` props
+ * because site-owned bookkeeping has to survive an edit. An edit is the same
+ * upstream thing; a copy is a different one.
+ */
+function _stripProvenanceProps(props) {
+    const provenanceKeys = Object.keys(props).filter((key) => key.startsWith("_"));
+    if (provenanceKeys.length === 0)
+        return props;
+    const next = { ...props };
+    for (const key of provenanceKeys)
+        delete next[key];
+    return next;
+}
+/**
+ * Canonical form of a `meta.path` for collision comparison. `/events/` and
+ * `/events` are one URL, so a page must not be able to claim a path another
+ * page already serves by differing in a trailing slash.
+ */
+function _canonicalPagePath(path) {
+    const trimmed = path.trim();
+    if (trimmed.length <= 1)
+        return trimmed;
+    return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+}
+/**
+ * Refuse a `meta.path` another page already serves.
+ *
+ * `path` is where the site actually answers for a page, and until now only the
+ * slug — the page's identity in the draft — was checked for uniqueness. Two
+ * pages could name one live URL and the first thing to notice was the browser.
+ *
+ * An empty or absent path collides with nothing: it means "the slug is the
+ * path", which is true for every page on a site whose routing Avocado owns.
+ */
+/**
+ * No two pages may serve one URL, checked across the finished plan.
+ *
+ * Two things make this an invariant of the *result* rather than a guard on
+ * `create_page`. A page that declares no `path` still serves one — its slug —
+ * so comparing declared paths to declared paths misses a page whose declared
+ * path is another page's slug, which is precisely the locale case `path`
+ * exists for. And a plan is atomic: checking as each op lands refuses
+ * `[create_page(path X), remove_page(the page holding X)]`, where the finished
+ * state is perfectly consistent and only the order was inconvenient.
+ *
+ * So it runs once, over what the plan actually produced.
+ */
+function _assertNoPagePathCollisions(finalPages) {
+    const byPath = new Map();
+    for (const [slug, page] of finalPages) {
+        // Absent means "the slug is the path" — the page still occupies a URL.
+        const effective = _canonicalPagePath(page.meta?.path ?? slug);
+        if (effective.length === 0)
+            continue;
+        const holder = byPath.get(effective);
+        if (holder !== undefined) {
+            throw new OperationError(`Two pages would serve ${JSON.stringify(effective)}: ${holder} and ${slug}. ` +
+                `A page's URL is its meta.path, or its slug when it declares none.`, { category: "schema_violation" });
+        }
+        byPath.set(effective, slug);
+    }
+}
 function _nextDuplicateSlug(candidateMap, sourceSlug) {
     const base = sourceSlug === "/" ? "/home-copy" : `${sourceSlug.replace(/\/+$/, "")}-copy`;
     if (!candidateMap.has(base))
@@ -444,8 +611,13 @@ function _validateWithManifestIfPresent(manifestByType, blockType, nextProps) {
             if (result.success)
                 coerced = result.data;
         }
-        if (!validateByJsonSchemaLike(manifestComponent.propsSchema, coerced)) {
-            throw new OperationError(`Invalid props for ${blockType}: does not match block manifest schema`, { category: "schema_violation" });
+        const issue = findManifestSchemaIssue(manifestComponent.propsSchema, coerced);
+        if (issue) {
+            // Name the prop and the mismatch. "does not match block manifest schema"
+            // on a block with a dozen props tells the person reading it nothing, and
+            // it is the message custom blocks get — the ones whose shape the reader
+            // is least likely to have memorised.
+            throw new OperationError(`Invalid props for ${blockType}: ${issue.path}: ${issue.message}`, { category: "schema_violation" });
         }
         return coerced;
     }
@@ -531,6 +703,7 @@ export async function applyOpsAtomically(session, ops, options) {
     }
 }
 async function _applyOpsAtomicallyUnsafe(session, ops, options) {
+    _assertOperationsPermitted(session, ops);
     const manifestByType = new Map();
     if (options?.componentsManifest) {
         for (const component of options.componentsManifest.blocks) {
@@ -676,8 +849,18 @@ async function _applyOpsAtomicallyUnsafe(session, ops, options) {
                 const nextBlocks = source.blocks.map((block) => {
                     const newId = _nextUniqueBlockId(source.blocks, `${block.id}_copy`);
                     blockIdMap[block.id] = newId;
-                    return { ...block, id: newId };
+                    return { ...block, id: newId, props: _stripProvenanceProps(block.props) };
                 });
+                // A copy's URL is nobody's to assign yet. `meta.path` is the adapter's
+                // report of where it serves the *source*; carried over, two draft pages
+                // answer for one live URL and nothing notices until a browser does.
+                // Absent means "the slug is the path", the honest answer for a page whose
+                // URL no one has assigned.
+                const { path: _sourcePath, ...copiedMeta } = source.meta ?? {};
+                // When caller passes newTitle, keep meta.title in sync so SEO doesn't show
+                // the source page's English title on a translated copy. Other meta fields
+                // (description, ogImage) stay — caller can patch them with update_page_meta.
+                const nextMeta = explicitNewTitle ? { ...copiedMeta, title: explicitNewTitle } : copiedMeta;
                 // source was already deep-cloned at entry into `staged`; spread is sufficient
                 // since all later mutations replace blocks/props wholesale rather than mutating in-place.
                 const copy = {
@@ -687,14 +870,9 @@ async function _applyOpsAtomicallyUnsafe(session, ops, options) {
                     title: explicitNewTitle ?? `${source.title} Copy`,
                     updatedAt: new Date().toISOString(),
                     blocks: nextBlocks,
-                    // When caller passes newTitle, keep meta.title in sync so SEO doesn't show
-                    // the source page's English title on a translated copy. Other meta fields
-                    // (description, ogImage) stay — caller can patch them with update_page_meta.
-                    meta: explicitNewTitle && source.meta
-                        ? { ...source.meta, title: explicitNewTitle }
-                        : explicitNewTitle
-                            ? { title: explicitNewTitle }
-                            : source.meta
+                    // A source whose only meta was `path` must not leave an empty `meta: {}`
+                    // behind for the adapter to read as "this page has SEO fields".
+                    meta: Object.keys(nextMeta).length > 0 ? nextMeta : undefined
                 };
                 staged.set(nextSlug, copy);
                 touchedSlugs.add(nextSlug);
@@ -885,6 +1063,20 @@ async function _applyOpsAtomicallyUnsafe(session, ops, options) {
             if (op.op === "add_block") {
                 if (isChrome(op.block.type))
                     throw new OperationError(`Cannot add chrome block type "${op.block.type}"`, { category: "schema_violation" });
+                /*
+                 * Registered is not the same as renderable. A site that declared its own
+                 * catalogue is telling us the built-ins it inherited by importing
+                 * `@avocadostudio-ai/shared` are types it has no renderer for — adding one
+                 * applies cleanly and draws nothing, which is worse than a refusal.
+                 *
+                 * Only `add_block` is guarded. A `duplicate_block` copies a type the page
+                 * already holds, so the site plainly renders it whatever the declaration
+                 * says, and refusing would strand existing content.
+                 */
+                if (!isInBlockCatalogue(op.block.type)) {
+                    throw new OperationError(`Cannot add block "${op.block.type}" — this site does not render that type. ` +
+                        `Its catalogue is: ${catalogueBlockTypes().join(", ")}`, { category: "not_found" });
+                }
                 _requireManifestComponent(manifestByType, op.block.type, "add block");
                 const validatedProps = _validateWithManifestIfPresent(manifestByType, op.block.type, op.block.props);
                 const alreadyExists = page.blocks.some((b) => b.id === op.block.id);
@@ -999,7 +1191,14 @@ async function _applyOpsAtomicallyUnsafe(session, ops, options) {
                 const nextList = list.map((entry, idx) => {
                     if (idx !== targetIndex)
                         return entry;
-                    return { ...entry, ...itemPatch };
+                    const previous = entry;
+                    const merged = { ...previous };
+                    for (const [key, value] of Object.entries(itemPatch)) {
+                        // Same coercion as update_props: a list item can hold a document-valued
+                        // rich-text field too (an FAQ answer, a tab body).
+                        merged[key] = _coerceRichTextValue(previous[key], value) ?? value;
+                    }
+                    return merged;
                 });
                 const nextProps = { ...block.props, [op.listKey]: nextList };
                 page.blocks[blockIdx] = { ...block, props: _withValidatedBlockProps(manifestByType, block, nextProps) };
@@ -1176,6 +1375,11 @@ async function _applyOpsAtomicallyUnsafe(session, ops, options) {
                     if (key === "imageAlt" && typeof newVal === "string" && _looksLikeUserInstruction(newVal)) {
                         continue;
                     }
+                    const coercedRichText = _coerceRichTextValue(oldVal, newVal);
+                    if (coercedRichText !== undefined) {
+                        nextProps[key] = coercedRichText;
+                        continue;
+                    }
                     // Deep-merge arrays of objects by index so partial items inherit existing fields
                     if (Array.isArray(oldVal) && Array.isArray(newVal)) {
                         nextProps[key] = newVal.map((item, i) => {
@@ -1294,6 +1498,7 @@ async function _applyOpsAtomicallyUnsafe(session, ops, options) {
             }
         }
     }
+    _assertNoPagePathCollisions(staged);
     // A dry-run never aborts on "nothing changed" — an empty preview is a valid,
     // useful answer ("this plan would do nothing"). Only the committing path
     // treats a wholly-ineffective plan as an error.

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

@@ -1,6 +1,7 @@
 import type { Logger } from "../logger.ts";
 import { type EditPlan, type Operation, type PageDoc, type SiteConfig } from "@avocadostudio-ai/shared";
 import { toErrorDetail as _unifiedToErrorDetail } from "../errors.ts";
+export { persistenceHealth, persistenceWarning, type PersistenceHealth } from "./sqlite-store-singleton.ts";
 import type { PublishLogEntry } from "./sqlite-store.ts";
 export type { PublishLogEntry, PublishLogStatus } from "./sqlite-store.ts";
 export declare const HISTORY_DEPTH_MAX = 50;
@@ -164,6 +165,29 @@ export declare const pendingApprovalPlanBySession: Map<string, PendingApprovalPl
 export type ImageSourcePreference = "unsplash" | "genai" | "either";
 export declare const imageSourcePreferenceBySession: Map<string, ImageSourcePreference>;
 export declare const publishStatusBySession: Map<string, PublishTracker>;
+/**
+ * What the adapter behind a session says it can honour, recorded when the
+ * session is first touched so the ops engine can refuse an operation the site
+ * cannot publish.
+ *
+ * Session-keyed rather than a module-level singleton, because one process can
+ * host several mounts: the standalone server serves many sites, and nothing
+ * stops a host from constructing two runtimes. A global "current capabilities"
+ * would let one site's declaration decide another site's edits.
+ *
+ * Ephemeral by design, and deliberately NOT persisted to SQLite: this is a
+ * property of the running mount, not of the draft. A restart with a different
+ * adapter must not inherit the old one's answer.
+ */
+export declare const capabilitiesBySession: Map<string, SessionCapabilities>;
+export type SessionCapabilities = {
+    createPages: boolean;
+    deletePages: boolean;
+    structuralEdits: boolean;
+};
+export declare function setSessionCapabilities(session: string, caps: SessionCapabilities): void;
+/** Silence means permission — see `resolveCapabilities` for why the default is not restrictive. */
+export declare function getSessionCapabilities(session: string): SessionCapabilities;
 export declare const siteConfigs: Map<string, {
     name?: string | undefined;
     logo?: string | undefined;
@@ -191,8 +215,39 @@ export type SessionSummary = {
     lastMutatedAt: string | null;
 };
 export declare function getSessionSummary(sessionKey: string): SessionSummary;
+/**
+ * Erase every trace of one session.
+ *
+ * Sessions are created by being named: a GET with a `siteId` nobody has ever
+ * used seeds a draft from the demo pages and the session exists from then on,
+ * indistinguishable in `/sessions` from one holding real work. That is fine
+ * for the demo it was built for and actively misleading everywhere else — an
+ * agent asked to find a site's pages sees "8 draft pages" under the right
+ * siteId and reasonably believes it has found them.
+ *
+ * Sites already had `DELETE /sites` for exactly this; sessions had nothing, so
+ * a session created by a typo could only be removed by stopping the process
+ * and editing SQLite. Every map keyed by the session key is listed here rather
+ * than a subset, because a half-forgotten session is worse than a kept one:
+ * the summary disappears while its undo stack and chat history stay behind.
+ */
+export declare function forgetSession(sessionKey: string): boolean;
 export declare function listSessionSummaries(): SessionSummary[];
-/** Total published pages across all sites (currently just the JSON-file legacy site). */
+/**
+ * Size of the in-memory published Map — which is the bundled demo content, and
+ * only that.
+ *
+ * The old comment here read "total published pages across all sites", and every
+ * caller believed it. `publishedPages` is seeded from `demoPublishedPages()` at
+ * import time and no publish path writes it: `POST /publish` goes to the site
+ * origin or a CmsAdapter, and `loadPublishedForDiff` treats this Map as its
+ * last-resort fallback precisely because it is stale. So the number is the
+ * constant 8 on every deployment that has not migrated a legacy JSON state file.
+ *
+ * Kept, because on the demo site it is the truth — but callers must say which
+ * site they are answering for before using it. `whoamiAction` is the worked
+ * example.
+ */
 export declare function publishedPageCountGlobal(): number;
 export declare function markRecentlyRestored(session: string): void;
 export declare function consumeRecentlyRestored(session: string): boolean;

package/dist/state/session-state.js

@@ -2,8 +2,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { demoPublishedPages, demoSiteConfig, ensureItemIds, IMAGE_PLACEHOLDER } from "@avocadostudio-ai/shared";
 import { toErrorDetail as _unifiedToErrorDetail } from "../errors.js";
-import { archiveMigratedJson, getStore, readLegacyJson, resolveJsonMigrationTtlDays, sweepStaleMigrations, } from "./sqlite-store-singleton.js";
-import { CHAT_HISTORY_CAP, HISTORY_DEPTH_CAP, RECENT_EDITS_CAP, VERSION_LOG_CAP, PUBLISH_LOG_CAP, } from "./sqlite-store.js";
+import { archiveMigratedJson, getStore, notePersistenceFailure, notePersistenceSuccess, readLegacyJson, resolveDbFile, resolveJsonMigrationTtlDays, sweepStaleMigrations, } from "./sqlite-store-singleton.js";
+// Re-exported so callers that already depend on this module for state can ask
+// whether that state is actually being kept, without a second import path.
+export { persistenceHealth, persistenceWarning } from "./sqlite-store-singleton.js";
+import { CHAT_HISTORY_CAP, HISTORY_DEPTH_CAP, RECENT_EDITS_CAP, VERSION_LOG_CAP, PUBLISH_LOG_CAP, preloadSqliteDriver, } from "./sqlite-store.js";
 // Single source of truth for these caps is `sqlite-store.ts`. Re-exported
 // under the legacy names so existing imports keep working.
 export const HISTORY_DEPTH_MAX = HISTORY_DEPTH_CAP;
@@ -96,6 +99,28 @@ export const chatHistoryBySession = new Map();
 export const pendingApprovalPlanBySession = new Map();
 export const imageSourcePreferenceBySession = new Map();
 export const publishStatusBySession = new Map();
+/**
+ * What the adapter behind a session says it can honour, recorded when the
+ * session is first touched so the ops engine can refuse an operation the site
+ * cannot publish.
+ *
+ * Session-keyed rather than a module-level singleton, because one process can
+ * host several mounts: the standalone server serves many sites, and nothing
+ * stops a host from constructing two runtimes. A global "current capabilities"
+ * would let one site's declaration decide another site's edits.
+ *
+ * Ephemeral by design, and deliberately NOT persisted to SQLite: this is a
+ * property of the running mount, not of the draft. A restart with a different
+ * adapter must not inherit the old one's answer.
+ */
+export const capabilitiesBySession = new Map();
+export function setSessionCapabilities(session, caps) {
+    capabilitiesBySession.set(session, caps);
+}
+/** Silence means permission — see `resolveCapabilities` for why the default is not restrictive. */
+export function getSessionCapabilities(session) {
+    return capabilitiesBySession.get(session) ?? { createPages: true, deletePages: true, structuralEdits: true };
+}
 export const siteConfigs = new Map();
 // No hardcoded seed: drafts now hydrate from the live published JSON via
 // `hydrateSiteConfigFromPublished` on first session touch. A hardcoded seed
@@ -119,6 +144,40 @@ export function getSessionSummary(sessionKey) {
     const lastMutatedAt = log && log.length > 0 ? log[log.length - 1].at : null;
     return { sessionKey, session, siteId, version, draftPageCount, lastMutatedAt };
 }
+/**
+ * Erase every trace of one session.
+ *
+ * Sessions are created by being named: a GET with a `siteId` nobody has ever
+ * used seeds a draft from the demo pages and the session exists from then on,
+ * indistinguishable in `/sessions` from one holding real work. That is fine
+ * for the demo it was built for and actively misleading everywhere else — an
+ * agent asked to find a site's pages sees "8 draft pages" under the right
+ * siteId and reasonably believes it has found them.
+ *
+ * Sites already had `DELETE /sites` for exactly this; sessions had nothing, so
+ * a session created by a typo could only be removed by stopping the process
+ * and editing SQLite. Every map keyed by the session key is listed here rather
+ * than a subset, because a half-forgotten session is worse than a kept one:
+ * the summary disappears while its undo stack and chat history stay behind.
+ */
+export function forgetSession(sessionKey) {
+    const existed = draftPages.has(sessionKey) || versions.has(sessionKey) || versionLog.has(sessionKey);
+    draftPages.delete(sessionKey);
+    historyUndo.delete(sessionKey);
+    historyRedo.delete(sessionKey);
+    versions.delete(sessionKey);
+    recentEdits.delete(sessionKey);
+    versionLog.delete(sessionKey);
+    publishLogBySession.delete(sessionKey);
+    continuationChainBySession.delete(sessionKey);
+    pendingClarificationBySession.delete(sessionKey);
+    chatHistoryBySession.delete(sessionKey);
+    pendingApprovalPlanBySession.delete(sessionKey);
+    imageSourcePreferenceBySession.delete(sessionKey);
+    publishStatusBySession.delete(sessionKey);
+    capabilitiesBySession.delete(sessionKey);
+    return existed;
+}
 export function listSessionSummaries() {
     // Union of every key seen across draft / version / version-log maps. A
     // session may appear in `versions` (bumped) without `draftPages` (e.g.
@@ -143,7 +202,21 @@ export function listSessionSummaries() {
     });
     return summaries;
 }
-/** Total published pages across all sites (currently just the JSON-file legacy site). */
+/**
+ * Size of the in-memory published Map — which is the bundled demo content, and
+ * only that.
+ *
+ * The old comment here read "total published pages across all sites", and every
+ * caller believed it. `publishedPages` is seeded from `demoPublishedPages()` at
+ * import time and no publish path writes it: `POST /publish` goes to the site
+ * origin or a CmsAdapter, and `loadPublishedForDiff` treats this Map as its
+ * last-resort fallback precisely because it is stale. So the number is the
+ * constant 8 on every deployment that has not migrated a legacy JSON state file.
+ *
+ * Kept, because on the demo site it is the truth — but callers must say which
+ * site they are answering for before using it. `whoamiAction` is the worked
+ * example.
+ */
 export function publishedPageCountGlobal() {
     return publishedPages.size;
 }
@@ -966,9 +1039,12 @@ export async function persistStateNow(logger) {
     }
     try {
         writeAllStateToStore(getStore());
+        notePersistenceSuccess();
     }
     catch (error) {
-        logger.error({ err: toErrorDetail(error) }, "Failed to persist orchestrator state to SQLite");
+        const reason = toErrorDetail(error);
+        notePersistenceFailure(reason);
+        logger.error({ err: reason }, "Failed to persist orchestrator state to SQLite");
         throw error;
     }
 }
@@ -991,9 +1067,12 @@ export function schedulePersistState(logger) {
         persistTimer = null;
         try {
             writeAllStateToStore(getStore());
+            notePersistenceSuccess();
         }
         catch (error) {
-            logger.error({ err: toErrorDetail(error) }, "Failed to persist orchestrator state to SQLite");
+            const reason = toErrorDetail(error);
+            notePersistenceFailure(reason);
+            logger.error({ err: reason }, "Failed to persist orchestrator state to SQLite");
         }
     }, PERSIST_DEBOUNCE_MS);
     // Don't let the debounce timer keep the process alive on its own.
@@ -1041,10 +1120,17 @@ export function evictStaleEphemeralMaps() {
 export async function loadStateFromDisk(logger) {
     let store;
     try {
+        // Resolve the native driver before the first synchronous `getStore()`.
+        // A bundled host can only reach it through an async import; see
+        // `preloadSqliteDriver`.
+        await preloadSqliteDriver();
         store = getStore();
     }
     catch (error) {
-        logger.error({ err: toErrorDetail(error) }, "Failed to open orchestrator SQLite store");
+        const reason = toErrorDetail(error);
+        notePersistenceFailure(reason);
+        logger.error({ err: reason, dbFile: resolveDbFile() }, "Failed to open orchestrator SQLite store — drafts will live in memory only " +
+            "and are lost on restart");
         return;
     }
     const jsonPath = resolveStateFilePath();

package/dist/state/sqlite-store-singleton.d.ts

@@ -4,6 +4,28 @@ export declare function resolveDbFile(): string;
 export declare function resolveJsonMigrationTtlDays(): number;
 export declare function resolveBackupLimit(): number;
 export declare function resolveBackupIntervalHours(): number;
+export type PersistenceHealth = {
+    ok: boolean;
+    reason: string | null;
+};
+/** Record a persistence failure. The first reason wins; later ones are noise. */
+export declare function notePersistenceFailure(reason: string): void;
+/** Clear the recorded failure — a successful write means we are healthy again. */
+export declare function notePersistenceSuccess(): void;
+export declare function persistenceHealth(): PersistenceHealth;
+/**
+ * Spread into a successful mutation response. Empty while healthy, so the happy
+ * path is unchanged and no client has to learn a new field to keep working.
+ *
+ * When it is not empty, `status: "applied"` is still true — the operation did
+ * apply, to state that will not outlive the process. Saying so in the response
+ * is the whole point: an agent gets one chance to notice, at the moment it
+ * would otherwise record the edit as done.
+ */
+export declare function persistenceWarning(): Record<string, never> | {
+    persisted: false;
+    persistenceWarning: string;
+};
 export declare function getStore(): SqliteStore;
 /** Close & clear the singleton. Intended for tests + graceful shutdown. */
 export declare function resetStore(): void;

package/dist/state/sqlite-store-singleton.js

@@ -17,7 +17,23 @@ export function resolveDbFile() {
         return ":memory:";
     if (process.env.NODE_ENV === "test")
         return ":memory:";
-    return resolve(process.cwd(), "../../.data/orchestrator.db");
+    /*
+     * `../../.data` is this monorepo's shape, not a general default.
+     *
+     * It is right for `apps/orchestrator`, whose cwd is two levels under the repo
+     * root, and wrong for everyone else: a library-mode host running from its own
+     * project root writes two directories *above* itself. PBA's landed in
+     * `~/Projects/.data` — outside the project, outside version control, and
+     * shared with any sibling checkout that made the same mistake.
+     *
+     * The default is now the host's own `.data/`. The legacy path still wins when
+     * a database is already sitting there, so an existing monorepo checkout keeps
+     * its state without an env var and without a migration step.
+     */
+    const legacy = resolve(process.cwd(), "../../.data/orchestrator.db");
+    if (existsSync(legacy))
+        return legacy;
+    return resolve(process.cwd(), ".data/orchestrator.db");
 }
 export function resolveJsonMigrationTtlDays() {
     const raw = Number(process.env.ORCHESTRATOR_JSON_MIGRATION_TTL_DAYS ?? 14);
@@ -35,6 +51,37 @@ export function resolveBackupIntervalHours() {
 // Singleton access
 // ---------------------------------------------------------------------------
 let store = null;
+let persistenceFailure = null;
+/** Record a persistence failure. The first reason wins; later ones are noise. */
+export function notePersistenceFailure(reason) {
+    if (persistenceFailure === null)
+        persistenceFailure = reason;
+}
+/** Clear the recorded failure — a successful write means we are healthy again. */
+export function notePersistenceSuccess() {
+    persistenceFailure = null;
+}
+export function persistenceHealth() {
+    return { ok: persistenceFailure === null, reason: persistenceFailure };
+}
+/**
+ * Spread into a successful mutation response. Empty while healthy, so the happy
+ * path is unchanged and no client has to learn a new field to keep working.
+ *
+ * When it is not empty, `status: "applied"` is still true — the operation did
+ * apply, to state that will not outlive the process. Saying so in the response
+ * is the whole point: an agent gets one chance to notice, at the moment it
+ * would otherwise record the edit as done.
+ */
+export function persistenceWarning() {
+    if (persistenceFailure === null)
+        return {};
+    return {
+        persisted: false,
+        persistenceWarning: "This edit was applied in memory but could not be saved — it will be lost when the " +
+            `server restarts, and the session may silently revert to CMS content. Cause: ${persistenceFailure}`
+    };
+}
 export function getStore() {
     if (!store) {
         store = new SqliteStore({ file: resolveDbFile() });
@@ -50,6 +97,7 @@ export function resetStore() {
         catch { /* ignore */ }
     }
     store = null;
+    persistenceFailure = null;
 }
 // ---------------------------------------------------------------------------
 // JSON migration helpers

package/dist/state/sqlite-store.d.ts

@@ -1,4 +1,9 @@
 import type { Database as BetterSqliteDatabase } from "better-sqlite3";
+/**
+ * Resolve and cache the driver. Awaited once at startup; safe to call again.
+ * Throws with every attempt's failure when the module cannot be reached at all.
+ */
+export declare function preloadSqliteDriver(): Promise<void>;
 import type { PageDoc, Operation, SiteConfig } from "@avocadostudio-ai/shared";
 export declare const HISTORY_DEPTH_CAP = 50;
 export declare const VERSION_LOG_CAP = 100;