@bridge4dev/runner 0.11.0 → 0.22.1

package/dist/service-unit.js

@@ -0,0 +1,211 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { systemdUserHome } from './paths.js';
+/**
+ * The systemd user unit, and the one decision inside it that matters: what to
+ * exec.
+ *
+ * The first version baked `realpathSync(process.argv[1])` — the resolved file
+ * inside the installed package directory. That pins the service to a directory
+ * that a package RENAME deletes: `@devbridge/runner` → `@bridge4dev/runner` moved
+ * the file, the unit kept pointing at the old path, and `systemctl restart`
+ * failed with ENOENT. The runner simply never came back and the server went
+ * offline until someone logged in — the one outcome an update must never produce.
+ *
+ * So the unit execs the COMMAND (`<prefix>/bin/devbridge-runner`), which npm
+ * re-creates on every install whatever the package is called. A source checkout
+ * has no such symlink, and there the resolved script is the honest answer.
+ */
+export const SERVICE_NAME = 'devbridge-runner';
+const COMMAND_NAME = 'devbridge-runner';
+/** `<prefix>/bin/devbridge-runner` for an installed package, else the script. */
+export function unitExecTarget(argv1 = process.argv[1] ?? '') {
+    // Invoked through the command itself: that is already the stable path.
+    try {
+        if (fs.lstatSync(argv1).isSymbolicLink()) {
+            return { execStart: path.resolve(argv1), viaCommand: true };
+        }
+    }
+    catch {
+        /* fall through to the resolved script */
+    }
+    let script;
+    try {
+        script = fs.realpathSync(argv1);
+    }
+    catch {
+        return { execStart: argv1, viaCommand: false };
+    }
+    // Invoked as the script inside a global install: find the prefix that owns the
+    // command. `<prefix>/lib/node_modules/@scope/runner/dist/index.js` → `<prefix>`.
+    if (script.split(path.sep).includes('node_modules')) {
+        let dir = path.dirname(script);
+        for (let i = 0; i < 6; i++) {
+            const candidate = path.join(dir, 'bin', COMMAND_NAME);
+            if (fs.existsSync(candidate))
+                return { execStart: candidate, viaCommand: true };
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return { execStart: script, viaCommand: false };
+}
+export function unitPath(home = systemdUserHome()) {
+    return path.join(home, '.config', 'systemd', 'user', `${SERVICE_NAME}.service`);
+}
+export function buildUnit(execStart) {
+    const target = execStart ?? unitExecTarget().execStart;
+    // The command carries a `#!/usr/bin/env node` shebang, so it is exec'd directly;
+    // a bare script path needs the interpreter spelled out.
+    const command = target.endsWith('.js')
+        ? `${process.execPath} ${target} daemon`
+        : `${target} daemon`;
+    return ([
+        '[Unit]',
+        'Description=DevBridge Dev Runner',
+        'After=network-online.target',
+        '',
+        '[Service]',
+        `ExecStart=${command}`,
+        'Restart=always',
+        'RestartSec=5',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+    ].join('\n') + '\n');
+}
+/**
+ * Resource policy for the service, and why it does not live in the unit above.
+ *
+ * The unit is written ONCE, at install time. Until 0.21.0 it carried
+ * `CPUQuota=80%` and `MemoryMax=2G` — and those two lines cost a production
+ * server every session it was running (QA-112 BLOCKER-1, 2026-07-30):
+ *
+ *  - every agent the runner starts, and every `pnpm build`/`tsc`/`vitest` that
+ *    agent runs, is a CHILD of this service and therefore inside this cgroup.
+ *    Three measured `claude` processes are 512/577/646 MB and one workspace
+ *    `pnpm -r typecheck` peaks at 1571 MB, against a ceiling of 2048 MB;
+ *  - `OOMPolicy` defaults to `stop`, so the kernel killing ONE of those children
+ *    tore down the whole service — and with it every other session on the
+ *    machine. `Restart=always` then brought the daemon back with an empty
+ *    session map, which is what the user sees as
+ *    «Runner reconnected. The session was resumed»;
+ *  - `CPUQuota=80%` is 0.8 of ONE core for all of the above, which is separately
+ *    what starves the event loop until the gateway's heartbeat gives up on it.
+ *
+ * So the policy is versioned and shipped as a drop-in instead. A drop-in can
+ * RESET a directive the main unit set (`MemoryMax=` with no value clears it),
+ * which is the only way to fix the servers that already have the bad numbers
+ * baked in — and it never overwrites a unit the operator edited by hand.
+ */
+export const LIMITS_VERSION = 2;
+const LIMITS_MARKER = '# devbridge-limits-version:';
+/** `zz-` so it sorts last: an operator's own drop-in should still win. */
+const LIMITS_FILE = 'zz-devbridge-limits.conf';
+export function limitsOverridePath(home = systemdUserHome()) {
+    return path.join(home, '.config', 'systemd', 'user', `${SERVICE_NAME}.service.d`, LIMITS_FILE);
+}
+/**
+ * `CPUQuota` worth keeping: enough headroom that a runaway build cannot make the
+ * box unreachable, but never so little that ordinary work is throttled.
+ *
+ * One core is reserved for the system (sshd, journald, the runner's own event
+ * loop). Below four cores there is nothing to reserve without crippling the
+ * agents, so no quota is set at all — an unusable dev server is a worse failure
+ * than a busy one.
+ */
+export function cpuQuotaPercent(cpuCount = os.cpus().length) {
+    return cpuCount >= 4 ? (cpuCount - 1) * 100 : null;
+}
+export function buildLimitsOverride(cpuCount = os.cpus().length) {
+    const quota = cpuQuotaPercent(cpuCount);
+    return ([
+        `${LIMITS_MARKER} ${LIMITS_VERSION}`,
+        '# Managed by devbridge-runner. Put your own overrides in a file that sorts',
+        '# after this one, or edit the unit itself — neither is touched by updates.',
+        '',
+        '[Unit]',
+        // Five fast failures used to leave the service in `failed` and the server
+        // offline until someone logged in. A dev runner must always come back;
+        // crash loops are surfaced through `lastExit` in hello, not by giving up.
+        'StartLimitIntervalSec=0',
+        'StartLimitBurst=0',
+        '',
+        '[Service]',
+        // The whole point of the change: one child's OOM must not take the fleet.
+        'OOMPolicy=continue',
+        // Clears `MemoryMax=2G` from units written before 0.21.0.
+        'MemoryMax=',
+        // Soft pressure instead of a hard ceiling: the kernel reclaims and
+        // throttles rather than killing, and the machine keeps a fifth of its
+        // memory for everything that is not this service.
+        'MemoryHigh=80%',
+        // Either a computed quota, or an explicit reset — both of which clear the
+        // `CPUQuota=80%` baked into units written before 0.21.0.
+        quota === null ? 'CPUQuota=' : `CPUQuota=${quota}%`,
+        // Needed for `doctor` and for the memory/CPU figures the runner reports.
+        'MemoryAccounting=yes',
+        'CPUAccounting=yes',
+        // An agent running a monorepo build forks a lot; the default is per-user.
+        'TasksMax=8192',
+    ].join('\n') + '\n');
+}
+/**
+ * Is the shipped resource policy missing or from an older runner?
+ *
+ * Deliberately version-based rather than content-based: an operator may add
+ * their own directives to our file, and re-writing on every start would fight
+ * them. Only the version number decides.
+ */
+export function limitsOverrideIsOutdated(readFile = (p) => fs.readFileSync(p, 'utf8'), home = systemdUserHome()) {
+    let contents;
+    try {
+        contents = readFile(limitsOverridePath(home));
+    }
+    catch {
+        return true; // never written — every server that predates 0.21.0
+    }
+    const line = contents.split('\n').find((l) => l.startsWith(LIMITS_MARKER));
+    if (!line)
+        return true;
+    const version = Number.parseInt(line.slice(LIMITS_MARKER.length).trim(), 10);
+    return !Number.isFinite(version) || version < LIMITS_VERSION;
+}
+/** Write the drop-in. Returns false when nothing needed doing. */
+export function writeLimitsOverride(force = false, home = systemdUserHome()) {
+    if (!force && !limitsOverrideIsOutdated(undefined, home))
+        return false;
+    const target = limitsOverridePath(home);
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(target, buildLimitsOverride(), { mode: 0o644 });
+    return true;
+}
+/**
+ * Does the installed unit point at something that no longer exists?
+ *
+ * Used after an update: if the package moved (a rename), a unit pinned to the old
+ * directory would kill the runner on the very restart the update asks for. Only a
+ * missing target counts — a unit the user edited on purpose is left alone.
+ */
+export function unitIsBroken(readFile = (p) => fs.readFileSync(p, 'utf8')) {
+    let contents;
+    try {
+        contents = readFile(unitPath());
+    }
+    catch {
+        return false; // no unit of ours — nothing to repair
+    }
+    const line = contents.split('\n').find((l) => l.startsWith('ExecStart='));
+    if (!line)
+        return false;
+    const parts = line.slice('ExecStart='.length).trim().split(/\s+/);
+    // `ExecStart=/usr/bin/node /path/index.js daemon` or `ExecStart=/path/cmd daemon`
+    const target = parts[0]?.endsWith('node') ? parts[1] : parts[0];
+    if (!target)
+        return false;
+    return !fs.existsSync(target);
+}
+//# sourceMappingURL=service-unit.js.map

package/dist/supervisor.d.ts

@@ -1,4 +1,5 @@
 import { JournalStore } from './journal.js';
+import { proposeCommitMessage } from './commit-message.js';
 import { selfUpdate, type SelfUpdateOutcome } from './self-update.js';
 import type { RunnerWsClient } from './ws-client.js';
 import type { SessionDescriptor } from './protocol.js';
@@ -30,6 +31,14 @@ export interface SupervisorOptions {
      * machine's owner decides how much of their machine an agent fleet may take.
      */
     maxSessionsLimit?: number;
+    /**
+     * `[verify] enabled` from the runner's own config (session 14). The machine's
+     * owner has the last word on whether project recipes run here at all;
+     * `false` means the capability is not announced and no run can be started.
+     */
+    verifyEnabled?: boolean;
+    /** Test seam for the one-shot commit-message run. */
+    proposeCommitMessage?: typeof proposeCommitMessage;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -54,10 +63,32 @@ export declare class Supervisor {
     private readonly repoLocks;
     /** An update is installing right now — a second one would fight it. */
     private selfUpdateInFlight;
+    /** Session 14: one project-recipe run per machine, and its verdict queue. */
+    private readonly verify;
+    private readonly verifyReports;
     constructor(ws: RunnerWsClient, opts: SupervisorOptions);
+    /**
+     * Push every unacked verdict at the API.
+     *
+     * Called on each reconnect and whenever a run finishes. Sending a report the
+     * API already has is harmless — it is keyed by `runId` and stored idempotently
+     * — while not sending one is a verdict that never existed.
+     */
+    private flushVerifyReports;
     get activeSessionIds(): string[];
     private onFrame;
     private startSession;
+    /**
+     * Where this session is going to work — a worktree of its own, or the project
+     * folder itself (session 16).
+     *
+     * The BRANCH path takes the repo lock because `worktree add` writes into the
+     * shared `.git` (registration + prune), exactly like commit/apply/revert. The
+     * DIRECT path takes none: it only READS which branch a folder is on, and
+     * queueing every session start behind whatever merge happens to be running
+     * would be a lock bought for nothing.
+     */
+    private prepareWorkspace;
     /**
      * Spin the adapter up — for a fresh session, a resume-on-next-message, or a
      * free CHAT session with no prompt at all (the agent boots, reports its
@@ -100,6 +131,23 @@ export declare class Supervisor {
      */
     private pauseForBudget;
     private pumpEvents;
+    /**
+     * "…and N of them are waiting for an answer from you."
+     *
+     * An open question pins its slot deliberately (`isParkable`), so a message
+     * that blames a running turn sends the user to wait for something that will
+     * never happen. Empty when nothing is waiting.
+     */
+    private waitingForAnswerSuffix;
+    /**
+     * Close out every ask this session still has open, with a stated cause.
+     *
+     * Idempotent: the adapter reports its own `question_resolved` when it can, and
+     * `forwardEvent` clears the id — so by the time this runs the set is usually
+     * already empty. What it catches is the path where the adapter never got the
+     * chance, and the alternative there is a card that stays clickable forever.
+     */
+    private withdrawOpenQuestions;
     /**
      * Deliver messages that were held because every slot was taken.
      *
@@ -140,10 +188,27 @@ export declare class Supervisor {
      * returns false and the caller tells the user rather than thrashing.
      */
     private ensureCapacity;
-    /** Idle after a finished turn — safe to kill the process and resume later. */
+    /**
+     * Idle after a finished turn — safe to kill the process and resume later.
+     *
+     * An open question is the exception (session 12): WAITING_INPUT there does
+     * NOT mean "the turn is over", it means the agent's tool call is parked on a
+     * human. Parking such a session killed a live turn — and, worse, killed the
+     * card the user was about to answer — the moment another session wanted a
+     * slot.
+     */
     private isParkable;
     private park;
     private forwardEvent;
+    /**
+     * The dashboard's answer to a parked question (session 12).
+     *
+     * A miss is reported in the feed rather than swallowed: the three cases that
+     * get here — a card from a previous life of the session, a second click, an
+     * ask the runner already withdrew — all look identical to the user unless
+     * somebody says so.
+     */
+    private onQuestionAnswer;
     private onUserMessage;
     /**
      * Run delivery work for one session, strictly after whatever is already
@@ -212,5 +277,47 @@ export declare class Supervisor {
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
     shutdown(): void;
 }
+/**
+ * The first message the agent gets.
+ *
+ * Two shapes, and the difference is whether tickets were handed over
+ * (session 16, owner's decision):
+ *
+ *  - **No tickets** — exactly what the human typed, and an empty prompt stays
+ *    empty. That is how you get a session that boots and waits for you to talk
+ *    first; it is a feature, not an oversight.
+ *  - **Tickets handed to a TICKET session** — the assignment is always sent and
+ *    cannot be removed: «Implement ticket #28.» Handing a ticket over IS the
+ *    instruction, so making the human retype it was ceremony. Anything they
+ *    typed follows underneath.
+ *
+ * What is NOT here any more: eight lines about which MCP tools to call and
+ * which statuses to move through. That is a standing convention of the project,
+ * true on the twentieth turn as much as the first, so it moved to the system
+ * prompt beside `CLAUDE.md` — which is read last and therefore overrides ours.
+ */
 export declare function composeInitialPrompt(descriptor: SessionDescriptor): string;
+/**
+ * Extra system-prompt material: where this session is in git, and how tickets
+ * are meant to move (session 13).
+ *
+ * Facts about THIS SESSION, and nothing else. They exist in no file on disk —
+ * which branch the agent is on, that it must not push, where a plan belongs,
+ * what to do with the tickets it was given — so somebody has to say them, and
+ * that somebody is us.
+ *
+ * The project's own documentation is deliberately NOT here. Both agents read
+ * their own file natively, verified live: Claude picks up `CLAUDE.md` through
+ * its memory mechanism (since `settingSources` includes `'project'`), and Codex
+ * picks up `AGENTS.md` even under the runner's isolated `CODEX_HOME`. Pasting a
+ * copy on top of that was work we were doing for no one — and when it was
+ * switched off for Claude alone it briefly left repositories that carry only
+ * `AGENTS.md` with nothing at all, which is precisely the kind of hole a
+ * half-measure digs.
+ *
+ * A repository that wants both agents equipped ships both files, or symlinks
+ * one to the other. That is a repository convention and not something a runner
+ * should paper over.
+ */
+export declare function composeWorkspaceContext(descriptor: SessionDescriptor): string;
 //# sourceMappingURL=supervisor.d.ts.map