@entrinsik/vite-plugin-informer 2.11.0 → 2.13.0

package/README.md

@@ -13,6 +13,8 @@ npm run dev                                # local dev against the Informer in .
 npm run deploy                             # assemble + upload + deploy
 ```
 
+`informer-init` leaves an existing `@entrinsik/vite-plugin-informer` entry alone, and writes one only when the dependency is missing — in which case it uses its own version (2.12.0 and later; before that it wrote `^1.0.0`). A project scaffolded earlier still carries `^1.0.0`, which resolves to 1.0.5 and predates everything below: bump it by hand.
+
 ## What a deploy ships
 
 The assembler uploads your built frontend plus these source trees, matching how an App's library is structured in Informer:
@@ -23,7 +25,7 @@ The assembler uploads your built frontend plus these source trees, matching how
 | `webhooks/` | Publicly callable webhook routes |
 | `tools/` | AI tools, private to the App's agents |
 | `mcp/` | Tools exposed over the App's MCP endpoint |
-| `channels/` | Live channel handlers: `join` / `joined` / `leave` and event-named handlers for `channel.send()`; `npm run dev` runs them locally, and the `channels:` block in `informer.yaml` declares relays only (each entry needs `on`) |
+| `channels/` | Live channel handlers: `join` / `joined` / `leave` and event-named handlers for `channel.send()`, or a channel actor (`config.actor`: one live instance per channel, with `start` / `tick` / `stop` / `snapshot`); `npm run dev` runs both locally, and the `channels:` block in `informer.yaml` declares relays only (each entry needs `on`) |
 | `migrations/` | Workspace database migrations, run in order on deploy |
 | `embeddings/` | Declarative embedding use cases (see below) |
 | `lib/`, `shared/` | Modules importable by the trees above |
@@ -44,7 +46,9 @@ Against an older server the CLI:
 
 A server whose version isn't comparable (a `dev` build, or an `/about` behind a proxy) is treated as current and warned about — gating it would break deploys to builds made from source.
 
-App Channels phase 2 (plugin 2.11.0: `channel.send()`, the `joined` export and event-named exports in `channels/` files, wildcard subscriptions, frame `seq` and replay, `connected`) needs a 2026.1.3 server that carries I5-13027. The version probe cannot tell such a server from an earlier 2026.1.3 build, so the deploy is not gated: an earlier build refuses a `channels/` file that exports `joined` or an event name, and accepts a `channels:` entry without `on` that a current server rejects. The dev server runs the phase 2 contract regardless.
+App Channels phase 2 (plugin ≥ 2.11.0: `channel.send()`, the `joined` export and event-named exports in `channels/` files, wildcard subscriptions, frame `seq` and replay, `connected`) needs a 2026.1.3 server that carries I5-13027. The version probe cannot tell such a server from an earlier 2026.1.3 build, so the deploy is not gated: an earlier build refuses a `channels/` file that exports `joined` or an event name, and accepts a `channels:` entry without `on` that a current server rejects. The dev server runs the phase 2 contract regardless; plugin 2.12.0 aligns its channel semantics with the server's (wildcard gating, replay expiry, and the per-user send budget), so on 2.11.0 the dev mirror has the phase 2 surface but not all of its behavior.
+
+Channel actors (plugin ≥ 2.13.0: `config.actor` files, `request.member`, `__INFORMER__.serverNow()`) need a server that reports `platform.capabilities.channelActors`; on one that does not, the same file runs as an ordinary channel handler, one fresh module per message. Under `npm run dev` each concrete channel gets its own module instance, calls run one at a time, `tick()` runs on a timer, and the actor stops `idleMs` after its last page leaves. `snapshot()` is kept in memory, so editing a file under `channels/`, `shared/`, `lib/` or `server/` restarts the running actors on the new code from their snapshots with the same pages subscribed: a game in progress survives the edit. The server's cluster, leases, billing and broadcast limits have no dev counterpart.
 
 Feature-detect at runtime with optional chaining, since `platform` is absent entirely before 2026.1.3:
 
@@ -118,11 +122,11 @@ const hits = await query(
 
 ### Dev loop
 
-`npm run deploy` uploads `embeddings/` like any other source tree — there is no manifest block to add (plugin ≥ 2.10.0; earlier versions never upload the folder, so the use case silently does not exist on the server). `npm run dev` never runs the pump, and its `embed()` throws an explanation rather than embedding (the dev mirror reports `platform.capabilities.embeddings: false`), so a search route is exercised against a deployed App. Feature-detect with `platform?.capabilities?.embeddings` — `typeof embed === 'function'` is true on both, since the binding exists either way. Then, in the App admin panel, the **Embeddings** tab lists each use case with its pump status (queued, running, up to date, last run, last error, skipped docs) and a **Run now** action; the same surface exists as API routes (`GET /apps/{id}/embeddings`, `POST /apps/{id}/embeddings/{name}/_run`). Deploy, run, read the error, fix, repeat.
+`npm run deploy` uploads `embeddings/` like any other source tree — there is no manifest block to add (plugin ≥ 2.10.0; earlier versions never upload the folder, so the use case silently does not exist on the server). `npm run dev` never runs the pump, and its `embed()` throws an explanation rather than embedding (the dev mirror reports `platform.capabilities.embeddings: false`), so a search route is exercised against a deployed App. Plugin ≥ 2.12.0 can opt in: `informer({ mock: { platform: { capabilities: { embeddings: true } } } })` binds the dev `embed()` to the deployed App's `_embed` route on the configured server (addressed by package.json `informer.id`; the dev credentials need write access to that App, and each call is billed to it), so the query vector under `npm run dev` is the deployed one — same model, same `revision`. The corpus is not: `query()` still reads the dev workspace datasource, which the pump never writes to, so a search route compares a deployed vector against local rows. Feature-detect with `platform?.capabilities?.embeddings` — `typeof embed === 'function'` is true on both, since the binding exists either way. Then, in the App admin panel, the **Embeddings** tab lists each use case with its pump status (queued, running, up to date, last run, last error, skipped docs) and a **Run now** action; the same surface exists as API routes (`GET /apps/{id}/embeddings`, `POST /apps/{id}/embeddings/{name}/_run`). Deploy, run, read the error, fix, repeat.
 
 ### Upgrading an App that already has an `embeddings/` folder
 
-`embeddings/` is a server-side folder from this release on, like `server/`: its files are uploaded with the library, never served to browsers, and scanned as pump handlers. An App that kept anything else there (assets, data files) loses those files in the browser after redeploying with plugin 2.10.0 or later. A `.js` file there that exports `GET` or `POST` but not both fails the deploy; one that exports neither is never scanned as a use case at all and lands as a warning on an otherwise successful deploy. Move such content elsewhere before upgrading; the deploy names every stray entry as a warning.
+`embeddings/` is a server-side folder from Informer 2026.1.3 on, like `server/`: its files are uploaded with the library, never served to browsers, and scanned as pump handlers. An App that kept anything else there (assets, data files) loses those files in the browser after redeploying with plugin 2.10.0 or later. A `.js` file there that exports `GET` or `POST` but not both fails the deploy; one that exports neither is never scanned as a use case at all and lands as a warning on an otherwise successful deploy. Move such content elsewhere before upgrading; the deploy names every stray entry as a warning.
 
 ### Older Informer releases
 

package/bin/deploy.js

@@ -82,5 +82,8 @@ try {
     }
 } catch (err) {
     console.error('Deploy failed:', err.message);
+    // The server's own message carries the recovery instruction; err.message is
+    // only the status line.
+    if (err.detail) console.error(err.detail);
     process.exit(1);
 }

package/bin/init.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { readFile, writeFile, access } from 'node:fs/promises';
 import { resolve, basename } from 'node:path';
 import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
@@ -118,6 +118,16 @@ function prompt(question, defaultValue) {
     });
 }
 
+/**
+ * The devDependency range a fresh scaffold gets. Read inside init() rather than
+ * at module scope so a failure reaches init()'s error handler.
+ */
+async function pluginVersionRange() {
+    const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    if (!version) throw new Error('could not read the version of @entrinsik/vite-plugin-informer; reinstall the plugin');
+    return `^${version}`;
+}
+
 /**
  * Convert package name to friendly display name.
  * "magic-quickbooks-report" -> "Magic Quickbooks Report"
@@ -174,7 +184,8 @@ async function init() {
     // 5. Add plugin to dependencies if not present
     if (!pkg.devDependencies) pkg.devDependencies = {};
     if (!pkg.devDependencies['@entrinsik/vite-plugin-informer']) {
-        pkg.devDependencies['@entrinsik/vite-plugin-informer'] = '^1.0.0';
+        // Float the scaffold on the version that scaffolded it, not a fixed range.
+        pkg.devDependencies['@entrinsik/vite-plugin-informer'] = await pluginVersionRange();
         console.log('Added @entrinsik/vite-plugin-informer to devDependencies');
     }
 

package/index.d.ts

@@ -2,12 +2,14 @@ import type { Plugin } from 'vite';
 
 /**
  * Dev-only binding for a `target: app` or `target: pack` dependency slot.
- * Points `request()` at the target app in dev. For app slots it overrides the
- * manifest `defaultBinding` when both are present; for pack slots it is the
- * only way to bind — the marketplace pin has no install to resolve against in
- * dev, so point it at your locally-installed copy of the pack's app.
+ * Points `request()` and `url()` at the target app in dev. For app slots it
+ * overrides the manifest `defaultBinding` when both are present; for pack
+ * slots it is the only way to bind — the marketplace pin has no install to
+ * resolve against in dev, so point it at your locally-installed copy of the
+ * pack's app.
  *
- * - `app` — the target app (`owner:slug` or UUID). Powers `request()`.
+ * - `app` — the target app (`owner:slug` or UUID). Powers `request()`, and
+ *   names the app `url()` links into (on `INFORMER_URL`).
  *
  * A bare string is shorthand for `{ app }`.
  */
@@ -15,11 +17,25 @@ export interface AppDevBinding {
     app?: string;
 }
 
+/**
+ * What the platform offers the app, as the server injects it
+ * (`window.__INFORMER__.platform`). A mock override merges into the dev
+ * defaults, so naming one capability leaves the rest alone.
+ */
+export interface MockPlatform {
+    version?: string;
+    originMode?: boolean;
+    capabilities?: Record<string, boolean>;
+}
+
 export interface InformerPluginOptions {
     mock?: {
         report?: { id?: string; name?: string };
         theme?: 'light' | 'dark';
         roles?: string[];
+        /** The viewer identity, for testing `@user/<username>` channels as someone else. */
+        user?: { username?: string; displayName?: string };
+        platform?: MockPlatform;
     };
     devBindings?: Record<string, string | AppDevBinding>;
     proxy?: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.11.0",
+    "version": "2.13.0",
     "description": "Vite plugin and deploy tool for Informer App development",
     "scripts": {
         "test": "node --test"

package/src/agent-dev.js

@@ -4,15 +4,7 @@ import { parse as parseUrl } from 'node:url';
 import yaml from 'yaml';
 import { manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
 import { createDevChannels, createDevEmit } from './dev-channels.js';
-import { devPlatform } from './dev-platform.js';
-
-// embed() is present on a real install even without the embeddings
-// capability, where it throws a written explanation. Mirroring that here
-// keeps the dev failure the same lesson as the deployed one, instead of a
-// bare "embed is not a function" that reads like a missing binding.
-const embed = async () => {
-    throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
-};
+import { devPlatform, createDevEmbed } from './dev-platform.js';
 
 const parseYaml = yaml.parse;
 
@@ -164,7 +156,7 @@ async function readSSE(response) {
  *   behind `broadcast()` and the `channels:` relay (a private one when omitted)
  * @returns {Function} Connect middleware
  */
-export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels = createDevChannels() }) {
+export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels = createDevChannels(), platform = devPlatform(), appId = null }) {
 
     // query() — proxies to the workspace _sql endpoint (same as server-routes.js)
     async function query(sql, params) {
@@ -223,6 +215,11 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
         return { status, body, contentType };
     }
 
+    // Throws the written explanation unless the mock platform opts into
+    // embeddings; then posts to the deployed app's _embed route through
+    // apiFetch (hoisted below). See createDevEmbed.
+    const embed = createDevEmbed({ platform, apiFetch, appId });
+
     async function apiFetch(path, opts = {}) {
         return await fetchAs(authHeader, path, opts);
     }
@@ -328,7 +325,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
                 // `context.<slot>.<method>(...)` and `env` work locally and match
                 // the prod sandbox bag. The manifest is already in hand.
                 const deps = manifestBlock(yaml, 'dependencies');
-                const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
+                const context = buildDevContext({ deps, apiFetch, devBindings, appFetch, serverOrigin });
                 const env = manifestBlock(yaml, 'env');
 
                 // emit() writes no app_event row in dev, but still relays a
@@ -455,7 +452,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
 
                         if (tool) {
                             try {
-                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: cryptoHelper, markdown, log, env, platform: devPlatform() });
+                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: cryptoHelper, markdown, log, env, platform });
                             } catch (err) {
                                 console.error(`[agent-dev] Tool "${tc.name}" failed:`, err.message);
                                 result = { error: err.message };

package/src/client.js

@@ -2,6 +2,26 @@
  * Informer API client using native fetch with Basic auth.
  */
 
+/**
+ * The server's own explanation, dug out of an error body.
+ *
+ * Boom replies carry the useful sentence in `message`, and for a refused deploy
+ * that sentence is the whole value of the response — it names the call that
+ * unblocks the app. A bare status line leaves the author with nothing to act on.
+ *
+ * @param {string} body - raw response body
+ * @returns {string} the server's message, or '' when the body says nothing
+ */
+function errorDetail(body) {
+    if (!body) return '';
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.message || parsed.error || '';
+    } catch {
+        return String(body).trim().slice(0, 500);
+    }
+}
+
 class InformerApiError extends Error {
     constructor(status, statusText, body, url) {
         super(`Informer API ${status} ${statusText}${url ? ` (${url})` : ''}`);
@@ -9,6 +29,7 @@ class InformerApiError extends Error {
         this.status = status;
         this.statusText = statusText;
         this.body = body;
+        this.detail = errorDetail(body);
         this.url = url;
     }
 }
@@ -63,7 +84,7 @@ export function createClient({ baseUrl, apiKey, user, pass }) {
      * Upload a file using chunked Flow.js protocol, then assemble into an entity's library.
      * @param {{ entityPath?: string, reportId?: string, path: string, buffer: Buffer, filename: string }} opts
      */
-    async function uploadChunked({ entityPath, reportId, path, buffer, filename }) {
+    async function uploadChunked({ entityPath, reportId, path, buffer, filename, stagingLibraryId }) {
         const basePath = entityPath || `reports/${reportId}`;
         const totalChunks = Math.ceil(buffer.length / CHUNK_SIZE);
         const uploadId = `publish-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
