@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/policy.js

@@ -517,6 +517,189 @@ function parsePush(segment) {
         remoteExec,
     };
 }
+const GIT_CHECKOUT = String.raw `\bgit\s+${FLAGS}(?:checkout|switch)\b`;
+/** A word whose meaning only the shell knows — `$BRANCH`, `` `cat .b` ``, `\x`. */
+const SHELL_UNRESOLVED = /[$`\\]/;
+/**
+ * A REVISION expression — `main~1`, `v2^`, `abc123^{commit}`.
+ *
+ * Not a branch name (git's own ref grammar forbids `~` and `^` in one) and
+ * emphatically not a pathspec: checking one out leaves the folder on no branch
+ * at all. Grouping it with the pathspecs below, on the grounds that it «cannot
+ * be a branch», was exactly backwards — `git checkout main~1` detaches the
+ * shared folder for everybody in it, silently.
+ */
+const REVISION_EXPRESSION = /[~^]/;
+/**
+ * An operand git could never read as a branch name — because it is a PATH.
+ *
+ * Not a guess about intent, a fact about the ref grammar: `*`, `?`, `[` and
+ * spaces are forbidden in a branch name, a leading `:` is git's own magic
+ * pathspec prefix, and `.`, `./x`, `../x`, `/x`, `x/` are paths by shape.
+ * A closing `]` is deliberately NOT here: `git check-ref-format --branch 'wip]1'`
+ * accepts it, so calling it impossible-in-a-branch would have waved through a
+ * real branch switch (QA #255).
+ * Everything else stays ambiguous, and git resolves ambiguity in favour of the
+ * BRANCH — which is why an ambiguous word asks rather than being waved through.
+ *
+ * Characters that are merely UNUSUAL in a branch name (a backslash, a control
+ * character, `@{`) are deliberately absent: they end up in the ambiguous pile,
+ * which asks. Every gap here has to fall on that side.
+ */
+function cannotBeBranch(operand) {
+    if (operand === '.' || operand === '..')
+        return true;
+    if (/^\.{1,2}\//.test(operand) || operand.startsWith('/'))
+        return true;
+    if (operand.startsWith(':'))
+        return true;
+    if (operand.endsWith('/'))
+        return true;
+    return /[*?[ ]/.test(operand);
+}
+/**
+ * The agent chose this word, so it is quoted back at a length WE choose.
+ *
+ * This string becomes the description of a permission card and travels in an
+ * event payload the gateway caps; a single implausibly long operand should cost
+ * a few characters of the sentence, never the card.
+ */
+function shortOperand(operand) {
+    return operand.length > 60 ? `${operand.slice(0, 60)}…` : operand;
+}
+const RESTORE_A_FILE = 'To put a file back use `git checkout -- <path>` or `git restore <path>`: those touch files only.';
+const MOVES_THE_FOLDER = 'this session works in the project folder itself, so switching branches there changes the files under every other session and person working in it';
+/**
+ * Does this segment move the shared folder onto another branch? (#361 п. 5)
+ *
+ * Parsed rather than pattern matched, for the same reason as `parsePush`: the
+ * difference between «restore this file» and «move everybody to another
+ * branch» is one `--` in the middle of the arguments, and no regex answers
+ * that. Synchronous and free of child processes — gotcha 196: this runs on
+ * every Bash call of every session on the machine.
+ *
+ * Returns null when the segment is not a checkout at all, or is one of the
+ * forms that provably only touches files.
+ */
+function parseCheckout(segment) {
+    if (!new RegExp(GIT_CHECKOUT).test(segment))
+        return null;
+    const tokens = words(segment);
+    const at = tokens.findIndex((token) => token === 'checkout' || token === 'switch');
+    if (at === -1) {
+        // The regex matched but the verb is hidden by a form this tokenizer does
+        // not model. Report the moving reading — «I could not parse it» must never
+        // become «go ahead».
+        return {
+            reason: `This git command could not be read well enough to tell whether it moves the folder onto another branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    if (tokens[at] === 'switch') {
+        // `git switch` has no file form at all — it exists to move a branch.
+        return {
+            reason: `\`git switch\` moves the folder onto another branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    const rest = tokens.slice(at + 1);
+    /**
+     * `--` names paths only when there ARE paths after it.
+     *
+     * The obvious reading — «a `--` anywhere means this is a file command» — is
+     * wrong, and wrong in the direction that matters. Verified on git 2.43:
+     * `git checkout feature --` prints «Switched to branch 'feature'», and
+     * `git checkout -b tmp --` creates the branch and moves onto it. Git's own
+     * parser treats a trailing `--` as «the word before me is definitely a ref»,
+     * which is the opposite of what it looks like. So the separator is only a
+     * separator when it separates something.
+     */
+    const dashDash = rest.indexOf('--');
+    if (dashDash !== -1 && dashDash < rest.length - 1)
+        return null;
+    const head = dashDash === -1 ? rest : rest.slice(0, dashDash);
+    let fileOnly = false;
+    let movingFlag = null;
+    const operands = [];
+    for (const token of head) {
+        if (token.startsWith('--')) {
+            const name = token.split('=')[0] ?? token;
+            if (name === '--ours' ||
+                name === '--theirs' ||
+                name === '--patch' ||
+                name === '--pathspec-from-file' ||
+                name === '--pathspec-file-nul') {
+                fileOnly = true;
+            }
+            else if (name === '--orphan' ||
+                name === '--detach' ||
+                name === '--track' ||
+                name === '--merge' ||
+                name === '--force') {
+                movingFlag ??= name;
+            }
+            continue;
+        }
+        // A lone `-` is an operand: «the branch I was on before».
+        if (token.startsWith('-') && token.length > 1) {
+            for (const letter of token.slice(1)) {
+                if (letter === 'p')
+                    fileOnly = true;
+                else if ('bBtmf'.includes(letter))
+                    movingFlag ??= `-${letter}`;
+            }
+            continue;
+        }
+        operands.push(token);
+    }
+    if (fileOnly)
+        return null;
+    if (movingFlag) {
+        return {
+            reason: `\`git checkout ${shortOperand(movingFlag)}\` moves the folder onto another branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    // `git checkout` on its own restores nothing and moves nothing — but only
+    // when the arguments really are all of them. `echo feature | xargs git
+    // checkout` is a checkout whose operand is handed to it by the program in
+    // front of it, and this parser cannot see it: the segment ends with a bare
+    // `git checkout` and looks harmless. So «no operands» is only an answer when
+    // git is the thing being run, not an argument to something else.
+    if (operands.length === 0) {
+        const first = tokens.find((token) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(token));
+        if (first === 'git')
+            return null;
+        return {
+            reason: `This \`git checkout\` gets its arguments from another program, so the runner cannot tell whether it moves the folder onto another branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    for (const operand of operands) {
+        if (SHELL_UNRESOLVED.test(operand)) {
+            return {
+                reason: `This \`git checkout\` names its target through the shell, so the runner cannot tell whether it is a file or a branch — and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+            };
+        }
+        if (operand === '-') {
+            return {
+                reason: `\`git checkout -\` moves the folder back onto the previous branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+            };
+        }
+        if (/^(HEAD|@)([~^].*)?$/.test(operand) ||
+            /^[0-9a-f]{7,40}$/i.test(operand) ||
+            REVISION_EXPRESSION.test(operand)) {
+            return {
+                reason: `\`git checkout ${shortOperand(operand)}\` leaves the folder on no branch at all (detached HEAD), and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+            };
+        }
+        if (cannotBeBranch(operand))
+            continue;
+        // A bare word. Git reads it as a BRANCH first and only falls back to a
+        // path, so «I meant the file» is not something this can assume — and the
+        // unambiguous spelling costs the agent three characters.
+        return {
+            reason: `\`git checkout ${shortOperand(operand)}\` is read by git as a branch first, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    return null;
+}
 /**
  * The project's git rules, applied to one Bash command.
  *
@@ -525,9 +708,18 @@ function parsePush(segment) {
  * DELIBERATELY switched something on — with the shipped defaults the first
  * check refuses every push and the rest never run, which is byte for byte the
  * behaviour of the four regexes it replaces.
+ *
+ * **A `deny` anywhere beats an `ask` anywhere.** Until #361 every decision here
+ * was a refusal, so returning the first one found in the first segment was the
+ * same thing as returning the worst one. With an `ask` in the set that stopped
+ * being true: `git checkout main && git push origin main` would have shown a
+ * card about the checkout, and confirming it would have run the push this
+ * function exists to refuse. So `deny` returns at once, `ask` is remembered,
+ * and the loop reads to the end.
  */
 export function evaluateGitPolicy(command, ctx) {
     const policy = resolveGitPolicy(ctx);
+    let asked = null;
     for (const segment of commandSegments(command)) {
         if (!policy.allowDestructiveGit) {
             /**
@@ -539,10 +731,14 @@ export function evaluateGitPolicy(command, ctx) {
              * that went that way on 2026-07-28 existed nowhere else — and
              * `git reset --hard` throws away every uncommitted edit in the tree.
              *
-             * Denied rather than turned into a permission card, because under AUTO
-             * trust there is no card: Bash is allowed before the safe list is
-             * consulted. An agent that needs to remove build output can name the
-             * paths; one that wants to undo its own work has `git checkout -- <file>`.
+             * Denied rather than turned into a permission card because there is no
+             * safe version of them, not because a card was impossible: this whole
+             * function runs BEFORE the trust branches, so an `ask` returned from here
+             * does reach the person even under AUTO (that is how #361 п. 5 works two
+             * rules below). What is true is that the safe LIST never sees them — Bash
+             * is allowed before it is consulted. An agent that needs to remove build
+             * output can name the paths; one that wants to undo its own work has
+             * `git checkout -- <file>`.
              */
             if (new RegExp(String.raw `\bgit\s+${FLAGS}clean\b`).test(segment)) {
                 return {
@@ -557,6 +753,16 @@ export function evaluateGitPolicy(command, ctx) {
                 };
             }
         }
+        // #361 п. 5 — only where the folder is shared. In a BRANCH session the
+        // worktree belongs to this session alone and moving it costs nobody
+        // anything. See `PolicyContext.workMode` for why silence means «ask».
+        if (ctx.workMode !== 'BRANCH') {
+            const move = parseCheckout(segment);
+            // `reason` stays a LABEL — it goes to logs and, on a denial, to the feed.
+            // The sentence a person reads on the card travels in `explain`.
+            if (move)
+                asked ??= { decision: 'ask', reason: 'moves the shared folder', explain: move.reason };
+        }
         const push = parsePush(segment);
         if (!push)
             continue;
@@ -648,7 +854,7 @@ export function evaluateGitPolicy(command, ctx) {
             }
         }
     }
-    return null;
+    return asked;
 }
 // Commands considered safe enough to run without asking under NORMAL trust.
 // Interpreters (node/python/…) and find (-exec) are NOT here: they execute
@@ -829,7 +1035,14 @@ export function evaluateRecipeCommand(command, ctx = {}) {
          * approval screen, not a side effect of this one.
          */
         const git = evaluateGitPolicy(variant, { trustMode: 'STRICT', worktreePath: '' });
-        if (git) {
+        // Only a REFUSAL stops a recipe. Since #361 this function can also return
+        // «ask», and the first line of this doc comment is the answer to it: an
+        // approved recipe does not ask, because a human already read this exact
+        // command on the approval screen. Turning that ask into `{allowed: false}`
+        // would hard-refuse every build script that starts with `git checkout main`
+        // — a refusal invented by a rule about AGENTS, applied to a text a person
+        // wrote and approved.
+        if (git?.decision === 'deny') {
             // The sentence is rewritten, not passed through (QA-134 MINOR-2). The
             // generic one says «this project has «Принудительно запретить push»
             // switched on» — and a project that switched it OFF would be sent to look
@@ -1001,11 +1214,19 @@ export function evaluateToolUse(toolName, input, ctx) {
         // and nothing after this line is consulted. That is exactly how «agents
         // never push» quietly failed for a whole release (session 13), and it is
         // the reason these rules did not simply move onto the safe list.
+        // Both spellings are read to the end before anything is returned: a `deny`
+        // in the dequoted form must beat an `ask` in the raw one, for the same
+        // reason a later segment beats an earlier one (see `evaluateGitPolicy`).
+        let gitAsk = null;
         for (const variant of [command, dequote(command)]) {
             const git = evaluateGitPolicy(variant, ctx);
-            if (git)
+            if (git?.decision === 'deny')
                 return git;
+            if (git)
+                gitAsk ??= git;
         }
+        if (gitAsk)
+            return gitAsk;
         if (trust === 'STRICT')
             return { decision: 'ask', reason: 'strict mode' };
         if (trust === 'AUTO')

package/dist/process-priority.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Everything an agent starts runs at a lower CPU priority than the daemon that
+ * supervises it.
+ *
+ * The failure this exists for is the runner starving itself with its own
+ * children (16.08): a session's build saturated the box, the daemon lost four
+ * heartbeats in a row, the server went Offline and every session on that
+ * machine answered 504 — while the work it was doing was fine. The daemon's job
+ * during a heavy turn is a few milliseconds of socket traffic; it should not
+ * have to queue behind a `tsc` it launched itself.
+ *
+ * **What this gives.** Inside the service's own cgroup the daemon (nice 0) gets
+ * the processor before the agents (nice 10); neighbouring sessions, all at 10,
+ * still share it evenly between themselves. Children inherit the nice value at
+ * fork, so a `vitest` the agent starts through Bash — several levels down from
+ * the process we renice — is covered without us knowing about it.
+ *
+ * Inheritance is why every call site is the line straight after its `spawn`:
+ * measured here, a grandchild forked AFTER the call comes up at 10 and one
+ * forked in the microseconds before it stays at 0. An agent needs hundreds of
+ * milliseconds to boot before it forks anything, so that window is empty in
+ * practice — but it is a window, and it only grows if the call drifts down the
+ * function.
+ *
+ * **What it does NOT give.** Against processes OUTSIDE the cgroup (production
+ * in `system.slice`) it does nothing at all: across cgroups the split is
+ * decided by `cpu.weight`, and nice only orders tasks within one. It does not
+ * touch memory, which is the mechanism behind three of the four incidents on
+ * other people's machines. This is the approach to stage 2 (a scope per session
+ * with a memory ceiling) and the fallback for it on cgroup v1, where stage 2
+ * cannot work — not a replacement for it.
+ *
+ * Priority is a convenience, not correctness: nothing here throws. A session
+ * that runs at the wrong priority is a slower machine; a session that fails to
+ * start because renicing failed is a broken product.
+ */
+/**
+ * The nice value every process the runner spawns for an agent gets.
+ *
+ * 10 rather than 19: the point is to lose to the daemon and to anything the
+ * owner is doing by hand, not to be scheduled last behind every background cron
+ * on the box. The scheduler's weight table gives nice 10 about a ninth of the
+ * share of nice 0 under contention (1024 → 110), which is all the room the
+ * heartbeat needs — 19 would buy an order of magnitude more and cost a session
+ * its throughput whenever anything else on the machine woke up.
+ */
+export declare const NICE = 10;
+/**
+ * Push one spawned process down to {@link NICE}. Never throws.
+ *
+ * Takes `number | undefined` because that is exactly what `child.pid` is: a
+ * spawn that failed has none, and the caller should not have to ask.
+ */
+export declare function lowerPriority(pid: number | undefined): void;
+//# sourceMappingURL=process-priority.d.ts.map

package/dist/process-priority.js

@@ -0,0 +1,99 @@
+import os from 'node:os';
+import { log } from './log.js';
+/**
+ * Everything an agent starts runs at a lower CPU priority than the daemon that
+ * supervises it.
+ *
+ * The failure this exists for is the runner starving itself with its own
+ * children (16.08): a session's build saturated the box, the daemon lost four
+ * heartbeats in a row, the server went Offline and every session on that
+ * machine answered 504 — while the work it was doing was fine. The daemon's job
+ * during a heavy turn is a few milliseconds of socket traffic; it should not
+ * have to queue behind a `tsc` it launched itself.
+ *
+ * **What this gives.** Inside the service's own cgroup the daemon (nice 0) gets
+ * the processor before the agents (nice 10); neighbouring sessions, all at 10,
+ * still share it evenly between themselves. Children inherit the nice value at
+ * fork, so a `vitest` the agent starts through Bash — several levels down from
+ * the process we renice — is covered without us knowing about it.
+ *
+ * Inheritance is why every call site is the line straight after its `spawn`:
+ * measured here, a grandchild forked AFTER the call comes up at 10 and one
+ * forked in the microseconds before it stays at 0. An agent needs hundreds of
+ * milliseconds to boot before it forks anything, so that window is empty in
+ * practice — but it is a window, and it only grows if the call drifts down the
+ * function.
+ *
+ * **What it does NOT give.** Against processes OUTSIDE the cgroup (production
+ * in `system.slice`) it does nothing at all: across cgroups the split is
+ * decided by `cpu.weight`, and nice only orders tasks within one. It does not
+ * touch memory, which is the mechanism behind three of the four incidents on
+ * other people's machines. This is the approach to stage 2 (a scope per session
+ * with a memory ceiling) and the fallback for it on cgroup v1, where stage 2
+ * cannot work — not a replacement for it.
+ *
+ * Priority is a convenience, not correctness: nothing here throws. A session
+ * that runs at the wrong priority is a slower machine; a session that fails to
+ * start because renicing failed is a broken product.
+ */
+/**
+ * The nice value every process the runner spawns for an agent gets.
+ *
+ * 10 rather than 19: the point is to lose to the daemon and to anything the
+ * owner is doing by hand, not to be scheduled last behind every background cron
+ * on the box. The scheduler's weight table gives nice 10 about a ninth of the
+ * share of nice 0 under contention (1024 → 110), which is all the room the
+ * heartbeat needs — 19 would buy an order of magnitude more and cost a session
+ * its throughput whenever anything else on the machine woke up.
+ */
+export const NICE = 10;
+/**
+ * EPERM is a property of the machine, not of the process — it means this kernel
+ * or container will not let us renice at all, and it will mean that for every
+ * spawn afterwards. Said once; the alternative is one warning per agent process
+ * for the life of the daemon, which is how a real line gets buried.
+ */
+let permissionWarned = false;
+function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        return String(error.code);
+    }
+    return '';
+}
+/**
+ * Push one spawned process down to {@link NICE}. Never throws.
+ *
+ * Takes `number | undefined` because that is exactly what `child.pid` is: a
+ * spawn that failed has none, and the caller should not have to ask.
+ */
+export function lowerPriority(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        os.setPriority(pid, NICE);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        // ESRCH: the child was already gone — a binary that is not there exits
+        // before we get to it. Nothing happened and nothing is wrong, so nothing
+        // is said; the spawn failure itself is reported by whoever spawned it.
+        if (code === 'ESRCH')
+            return;
+        if (code === 'EPERM') {
+            if (permissionWarned)
+                return;
+            permissionWarned = true;
+            log.warn('priority: not allowed to renice agent processes on this machine', {
+                nice: NICE,
+                error: String(error),
+            });
+            return;
+        }
+        log.warn('priority: could not lower a spawned process', {
+            pid,
+            nice: NICE,
+            error: String(error),
+        });
+    }
+}
+//# sourceMappingURL=process-priority.js.map

package/dist/protocol.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { HostLoadFrame } from './host-load.js';
 export declare const SessionDescriptorSchema: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<["TICKET", "CHAT"]>;
@@ -242,6 +243,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         url: string;
         token: string;
     } | undefined;
+    workMode?: "DIRECT" | "BRANCH" | undefined;
     pausedUntil?: string | null | undefined;
     agentLatestVersion?: string | undefined;
     skipAgentPrompt?: boolean | undefined;
@@ -252,7 +254,6 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         baseBranch?: string | undefined;
         baseSha?: string | undefined;
     } | undefined;
-    workMode?: "DIRECT" | "BRANCH" | undefined;
 }, {
     agent: "CLAUDE" | "CODEX";
     id: string;
@@ -284,6 +285,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         token: string;
     } | undefined;
     mode?: "ask" | "plan" | "auto" | "full" | undefined;
+    workMode?: unknown;
     model?: string | null | undefined;
     effort?: string | null | undefined;
     epoch?: number | undefined;
@@ -296,7 +298,6 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     skipAgentPrompt?: unknown;
     branchHint?: unknown;
     branchPlan?: unknown;
-    workMode?: unknown;
 }>;
 export type SessionDescriptor = z.infer<typeof SessionDescriptorSchema>;
 /**
@@ -660,6 +661,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
@@ -670,7 +672,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseBranch?: string | undefined;
             baseSha?: string | undefined;
         } | undefined;
-        workMode?: "DIRECT" | "BRANCH" | undefined;
     }, {
         agent: "CLAUDE" | "CODEX";
         id: string;
@@ -702,6 +703,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         mode?: "ask" | "plan" | "auto" | "full" | undefined;
+        workMode?: unknown;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -714,12 +716,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
-        workMode?: unknown;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    type: "hello_ack";
-    serverName: string;
-    serverId: string;
     sessions: {
         mode: "ask" | "plan" | "auto" | "full";
         agent: "CLAUDE" | "CODEX";
@@ -758,6 +756,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
@@ -768,13 +767,12 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseBranch?: string | undefined;
             baseSha?: string | undefined;
         } | undefined;
-        workMode?: "DIRECT" | "BRANCH" | undefined;
     }[];
-    maxSessions?: number | undefined;
-}, {
     type: "hello_ack";
     serverName: string;
     serverId: string;
+    maxSessions?: number | undefined;
+}, {
     sessions: {
         agent: "CLAUDE" | "CODEX";
         id: string;
@@ -806,6 +804,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         mode?: "ask" | "plan" | "auto" | "full" | undefined;
+        workMode?: unknown;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -818,8 +817,10 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
-        workMode?: unknown;
     }[];
+    type: "hello_ack";
+    serverName: string;
+    serverId: string;
     maxSessions?: unknown;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"event_ack">;
@@ -1093,6 +1094,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
@@ -1103,7 +1105,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseBranch?: string | undefined;
             baseSha?: string | undefined;
         } | undefined;
-        workMode?: "DIRECT" | "BRANCH" | undefined;
     }, {
         agent: "CLAUDE" | "CODEX";
         id: string;
@@ -1135,6 +1136,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         mode?: "ask" | "plan" | "auto" | "full" | undefined;
+        workMode?: unknown;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -1147,10 +1149,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
-        workMode?: unknown;
     }>;
 }, "strip", z.ZodTypeAny, {
-    type: "session_start";
     session: {
         mode: "ask" | "plan" | "auto" | "full";
         agent: "CLAUDE" | "CODEX";
@@ -1189,6 +1189,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
@@ -1199,10 +1200,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseBranch?: string | undefined;
             baseSha?: string | undefined;
         } | undefined;
-        workMode?: "DIRECT" | "BRANCH" | undefined;
     };
-}, {
     type: "session_start";
+}, {
     session: {
         agent: "CLAUDE" | "CODEX";
         id: string;
@@ -1234,6 +1234,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         mode?: "ask" | "plan" | "auto" | "full" | undefined;
+        workMode?: unknown;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -1246,8 +1247,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
-        workMode?: unknown;
     };
+    type: "session_start";
 }>, z.ZodObject<{
     type: z.ZodLiteral<"session_message">;
     sessionId: z.ZodString;
@@ -1406,8 +1407,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
 }, "strip", z.ZodTypeAny, {
     type: "workspace_settings";
     workspaceId: string;
-    trustMode?: "STRICT" | "NORMAL" | "AUTO" | undefined;
     agentAutoCommit?: boolean | undefined;
+    trustMode?: "STRICT" | "NORMAL" | "AUTO" | undefined;
     agentPushBan?: boolean | undefined;
     agentProtectedBranches?: string[] | undefined;
     agentAllowForcePush?: boolean | undefined;
@@ -1415,8 +1416,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
 }, {
     type: "workspace_settings";
     workspaceId: string;
-    trustMode?: "STRICT" | "NORMAL" | "AUTO" | undefined;
     agentAutoCommit?: boolean | undefined;
+    trustMode?: "STRICT" | "NORMAL" | "AUTO" | undefined;
     agentPushBan?: boolean | undefined;
     agentProtectedBranches?: string[] | undefined;
     agentAllowForcePush?: boolean | undefined;
@@ -1651,7 +1652,28 @@ export type RunnerFrame = {
         from: string | null;
         to: string;
     };
-} | {
+}
+/**
+ * What this machine's own load looks like, right now (plan §5.3).
+ *
+ * A frame of its own rather than a field of `hello`, for the same reason
+ * `agent_versions` is one: `hello` is composed once per process and replayed
+ * on every reconnect, so a load put there would be frozen at daemon start —
+ * a number that is always wrong except in the first second of the machine's
+ * life. This one is measured on a timer and sent only when it moved.
+ *
+ * Nothing static travels here. `machine: {cpuCount, memTotalBytes,
+ * memAvailableBytes}` is already in `hello`, and repeating facts is how two
+ * sources of one truth start disagreeing. `cpuCount` is the single exception
+ * and it earns its place: load1 without it cannot be read as a ratio, and a
+ * consumer joining two frames to find out would eventually paint one
+ * machine's load against another's core count.
+ *
+ * Fields and thresholds mirror `@devbridge/shared` — see `host-load.ts`.
+ */
+ | ({
+    type: 'host_load';
+} & HostLoadFrame) | {
     type: 'pong';
 };
 //# sourceMappingURL=protocol.d.ts.map