@bridge4dev/runner 0.13.1 → 0.22.1

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -14,8 +15,20 @@ 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, unitExecTarget, unitPath } from './service-unit.js';
+import { buildUnit, cpuQuotaPercent, limitsOverrideIsOutdated, limitsOverridePath, unitExecTarget, unitPath, writeLimitsOverride, LIMITS_VERSION, } from './service-unit.js';
+import { readOomKills, recordCrash, takeLastExit } from './crash-note.js';
+import { mcpConfigDir } from './paths.js';
 const execFileAsync = promisify(execFile);
+/**
+ * Identity of this process, and the note the previous one left.
+ *
+ * Read once at module load, before anything can connect: `takeLastExit()`
+ * CONSUMES the note, so it must happen exactly once per process — reading it
+ * per reconnect would report the same death forever (QA-112).
+ */
+const INSTANCE_ID = crypto.randomUUID();
+const STARTED_AT = new Date().toISOString();
+const LAST_EXIT = takeLastExit();
 function print(line) {
     process.stdout.write(line + '\n');
 }
@@ -49,6 +62,21 @@ function installedAgents() {
 function selfUpdatable() {
     return resolveInstalledPackageDir() !== null && isSupervisedProcess();
 }
+/**
+ * Why this runner cannot replace itself — so the card can SAY it.
+ *
+ * Both halves look identical from the dashboard (no button), and "why does this
+ * machine have a button and that one doesn't" is exactly the question the page
+ * should not leave hanging. Reported as a string rather than inferred, because
+ * only the runner knows how it was started.
+ */
+function selfUpdateBlockedReason() {
+    if (resolveInstalledPackageDir() === null)
+        return 'source-checkout';
+    if (!isSupervisedProcess())
+        return 'unsupervised';
+    return null;
+}
 function hasExecutable(name) {
     const dirs = (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean);
     return dirs.some((dir) => {
@@ -68,7 +96,12 @@ function hasExecutable(name) {
  * command it does not know would just hang until the gateway timeout.
  */
 function runnerCapabilities() {
-    const localLimit = loadConfig()?.limits?.max_sessions;
+    const config = loadConfig();
+    const localLimit = config?.limits?.max_sessions;
+    // Session 14: the machine owner's veto. Default on — the safety of the
+    // feature is that a DevBridge manager approves every command first — but the
+    // person who owns the server gets the last word on whether it exists here.
+    const verifyEnabled = config?.verify?.enabled !== false;
     return {
         agents: installedAgents(),
         git: true,
@@ -83,7 +116,9 @@ function runnerCapabilities() {
          * installed package under a supervisor — a source checkout or a hand-started
          * daemon says so here, so the button never appears where it cannot work.
          */
-        ...(selfUpdatable() ? { selfUpdate: true } : {}),
+        ...(selfUpdatable()
+            ? { selfUpdate: true }
+            : { selfUpdateBlocked: selfUpdateBlockedReason() ?? 'unsupervised' }),
         /**
          * A stricter ceiling set on the machine itself (layer 1). Reported so the
          * dashboard can explain why raising the number there changed nothing.
@@ -99,8 +134,144 @@ function runnerCapabilities() {
          * History tab rather than showing a tab that answers "unknown command".
          */
         gitHistory: true,
+        /**
+         * Session 12: parks `AskUserQuestion` and understands the `question_answer`
+         * frame. The API refuses to accept an answer without it — otherwise the
+         * frame would leave, the socket would report success, and the runner would
+         * drop it: the silent failure this whole session exists to remove.
+         */
+        questionCards: true,
+        /**
+         * Session 13: git is a workplace, not a one-way door.
+         *
+         * Understands `branchPlan` (create vs continue, with a pinned fork point),
+         * answers `git_branches` / `update_from_base` / `git_push`, and reports
+         * ahead/behind/drift in `git_status`. One flag rather than four: they ship
+         * together and the panel needs all of them to say anything true.
+         */
+        gitWorkspace: true,
+        /**
+         * Session 14: the graph became a repository viewer.
+         *
+         * `git_refs`, a `git_log` that takes an explicit ref set, typed
+         * decorations, the committer in both formats, and `workspace_state`. One
+         * flag rather than five: the graph needs all of them at once to draw
+         * anything the previous version could not.
+         */
+        gitRefs: true,
+        /**
+         * Session 14: reads `.devbridge/project.json`. Announced even when
+         * verification is switched off — «this machine will not run recipes» and
+         * «this project has no recipe» are different sentences and the card has to
+         * be able to say both.
+         */
+        projectRecipe: true,
+        /**
+         * Session 14: can execute an APPROVED recipe and report a verdict.
+         *
+         * Withheld when the machine's owner set `[verify] enabled = false`, and
+         * withheld means the dashboard draws no card at all — a control that is
+         * switched off must not look like a control that is broken.
+         */
+        ...(verifyEnabled ? { verifyRuns: true } : { verifyBlocked: 'disabled-by-config' }),
+        /** Session 14: a second, detached worktree driven only by `preview`. */
+        ...(verifyEnabled ? { previewWorktrees: true } : {}),
+        /** Session 14: one-shot agent-written commit messages. */
+        commitMessages: true,
+        /**
+         * Session 15: `git_status` reports whether the PROJECT FOLDER is clean, so
+         * the panel can say what is blocking an Apply instead of offering a button
+         * that the runner will refuse.
+         */
+        workspaceDirtyReporting: true,
+        /**
+         * Session 15: reads `agentAutoCommit` off the workspace and honours it on
+         * every tool call rather than at launch.
+         *
+         * Its own flag now. It used to ride on `workspaceStash`, which was fine
+         * while the two shipped together and wrong the moment one of them was
+         * deleted — the settings card would have started calling every up-to-date
+         * runner incapable of the setting it honours.
+         */
+        agentAutoCommit: true,
+        /**
+         * Session 16: git is git.
+         *
+         * `git_stage` / `git_unstage` / `git_discard` / `git_pull` /
+         * `git_merge_abort`, a `git_status` that reports the working tree the way
+         * `git status` does (both columns, upstream, ahead/behind, merge in
+         * progress), a `git_diff` that can show either side of the index, a
+         * `git_commit` that can commit just what was staged, and `workMode:
+         * DIRECT` — a session that works in the project folder itself.
+         *
+         * One flag for all of it because the Source Control panel needs all of it:
+         * a stage button next to a status that cannot say what is staged would be a
+         * control with nothing to control.
+         */
+        sourceControl: true,
+        /**
+         * Session 17 (#113): `agent_tasks` — the live set of subagents, background
+         * shells and dynamic workflows the agent is running beside the
+         * conversation, published as a level signal with REPLACE semantics.
+         *
+         * Nothing gates on it yet — the tray simply stays empty on a runner that
+         * sends no `agent_tasks`, which is the right behaviour either way. It is
+         * advertised now because a capability has to be on the wire BEFORE anything
+         * can gate on it: the runner ships to machines on its own schedule, and a
+         * flag added at the same time as its first reader is a flag that reads
+         * `false` on every server that has not been updated yet.
+         */
+        agentTasks: true,
+        /**
+         * Session 18 (QA-112): the facts DevBridge needs to stop guessing.
+         *
+         * `maxSessions` was a number out of thin air (default 3) while this machine
+         * silently decided whether three agents fit. Three measured `claude`
+         * processes are ~1.7 GB and one workspace typecheck peaks at 1.5 GB, so on a
+         * small box the answer is no — and the only symptom used to be a dead runner.
+         * Reported so the dashboard can recommend a ceiling and explain a refusal.
+         */
+        machine: {
+            cpuCount: os.cpus().length,
+            memTotalBytes: os.totalmem(),
+            memAvailableBytes: os.freemem(),
+            limitsVersion: LIMITS_VERSION,
+            limitsCurrent: !limitsOverrideIsOutdated(),
+        },
+        /**
+         * Identity of THIS process, so the API can tell a network blink from a
+         * restart. Without it `dev-runner: connected activeSessions: 3` reads the
+         * same either way, which is why the incident's six drops could not be
+         * classified (QA-112 MAJOR-4).
+         */
+        instanceId: INSTANCE_ID,
+        startedAt: STARTED_AT,
+        /**
+         * How the PREVIOUS process died, consumed once. Absent on a clean start.
+         * `kind: 'oom'` is inferred from the cgroup counter — see `crash-note.ts`.
+         */
+        ...(LAST_EXIT ? { lastExit: LAST_EXIT } : {}),
         /** Commands beyond the stage-A/B set. */
-        commands: ['purge_session', 'git_log', 'git_show'],
+        commands: [
+            'purge_session',
+            'git_log',
+            'git_show',
+            'git_branches',
+            'update_from_base',
+            'git_push',
+            'git_refs',
+            'workspace_state',
+            'git_stage',
+            'git_unstage',
+            'git_discard',
+            'git_pull',
+            'git_merge_abort',
+            'recipe_state',
+            'propose_commit_message',
+            ...(verifyEnabled
+                ? ['verify_start', 'verify_status', 'verify_cancel', 'preview_checkout', 'preview_stop']
+                : []),
+        ],
     };
 }
 // ─── pair ────────────────────────────────────────────────────────────
@@ -165,9 +336,80 @@ function bootstrapCodex(config) {
 }
 /** Long enough for the `command_result` frame to leave the socket. */
 const RESTART_DELAY_MS = 1_500;
+/**
+ * Bring this machine's resource policy up to date, on every daemon start.
+ *
+ * `self-update` also does this, and that is NOT enough: the update is executed by
+ * the process being replaced, so the code that writes the drop-in only exists in
+ * the build being INSTALLED. Updating 0.20.1 → 0.21.0 therefore left the bad
+ * `MemoryMax=2G` in place and the runner reported `limitsCurrent: false` on its
+ * first hello — caught live on vmi3328440, 2026-07-30 03:35 UTC.
+ *
+ * A migration that only runs during an update can never fix the version that
+ * introduces it. Startup is the place that always belongs to the new build.
+ *
+ * Idempotent by version marker, so a normal restart writes nothing. Never fatal:
+ * 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() {
+    try {
+        if (!writeLimitsOverride())
+            return;
+        log.warn('daemon: resource limits drop-in written — reloading systemd', {
+            path: limitsOverridePath(),
+            version: LIMITS_VERSION,
+        });
+        await execFileAsync('systemctl', ['--user', 'daemon-reload'], { timeout: 15_000 });
+        // Deliberately no restart: `daemon-reload` alone is enough for these
+        // directives (verified live — OOMPolicy went stop→continue and MemoryMax
+        // 2G→infinity with the PID unchanged), and restarting here would park every
+        // live session to apply a setting that is already in force.
+        log.info('daemon: resource limits applied without a restart');
+    }
+    catch (error) {
+        log.error('daemon: could not apply the resource limits drop-in', {
+            error: String(error instanceof Error ? error.message : error),
+            hint: 'run `devbridge-runner doctor --fix`',
+        });
+    }
+}
+/**
+ * Ticket #119. `ClaudeAdapter.stop()` removes each session's MCP config file,
+ * but a kill -9, an OOM or a machine reboot leaves it behind — a live project
+ * key sitting on disk with nothing left that will ever clean it up. Nothing is
+ * running yet at this point in the boot, so every file here is by definition an
+ * orphan of a previous process.
+ */
+function sweepOrphanedMcpConfigs() {
+    const dir = mcpConfigDir();
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return; // never created — the normal case on a fresh install
+    }
+    let removed = 0;
+    for (const name of entries) {
+        if (!name.startsWith('devbridge-mcp.') || !name.endsWith('.json'))
+            continue;
+        try {
+            fs.unlinkSync(path.join(dir, name));
+            removed += 1;
+        }
+        catch {
+            // Leave it; a warning per file would be noise.
+        }
+    }
+    if (removed > 0)
+        log.warn('daemon: removed orphaned MCP config files', { count: removed });
+}
 async function cmdDaemon() {
     const config = requireConfig();
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
+    sweepOrphanedMcpConfigs();
+    await repairResourceLimits();
     const agents = installedAgents();
     const ws = new RunnerWsClient(config.api.ws_url, config.server.token, runnerCapabilities());
     const codex = agents.includes('codex') ? bootstrapCodex(config) : null;
@@ -178,6 +420,9 @@ async function cmdDaemon() {
         },
         ...(config.mcp ? { mcp: { url: config.mcp.url, token: config.mcp.token } } : {}),
         ...(config.limits?.max_sessions ? { maxSessionsLimit: config.limits.max_sessions } : {}),
+        // 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,
         apiUrl: config.api.url,
         // Used to fetch the files a user attaches to a message (session 10) — the
         // same token the WS connection authenticates with, never passed onwards.
@@ -231,6 +476,37 @@ async function cmdDaemon() {
     };
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGTERM', () => shutdown('SIGTERM'));
+    /**
+     * A death must leave a note. Until 0.21.0 the only handlers here were the two
+     * signals above, so an unhandled error exited the process silently and the
+     * only trace anywhere was systemd's `Scheduled restart job` — which is why the
+     * 2026-07-30 incident could not be classified as OOM-vs-crash after the fact
+     * (QA-112 MAJOR-4).
+     *
+     * `crashFile` is read by the next process and reported in `hello`, so the
+     * cause survives the restart and reaches the dashboard.
+     */
+    const noteFatal = (kind, error) => {
+        const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+        log.error(`daemon: ${kind} — exiting for a restart`, { detail: detail.slice(0, 2000) });
+        try {
+            recordCrash({
+                kind,
+                detail: detail.slice(0, 2000),
+                at: new Date().toISOString(),
+                version: RUNNER_VERSION,
+                activeSessionIds: supervisor.activeSessionIds,
+            });
+        }
+        catch {
+            /* the log line above is already on disk via journald */
+        }
+        // Not a graceful supervisor.shutdown(): the process state is by definition
+        // untrustworthy here, and systemd `Restart=always` is the recovery path.
+        process.exit(1);
+    };
+    process.on('uncaughtException', (error) => noteFatal('uncaughtException', error));
+    process.on('unhandledRejection', (reason) => noteFatal('unhandledRejection', reason));
     ws.start();
     updateStatus();
     // Keep the process alive forever; ws timers drive everything.
@@ -289,6 +565,11 @@ async function cmdInstallService() {
     const exec = unitExecTarget();
     fs.writeFileSync(target, buildUnit(exec.execStart));
     print(`Wrote ${target}`);
+    // Resource policy is a versioned drop-in, not part of the unit — see
+    // `buildLimitsOverride`. Forced here: a fresh install must have it even if a
+    // file from an older runner is already sitting there.
+    writeLimitsOverride(true);
+    print(`Wrote ${limitsOverridePath()}`);
     if (!exec.viaCommand) {
         // Worth saying out loud: a unit pinned to a file inside the package directory
         // breaks if that directory ever moves (which a package rename does).
@@ -312,6 +593,120 @@ async function cmdInstallService() {
     }
     print('Verify with: devbridge-runner status');
 }
+// ─── doctor ──────────────────────────────────────────────────────────
+/**
+ * The one command that answers «is this machine set up to run the sessions it
+ * says it can run».
+ *
+ * It exists because of what the 2026-07-30 incident cost to diagnose: the
+ * runner's own systemd limits were the cause, they were invisible from
+ * DevBridge, and the machine could not be reached. Everything printed here was
+ * needed to reach that answer and none of it was available in one place.
+ */
+async function cmdDoctor(args) {
+    const fix = args.includes('--fix');
+    const config = loadConfig();
+    print(`devbridge-runner ${RUNNER_VERSION}`);
+    print(config ? `Paired with: ${config.server.name} (${config.api.url})` : 'Not paired');
+    const cpuCount = os.cpus().length;
+    const quota = cpuQuotaPercent(cpuCount);
+    print('');
+    print('Machine');
+    print(`  cpus            ${cpuCount}`);
+    print(`  memory total    ${Math.round(os.totalmem() / 1024 / 1024)} MB`);
+    print(`  memory free     ${Math.round(os.freemem() / 1024 / 1024)} MB`);
+    // The number that matters: sessions cost ~1.5 GB each once an agent starts a
+    // 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)`);
+    print('');
+    print('Service limits');
+    const outdated = limitsOverrideIsOutdated();
+    print(`  drop-in         ${limitsOverridePath()}`);
+    print(`  version         ${outdated ? `MISSING or OLD (want ${LIMITS_VERSION})` : LIMITS_VERSION}`);
+    print(`  cpu quota       ${quota === null ? 'none (fewer than 4 cpus)' : `${quota}%`}`);
+    let effective;
+    try {
+        const { stdout } = await execFileAsync('systemctl', [
+            '--user',
+            'show',
+            'devbridge-runner',
+            '-p',
+            'CPUQuotaPerSecUSec',
+            '-p',
+            'MemoryMax',
+            '-p',
+            'MemoryHigh',
+            '-p',
+            'OOMPolicy',
+            '-p',
+            'NRestarts',
+        ]);
+        effective = stdout.trim().split('\n').filter(Boolean);
+    }
+    catch {
+        effective = ['(systemctl --user unavailable — is this a source checkout?)'];
+    }
+    print('');
+    print('Effective (systemd)');
+    for (const line of effective)
+        print(`  ${line}`);
+    // The two settings that turned one agent's OOM into a dead server.
+    const bad = effective.filter((l) => (l.startsWith('OOMPolicy=') && !l.endsWith('=continue')) ||
+        (l.startsWith('MemoryMax=') && !l.endsWith('=infinity')) ||
+        (l.startsWith('CPUQuotaPerSecUSec=') && l.endsWith('=800ms')));
+    if (bad.length > 0) {
+        print('');
+        print('PROBLEM — these limits kill every session on this machine when one agent runs out of memory:');
+        for (const line of bad)
+            print(`  ${line}`);
+    }
+    // `systemctl set-property` (the zero-downtime emergency fix) persists into
+    // `~/.config/systemd/user.control/`, which OUTRANKS the drop-in we ship. Left
+    // in place it silently pins the numbers from whatever the emergency was, on a
+    // machine whose core count may since have changed — so say so.
+    const controlDir = path.join(os.homedir(), '.config', 'systemd', 'user.control', 'devbridge-runner.service.d');
+    try {
+        const files = fs.readdirSync(controlDir).filter((f) => f.endsWith('.conf'));
+        if (files.length > 0) {
+            print('');
+            print(`Emergency overrides present (these WIN over the shipped policy): ${controlDir}`);
+            for (const file of files)
+                print(`  ${file}`);
+            print('  Remove with: systemctl --user revert devbridge-runner');
+        }
+    }
+    catch {
+        /* no emergency overrides — the normal case */
+    }
+    const oomKills = readOomKills();
+    if (oomKills !== null) {
+        print('');
+        print(`OOM kills in this service's cgroup (cumulative): ${oomKills}`);
+    }
+    if (LAST_EXIT) {
+        print(`Previous process exit: ${LAST_EXIT.kind}${LAST_EXIT.at ? ` at ${LAST_EXIT.at}` : ''}`);
+    }
+    if (!fix) {
+        if (outdated || bad.length > 0) {
+            print('');
+            print('Run `devbridge-runner doctor --fix` to write the drop-in, then restart the service.');
+            process.exit(1);
+        }
+        return;
+    }
+    writeLimitsOverride(true);
+    print('');
+    print(`Wrote ${limitsOverridePath()}`);
+    try {
+        await execFileAsync('systemctl', ['--user', 'daemon-reload']);
+        print('systemctl --user daemon-reload — done.');
+        print('Restart when sessions are idle: systemctl --user restart devbridge-runner');
+    }
+    catch (error) {
+        fail(`daemon-reload failed: ${String(error instanceof Error ? error.message : error)}`);
+    }
+}
 // ─── set-token ───────────────────────────────────────────────────────
 function cmdSetToken(args) {
     const token = args[0];
@@ -330,6 +725,7 @@ Usage:
   devbridge-runner install-service                                 install + start systemd user service
   devbridge-runner status                                          connection status (exit 0 = connected)
   devbridge-runner set-token <dbr_token>                           store a rotated runner token
+  devbridge-runner doctor [--fix]                                  report (and repair) resource limits
 `;
 async function main() {
     const [command, ...args] = process.argv.slice(2);
@@ -344,6 +740,8 @@ async function main() {
             return cmdInstallService();
         case 'set-token':
             return cmdSetToken(args);
+        case 'doctor':
+            return cmdDoctor(args);
         case '--version':
         case 'version':
             print(RUNNER_VERSION);

package/dist/paths.d.ts

@@ -1,7 +1,33 @@
 export declare function configDir(): string;
 export declare function stateDir(): string;
+/**
+ * Home for systemd USER units. Honours `DEVBRIDGE_RUNNER_HOME` like everything
+ * else here: `service-unit.ts` used to reach for `os.homedir()` directly, and the
+ * moment it started WRITING (the 0.21.0 limits drop-in) a test run began
+ * reconfiguring the developer's own service.
+ */
+export declare function systemdUserHome(): string;
 export declare function configFilePath(): string;
 export declare function statusFilePath(): string;
 export declare function journalDir(): string;
 export declare function worktreesDir(): string;
+/** Session 14: the single preview checkout per repository. */
+export declare function previewsDir(): string;
+/**
+ * Per-session MCP config files (ticket #119).
+ *
+ * The Agent SDK serialises its `mcpServers` option straight into the CLI's
+ * argv (`sdk.mjs`: `H.push("--mcp-config", Re({mcpServers:ke}))`), which put the
+ * project's `dbk_…` key in `/proc/<pid>/cmdline` — world-readable, and how the
+ * key was found in the first place. The CLI also accepts a PATH there
+ * (`--mcp-config <configs...>`: "Load MCP servers from JSON files or strings"),
+ * so we write the same JSON to a 0600 file and pass the path instead.
+ *
+ * The basename is deliberately distinctive rather than just `<sessionId>.json`:
+ * `policy.ts` matches it by name in BOTH secret lists, so the guard holds
+ * wherever the file ends up — including under a `DEVBRIDGE_RUNNER_HOME`
+ * override, where the path carries no `devbridge-runner` segment.
+ */
+export declare function mcpConfigDir(): string;
+export declare function mcpConfigPath(sessionId: string): string;
 //# sourceMappingURL=paths.d.ts.map

package/dist/paths.js

@@ -18,6 +18,15 @@ export function stateDir() {
     const xdg = process.env['XDG_STATE_HOME'] ?? path.join(os.homedir(), '.local', 'state');
     return path.join(xdg, 'devbridge-runner');
 }
+/**
+ * Home for systemd USER units. Honours `DEVBRIDGE_RUNNER_HOME` like everything
+ * else here: `service-unit.ts` used to reach for `os.homedir()` directly, and the
+ * moment it started WRITING (the 0.21.0 limits drop-in) a test run began
+ * reconfiguring the developer's own service.
+ */
+export function systemdUserHome() {
+    return baseDir() ?? os.homedir();
+}
 export function configFilePath() {
     return path.join(configDir(), 'config.toml');
 }
@@ -30,4 +39,29 @@ export function journalDir() {
 export function worktreesDir() {
     return path.join(stateDir(), 'worktrees');
 }
+/** Session 14: the single preview checkout per repository. */
+export function previewsDir() {
+    return path.join(stateDir(), 'previews');
+}
+/**
+ * Per-session MCP config files (ticket #119).
+ *
+ * The Agent SDK serialises its `mcpServers` option straight into the CLI's
+ * argv (`sdk.mjs`: `H.push("--mcp-config", Re({mcpServers:ke}))`), which put the
+ * project's `dbk_…` key in `/proc/<pid>/cmdline` — world-readable, and how the
+ * key was found in the first place. The CLI also accepts a PATH there
+ * (`--mcp-config <configs...>`: "Load MCP servers from JSON files or strings"),
+ * so we write the same JSON to a 0600 file and pass the path instead.
+ *
+ * The basename is deliberately distinctive rather than just `<sessionId>.json`:
+ * `policy.ts` matches it by name in BOTH secret lists, so the guard holds
+ * wherever the file ends up — including under a `DEVBRIDGE_RUNNER_HOME`
+ * override, where the path carries no `devbridge-runner` segment.
+ */
+export function mcpConfigDir() {
+    return path.join(stateDir(), 'mcp');
+}
+export function mcpConfigPath(sessionId) {
+    return path.join(mcpConfigDir(), `devbridge-mcp.${sessionId}.json`);
+}
 //# sourceMappingURL=paths.js.map

package/dist/policy.d.ts

@@ -3,6 +3,19 @@ export interface PolicyContext {
     trustMode: TrustMode;
     /** The session worktree — the only place the agent may write. */
     worktreePath: string;
+    /**
+     * May the agent commit on its own? (session 15)
+     *
+     * `false` is the project setting «I review and commit myself». It was a
+     * column, an API field and a switch in the workspace form since session 14 —
+     * and nothing ever sent it anywhere, so the switch moved a value that no code
+     * read. A control that does nothing is worse than a missing one: somebody
+     * turns it off and believes the agent stopped committing.
+     *
+     * `undefined` means the API did not say, which is every runner-API pair older
+     * than this release — and there the answer stays what it has always been.
+     */
+    agentAutoCommit?: boolean;
 }
 export interface PolicyDecision {
     decision: 'allow' | 'deny' | 'ask';
@@ -13,5 +26,55 @@ export declare function maskString(value: string): string;
 export declare function maskSecrets<T>(value: T): T;
 export declare function isSecretPath(p: string): boolean;
 export declare function isInsideWorktree(p: string, worktreePath: string): boolean;
+/**
+ * Anything inside a `.git` directory (session 16, QA-110 B2).
+ *
+ * This became load-bearing the day DIRECT mode made the repository ROOT the
+ * agent's confinement. In a linked worktree the real `.git` lives elsewhere, so
+ * «outside the worktree» happened to cover it; in the project folder it sits
+ * right there, one level down, and «inside the worktree» happened to allow it.
+ *
+ * A file in `.git/hooks/` is not data — it is code git runs on the next commit,
+ * outside every rule on the Bash denylist, including the `git clean` and
+ * `git reset --hard` this same session added to it. `.git/config` is worse: it
+ * can set `core.fsmonitor` or a credential helper and run a command on the very
+ * next git invocation. Neither is ever ordinary agent work.
+ */
+export declare function isGitInternalPath(p: string): boolean;
+export interface RecipeCommandContext {
+    /**
+     * The docker compose project this preview owns, from `preview.project` in the
+     * recipe. Present only for the preview `stop` command.
+     */
+    dockerProject?: string;
+    /** True only for the recipe's own `preview.stop` command. */
+    isPreviewStop?: boolean;
+}
+export interface RecipeCommandDecision {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Layer 1 for a command that came out of an APPROVED project recipe.
+ *
+ * The semantics, fixed here rather than left to be discovered: **an approved
+ * recipe does not ask, but it cannot get past the denylist.** Both halves
+ * matter and neither is what `evaluateToolUse` would do on its own.
+ *
+ *  - It does not ask, because there is nobody to ask: a build runs for minutes
+ *    with no agent turn around it, and the human already read every command on
+ *    the approval screen. Running it through the strict-mode branch would turn
+ *    `docker compose up --build` — which is not on any safe list — into a
+ *    permission card nobody can answer.
+ *  - It cannot get past the denylist, because approval is a statement about a
+ *    build, not a grant of `sudo`, of the firewall, or of the machine's power
+ *    switch.
+ *
+ * One denial is liftable, and only one: `docker … down`. A preview that cannot
+ * tear its own stack down leaks containers forever, so a recipe that NAMES its
+ * compose project may run `down` on that project in its `stop` command — and
+ * nowhere else. Without the name, the refusal stands and says why.
+ */
+export declare function evaluateRecipeCommand(command: string, ctx?: RecipeCommandContext): RecipeCommandDecision;
 export declare function evaluateToolUse(toolName: string, input: Record<string, unknown>, ctx: PolicyContext): PolicyDecision;
 //# sourceMappingURL=policy.d.ts.map