@bridge4dev/runner 0.30.0 → 0.33.0

package/dist/protocol.js

@@ -52,9 +52,52 @@ export const SessionDescriptorSchema = z.object({
          * every project the moment a runner updated ahead of its API.
          */
         agentAutoCommit: z.boolean().optional(),
+        /**
+         * The project's own prompt file, relative to `path` — its contents reach
+         * the agent as SYSTEM-prompt text (see `agent-prompt.ts` for why the level
+         * matters).
+         *
+         * `.catch(undefined)` for the same reason as `branchHint` and `branchPlan`:
+         * this field travels inside `hello_ack`, which carries EVERY session of the
+         * server, so a malformed value must cost its own session's prompt at most —
+         * never the frame (QA-100 MAJOR-1). The runner re-validates the path from
+         * scratch anyway; the bounds here only keep nonsense off the wire.
+         */
+        agentPromptPath: z.string().max(300).nullable().optional().catch(undefined),
+        /**
+         * Session 18: the project's git policy for agents.
+         *
+         * `.optional().catch(undefined)` for the QA-100 MAJOR-1 reason above — this
+         * rides inside `hello_ack` with every session on the server, so a malformed
+         * value must cost its own session's policy at most, never the frame.
+         *
+         * «Costs its own session's policy» is safe here BECAUSE of the polarity in
+         * `policy.ts`: `agentPushBan` resolves `undefined` to «refuse», so a value
+         * this schema drops leaves the session strictly more restricted, never less.
+         * That property is the whole reason `.catch(undefined)` is acceptable on a
+         * security field, and it is why the resolution lives in exactly one
+         * function rather than at each point of use.
+         */
+        agentPushBan: z.boolean().optional().catch(undefined),
+        agentProtectedBranches: z
+            .array(z
+            .string()
+            .max(200)
+            .regex(/^[A-Za-z0-9][A-Za-z0-9._\-/]*$/))
+            .max(20)
+            .optional()
+            .catch(undefined),
+        agentAllowForcePush: z.boolean().optional().catch(undefined),
+        agentAllowDestructiveGit: z.boolean().optional().catch(undefined),
         budgetUsd: z.number().nullable(),
         budgetMinutes: z.number().nullable(),
     }),
+    /**
+     * «Run this one without the project's agent prompt.» Absent means no — both
+     * because an older API never sends it and because that is the default a human
+     * gets when they do not touch the checkbox.
+     */
+    skipAgentPrompt: z.boolean().optional().catch(undefined),
     tickets: z.array(z.object({ id: z.string().uuid(), number: z.number(), title: z.string() })),
     // Branch the API would like this session to use (derived from its ticket
     // group). Optional: an older API omits it and the runner keeps its