@@ -98,14 +119,19 @@ export function createClient({ baseUrl, apiKey, user, pass }) {
             }
         }
 
-        // Assemble chunks into a file in the entity's library at the specified path
+        // Assemble chunks into a file in the entity's library at the specified
+        // path. `stagingLibraryId` claims the in-flight deploy — without it the
+        // server refuses the write rather than folding it into someone else's
+        // build (see deploy-target.js).
         await request('POST', `${basePath}/_upload`, {
             uploadId,
-            path
+            path,
+            ...(stagingLibraryId ? { stagingLibraryId } : {})
         });
     }
 
     return {
+        baseUrl: origin,
         get: (path) => request('GET', path),
         post: (path, body) => request('POST', path, body),
         put: (path, body) => request('PUT', path, body),

package/src/deploy.js

@@ -71,19 +71,18 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         };
         if (id) payload.id = id;
 
-        try {
-            console.log(`Creating new app "${name}"...`);
-            entity = await api.post('apps', { ...payload, type: 'app' });
-            apiPrefix = 'apps';
-        } catch (e) {
-            // If apps endpoint doesn't exist (404), fall back to legacy reports
-            if (e.status === 404) {
-                console.log('Apps API not available, using legacy reports API...');
-                entity = await api.post('reports', { ...payload, type: 'magicReport' });
-                apiPrefix = 'reports';
-            } else {
-                throw e;
-            }
+        console.log(`Creating new app "${name}"...`);
+        entity = await api.post('apps', { ...payload, type: 'app' });
+        apiPrefix = 'apps';
+
+        // Null, not a throw: client.js turns a 404 into a null reply, so the
+        // legacy-reports fallback has to branch on the value. As a catch on
+        // `e.status === 404` it could never fire, and a genuine missing-apps-API
+        // surfaced as "Failed to create" instead of falling back.
+        if (entity === null) {
+            console.log('Apps API not available, using legacy reports API...');
+            entity = await api.post('reports', { ...payload, type: 'magicReport' });
+            apiPrefix = 'reports';
         }
 
         if (!entity || !entity.id) {
@@ -116,9 +115,10 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         limit: 10
     });
 
