gina 0.6.8 → 0.6.9

package/CHANGELOG.md

@@ -6,6 +6,24 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.6.9 - 2026-08-16
+### Added
+* `gina.pushToSession(sessionID, payload[, option][, callback])` — a sanctioned way to push to a session from OUTSIDE a request (#B366). `self.push()` needs a live request-bound controller, so code that has none (a `lib/job` handler, a cron tick, a boot hook) had no route to a user's socket at all; the pattern consumers reached for instead — a background worker making an HTTP hop carrying the user's session id in the request body — was the #B364 vulnerability, and closing it left that shape with nowhere to go. This is the replacement, and it is deliberately narrow. The recipient is a REQUIRED argument: an absent or empty `sessionID` is an error, never a fan-out, and no broadcast is reachable from this API at all — the deliberate all-clients send stays in-request as `self.push(payload, { broadcast: true })`. Source the recipient from server-held state (capture it when the work is queued, keep it server-side); round-tripping a recipient id, or a token naming one, through the browser hands the choice back to the caller and re-opens #B364 one layer up. Delivery is reported rather than assumed: `callback(err, { delivered })` fires exactly once with the number of sockets written, and `delivered: 0` is a normal outcome (the user closed the tab), not an error — the shape this replaces was fire-and-forget and blind. Errors carry a machine-readable `err.code` (`PUSH_INVALID_RECIPIENT`, `PUSH_INVALID_PAYLOAD`, `PUSH_CHANNEL_NOT_CONFIGURED`, `PUSH_CHANNEL_NOT_READY`, `PUSH_PAYLOAD_SERIALIZE_FAILED`). Requires the isaac engine with `settings.json > server.ioServer` attached; the express engine has no engine.io channel and now says so by name instead of failing as a 500. Available as `lib.push.toSession()` for code holding its own server instance.
+* A bundle can now declare which scopes it is deployed in, via an optional `scopes` allow-list on its `manifest.json` entry (#B373). Until now a registered bundle was deployed in EVERY scope, and the only way to exclude one was to leave it out of the manifest entirely — which removes it from all scopes at once. The motivating case is a bundle you are still building: `"scopes": ["local"]` keeps it running locally while every other scope behaves as though it does not exist. An ABSENT (or null) key means every scope, so existing manifests are completely unaffected; an empty array parks the bundle everywhere; and a value that is not an array is reported as a manifest error by name rather than silently read as "no scopes". The semantics deliberately mirror a route's rule-level `scopes`. How an exclusion is reported depends on whether you asked for it: the boot and `gina project:build` SKIP an excluded bundle with a notice naming the scope and the one-line remedy, so one parked bundle never blocks a project build; starting an excluded bundle, or naming it explicitly in `gina bundle:build <name> --scope=<scope>`, is REFUSED by name, because silently producing no artifact would read as success in a deploy script. Note that deleting a bundle's `releases.<scope>` entry by hand was never a working substitute for this: both build commands walk every scope in the project and re-create any missing release entry, so a hand-deleted one reappears on the next build. A `scopes` declaration also survives `gina project:add` and `gina project:import`: the long-standing manifest reset those commands used to perform on a bundle-count mismatch — which would have silently dropped this key — is fixed in this same release (#B375), so the declaration round-trips.
+### Fixed
+* `self.push()` now refuses by name when the server instance has no engine.io channel, instead of failing as an opaque 500 (#B371). The push channel is an isaac-engine facility — `serverInstance.eio` is attached there and nowhere else — so on the express engine the client lookup dereferenced an absent `eio` and surfaced as a TypeError-derived 500 whose message named neither push nor the missing channel, leaving "why is this route 500-ing?" as the only signal a developer got. It now warns, hands a supplied `callback` a `PUSH_CHANNEL_NOT_CONFIGURED` error, and sends nothing — WITHOUT failing the request, so a notification side-channel no longer takes down the response it rode in on. This is also the first time push() honours the `callback(err, result)` contract its own documentation has always described: the body accepted a callback and forwarded it to the transport, but never once invoked it itself. The condition is structural rather than per-call — the channel either exists in this process or it never will — so it is reported identically on every call, matching the refusal `gina.pushToSession()` gives for the same cause.
+* A bundle whose release tree cannot be linked now refuses to boot with a message naming the bundle, the env and the scope, instead of an opaque `TypeError` (#B372). The config loader links each registered bundle's release target for a non-dev env and, when that fails, builds a `[ releaseError ]` carrying the offending path — but the receiving callback never inspected its error argument and dereferenced the (absent) configuration object instead, so the useful reason was discarded and the process died on `TypeError: Cannot set properties of undefined (setting 'env')` as an uncaughtException. The server never binds, so a startup probe sees only a refused connection, and the error points at framework internals rather than at the path an operator has to fix. Because the configuration load is shared across the project, ONE bundle's missing release tree took down EVERY bundle in it. The error is now propagated and reported through the same sink the bundle-configuration loader already used — logged, flushed synchronously to stderr so the reason survives on an async pipe, then a clean exit 1. Note that omitting a bundle's `releases.<scope>` entry is NOT how you mark it as undeployed — that produces this same refusal rather than skipping the bundle. To exclude a bundle from a scope deliberately, use the `scopes` allow-list on its manifest entry, added in this same release.
+* The path helper's file copier — the byte-writer behind `_().cp()` and `PathObject.mv()`, which CLI copy, build and rename paths ride — no longer destroys or truncates the destination on a failed copy (#B227). Bytes now stage to a temp sibling in the destination's directory and publish with an atomic rename, so a reader never observes a partial file and a pre-existing destination is replaced only on success (previously it was unlinked BEFORE the copy started); a source-side read error is now handled instead of raising an unhandled `error` event that killed the process; a failed copy settles the callback exactly once (previously a destination-side failure settled twice — the second time as a success, which forked directory-copy recursion); and failures propagate a real `Error` (previously a plain string, so callers printing `err.stack` logged `undefined`). Contract note: a consumer matching the exact pre-existing failure string `Error on Path.cp(...): Not found ...` now receives an `Error` whose message names the copy that failed.
+* A bundle with `engine: "express"` now boots and serves on Express 5, and the supported range is declared for the first time (#B211). Express 5 broke the engine twice over: its router rejects the bare-string `'*'` catch-all at mount time (the bundle aborted with `TypeError: Missing parameter name` before ever listening), and it turned `req.query` into a prototype getter, so even past the mount every request died on the framework's strict-mode query assignment. The catch-all now mounts a RegExp (accepted and verified live-dispatching on Express 4 AND 5 — no version branching; inert on the default isaac engine, which never reads the pattern), and the Express adapter shadows `query` on the per-app request prototype with a writable property (a measured no-op on Express 4). The adapter also logs the detected Express version at engine construction — supported range `>= 4 < 6`, both majors verified live — and an out-of-range major logs a loud warning but still boots. Express remains consumer-provided: it is deliberately not a dependency of the framework, and not a peerDependency either, since npm 7+ auto-installs peers.
+* The secrets resolver no longer lets a swept framework-environment value beat `process.env`, and three malformed `settings.secrets.file` shapes that used to pass in silence are now caught (#B270, #B271, #B272). **Precedence (#B270):** the two environment tiers were joined with `||`, and `filterArgs()` stores swept `GINA_*`/`VENDOR_*`/`USER_*` values as REAL booleans — so a key whose swept value was boolean `true` satisfied the short-circuit, `process.env` was never consulted, and the file tier won over a perfectly good environment variable. That inverts the precedence the file backend exists to enforce: a stale plaintext file could shadow the credential the platform injected. The tiers are now read independently and only a non-empty STRING from the framework tier wins. **Shape guards (#B271, #B272), all three affecting boot:** an empty array still disables the file tier exactly like `null` — boot is not refused, since an empty list genuinely means "no files" — but it now WARNS, because emptying the array to drop one layer drops the whole tier and used to do so without a word. A whitespace-only entry is now REFUSED rather than building a tier that can never resolve anything: the schema's `minLength: 1` counts a space, so `[" "]` cleared both layers and failed only as a suppressed debug line. And a path containing an empty segment (`//`) is now REFUSED, which is what a `${...}` token that resolved to an EMPTY value leaves behind — `${homedir}/${scope}/secrets.env` with an empty scope collapses to a read of the file one directory UP, silently, with no unresolved token left for the existing guard to catch. ACTION REQUIRED if a config carries either refused shape, and each error names the offending path. The whitespace-only entry is a typo rather than a working configuration. The empty segment may NOT be: the dangerous cause is a token that resolved to nothing, but a token carrying a trailing slash produces the same `//` and resolves to exactly the intended file — `GINA_HOMEDIR=/opt/gina/` with the documented `"${homedir}/secrets.env"` is the shape to check. That configuration worked before this release and now refuses to boot. The two are indistinguishable by the time the path is assembled, so boot refuses on both rather than risk running a bundle on the wrong credential, and the error names both causes; removing the doubled separator, or the trailing slash from the token, resolves it. Both guards apply only to configs that declared `settings.secrets.file`, which is opt-in and absent by default. The schema gains `minItems: 1` as an editor-facing hint — no runtime validator reads `schema/settings.json`, so the runtime guard is the enforcement.
+* `gina project:add` now writes the project's `.gitignore`, which it never did (#B258, #B291). The framework has always shipped a `core/template/_gitignore` whose `_` prefix implies a rename to the dotted form at scaffold time — but nothing performed that rename, so the template had zero consumers and every scaffolded project came out with no `.gitignore` at all. The practical consequence was that the secret-file globs the template carries (`.env`, `.env.*`, `*.env`, with `!.env.example` negations so a sample can still be committed) protected nothing: a new project would happily track a `secrets.env` or `.env.production` on its first commit. The glob shape is the point — a bare `.env` matches neither of those names. The copy is SKIP-IF-EXISTS: your `.gitignore` is your file, routinely carrying rules the framework knows nothing about, so the scaffold fills a gap and never replaces or appends to one. That also makes it idempotent, so re-running `project:add` over an existing project changes nothing. It applies to the import path as well as to new projects, since an imported project without a `.gitignore` has exactly the same exposure. A failure to read the template warns rather than aborting — a scaffold that produced an otherwise complete project should not die over an ignore file. No action required: existing projects are untouched, and if you already have a `.gitignore` you will not notice this at all.
+* `gina project:add` and `gina project:import` no longer destroy `manifest.json` bundle declarations when the declared bundle count differs from what is on disk (#B375). Previously, ANY count mismatch made those commands empty the whole `bundles` block and rebuild it from the directory listing — dropping every key the rebuild template does not carry (the new `scopes` allow-list, `gina_version`, any custom key) and resetting each bundle's `version`, `tag` and release targets to defaults — and the reset hit EVERY registered project on the machine, not just the one being added or imported: a bystander project got no rebuild at all and was left with a permanently empty `bundles` block that fails its next boot. Plain `project:add` suffered the same total loss, since only the import path rebuilds. The commands now treat the manifest as the authority: declared bundles are preserved untouched, bundles found on disk but missing from the manifest are still registered additively on import (the legitimate function the old reset served), and a declared bundle whose directory is absent is reported with a warning naming the bundle and the scanned location — never auto-pruned, since the declaration may be deliberate (e.g. a bundle restricted to other scopes). Removing an entry for good remains `gina bundle:remove`'s job. Also guarded: importing a project whose manifest declares a bundle with no tree on disk no longer risks a crash in the port/settings pass.
+* During `gina project:add`/`gina project:import`, the rescan that registers bundles found on disk built a wrong `settings.json` path for every bundle after the first — the scan root grew by one path segment per bundle, so the second bundle's settings were looked up under the first bundle's directory, the third under the first two, and so on (#B376). Only the first bundle's settings file could ever be found by the pass that reconciles a bundle's declared protocol and scheme with the project's lists; every later bundle was silently skipped. Each bundle's path is now derived from the scan root and its own name.
+* A project's `protocols` and `schemes` lists in `~/.gina/projects.json` can no longer be polluted by a bundle's invalid `server.protocol`/`server.scheme` declaration — nor by another project's bundles (#B378, #B379). Two defects compounded here. First, `gina project:add`/`gina project:import` adopted whatever protocol or scheme a bundle's `settings.json` declared straight into the project's registry lists, unchecked: an arbitrary string became a registered "valid" value, persisted, and `gina image:build` then baked the polluted list into the synthesized container image's environment. Second, the same pass resolved every registered project's bundles against the path of the project being added or imported — so when two projects each had a bundle of the same name (an `api` or `web` in both, say), one project's declarations silently leaked into the OTHER project's registry entry, from a command that never named it. Both are fixed under one contract: the framework's supported sets in `~/main.json` are the authority, and a project's lists stay a subset of them. A bundle's declared value may still extend its own project's list when the framework supports it (that is how the port matrix learns what a project's bundles use); an unsupported value is now reported by name — bundle, value, and the allowed set — once per command, and is adopted nowhere, not even as the bundle entry's default. Each project's bundles are resolved against that project's own path. The import-time heal that rewrites an invalid bundle declaration to the project default still runs (it is what keeps the bundle bootable), but it now reports each change by name (`server.protocol "x" -> "http/1.1"`) as a warning instead of rewriting the file behind a debug line.
+* The port-setup merge that folds newly seen protocols and schemes into a project's registry lists read the wrong array — the project's own list indexed by the contextual list's position — so once the contextual list outgrew the project's, the overshoot read `undefined` (#B380). No user-visible consequence was demonstrated (a scene built to arm the overshoot produced none), so this ships as a correctness fix: the merge now reads the contextual list by its own index, exactly as the environment merge beside it always did, and it admits only values the framework supports — the contextual list also grows from `ports.json` keys, which can retain protocols a framework update removed, and those no longer re-enter the project's lists.
+### Security
+* An engine.io socket's session identity is now derived SERVER-side instead of being asserted by the client (#B365). The socket's `sessionId` — the value every targeted `self.push()` matches against — used to be set from `payload.session.id`, a field the browser sends, on every message, never checked against the connection's own session. Any client could therefore claim another user's session and receive the pushes addressed to it; and because a rendered page carries the BARE session id in its bootstrap script while the cookie carries the signed form, claiming one required strictly less than stealing the cookie. Affects every published release that attaches `server.ioServer`. The binding now happens once, at connection, from the upgrade request's own cookie: gina replays the bundle's OWN session middleware over that request, so the same secret, store and cookie name apply with no new configuration and no framework access to the secret — and it works whether or not the bundle adopted `gina.plugins.Session()`. The response handed to that middleware is inert, so a socket upgrade can never emit `Set-Cookie` or persist a session. It fails CLOSED: no session middleware, no cookie, or a cookie that does not verify leaves the socket with no id, and an id-less socket matches no targeted push — it receives only deliberate broadcasts. A client that still asserts an id is logged and ignored, which doubles as an impersonation detector. This is the receiver half of the axis #B364 left open: that fix decided who a SENDER may aim at, this one decides how a RECEIVER proves who it is.
+
 ## 0.6.8 - 2026-08-15
 ### Added
 * Storage drivers can now read a byte range. `getRange(key, start, end, cb)` ships on every local strategy (`sharded`, `cas` and `stream`) and `capabilities.ranges` is true for all of them, where it was false in every prior release. `end` is INCLUSIVE, matching the HTTP `Range` header, so a header's byte offsets pass through unchanged; an `end` past the last byte is clamped rather than refused, and only a `start` at or beyond the object's size is unsatisfiable — that is the caller's `416`. Both size tiers answer (an inline object slices its stored bytes, a published one gets a positioned read), and under `cas` a released blob stays invisible to `getRange()` exactly as it already is to `get()`. The serving half ships alongside it: `self.serveFromStorage()` answers `206`/`416`/`304` with `Accept-Ranges`/`Content-Range` on both engines, gated on `capabilities.ranges`, so a controller only reaches for raw `getRange()` when it wants custom protocol handling.

package/README.md

@@ -61,38 +61,35 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.6.8
+## What's in 0.6.9
 
-> **Restart your bundles — no re-bake this time.** The browser bundle is
-> byte-identical to `0.6.7`, so `gina bundle:restart` is enough; everything below
-> is server-side. (`0.6.7` did need the rebuild — this one does not.)
+> **Restart your bundles — no re-bake.** The browser bundle is byte-identical to
+> `0.6.8`, so `gina bundle:restart` is enough; everything below is server-side
+> or CLI.
 
-> **No settings reset.** `0.6.8` is a patch — the `shortVersion` stays `0.6`, so
+> **No settings reset.** `0.6.9` is a patch — the `shortVersion` stays `0.6`, so
 > your `~/.gina/0.6/settings.json` is untouched. (`0.6.0` was the reset.)
 
-**This release fixes two security flaws, and both were live in every published
-version up to and including `0.6.7`.** One of them changes behaviour you may be
-relying on: `self.push()` no longer lets the request choose who receives a push,
-which stops a pattern some applications use to report background-job progress.
-Read that entry before upgrading. Both are covered in the
-[migration guide](https://gina.io/docs/migration).
-
-- **Security — `self.push()` decides its own recipient.** The recipient was read from the request body, so a caller could aim a push at any session by sending a session id — and omitting that id broadcast to *every* connected client. The payload defaults to request input too, so on any route reaching `push()` an unprivileged caller could deliver arbitrary content to everyone, or to a chosen victim. The recipient is now decided server-side: an explicit `option.sessionID` wins, otherwise the caller's own session; with neither a resolvable session nor a deliberate `{ broadcast: true }`, `push()` sends nothing and warns, where it previously fell open to everybody. The request body can no longer influence the recipient at all. **Action required if you push at all:** a bare `self.push()` driven over an HTTP hop by a background worker — a job runner reporting progress to the user who queued it, threading that user's session id through the request — now resolves to the caller's own session and stops delivering. That pattern *is* the vulnerability, so it cannot be preserved; but be aware there is no in-process substitute yet, because `push()` is reachable only from a live request-bound controller. Until an explicit out-of-request channel exists, poll `GET /_gina/jobs/:id` or use a transport your application owns. In-request callers are unaffected unless they relied on the implicit fan-out, which now needs `{ broadcast: true }`.
-- **Security — forwarded headers can no longer inject script.** `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Forwarded-Prefix` and the request's own `Host` were spliced unescaped into the client bootstrap script gina emits on every rendered page, landing inside JavaScript string literals. A header containing a single quote closed the literal and ran attacker-chosen script in the browser of anyone served that page — no authentication, any route that renders a view. Forwarded values are now validated where they are read: a host must be a hostname with an optional port or a bracketed IPv6 literal, a scheme must be exactly `http` or `https`, and a path prefix must be URL-path characters only. Anything else is refused and the request falls back to the bundle's own configured host and webroot, exactly as if the header had never been sent. Whether you were reachable depended on your proxy — one that sets or strips the `X-Forwarded-*` headers it forwards never passed an injected value through, while a bundle exposed directly, or behind a proxy relaying client headers verbatim, could be driven by any anonymous caller. No action beyond upgrading; a well-formed host, scheme and prefix behave identically.
-- **Added — storage metadata on Couchbase, which makes a driver root shareable.** The embedded SQLite store is single-process-per-root, so two bundles — or two replicas of one — could not share a root until now. Point a driver's `store` at a `connectors.json` entry whose connector is `couchbase` and every metadata row, inline payloads included, lives on the cluster. Per-key atomicity comes from Couchbase's own CAS, so `cas` reference counting behaves exactly as on the embedded store, and the GC sweep needs no election layer when several replicas run it at once — the claim step is itself compare-and-set, so each blob is collected exactly once. Rows are namespaced by driver name. The two secondary indexes the maintenance verbs need are created at boot when missing; if the account may not create them the boot still succeeds and the exact `CREATE INDEX` statements are logged. Inline payloads are base64-encoded inside the document, which costs about a third more space and puts a practical ceiling near a 14MB `inlineThreshold`.
-- **Added — a `stream` strategy for large sequential media, with resumable uploads.** Keys name an *asset* rather than a file (`assets/<ulid>/original<ext>`), so an object and anything later derived from it live in one directory you can move or delete as a unit. Alongside `put()`, a stream driver carries `createUpload()`, `writeSegment()` (at a byte offset — segments may arrive out of order and in parallel, and re-sending a landed range is harmless), `statUpload()` (which reports what is still *missing*), `finalize()` and `abortUpload()`. Sessions survive a restart. `createUpload()` requires the object's total size deliberately: without it nothing can verify the received ranges actually cover the object. Finalise checks coverage as an interval union and refuses to publish a gap — an unwritten range reads back as zeros rather than failing, so a finalise that merely summed what it received could publish a plausible object with silently wrong bytes. Finalise is idempotent. New optional per-driver keys: `chunkSize` (default `"8MB"`), `sessionTtl` (`"24h"`) and `sessionSweepInterval` (`"1h"`).
-- **Added — HTTP Range serving for stored objects.** `self.serveFromStorage(driverName, key[, opts])` is the read-side companion of `store()`'s driver routing, and owns the whole protocol dance on both engines: `stat()`-gated 404s, a strong ETag minted from the immutable storage key, conditional GET answering 304 with no driver read, and single-range `bytes=` evaluation — a satisfiable range answers 206 with an exact `Content-Length`, an unsatisfiable one 416, and multi-range lists, foreign units and syntactic garbage fall back to the full 200 as RFC 9110 sanctions. Every response carries `X-Content-Type-Options: nosniff`, and a stored `contentType` for active-content types (html/xml/svg/javascript) downgrades to `application/octet-stream` unless you pass an explicit `opts.contentType`. `opts.download`/`opts.filename` emit an RFC 6266 attachment disposition.
-- **Added — the `s3` storage adapter, completing the pluggable object-storage layer.** `adapter: 's3'` plus a `bucket` stores objects on any S3-compatible provider (AWS S3, Scaleway, MinIO, R2…) under the sharded key grammar. Storeless by design: the provider carries each object's metadata on the object itself, so there is no metadata store, no tiering and no drift class to verify. The SDK stays your project's dependency — install `@aws-sdk/client-s3`, `@aws-sdk/lib-storage` and `@aws-sdk/s3-request-presigner`; a configured s3 driver whose SDK is missing refuses the boot with that hint. `resolve()` answers `{kind: 'url'}` with a presigned GET, and `capabilities.offload` flips true for the first time: `serveFromStorage()` answers GET/HEAD with a 307 to the presigned URL — after the local 304 check, with the content-type downgrade riding the signed `response-content-type` so the stored-XSS guard holds when the provider serves the bytes. `opts.offload: false` keeps the in-process proxy path. Static credentials are optional; omitted, the SDK's default provider chain runs.
-- **Added — storage drivers can read a byte range.** `getRange(key, start, end, cb)` ships on every local strategy (`sharded`, `cas`, `stream`), returning a readable stream over the requested slice.
-- **Added — machine-readable storage read errors.** Read-verb failures now carry `err.code` — `STORAGE_NO_OBJECT` for an unknown, released or vanished key, and siblings for the other classes — so callers can branch on the cause instead of matching message text.
-- **Added — Couchbase soak probes ship in the package.** The soak probes for the Couchbase metadata store live at `script/soak/storage/`, so you can exercise a cluster-backed driver root against your own deployment rather than trusting ours.
-- **Changed — `renderStream()` is byte-serving-capable.** On non-SSE content types, `Buffer` chunks now pass through verbatim instead of being UTF-8-decoded — binary payloads previously arrived corrupted, with every invalid-UTF-8 byte replaced by U+FFFD. Valid-UTF-8 buffers re-encode byte-identically, so text consumers are unaffected, and SSE keeps its decode. HEAD requests answer headers-only without consuming the iterable (a destroyable source is destroyed rather than leaking its handle), and the delegate's default headers now yield to values the caller pre-set instead of clobbering them.
-- **Fixed — `renderStream()` honours a caller-set status code on both engines.** The HTTP/2 arm built its response headers before the caller's status was read, so a streamed 206 or 404 went out as 200.
-- **Fixed — `renderStream()` no longer throws a swallowed `TypeError` at the end of every streamed response.** The post-end `headersSent` bookkeeping ran against a response object that no longer accepted it.
-- **Fixed — a redirect no longer treats `HEAD` as a wrong method.** `HEAD` is a safe method — `GET` without a response body — but the redirect path rejected it as if it were a write.
-- **Fixed — a redirect keeps the caller's query string under `keep-params: true`.** The declared parameters were carried but the query string was dropped.
-- **Fixed — a `sharded` driver reclaims temp files left by a crashed `put()`.** A `put()` whose *process* died left its temp file behind to accumulate forever; an age-gated best-effort sweep now clears them.
-- **Fixed — a refused or interrupted `put()` leaves no temp residue.** The stray temp file a rejected write left in a local storage root is now removed on the failure path.
+**This release fixes one security flaw, live in every published version that
+attaches `server.ioServer`.** It closes the receiver half of the axis `0.6.8`
+opened, and it fails closed — so if you use targeted pushes, confirm they still
+arrive after upgrading. Separately, two malformed `settings.secrets.file` shapes
+now refuse to boot; check that config if you use the file tier. Both are covered
+in the [migration guide](https://gina.io/docs/migration).
+
+- **Security — an engine.io socket's session is now proven, not claimed.** A socket's `sessionId` — the value every targeted `self.push()` matches against — was set from `payload.session.id`, a field the browser sends, on every message, and was never checked against the connection's own session. Any client could therefore claim another user's session and receive the pushes addressed to it; and because a rendered page carries the *bare* session id in its bootstrap script while the cookie carries the signed form, doing so took strictly less than stealing the cookie the signature exists to protect. The binding now happens once, at connection, from the upgrade request's own cookie: gina replays the bundle's own session middleware over that request, so the same secret, store and cookie name apply with no new configuration and no framework access to your secret — and it works whether or not the bundle adopted `gina.plugins.Session()`. The response handed to that middleware is inert, so a socket upgrade can never emit `Set-Cookie` or persist a session. It fails closed: no session middleware, no cookie, or a cookie that does not verify leaves the socket with no id, and an id-less socket matches no targeted push. A client that still asserts an id is logged and ignored, which doubles as an impersonation detector. No code change is needed — but because the failure direction is silence rather than an error, verify your targeted pushes still land.
+- **Added — `gina.pushToSession()`, a sanctioned push from outside a request.** `self.push()` needs a live request-bound controller, so a `lib/job` handler, a cron tick or a boot hook had no route to a user's socket at all — and the pattern reached for instead, a worker making an HTTP hop carrying the session id in the request body, *was* the flaw `0.6.8` closed. This is the replacement `0.6.8` promised, and it is deliberately narrow: the recipient is a required argument, an absent or empty `sessionID` is an error rather than a fan-out, and no broadcast is reachable from this API at all (a deliberate all-clients send stays in-request as `self.push(payload, { broadcast: true })`). Source the recipient from server-held state — round-tripping a recipient id, or a token naming one, through the browser hands the choice back to the caller and re-opens the same flaw one layer up. Delivery is reported rather than assumed: `callback(err, { delivered })` fires exactly once with the number of sockets written, and `delivered: 0` is a normal outcome, not an error. Errors carry a machine-readable `err.code`. Requires the `isaac` engine with `server.ioServer` attached; also available as `lib.push.toSession()`.
+- **Added — a bundle can declare which scopes it is deployed in.** An optional `scopes` allow-list on a bundle's `manifest.json` entry replaces the all-or-nothing choice between "registered everywhere" and "not in the manifest at all". The motivating case is a bundle you are still building: `"scopes": ["local"]` keeps it running locally while every other scope behaves as though it does not exist. An absent or null key means every scope, so existing manifests are completely unaffected; an empty array parks the bundle everywhere; a non-array value is reported as a manifest error by name. How an exclusion is reported depends on whether you asked for it — the boot and `gina project:build` skip an excluded bundle with a notice, so one parked bundle never blocks a project build, while starting it or naming it in `gina bundle:build --scope=` is refused by name, because silently producing no artifact would read as success in a deploy script.
+- **Fixed — `engine: "express"` bundles boot and serve on Express 5.** Express 5 broke the engine twice over: its router rejected the bare-string `'*'` catch-all at mount time, so the bundle aborted before ever listening, and it turned `req.query` into a prototype getter, so even past the mount every request died on the framework's strict-mode query assignment. Both are fixed, and the supported range is declared for the first time — `>= 4 < 6`, with both majors verified live. An out-of-range major logs a loud warning but still boots, since a wrong refusal is a total outage while a wrong warning is a log line. Express remains yours to provide: it is deliberately neither a dependency nor a peer dependency.
+- **Fixed — `project:add` / `project:import` no longer rebuild the `bundles` block destructively.** Any mismatch between the declared bundle count and what was on disk made those commands empty the whole block and rebuild it from the directory listing — dropping every key the rebuild template does not carry (the new `scopes` allow-list, `gina_version`, any custom key) and resetting each bundle's version, tag and release targets. The reset hit *every* registered project on the machine, not just the one being named: a bystander project got no rebuild at all and was left with a permanently empty `bundles` block that fails its next boot. The manifest is now the authority — declared bundles are preserved untouched, bundles found on disk but missing from the manifest are still registered additively on import, and a declared bundle whose directory is absent is reported with a warning rather than auto-pruned. A related path bug is fixed with it: the rescan built a wrong `settings.json` path for every bundle after the first, so only the first bundle's settings could ever be found.
+- **Fixed — registration no longer adopts invalid protocol/scheme declarations, nor reads other projects' bundles.** `project:add`/`project:import` adopted whatever `server.protocol` or `server.scheme` a bundle declared straight into the project's registry lists, unchecked — an arbitrary string became a registered "valid" value, persisted, and `gina image:build` then baked the polluted list into the synthesized image's environment. The same pass also resolved *every* registered project's bundles against the path of the project being added, so when two projects each had a bundle of the same name, one project's declarations leaked into the other's registry entry from a command that never named it. The framework's supported sets are now the authority, a project's lists stay a subset of them, an unsupported value is reported by name and adopted nowhere, and each project's bundles are resolved against that project's own path.
+- **Fixed — `project:add` writes the project's `.gitignore`.** The framework has always shipped a `core/template/_gitignore` whose underscore prefix implies a rename at scaffold time, but nothing performed that rename — so the template had zero consumers and every scaffolded project came out with no `.gitignore` at all, leaving the secret-file globs it carries protecting nothing. The copy is skip-if-exists, so your own file is never replaced or appended to, and re-running the command changes nothing.
+- **Fixed — a failed file copy can no longer destroy the destination it was replacing.** The path helper's copier — the byte-writer behind `_().cp()` and `PathObject.mv()`, which CLI copy, build and rename paths all ride — wrote directly to the final name and unlinked an existing destination *before* the copy started. Bytes now stage to a temp sibling and publish with an atomic rename, so a reader never observes a partial file and the destination is replaced only on success. A source-side read error is handled instead of killing the process, a failed copy settles its callback exactly once, and failures propagate a real `Error` rather than a plain string. **Contract note:** code matching the exact former failure string now receives an `Error` instead.
+- **Fixed — the environment beats the secrets file again, and three malformed `secrets.file` shapes are caught.** The two environment tiers were joined with `||`, and the CLI stores swept `GINA_*`/`VENDOR_*`/`USER_*` values as real booleans — so a key whose swept value was boolean `true` satisfied the short-circuit, `process.env` was never consulted, and the file tier won over a perfectly good environment variable, letting a stale plaintext file shadow a platform-injected credential. The tiers are now read independently. **Action required if you use the file tier:** a whitespace-only entry and a path containing an empty segment (`//`) now refuse to boot rather than failing as a suppressed debug line. The empty segment is worth a look — it is what a `${...}` token that resolved to nothing leaves behind, but a token carrying a *trailing slash* produces the same shape and resolves to exactly the intended file, so a config that worked before will now refuse; removing the doubled separator resolves it.
+- **Fixed — a bundle whose release tree cannot be linked says which bundle, and why.** The config loader built a useful error carrying the offending path, but the receiving callback never inspected it and dereferenced the absent configuration object instead — so the reason was discarded and the process died on an opaque `TypeError`. Because the configuration load is shared across the project, one bundle's missing release tree took down every bundle in it. The error is now reported through the same sink the bundle-configuration loader already used, naming the bundle, env and scope.
+- **Fixed — `self.push()` refuses by name when there is no engine.io channel.** The push channel is an isaac-engine facility, so on the Express engine the client lookup dereferenced an absent `eio` and surfaced as an opaque 500 that named neither push nor the missing channel. It now warns, hands a supplied callback a `PUSH_CHANNEL_NOT_CONFIGURED` error, and sends nothing — without failing the request, so a notification side-channel no longer takes down the response it rode in on. This is also the first time `push()` honours the `callback(err, result)` contract its documentation always described.
+- **Fixed — the port-setup merge read the wrong list.** The pass that folds newly seen protocols and schemes into a project's registry lists indexed the project's own list by the contextual list's position, so once the contextual list outgrew it the overshoot read `undefined`. No user-visible consequence was demonstrated, so this ships as a correctness fix.
+
 ## Documentation
 
 Full installation guide, tutorials, configuration reference, and API docs at **[gina.io/docs](https://gina.io/docs/)**.

package/ROADMAP.md

@@ -59,7 +59,8 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q4 2026** | `0.6.5` ✅ | **Fixed**: the silent-dead-control release — a family of defects where a control looked completely normal and did nothing at all. A submit trigger disabled by your own double-submit guard during the click (a `0.6.4` regression), a submit button whose DOM node an AJAX update or popin re-render replaced, a form left blocked after its async uniqueness check came back clean, a popin close button given your own id or wrapping an icon, a `data-gina-link` given your own id, and a popin holding several forms releasing only every other one — all now work. Trusted gestures (Enter, wrapped-label clicks) respect the submit gate; `data-gina-link` stops swallowing `download`, `target`, `#`-fragment and modified clicks, and gains the disabled gate it never had; download filenames parse and serialize per RFC 6266; `gina.setOptions()` writes the config the framework reads, having been silently ignored since it shipped; `isRequired` accepts padded input and `trim` strips both sides · **Changed**: the not-ready submit-trigger state moves off `aria-disabled` onto the framework-owned `data-gina-form-submit-gated`, with a default look — the marker no longer claims a control is inoperable while gina deliberately answers its click |
 | **Q4 2026** | `0.6.6` ✅ | **Fixed**: the logging-transport release. A slow boot no longer silences a bundle's logging for the life of the process — a two-second connect deadline added in `0.6.5` read a socket flag Node clears one event-loop phase later, so any boot that blocked the loop past it destroyed a connection the kernel had already established (every container start and network-filesystem mount was exposed, and the transport never redialled). The MQ and file log transports also stopped dialling `host_v4`, which on a `~/.gina` shared across hosts silently shipped every log line off-host while all connection lines read healthy. Plus: the popin `success` event fires again instead of raising a 422 carrying the successful response body; a link request belongs to the anchor you clicked rather than the first anchor sharing its url; and constructing the link handler twice no longer corrupts the first instance · **Added**: the log transport reconnects — exponential backoff to a 30-second ceiling, one report per outage, frames dropped rather than queued while down so an outage cannot grow memory |
 | **Q4 2026** | `0.6.7` ✅ | **Added**: the object-storage release — a `storage` block declares named drivers (an adapter crossed with a strategy) reachable as `gina.storage()`, publishing objects atomically under opaque keys with their metadata written through a pluggable store seam; a content-addressed `cas` strategy deduplicates identical bytes behind a reference count, reclaiming them only after a grace-gated sweep; size tiering keeps sub-`64KB` objects inline in the metadata store, measurably faster than per-file writes; `storage:stats` / `storage:gc` / `storage:verify` operate a bundle's drivers whether it is running or stopped, through always-on admin-gated endpoints; and an upload group can route its `self.store()` step straight into a driver · **Security**: bound query parameter values no longer reach dev consoles or the Inspector query log — count and type markers replace them, with `inspector.queries.captureValues` to opt back in · **Fixed**: the `is` rule compiles regex literals as authored instead of stripping their parentheses (stricter — review patterns containing parens), forms with an async `query` rule complete correctly across a cluster of interacting defects (a submit leaving before the verdict landed, a completion carrying only the query field's slice, a re-click clearing later fields' errors, a clean form whose query field was not declared last never submitting at all, replayed submits from stale listeners, and an id-less trigger bound twice), `getConfig().settings` resolves path placeholders, `req.files[].group` reports the resolved group instead of `undefined`, and the Inspector's Data and Forms tabs stop putting framework-internal keys and the bundle catalog above your own data · **Changed**: framework default looks ship inside a `@layer gina` cascade layer, so any un-layered project rule overrides them without `!important` |
-| **Q4 2026** | `0.6.8` ✅ | **Security**: `self.push()` decides its recipient server-side instead of reading it from the request, where a supplied session id aimed the push at any session and an absent one broadcast to every connected client (ACTION REQUIRED — a background worker pushing over an HTTP hop stops delivering; poll `GET /_gina/jobs/:id` in the meantime) · forwarded headers (`X-Forwarded-Host`, `-Proto`, `-Prefix` and the request's own `Host`) are validated where they are read, closing a reflected-XSS path that spliced them unescaped into the client bootstrap script emitted on every rendered page · **Added**: storage metadata can live on Couchbase, which is what makes a driver root shareable across bundles and replicas; a `stream` strategy for large sequential media brings resumable, out-of-order, restart-surviving uploads whose finalise verifies coverage as an interval union and refuses to publish a gap; HTTP Range serving through `self.serveFromStorage()` on both engines, with conditional GET and a fail-closed content-type downgrade; the `s3` adapter completes the pluggable object-storage layer, storeless by design and able to offload GET/HEAD to a presigned URL; `getRange()` on every local strategy; machine-readable `err.code` on storage read verbs; and the Couchbase soak probes ship in the package · **Changed**: `renderStream()` is byte-serving-capable — `Buffer` chunks pass through verbatim on non-SSE content types (binary payloads previously arrived corrupted), HEAD answers headers-only without consuming the iterable, and caller-set headers are no longer clobbered · **Fixed**: `renderStream()` honours a caller-set status on both engines and stops throwing a swallowed error at the end of every streamed response, a redirect treats `HEAD` as the safe method it is and keeps the caller's query string under `keep-params: true`, and a local storage driver reclaims the temp files left behind by a crashed or refused `put()` |
+| **Q4 2026** | `0.6.8` ✅ | **Security**: `self.push()` decides its recipient server-side instead of reading it from the request, where a supplied session id aimed the push at any session and an absent one broadcast to every connected client (ACTION REQUIRED — a bare worker push over an HTTP hop that carried the recipient IN THE REQUEST stops delivering; where the hop is authenticated the controller can pass `{ sessionID }` explicitly and keep working, and a worker with no request context at all polls `GET /_gina/jobs/:id`) · forwarded headers (`X-Forwarded-Host`, `-Proto`, `-Prefix` and the request's own `Host`) are validated where they are read, closing a reflected-XSS path that spliced them unescaped into the client bootstrap script emitted on every rendered page · **Added**: storage metadata can live on Couchbase, which is what makes a driver root shareable across bundles and replicas; a `stream` strategy for large sequential media brings resumable, out-of-order, restart-surviving uploads whose finalise verifies coverage as an interval union and refuses to publish a gap; HTTP Range serving through `self.serveFromStorage()` on both engines, with conditional GET and a fail-closed content-type downgrade; the `s3` adapter completes the pluggable object-storage layer, storeless by design and able to offload GET/HEAD to a presigned URL; `getRange()` on every local strategy; machine-readable `err.code` on storage read verbs; and the Couchbase soak probes ship in the package · **Changed**: `renderStream()` is byte-serving-capable — `Buffer` chunks pass through verbatim on non-SSE content types (binary payloads previously arrived corrupted), HEAD answers headers-only without consuming the iterable, and caller-set headers are no longer clobbered · **Fixed**: `renderStream()` honours a caller-set status on both engines and stops throwing a swallowed error at the end of every streamed response, a redirect treats `HEAD` as the safe method it is and keeps the caller's query string under `keep-params: true`, and a local storage driver reclaims the temp files left behind by a crashed or refused `put()` |
+| **Q4 2026** | `0.6.9` ✅ | **Security**: an engine.io socket's session identity is derived server-side from the upgrade request's own cookie instead of a field the browser asserts on every message — any client could previously claim another user's session and receive the pushes addressed to it, which took strictly less than stealing the cookie, since a rendered page carries the bare session id while the cookie carries the signed form; the binding replays the bundle's own session middleware (same secret, store and cookie name, no new configuration) and fails closed, so an id-less socket receives only deliberate broadcasts · **Added**: `gina.pushToSession()` gives code with no request context — a job handler, a cron tick, a boot hook — a sanctioned route to a user's socket, with a required recipient, no reachable broadcast, and delivery reported rather than assumed; and a bundle can declare which scopes it is deployed in through a `scopes` allow-list on its manifest entry, so one still under development stays out of every other scope · **Fixed**: `engine: "express"` bundles boot and serve on Express 5, with the supported range declared for the first time (`>= 4 < 6`, both majors verified live) · `project:add`/`project:import` no longer empty a project's `bundles` block on a declared-count mismatch, no longer adopt a bundle's invalid `server.protocol`/`server.scheme` into the project's registry lists, and no longer resolve one project's bundles against another project's path · `project:add` writes the `.gitignore` the shipped template's underscore prefix has always implied · the path helper's copier stages to a temp sibling and publishes with an atomic rename, so a failed copy can no longer destroy the destination it was replacing · the secrets resolver reads its two environment tiers independently, so a swept boolean no longer lets a plaintext file shadow `process.env`, and three malformed `settings.secrets.file` shapes that used to pass in silence are caught (ACTION REQUIRED — two of them now refuse to boot) · a bundle whose release tree cannot be linked refuses by name instead of dying as an opaque TypeError · `self.push()` refuses by name when the server instance has no engine.io channel |
 | **Q1 2027** | `0.6.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **2027** | `0.7.0` | Performance — remaining measure-gated candidates: multipart & WebSocket fast paths, render/log cleanups, SIMD scanner (the render-path deep-clone & id-mint reduction shipped early in `0.6.2` with a measured 4.4× render-throughput gain; the profiling baseline itself also shipped in `0.6.2`) |
 | **2027** | `0.8.0` | Financial-messaging foundations — XML request/response handling · pluggable message-schema validation · IBAN/BIC validation rules · money & ISO 4217 minor-unit utilities · idempotency keys · sequence primitive · OAuth2 client-credentials egress |

package/framework/v0.6.9/VERSION

@@ -0,0 +1 @@
+0.6.9

package/framework/{v0.6.8 → v0.6.9}/core/config.js

@@ -175,6 +175,22 @@ function Config(opt, contextResetNeeded) {
 
         self.Env.load( function(err, envConf) {
 
+            // #B372 — the env load can fail (an unlinkable release path, most often one
+            // bundle's release tree missing on the target host). Nothing consumed that
+            // error before, so it either vanished or resurfaced as an opaque deref later
+            // in the boot. Refuse here, through the same sink loadBundlesConfiguration
+            // uses below, so the reason reaches stderr and the process exits cleanly.
+            if (err) {
+                var _envMsg = (err.stack||err.message);
+                console.error(_envMsg);
+                // Guarantee the reason survives process.exit() on an async pipe (e.g. bin/gina-container).
+                try { fs.writeSync(2, _envMsg + '\n'); } catch (_e) { /* best-effort */ }
+                setTimeout(() => {
+                    process.exit(1);
+                }, 0);
+                return;
+            }
+
             if ( typeof(self.Env.loaded) == 'undefined') {
                 // Need to globalize some of them.
                 self.envConf = envConf;
@@ -400,6 +416,17 @@ function Config(opt, contextResetNeeded) {
         template : requireJSON( getEnvVar('GINA_FRAMEWORK_DIR') +'/core/template/conf/env.json'),
         load : function(callback) {
             loadWithTemplate(this.parent.userConf, this.template, function(err, envConf) {
+                // #B372 — loadWithTemplate calls back with an error and NO envConf (e.g. a
+                // release path that cannot be linked). Dereferencing envConf here discarded
+                // that well-formed reason — which already names the offending path — and
+                // replaced it with `TypeError: Cannot set properties of undefined (setting
+                // 'env')`, so the operator got an uncaughtException pointing at framework
+                // internals instead of at the path they had to fix. Propagate: getConf's
+                // callback turns it into a named exit(1).
+                if (err) {
+                    return callback(err);
+                }
+
                 self.envConf            = envConf;
                 envConf.env             = self.env;
                 envConf.scope           = self.scope;
@@ -640,6 +667,36 @@ function Config(opt, contextResetNeeded) {
     //     }
     // }
 
+    /**
+     * Whether a manifest bundle entry is deployed in the given scope.
+     *
+     * `bundles[<name>].scopes` is an OPTIONAL allow-list of scope names — the
+     * same semantics as a route's rule-level `scopes`: the key ABSENT (or null)
+     * means every scope (back-compat, the historical behaviour), an empty array
+     * means no scope at all (the bundle is parked), and a non-array is INVALID —
+     * callers fail fast on that shape with a named error before relying on this
+     * predicate, which returns false for it only as a defensive default.
+     *
+     * A twin of this predicate lives in `core/gna.js` (the mount-resolution
+     * path runs before Config and cannot reach this closure) — keep the two
+     * in sync.
+     *
+     * @inner
+     * @private
+     * @param {object} bundleEntry - The bundle's `manifest.json` entry (`bundles[<name>]`)
+     * @param {string} scopeName - Scope being booted/loaded
+     * @returns {boolean} `true` when the bundle is deployed in `scopeName`
+     */
+    var isBundleDeployedInScope = function(bundleEntry, scopeName) {
+        if ( !bundleEntry || typeof(bundleEntry.scopes) == 'undefined' || bundleEntry.scopes === null ) {
+            return true;
+        }
+        if ( !Array.isArray(bundleEntry.scopes) ) {
+            return false;
+        }
+        return bundleEntry.scopes.indexOf(scopeName) > -1;
+    }
+
     /**
      * Merges the user's project config (`userConf`) against the framework's
      * `env.json` template, resolving port assignments, bundle paths, model
@@ -699,6 +756,27 @@ function Config(opt, contextResetNeeded) {
             return callback(err);
         }
 
+        // #B373 — the STARTING bundle is a special case: skipping it would leave the
+        // boot with no bundle to serve and it would die further down in the #B181(b)
+        // env.json guard, whose message describes the wrong cause entirely. Refuse
+        // here instead, naming the scope and the one-line remedy. Reaches exit(1)
+        // through the same sink #B372 installed on this callback.
+        if (
+            typeof(pkg) != 'undefined' && pkg !== null
+            && typeof(pkg[self.startingApp]) != 'undefined'
+            && !isBundleDeployedInScope(pkg[self.startingApp], scope)
+        ) {
+            let _startingScopeError = new Error(
+                '[ scope ] cannot start `'+ self.startingApp +'` in scope `'+ scope +'`: the bundle is not deployed there. '
+                + '`bundles.'+ self.startingApp +'.scopes` in manifest.json declares '
+                + ( Array.isArray(pkg[self.startingApp].scopes) && pkg[self.startingApp].scopes.length
+                        ? '`'+ pkg[self.startingApp].scopes.join('`, `') +'`'
+                        : 'no scope at all' )
+                + '. Add `'+ scope +'` to that list, or start the bundle in a scope it belongs to.'
+            );
+            return callback(_startingScopeError);
+        }
+
 
         // For each app.
         var isCacheless         = self.isCacheless()
@@ -748,6 +826,22 @@ function Config(opt, contextResetNeeded) {
                 continue;
             }
 
+            // #B373 — per-scope deployment. `bundles[<name>].scopes` is an optional
+            // allow-list: absent means every scope (back-compat), so this can only
+            // skip a bundle whose manifest OPTS OUT of the scope being booted. A
+            // non-array is a manifest error, not an opt-out — refuse rather than
+            // silently parking the bundle everywhere.
+            if ( typeof(pkg[app].scopes) != 'undefined' && pkg[app].scopes !== null && !Array.isArray(pkg[app].scopes) ) {
+                let _scopesTypeError = new Error('[ manifest ] `bundles.'+ app +'.scopes` must be an array of scope names (got '+ typeof(pkg[app].scopes) +'). Remove the key to deploy `'+ app +'` in every scope, or list the scopes it belongs to.');
+                return callback(_scopesTypeError);
+            }
+            if ( !isBundleDeployedInScope(pkg[app], scope) ) {
+                // Say so rather than letting the bundle vanish from the boot with
+                // nothing explaining why — the #B183 skipped-sibling lesson.
+                console.warn('[CONFIG] Skipping bundle [ '+ app +' ]: not deployed in scope `'+ scope +'` (declared scopes: '+ (pkg[app].scopes.length ? '`'+ pkg[app].scopes.join('`, `') +'`' : 'none') +'). Add `'+ scope +'` to `bundles.'+ app +'.scopes` in manifest.json to deploy it here.');
+                continue;
+            }
+
             appPath = _(root +'/'+ pkg[app].link, true);
             console.debug('[CONFIG] Checking appPath [ '+ appPath +' ] ');
             // cleanup symlinks
@@ -767,7 +861,14 @@ function Config(opt, contextResetNeeded) {
                 }
             } catch (releaseError) {
                 console.error('[ releaseError ] ', releaseError);
-                let _releaseError = new Error('[ releaseError ] path: '+ targetAppPathObj.toString() );
+                // #B372 — name the bundle, env and scope. One bundle's unlinkable release
+                // tree aborts the SHARED config load for every bundle in the project, so
+                // "which one?" is the operator's first question and the loop already knows.
+                // `targetAppPathObj` is deliberately not reported: when the throw comes from
+                // `pkg[app].releases[scope][env]` itself, the assignment above never ran and
+                // the object still holds the LINK path, so reporting it names the wrong file.
+                // The underlying message does name the real one (ENOENT carries the path).
+                let _releaseError = new Error('[ releaseError ] bundle: `'+ app +'` (env: `'+ env +'`, scope: `'+ scope +'`), link: '+ appPath +' — '+ (releaseError.message || releaseError) );
                 return callback(_releaseError);
             }
             targetAppPathObj = null;

package/framework/{v0.6.8 → v0.6.9}/core/controller/controller.js

@@ -6441,12 +6441,19 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
      * Reaching every connected client requires `option.broadcast === true`,
      * supplied by your code rather than inferred from a missing value.
      *
+     * The channel itself is an isaac-engine facility. On the express engine there
+     * is none, so a push sends nothing, warns, and reports
+     * `PUSH_CHANNEL_NOT_CONFIGURED` to a supplied callback rather than failing the
+     * request (#B371) — a structural condition, identical on every call.
+     *
      * @param {object|null}  payload             - Data to push; falls back to `req[method].payload` when `null`
      * @param {object}       [option]            - Push options, also forwarded to the transport (e.g. `{ compress: true }`)
      * @param {string}       [option.sessionID]  - Explicit recipient session id; defaults to the caller's own session
      * @param {boolean}      [option.broadcast]  - `true` (strictly) to reach every connected client
      * @param {string}       [option.section]    - Section stamped onto the payload; falls back to `req[method].section`
-     * @param {function}     [callback]          - `callback(err, result)`
+     * @param {function}     [callback]          - `callback(err, result)`; receives a
+     *                                             `PUSH_CHANNEL_NOT_CONFIGURED` error when this
+     *                                             server instance has no engine.io channel
      * @returns {void}
      *
      * @example
@@ -6474,6 +6481,25 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         var req = local.req, res = local.res;
         var method  = req.method.toLowerCase();
 
+        // #B371 — the push channel is an isaac-engine facility: `serverInstance.eio`
+        // is attached there and nowhere else, so on the express engine the client
+        // lookup further down dereferenced `undefined` and surfaced as an opaque
+        // TypeError-derived 500 that named neither push nor the missing channel.
+        // Refuse by name instead, the way the out-of-request sibling does
+        // (`lib/push` → PUSH_CHANNEL_NOT_CONFIGURED): warn, tell a caller that
+        // passed a callback, and send nothing. This is a structural, process-wide
+        // condition — unlike the per-call no-recipient case below — so it can
+        // never resolve on a later call and is reported the same way every time.
+        if ( self.serverInstance == null || self.serverInstance.eio == null ) {
+            console.warn('[CONTROLLER][ push ] no engine.io channel on this server instance, so nothing was sent. The push channel needs the isaac engine with `settings.json > server.ioServer.integrationMode: "attach"`; the express engine has no `eio`.');
+            if ( typeof(callback) == 'function' ) {
+                var noChannelErr  = new Error('no engine.io channel on this server instance. The push channel needs the isaac engine with `settings.json > server.ioServer.integrationMode: "attach"`; the express engine has no `eio`.');
+                noChannelErr.code = 'PUSH_CHANNEL_NOT_CONFIGURED';
+                callback(noChannelErr);
+            }
+            return;
+        }
+
         // #B364 — the recipient is NEVER read from the request body. It used to be
         // (`req[method].sessionID`), which let a caller aim a push at any session by
         // sending an id — and, when the id was absent, at EVERY connected client.
@@ -6548,9 +6574,11 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                             && clients[s].sessionId == sessionId
                         )
                     ) {
-                        // #B364 — was `options`, an identifier that exists nowhere in this
-                        // scope: every call threw ReferenceError here before sending, so
-                        // push() had never delivered a packet in any published release.
+                        // #B364 — was `options`: SuperController's own constructor
+                        // parameter, in scope here by closure, where the caller's
+                        // `option` was meant. It resolved, so nothing threw and the
+                        // packet WAS sent — carrying the controller's options in
+                        // place of the caller's, which never reached the transport.
                         clients[s].sendPacket("message", payload, option, callback);
                     }
                 }

package/framework/{v0.6.8 → v0.6.9}/core/gna.js

@@ -2093,6 +2093,31 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
             , path  = null
             , packs = project.bundles
         ;
+
+        /**
+         * Whether a manifest bundle entry is deployed in the given scope (#B373).
+         *
+         * TWIN of `isBundleDeployedInScope` in `core/config.js` — this path runs
+         * BEFORE Config exists and cannot reach that closure, so the predicate is
+         * duplicated deliberately. Keep both in sync: `scopes` absent/null means
+         * every scope (back-compat), `[]` means none, a non-array is invalid.
+         *
+         * @inner
+         * @private
+         * @param {object} bundleEntry - The bundle's manifest entry
+         * @param {string} scopeName - Scope being mounted
+         * @returns {boolean} `true` when deployed in `scopeName`
+         */
+        var isBundleDeployedInScope = function(bundleEntry, scopeName) {
+            if ( !bundleEntry || typeof(bundleEntry.scopes) == 'undefined' || bundleEntry.scopes === null ) {
+                return true;
+            }
+            if ( !Array.isArray(bundleEntry.scopes) ) {
+                return false;
+            }
+            return bundleEntry.scopes.indexOf(scopeName) > -1;
+        };
+
         if (isLoadedThroughCLI) {
             appName = getContext('bundle');
             if (!isPath) {
@@ -2100,6 +2125,28 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
                 if (typeof (packs[appName].version) == 'undefined' && typeof (packs[appName].tag) != 'undefined') {
                     packs[appName].version = packs[appName].tag
                 }
+                // #B373 — refuse by name BEFORE the release deref below. This deref sits
+                // outside any try, so an opted-out bundle used to die here as an opaque
+                // TypeError before Config (and its named refusal) ever ran. The type
+                // check comes first: a malformed `scopes` is a manifest error, and
+                // reporting it as "not deployed" would send the operator hunting the
+                // wrong thing (the predicate returns false for both).
+                if (
+                    typeof (packs[appName].scopes) != 'undefined' && packs[appName].scopes !== null
+                    && !Array.isArray(packs[appName].scopes)
+                ) {
+                    return abort('[ manifest ] `bundles.' + appName + '.scopes` must be an array of scope names (got '
+                        + typeof (packs[appName].scopes) + '). Remove the key to deploy `' + appName + '` in every scope, '
+                        + 'or list the scopes it belongs to.');
+                }
+                if ( !isBundleDeployedInScope(packs[appName], scope) ) {
+                    return abort('[ scope ] cannot mount `'+ appName +'` in scope `'+ scope +'`: the bundle is not deployed there. '
+                        + '`bundles.'+ appName +'.scopes` in manifest.json declares '
+                        + ( Array.isArray(packs[appName].scopes) && packs[appName].scopes.length
+                                ? '`'+ packs[appName].scopes.join('`, `') +'`'
+                                : 'no scope at all' )
+                        + '. Add `'+ scope +'` to that list, or start the bundle in a scope it belongs to.');
+                }
                 packs[appName].releases[scope][env].target = 'releases/' + appName + '/' + scope + '/' + env + '/' + packs[appName].version;
                 path = (isDev) ? packs[appName].src : packs[appName].releases[scope][env].target
             } else {
@@ -2127,6 +2174,13 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
                 for (let bundle in packs) {
                     //is bundle ?
                     let tmp = '';
+                    // #B373 — a bundle not deployed in this scope can never be the one
+                    // being mounted here, and its release deref below sits in a try whose
+                    // catch ABORTS the whole mount — so without this skip one opted-out
+                    // sibling would take the process down at any non-dev scope.
+                    if ( !isBundleDeployedInScope(packs[bundle], scope) ) {
+                        continue;
+                    }
                     // For all but dev
                     if (
                         typeof (packs[bundle].releases) != 'undefined'
@@ -2467,6 +2521,59 @@ gna.storage = function(name) {
     return lib.storage.get(name);
 };
 
+/**
+ * #B366 — push a payload to ONE named session from OUTSIDE a request.
+ *
+ * `self.push()` needs a live request-bound controller, so code that has none —
+ * a `lib/job` handler, a cron tick, a boot hook — had no sanctioned route to a
+ * user's socket. This is that route, and it is deliberately narrow:
+ *
+ *   - `sessionID` is REQUIRED. An absent or empty recipient is an error, never
+ *     a fan-out. There is no broadcast reachable from here at all; the
+ *     deliberate all-clients send stays in-request as
+ *     `self.push(payload, { broadcast: true })`.
+ *   - The recipient must come from server-held state — captured when the work
+ *     was queued, and kept server-side. Never round-trip it (or a token naming
+ *     it) through the browser: that hands the choice back to the caller and
+ *     re-opens #B364 one layer up.
+ *   - Delivery is reported, not assumed: `delivered` is how many sockets were
+ *     written, and `0` is a normal outcome, not an error.
+ *
+ * Requires the isaac engine with `settings.json > server.ioServer` attached;
+ * the express engine has no engine.io channel and gets a named error.
+ *
+ * Assigned UNCONDITIONALLY (same reasoning as `gna.storage` above), so a
+ * misconfigured bundle gets an error naming the fix rather than
+ * `gna.pushToSession is not a function`.
+ *
+ * @param {string}        sessionID          - REQUIRED recipient session id.
+ * @param {object|string} payload            - Object (JSON-stringified) or a pre-serialized string.
+ * @param {object}        [option]           - Forwarded to the transport (e.g. `{ compress: true }`).
+ * @param {string}        [option.section]   - Stamped onto an object payload lacking one.
+ * @param {function}      [callback]         - `callback(err, { delivered })`, called exactly once.
+ * @returns {void}
+ * @example
+ *   // in a job handler — sessionID was captured when the job was created
+ *   gina.pushToSession(job.sessionID, { event: 'export:ready', key: res.key }, function (err, out) {
+ *       if (err) { return console.error(err.code, err.message); }
+ *       if (!out.delivered) { console.debug('nobody listening — the user closed the tab'); }
+ *   });
+ */
+gna.pushToSession = function(sessionID, payload, option, callback) {
+    var instance = ( process.gina ) ? process.gina._serverInstance : null;
+    if ( instance == null ) {
+        var err = new Error(
+            '[ push ] the server instance is not published yet, so there is no socket set to reach. '
+            + 'This is normal before the bundle has served its first request.'
+        );
+        err.code = 'PUSH_CHANNEL_NOT_READY';
+        if ( typeof(option) == 'function' ) { return option(err); }
+        if ( typeof(callback) == 'function' ) { return callback(err); }
+        throw err;
+    }
+    return lib.push.toSession(instance, sessionID, payload, option, callback);
+};
+
 // ── JSON helper (framework/v*/helpers/json/src/main.js) ──────────────────
 
 /**