@bridge4dev/runner 0.56.0 → 0.58.1

package/dist/config.d.ts

@@ -41,11 +41,79 @@ declare const ConfigSchema: z.ZodObject<{
         auth?: "link" | "own" | undefined;
     }>>;
     limits: z.ZodOptional<z.ZodObject<{
-        max_sessions: z.ZodNumber;
+        /**
+         * OPTIONAL since 0.58.0, and the change is a bug fix rather than a
+         * loosening.
+         *
+         * `loadConfig()` uses `.parse`, not `safeParse`, and a ZodError from it
+         * reaches `main().catch` and exits 1 — under systemd that is a restart
+         * loop. So while this field was required, a machine owner who opened
+         * `config.toml` to add any OTHER key under `[limits]` and did not happen
+         * to have this one would have taken their dev server down, and `doctor`
+         * could not have told them why: it dies on the same parse.
+         *
+         * The default is unchanged — absence means «the API's number decides»,
+         * which is what `get maxSessions()` already did.
+         */
+        max_sessions: z.ZodOptional<z.ZodNumber>;
+        /**
+         * #398 S6: the emergency switch back to the pre-0.58.0 behaviour.
+         *
+         * `false` puts every session on the fixed `max(pot / 3, 2 GiB)` share
+         * that shipped in 0.55.0, computed once at daemon start and never moved.
+         * It exists because this formula travels to dev servers nobody here has
+         * ever seen, and the two previous memory rules were both reasonable on
+         * the author's machine and destructive somewhere else. A machine owner
+         * who has to get work done tonight needs a way back that does not involve
+         * downgrading the runner.
+         */
+        adaptive_memory: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * The guarantee, in megabytes — what a session on this machine will not
+         * have taken away.
+         *
+         * The default is 2048, sized over the 1571 MB peak measured for a
+         * workspace `pnpm typecheck`. Lower it on a machine that runs lighter
+         * work and wants more sessions; raise it on one that runs heavier.
+         */
+        session_memory_min: z.ZodOptional<z.ZodNumber>;
+        /**
+         * A ceiling on the ceiling, in megabytes — the most any single session
+         * may be allowed to grow to, whatever the machine has free.
+         *
+         * For the owner who wants agents to leave room for something the runner
+         * cannot see (a build they run by hand, a database that spikes).
+         */
+        session_memory_max: z.ZodOptional<z.ZodNumber>;
+        /**
+         * How long a session that has stopped moving is given before its biggest
+         * command is stopped, in seconds. Default 180 (decision D6).
+         */
+        memory_stall_grace_sec: z.ZodOptional<z.ZodNumber>;
+        /**
+         * What happens when that time runs out: `stop-command` (the default) or
+         * `report-only`.
+         *
+         * `report-only` is for the owner who would rather have a session stand
+         * still than have a command stopped under it. It changes nothing else —
+         * the deadline still runs and the strip still shows it, so the person can
+         * act; only DevBridge stops acting on their behalf.
+         */
+        memory_stall_action: z.ZodOptional<z.ZodEnum<["stop-command", "report-only"]>>;
     }, "strip", z.ZodTypeAny, {
-        max_sessions: number;
+        max_sessions?: number | undefined;
+        adaptive_memory?: boolean | undefined;
+        session_memory_min?: number | undefined;
+        session_memory_max?: number | undefined;
+        memory_stall_grace_sec?: number | undefined;
+        memory_stall_action?: "stop-command" | "report-only" | undefined;
     }, {
-        max_sessions: number;
+        max_sessions?: number | undefined;
+        adaptive_memory?: boolean | undefined;
+        session_memory_min?: number | undefined;
+        session_memory_max?: number | undefined;
+        memory_stall_grace_sec?: number | undefined;
+        memory_stall_action?: "stop-command" | "report-only" | undefined;
     }>>;
     /**
      * Session 14: the machine owner's veto over running project recipes.
@@ -126,7 +194,12 @@ declare const ConfigSchema: z.ZodObject<{
         auth: "link" | "own";
     } | undefined;
     limits?: {
-        max_sessions: number;
+        max_sessions?: number | undefined;
+        adaptive_memory?: boolean | undefined;
+        session_memory_min?: number | undefined;
+        session_memory_max?: number | undefined;
+        memory_stall_grace_sec?: number | undefined;
+        memory_stall_action?: "stop-command" | "report-only" | undefined;
     } | undefined;
     verify?: {
         enabled: boolean;
@@ -155,7 +228,12 @@ declare const ConfigSchema: z.ZodObject<{
         auth?: "link" | "own" | undefined;
     } | undefined;
     limits?: {
-        max_sessions: number;
+        max_sessions?: number | undefined;
+        adaptive_memory?: boolean | undefined;
+        session_memory_min?: number | undefined;
+        session_memory_max?: number | undefined;
+        memory_stall_grace_sec?: number | undefined;
+        memory_stall_action?: "stop-command" | "report-only" | undefined;
     } | undefined;
     verify?: {
         enabled?: boolean | undefined;

package/dist/config.js

@@ -41,7 +41,65 @@ const ConfigSchema = z.object({
     // processes and worktrees may exist at once.
     limits: z
         .object({
-        max_sessions: z.number().int().min(1).max(64),
+        /**
+         * OPTIONAL since 0.58.0, and the change is a bug fix rather than a
+         * loosening.
+         *
+         * `loadConfig()` uses `.parse`, not `safeParse`, and a ZodError from it
+         * reaches `main().catch` and exits 1 — under systemd that is a restart
+         * loop. So while this field was required, a machine owner who opened
+         * `config.toml` to add any OTHER key under `[limits]` and did not happen
+         * to have this one would have taken their dev server down, and `doctor`
+         * could not have told them why: it dies on the same parse.
+         *
+         * The default is unchanged — absence means «the API's number decides»,
+         * which is what `get maxSessions()` already did.
+         */
+        max_sessions: z.number().int().min(1).max(64).optional(),
+        /**
+         * #398 S6: the emergency switch back to the pre-0.58.0 behaviour.
+         *
+         * `false` puts every session on the fixed `max(pot / 3, 2 GiB)` share
+         * that shipped in 0.55.0, computed once at daemon start and never moved.
+         * It exists because this formula travels to dev servers nobody here has
+         * ever seen, and the two previous memory rules were both reasonable on
+         * the author's machine and destructive somewhere else. A machine owner
+         * who has to get work done tonight needs a way back that does not involve
+         * downgrading the runner.
+         */
+        adaptive_memory: z.boolean().optional(),
+        /**
+         * The guarantee, in megabytes — what a session on this machine will not
+         * have taken away.
+         *
+         * The default is 2048, sized over the 1571 MB peak measured for a
+         * workspace `pnpm typecheck`. Lower it on a machine that runs lighter
+         * work and wants more sessions; raise it on one that runs heavier.
+         */
+        session_memory_min: z.number().int().min(256).max(262144).optional(),
+        /**
+         * A ceiling on the ceiling, in megabytes — the most any single session
+         * may be allowed to grow to, whatever the machine has free.
+         *
+         * For the owner who wants agents to leave room for something the runner
+         * cannot see (a build they run by hand, a database that spikes).
+         */
+        session_memory_max: z.number().int().min(256).max(1048576).optional(),
+        /**
+         * How long a session that has stopped moving is given before its biggest
+         * command is stopped, in seconds. Default 180 (decision D6).
+         */
+        memory_stall_grace_sec: z.number().int().min(30).max(3600).optional(),
+        /**
+         * What happens when that time runs out: `stop-command` (the default) or
+         * `report-only`.
+         *
+         * `report-only` is for the owner who would rather have a session stand
+         * still than have a command stopped under it. It changes nothing else —
+         * the deadline still runs and the strip still shows it, so the person can
+         * act; only DevBridge stops acting on their behalf.
+         */
+        memory_stall_action: z.enum(['stop-command', 'report-only']).optional(),
     })
         .optional(),
     /**

package/dist/daemon-lock.d.ts

@@ -0,0 +1,43 @@
+/**
+ * One daemon per user manager, and the reason is the sweep (#403).
+ *
+ * `cmdDaemon` stops every session scope it does not know about, and at start-up
+ * it knows about none — that is the point: a scope outliving a killed daemon
+ * carries a whole process tree with it. But the same line, run by a SECOND
+ * daemon on a machine where the first one is working, ends every live session
+ * the first one is supervising. `pnpm --filter @bridge4dev/runner dev` beside a
+ * paired runner is enough, and no amount of care inside the test suite touches
+ * that path.
+ *
+ * The lock is in `/run/user/<uid>` and not in the state directory on purpose:
+ * `DEVBRIDGE_RUNNER_HOME` moves the state directory (the test contour uses it),
+ * and two daemons with different state directories still share one systemd user
+ * bus — which is the thing being protected.
+ */
+export interface DaemonLock {
+    /** Where the lock lives, for the message a person reads. */
+    path: string;
+    /** Give it up — on shutdown, or when the daemon is done with it. */
+    release: () => void;
+}
+export interface HeldByAnother {
+    heldBy: number;
+    path: string;
+}
+/** The lock file for this user's manager. */
+export declare function daemonLockPath(): string;
+/**
+ * Take the lock, or say who has it.
+ *
+ * A stale lock — the pid in it is gone — is taken over silently: a daemon that
+ * was killed with `SIGKILL` cannot clean up after itself, and refusing to start
+ * after a crash would be a worse failure than the one being prevented.
+ */
+export declare function acquireDaemonLock(io?: {
+    lockPath?: () => string;
+    isAlive?: (pid: number) => boolean;
+    now?: () => number;
+}): DaemonLock | HeldByAnother;
+/** True when this is a refusal rather than a lock. */
+export declare function isHeldByAnother(result: DaemonLock | HeldByAnother): result is HeldByAnother;
+//# sourceMappingURL=daemon-lock.d.ts.map

