@bridge4dev/runner 0.11.0 → 0.22.1

package/dist/commit-message.js

@@ -0,0 +1,224 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { scrubbedEnv } from './adapters/claude.js';
+import { gitBranchDiff } from './gitops.js';
+import { isSecretPath, maskString } from './policy.js';
+/**
+ * «Propose a commit message» — level 1 (session 14).
+ *
+ * A ONE-SHOT run, not a message into the live session. Sending it to the open
+ * session would cost three things at once: the feed fills with a request nobody
+ * made, the session's context window pays for the whole diff, and the call
+ * collides with the worktree lock the agent is already holding mid-turn.
+ *
+ * It always uses the Claude SDK, whichever agent the session runs. The SDK
+ * ships its own CLI, so it is present on every runner — a Codex session gets a
+ * proposal too, instead of the button being greyed out on half the machines.
+ *
+ * The diff is masked and stripped of protected files BEFORE it becomes prompt
+ * text. A model prompt is an outbound channel exactly like the Files panel, and
+ * QA-105 is the reminder that the two have to be held to the same rule.
+ */
+/** How much diff is worth a commit message. Beyond this it is a code review. */
+const DIFF_PROMPT_CAP = 60_000;
+/** The whole answer is one commit message; anything longer is a monologue. */
+const MESSAGE_CAP = 4_000;
+/** A model that has not answered by now is not going to. */
+const PROPOSE_TIMEOUT_MS = 90_000;
+/**
+ * Drop whole file sections that are on the secret denylist.
+ *
+ * `gitDiff` throws in this situation; here that would mean «no proposal at all
+ * because the branch touches `.env.example`». Removing the file and saying so
+ * is both safer (the bytes never leave) and more useful.
+ */
+export function stripProtectedFiles(diff) {
+    const sections = diff.split(/(?=^diff --git )/m);
+    let redacted = 0;
+    const kept = sections.filter((section) => {
+        // The first section of a diff is whatever came before the first header —
+        // usually empty. It carries no file, so there is nothing to protect.
+        if (!/^diff --git /.test(section))
+            return true;
+        const paths = diffHeaderPaths(section);
+        // Fail CLOSED. A header shape we cannot read is a file we cannot check,
+        // and the two outcomes are not comparable: dropping it costs a slightly
+        // less informed commit message, keeping it puts an unexamined file into a
+        // prompt that leaves the machine. Session 15 found this with the shape
+        // that actually occurs — git QUOTES a header whose path contains `"`, a
+        // backslash, a tab or a newline (`diff --git "a/we\"ird/.env" …`), and
+        // `core.quotePath=false` does not turn that off. It only suppresses the
+        // octal escaping of non-ASCII.
+        if (!paths) {
+            redacted += 1;
+            return false;
+        }
+        if (paths.some(isSecretPath)) {
+            redacted += 1;
+            return false;
+        }
+        return true;
+    });
+    return { diff: kept.join(''), redacted };
+}
+/**
+ * The `a/` and `b/` paths out of a `diff --git` header, quoted or not.
+ *
+ * Git writes the quoted form whenever a path contains a character it cannot
+ * put in the line as-is, and escapes it the way C does. Unescaping is enough
+ * here: these strings are only ever compared against the secret-path denylist,
+ * never used to open anything.
+ */
+function diffHeaderPaths(section) {
+    const line = section.split('\n', 1)[0] ?? '';
+    const plain = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+    if (plain)
+        return [plain[1] ?? '', plain[2] ?? ''];
+    const quoted = /^diff --git "a\/((?:[^"\\]|\\.)*)" "b\/((?:[^"\\]|\\.)*)"$/.exec(line);
+    if (quoted)
+        return [unescapeGitPath(quoted[1] ?? ''), unescapeGitPath(quoted[2] ?? '')];
+    // One side quoted and the other not — git does not write that, and a header
+    // we cannot account for is one the caller must treat as unknown.
+    return null;
+}
+function unescapeGitPath(value) {
+    return value.replace(/\\([0-7]{3}|.)/g, (_match, escaped) => {
+        if (/^[0-7]{3}$/.test(escaped))
+            return String.fromCharCode(parseInt(escaped, 8));
+        const simple = { n: '\n', t: '\t', r: '\r', '\\': '\\', '"': '"' };
+        return simple[escaped] ?? escaped;
+    });
+}
+function buildPrompt(input, diff) {
+    const language = input.language?.trim() || 'English';
+    const convention = input.convention?.trim() ||
+        'Conventional Commits: `type(scope): subject`, where type is one of feat/fix/docs/refactor/test/chore/perf/build/ci.';
+    const commits = (input.commitSubjects ?? []).slice(0, 20);
+    return [
+        'Write ONE git commit message for the change below. Output the message and nothing else —',
+        'no preamble, no explanation, no code fences.',
+        '',
+        'Rules:',
+        `- Language: ${language}.`,
+        `- Convention: ${convention}`,
+        '- The subject line is at most 72 characters and does not end with a period.',
+        '- After the subject: a blank line, then 1–3 sentences on what changed and why, then a blank',
+        '  line and up to 5 bullets of the notable points. Skip the bullets if there is nothing to say.',
+        '- Describe what the diff actually does. Do not speculate about intent you cannot see.',
+        '- Do NOT add ticket references, `Co-Authored-By`, `Generated with`, emoji or any trailer —',
+        '  DevBridge appends the trailers itself and strips anything else.',
+        '',
+        `Branch: ${input.branch}${input.baseBranch ? ` (forked from ${input.baseBranch})` : ''}`,
+        ...(commits.length
+            ? ['', 'Commits already on this branch, newest first:', ...commits.map((s) => `- ${s}`)]
+            : []),
+        '',
+        'Diff:',
+        '```diff',
+        diff,
+        '```',
+    ].join('\n');
+}
+/**
+ * The one-shot itself.
+ *
+ * `maxTurns: 1` and every tool refused: this run must read nothing, write
+ * nothing and call nothing. It gets the diff in its prompt and answers with
+ * text. `settingSources: []` for the same reason the session adapter uses it —
+ * a `.claude/settings.json` inside the worktree is a file the agent can write.
+ */
+export async function proposeCommitMessage(input, queryFn = query) {
+    const raw = await gitBranchDiff({
+        worktreePath: input.worktreePath,
+        workspacePath: input.workspacePath,
+        sessionBranch: input.branch,
+        ...(input.baseBranch ? { baseBranch: input.baseBranch } : {}),
+        maxBytes: DIFF_PROMPT_CAP,
+    }).catch(() => null);
+    if (!raw)
+        return { ok: false, error: 'Could not read the diff of this branch' };
+    const { diff, redacted } = stripProtectedFiles(raw.diff);
+    if (!diff.trim()) {
+        return {
+            ok: false,
+            error: redacted > 0
+                ? 'Everything this branch changed is on the protected-paths list — nothing can be described'
+                : 'There is nothing to describe yet — this branch matches its base branch',
+            redactedFiles: redacted,
+        };
+    }
+    let text = '';
+    try {
+        const run = queryFn({
+            prompt: buildPrompt(input, diff),
+            options: {
+                cwd: input.worktreePath,
+                env: scrubbedEnv(),
+                settingSources: [],
+                maxTurns: 1,
+                // Belt and braces: an empty allowlist is a statement of intent, the
+                // callback is the mechanism. Both, because this run has no human
+                // attached to answer a permission prompt.
+                allowedTools: [],
+                canUseTool: () => Promise.resolve({
+                    behavior: 'deny',
+                    message: 'This run only writes a commit message — it may not use tools.',
+                }),
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: 'You are writing a single git commit message for DevBridge. Answer with the message text only.',
+                },
+            },
+        });
+        const deadline = setTimeout(() => void run.interrupt?.().catch(() => undefined), PROPOSE_TIMEOUT_MS);
+        deadline.unref();
+        try {
+            for await (const message of run) {
+                if (message.type !== 'assistant')
+                    continue;
+                for (const block of message.message.content) {
+                    if (block.type === 'text')
+                        text += block.text;
+                }
+            }
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: maskString(String(error instanceof Error ? error.message : error)).slice(0, 300),
+        };
+    }
+    const message = cleanProposal(text);
+    if (!message)
+        return { ok: false, error: 'The agent returned nothing usable' };
+    return {
+        ok: true,
+        message,
+        ...(redacted > 0 ? { redactedFiles: redacted } : {}),
+        ...(raw.truncated ? { diffTruncated: true } : {}),
+    };
+}
+/**
+ * What comes back is text a model wrote, so it is treated as such: fences off,
+ * an opening «Here is the commit message:» off, masked, capped.
+ *
+ * The trailer and signature filtering lives on the API side, where it also
+ * catches what a human pastes into the box — one filter, one place.
+ */
+export function cleanProposal(text) {
+    let value = maskString(text).trim();
+    const fenced = /^```(?:[a-z]*)\n([\s\S]*?)\n?```$/i.exec(value);
+    if (fenced?.[1])
+        value = fenced[1].trim();
+    // `here(?:'s| is)` — with the apostrophe attached, not spaced. «Here's the
+    // commit message:» is the commonest preamble a model writes and the original
+    // `here (?:is|'s)` required a space before it, so that one form survived into
+    // the box (session 15).
+    value = value.replace(/^(?:here(?:'s| is)[^\n:]*:|commit message:)\s*\n+/i, '').trim();
+    return value.slice(0, MESSAGE_CAP);
+}
+//# sourceMappingURL=commit-message.js.map

package/dist/config.d.ts

@@ -47,6 +47,23 @@ declare const ConfigSchema: z.ZodObject<{
     }, {
         max_sessions: number;
     }>>;
+    /**
+     * Session 14: the machine owner's veto over running project recipes.
+     *
+     * Verification executes commands a DevBridge manager approved — a build, a
+     * test run, possibly a deploy. That is a real execution channel on somebody
+     * else's server, and the person who owns the server gets the last word on
+     * whether it exists at all. `enabled = false` here means the capability is
+     * not even announced, so the dashboard never draws the card: a control that
+     * is switched off must not look like a control that is broken.
+     */
+    verify: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+    }, {
+        enabled?: boolean | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     api: {
         url: string;
@@ -57,16 +74,19 @@ declare const ConfigSchema: z.ZodObject<{
         name: string;
         token: string;
     };
-    codex?: {
-        auth: "link" | "own";
-    } | undefined;
     mcp?: {
         url: string;
         token: string;
     } | undefined;
+    codex?: {
+        auth: "link" | "own";
+    } | undefined;
     limits?: {
         max_sessions: number;
     } | undefined;
+    verify?: {
+        enabled: boolean;
+    } | undefined;
 }, {
     api: {
         url: string;
@@ -77,16 +97,19 @@ declare const ConfigSchema: z.ZodObject<{
         name: string;
         token: string;
     };
-    codex?: {
-        auth?: "link" | "own" | undefined;
-    } | undefined;
     mcp?: {
         url: string;
         token: string;
     } | undefined;
+    codex?: {
+        auth?: "link" | "own" | undefined;
+    } | undefined;
     limits?: {
         max_sessions: number;
     } | undefined;
+    verify?: {
+        enabled?: boolean | undefined;
+    } | undefined;
 }>;
 export type RunnerConfig = z.infer<typeof ConfigSchema>;
 export declare function loadConfig(): RunnerConfig | null;

package/dist/config.js

@@ -44,6 +44,21 @@ const ConfigSchema = z.object({
         max_sessions: z.number().int().min(1).max(64),
     })
         .optional(),
+    /**
+     * Session 14: the machine owner's veto over running project recipes.
+     *
+     * Verification executes commands a DevBridge manager approved — a build, a
+     * test run, possibly a deploy. That is a real execution channel on somebody
+     * else's server, and the person who owns the server gets the last word on
+     * whether it exists at all. `enabled = false` here means the capability is
+     * not even announced, so the dashboard never draws the card: a control that
+     * is switched off must not look like a control that is broken.
+     */
+    verify: z
+        .object({
+        enabled: z.boolean().default(true),
+    })
+        .optional(),
 });
 export function loadConfig() {
     const file = configFilePath();

package/dist/crash-note.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Why the previous runner process died — written by the dying process, read once
+ * by its successor, reported in `hello`.
+ *
+ * The 2026-07-30 incident (QA-112) could not be classified after the fact: three
+ * live sessions were parked with «Runner reconnected», and the only evidence the
+ * daemon had even restarted was that its in-memory session map was empty. The
+ * process itself left nothing, and the machine's journal is unreachable from
+ * DevBridge. This file closes that gap for the two causes that matter:
+ *
+ *  - an unhandled error, which the process can describe itself;
+ *  - a kernel OOM kill, which it cannot — the note is absent and the cgroup's
+ *    `memory.events` counter is read instead (`readOomKills`).
+ *
+ * "Absent note + oom_kill went up" is therefore a positive OOM diagnosis rather
+ * than a shrug, which is exactly the distinction the incident needed.
+ */
+export interface CrashNote {
+    kind: string;
+    detail: string;
+    at: string;
+    version: string;
+    activeSessionIds: string[];
+}
+/** What the successor reports upstream. `kind: 'oom'` is inferred, not written. */
+export interface LastExit {
+    kind: string;
+    at?: string;
+    detail?: string;
+    version?: string;
+    /** Sessions the dead process was running — how much the death actually cost. */
+    activeSessionIds?: string[];
+    /** Cumulative `oom_kill` from the service cgroup, when readable. */
+    oomKills?: number;
+}
+export declare function recordCrash(note: CrashNote): void;
+/**
+ * `oom_kill` from the cgroup this process lives in.
+ *
+ * cgroup v2 exposes it in `memory.events` of the service slice. The counter is
+ * cumulative for the cgroup's lifetime, and a systemd restart does NOT reset it
+ * (the cgroup outlives the process), so the interesting quantity is the delta —
+ * hence the small sidecar file.
+ */
+export declare function readOomKills(readFile?: (p: string) => string): number | null;
+/**
+ * Read and CONSUME the note left by the previous process.
+ *
+ * Consuming matters: without it every reconnect for the rest of the daemon's
+ * life would keep reporting a death that happened once, and the dashboard would
+ * show a permanent crash badge on a healthy server.
+ */
+export declare function takeLastExit(readOom?: () => number | null): LastExit | null;
+//# sourceMappingURL=crash-note.d.ts.map

package/dist/crash-note.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { stateDir } from './paths.js';
+function crashNotePath() {
+    return path.join(stateDir(), 'crash.json');
+}
+function oomCounterPath() {
+    return path.join(stateDir(), 'oom-kills');
+}
+export function recordCrash(note) {
+    const dir = stateDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // Written in place, not atomically: a rename needs a second syscall and this
+    // runs on a process that is already failing. A truncated note still carries
+    // its `kind`, and a missing one is handled as "unknown" upstream.
+    fs.writeFileSync(crashNotePath(), JSON.stringify(note), { mode: 0o600 });
+}
+/**
+ * `oom_kill` from the cgroup this process lives in.
+ *
+ * cgroup v2 exposes it in `memory.events` of the service slice. The counter is
+ * cumulative for the cgroup's lifetime, and a systemd restart does NOT reset it
+ * (the cgroup outlives the process), so the interesting quantity is the delta —
+ * hence the small sidecar file.
+ */
+export function readOomKills(readFile = (p) => fs.readFileSync(p, 'utf8')) {
+    try {
+        // `/proc/self/cgroup` on v2 is a single line: `0::/user.slice/.../x.service`
+        const rel = readFile('/proc/self/cgroup')
+            .split('\n')
+            .map((line) => line.split(':'))
+            .find((parts) => parts[0] === '0' && parts[1] === '')?.[2];
+        if (!rel)
+            return null;
+        const events = readFile(path.join('/sys/fs/cgroup', rel, 'memory.events'));
+        const line = events.split('\n').find((l) => l.startsWith('oom_kill '));
+        if (!line)
+            return null;
+        const value = Number.parseInt(line.slice('oom_kill '.length).trim(), 10);
+        return Number.isFinite(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read and CONSUME the note left by the previous process.
+ *
+ * Consuming matters: without it every reconnect for the rest of the daemon's
+ * life would keep reporting a death that happened once, and the dashboard would
+ * show a permanent crash badge on a healthy server.
+ */
+export function takeLastExit(readOom = readOomKills) {
+    let note;
+    try {
+        note = JSON.parse(fs.readFileSync(crashNotePath(), 'utf8'));
+    }
+    catch {
+        note = null;
+    }
+    try {
+        fs.rmSync(crashNotePath(), { force: true });
+    }
+    catch {
+        /* a note we cannot delete is better than refusing to start */
+    }
+    const oomKills = readOom();
+    let previousOomKills;
+    try {
+        previousOomKills = Number.parseInt(fs.readFileSync(oomCounterPath(), 'utf8').trim(), 10);
+        if (!Number.isFinite(previousOomKills))
+            previousOomKills = null;
+    }
+    catch {
+        previousOomKills = null;
+    }
+    if (oomKills !== null) {
+        try {
+            fs.mkdirSync(stateDir(), { recursive: true, mode: 0o700 });
+            fs.writeFileSync(oomCounterPath(), String(oomKills), { mode: 0o600 });
+        }
+        catch {
+            /* the absolute count is still reported below */
+        }
+    }
+    const oomSinceLastStart = oomKills !== null && previousOomKills !== null ? oomKills - previousOomKills : null;
+    if (note) {
+        return {
+            kind: note.kind,
+            at: note.at,
+            detail: note.detail,
+            version: note.version,
+            activeSessionIds: note.activeSessionIds,
+            ...(oomKills === null ? {} : { oomKills }),
+        };
+    }
+    // No note. If the cgroup's OOM counter moved since we last looked, the kernel
+    // killed something in this service — the honest answer the incident lacked.
+    if (oomSinceLastStart !== null && oomSinceLastStart > 0) {
+        return { kind: 'oom', oomKills: oomKills ?? undefined };
+    }
+    // First ever start, a clean stop, or a SIGKILL from outside. Nothing to claim.
+    return null;
+}
+//# sourceMappingURL=crash-note.js.map

package/dist/git.d.ts

@@ -22,6 +22,26 @@ export declare function repoKeyFor(pathInsideRepo: string): Promise<string>;
 export interface SessionWorktree {
     branch: string;
     worktreePath: string;
+    /** The branch this one forked from, when we created it just now. */
+    baseBranch?: string;
+    baseSha?: string;
+}
+/**
+ * What the API decided about this session's branch (session 13).
+ *
+ * Before this, the runner guessed: a branch that already existed was silently
+ * reused — so a second session on the same tickets inherited a stranger's
+ * commits — and a branch that did not was created off whatever the project
+ * folder was on. Both guesses are now errors, because both of them lose work
+ * without saying anything.
+ */
+export interface BranchPlan {
+    branch: string;
+    /** `NEW` — create it, and fail if it is already there. `CONTINUE` — the opposite. */
+    source: 'NEW' | 'CONTINUE';
+    /** Fork point for a NEW branch. `baseSha` wins when both are given. */
+    baseBranch?: string;
+    baseSha?: string;
 }
 /**
  * Accept a branch name from the API only if git would accept it too. The value
@@ -37,7 +57,58 @@ export declare function sanitizeBranch(hint: string | undefined): string | null;
  */
 export declare function ensureSessionWorktree(workspacePath: string, sessionId: string, branchHint?: string, options?: {
     requireExistingBranch?: boolean;
+    plan?: BranchPlan;
 }): Promise<SessionWorktree>;
+/**
+ * DIRECT mode (session 16): the session's workplace IS the project folder.
+ *
+ * Nothing is created and nothing is moved. The folder stays on the branch it is
+ * on, and that branch is the session's branch — which is the whole point: the
+ * work the agent does is already where the person expects to find it, with no
+ * «Apply» step in between and nothing to lose if the session is never applied.
+ *
+ * The two refusals are both about NOT guessing:
+ *
+ *  - not a git work tree — every git surface downstream would fail one call at
+ *    a time instead of once, here, with a sentence that names the folder;
+ *  - a detached HEAD — commits would land on no branch at all and be reachable
+ *    only by sha. A person who checked out a tag to look at something must not
+ *    discover an agent committed onto it.
+ *
+ * The path returned is the repository ROOT, not necessarily the folder that was
+ * configured. Every path in the Source Control panel is repo-root-relative
+ * because that is what `git status` prints, so the root is the only place the
+ * paths and the commands agree — and it is also the confinement root layer 1
+ * hands the agent.
+ */
+export declare function prepareDirectWorkspace(workspacePath: string): Promise<SessionWorktree>;
+/**
+ * One preview checkout per repository, and never the project folder itself.
+ *
+ * The honest constraint behind «show me branch B while branch A is running»:
+ * the docker build context IS the project folder, so a rebuild there replaces
+ * the single running copy. A second worktree is the only way to have both — and
+ * the runner NEVER switches the branch in the project folder, because that
+ * silently moves the base, and the target of «Apply», for every session of the
+ * project at once.
+ *
+ * Checked out DETACHED at a sha rather than on the branch: git refuses to have
+ * one branch checked out twice, and a preview is a snapshot of a commit, not a
+ * place anybody commits.
+ */
+export declare function previewWorktreePath(workspaceKey: string): string;
+export interface PreviewCheckout {
+    worktreePath: string;
+    branch: string;
+    sha: string;
+}
+export declare function ensurePreviewWorktree(input: {
+    workspacePath: string;
+    workspaceKey: string;
+    branch: string;
+}): Promise<PreviewCheckout>;
+/** Give the slot back. The branch is untouched — it was never checked out. */
+export declare function removePreviewWorktree(workspaceKey: string): Promise<boolean>;
 /**
  * Drop a session branch after its worktree is gone. Only ever called when the
  * API confirmed the work was already applied to the base branch — `-D` because