@@ -212,6 +255,19 @@ export const GatewayFrameSchema = z.discriminatedUnion('type', [
         workspaceId: z.string().min(1).max(64),
         trustMode: z.enum(['STRICT', 'NORMAL', 'AUTO']).optional(),
         agentAutoCommit: z.boolean().optional(),
+        // Session 18 — the git policy, for the same reason: read on every tool
+        // call, so switching «Принудительно запретить push» back on must not
+        // require stopping the agent first.
+        agentPushBan: z.boolean().optional(),
+        agentProtectedBranches: z
+            .array(z
+            .string()
+            .max(200)
+            .regex(/^[A-Za-z0-9][A-Za-z0-9._\-/]*$/))
+            .max(20)
+            .optional(),
+        agentAllowForcePush: z.boolean().optional(),
+        agentAllowDestructiveGit: z.boolean().optional(),
     }),
     z.object({
         type: z.literal('session_settings'),

package/dist/supervisor.d.ts

@@ -118,6 +118,26 @@ export declare class Supervisor {
      * stay queued rather than be marked delivered (session 9).
      */
     private launchAgent;
+    /**
+     * The project's own prompt file, read fresh for THIS agent process.
+     *
+     * Read per launch rather than per session on purpose: a system prompt only
+     * ever changes when the process restarts, so «edit the file, then press
+     * Continue» is the honest contract, and re-reading is what makes it true.
+     *
+     * Every outcome is said out loud. The whole point of moving the project's
+     * rules into the system prompt is that they can no longer be quietly
+     * outranked — so «the prompt did not load» must never be indistinguishable
+     * from «the prompt loaded». Supervisor notices repeat on every launch (only
+     * ADAPTER notices are de-duplicated — gotcha #148), which is exactly what is
+     * wanted here: each agent process either has the prompt or does not.
+     *
+     * Returns the text AND the absolute file, because layer 1 needs the second to
+     * refuse writes to it: in `workMode: DIRECT` the project folder is the
+     * agent's own working directory, so without that rule a session could rewrite
+     * the prompt it will itself be started with next time (QA-130 MAJOR-3).
+     */
+    private resolveAgentPrompt;
     /** Warn the user when this share of the budget is gone. */
     private static readonly BUDGET_WARN_RATIO;
     /** Is the agent actually working right now (i.e. should the clock run)? */
@@ -408,6 +428,14 @@ export declare function composeInitialPrompt(descriptor: SessionDescriptor): str
  * 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.
+ *
+ * `agentPrompt` is the one exception, and it is an exception for a reason this
+ * function cannot do anything about: `CLAUDE.md` and `AGENTS.md` arrive at the
+ * USER level, and a project's standing process rules have to sit at the system
+ * level to survive both a compaction and a rule the CLI states about itself
+ * (`agent-prompt.ts`). It arrives here already read and already checked — this
+ * function still opens no files — and it goes LAST, so a project overrides us
+ * exactly the way `CLAUDE.md` does by being read last.
  */
-export declare function composeWorkspaceContext(descriptor: SessionDescriptor): string;
+export declare function composeWorkspaceContext(descriptor: SessionDescriptor, agentPrompt?: string): string;
 //# sourceMappingURL=supervisor.d.ts.map

package/dist/supervisor.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { log } from './log.js';
 import { claimAutoResume, clearAutoResume, pruneAutoResume } from './auto-resume.js';
 import { evaluateRecipeCommand, maskSecrets, maskString } from './policy.js';
+import { agentPromptSizeLabel, quotePath, readAgentPrompt } from './agent-prompt.js';
 import { JournalStore } from './journal.js';
 import { deleteSessionBranch, ensurePreviewWorktree, ensureSessionWorktree, prepareDirectWorkspace, previewWorktreePath, removePreviewWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, } from './git.js';
 import { readRecipeProposal } from './recipe.js';
@@ -21,6 +22,28 @@ import { availableModes, MODE_REFUSED_TEXT } from './adapters/types.js';
 /** Refusals shared by every checkpoint command (ticket #126). */
 const CHECKPOINTS_OFF = 'Restore points are switched off on this server ([checkpoints] enabled = false)';
 const AGENT_BUSY = 'The agent is still working — stop the turn first';
+/**
+ * The project's git policy, lifted out of a session descriptor (session 18).
+ *
+ * One function so that «which descriptor fields are the git policy» is answered
+ * once. Absent fields are passed through as absent — `resolveGitPolicy` in
+ * `policy.ts` is the single place that decides what absent MEANS, and inventing
+ * a default here would put a second such place in the codebase, facing the
+ * other way.
+ */
+function gitPolicyOf(descriptor) {
+    const w = descriptor.workspace;
+    return {
+        ...(w.agentPushBan !== undefined ? { agentPushBan: w.agentPushBan } : {}),
+        ...(w.agentProtectedBranches !== undefined
+            ? { agentProtectedBranches: w.agentProtectedBranches }
+            : {}),
+        ...(w.agentAllowForcePush !== undefined ? { agentAllowForcePush: w.agentAllowForcePush } : {}),
+        ...(w.agentAllowDestructiveGit !== undefined
+            ? { agentAllowDestructiveGit: w.agentAllowDestructiveGit }
+            : {}),
+    };
+}
 export class Supervisor {
     ws;
     opts;
@@ -130,11 +153,43 @@ export class Supervisor {
                     if (frame.agentAutoCommit !== undefined) {
                         running.descriptor.workspace.agentAutoCommit = frame.agentAutoCommit;
                     }
+                    /**
+                     * Session 18: the git policy, applied live for the same reason as the
+                     * two above — it is read on every tool call, so «switch push back
+                     * off» must not mean «stop the agent first».
+                     *
+                     * The four fields move together, and the API sends all four in every
+                     * frame that touches any of them, so a partial update cannot leave
+                     * the runner with «push is allowed now» beside a protected list from
+                     * before the change. `!== undefined` on the FRAME is what tells a
+                     * policy change apart from a trust-only frame; inside the object,
+                     * `undefined` keeps its restrictive meaning as everywhere else.
+                     */
+                    const policyChanged = frame.agentPushBan !== undefined ||
+                        frame.agentProtectedBranches !== undefined ||
+                        frame.agentAllowForcePush !== undefined ||
+                        frame.agentAllowDestructiveGit !== undefined;
+                    if (policyChanged) {
+                        const next = {
+                            ...(frame.agentPushBan !== undefined ? { agentPushBan: frame.agentPushBan } : {}),
+                            ...(frame.agentProtectedBranches !== undefined
+                                ? { agentProtectedBranches: frame.agentProtectedBranches }
+                                : {}),
+                            ...(frame.agentAllowForcePush !== undefined
+                                ? { agentAllowForcePush: frame.agentAllowForcePush }
+                                : {}),
+                            ...(frame.agentAllowDestructiveGit !== undefined
+                                ? { agentAllowDestructiveGit: frame.agentAllowDestructiveGit }
+                                : {}),
+                        };
+                        Object.assign(running.descriptor.workspace, next);
+                    }
                     running.session?.setWorkspacePolicy({
                         ...(frame.trustMode !== undefined ? { trustMode: frame.trustMode } : {}),
                         ...(frame.agentAutoCommit !== undefined
                             ? { agentAutoCommit: frame.agentAutoCommit }
                             : {}),
+                        ...(policyChanged ? { gitPolicy: gitPolicyOf(running.descriptor) } : {}),
                     });
                 }
                 break;
@@ -380,9 +435,11 @@ export class Supervisor {
             return false;
         }
         running.lastPrompt = prompt;
-        // Facts about this session only. The project's own documentation is read by
-        // each agent itself — see `composeWorkspaceContext`.
-        const workspaceContext = composeWorkspaceContext(descriptor);
+        // Facts about this session only, plus the one file the project named. The
+        // rest of the project's documentation is read by each agent itself — see
+        // `composeWorkspaceContext`.
+        const agentPrompt = this.resolveAgentPrompt(running);
+        const workspaceContext = composeWorkspaceContext(descriptor, agentPrompt?.text);
         const rewind = running.rewindAnchor;
         delete running.rewindAnchor;
         // A rewind resumes the conversation the POINT names, which is not always
@@ -396,10 +453,18 @@ export class Supervisor {
             cwd: running.worktreePath,
             ...(prompt ? { prompt } : {}),
             ...(workspaceContext ? { workspaceContext } : {}),
+            // Only when it was actually read: layer 1 must refuse writes to the file
+            // this process was given, not to a path it was merely told about.
+            ...(agentPrompt ? { agentPromptFile: agentPrompt.absPath } : {}),
             trustMode: descriptor.workspace.trustMode,
             ...(descriptor.workspace.agentAutoCommit === undefined
                 ? {}
                 : { agentAutoCommit: descriptor.workspace.agentAutoCommit }),
+            // Session 18. Always present, even when every field inside it is absent:
+            // an absent OBJECT and an object of absent fields resolve identically
+            // (`resolveGitPolicy` gives both the restrictive reading), and passing it
+            // unconditionally keeps one code path instead of two.
+            gitPolicy: gitPolicyOf(descriptor),
             mode: running.mode,
             ...(running.model ? { model: running.model } : {}),
             ...(running.effort ? { effort: running.effort } : {}),
@@ -426,6 +491,70 @@ export class Supervisor {
         void this.pumpEvents(running);
         return true;
     }
+    /**
+     * The project's own prompt file, read fresh for THIS agent process.
+     *
+     * Read per launch rather than per session on purpose: a system prompt only
+     * ever changes when the process restarts, so «edit the file, then press
+     * Continue» is the honest contract, and re-reading is what makes it true.
+     *
+     * Every outcome is said out loud. The whole point of moving the project's
+     * rules into the system prompt is that they can no longer be quietly
+     * outranked — so «the prompt did not load» must never be indistinguishable
+     * from «the prompt loaded». Supervisor notices repeat on every launch (only
+     * ADAPTER notices are de-duplicated — gotcha #148), which is exactly what is
+     * wanted here: each agent process either has the prompt or does not.
+     *
+     * Returns the text AND the absolute file, because layer 1 needs the second to
+     * refuse writes to it: in `workMode: DIRECT` the project folder is the
+     * agent's own working directory, so without that rule a session could rewrite
+     * the prompt it will itself be started with next time (QA-130 MAJOR-3).
+     */
+    resolveAgentPrompt(running) {
+        const { descriptor } = running;
+        const configured = descriptor.workspace.agentPromptPath?.trim();
+        if (!configured)
+            return undefined;
+        // The session was started with «without the project's agent prompt». Said
+        // out loud too: a session behaving unlike every other session on the
+        // project should carry the reason in its own feed.
+        if (descriptor.skipAgentPrompt) {
+            this.sendEvent(running, 'notice', {
+                level: 'info',
+                text: 'Project prompt is switched off for this session. DevBridge rules still apply.',
+            });
+            return undefined;
+        }
+        const result = readAgentPrompt(descriptor.workspace.path, configured);
+        if (!result.ok) {
+            log.warn('agent prompt not loaded', {
+                sessionId: descriptor.id,
+                path: configured,
+                reason: result.reason,
+            });
+            this.sendEvent(running, 'notice', {
+                level: 'warn',
+                text: `Project prompt ${quotePath(configured)} was NOT loaded: ${result.reason}. The agent is running without it.`,
+            });
+            return undefined;
+        }
+        log.info('agent prompt loaded', {
+            sessionId: descriptor.id,
+            path: result.relPath,
+            bytes: result.bytes,
+            sha: result.sha,
+        });
+        // The `sha` is in the line a person reads, not only in journald. It is the
+        // one signal that the file behind an unchanged path has changed — which is
+        // exactly what an agent editing its own rules in DIRECT mode looks like
+        // (QA-130 MAJOR-3), and layer 1 cannot promise to prevent that in every
+        // mode.
+        this.sendEvent(running, 'notice', {
+            level: 'info',
+            text: `Project prompt loaded from ${quotePath(result.relPath)} — ${agentPromptSizeLabel(result.bytes)}, sha ${result.sha}.`,
+        });
+        return { text: result.text, absPath: result.absPath };
+    }
     // ─── Time budget (session 7) ───────────────────────────────────────
     //
     // The budget measures the AGENT's working time, not the calendar. Everything
@@ -3276,20 +3405,70 @@ export function composeInitialPrompt(descriptor) {
  * 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.
+ *
+ * `agentPrompt` is the one exception, and it is an exception for a reason this
+ * function cannot do anything about: `CLAUDE.md` and `AGENTS.md` arrive at the
+ * USER level, and a project's standing process rules have to sit at the system
+ * level to survive both a compaction and a rule the CLI states about itself
+ * (`agent-prompt.ts`). It arrives here already read and already checked — this
+ * function still opens no files — and it goes LAST, so a project overrides us
+ * exactly the way `CLAUDE.md` does by being read last.
  */
-export function composeWorkspaceContext(descriptor) {
+export function composeWorkspaceContext(descriptor, agentPrompt) {
     const sections = [];
     const plan = descriptor.branchPlan;
+    /**
+     * What this session may do about push, in one sentence (session 18).
+     *
+     * `!== false` — silence refuses, exactly as `resolveGitPolicy` reads it. This
+     * text and the rule in `policy.ts` have to agree; an agent told it may push
+     * and then refused has been lied to, and an agent told it may not while the
+     * project allows it wastes the freedom the owner paid for.
+     */
+    const pushLine = (() => {
+        // `?.` and not `.`: this function is exported and called with descriptors
+        // assembled by hand in tests and by older code paths. A missing `workspace`
+        // must land on the refusing branch like every other unknown here, not throw
+        // and take the whole session start with it.
+        if (descriptor.workspace?.agentPushBan !== false) {
+            return '- You cannot push: `git push` is refused for this project. A human presses «Push» in DevBridge when they want the branch on the remote.';
+        }
+        const guarded = descriptor.workspace?.agentProtectedBranches ?? ['main', 'master'];
+        return guarded.length > 0
+            ? `- You may push, except to these protected branches: ${guarded.join(', ')}. Name the branch explicitly — \`git push <remote> <branch>\`.`
+            : '- You may push.';
+    })();
     if (plan) {
         const forked = plan.baseBranch ? ` It was branched from \`${plan.baseBranch}\`.` : '';
         sections.push([
             'Git in this session:',
             `- You are in a dedicated worktree on branch \`${plan.branch}\`.${forked}`,
             '- Commit to this branch. Do not switch branches and do not merge into the base branch yourself — a human presses «Apply» in DevBridge, which squash-merges your branch for them.',
-            '- You cannot push: `git push` is refused. A human presses «Push» when they want the branch on the remote.',
+            pushLine,
             `- Put a plan or working notes in \`docs/devbridge/${plan.branch.replace(/\//g, '-')}.md\`, unless this repository already has its own convention for where such documents live — if it does, follow that.`,
         ].join('\n'));
     }
+    else {
+        /**
+         * A DIRECT session got NO «Git in this session» block at all, and that is
+         * the older half of this bug (session 16 shipped DIRECT as the default;
+         * this block stayed gated on `branchPlan`, which only a BRANCH session
+         * has). So the arrangement that writes into the person's OWN project
+         * folder was the one told nothing about where it was — while the adapter's
+         * static line went on claiming «a dedicated git worktree on a session
+         * branch», which in DIRECT is simply false.
+         *
+         * Being in somebody's working copy is the case that needs saying MORE, not
+         * less: there is no «Apply» to undo it, and uncommitted changes in that
+         * folder may not be the agent's.
+         */
+        sections.push([
+            'Git in this session:',
+            '- You are working in the PROJECT FOLDER ITSELF, on the branch it is already checked out on — not in a worktree of your own. There is no session branch and nothing to «apply» afterwards: your commits are immediately on the branch the person works on.',
+            '- Uncommitted changes you find here may be a human’s, or another session’s. Never discard or reset what you did not write.',
+            pushLine,
+        ].join('\n'));
+    }
     // The ticket convention lives HERE, not in the first chat message (session
     // 16). It is a standing rule of the project — true on the twentieth turn as
     // much as the first — and putting it in the visible prompt only trained the
@@ -3305,6 +3484,8 @@ export function composeWorkspaceContext(descriptor) {
     else if (descriptor.tickets.length > 0) {
         sections.push('DevBridge tickets are attached to this chat for CONTEXT only. Read them with the DevBridge MCP tools; do not change their status — this session is not assigned to them.');
     }
+    if (agentPrompt)
+        sections.push(agentPrompt);
     return sections.join('\n\n');
 }
 //# sourceMappingURL=supervisor.js.map

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.30.0";
+export declare const RUNNER_VERSION = "0.33.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.30.0';
+export const RUNNER_VERSION = '0.33.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.30.0",
+  "version": "0.33.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",