THU-MAIC/OpenMAIC v1.2.0-rc.1

v1.2.0-rc.1 — server-first (release candidate)

on GitHub

Breaking Changes

• Server-backed persistence is always on. Courses, folders and folder membership, chat history and learner runtime, and generated media are stored on the server through /api/persistence; the browser has no storage backend of its own any more. The build-time NEXT_PUBLIC_PERSISTENCE switch is removed (from the client, the Dockerfile and docker-compose.yml) and ignored. The server now requires DATABASE_URL and exits at startup without it ([boot] Invalid server configuration; the server will not start: DATABASE_URL is not set. ...); pnpm db:up / pnpm db:down start and stop a separate development database (the Compose postgres service definition under its own project and volume, openmaic-dev-db), published on 127.0.0.1 (OPENMAIC_DB_PORT, default 5432), for local development; other deployments point DATABASE_URL at a PostgreSQL database they run. Only device-local state stays in the browser (settings, playback position, the editor's current scene and undo history, a local cache of media the server already stores, and browser voice profiles), in a new maic-device-cache IndexedDB database; Settings → Clear Local Cache clears exactly that. Courses an earlier browser-only build stored in the browser are not deleted; the one-way importer below moves them to the server.

• Docker Compose: docker compose up now starts PostgreSQL (no profile) and a server-backed app (DATABASE_URL set from PERSISTENCE_POSTGRES_PASSWORD) that waits for PostgreSQL to be healthy, in single-user mode (docker-compose.defaults.env, read before .env.local so it can be overridden there). The app port is published on 127.0.0.1 only; start with OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 to serve other machines, and set ACCESS_CODE then: every visitor is the same single owner. OPENMAIC_PORT changes the host port. --profile server-persistence is still accepted and does nothing. A DATABASE_URL in .env.local still wins over the bundled default. Courses an earlier browser-only deployment stored in the browser are not deleted; the one-way importer in this release moves them to the server. Anonymous libraries from an earlier server-backed deployment are not merged into the single owner automatically; claim them explicitly. A .env.local that sets PERSISTENCE_SHARED_OWNER_ID must also set OWNER_SINGLE_USER=false.

• @openmaic/storage 0.34.0: course ownership is no longer recorded on document_stages. PgDocumentStore never reads or writes document_stages.owner_id; an owner-bound store scopes listings, writes, deletes, the freshness manifest and folder membership through the host's ownership relation, named with the new documentOwnership option ({ table, stageIdColumn?, ownerIdColumn?, tombstoneColumn?, claimOnCreate? }). The relation must cascade with the document rows (REFERENCES document_stages(id) ON DELETE CASCADE) or be cleaned alongside them; a leftover ownership row keeps the id reserved for its owner. documentOwnership: false turns document scoping off, and on an owner-bound store it requires allowCrossOwnerDocumentAccess: true, so binding an owner for folders or asset principals cannot silently expose every owner's documents. forOwner(ownerId) (or ownerId) without documentOwnership now throws at construction instead of silently scoping nothing. A store that is not owner-bound is tenant-agnostic: it lists and writes every document, where it used to see only documents with no owner. AssetCollector's assetReferencePrincipals requires documentOwnership too, because the backfill reads each document's owner from that relation. A new folders: false option lets a host whose own document_stages has no folder_id column use the store without folders. Fresh installs no longer get the owner_id column or its two indexes (document_stages_owner_idx, document_stages_owner_folder_idx); document_stages_folder_idx replaces the latter.

• Server persistence: stage_meta is the only record of who owns a course. At the first start, courses whose owner was recorded only on document_stages.owner_id are adopted into stage_meta (once per database, logged with a count; where the two records disagree stage_meta stands and the disagreement is counted). To roll back to a release that still reads the column, first copy ownership back for courses created since the upgrade: UPDATE document_stages AS d SET owner_id = m.owner_id FROM stage_meta AS m WHERE m.stage_id = d.id AND d.owner_id IS NULL.

• Server persistence: runtime sessions (/api/persistence/runtime/*) are keyed by the owner the owner identity seam resolves, not by a client-supplied x-learner-key behind the development token. PERSISTENCE_DEV_TOKEN, NEXT_PUBLIC_PERSISTENCE_TOKEN and PERSISTENCE_ALLOW_INSECURE_DEV_AUTH are removed and ignored; the browser learns its learner key from GET /api/persistence/learner-key. Runtime sessions written before this change were keyed by a browser-minted learner key and are no longer reachable; they are not migrated, because trusting a client-supplied old key would restore client-chosen identity. Course documents and media are unaffected. If the development token was your only access gate, put the deployment behind ACCESS_CODE or a gateway, or register owner auth methods, before upgrading: without the token the endpoint serves every visitor as their own anonymous owner.

• Server persistence: assets are allocated in a per-owner partition, so ASSET_QUOTA_BYTES is a per-owner ceiling and only the owner can replace or delete an entry. Other owners read an entry by id while a live course of the entry's owner references it, and a document write references and commits only its owner's entries (and legacy ones), so naming another owner's id records nothing. Entries in the old shared partition stay readable by id, and can be replaced or deleted only by an owner who owns every course referencing them.

• Server-side classroom generation (POST /api/generate-classroom) writes through server persistence. A job runs for the request owner and saves the classroom into that owner's course library, with its images, videos and narration in the owner's asset pool; nothing is written under data/classrooms or data/classroom-jobs any more. POST /api/classroom and GET /api/classroom are removed, and so is the classroom page's fallback to GET /api/classroom. Jobs are stored in PostgreSQL (as generation runs, see below) and are owner-scoped: GET /api/generate-classroom/<jobId> answers only the owner that created the job (or the account it was claimed into) and 404 for everyone else, like an unknown id. With a fixed owner (PERSISTENCE_SHARED_OWNER_ID, OWNER_SINGLE_USER, or a host auth method) this is automatic; in anonymous-cookie mode a headless caller must keep the cookie from its first response and send it when polling, and the classrooms it generates belong to that anonymous owner: anyone can open them by link, but no browser user can edit them. Run with a fixed owner or host auth when API-generated courses should be editable.

• Headless generation runs on the server's generation runs (#1754, E2): POST /api/generate-classroom starts a run of the request owner, the same pipeline (and the same step functions, prompts and validation) as classic generation, with the outline confirmed by the run itself, course-specific agents (the built-in ones if that step fails), and no interactive or task-engine mode. The separate server pipeline (generateClassroom, its media and TTS passes and the in-process job runner) is removed. For API callers:

  • The job id is the run id (run-…), also returned as runId; job ids of earlier builds answer 404. The poll response keeps its shape (status queued / running / succeeded / failed, step, progress, scenesGenerated, totalScenes, result.classroomId / url / scenesCount, error, done), read from the run, and adds runId, runState and retryable. A run paused at a failed step, and a run whose course was deleted or that was discarded, read as failed with error naming the step; a paused one is retryable and keeps its scenes, and POST /api/generation-runs/<runId>/retry ({ commandId }) resumes it at that step, after which the job reads running again. step no longer reports generating_tts or persisting (narration is part of each scene, and each scene is saved as it is generated); it adds generating_media for the images and videos that finish after the last scene.
  • A submission is refused up front, before any run exists, instead of becoming a job that fails: 400 MISSING_MODEL when the outline or actions slot, or every scene content type (course.content.<type>, which inherits course.content and llm), resolves to no model (none configured, or the slot turned off), 400 MISSING_API_KEY when its provider needs a key it lacks, 400 INVALID_URL for an endpoint the workspace may not use, 400 MODEL_CONFIG_INVALID for an option only the deployment may set (Bedrock, a proxy). Bodies are capped at 64 KiB (413) and requirements at 20 000 characters. The checks run in this order: the body, the models, the materials, the limit. When only some scene types resolve, the submission is accepted: the outline does not avoid the others, and a scene of such a type pauses the run at its content step.
  • Runs are limited per owner: 429 ACTIVE_RUN_LIMIT when the owner already has OPENMAIC_MAX_ACTIVE_RUNS_PER_OWNER runs in progress (default 2). A paused run, like one waiting for its outline to be confirmed, holds no worker and does not count; a step Retry makes it count again and answers the same 429 over the limit (as confirm-outline does).
  • Courses are written as they generate: the course exists (read-only to other writers) from its first scene, each scene is narrated before it is appended, and images and videos are generated alongside. A narration provider failure the retries cannot overcome pauses the run instead of leaving clips silent; a clip the asset store refuses is left silent and counted in result.warning, as is a failed image or video, which does not fail the job either (the retryable ones have a Retry on the run). The counts survive the compaction of finished runs. result.ttsCoverage is removed, and so are TTS_MIN_INTERVAL_MS and TTS_BACKOFF_BUDGET_MS, which only the removed TTS pass read.
  • Document images found by material extraction are stored as assets of the course and can be placed on slides; the removed pipeline used the extracted text only.
  • The generate-classroom LLM stage key is removed (nothing resolves through it); an x-model-routes header naming it gets the unknown-stage warning, and the MODEL_ROUTES migration table keeps its row.
  • Pre-release builds of this line created a classroom_generation_jobs table (schema store classroom-generation-jobs); it is no longer created or read, and is left untouched in databases that have it.

• Deployment: OpenMAIC needs a long-running Node.js process with PostgreSQL, the Docker image (docker compose or on its own) or pnpm start (#1754, F). Generation runs execute in a worker inside the server process and continue after the request that started them, so serverless hosts, Vercel included, are not supported. vercel.json is removed, and the build always produces the standalone output (the VERCEL build switch in next.config.ts is gone). Serverless deployment is supported up to 1.1.x: the README describes deploying the release/1.1.x branch on Vercel (Vercel's deploy button cannot select a branch whose name contains a slash), and such a deployment moves to a long-running host without losing data when the new host uses the same database and address. The deployment docs gain the required configuration (DATABASE_URL, an identity mode, and for several instances OPENMAIC_SECRET_KEY and one shared data directory, where uploaded materials live), the generation run variables and an "Upgrading from 1.1.x" table.

• Model configuration is server-side (#1701): models and providers come from openmaic.yml or the settings (Token Plan, Model Services and Course Model Config, see Features), not from the browser. MODEL_ROUTES is no longer read (see below); with openmaic.yml it is ignored with a notice. The pbl-chat and maic-agent stage keys, which nothing resolved, are removed. The provider variables, server-providers.yml, DEFAULT_MODEL and MODEL_FALLBACK keep working while there is no openmaic.yml and are deprecated; with openmaic.yml they configure nothing on their own and are referenced from the file as ${VAR}. #1731 #1732 #1735

• MODEL_ROUTES without openmaic.yml stops the server at startup (MODEL_ROUTES does not carry over to the model configuration: ...). Earlier releases required MODEL_ROUTES for the agent runtime (a maic-agent-driver route), so every deployment that runs the Pro agent must migrate before upgrading: write openmaic.yml and remove MODEL_ROUTES. Each route becomes the slot of its stage: maic-agent-driver → agent (its api and contextWindow move to the slot; a thinking effort is refused there as before), conversation-title → agent.title (unset, it follows agent), scene-outlines-stream → course.outline, scene-content and scene-content:slide|quiz|interactive|pbl → course.content and course.content.slide|quiz|interactive|pbl, scene-actions → course.actions, agent-profiles → course.agents, web-search-query-rewrite → course.research, chat-adapter, quiz-grade and pbl-v2-runtime (with its :instructor, :open-task, :evaluate, :simulator variants) → classroom, generate-classroom → llm. Stages that share a slot take one model. A route's thinking moves to the slot. See "Migrating from the legacy configuration" in the configuration docs for a worked example.

• Model configuration: the browser holds no provider state and sends none. Providers, keys, endpoints, model and provider ids, thinking settings, per-stage routes, Token Plan enrollment and per-capability selections are removed from the settings store; the Token Plan, Model Services and Course Model Config sections read and write the workspace's configuration on the server instead (see Features); the client no longer sends x-api-key, x-base-url, x-model, x-model-routes, x-image-*, x-video-*, x-*-provider or the key, endpoint, provider and model body fields. A browser's own settings are imported once (see Features). #1735 #1737 #1744 #1767

• Deprecated request fields: x-model, x-api-key, x-base-url, x-provider-type, x-model-routes, x-image-provider, x-image-model, x-video-provider, x-video-model and the equivalent body fields of the speech, search and document routes are honoured only while the slot they would affect has nothing assigned or, on a server still configured through the legacy variables, only a default those translate to (a default in openmaic.yml, a workspace's own choice and a locked slot win, and a slot set to null refuses the request), and not at all under allowUserKeys: false, which also refuses the header form of the provider test routes. The server logs a warning the first time a request names its own language model. They will be removed two minor versions after the model settings ship.

• POST /api/generate-classroom takes { requirement, materialIds? }. Documents are uploaded first with POST /api/materials (X-Material-Filename, the bytes as the body) as the same owner (in anonymous-cookie mode, keep one cookie jar for the upload, the submission and the polls), referenced by id, and deleted with the new DELETE /api/materials/<id> once the job is finished. pdfContent is refused with 400 INVALID_REQUEST; enableWebSearch, enableImageGeneration, enableVideoGeneration, enableTTS, agentMode, webSearchProviderId, webSearchApiKey, webSearchModelId and baiduSubSources are removed and ignored. Web search, images, video and narration run whenever the server configures them, and the new GET /api/generate-classroom/capabilities reports what is configured and which upload types this server can extract. materialIds takes at most 5 ids, 150 MiB in total, of types an available extractor reads, and unknown, foreign, unfinished and deleted ids share one answer; each owner's material library is capped (100 files / 2 GiB by default). The server never fetches caller-supplied URLs. The job record's inputSummary (requirementPreview, hasPdf, pdfTextLength, pdfImageCount, kept in the old data/classroom-jobs files and never part of the poll response) is removed. Uploads and materials are owner-scoped like jobs. #1728

• Generation runs on the server (see Features): a run keeps going when the page that started it is left or closed, and once its outline is confirmed it has no stop or pause; deleting the course ends it at its next step. A course is read-only to every other writer until its run completes or ends: content writes through the document store (saveDocument, putStage, putScene, deleteScene) and generation-complete answer 409 COURSE_GENERATING on the stage routes, 403 with that code on /api/persistence and an error to the Pro agent's tools; deleting the course and moving it between folders stay allowed. A run paused at a failed step keeps its course read-only until a Retry completes it or the course is deleted. #1759 #1761

• The per-step generation routes the browser called in 1.1.x are removed; course generation runs on the server (#1754, E4). Start a run with POST /api/generation-runs (or POST /api/generate-classroom for a headless caller) and follow it instead:

  • POST /api/generate/scene-outlines-stream is removed; use generation runs.
  • POST /api/generate/agent-profiles is removed; use generation runs.
  • POST /api/generate/scene-content is removed; use generation runs.
  • POST /api/generate/scene-actions is removed; use generation runs.
  • POST /api/extract-document is removed; use generation runs (upload materials with POST /api/materials).
  • POST /api/web-search is removed; use generation runs.

• Courses interrupted in the browser before 1.2.0 are not resumed; their remaining scenes show as interrupted ("Generation was interrupted", with no Retry). The scenes they have keep working, and images and videos of those courses that were never generated are offered as Retry rather than generated on open.

• Embedders: the browser storage seams (configureDocumentStorage, configureRuntimeStorage, configureAssetPoolStorage) have no IndexedDB fallback any more. The browser bootstrap configures the HTTP stores; code outside the browser must configure a store, and resolving an unconfigured seam throws. #1710

Deprecated

• document_stages.owner_id: the document store no longer reads or writes it (only the boot backfill reads it, and a claim mirrors the new owner into it while it exists, so a rollback still finds consistent ownership). Existing installations keep the column (made nullable, its default removed) for this release so a rollback still finds it; it will be dropped in the next release.

Upgrade notes

• Anonymous identities: existing 30-day anonymous_id cookies are renewed to 400 days on their next API request, and every response of an owner-scoped route that resolves to an anonymous cookie now carries a Set-Cookie renewing it. A browser that loses the cookie (a manual clear, or 400 days without use) gets a new owner, and cannot reach the earlier anonymous library, or a pending legacy import bound to it, from that browser: anonymous identity has no other key. Use single-user mode (the Compose default) for a personal installation, or accounts (owner auth methods) for many users.
• Schema versions: every start now records which schema version each store of the database is at, in a new openmaic_schema_migrations table, and applies only what is missing, in order, under the existing bootstrap lock (waited on for at most five minutes, then the start fails naming the lock). One-time steps (the stage_meta ownership adoption, the document_stages.owner_id retirement, the owner-material asset_id drop, the agent-session owner-event constraint swap) run once per database instead of on every start. The first start on an existing database (1.1.x or a development build) runs every store's baseline statement by statement, outside a transaction, exactly as earlier starts ran it (the same locks, released as each statement finishes), and records it afterwards; a start interrupted part-way runs it again. A migration that fails is reported with its store, version and name and retried on the next request. The server exits at startup ([boot] Server startup failed ... SchemaVersionAheadError) if the database records a version of any store, including those of features not in use, that is newer than the release knows: it was upgraded by a newer release, so run that release or a later one, or restore a backup taken before it. Releases before 1.2.0 do not read the table; rolling back to one still requires the ownership copy-back above (courses 1.2.0 creates have no document_stages.owner_id), otherwise restore a backup taken before the upgrade. A changed checksum of an applied migration only logs a warning in production (and stops a development or test server). Schema bootstrap needs a direct or session-pooled PostgreSQL connection; a pooler in transaction mode (PgBouncer pool_mode = transaction) is not supported.
• The first start creates the owner_merges table (with the stage_meta and owner-material schemas). Nothing is claimed until a claim is triggered; the default trigger is the explicit POST /api/identity/claim.
• The first start on an existing installation changes document_stages under table locks. CREATE INDEX document_stages_folder_idx builds the new index under a SHARE lock, which blocks writes to document_stages for the length of the build. DROP INDEX of document_stages_owner_idx / document_stages_owner_folder_idx takes a brief ACCESS EXCLUSIVE lock. If a host added NOT NULL or a default to owner_id, ALTER TABLE ... DROP NOT NULL / DROP DEFAULT also takes ACCESS EXCLUSIVE, which blocks reads too and waits behind any open transaction on the table. Upgrade in a quiet window, or start one instance first and let it finish before the rest start (concurrent starts are serialized anyway; see Bug Fixes). Once done, later starts change nothing.
• To keep the index build off the start path on a large table, create the index and drop the old ones yourself beforehand, outside a transaction: CREATE INDEX CONCURRENTLY IF NOT EXISTS document_stages_folder_idx ON document_stages (folder_id, id) WHERE folder_id IS NOT NULL;, DROP INDEX CONCURRENTLY IF EXISTS document_stages_owner_idx;, DROP INDEX CONCURRENTLY IF EXISTS document_stages_owner_folder_idx;. The start then builds and drops nothing. It still takes and releases the same momentary SHARE lock that every other CREATE INDEX IF NOT EXISTS in the schema takes on each start.
• Classrooms an earlier version stored under data/classrooms (or OPENMAIC_CLASSROOMS_DIR) are imported once, in the background after startup, retried with backoff until the import completes: each keeps its id (its link shows not-found until its import lands), its own /api/classroom-media media and narration move to the asset pool, and the outcome is recorded in the new legacy_classroom_imports table, so later starts skip it. An id another course already holds is skipped and that course stays as it is; so are invalid files and reservation placeholders, decided before any media is stored, and creates the host refuses, whose stored media is released. When the owner's asset store is full the run stops, records nothing for the classrooms it did not import, releases what it had stored for the current one while it is still unclaimed, logs it, and tries again later. A classroom whose import fails otherwise is retried and, after three failed attempts, skipped with its last error. One instance imports at a time. Imported classrooms belong to the shared team owner or the single user when one is configured, otherwise to a dedicated owner (system:legacy-classrooms): they open read-only from their old link and appear in no visitor's library. The files are not deleted; keep the directory, since imported classrooms may still reference other classrooms' files and agent-run courses still serve media from it.
• Rolling upgrades: jobs an older instance recorded under data/classroom-jobs are not migrated, and polling them answers 404. An older instance still running during the upgrade may finish a classroom the importer had skipped as a reservation placeholder; that file is not imported later.
• Media capabilities after an upgrade with the legacy configuration: the first configured TTS, ASR, image, video and document provider, and the first search provider in the old priority order, become server defaults, so these capabilities are on wherever the server configures a provider. This keeps the earlier behaviour of the web app, which switched image, video and narration on at a browser's first visit whenever the server had a provider for them, and gave the classroom chat and the agent web search whenever a search provider was configured. Two things change: course generation now researches the web whenever web search is on (it was an opt-in switch, off by default), and headless /api/generate-classroom jobs use every configured capability (the request flags defaulted to off). A workspace switches any of them off in Settings → Course Model Config; a deployment that wants one off for everybody sets its slot to null in openmaic.yml and names it in lock.
• Settings stored in a browser by an earlier version (providers with their keys and base URLs, the chosen model, token plan enrollment and each capability's selection) are imported into the workspace once, never replacing a workspace setting or a slot in a subtree openmaic.yml locks. Not carried over, to set up again: per-stage models, thinking settings, custom speech and transcription providers, AliDocMind's key pair, the VoxCPM backend and Baidu search sub-sources (the custom providers and the key pair stay in the browser with their keys, listed in Settings → Model Services). Speech input switched off becomes asr: null, and narration, images or video switched off while a usable provider for them was set up become tts: null, image: null or video: null. The research switch is not carried over (it only stopped course research; chat and the agent kept searching), nor is a switch that was off only by default: each capability now runs whenever its slot resolves.
• Keys saved in the model settings are encrypted under OPENMAIC_SECRET_KEY, or, when it is unset, under a secret generated on first use in data/instance-secret.key. Set OPENMAIC_SECRET_KEY when several replicas share the database, when data/ does not survive a restart (a container without a volume) and when the working directory is read-only (saving a key fails there otherwise); back up the secret file with the database otherwise. Keys sealed under a lost or different secret cannot be read (the settings mark them) and have to be entered again. #1733 #1783 The server warns at startup when OPENMAIC_SECRET_KEY is unset and the data directory is not writable, and when stored keys were sealed under a different secret than the current one; it still starts.

Features

• One-way import of browser data from earlier builds (temporary). On the first load after the upgrade, once the page is idle, the client moves what an earlier build kept in the browser to the server, for the owner the server resolves: courses from the browser document store and the original tables with their chat, learner runtime, playback position, agent roster, folders and membership, pre-runtime quiz state and media; media bytes of server courses from earlier opt-in server builds that only the old browser tables hold; and device-only rows (generation failure records, bytes a full store refused, auto-voice reference clips) into the device cache. It runs once per browser: the server binds the browser's random id to the first owner that asks (the new legacy_import_bindings table and POST /api/identity/legacy-import-binding, an atomic insert that answers only whether the requesting owner holds the browser), a claim carries the binding to the account (a new claim participant), and owner resolution refuses every importer request (X-OpenMAIC-Legacy-Import) of an owner that does not hold the binding with 409 LEGACY_IMPORT_NOT_BOUND; any other owner later using the same browser gets nothing imported. It is automatic and silent (problems are logged under [legacy-browser-import]), never writes to the old browser storage, keeps one ledger per browser (a random browser id and no owner information) so it resumes after an interruption and never imports twice (Clear Local Cache keeps it, and keeps the pre-runtime quiz keys until the import is complete), and serializes tabs with Web Locks. A course the owner already has on the server stays as the server has it; one whose id another owner holds is imported under a new id derived from the browser id; one deleted on the server stays deleted. Transient failures and 401s are retried on later loads with backoff; when the asset store is full the course is imported anyway and its media waits where the app's own retry finds it; media the server refuses for good shows the ordinary failed-media state (without Retry when nothing could regenerate it). A course the old browser storage cannot read holds up only what it could affect, and settles after five failing runs over a day (the older table copy when there is one, otherwise skipped with the reason). A browser whose data another owner holds asks the server again only every ten minutes, and opens the old databases only once it is bound. The module (lib/legacy-browser-import/) will be removed a few releases later; its README lists the steps.

• Owner identity: a built-in singleUser owner for personal installations. OWNER_SINGLE_USER=true resolves every request to one owner (OWNER_SINGLE_USER_ID, default local) with kind: 'user' and course:publish, minting no anonymous cookie; the principal gets a claim candidate from an anonymous cookie the browser still carries, so earlier anonymous work can be claimed into it explicitly (POST /api/identity/claim; OWNER_CLAIM_TRIGGER=auto would merge every visiting browser's anonymous library, so it is not a default). It runs with or without ACCESS_CODE; without one the server logs one prominent startup warning (in place of the generic unset-ACCESS_CODE warning) that anyone who can reach it shares, edits and can delete the single library. It excludes PERSISTENCE_SHARED_OWNER_ID; hosts may register singleUserAuthMethod() last, under the same rules as sharedTeamAuthMethod(). Malformed values fail startup. The app warns at startup when published beyond loopback (OPENMAIC_PUBLISH_ADDRESS, which the Compose file passes to it) with the Compose default PostgreSQL password.

• Owner identity: one resolution entry point with composable auth methods. A host registers an ordered list of OwnerAuthMethods once from instrumentation.ts with configureOwnerAuthentication({ methods, anonymousFallback? }) (single-shot, sealed on first use, validated at boot). Each method answers authenticated, not-applicable (no credential of its kind) or invalid (its credential is present but bad); core keeps the first authenticated answer, refuses any invalid answer with 401 INVALID_CREDENTIAL without asking later methods, and when no method applies falls back to the anonymous cookie owner, or answers 401 with anonymousFallback: false. Route handlers and Server Actions ask the same methods in the same order, once per request. PERSISTENCE_SHARED_OWNER_ID still selects the sharedTeam owner on its own; beside host methods it is kept by listing sharedTeamAuthMethod() last, and setting the variable while a registration leaves it out fails startup. Identity gateways are covered by a documented recipe (a host method that verifies the gateway's signed JWT against the identity provider's keys), not by a built-in. Host methods live in lib/server/identity/host/, the only place the boundary test lets code read gateway identity headers or an incoming Authorization header. On 403 OWNER_RETIRED, core calls clearCredential only on the anonymous fallback and on methods that declare issuesAnonymousOwners: true, never on an account method. The unreleased OWNER_AUTHENTICATOR / TRUSTED_PROXY_* variables of an earlier built-in gateway-header authenticator fail startup when set.

• Owner identity: claiming anonymous work into an account. When a host auth method authenticates a non-anonymous principal and the same request also carries a valid anonymous owner cookie, core attaches a pendingClaim naming that anonymous owner (never for an anonymous principal or the built-in sharedTeam, and a method cannot set one itself), which covers both an anonymous-then-sign-in flow and a deployment moving from anonymous use to accounts. POST /api/identity/claim (same-origin JSON only; OWNER_CLAIM_TRIGGER=auto claims on the first request carrying a pending claim, except the explicit claim routes) moves the anonymous owner's folders, courses, materials, agent sessions, skills, runtime sessions and asset entries to the account in one transaction, records it in the new owner_merges table, and drops the anonymous cookie. Same-named folders merge, a folder id the account already uses is renumbered, a colliding skill handle gets the first free numeric suffix, runtime sessions are re-keyed as stored, and quotas are not applied to what moves. Claims are idempotent per pair, refused for an anonymous owner another account already claimed, and never chain. A retired anonymous id writes nothing afterwards: creates and writes through /api/persistence, the folder, course, material and skill routes, and writes by id to moved rows answer 403 OWNER_RETIRED, with a Set-Cookie that drops the retired cookie. Agent runs, generated media and skills created by a run that started before the claim follow it to the account. Every owner write takes a per-owner advisory lock first, so a fenced write racing a claim is moved or refused; lock waits are bounded (OWNER_CLAIM_LOCK_WAIT_MS, OWNER_WRITE_LOCK_WAIT_MS) and running out answers 503 OWNER_BUSY with Retry-After. The anonymous cookie is a bearer credential: its holder can claim that anonymous work into a signed-in account, so clear it on shared devices. Hosts add their own tables with registerClaimParticipant, and an auth method may implement describeStoredOwner and clearCredential; principalFromStoredOwner(ownerId) describes a stored id for work without a request. The runtime contract's POST /runtime/learners/merge now performs the same claim, allowed only from the request's own pending claim. The owner-events stream tells a retired owner only that it moved, never the account's id.

• @openmaic/storage 0.37.0: versioned schema migrations for the PostgreSQL backends. Each backend declares an ordered list (DOCUMENT_PG_MIGRATIONS, RUNTIME_PG_MIGRATIONS, ASSET_PG_MIGRATIONS, AGENT_SESSION_PG_MIGRATIONS, AGENT_SESSION_MATERIAL_PG_MIGRATIONS, USER_SKILL_PG_MIGRATIONS) whose version 1 is the DDL earlier releases ran on every start, run statement by statement outside a transaction, and applySchemaMigrations(queryable, { store, migrations }, { lockTimeoutMs? }) (@openmaic/storage/pg-migrations) applies the pending ones under a session-level advisory lock waited on for a bounded time (SchemaLockTimeoutError), each later migration in a transaction with its record unless it sets transaction: false, recording (store, version, name, checksum, applied_at) in openmaic_schema_migrations. The ensure*Schema functions keep their signatures and now run their store's migrations: they are safe to call from several instances at once, accept a pool, a checked-out client, a connected pg.Client or PGlite, and refuse a connection inside an open transaction (SchemaMigrationInTransactionError) instead of committing the caller's work. A database that records a newer version of a store than the code knows is refused with SchemaVersionAheadError; a changed checksum of an applied migration throws SchemaMigrationChecksumError outside production and warns under NODE_ENV=production. verifySchemaMigrations(queryable, sets) makes both checks read-only. One-time steps now run once per database: the document_stages.owner_id retirement (relaxing NOT NULL / default, dropping its two indexes) is document version 2, and the owner-event type constraint swap is agent-session version 2, so DOCUMENT_PG_SCHEMA and AGENT_SESSION_PG_SCHEMA, now every migration's SQL concatenated, list those statements last. A table-name override is recorded as a store of its own. splitSqlStatements no longer drops a last statement that has no terminating semicolon. #1757

• @openmaic/storage 0.36.0: PgAssetStore.releasePending(principal, ref) deletes an entry only while it is still an unclaimed allocation (the principal's, pending, and named by no document), and answers whether it did. It locks the pending entry and then checks references in a separate statement, like the collector's entry pass, so a reference a concurrent backfill commits is never cascaded away. A writer that allocated ids and then failed to write the document naming them can release them at once without risking an entry a document did commit.

• @openmaic/storage 0.35.1: reassignDocumentFolders(tx, { fromOwnerId, toOwnerId, documentOwnership }) moves one owner's folders and filing to another (merging same-named folders, renumbering colliding ids); PgAssetStore.reassignPrincipal(fromKey, toKey) moves a principal's entries under both principals' write locks; PgUserSkillStore.mergeOwner(from, to) moves skills, renaming a handle the target holds to one neither side holds; PgRuntimeStore.reassignLearner(from, to) re-keys sessions without re-validating them. PgUserSkillStore (resolveFinalOwner) and PgRuntimeStore (resolveFinalLearner) take a hook that runs as the create transaction's first statement. Every HTTP handler (runtime, documents, assets) now answers a DocumentWriteRefusedError as 403 with its code, and the new StorageBusyError(code, message, retryAfterSeconds) as 503 with its code and Retry-After. PgUserSkillStore.list orders ties by id.

• Server persistence: host extension hooks, registered once from instrumentation.ts next to the owner auth methods and sealed on first use. configurePersistenceHooks adds authorizeCreate / onCreate (run once per created course inside its transaction; a refusal answers 403 CREATE_REFUSED and a throw rolls the create back), a library provider for what GET /api/stages lists (never an id the read path would refuse), and beforeAssetAllocate (refuse an upload, create or replace, with any Response before bytes are stored or quota counted). Hooks receive an actor whose source is 'request' (with the resolved principal) or 'background' (an agent run; a refusal reaches the agent as a fixed message). configureAssetByteStore replaces the ASSET_S3_BUCKET switch for the request path and the asset collector alike; under ASSET_BYTE_EGRESS=redirect a store that does not declare signsReadUrls stops the server at boot. Nothing changes when no hook is registered.

• @openmaic/storage 0.33.0: DocumentWriteRefusedError(stageId, code, message) lets a store refuse a write as policy; the document HTTP handler answers 403 with the error's code and applies nothing. isDocumentWriteRefusedError also recognizes one thrown by another copy of the package, by name and shape.

• Server persistence: ServerPersistenceProvider (lib/persistence/server-provider.ts) no longer exposes an unscoped documentStore, which wrote courses with no owner check and no host hooks. Use the owner-bound store (createOwnerBoundDocumentStore, or getOwnerScopedDocumentStore).

• Owner identity: POST /api/chat/pi answers 401 when owner resolution refuses the request, like every other owner-resolving route, instead of continuing without an owner. Under the default anonymous fallback nothing changes.

• Agent registry on the server (#1754, G). Built-in agents stay in code (read-only, updated and translated with releases); an owner's custom agents are stored in a new owner-scoped owner_agents table (schema store owner-agents) instead of the browser's agent-registry-storage. GET /api/agents lists the built-in agents (readOnly: true) and then the owner's own; POST /api/agents creates one and PUT / DELETE /api/agents/:id change or delete one, checked with the same schema the browser uses (at most 100 per owner); built-in agents answer 403 BUILT_IN_AGENT_READ_ONLY. A claim moves the anonymous owner's agents to the account, which keeps its own agent where both use an id. On the server, resolveAgentsForOwner(ownerId, agentIds) (lib/server/agents/registry.ts) resolves ids to agents and throws UnknownAgentsError listing the unknown ones. The browser registry reads and writes through the API and no longer writes localStorage; the custom agents an earlier build kept there are imported in the background, through the legacy importer's binding and fence (POST /api/agents/import), and the import stays open (the browser copy kept, Clear Local Cache included) until every one of them is on the server. #1758

• Capability slots (#1701): every model and provider call resolves through one slot of a fixed tree: llm with course.research, course.outline, course.agents, course.content (and course.content.slide / quiz / interactive / pbl), course.actions, classroom and agent (requires tool calling) with agent.title (openmaic.yml only); and the roots tts, asr, image, video, webSearch and document. A slot without an assignment follows its parent; null turns a capability off for its subtree (whatever a request names); a root with nothing assigned fails loudly instead of falling back to any vendor. A slot in a subtree openmaic.yml locks resolves from the file alone; any other slot takes the workspace's own assignment found anywhere from the slot up to the root, and only without one the server's default (slots in openmaic.yml, or the translated DEFAULT_MODEL and friends), so whatever a user changes wins and a slot that follows its parent follows the user's choice there. Resolution runs at request time for the request's owner and in background work for the owner it works for (following a claim). Requirements are checked on the slot that declares them. Language-model slots take a fallback, used by callLLM and, as the last attempt before anything has streamed, by streaming calls; a slot-resolved model no longer retries on MODEL_FALLBACK, and a fallback on any other slot is refused. Browserless outlines resolve course.outline instead of the generate-classroom model. Media, search, document extraction, narration and the agent runtime's tools resolve through their slots too, keeping the <CAP>_<VENDOR>_ENABLED=false switches in force. #1726 #1729 #1734 #1735 #1737 #1739 #1743

• openmaic.yml: the deployment's model configuration, read at startup from the working directory (/app in the Docker image) or the file OPENMAIC_CONFIG names (which must then exist). It declares providers ({ preset, apiKey, baseUrl, proxy, credentials, options }, from built-in presets including the four token plans and openai-compatible), slots, the server's defaults that users may change in the model settings (provider:model, a provider-only reference for search and document services, null, or { model, thinking, fallback, api, contextWindow }), lock ([slot, ...] or all: slots fixed for everyone, each with its whole subtree; every slot listed must be written under slots) and allowUserKeys (default true; false keeps users from adding providers, keys and token plans and stops using the ones they added). A policy key is refused, naming allowUserKeys. ${VAR} is interpolated in every string and an unset or empty variable is an error; the schema is strict and every problem is reported at once by its path, and an invalid file stops the server at startup. Without the file, the provider variables, server-providers.yml, DEFAULT_MODEL and MODEL_FALLBACK are translated at startup into providers and defaults (DEFAULT_MODEL for llm; the provider the server used to pick, or DEFAULT_IMAGE_PROVIDER, for the media, search and document roots) with a deprecation notice. A new openmaic.example.yml; Docker mounts the file at run time and .dockerignore keeps it out of images. The configuration docs are rebuilt around it, in every locale. #1727 #1731 #1732 #1737 #1742 #1744 #1750

• Model settings on the server: Token Plan, Model Services and Course Model Config read and write the workspace's model configuration through the new GET / PUT /api/model-config (one change per request against a revision; 409 CONFLICT, 409 SLOT_LOCKED for any slot in a locked subtree). The view carries each slot's source (default, workspace, locked, inherited with the slot it follows, or unconfigured), whether it is locked, the serverDefault written on it, and the deployment's allowUserKeys. The settings take one of three shapes derived from it: set it up yourself (allowUserKeys on: Token Plan, Model Services and Course Model Config), choose a model (allowUserKeys: false: only Course Model Config, among the deployment's providers) and configured by the administrator (everything locked: the course model diagram, every card read-only). A control is shown only where using it can change something: a Model Services tab and adding a service only while its capability has a slot a user may set, Token Plan only while a plan can fill a slot that is not locked (connecting never touches a locked one), a locked card as one read-only line marked Fixed by the administrator, a card on a server default marked Server default with Reset to server default once changed, and the home page model picker only when the default model can be changed (llm not locked, a language model to pick). Model Services keeps one tab per capability with its services: a service's key (write-only, shown masked), endpoint (chat services only) and model list are its workspace provider, and the deployment's services are shown read-only. Course Model Config is the course model map: each slot with its effective model and where it comes from, edited on the card (follow the parent, a model, off, a fallback, the thinking settings of a chat slot's own model); a capability's switch sets its slot to null and restores what it held. Connecting a token plan adds its provider and applies its recommended configuration (asking first before it replaces assignments the workspace made); disconnecting removes it. Test buttons and model lists name the saved provider (provider / model on the verify routes and probe-models, previewProvider / previewModel on speech and transcription), so no key leaves the browser. A workspace's settings are stored per owner in PostgreSQL with keys encrypted at rest (AES-256-GCM under the instance secret) and move with a claim. Workspace providers may not use Bedrock, a proxy or a key pair; a custom base URL is for chat presets only, validated as a caller-supplied endpoint; media, search and document services use their preset's public endpoint, except Azure Speech's official regional endpoints. The generation toolbar's model picker sets the default model (llm) with its thinking settings, which every slot that follows it uses (stages with a model of their own are shown in Course Model Config); the material popover's extractor select sets the document slot. #1733 #1740 #1741 #1744 #1767 #1780 #1781 #1784

• One-time import of browser model settings (temporary): the settings store's migration turns what a browser kept (providers with keys or custom endpoints, enrolled token plans, the chosen model, per-capability selections, an explicit "speech input off") into a proposal for POST /api/model-config/import, staged before any field is dropped and sent through the legacy importer's binding. The import adds only what the workspace and the deployment do not already have and lists what it skipped; per-stage routes and the old per-browser media toggles are not imported. A setting leaves the browser only once the answer shows the workspace holding it (a provider only when the server holds the same key); anything skipped, refused or unconfirmed stays in the browser with its keys and is listed in Settings → Model Services until it is set up again or discarded (see Upgrade notes). #1744 #1784 #1785 #1787

• Generation runs (#1754, E): a run is an owner-scoped PostgreSQL record (new schema store generation-runs: runs, per-step checkpoints, an ordered event log and idempotent commands) that executes the classic pipeline with the step functions shared with the routes (research, outline, agents, then per scene content, actions and narration) and commits a checkpoint after every step. A worker runs in every server process, whether or not OPENMAIC_AGENT_RUNTIME_ENABLED is set; another process takes a run over from its last checkpoint when its worker dies, and a step whose workers keep dying pauses the run. States: preparing → outlining → awaiting_outline_confirmation → generating → completed, plus paused (a step failed after its retries; Retry re-runs that step only) and ended (the course was deleted, or a run without a course discarded). The outline always waits for confirm-outline ({ outlineRevision, outlines?, commandId }) holding no worker, unless the run was started with outlineReview: "auto". The course is created with the first scene, scenes are appended as they are narrated, and completion sets generationComplete. API (owner-scoped; another owner's run answers 404): POST /api/generation-runs, GET /api/generation-runs?active=1, GET / DELETE /api/generation-runs/<id>, GET /api/generation-runs/<id>/events?after=<seq> (SSE with replay, resync and heartbeat), POST …/confirm-outline, POST …/retry and GET /api/generation-runs/events (the owner's run changes). Limits: OPENMAIC_MAX_ACTIVE_RUNS_PER_OWNER (default 2), OPENMAIC_MAX_WAITING_RUNS_PER_OWNER (10), OPENMAIC_GENERATION_RUN_MAX_CONCURRENT runs per process (4) and OPENMAIC_GENERATION_RUN_STREAMS_PER_OWNER (16); finished runs are compacted after OPENMAIC_GENERATION_RUN_RETENTION_HOURS (24). Outlines are capped at 100 scenes and 512 KiB, also in browser generation. #1756 #1759

• Generation runs: a media lane generates the images and videos the outline asks for once the course exists, alongside the scenes and one item at a time, with a checkpoint per item: stored bytes commit with their checkpoint, a takeover places them instead of paying again, and a video takeover resumes the provider task it recorded. A slot that is off or unassigned skips its kind; a media failure never pauses the run and carries the route's code (CONTENT_SENSITIVE, GENERATION_DISABLED, MISSING_MODEL, ASSET_QUOTA_EXCEEDED, MEDIA_PLACEMENT_FAILED, MEDIA_ELEMENT_REMOVED). POST …/retry with { commandId, media: { elementId } } runs one failed or skipped item again, also after completion, when its result is written into the current course without touching the author's other edits. The run snapshot includes media, and media events report each item. Images found in uploaded materials are stored as assets of the course and can be placed on slides. #1761

• Course materials are extracted when they are uploaded (#1754, E): POST /api/materials starts the extraction in the background (?extract=false defers it), and GET /api/materials/<id> (and the owner's list, GET /api/materials without sessionId) reports its extraction: extracting, ready (with textChars, pageCount, imageCount and what a course leaves out, truncated), or failed with the extractor's error; POST /api/materials/<id>/extraction extracts a failed one again. A background extractor in every server process holds each extraction under a lease (a restart resumes it; OPENMAIC_MATERIAL_EXTRACTION_CONCURRENCY, default 2), lets owners take turns (OPENMAIC_MATERIAL_EXTRACTION_PER_OWNER, default 2 running per owner), and stops the extractor's requests and commands when the material is deleted or the extraction runs out of time. The same file uploaded again by the same owner reuses its finished extraction when it would be extracted the same way (same type and services). The stored result counts against the owner's byte quota (checked when it is published; over it fails with MATERIAL_QUOTA_EXCEEDED) and is capped (OPENMAIC_MATERIAL_EXTRACTION_MAX_RESULT_MB, default 100; larger fails with EXTRACTION_RESULT_TOO_LARGE). Uploads no run or agent session uses are deleted once unread for OPENMAIC_UNUSED_MATERIAL_TTL_HOURS (default 24); an open composer reads its materials back to keep them, and the same sweep removes result files no attempt published. A run reads the stored extraction, waits for one still running, and fails with a failed one's error (Retry extracts it again). The composer uploads a file as soon as it is attached and shows its progress, parsing (or transcribing), ready or failed with Retry on the material; Generate waits until every material is ready, and the preview then opens without a material analysis. What a course leaves out of a long material is shown on the material instead of in the preview.

Bug Fixes

• Pro workspace: the course list shows a placeholder for a classic generation from the moment it starts, matching the home page's card (title, state, and opening the generation preview), and turns it into the course in place once the course exists.
• Pro workspace: a course that is still being generated shows its progress in the course list and a "being generated" placeholder in the classroom pane instead of a blank pane; it cannot be opened or @-mentioned until it completes, then opens automatically, and the agent is told it is read-only until generation completes.
• Classic generation no longer stalls at the outline when the preview is closed: the short pause before an outline continues now runs on the server (outlineReview: "countdown", generation-runs migration 4), so the run continues with no page open, while opening the review mid-stream or during the pause holds it (POST /api/generation-runs/<id>/hold-outline) for editing as before; with "Always review outlines before generation" on, the run waits for the learner's confirmation in any tab.
• Home: the composer no longer keeps the last requirement as a draft; Generate creates the course card at once.
• Home: video thumbnails no longer leave failed requests in the browser's network panel on every load; each video is drawn from its poster, or from its opening frame (decoded once and cached) when it has none.
• Home: the course list shows as soon as the library loads, instead of waiting for every course's content and first-slide media; thumbnails load as cards come into view, a few at a time.
• Home: while the page loads, it shows its hero and a skeleton of the course library instead of a blank grey screen (in dark mode too), and the courses take the skeleton's place without moving.
• Home: course thumbnails are kept in the browser's local cache, so a reload shows unchanged courses at once without downloading their content and media again; a course that changed is read again, and Settings → Clear Local Cache clears them.
• Composer: the document extractor picker in the course-material popover is hidden when the deployment locks the document slot (lock: [document] or lock: all); uploading stays available.
• Token Plan: connecting TokenDance also assigns the Pro agent (agent) to deepseek-v4.1-flash; the default model stays the plan's own.
• Classroom: the page no longer logs a 404 for /api/persistence/runtime/sessions/whiteboard:… on every load and whiteboard open before anything was drawn; the learner whiteboard loads from the session listing.
• Pro workspace: a course generated on the server no longer shows a "Read-only" badge to its owner; only a course saved from Discover, or one still being generated, is shown read-only.
• Settings: with every slot locked (lock: all), Token Plan and Model Services are hidden, including a plan the workspace connected earlier and the Text-to-Speech tab for user voices; only the read-only course model map remains.
• Generation preview: no "document parsing" step any more. Materials are extracted when they are attached, so the run's material step is not shown; a failure there still pauses the run with Retry.
• Composer: the course-material popover lists materials as compact rows on the popover's type scale, with file-type icons, a thin progress bar and icon buttons for Retry and Remove.
• Editor: slide elements can be dragged, resized and rotated in Safari; the Pro-mode editor no longer throws on mouse-down where the TouchEvent API is missing (desktop Safari).
• Settings: Model Services scrolls its list to the selected service (by default the one in use, such as a connected token plan's provider further down the list), and the selected row no longer looks like the promoted first row, so the list always highlights the service the panel shows.
• Owner identity: a browser's first load establishes one anonymous owner. The page response now sets the anonymous_id cookie (same value format and attributes as before) when the request carries no valid one and neither OWNER_SINGLE_USER nor PERSISTENCE_SHARED_OWNER_ID is set, so the page's concurrent first API requests no longer each mint an owner and overwrite one another's cookie; a valid cookie is never replaced. POST /api/identity/legacy-import-binding binds only an owner the browser already presented (a request that minted its owner answers 409 OWNER_NOT_ESTABLISHED and the importer retries on a later load), so the legacy import can no longer be bound to an owner whose cookie a later response replaced and then stall with 409 LEGACY_IMPORT_NOT_BOUND. OWNER_ANONYMOUS_PREMINT=false turns page minting off (default on; a malformed value fails startup). Set it only when registered owner auth methods set anonymousFallback: false, and the server warns at startup when such a registration leaves it on; hosts that keep anonymous visitors keep it and skip it per request in middleware.ts for requests their methods authenticate (see "Registering methods" in the README).
• Owner identity: the anonymous identity lasts 400 days (the longest browsers keep a cookie) instead of 30, and is renewed while in use: every route handler and Server Action response that resolves to a valid anonymous cookie re-sends the same value with a fresh Max-Age, so an active visitor no longer loses the whole library 30 days after the first visit. Page responses do not renew it, so pages stay cacheable, and a response that clears the cookie (a claim, a retired owner) never renews it.
• Server persistence: the course library and folders work without the agent runtime. /api/stages/** (list, create, read, save, delete, manifest, scenes, freshness, status, generation-complete, publish, unpublish) and /api/folders/** now gate on DATABASE_URL alone instead of also requiring OPENMAIC_AGENT_RUNTIME_ENABLED, so a deployment with server persistence and the runtime off no longer answers 404 there and shows an empty, unavailable library. Agent routes (/api/agent/**, /api/skills/**) and the session-scoped material reads (GET /api/materials, GET /api/materials/<id>) still require the runtime, while uploading to and deleting from the owner's material library (POST /api/materials, DELETE /api/materials/<id>) needs only DATABASE_URL, and without a DATABASE_URL everything answers 404 as before. GET /api/agent/runtime also reports persistence.
• Startup: a configuration refused by the boot validation in instrumentation.ts (a malformed ASSET_QUOTA_BYTES, ASSET_PENDING_TTL_MS, OWNER_WRITE_LOCK_WAIT_MS or OWNER_CLAIM_LOCK_WAIT_MS; an OWNER_CLAIM_TRIGGER other than explicit / auto; the removed OWNER_AUTHENTICATOR / TRUSTED_PROXY_* variables; a malformed PERSISTENCE_SHARED_OWNER_ID, one without ACCESS_CODE or beside a registration that leaves out sharedTeamAuthMethod(), or sharedTeamAuthMethod() registered without it or not last; ASSET_S3_BUCKET beside a registered asset byte store, or ASSET_BYTE_EGRESS=redirect with a byte store that does not declare signsReadUrls) now exits the Node.js server with code 1 after one [boot] Invalid server configuration line carrying the original message. Any other boot failure (a module missing from the build, a host registration call that throws) also exits with code 1, printed as [boot] Server startup failed with its stack. Previously the server logged "Failed to prepare server", kept listening, and answered every request with 500. Warnings never stop the server.
• Server persistence: two concurrent creates of one new course id by the same owner no longer refuse the second as reserved-document: creates of one id take turns, and the second saves as an update without running the create hooks again.
• Server persistence: instances starting at the same time against one database no longer fail schema setup on a catalog race (duplicate key value violates unique constraint "pg_class_relname_nsp_index" / pg_type_typname_nsp_index, tuple concurrently updated), which made an instance's first request answer 500. Every schema bootstrap (documents, stage_meta and its ownership backfill, owner materials, assets, runtime, agent sessions, session materials, user skills, and the asset collector's) now runs under one PostgreSQL advisory lock held on a dedicated connection.

Security

• Server persistence: operations on one owner-bound document store no longer share mutable state, so concurrent calls on a store an agent run shares with its tools each gate their own stage; create_stage also runs sequentially within a tool batch.
• Server persistence: runtime data of a deleted course reads as absent and takes no new writes, however the request path is spelled.
• @openmaic/storage 0.32.0: PgDocumentStore takes assetReferencePrincipals (and AssetCollector a matching per-owner function) so a document write can no longer commit or pin another principal's asset entry; a store can refuse createSession with RuntimeStageNotFoundError (404 STAGE_NOT_FOUND); and a session create over a taken id answers 409 SESSION_ALREADY_EXISTS whoever holds it, instead of 403 for another learner's session.