gina 0.5.2 → 0.5.3

package/framework/{v0.5.2 → v0.5.3}/lib/cmd/port/set.js

@@ -18,6 +18,13 @@ var console = lib.logger;
  *
  * When a required value is omitted, the user is prompted interactively.
  *
+ * Pass --force to reassign a port that is currently held by a different bundle:
+ * the prior holder is evicted (it loses that port for the protocol/scheme and
+ * re-pins itself the next time its own context runs port:set). Without --force,
+ * a port already assigned to another bundle is rejected.
+ *
+ *  gina port:set <bundle_name> @<project_name> --protocol=http/2.0 --scheme=https --port=8443 --env=dev --force
+ *
  * @class Set
  * @constructor
  * @param {object} opt - Parsed command-line options
@@ -34,6 +41,7 @@ function Set(opt, cmd) {
         , requestedScheme = null
         , requestedPort   = null
         , requestedEnv    = null
+        , requestedForce  = false
     ;
 
     // Pre-parse argv before CmdHelper to extract protocol:port and @project/env
@@ -65,6 +73,7 @@ function Set(opt, cmd) {
             if ( /^\-\-protocol\=/.test(arg) ) { requestedProtocol = arg.split('=')[1];   continue; }
             if ( /^\-\-scheme\=/.test(arg) )   { requestedScheme   = arg.split('=')[1];   continue; }
             if ( /^\-\-env\=/.test(arg) )      { requestedEnv      = arg.split('=')[1];   continue; }
+            if ( /^\-\-force$/.test(arg) )     { requestedForce   = true;                continue; }
 
             cleaned.push(arg);
         }
@@ -242,12 +251,20 @@ function Set(opt, cmd) {
      * ports.reverse.json. Removes any previous assignment for the same
      * bundle/env/protocol/scheme before writing the new one.
      *
+     * If the target port is already held by a DIFFERENT bundle/env, the call is
+     * rejected — unless `--force` was passed (closure var `requestedForce`), in
+     * which case the prior holder is evicted from both maps and a warning is
+     * logged before the new assignment is written.
+     *
      * @inner
      * @private
      * @param {string} protocol - e.g. 'http/1.1', 'http/2.0'
      * @param {string} scheme   - e.g. 'http', 'https'
      * @param {number} port     - Port number to assign
      * @param {string} env      - Environment name (e.g. 'dev', 'staging')
+     * @example
+     * // Pin a bundle to a fixed port even if another bundle currently holds it:
+     * //   gina port:set frontend @myproject --protocol=http/2.0 --scheme=https --port=8443 --env=dev --force
      */
     var setPort = function(protocol, scheme, port, env) {
 
@@ -290,8 +307,34 @@ function Set(opt, cmd) {
             && typeof(ports[protocol][scheme][portStr]) != 'undefined'
             && ports[protocol][scheme][portStr] !== portValue
         ) {
-            console.error('Port '+ port +' is already assigned to '+ ports[protocol][scheme][portStr]);
-            process.exit(1);
+            var squatter = ports[protocol][scheme][portStr];
+
+            if ( !requestedForce ) {
+                console.error('Port '+ port +' is already assigned to '+ squatter +' (use --force to reassign)');
+                process.exit(1);
+            }
+
+            // --force: evict the current holder so this bundle can take the port.
+            // The displaced bundle loses this port for this protocol/scheme; it
+            // re-pins itself the next time its own context runs `port:set`. This is
+            // the intended shape for one-bundle-per-container deployments where each
+            // container owns exactly one bundle and pins it to a fixed port.
+            console.warn('[port:set] --force: reassigning port '+ port +' from '+ squatter +' to '+ portValue);
+            delete ports[protocol][scheme][portStr];
+
+            // Drop the displaced bundle's reverse entry so the two maps stay consistent.
+            var sSlash = squatter.lastIndexOf('/');
+            if ( sSlash > 0 ) {
+                var sBundleKey = squatter.substring(0, sSlash);
+                var sEnv       = squatter.substring(sSlash + 1);
+                if (
+                    typeof(portsReverse[sBundleKey]) != 'undefined'
+                    && typeof(portsReverse[sBundleKey][sEnv]) != 'undefined'
+                    && typeof(portsReverse[sBundleKey][sEnv][protocol]) != 'undefined'
+                ) {
+                    delete portsReverse[sBundleKey][sEnv][protocol][scheme];
+                }
+            }
         }
 
         // Remove previous port for this bundle/env/protocol/scheme (if reassigning)

package/framework/{v0.5.2 → v0.5.3}/lib/generator/index.js

@@ -20,6 +20,10 @@ var fs = require('fs');
 var _stateModule;
 try { _stateModule = require('../state'); } catch (_) { _stateModule = null; }
 
+// #B43 — monotonic counter for unique same-process atomic-write temp filenames
+// (createFileFromDataSync's legacy path writes a temp + renames to stay tear-free).
+var _atomicWriteSeq = 0;
+
 /**
  * @class Generator
  *
@@ -103,10 +107,21 @@ var Generator = {
             }
         }
 
-        // Legacy JSON write (non-state files, or SQLite unavailable)
+        // Legacy JSON write (non-state files, or SQLite unavailable).
+        // #B43 — write ATOMICALLY: a same-dir temp + rename, so a concurrent reader
+        // never observes a truncated/empty file (a bare fs.writeFileSync truncates the
+        // target in place; a concurrent boot read of the partial JSON crashes FATALLY).
+        // rename(2) is atomic within a filesystem; the temp is a sibling of the target.
         data = (typeof(data) == "object") ? JSON.stringify(data, null, 4) : data;
-        fs.writeFileSync(target, data);
-        fs.chmodSync(target, 0755)
+        var _tmp = target + '.' + process.pid + '.' + (_atomicWriteSeq++) + '.tmp';
+        try {
+            fs.writeFileSync(_tmp, data);
+            fs.chmodSync(_tmp, 0755);
+            fs.renameSync(_tmp, target);
+        } catch (writeErr) {
+            try { fs.unlinkSync(_tmp); } catch(unlinkErr) {}
+            throw writeErr;
+        }
     },
     // createFoldersFromStructureSync : function(structure){
     // },

package/framework/{v0.5.2 → v0.5.3}/lib/proc.js

@@ -662,7 +662,10 @@ function Proc(bundle, proc, usePidFile){
 
     //init
     if ( typeof(self.bundle) == "undefined" ) {
-        console.error('[ PROC ] Invalid or undefined proc name . Proc naming Aborted');
+        var _procMsg = '[ PROC ] Invalid or undefined proc name . Proc naming Aborted';
+        console.error(_procMsg);
+        // Guarantee the reason survives process.exit() on an async pipe (e.g. bin/gina-container).
+        try { fs.writeSync(2, _procMsg + '\n'); } catch (_e) { /* best-effort */ }
         process.exit(1)
     } else {
         init()

package/framework/{v0.5.2 → v0.5.3}/lib/state.js

@@ -15,6 +15,10 @@
 var fs       = require('fs');
 var nodePath = require('path');
 
+// #B43 — monotonic counter for unique same-process atomic-write temp filenames
+// (see this.write: a temp + rename keeps the JSON sidecar reads tear-free).
+var _sidecarWriteSeq = 0;
+
 /**
  * SQLite-backed key-value store for the five `~/.gina/` state files.
  *
@@ -184,7 +188,11 @@ function StateStore() {
      *
      * The sidecar write keeps every legacy read path (`require()`,
      * `requireJSON()`, `fs.readFileSync()`) working without modification.
-     * SQLite is canonical; the JSON file is derived from it.
+     * SQLite is canonical; the JSON file is derived from it. The sidecar is
+     * itself written atomically — a same-dir temp file then `fs.renameSync`
+     * (#B43) — so a concurrent fleet-boot reader never observes a truncated
+     * or empty file (a bare in-place write would let a partial read crash
+     * the booting process).
      *
      * Returns `false` when the store is unavailable (Node < 22.5.0 or
      * `GINA_HOMEDIR` not yet set); the caller should fall through to a
@@ -207,9 +215,23 @@ function StateStore() {
             'INSERT OR REPLACE INTO kv_store (key, value, updated_at) VALUES (?, ?, ?)'
         ).run(key, value, Date.now());
 
-        // Write JSON sidecar — derived from SQLite, needed by all read call sites
-        fs.writeFileSync(filePath, value);
-        try { fs.chmodSync(filePath, 0o755); } catch(chmodErr) {}
+        // Write the JSON sidecar — derived from SQLite, needed by all read call sites.
+        // #B43 — write it ATOMICALLY: a same-dir temp + rename, so a concurrent reader
+        // (requireJSON / require / raw JSON.parse on a fleet boot) never observes a
+        // truncated or empty file. A bare fs.writeFileSync truncates the target in
+        // place, leaving a window where a concurrent read parses partial JSON and
+        // crashes FATALLY (requireJSON -> process.exit(1); plain require -> uncaught
+        // SyntaxError). rename(2) is atomic within a filesystem; the temp is a sibling
+        // of the target so the two always share one.
+        var _tmp = filePath + '.' + process.pid + '.' + (_sidecarWriteSeq++) + '.tmp';
+        try {
+            fs.writeFileSync(_tmp, value);
+            try { fs.chmodSync(_tmp, 0o755); } catch(chmodErr) {}
+            fs.renameSync(_tmp, filePath);
+        } catch (writeErr) {
+            try { fs.unlinkSync(_tmp); } catch(unlinkErr) {}
+            throw writeErr;
+        }
 
         return true;
     };

package/framework/{v0.5.2 → v0.5.3}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.2-alpha.2",
+  "version": "0.5.3-alpha.2",
   "dependencies": {
     "@rhinostone/swig": "^2.7.2",
     "intl-messageformat": "^11.2.4",

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.5.2/core/gna');
+var _gna = require('./framework/v0.5.3/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.5.2/core/controller');
-var EntitySuper     = require('./framework/v0.5.2/core/model/entity');
+var SuperController = require('./framework/v0.5.3/core/controller');
+var EntitySuper     = require('./framework/v0.5.3/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.5.2/lib/uuid');
+var uuid = require('./framework/v0.5.3/lib/uuid');
 
 module.exports = {
 

package/llms.txt

@@ -794,7 +794,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 97. **`String.prototype.match` + `indexOf(match)` is unsafe positional anchoring when match strings can be substrings of each other** — short regex matches (e.g. a bare `//` separator) collide on `indexOf` with longer matches earlier in the haystack (a `//` inside a URL string on a prior line that already passed the guard). Manifested at `helpers/json/src/main.js:63-78` where the comment-stripping loop did `commentsWithSlashes = jsonStr.match(/\/\/(.*)?/g)` + per-match `jsonStr.indexOf(m)` + `charAt(pos-1)` URL-guard: the bare `//` separator's `indexOf` re-found the URL's `//`, the guard re-fired against the URL's `:`, and the real separator was never stripped — `JSON.parse` then threw `Expected double-quoted property name` on every bundle config combining a URL string with a bare `//` line. **Use `matchAll` (returns `match.index` per occurrence) when positional iteration is needed, or restructure to per-line scanning.** Related secondary trap: greedy regex-and-loop has implicit per-line scope (`(.*)?` consumed rest of line so only the FIRST `//` per line was guarded); naively replacing it with a non-greedy single-pass lookbehind `(?<![:"\\])\/\/[^\n]*/g` flattens this to per-position and would strip from mid-string `//`-bearing URLs like `"http://host//:rest"` — 8 fixtures under `lib/collection/test/data/` (Couchbase travel-sample data) carry exactly this pattern, caught by `test/lib/collection.test.js` § 05's `assert.deepStrictEqual(result, mocks)` where `mocks` is `requireJSON(...)`. **Final fix shape**: `split('\n')` + per-line leftmost `//` + `:` / `"` / `\` char-before guard — mirrors the original greedy heuristic without the substring-collision class of bug. Established 2026-05-13 (commit `2210ab17`); full incident narrative in the project's post-mortem store.
 
-98. **Secrets resolver — `${secret:KEY}` placeholder substitution in bundle JSON configs at config-load time** — `lib/secrets` walks the merged per-bundle config and substitutes `${secret:KEY}` placeholders from `process.env[KEY]` before `self.envConf[bundle][env]` is finalised in `core/config.js::loadBundleConfig`. Anchored regex `^\${secret:([A-Z_][A-Z0-9_]*)\}$` matches ONLY when the entire string value is the placeholder — mixed strings (`"prefix-${secret:K}-suffix"`) pass through unchanged (deliberate scope choice: removes the "is `{` substitution or literal?" ambiguity). Non-string scalars are walked but never mutated; nested objects and arrays descend recursively. **Fail-closed**: unset / empty env var throws `Error('Secret resolution failed')` (no key name in the message — the key is attached as a non-enumerable `_ginaSecretKey` property for debug-only logging; consumer surfaces never see the key name). Resolution happens once per config-load cycle (in-place mutation; second pass finds nothing). Cache invalidation: `config.refresh()` re-runs the resolver, but secret rotation needs a process restart (the supervisor inherits its env from container init, not from the running framework). **Pluggable backend interface** — `secrets.resolve(config, backend?)` accepts a `{resolve(key) → string|throw}` object; only the `process.env` backend ships in this iteration, but the API is stable for future plug-ins (Vault, SOPS, K8s Secrets). **Path tracking via `WeakMap`** — `secrets.getResolvedPaths(config)` returns the dotted paths (`'db.password'`, `'items[0]'`) the resolver substituted; storage is GC'd when the config is collected and never serialised. Groundwork for a future log-redaction wrapper at any merged-conf print site (`Inspector` payload, debug-export tools); no such print site exists in `core/config.js` today (existing `console.debug` calls interpolate scalar identifiers, not the merged object). **Consumers** — `gina.plugins.Csrf()` reads `settings.csrf.secret` (placeholder-resolved) with precedence `opts.secret` > `settings.csrf.secret` > `process.env.GINA_CSRF_SECRET` (back-compat); `gina bundle:mcp-start` re-runs the resolver on the parsed `mcp.json` immediately after `requireJSON()` so `server.authToken` etc. resolve before downstream readers; bundle scaffolding (`project:add` / `bundle:add`) recommends the placeholder shape in `core/template/conf/settings.json` and `core/template/boilerplate/bundle/index.js`. Established 2026-05-13 (#SECRETS1, commits `8aa2ec82` resolver + wiring, `c1b09ed5` syntax rename `{secret:KEY}` → `${secret:KEY}`, `7a8b0f36` csrf.secret slot, `7d513638` mcp.json route, `33f34b23` scaffolding).
+98. **Secrets resolver — `${secret:KEY}` placeholder substitution in bundle JSON configs at config-load time** — `lib/secrets` walks the merged per-bundle config and substitutes `${secret:KEY}` placeholders from `process.env[KEY]` before `self.envConf[bundle][env]` is finalised in `core/config.js::loadBundleConfig`. Anchored regex `^\${secret:([A-Z_][A-Z0-9_]*)\}$` matches ONLY when the entire string value is the placeholder — mixed strings (`"prefix-${secret:K}-suffix"`) pass through unchanged (deliberate scope choice: removes the "is `{` substitution or literal?" ambiguity). Non-string scalars are walked but never mutated; nested objects and arrays descend recursively. **Fail-closed**: unset / empty env var throws `Error('Secret resolution failed')` (no key name in the message — the key is attached as a non-enumerable `_ginaSecretKey` property for debug-only logging; consumer surfaces never see the key name). Resolution happens once per config-load cycle (in-place mutation; second pass finds nothing). Cache invalidation: `config.refresh()` re-runs the resolver, but secret rotation needs a process restart (the supervisor inherits its env from container init, not from the running framework). **Pluggable backend interface** — `secrets.resolve(config, backend?)` accepts a `{resolve(key) → string|throw}` object; only the `process.env` backend ships in this iteration, but the API is stable for future plug-ins (Vault, SOPS, K8s Secrets). **Path tracking via `WeakMap`** — `secrets.getResolvedPaths(config)` returns the dotted paths (`'db.password'`, `'items[0]'`) the resolver substituted; storage is GC'd when the config is collected and never serialised. Groundwork for a future log-redaction wrapper at any merged-conf print site (`Inspector` payload, debug-export tools); no such print site exists in `core/config.js` today (existing `console.debug` calls interpolate scalar identifiers, not the merged object). **Consumers** — `gina.plugins.Csrf()` reads `settings.csrf.secret` (placeholder-resolved) with precedence `opts.secret` > `settings.csrf.secret` > `process.env.GINA_CSRF_SECRET` (back-compat); `gina bundle:mcp-start` re-runs the resolver on the parsed `mcp.json` immediately after `requireJSON()` so `server.authToken` etc. resolve before downstream readers; bundle scaffolding (`project:add` / `bundle:add`) recommends the placeholder shape in `core/template/conf/settings.json` and `core/template/boilerplate/bundle/index.js`. Established 2026-05-13 (#SECRETS1, commits `8aa2ec82` resolver + wiring, `c1b09ed5` syntax rename `{secret:KEY}` → `${secret:KEY}`, `7a8b0f36` csrf.secret slot, `7d513638` mcp.json route, `33f34b23` scaffolding). **#B42 (2026-06-14, commit `341acc4f`):** the config-load catch in `core/config.js::loadBundleConfig` now actually SURFACES that `_ginaSecretKey` — on a resolution failure it logs `console.debug('[CONFIG][loadBundleConfig] Secret resolution failed for \`<KEY>\` in \`<bundle>/<env>:<scope>\` configuration')` before propagating, so an operator with an unset placeholder learns WHICH key and WHICH bundle/config (previously the catch discarded the key and only the generic `Secret resolution failed` message bubbled to the top-level handler, naming neither). Debug level only — the propagated error and the top-level log stay generic, so the key never reaches a louder channel; a `<unknown>` fallback covers a future backend that throws without attaching the key.
 
 99. **Probe-first protocol for removing load-bearing fallback code** — when a defensive fallback (eval fallback, try/catch shim, recovery branch) has documented history of being load-bearing despite "looking like dead code", apply the structural fix at the cause-side FIRST, then instrument the fallback with a stderr probe BEFORE removing it, then run the full test suite to observe whether the probe fires. Only remove the fallback (and the probe) AFTER observing zero probe fires across all sites. This turns "I reasoned the structural fix breaks the trigger condition" into "the test suite empirically confirms the fallback never executes after the structural fix". **Worked example** — #M22 logger circular-require (2026-05-14). The 3 eval fallbacks at `lib/logger/src/main.js:69` + `containers/file/index.js:16` + `containers/mq/index.js:10` had bitten a prior session (#SCS1c, commit `ae932a5e`, 2026-04-23) — the evals were removed WITHOUT the structural fix and every logger-consuming test crashed with `TypeError: merge is not a function at init`. The 2026-05-14 protocol: (1) apply ONLY the structural fix in `lib/merge/src/main.js` (`require('../../../helpers')` → direct `require(__dirname + '/../../../../../utils/prototypes.json_clone')`, same `JSON.clone` population without going through the for-loop helper loader). (2) Add `process.stderr.write('[m22-probe] eval fallback fired at <file>:<line>\n')` at each fallback site, KEEPING the eval intact. (3) Run full local suite, capture stderr, `grep -c '\[m22-probe\]'`. **Zero fires** = empirical evidence the structural fix worked. (4) Only THEN remove the probes + evals. (5) Re-run suite to verify clean. ~10 minutes of work; the equivalent "reason about it and hope" approach was the failure mode of #SCS1c. **Detection signal that the protocol is warranted**: any session prompt or proposal phrased as "X is load-bearing because the prior attempt failed when X was removed". When you see that shape, surface the probe-first protocol BEFORE any code deletion. **Reflex check**: if your proposed protocol is "apply X subset first, then the rest" without a measurement justification for the subset choice, you're hedging, not measuring. The user's "is this your measured recommendation?" reflex catches this — answer is to surface positive evidence (probe never fires) rather than just smaller-blast-radius framing. Sister rule: the global "No fix without measurement" + the "Verification has THREE outcomes" expansion. Established 2026-05-14 (#M22, commit `2247e22e`).
 
@@ -921,4 +921,16 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 177. **Couchbase connector — install-derived SDK resolution (v2 removed), `connectors.json` semantics, `getCluster()`, dev-mode index reporting** (replaces individual entries #29, #40, #41, #57, #136, #153) — connectors are keyed in `schema/connectors.json` by LOGICAL name (`primary`, `sessionStore`, `cache`, …) with the driver selected by the `connector` enum field (`couchbase`/`mysql`/`postgresql`/`sqlite`/`redis`/`ai`/…) — never introduce a separate `driver` field; the optional `version` field carries a semver range used by `connector:add --driver-version=…` for the npm-install hint. The Couchbase SDK major is derived from the project's INSTALLED `couchbase` npm version — the leading major of `dependencies.couchbase` selects `connector.v<major>.js`, which stamps `conn.sdk = { version: N }` — never from a config key, so migrating SDK majors is a driver bump (`npm install couchbase@^4`), not a config edit. SDK v2 is REMOVED as of 0.4.0: the resolver now throws a clear "SDK v2 is no longer supported — upgrade couchbase@^3/^4" error when the installed major is ≤ 2 or the connector file is missing (previously a silent fallback that crashed later with an opaque MODULE_NOT_FOUND); the v3-vs-v4 split remains for param shaping. Generalises: when a connector's behavior-version derives from an installed dependency rather than config, fail fast once the installed major drops below the supported floor. Couchbase entities expose a public `getCluster()` (on both the model-entity and N1QL-entity prototypes) returning the underlying SDK `Cluster` handle for features the ORM doesn't wrap — chiefly multi-document ACID transactions (`cluster.transactions().run(...)`, needs SDK 3.2+/4.x) — without touching private `_*` internals; it throws a coded `GINA_COUCHBASE_CLUSTER_UNRESOLVED` error when neither connection shape resolves. Dev-mode index reporting: the SDK v4 C++ binding never populates `meta.profile` despite `profile: 'timings'` being sent (confirmed on v4.6.0), so an async `EXPLAIN <statement>` fallback with a per-process per-statement cache supplies the plan instead (the first request for a new statement may show N/A; subsequent requests hit the cache), and `USE KEYS` plans surface as "KV lookup" via `ExpressionScan`/`KeyScan` operator detection. Two historical traps locked by tests: `conn._cluster.query()` must receive the full `queryOptions` object, not the raw params array (the raw form silently dropped `profile`/`scanConsistency`/`adhoc` from every query), and of the connector's two `register()` dispatch paths, Option B (`!_isRegisteredFromProto`) is the ALWAYS-active one — instrumentation or logging added to Option A never executes.
 
-178. **HTTP/2 query paths must tolerate a released response — retry re-entries and late upstream responses run after terminal exits (#B33, 2026-06-12, commit `9c2d802a`).** Terminal exits release the per-request refs, and `redirect()` releases them and THEN calls next(), so an inter-bundle HTTP/2 query can outlive its own request in three measured ways, each previously an uncaughtException → SIGTERM bundle kill: (1) every retry re-entry (the 502/timeout/stream-error/preflight setTimeout paths) re-executes the header-forward prep block, which read the released request's headers — null deref from a timer callback outside all try/catch; (2) a late upstream response's success path calls isHaltedRequest → getSession, which read the released request's session from the stream end handler; (3) a parsed upstream payload claiming a 3xx status routed into the redirect intercepts, which wrote headers to the released response (the emitter-mode intercept uncaught; the callback-mode one contained only via a fragile catch chain). All sites null-guarded: forwards and intercepts no-op on a released request (the same options object travels through retries, so options.headers already carries the attempt-1 values — nothing is lost), getSession reports no session, and the emitter-mode intercept falls through to the query#complete emit so listeners still learn the outcome. Live-request behaviour is byte-identical. Runtime-verified by driving the REAL query() through a standalone controller harness against local h2c servers (six probe modes, crash reproduced pre-fix and clean post-fix per site). Sibling unguarded request-header reads exist in OTHER lifecycle functions; the §23 guard pin is block-scoped to the fixed functions for exactly that reason. **Follow-up #B35 (2026-06-13, `714d816f`+next):** the 5 directly-callable SYNCHRONOUS siblings were MEASURED (standalone harness: createTestInstance → renderTEXT() releases the triplet → call → confirmed `uncaughtException`-class crash) and guarded with top-of-function early-returns — `isPopinContext` → false, `setRequestMethod` → null, `setRequestMethodParams` → (void), `getRequestMethodParams` → the cached value, `getFormsRules` → {} (tests `controller.test.js §25`). **#B36 (`c5eaeeb7`+next):** `renderJSON()` is the same shape — its delegate reads `local.res.stream` synchronously before any `headersSent` guard, measured (standalone harness driving the real `render-json.js` delegate: CONTROL live rendered, RELEASE after `renderTEXT()` threw `reading 'stream'`) to crash a released response → SIGTERM; guarded with a top-of-function `if (local.res == null) return` (tests `render-json.test.js §03`). The render-swig / render-nunjucks delegates share the same read but are the NON-FATAL async class (measured 2026-06-13, NOT guarded): their `render()` is `async` and `this.render` returns the delegate promise un-awaited, so a released-instance read rejects → `unhandledRejection` → `gna.js:726` logs it (no SIGTERM). This is the canonical severity-axis example — a SYNCHRONOUS released read (render-json `#B36`, the `#B35` helpers) is a SIGTERM bundle-kill worth guarding; the same read in an ASYNC delegate is a logged unhandledRejection not worth editing the hot render path for. `redirect` GUARDED too (**#B37**, `a03e6f84`+next): measured synchronous, so a released second-call (redirect-then-redirect, or render-error-then-redirect) crashed `reading 'originalMethod'` → SIGTERM; top-of-function `if (local.req == null) return` (tests `controller.test.js §26`). **#B38 (2026-06-13) — the #B37 "SIGTERM class CLOSED" claim was premature: an exhaustive sweep of EVERY synchronous controller surface found SIX more lethal sync residuals, each measured (CONTROL no-throw / RELEASE positive crash, then no-throw post-guard) and guarded top-of-function with the same `if (local.req|res == null) return <default>` shape:** `downloadFromLocal` (`reading 'setHeader'`), the inner `start` of `store` (`reading 'files'` — reached SYNCHRONOUSLY through the documented `store(target).onComplete(cb)` wrapper, which calls `start` OUTSIDE the async `store` body; the #B35 probe had only tried `store('t')`, which returns the wrapper WITHOUT calling `start`, so `store` was wrongly filed as async-deferred here), `renderStream` (`reading 'stream'` — its controller wrapper AND the delegate are both synchronous, and the read precedes the delegate's headersSent guard, mirroring the #B36 render-json placement), `push` (`reading 'method'`), `pauseRequest` (`reading 'url'`), `resumeRequest` (`reading 'session'`/`'method'`) — tests `controller.test.js §27` + `render-stream.test.js §11`. Genuinely document-skipped (measured NON-FATAL, mirroring the render-swig/nunjucks #B36 decision): `downloadFromURL` (its reads sit inside an `async function`, so any throw is a rejected promise → `unhandledRejection`), and the render-path inner fns `setResources` / `getNodeRes` (sync, but invoked ONLY from the async render delegates, so a throw rejects the delegate promise — and the captured-req fix-shape was declined because the captured req is itself null in the released-response case). **Rule: lethality follows the NEAREST async boundary, not the function's own sync/async keyword — a sync read with no async function between it and the dispatcher is a SIGTERM bundle-kill (guard it); the same read reached only through an async function degrades to a logged unhandledRejection (skip it). Probe-asymmetry corollary: "no throw" is NOT proof of safety — feed inputs that actually REACH the deref (`resumeRequest({})` dodged its `req.session` read via an `&&` short-circuit + an early `throwError` return and looked safe until re-measured with a deref-reaching input).**
+178. **HTTP/2 query paths must tolerate a released response — retry re-entries and late upstream responses run after terminal exits (#B33, 2026-06-12, commit `9c2d802a`).** Terminal exits release the per-request refs, and `redirect()` releases them and THEN calls next(), so an inter-bundle HTTP/2 query can outlive its own request in three measured ways, each previously an uncaughtException → SIGTERM bundle kill: (1) every retry re-entry (the 502/timeout/stream-error/preflight setTimeout paths) re-executes the header-forward prep block, which read the released request's headers — null deref from a timer callback outside all try/catch; (2) a late upstream response's success path calls isHaltedRequest → getSession, which read the released request's session from the stream end handler; (3) a parsed upstream payload claiming a 3xx status routed into the redirect intercepts, which wrote headers to the released response (the emitter-mode intercept uncaught; the callback-mode one contained only via a fragile catch chain). All sites null-guarded: forwards and intercepts no-op on a released request (the same options object travels through retries, so options.headers already carries the attempt-1 values — nothing is lost), getSession reports no session, and the emitter-mode intercept falls through to the query#complete emit so listeners still learn the outcome. Live-request behaviour is byte-identical. Runtime-verified by driving the REAL query() through a standalone controller harness against local h2c servers (six probe modes, crash reproduced pre-fix and clean post-fix per site). Sibling unguarded request-header reads exist in OTHER lifecycle functions; the §23 guard pin is block-scoped to the fixed functions for exactly that reason. **Follow-up #B35 (2026-06-13, `714d816f`+next):** the 5 directly-callable SYNCHRONOUS siblings were MEASURED (standalone harness: createTestInstance → renderTEXT() releases the triplet → call → confirmed `uncaughtException`-class crash) and guarded with top-of-function early-returns — `isPopinContext` → false, `setRequestMethod` → null, `setRequestMethodParams` → (void), `getRequestMethodParams` → the cached value, `getFormsRules` → {} (tests `controller.test.js §25`). **#B36 (`c5eaeeb7`+next):** `renderJSON()` is the same shape — its delegate reads `local.res.stream` synchronously before any `headersSent` guard, measured (standalone harness driving the real `render-json.js` delegate: CONTROL live rendered, RELEASE after `renderTEXT()` threw `reading 'stream'`) to crash a released response → SIGTERM; guarded with a top-of-function `if (local.res == null) return` (tests `render-json.test.js §03`). The render-swig / render-nunjucks delegates share the same read but are the NON-FATAL async class (measured 2026-06-13, initially NOT guarded — GUARDED as of #B45, see below): their `render()` is `async` and `this.render` returns the delegate promise un-awaited, so a released-instance read rejects → `unhandledRejection` → `gna.js:726` logs it (no SIGTERM). This is the canonical severity-axis example — a SYNCHRONOUS released read (render-json `#B36`, the `#B35` helpers) is a SIGTERM bundle-kill worth guarding; the same read in an ASYNC delegate is a logged unhandledRejection not worth editing the hot render path for. **#B45 (2026-06-14, `d9bfc5af`) reversed that for the render delegates:** production surfaced exactly the predicted `unhandledRejection` (a controller firing several parallel `self.query()` calls against a downed upstream — the first failure callback renders+releases the triplet, a later callback re-enters `render()` at `local.res === null` → render-swig.js:259 `res.stream` throws), which is the #B36 "revisit only if the log noise proves operationally costly" trigger. All four async delegates (render-swig / render-nunjucks + both async variants) now carry the same top-of-function `if (local.res == null) return` guard as render-json/render-stream — one null check at the top, byte-identical on live requests; the rarer in-flight #M1 `setResources` race (render-swig.js:613 → controller.js:896, caught + #B31-guarded) is unchanged. The severity-axis lesson still holds (sync → SIGTERM → always guard; async → unhandledRejection → guard only once the noise is shown operationally costly) — #B45 is the worked example of the async "guard-when-costly" branch firing (tests `render-swig.test.js §19` / `render-nunjucks.test.js §08` / `render-engine-dispatch.test.js §08`). `redirect` GUARDED too (**#B37**, `a03e6f84`+next): measured synchronous, so a released second-call (redirect-then-redirect, or render-error-then-redirect) crashed `reading 'originalMethod'` → SIGTERM; top-of-function `if (local.req == null) return` (tests `controller.test.js §26`). **#B38 (2026-06-13) — the #B37 "SIGTERM class CLOSED" claim was premature: an exhaustive sweep of EVERY synchronous controller surface found SIX more lethal sync residuals, each measured (CONTROL no-throw / RELEASE positive crash, then no-throw post-guard) and guarded top-of-function with the same `if (local.req|res == null) return <default>` shape:** `downloadFromLocal` (`reading 'setHeader'`), the inner `start` of `store` (`reading 'files'` — reached SYNCHRONOUSLY through the documented `store(target).onComplete(cb)` wrapper, which calls `start` OUTSIDE the async `store` body; the #B35 probe had only tried `store('t')`, which returns the wrapper WITHOUT calling `start`, so `store` was wrongly filed as async-deferred here), `renderStream` (`reading 'stream'` — its controller wrapper AND the delegate are both synchronous, and the read precedes the delegate's headersSent guard, mirroring the #B36 render-json placement), `push` (`reading 'method'`), `pauseRequest` (`reading 'url'`), `resumeRequest` (`reading 'session'`/`'method'`) — tests `controller.test.js §27` + `render-stream.test.js §11`. Genuinely document-skipped (measured NON-FATAL, by the same async-boundary reasoning — the render delegates themselves since GUARDED, see #B45 above): `downloadFromURL` (its reads sit inside an `async function`, so any throw is a rejected promise → `unhandledRejection`), and the render-path inner fns `setResources` / `getNodeRes` (sync, but invoked ONLY from the async render delegates, so a throw rejects the delegate promise — and the captured-req fix-shape was declined because the captured req is itself null in the released-response case). **Rule: lethality follows the NEAREST async boundary, not the function's own sync/async keyword — a sync read with no async function between it and the dispatcher is a SIGTERM bundle-kill (guard it); the same read reached only through an async function degrades to a logged unhandledRejection (skip it). Probe-asymmetry corollary: "no throw" is NOT proof of safety — feed inputs that actually REACH the deref (`resumeRequest({})` dodged its `req.session` read via an `&&` short-circuit + an early `throwError` return and looked safe until re-measured with a deref-reaching input).** **#B44 (2026-06-14, commit `d95ac2fe`) — closes the one throwError-OWN residual the #B38 sweep flagged, and is the worked example of the measurement-scope-gap.** `throwError` reads `res.stream` (the HTTP/2 protocol branch) and then builds the error object from `res.error`/`res.stack`/`res.fallback` (~10 reads) BEFORE its OWN #B31 guard. For the 2-arg `throwError(code, Error|string)` and 3-arg `throwError(local.res, code, msg)` shapes `res` is already the released `local.res` (null) at those reads, so a released response crashed at `res.stream` on HTTP/2 bundles and at `res.error` on EVERY bundle (HTTP/1.1 reaches it because the `res.stream` read short-circuits off-h2). The 1-arg shape is unaffected (its `res` stays the truthy errObj until reassigned just before the guard — why #B31 sufficed for ITS scenario). Fixed with an up-front `if (!res) { warn; return false; }` early guard before any deref (tests `controller.test.js §28`); severity LOW (only the async `downloadFromURL` path reaches it today → non-fatal `unhandledRejection`), but it lifts the #B38 qualification for the synchronous 2-arg/3-arg surface on both protocols. **Measurement-scope-gap lesson: the FIRST-proposed fix (guard the `res.stream` read only) was INSUFFICIENT — it does NOTHING on HTTP/1.1 (already short-circuits there; the crash is at the `res.error` build) and merely RELOCATES the HTTP/2 crash to that same build. The prior repro was VERBATIM-TRUNCATED at the first crash line (it ran through the `res.stream` read, saw the TypeError, STOPPED), so it proved "the crash exists" but never executed the NEXT deref and so couldn't see that guarding one site just moves the crash. A repro that stops at the first crash cannot validate a "falls through to the guard" claim — match the repro's SCOPE to the claim's scope (the "match the measurement's scope to the claim's scope" rule, applied to a runtime repro). A per-site `&& res` is whack-a-mole here (~10 derefs before the guard); one early guard covers them all.**
+
+179. **A `Date.now()`-prefixed ID needs a LONG random suffix — `Date.now().toString(36) + '-' + uuid()` with the 4-char default is a birthday-paradox collision (and an intermittent test flake).** In a tight insert burst many IDs share the same millisecond prefix, so uniqueness rests on the random suffix; the lib/uuid 4-char default (62^4 ≈ 14.7M) collides at ~0.02% per 100 IDs (measured). The storage plugin's record `_id` used this shape and was widened to `uuid(16)` (62^16; collision ~1e-25), mirroring the lib/collection size=16 opt-in — `_id` is opaque (written once, never parsed), so it was a safe drop-in; the storage module is bundled into the browser bundle, so the dist was rebuilt (CI tool flags, baseline-build-first → only the 4 JS bundle files changed). Rule: any `Date.now()`-prefixed ID whose uniqueness matters uses `uuid(16)`, not the default. **CI corollary — diagnose flake-vs-merge BEFORE reacting:** a Tests red that appears ONLY on the post-release `Merge tag` run on master, on the FASTER Node version, with the SAME tree green on develop, is almost always a timing-dependent flaky test (this uniqueness check — faster loop packs more calls into the same ms → higher collision odds; or the container-boot integration test's intermittent boot crash), NOT a merge problem. A job rerun (same tree → green) confirms it, and the master post-merge run fires AFTER publish so such a red never blocks the release.
+
+180. **`process.exit(non-zero)` TRUNCATES async stdout/stderr on a PIPE — a diagnostic printed right before exit is LOST under a container log collector or a piped test harness (the empty-log crash signature).** Node makes `process.stdout`/`process.stderr` synchronous for a TTY/file but ASYNCHRONOUS for a pipe, and `process.exit()` tears the process down without draining the async buffer — so `console.emerg(msg); process.exit(1)` (or `process.stdout.write(msg); process.exit(1)`) prints `msg` on a local TTY yet emits NOTHING when stdout is a pipe. This was the container-boot CI flake's empty-log signature (exit 1, zero captured output): the daemonless `bin/gina-container` launcher AND every framework boot exit site (gna.js abort + mount-symlink, server.js ServerEngine catch, server.isaac.js https-credentials, proc.js invalid-proc-name) all used the antipattern, so a real boot crash in a piped/containerised deployment exited silently. Fix: flush the reason SYNCHRONOUSLY with `fs.writeSync(1|2, msg)` (blocks until the bytes are handed to the pipe) BEFORE `process.exit` — the launcher routes every diagnostic through an `out()` helper (fd 1); each framework site keeps its `console.emerg`/`console.error` and adds a guaranteed `fs.writeSync(2, …)` before the exit. Behaviourally proven: under a piped stdout an early-exit message now survives (`test/core/boot-exit-flush.test.js`, both a launcher spawn and an fd-2 child); happy-path boot unchanged. **Meta-lesson: a diagnostic added at the OBSERVER (a test capturing the child's piped output, e.g. a `bootDiagnostics()` dump) cannot fix truncation that happens at the SOURCE (the crashing process) — the bytes never reach the pipe, so the observer still sees empty. Fix the flush at every `*.exit()`-after-write site, not at the reader.** Rule: any `write/log → process.exit(non-zero)` on a boot / request / CLI path that may run with piped stdio (containers, spawned children, CI) must flush synchronously first — never rely on the async writer draining before the exit.
+
+181. **`gina port:set --force` pins a bundle to a fixed port even when another bundle holds it — the fix for `port:reset`'s alphabetical, count-sensitive allocation drifting hardcoded ports (2026-06-14, commit `fbde6543`).** `gina port:reset @<project> --start-port-from=N` allocates by SORTING the whole project's bundle set alphabetically (`reset.js` `self.bundles.sort()`) and counting up, so the bundle→port map depends on bundle COUNT + NAMES: adding / removing / splitting a bundle shifts every alphabetically-later bundle's port (a new bundle adds 2 ports/scheme to each prior block, moving the http/2 block start, AND inserts its own name into the sort order). A one-bundle-per-container deployment that HARDCODES each bundle's port (reverse-proxy upstream / compose mapping / `PORT` env) then breaks the moment the set changes — the bundle binds the drifted registry port while the proxy still targets the old one (connection refused). Root fix: don't depend on `port:reset`'s allocation — pin each container's own bundle to its declared port with `gina port:set <bundle> @<project> --protocol=http/2.0 --scheme=https --port=<PORT> --env=<env> --force`. The new `--force` evicts the prior holder from BOTH maps (forward `ports.json` + reverse `ports.reverse.json`) then assigns; WITHOUT `--force` an in-use port is still rejected — back-compat preserved, the conflict error+exit is byte-identical, only gated on `!--force`. Idempotent (re-setting the bundle's own port is a no-op); the displaced bundle re-pins itself the next time its own context runs the same line. Eviction (not swap) is the chosen semantic: the displaced bundle simply loses that protocol/scheme slot, which suits per-container deployments where each container owns exactly one bundle. Tests: `test/lib/port-set.test.js` §02 (force source pins) / §04 (parse) / §06 (evict-both-maps + non-force-still-rejects + idempotent) / §07 (help).
+
+182. **Framework-connection CLI flags (`--port`/`--mq-port`/`--host-v4`/`--hostname`/`--debug-port`) must be scoped to framework-scoped commands, or a sub-topic command's `--port` corrupts the framework command-socket port in `~/.gina/<short>/settings.json` (the recurring container-boot instability, 2026-06-14, commit `85a5debf`).** These flags were hoisted into `GINA_*` for EVERY command by TWO independent arg pre-processors — `bin/cli`'s param loop AND `utils/helper.js` `filterArgs` (the generic `--k=v → GINA_K` hoister) — and `framework:init` then persists `GINA_PORT` into settings.json. So `gina port:set <bundle> --port=N` (where `--port` is the BUNDLE port) overwrote the framework command-socket port (8124 → N); every later online command read the corrupted value, and depending on timing the framework daemon itself could bind the bundle port N instead of 8124. In a one-bundle-per-container deployment that pins its bundle port, this made the bundle unhealthy on boot (`bundle:start` → `[ gina ] not started` + `ECONNREFUSED`). Fix: BOTH hoisters gate the framework-connection flags on `isFrameworkScopedCmd` — `process.argv[2]` has no `:` (bare `start`/`stop`/`restart`, which are prefixed to `framework:*` downstream) OR starts with `framework:`; for a sub-topic command the flags stay in argv for that command's own parser to read. The `--inspect`/`--debug` splice stays unconditional (`bundle:start --inspect` relies on it). **Lesson (no-fix-without-measurement): reading mis-identified the write site — the first fix (the `bin/cli` param loop only) did NOT stop the corruption; temporarily instrumenting `createFileFromDataSync` to dump the stack on any settings.json write revealed the SECOND hoister (`filterArgs`) and the actual persist site in `framework:init`. Instrument the WRITE, don't infer it from reading the hoisters.**
+
+183. **The framework command socket must accumulate-and-guard-parse incoming chunks — an unguarded `JSON.parse(data.toString())` on each raw `'data'` chunk is a crash vector (2026-06-14, commit `c4694bde`).** `bin/cmd`'s `launchFramework` socket handler parsed every TCP chunk directly as JSON. The client (`bin/cli`) sends `JSON.stringify(process.argv)` in a SINGLE write, but TCP may split or coalesce it across chunks, and a partial / empty / non-JSON payload makes `JSON.parse` throw a `SyntaxError`; with no try/catch and no request lifecycle around it, the throw reaches `proc.js`'s `uncaughtException` handler → emerg + `dismiss(pid, 'SIGTERM')`, dropping the command and risking a daemon teardown (same throw-site crash family as the malformed-`%` decode DoS and the boot-exit-flush truncation entries). Fix: a per-connection `_payload` accumulator (declared in the `net.createServer(function(conn){…})` closure so each connection has its own buffer); `conn.on('data')` appends, then `try { argv = JSON.parse(_payload) } catch { return }` — a partial chunk keeps accumulating until complete, a non-JSON/empty payload never parses and is ignored, and on success the buffer resets for any further command on the connection. An `!Array.isArray(argv)` guard (warn + drop) closes the residual path, since `argv.join`/`argv[0]=` sit OUTSIDE the parse try and would throw on a valid-but-non-array payload. The parse catch stays SILENT (no log): it fires on a legitimate incomplete chunk too, before it is known whether the payload will complete, so a "parse failed" log there would be misleading. Rule: never `JSON.parse` a raw socket chunk unguarded — accumulate and try/catch, and guard the post-parse shape.
+
+184. **`~/.gina` state files must be written ATOMICALLY (temp + rename) — a truncate-in-place `fs.writeFileSync` lets a concurrent boot read a torn/empty file and crash (#B43, 2026-06-14, commit `519788ea`).** The five state files (`main.json`/`projects.json`/`settings.json`/`env.json`/`locals.json`) were written with a bare in-place `fs.writeFileSync(target, data)` at the two write sites — the StateStore JSON sidecar (`lib/state.js` `this.write`) and the legacy fallback (`lib/generator/index.js` `createFileFromDataSync`, the single chokepoint for all ~150 state-file writes). `writeFileSync` opens with `O_TRUNC` (target → 0 bytes) then streams, so a concurrent reader catches either an EMPTY file (the post-truncate window, payload-size-independent) or a PARTIAL one (mid-`write()`, widening with file size). Every state-file READ path is FATAL on a parse failure: `requireJSON` does `console.emerg` + `process.exit(1)` for non-`/controllers/` paths, and the more common plain `require('*.json')` boot reads (`gna.js`, `config.js`, framework `start.js`, six `init.js` sites) throw an uncaught `SyntaxError` → process death. So a concurrent fleet boot (many bundles/containers booting against one `~/.gina`) intermittently crashed when a reader caught a writer mid-write; the supervisor respawned and a later non-concurrent read succeeded, presenting as an intermittent crash. MEASURED with a concurrent reader/writer race on the exact `fs.writeFileSync` primitive (empty + partial reads → `JSON.parse` `SyntaxError`; the empty-read window is always present, the partial window widens with file size). Fix: both sites write a same-dir temp (`<target>.<pid>.<seq>.tmp`) then `fs.renameSync` — `rename(2)` is atomic within a filesystem, so a reader sees the complete old file or the complete new one, never a torn one; `chmod` the temp before rename, unlink-on-failure + rethrow. The SQLite `INSERT` was already atomic — only the JSON sidecar that readers consume was torn. Because `createFileFromDataSync` is the single write chokepoint, the two edits close the window for ALL readers (`requireJSON`, plain `require`, `gina-container`'s raw `JSON.parse`). A reader-side retry in `requireJSON` was DECLINED — it covers only the `requireJSON` minority (not the plain-`require` majority), defends a window the write fix already closes, and pollutes the hot general-purpose helper while masking genuine corruption. Rule: any `~/.gina` state-file write goes through the atomic temp+rename, never a bare in-place `writeFileSync`. Tests: `test/lib/state-atomic-write.test.js` (block-scoped source pins on both sites + fs-spy behavioural on the real generator legacy + StateStore sidecar paths + the deterministic torn-read consequence).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -72,12 +72,12 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.5.2/core/gna",
+  "main": "./framework/v0.5.3/core/gna",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "import": "./index.mjs",
-      "require": "./framework/v0.5.2/core/gna.js"
+      "require": "./framework/v0.5.3/core/gna.js"
     },
     "./gna": {
       "types": "./types/gna.d.ts",

package/script/check_roadmap_consistency.js

@@ -34,12 +34,17 @@
  *      are the sanctioned re-target form.
  *
  *   2. ABORT — a done (✅) row references a version NEWER than the one
- *      being released. A feature cannot have shipped in a version that
- *      does not exist yet; this catches target-version labels left on
- *      rows that were flipped to ✅ before the cut. Only tokens sharing
- *      the released version's MAJOR are compared, so dependency
- *      versions in prose (e.g. a `2.x` template-engine floor or a
- *      two-digit uuid major) cannot false-positive.
+ *      being released AND newer than the latest version the timeline
+ *      records as shipped. A feature cannot have shipped in a version
+ *      that does not exist yet; this catches target-version labels left
+ *      on rows that were flipped to ✅ before the cut. The comparison is
+ *      floored at the latest shipped stable (see `latestTimelineStable`)
+ *      so a hotfix / out-of-order cut of an OLDER line is not falsely
+ *      blocked by the (already-shipped) newer versions it legitimately
+ *      references. Only tokens sharing the released version's MAJOR are
+ *      compared, so dependency versions in prose (e.g. a `2.x`
+ *      template-engine floor or a two-digit uuid major) cannot
+ *      false-positive.
  *
  *   3. WARN — no timeline row marks the released version ✅
  *      (`` `X.Y.Z` ✅ ``). The timeline is coarse narrative, so this is
@@ -133,6 +138,34 @@ function compareVersions(a, b) {
     return 0;
 }
 
+/**
+ * The highest STABLE version a timeline row marks as shipped
+ * (`` `X.Y.Z` ✅ ``) — the roadmap's own record of "newest released".
+ * Used to floor rule 2 so a hotfix / out-of-order cut of an older line
+ * is not falsely flagged for the (already-shipped) newer versions it
+ * legitimately references. Deliberately matches ONLY the timeline form
+ * (version token immediately followed by ✅); status rows put the ✅
+ * marker in the FIRST cell, before the version, so they never match
+ * here, and `-alpha` marks are ignored (the timeline records stables).
+ *
+ * @param {string} content  full ROADMAP.md content
+ * @returns {string|null} the highest shipped stable version, or null if none
+ * @example
+ * latestTimelineStable('| **Q2** | `0.5.2` ✅ | x |\n| **Q1** | `0.5.0` ✅ | y |'); // '0.5.2'
+ * latestTimelineStable('| ✅ | feature | `0.5.0` | 2026-06-11 |');                  // null
+ */
+function latestTimelineStable(content) {
+    var re = /`(\d+\.\d+\.\d+)`\s*✅/g;
+    var best = null;
+    var m;
+    while ((m = re.exec(String(content || ''))) !== null) {
+        if (best === null || compareVersions(m[1], best) > 0) {
+            best = m[1];
+        }
+    }
+    return best;
+}
+
 /**
  * Parse the roadmap content into status rows.
  *
@@ -173,6 +206,21 @@ function check(opts) {
     var warnings = [];
     var targetMajor = Number(String(version).split('.')[0]);
 
+    // Rule 2 baseline. A ✅ row may legitimately reference a version NEWER than
+    // the one being released when that version has ALREADY shipped — i.e. a
+    // hotfix / out-of-order cut of an older line, while a newer minor is already
+    // out. Floor the "future" comparison at the latest version the timeline
+    // records as shipped, so only versions newer than BOTH the target AND the
+    // latest release count as "does not exist yet". For a normal forward cut
+    // (target at or above everything shipped) the baseline collapses to the
+    // target and behaviour is unchanged. (Residual: a bogus ✅ row whose version
+    // is ALSO bogusly timeline-marked shipped escapes — a two-mistake case far
+    // narrower than the single jumped-ahead-label drift rule 2 targets.)
+    var latestStable = latestTimelineStable(content);
+    var futureBaseline = (latestStable && compareVersions(latestStable, version) > 0)
+        ? latestStable
+        : version;
+
     var rows = parseStatusRows(content);
     for (var i = 0; i < rows.length; i++) {
         var row = rows[i];
@@ -188,7 +236,7 @@ function check(opts) {
             }
             if (row.status === '✅'
                 && Number(token.split('.')[0]) === targetMajor
-                && compareVersions(token, version) > 0
+                && compareVersions(token, futureBaseline) > 0
             ) {
                 failures.push({
                     rule: 'done-row-references-future-version',
@@ -279,6 +327,7 @@ function main() {
 module.exports = {
     extractVersionTokens: extractVersionTokens,
     compareVersions: compareVersions,
+    latestTimelineStable: latestTimelineStable,
     parseStatusRows: parseStatusRows,
     check: check,
     isAlphaPublish: isAlphaPublish,

package/utils/helper.js

@@ -81,6 +81,18 @@ function MainHelper(opt) {
             , err   = null
         ;
 
+        // #B40 — Treat framework-connection flags (--port, --mq-port, --host-v4,
+        // --hostname, --debug-port) as framework settings ONLY for framework-scoped
+        // commands (bare commands like `start`/`stop`/`restart` — prefixed to
+        // `framework:*` downstream — or explicit `framework:*`). For a sub-topic
+        // command (`port:set <bundle> --port=N`, `bundle:start ... --port=N`, ...)
+        // `--port` is the BUNDLE's port; hoisting it into GINA_PORT made
+        // framework:init overwrite the framework socket port in
+        // ~/.gina/<short>/settings.json, so later online commands connected to the
+        // wrong port and reported "[ gina ] not started".
+        var _topic = ( typeof(process.argv[2]) != 'undefined' ) ? process.argv[2] : '';
+        var _isFrameworkScopedCmd = ( _topic.indexOf(':') < 0 || /^framework:/.test(_topic) );
+
         if ( typeof(process.env['gina']) == 'undefined') {
             process.env['gina'] = {}
         }
@@ -93,6 +105,16 @@ function MainHelper(opt) {
                     continue;
                 }
 
+                // #B40 — don't hoist framework-connection flags for sub-topic
+                // commands; keep them in argv for the sub-command's own parser
+                // (e.g. port:set reads --port itself). Framework-scoped commands
+                // still hoist them (so `gina start --port=N` / `framework:set
+                // --port=N` persist to settings.json as intended).
+                if ( !_isFrameworkScopedCmd && /^\-\-(port|mq-port|host-v4|hostname|debug-port|debug_port)=/.test(process.argv[a]) ) {
+                    newArgv[a] = process.argv[a];
+                    continue;
+                }
+
 
                 // Split on the first `=` only. Values with `=` (e.g.
                 // `--driver-version=">=5.3.0 <6.0.0"`, base64-ish passwords,

package/framework/v0.5.2/VERSION

@@ -1 +0,0 @@
-0.5.2