-    // 5. Clear existing files in one server-side transaction
-    console.log('Clearing existing files...');
-    await api.post(`${entityPath}/files/_clear`);
+    // 5. Open a staging library so the upload pass below doesn't touch what the
+    //    app is currently serving.
+    console.log('Staging deploy...');
+    const stagingLibraryId = await openStagingDeploy(api, entityPath);
 
     // 6. Upload the app-library file set assembled in step 0: dist output at the
     //    library root, plus informer.yaml / data-access.yaml and the
@@ -126,37 +126,59 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     //    tree this server is too old to keep out of browsers (see compat.js).
     //    Sourced from the shared collectAppFiles() so a deploy and a marketplace
     //    publish package byte-identical contents.
-    console.log('Uploading files...');
+    //
+    //    Everything from here until the deploy completes runs inside the try, so
+    //    nothing can leave the app staged: a live staging pointer redirects later
+    //    content writes into a library nothing serves while reads keep returning
+    //    the old build, and the routes that cannot redirect refuse with 409
+    //    (I5-12961). `files` is declared outside the try so step 13 can still
+    //    report on it once the staging lock has released.
     const files = plan.files;
+    let deployed = false;
+    const releaseStaging = installStagingSignalHandlers(api, entityPath, stagingLibraryId);
+    try {
+        console.log('Uploading files...');
 
-    for (const { abs, rel } of files) {
-        const content = await readFile(abs);
-
-        if (content.length > CHUNK_THRESHOLD) {
-            // Large file: chunked upload via Flow.js protocol
-            await api.uploadChunked({
-                entityPath,
-                path: rel,
-                buffer: content,
-                filename: basename(abs)
-            });
-            console.log(`  ${rel} (${formatSize(content.length)}, chunked)`);
-        } else {
-            // Small file: direct JSON upload
-            const ext = '.' + rel.split('.').pop();
-            const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
-            const payload = isText
-                ? { content: content.toString('utf8'), encoding: 'utf8' }
-                : { content: content.toString('base64'), encoding: 'base64' };
-
-            await api.put(`${entityPath}/contents/${rel}`, payload);
-            console.log(`  ${rel}`);
+        // Presented on every write so the server folds it into THIS deploy. A
+        // write that doesn't claim the staging library is refused rather than
+        // quietly joining it (see deploy-target.js). Empty on the _clear
+        // fallback, where there is no staging library to claim.
+        const claim = stagingLibraryId ? { stagingLibraryId } : {};
+
+        for (const { abs, rel } of files) {
+            const content = await readFile(abs);
+
+            if (content.length > CHUNK_THRESHOLD) {
+                // Large file: chunked upload via Flow.js protocol
+                await api.uploadChunked({
+                    entityPath,
+                    path: rel,
+                    buffer: content,
+                    filename: basename(abs),
+                    stagingLibraryId
+                });
+                console.log(`  ${rel} (${formatSize(content.length)}, chunked)`);
+            } else {
+                // Small file: direct JSON upload
+                const ext = '.' + rel.split('.').pop();
+                const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
+                const payload = isText
+                    ? { content: content.toString('utf8'), encoding: 'utf8', ...claim }
+                    : { content: content.toString('base64'), encoding: 'base64', ...claim };
+
+                await api.put(`${entityPath}/contents/${rel}`, payload);
+                console.log(`  ${rel}`);
+            }
         }
-    }
 
-    // 12. Deploy: run migrations + scan/bundle server routes + webhooks + embeddings + tools + agents
-    if (apiPrefix === 'apps') {
-        await runServerDeploy(api, entityPath);
+        // 12. Deploy: run migrations + scan/bundle server routes + webhooks + embeddings + tools + agents
+        if (apiPrefix === 'apps') {
+            await runServerDeploy(api, entityPath, stagingLibraryId);
+        }
+        deployed = true;
+    } finally {
+        releaseStaging();
+        if (stagingLibraryId && !deployed) await discardStaging(api, entityPath, stagingLibraryId);
     }
 
     // 13. Print URL and return UUID for saving
@@ -170,6 +192,129 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     return { id: entity.id, url: entityUrl };
 }
 
+/**
+ * Discard this deploy's staged upload so a failure doesn't leave the app locked.
+ *
+ * Presents the id so a cleanup can never destroy a DIFFERENT deploy's in-flight
+ * upload, and is best-effort: the original failure is what the user needs to
+ * see, so a cleanup problem is reported but never replaces it.
+ *
+ * @param {Object} api - Informer API client
+ * @param {string} entityPath
+ * @param {string} stagingLibraryId
+ */
+export async function discardStaging(api, entityPath, stagingLibraryId) {
+    try {
+        await api.del(`${entityPath}/files/_stage?stagingLibraryId=${encodeURIComponent(stagingLibraryId)}`);
+        console.log('Discarded the staged upload; the app is unchanged and editable.');
+    } catch (cleanupErr) {
+        console.log(`Could not discard the staged upload (${cleanupErr.message}).`);
+        console.log(`The app will keep redirecting content edits until it is cleared.`);
+        console.log(`Run: DELETE ${entityPath}/files/_stage`);
+    }
+}
+
+/**
+ * Discard the staged upload if the process is interrupted.
+ *
+ * Ctrl-C during a long upload is an ordinary way to end a deploy, and without a
+ * handler it leaves the app staged with no cleanup at all. Returns a function
+ * that removes the handlers so a completed deploy doesn't keep them installed.
+ *
+ * @returns {Function} release
+ */
+function installStagingSignalHandlers(api, entityPath, stagingLibraryId) {
+    if (!stagingLibraryId) return () => {};
+
+    // A second Ctrl-C during the cleanup await would re-enter and start a
+    // competing discard, so the first one wins and later signals exit at once.
+    let discarding = false;
+
+    const handlers = ['SIGINT', 'SIGTERM'].map((signal) => {
+        const handler = async () => {
+            if (discarding) {
+                console.log(`\nInterrupted again; exiting without waiting for the discard.`);
+                process.exit(130);
+            }
+            discarding = true;
+            console.log(`\nInterrupted (${signal}); discarding the staged upload...`);
+            await discardStaging(api, entityPath, stagingLibraryId);
+            process.exit(130);
+        };
+        process.on(signal, handler);
+        return { signal, handler };
+    });
+
+    return () => handlers.forEach(({ signal, handler }) => process.off(signal, handler));
+}
+
+/**
+ * POST `files/_stage`: open a staging library for this deploy.
+ *
+ * Everything uploaded afterwards lands in the staging library while the app
+ * goes on serving its current one; POST `_deploy`, given this library's id,
+ * then replaces the live library's files with the staged ones inside a single
+ * transaction. That is what keeps an app usable, and complete, for the
+ * whole length of its own deploy (I5-12961).
+ *
+ * Falls back to the old wipe-then-upload flow against a server with no _stage
+ * route. That flow is precisely what staging exists to avoid, so it announces
+ * itself rather than degrading silently.
+ *
+ * Note the null check rather than a try/catch: client.js turns a 404 into a
+ * `null` reply instead of throwing, so an unsupported route arrives here as a
+ * value, not an exception.
+ *
+ * @param {Object} api - Informer API client
+ * @param {string} entityPath - e.g. `apps/team:my-app`
+ * @returns {Promise<string|null>} staging library id to present at deploy time, or
+ *   null when it fell back to _clear and there is nothing to promote
+ */
+export async function openStagingDeploy(api, entityPath) {
+    let staged;
+    try {
+        staged = await api.post(`${entityPath}/files/_stage`);
+    } catch (err) {
+        // 409 means a previous deploy died and left its upload staged. The
+        // server refuses to stage over it (destroying it silently is how two
+        // deploys interleave), so the app stays locked until someone discards
+        // it — and this message is the only place that instruction appears.
+        if (err.status === 409) {
+            const base = api.baseUrl ? `${api.baseUrl}/api` : '<informer-url>/api';
+            throw new Error(
+                `${err.detail || 'This app already has a staged upload from an earlier deploy.'}\n\n`
+                + `A previous deploy did not finish and left its upload staged. Discard it, then re-run this deploy:\n`
+                + `  curl -u <user>:<pass> -X DELETE '${base}/${entityPath}/files/_stage'`
+            );
+        }
+        throw err;
+    }
+
+    // `null` means 404 and ONLY 404 — client.js returns it for a missing route
+    // and throws for every other non-ok status. Any other falsy-id reply is a
+    // server that DID stage, so it must not take the destructive branch.
+    if (staged === null) {
+        console.log('  Server does not support staged deploys; clearing files instead.');
+        console.log('  The app will be unavailable to its users until this deploy finishes.');
+        await api.post(`${entityPath}/files/_clear`);
+        return null;
+    }
+
+    if (!staged.id) {
+        // _stage SUCCEEDED, so the server has already pointed the app at a
+        // staging library this deploy cannot name. Clearing here would empty the
+        // live library while every upload silently redirected into that staging
+        // library, and the unclaimed deploy would then publish the empty one.
+        throw new Error(
+            `POST ${entityPath}/files/_stage succeeded but returned no library id `
+            + `(got: ${JSON.stringify(staged).slice(0, 200)}). The app now has a staging library `
+            + `this deploy cannot claim. Nothing was uploaded or cleared.`
+        );
+    }
+
+    return staged.id;
+}
+
 /**
  * POST `_deploy`: run migrations, scan/bundle server routes, webhooks, tools and
  * agents, and claim the app as platform-managed.
@@ -179,8 +324,10 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
  *
  * @param {{post: (path: string, body?: unknown) => Promise<unknown>}} api
  * @param {string} entityPath e.g. `apps/my-app`
+ * @param {string} [stagingLibraryId] id returned by openStagingDeploy; presenting
+ *     it is what authorises the server to promote that staged upload
  */
-export async function runServerDeploy(api, entityPath) {
+export async function runServerDeploy(api, entityPath, stagingLibraryId) {
     try {
         console.log('Deploying...');
         // `managed: true` claims the app as platform-managed (origin
@@ -189,7 +336,13 @@ export async function runServerDeploy(api, entityPath) {
         // flag is absent, so the GO admin panel's Redeploy and the builder's
         // Save can share this route without converting user-built apps. See
         // app/routes/deploy.js.
-        const result = await api.post(`${entityPath}/_deploy`, { managed: true });
+        // Presenting the staged id is what authorises the server to promote that
+        // upload. Omitting it (the _clear fallback path) leaves the server
+        // deploying the live library, which is the pre-staging behaviour.
+        const result = await api.post(`${entityPath}/_deploy`, {
+            managed: true,
+            ...(stagingLibraryId ? { stagingLibraryId } : {})
+        });
         if (result === null) {
             // api.post turns a 404 into null instead of throwing, so this is the
             // only place it can be caught. Files uploaded, but migrations, server