@bridge4dev/runner 0.56.0 → 0.58.1

package/dist/index.js

@@ -9,6 +9,8 @@ import { ClaudeAdapter } from './adapters/claude.js';
 import { CodexAdapter } from './adapters/codex.js';
 import { ensureCodexHome } from './adapters/codex-home.js';
 import { sessionClaudePath } from './agent-binary.js';
+import { claimCageAuthority, runSystemctl } from './cage-authority.js';
+import { acquireDaemonLock, isHeldByAnother } from './daemon-lock.js';
 import { loadConfig, mergeIntoPairedConfig, requireConfig, saveConfig, } from './config.js';
 import { log } from './log.js';
 import { installIsWritable, installPrefixFor, isSupervisedProcess, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
@@ -17,12 +19,14 @@ import { Supervisor } from './supervisor.js';
 import { readStatusFile, isPidAlive, writeStatusFile, STATUS_FRESH_MS } from './status-file.js';
 import { RunnerWsClient } from './ws-client.js';
 import { RUNNER_VERSION } from './version.js';
-import { buildUnit, cpuQuotaPercent, devbridgeSliceOverridePath, limitsOverrideIsOutdated, limitsOverridePath, memoryPolicy, readMemoryFacts, sessionsSliceOverridePath, unitExecTarget, unitPath, writeLimitsOverride, DEVBRIDGE_SLICE, LIMITS_VERSION, SESSION_CPU_WEIGHT, SESSIONS_SLICE, } from './service-unit.js';
-import { initSessionCage, listSessionScopes, sessionCage, sweepOrphanSessionScopes, SESSION_TASKS_MAX, } from './session-cage.js';
+import { SESSION_GUARANTEE_BYTES } from './session-allocator.js';
+import { STALL_GRACE_MS } from './session-stall.js';
+import { buildUnit, cpuQuotaPercent, devbridgeSliceOverridePath, limitsOverrideIsOutdated, limitsOverridePath, memoryPolicy, readMemoryFacts, sessionsSliceOverridePath, unitExecTarget, unitPath, writeLimitsOverride, DEVBRIDGE_SLICE, LIMITS_VERSION, SESSION_CPU_WEIGHT, SESSIONS_SLICE, readSwapTotalBytes, } from './service-unit.js';
+import { defaultCageProbe, initSessionCage, readSliceLimits, listSessionScopes, sessionCage, sweepOrphanSessionScopes, SESSION_TASKS_MAX, } from './session-cage.js';
 import { SEARCH_GUARD_ENABLED, claudeSettingsPath, installSearchGuard, removeSearchGuard, searchGuardCommand, searchGuardHome, searchGuardHookPath, searchGuardStatus, } from './claude-settings.js';
 import { readOomKills, recordCrash, takeLastExit } from './crash-note.js';
 import { agentAuthStatuses } from './auth-relay.js';
-import { addSafeDirectory, agentConfigContour, dockerCheck, ensureAgentPath, firstUnreachableAncestor, hasSafeDirectory, inspectPath, knownWorkspacePaths, lingerEnabled, nodeCheck, otherHomeWithAgents, runnerIdentity, safeDirectoryCommand, systemctlHint, systemdUserBusReachable, systemdUserEnv, } from './environment.js';
+import { addSafeDirectory, agentConfigContour, dockerCheck, ensureAgentPath, firstUnreachableAncestor, hasSafeDirectory, inspectPath, knownWorkspacePaths, lingerEnabled, nodeCheck, otherHomeWithAgents, runnerIdentity, safeDirectoryCommand, systemctlHint, systemdUserBusReachable, } from './environment.js';
 import { mcpConfigDir } from './paths.js';
 import { readMemoryFactsFromSystemd } from './systemd-memory.js';
 const execFileAsync = promisify(execFile);
@@ -536,6 +540,11 @@ async function cmdPair(args) {
     // Probed here as well as at daemon start, so the very first record of this
     // server already carries the truth about its containment instead of the safe
     // default. Costs one throwaway process, once.
+    //
+    // `probe` and not `daemon` (#403): pairing may run its own throwaway unit and
+    // clean it up, and it has no business anywhere near a session's cage — there
+    // may be a daemon running sessions on this machine right now.
+    claimCageAuthority('probe');
     await initSessionCage();
     const capabilities = runnerCapabilities(apiUrl);
     const response = await fetch(`${apiUrl}/api/v1/dev/servers/claim`, {
@@ -607,7 +616,91 @@ const RESTART_DELAY_MS = 1_500;
  * a runner that refuses to start because it could not improve its own limits is
  * strictly worse than one that starts without the improvement.
  */
-async function repairResourceLimits() {
+/**
+ * The machine as the cage last measured it — see {@link reMeasureMachine}.
+ */
+let lastMachineFingerprint = null;
+/**
+ * Re-measure the machine on the hourly tick, and re-probe the cage when it has
+ * actually changed (#398 S3, work 11).
+ *
+ * `initSessionCage()` probes the machine EXACTLY ONCE, at daemon start, and
+ * remembers the answer; the hourly `repairResourceLimits` rewrites the slice's
+ * drop-in from fresh facts but never touches that cache. A live example, on the
+ * day of the incident: a swap file appeared on vmi3219930, and every session
+ * there went on being told `MemorySwapMax=0` — so the brake kept stopping dead
+ * instead of slowing down, on the one machine that had by then acquired
+ * somewhere to push pages. Until this, such a machine was cured only by
+ * restarting the runner.
+ *
+ * The probe costs a throwaway scope, so it is not done unconditionally: it runs
+ * only when the machine's fingerprint moved. New numbers reach LIVE sessions
+ * through the allocator's own tick, which reads the slice off cgroupfs and
+ * writes what has changed.
+ *
+ * The card is deliberately NOT promised here: `capabilities` are assembled once
+ * in `cmdDaemon` and travel only inside `hello`, so there is nothing to reissue
+ * them with short of a reconnect.
+ */
+async function reMeasureMachine(maxSessions) {
+    await repairResourceLimits(maxSessions);
+    try {
+        const slice = readSliceLimits();
+        const fingerprint = JSON.stringify({
+            swap: readSwapTotalBytes() ?? 0,
+            pot: slice?.potBytes ?? null,
+            brake: slice?.collectiveBrakeBytes ?? null,
+        });
+        if (lastMachineFingerprint === null) {
+            lastMachineFingerprint = fingerprint;
+            return;
+        }
+        if (fingerprint === lastMachineFingerprint)
+            return;
+        log.warn('daemon: the machine changed under us — re-measuring the session cage', {
+            was: lastMachineFingerprint,
+            now: fingerprint,
+        });
+        /**
+         * A re-probe that comes back WORSE does not take the cage away.
+         *
+         * `initSessionCage` replaces what the daemon knows, and its live probe is a
+         * `systemd-run` — one transient failure (a busy bus, a momentary
+         * `Failed to connect`) would answer `nice-only`, and from that moment every
+         * new session on that machine would start with no cage at all, until
+         * somebody restarted the runner. An hourly job must not be able to do that.
+         * Found by the independent review of 10.09.2026.
+         *
+         * Losing the cage for real is possible — someone remounts cgroups, the user
+         * bus goes — and it is not silent: the line below says so, and the next
+         * daemon start settles it.
+         */
+        // `keepCageIfWorse`: an hourly job must not be able to uncage a healthy
+        // machine on one transient `systemd-run` failure — see `initSessionCage`.
+        const facts = await initSessionCage(defaultCageProbe, { keepCageIfWorse: true });
+        /**
+         * Remembered only when the measurement actually SUCCEEDED (#398 S7, B4).
+         *
+         * The fingerprint used to be stored before the probe, so one transient
+         * failure — the very failure `keepCageIfWorse` exists to survive — left the
+         * next hour seeing an unchanged fingerprint and skipping the re-probe
+         * forever. The cage was kept, and the FACTS behind it stayed yesterday's:
+         * `swapMaxBytes` above all, which is the vmi3219930 bug this work was
+         * written for. Cured only by restarting the runner, which is what the whole
+         * job was supposed to stop needing.
+         */
+        if (facts.mode === 'scope')
+            lastMachineFingerprint = fingerprint;
+    }
+    catch (error) {
+        // Never fatal: a runner that dies because it could not re-measure is worse
+        // than one that keeps yesterday's numbers for another hour.
+        log.warn('daemon: could not re-measure the machine', {
+            error: String(error instanceof Error ? error.message : error),
+        });
+    }
+}
+async function repairResourceLimits(maxSessions) {
     try {
         const { facts, sessionsUsageBytes } = await readMemoryFactsFromSystemd();
         if (facts === null) {
@@ -628,17 +721,14 @@ async function repairResourceLimits() {
                 totalMB: Math.round(facts.totalBytes / 1048576),
             });
         }
-        if (!writeLimitsOverride(false, undefined, facts, sessionsUsageBytes))
+        if (!writeLimitsOverride(false, undefined, facts, sessionsUsageBytes, maxSessions))
             return;
         log.warn('daemon: resource limits drop-in written — reloading systemd', {
             path: limitsOverridePath(),
             version: LIMITS_VERSION,
             ...memoryPolicy(facts),
         });
-        await execFileAsync('systemctl', ['--user', 'daemon-reload'], {
-            timeout: 15_000,
-            env: systemdUserEnv(),
-        });
+        await runSystemctl(['daemon-reload'], { timeout: 15_000 });
         // Deliberately no restart: `daemon-reload` alone is enough for these
         // directives — verified live twice, in both directions: 2026-07-30 removing a
         // ceiling (MemoryMax 2G→infinity, OOMPolicy stop→continue) and 2026-08-12
@@ -757,13 +847,51 @@ async function cmdDaemon() {
     const config = requireConfig();
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
     sweepOrphanedMcpConfigs();
+    /**
+     * One daemon per user manager, checked BEFORE the sweep below (#403).
+     *
+     * The sweep stops every session scope this process does not know about, and
+     * at start-up that is all of them. A second daemon — `pnpm dev` of this
+     * package beside a paired runner, or a hand-started `devbridge-runner daemon`
+     * — therefore ends every live session the first one is supervising, and no
+     * guard inside the test suite covers that path.
+     *
+     * The escape hatch is deliberate and narrow: `DEVBRIDGE_ALLOW_SECOND_DAEMON=1`
+     * starts a second daemon with the `probe` grade, so it can run and be
+     * developed against but cannot touch anybody's cage.
+     */
+    const lock = acquireDaemonLock();
+    const second = isHeldByAnother(lock);
+    if (second) {
+        if (process.env['DEVBRIDGE_ALLOW_SECOND_DAEMON'] !== '1') {
+            fail(`another devbridge-runner daemon is already running on this user (pid ${lock.heldBy}). ` +
+                "Two daemons stop each other's sessions — see the lock at " +
+                `${lock.path}. Set DEVBRIDGE_ALLOW_SECOND_DAEMON=1 to start one that cannot touch cages.`);
+        }
+        log.warn('daemon: a second daemon, started without the right to act on session cages', {
+            heldBy: lock.heldBy,
+        });
+    }
+    else {
+        process.once('exit', () => lock.release());
+    }
+    /**
+     * The daemon is the ONE process on this machine allowed to act on session
+     * cages (#403), and it says so here, once, before the first sweep.
+     *
+     * Everything below — the sweep, the drop-ins, the probe, and later every
+     * limit written to a live scope — goes through `cage-authority.ts` and would
+     * be refused without this line. A test process cannot reach it at all: the
+     * claim throws there rather than granting anything.
+     */
+    claimCageAuthority(second ? 'probe' : 'daemon');
     // Nothing of ours is running yet, so every `devbridge-session-*.scope` on this
     // machine belongs to a process that is gone. Stopping the scope takes the
     // whole tree under it — which is the answer to the `ugrep` that outlived its
     // session by 10 h 51 min on 16.08, and to every scope the OOM killer left in
     // `failed` (a name systemd will otherwise refuse to reuse).
     await sweepOrphanSessionScopes();
-    await repairResourceLimits();
+    await repairResourceLimits(config.limits?.max_sessions);
     // After the drop-ins are on disk and reloaded, never before: the probe below
     // creates `devbridge-sessions.slice`, and a slice first loaded without its
     // policy would hold no ceiling until the next daemon-reload.
@@ -785,6 +913,29 @@ async function cmdDaemon() {
         },
         ...(config.mcp ? { mcp: { url: config.mcp.url, token: config.mcp.token } } : {}),
         ...(config.limits?.max_sessions ? { maxSessionsLimit: config.limits.max_sessions } : {}),
+        /**
+         * #398 S6: the machine owner's memory knobs, read once here and passed
+         * down. Nothing outside this file imports `config.js`, and a module that
+         * read the file itself would be the first place for two answers about one
+         * setting to appear.
+         */
+        memoryKnobs: {
+            ...(config.limits?.adaptive_memory === undefined
+                ? {}
+                : { adaptive: config.limits.adaptive_memory }),
+            ...(config.limits?.session_memory_min === undefined
+                ? {}
+                : { guaranteeBytes: config.limits.session_memory_min * 1024 * 1024 }),
+            ...(config.limits?.session_memory_max === undefined
+                ? {}
+                : { sessionMaxBytes: config.limits.session_memory_max * 1024 * 1024 }),
+        },
+        ...(config.limits?.memory_stall_grace_sec === undefined
+            ? {}
+            : { stallGraceMs: config.limits.memory_stall_grace_sec * 1000 }),
+        ...(config.limits?.memory_stall_action === undefined
+            ? {}
+            : { memoryStallAction: config.limits.memory_stall_action }),
         // The same veto the capability list honours — announced AND enforced, so a
         // frame from an API that has not noticed still cannot start a run.
         verifyEnabled: config.verify?.enabled !== false,
@@ -836,7 +987,7 @@ async function cmdDaemon() {
     pruneTimer.unref();
     // Re-measure the machine — see `LIMITS_RECHECK_MS`. Writes nothing in the
     // normal case, so this is a file read and some arithmetic once an hour.
-    const limitsTimer = setInterval(() => void repairResourceLimits(), LIMITS_RECHECK_MS);
+    const limitsTimer = setInterval(() => void reMeasureMachine(config.limits?.max_sessions), LIMITS_RECHECK_MS);
     limitsTimer.unref();
     const shutdown = (signal) => {
         log.info(`daemon: ${signal} received, shutting down`);
@@ -931,6 +1082,9 @@ async function cmdInstallService() {
     requireConfig(); // fail early if not paired
     if (process.platform !== 'linux')
         fail('install-service supports Linux/systemd only');
+    // Installing the service writes the runner's own unit and starts it; it never
+    // touches a session's cage, so `install` and not `daemon` (#403).
+    claimCageAuthority('install');
     const target = unitPath();
     fs.mkdirSync(path.dirname(target), { recursive: true });
     const exec = unitExecTarget();
@@ -979,10 +1133,8 @@ async function cmdInstallService() {
         print(`note: the service runs ${exec.execStart} directly — re-run install-service after reinstalling the package.`);
     }
     try {
-        await execFileAsync('systemctl', ['--user', 'daemon-reload'], { env: systemdUserEnv() });
-        await execFileAsync('systemctl', ['--user', 'enable', '--now', 'devbridge-runner'], {
-            env: systemdUserEnv(),
-        });
+        await runSystemctl(['daemon-reload']);
+        await runSystemctl(['enable', '--now', 'devbridge-runner']);
         print('Service enabled and started (systemctl --user).');
     }
     catch (error) {
@@ -1008,7 +1160,9 @@ function printCheck(check) {
 /** One property of the user service, or null when systemd cannot answer. */
 async function systemctlProperty(name) {
     try {
-        const { stdout } = await execFileAsync('systemctl', ['--user', 'show', 'devbridge-runner', '-p', name, '--value'], { timeout: 10_000, env: systemdUserEnv() });
+        const { stdout } = await runSystemctl(['show', 'devbridge-runner', '-p', name, '--value'], {
+            timeout: 10_000,
+        });
         const value = stdout.trim();
         return value.length > 0 ? value : null;
     }
@@ -1378,6 +1532,9 @@ async function reportAgentReadiness(paths, fix) {
 }
 async function cmdDoctor(args) {
     const fix = args.includes('--fix');
+    // Reading needs no right at all; `--fix` writes the runner's own drop-in and
+    // reloads systemd, which is the `install` grade and nothing above it (#403).
+    claimCageAuthority(fix ? 'install' : 'probe');
     const config = loadConfig();
     print(`devbridge-runner ${RUNNER_VERSION}`);
     print(config ? `Paired with: ${config.server.name} (${config.api.url})` : 'Not paired');
@@ -1397,6 +1554,52 @@ async function cmdDoctor(args) {
     // build, so this is the honest ceiling regardless of what the dashboard says.
     const advised = Math.max(1, Math.floor(os.totalmem() / 1024 / 1024 / 1536));
     print(`  fits sessions   ~${advised} (at ~1.5 GB per session under load)`);
+    /**
+     * #398 S6. Every memory number `doctor` printed before this block came off
+     * systemd or off `os` — it never said a word about `[limits]` in the machine
+     * owner's own `config.toml`, so «I set a guarantee and nothing changed» had no
+     * answer anywhere on the machine. Each line names the value in force AND
+     * where it came from.
+     */
+    print('');
+    print('Session memory (#398)');
+    {
+        const limits = loadConfig()?.limits;
+        const shipped = (value) => `${value} (shipped default)`;
+        const chosen = (value, unit) => `${value}${unit} (config.toml)`;
+        print(`  adaptive        ${limits?.adaptive_memory === false
+            ? 'OFF (config.toml) — sessions get the fixed pre-0.58.0 third'
+            : 'on (shipped default) — the share follows what is actually free'}`);
+        print(`  guarantee       ${limits?.session_memory_min === undefined
+            ? shipped(Math.round(SESSION_GUARANTEE_BYTES / 1024 / 1024)) + ' MB'
+            : chosen(limits.session_memory_min, ' MB')}`);
+        print(`  session ceiling ${limits?.session_memory_max === undefined
+            ? 'whatever the machine has free (shipped default)'
+            : chosen(limits.session_memory_max, ' MB')}`);
+        print(`  stall grace     ${limits?.memory_stall_grace_sec === undefined
+            ? shipped(Math.round(STALL_GRACE_MS / 1000)) + ' s'
+            : chosen(limits.memory_stall_grace_sec, ' s')}`);
+        print(`  when it stalls  ${limits?.memory_stall_action === 'report-only'
+            ? 'report only (config.toml) — DevBridge stops nothing'
+            : 'stop the biggest command (shipped default)'}`);
+        print(`  seats           ${limits?.max_sessions ?? 'the API decides (no max_sessions set)'}`);
+        const slice = readSliceLimits();
+        /**
+         * Named precisely, because «MISSING» alone sent people looking for a fault.
+         *
+         * The brake arrives with `LIMITS_VERSION` 6, and a machine whose runner has
+         * not restarted since the update simply does not have it yet — that is a
+         * pending update, not a broken machine. Found by the independent review of
+         * 10.09.2026.
+         */
+        const brakeInForce = slice?.collectiveBrakeBytes ?? null;
+        const dropInIsOld = limitsOverrideIsOutdated();
+        print(`  collective brake ${brakeInForce === null
+            ? dropInIsOld
+                ? 'not applied yet — the drop-in on this machine is older than this runner; `doctor --fix` writes it'
+                : 'MISSING — run `devbridge-runner doctor --fix`; until then sessions get a smaller share each'
+            : `${Math.round(brakeInForce / 1024 / 1024)} MB in force on the slice`}`);
+    }
     print('');
     print('Service limits');
     const { facts: memFacts, sessionsUsageBytes: memSessionsUsage } = await readMemoryFactsFromSystemd();
@@ -1476,8 +1679,7 @@ async function cmdDoctor(args) {
     }
     let effective;
     try {
-        const { stdout } = await execFileAsync('systemctl', [
-            '--user',
+        const { stdout } = await runSystemctl([
             'show',
             'devbridge-runner',
             '-p',
@@ -1490,7 +1692,7 @@ async function cmdDoctor(args) {
             'OOMPolicy',
             '-p',
             'NRestarts',
-        ], { env: systemdUserEnv() });
+        ]);
         effective = stdout.trim().split('\n').filter(Boolean);
     }
     catch {
@@ -1629,7 +1831,7 @@ async function cmdDoctor(args) {
         }
     }
     try {
-        await execFileAsync('systemctl', ['--user', 'daemon-reload'], { env: systemdUserEnv() });
+        await runSystemctl(['daemon-reload']);
         print('systemctl --user daemon-reload — done.');
         print('Restart when sessions are idle: systemctl --user restart devbridge-runner');
     }

package/dist/policy.d.ts

@@ -71,6 +71,14 @@ export interface PolicyContext extends AgentGitPolicy {
      * than this release — and there the answer stays what it has always been.
      */
     agentAutoCommit?: boolean;
+    /**
+     * This session's memory ceiling in bytes, or `undefined` on a machine with no
+     * cage (#398 S5).
+     *
+     * Passed in rather than read here, so the pure policy stays pure and a test
+     * can put a session on a machine of any size.
+     */
+    sessionMemoryMaxBytes?: number;
     /**
      * Absolute path of the project's own prompt file, when this session was given
      * one (session 17).
@@ -226,5 +234,6 @@ export declare function evaluateRecipeCommand(command: string, ctx?: RecipeComma
  * workspace trust unchanged, which is exactly the old behaviour.
  */
 export declare function effectiveTrust(trustMode: TrustMode, mode?: AgentMode): TrustMode;
+export declare function requestedHeapBytes(command: string): number | null;
 export declare function evaluateToolUse(toolName: string, input: Record<string, unknown>, ctx: PolicyContext): PolicyDecision;
 //# sourceMappingURL=policy.d.ts.map

package/dist/policy.js

@@ -1173,6 +1173,46 @@ export function effectiveTrust(trustMode, mode) {
     // ask / plan — at most NORMAL, never AUTO.
     return trustMode === 'AUTO' ? 'NORMAL' : trustMode;
 }
+/**
+ * The largest Node heap this command line asks for, in bytes — or null when it
+ * asks for none.
+ *
+ * Both spellings systemd-era Node accepts (`--max-old-space-size=N` and
+ * `--max_old_space_size N`), anywhere on the line: the flag arrives through
+ * `NODE_OPTIONS=`, through `node --…`, and through a `pnpm` script that passes
+ * it on, and it is the NUMBER that matters, not who wrote it.
+ *
+ * The unit is megabytes, which is V8's own unit for the flag — a plain number,
+ * never a suffix.
+ */
+/**
+ * Commands that RUN node, as opposed to commands that merely mention it.
+ *
+ * The gate reads the heap flag out of a shell line, and a shell line is not one
+ * command: `sed -i 's/--max-old-space-size=8192/…=3000/' package.json` contains
+ * the flag and asks Node for nothing at all. Denying that was worse than a
+ * nuisance — LOWERING the flag is exactly what the refusal tells the agent to
+ * do, so the gate forbade its own remedy (#398 S7, B10).
+ */
+const NODE_RUNNERS = /(^|[\s;&|(])(sudo\s+)?(env\s+)?([A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(node|nodejs|npm|npx|pnpm|yarn|bun|deno|tsx|ts-node|vitest|jest)([\s;&|)]|$)/;
+export function requestedHeapBytes(command) {
+    let largest = null;
+    for (const segment of commandSegments(command)) {
+        // `NODE_OPTIONS=` carries the flag into whatever the segment starts, so it
+        // counts on its own; otherwise the segment has to actually start a runtime.
+        if (!/NODE_OPTIONS\s*=/.test(segment) && !NODE_RUNNERS.test(segment))
+            continue;
+        for (const match of segment.matchAll(/--?max[-_]old[-_]space[-_]size(?:\s*=\s*|\s+)(\d+)/gi)) {
+            const mb = Number(match[1]);
+            if (!Number.isSafeInteger(mb) || mb <= 0)
+                continue;
+            const bytes = mb * 1024 * 1024;
+            if (largest === null || bytes > largest)
+                largest = bytes;
+        }
+    }
+    return largest;
+}
 export function evaluateToolUse(toolName, input, ctx) {
     // Read ONCE, here, and never `ctx.trustMode` again below: the branches that
     // follow are the whole of layer 1, and a single one still reading the raw
@@ -1227,6 +1267,34 @@ export function evaluateToolUse(toolName, input, ctx) {
         }
         if (gitAsk)
             return gitAsk;
+        /**
+         * A heap the cage cannot honour (#398 S5).
+         *
+         * Same position as everything above it and for the same reason: under AUTO
+         * the Bash branch returns `allow` two lines down, and a rule placed below
+         * that line is dead in the one mode most sessions run in. That mistake cost
+         * a whole release once (session 13).
+         *
+         * From the incident this plan comes from: the agent raised its own heap to
+         * 4 GB, then to 6 GB, against a wall of 4296 MB, and each time made things
+         * worse — the ceiling is enforced OUTSIDE the process, so asking for more
+         * only means being stopped sooner. The reason is written for the model to
+         * read: it names the number and the way out.
+         */
+        if (ctx.sessionMemoryMaxBytes !== undefined && ctx.sessionMemoryMaxBytes > 0) {
+            for (const variant of [command, dequote(command)]) {
+                const asked = requestedHeapBytes(variant);
+                if (asked !== null && asked > ctx.sessionMemoryMaxBytes) {
+                    const mb = (bytes) => Math.round(bytes / (1024 * 1024));
+                    return {
+                        decision: 'deny',
+                        reason: `this command asks Node for a ${mb(asked)} MB heap, and this session cannot exceed ` +
+                            `${mb(ctx.sessionMemoryMaxBytes)} MB — the ceiling is enforced outside the process, so a ` +
+                            'bigger heap only means being stopped sooner. Lower --max-old-space-size, or split the work up',
+                    };
+                }
+            }
+        }
         if (trust === 'STRICT')
             return { decision: 'ask', reason: 'strict mode' };
         if (trust === 'AUTO')