package/dist/daemon-lock.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runnerIdentity, systemdUserEnv } from './environment.js';
+import { log } from './log.js';
+import { isPidAlive } from './status-file.js';
+/** The lock file for this user's manager. */
+export function daemonLockPath() {
+    const runtimeDir = systemdUserEnv()['XDG_RUNTIME_DIR'];
+    const uid = runnerIdentity().uid;
+    const dir = runtimeDir ?? path.join('/run/user', String(uid));
+    return path.join(dir, 'devbridge-runner.daemon.lock');
+}
+/**
+ * Take the lock, or say who has it.
+ *
+ * A stale lock — the pid in it is gone — is taken over silently: a daemon that
+ * was killed with `SIGKILL` cannot clean up after itself, and refusing to start
+ * after a crash would be a worse failure than the one being prevented.
+ */
+export function acquireDaemonLock(io = {}) {
+    const file = (io.lockPath ?? daemonLockPath)();
+    const alive = io.isAlive ?? isPidAlive;
+    const write = () => {
+        fs.writeFileSync(file, JSON.stringify({ pid: process.pid, at: (io.now ?? Date.now)() }), {
+            flag: 'w',
+        });
+    };
+    /**
+     * The directory first and on its own, because its `EEXIST` means the opposite
+     * of the one below: «the folder is already there», which is the ordinary
+     * case. Mixed into the same `try`, it was read as «somebody holds the lock».
+     */
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST') {
+            log.warn('daemon: could not take the single-daemon lock, starting without it', {
+                path: file,
+                error: String(error instanceof Error ? error.message : error),
+            });
+            return { path: file, release: () => { } };
+        }
+    }
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            // `wx` fails when the file exists — that is the whole exclusion.
+            fs.writeFileSync(file, JSON.stringify({ pid: process.pid, at: (io.now ?? Date.now)() }), {
+                flag: 'wx',
+            });
+            return { path: file, release: () => releaseLockFile(file) };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                /**
+                 * The runtime directory is not there, or is not writable. Not a reason
+                 * to refuse to start: a machine with no `/run/user/<uid>` has no user
+                 * manager either, so it has no session scopes to protect.
+                 */
+                log.warn('daemon: could not take the single-daemon lock, starting without it', {
+                    path: file,
+                    error: String(error instanceof Error ? error.message : error),
+                });
+                return { path: file, release: () => { } };
+            }
+            const holder = readHolder(file);
+            if (holder !== null && holder !== process.pid && alive(holder)) {
+                return { heldBy: holder, path: file };
+            }
+            // Stale (the holder is gone) or ours from a previous life: take it over.
+            try {
+                fs.rmSync(file, { force: true });
+            }
+            catch {
+                // Somebody else got there first; the next attempt will find out whose.
+            }
+            if (attempt === 1) {
+                write();
+                return { path: file, release: () => releaseLockFile(file) };
+            }
+        }
+    }
+    return { path: file, release: () => releaseLockFile(file) };
+}
+/** True when this is a refusal rather than a lock. */
+export function isHeldByAnother(result) {
+    return 'heldBy' in result;
+}
+function readHolder(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return typeof raw.pid === 'number' && raw.pid > 0 ? raw.pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function releaseLockFile(file) {
+    try {
+        if (readHolder(file) === process.pid)
+            fs.rmSync(file, { force: true });
+    }
+    catch {
+        // Gone already, or never ours. Nothing to undo.
+    }
+}
+//# sourceMappingURL=daemon-lock.js.map

package/dist/host-load.d.ts

@@ -12,6 +12,15 @@
  * both world-readable, neither containing a path, a command line, an
  * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
  *
+ * **One module is allowed past that line, and it is named here so the rule and
+ * the code cannot drift apart:** `session-stall.ts` reads `/proc/<pid>` for the
+ * processes of ONE session's own cgroup, in order to choose which command to
+ * stop when that session has run out of memory (#398 S2). It is not telemetry —
+ * nothing it reads is reported anywhere, and the single thing that leaves the
+ * machine is a command NAME with no arguments, because arguments carry keys and
+ * tokens. Choosing a victim cannot be done from two summary files, and the
+ * alternative was killing the session instead of its command.
+ *
  * Mirror of `packages/shared/src/schemas/host-load.ts` and the `HOST_LOAD_*`
  * block of `packages/shared/src/constants/runner.ts` — the DevBridge side is
  * the source of truth, exactly like `levels.ts` mirrors the level thresholds

package/dist/host-load.js

@@ -15,6 +15,15 @@ import path from 'node:path';
  * both world-readable, neither containing a path, a command line, an
  * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
  *
+ * **One module is allowed past that line, and it is named here so the rule and
+ * the code cannot drift apart:** `session-stall.ts` reads `/proc/<pid>` for the
+ * processes of ONE session's own cgroup, in order to choose which command to
+ * stop when that session has run out of memory (#398 S2). It is not telemetry —
+ * nothing it reads is reported anywhere, and the single thing that leaves the
+ * machine is a command NAME with no arguments, because arguments carry keys and
+ * tokens. Choosing a victim cannot be done from two summary files, and the
+ * alternative was killing the session instead of its command.
+ *
  * Mirror of `packages/shared/src/schemas/host-load.ts` and the `HOST_LOAD_*`
  * block of `packages/shared/src/constants/runner.ts` — the DevBridge side is
  * the source of truth, exactly like `levels.ts` mirrors the level thresholds