@bridge4dev/runner 0.46.1 → 0.47.0

package/dist/protocol.d.ts

@@ -30,6 +30,31 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
      * behaviour every runner had before this release.
      */
     pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    /**
+     * The newest published version of THIS session's agent — Р13, §4.8.
+     *
+     * The API sends it only when the machine's «Auto-update agents» switch is on,
+     * so **the absence of this field is the off position**. That is why the switch
+     * needs no frame, no acknowledgement and no capability handshake: a runner
+     * older than 0.47.0 drops the field (this schema is not `.strict()`), and a
+     * runner that is told nothing does nothing.
+     *
+     * Never a package name, a URL or a command — only a version, and only for the
+     * agent this session is starting. Everything about WHAT gets installed comes
+     * from the registry compiled into this build (§6).
+     *
+     * `.catch(undefined)` like its neighbours: this rides inside `hello_ack`,
+     * which carries every session of the server, so one malformed value must cost
+     * its own session at most — and here «cost» means «no auto-update», the
+     * behaviour of every runner shipped before this one.
+     *
+     * The version pattern is stated HERE as well as inside `installAgent`, and the
+     * duplication is the point: §6 says the server may pick the version and
+     * nothing else, so the boundary that first reads the value is the boundary
+     * that should refuse anything which is not a plain `x.y.z`. Anything else
+     * arrives as `undefined`, which is the same as «auto-update is off».
+     */
+    agentLatestVersion: z.ZodCatch<z.ZodOptional<z.ZodString>>;
     workspace: z.ZodObject<{
         id: z.ZodString;
         path: z.ZodString;
@@ -75,9 +100,9 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         budgetUsd: z.ZodNullable<z.ZodNumber>;
         budgetMinutes: z.ZodNullable<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
+        path: string;
         trustMode: "STRICT" | "NORMAL" | "AUTO";
         id: string;
-        path: string;
         projectId: string;
         budgetUsd: number | null;
         budgetMinutes: number | null;
@@ -88,9 +113,9 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         agentAllowForcePush?: boolean | undefined;
         agentAllowDestructiveGit?: boolean | undefined;
     }, {
+        path: string;
         trustMode: "STRICT" | "NORMAL" | "AUTO";
         id: string;
-        path: string;
         projectId: string;
         budgetUsd: number | null;
         budgetMinutes: number | null;
@@ -181,9 +206,9 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     mode: "ask" | "plan" | "auto" | "full";
+    agent: "CLAUDE" | "CODEX";
     id: string;
     status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-    agent: "CLAUDE" | "CODEX";
     kind: "TICKET" | "CHAT";
     model: string | null;
     effort: string | null;
@@ -195,9 +220,9 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     activeMsBase: number;
     extraBudgetMinutes: number | null;
     workspace: {
+        path: string;
         trustMode: "STRICT" | "NORMAL" | "AUTO";
         id: string;
-        path: string;
         projectId: string;
         budgetUsd: number | null;
         budgetMinutes: number | null;
@@ -218,6 +243,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         token: string;
     } | undefined;
     pausedUntil?: string | null | undefined;
+    agentLatestVersion?: string | undefined;
     skipAgentPrompt?: boolean | undefined;
     branchHint?: string | undefined;
     branchPlan?: {
@@ -228,16 +254,16 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     } | undefined;
     workMode?: "DIRECT" | "BRANCH" | undefined;
 }, {
+    agent: "CLAUDE" | "CODEX";
     id: string;
     status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-    agent: "CLAUDE" | "CODEX";
     kind: "TICKET" | "CHAT";
     prompt: string;
     providerSessionId: string | null;
     workspace: {
+        path: string;
         trustMode: "STRICT" | "NORMAL" | "AUTO";
         id: string;
-        path: string;
         projectId: string;
         budgetUsd: number | null;
         budgetMinutes: number | null;
@@ -266,6 +292,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     activeMsBase?: number | undefined;
     extraBudgetMinutes?: number | null | undefined;
     pausedUntil?: unknown;
+    agentLatestVersion?: unknown;
     skipAgentPrompt?: unknown;
     branchHint?: unknown;
     branchPlan?: unknown;
@@ -421,6 +448,31 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
          * behaviour every runner had before this release.
          */
         pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+        /**
+         * The newest published version of THIS session's agent — Р13, §4.8.
+         *
+         * The API sends it only when the machine's «Auto-update agents» switch is on,
+         * so **the absence of this field is the off position**. That is why the switch
+         * needs no frame, no acknowledgement and no capability handshake: a runner
+         * older than 0.47.0 drops the field (this schema is not `.strict()`), and a
+         * runner that is told nothing does nothing.
+         *
+         * Never a package name, a URL or a command — only a version, and only for the
+         * agent this session is starting. Everything about WHAT gets installed comes
+         * from the registry compiled into this build (§6).
+         *
+         * `.catch(undefined)` like its neighbours: this rides inside `hello_ack`,
+         * which carries every session of the server, so one malformed value must cost
+         * its own session at most — and here «cost» means «no auto-update», the
+         * behaviour of every runner shipped before this one.
+         *
+         * The version pattern is stated HERE as well as inside `installAgent`, and the
+         * duplication is the point: §6 says the server may pick the version and
+         * nothing else, so the boundary that first reads the value is the boundary
+         * that should refuse anything which is not a plain `x.y.z`. Anything else
+         * arrives as `undefined`, which is the same as «auto-update is off».
+         */
+        agentLatestVersion: z.ZodCatch<z.ZodOptional<z.ZodString>>;
         workspace: z.ZodObject<{
             id: z.ZodString;
             path: z.ZodString;
@@ -466,9 +518,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: z.ZodNullable<z.ZodNumber>;
             budgetMinutes: z.ZodNullable<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -479,9 +531,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentAllowForcePush?: boolean | undefined;
             agentAllowDestructiveGit?: boolean | undefined;
         }, {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -572,9 +624,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         }>>;
     }, "strip", z.ZodTypeAny, {
         mode: "ask" | "plan" | "auto" | "full";
+        agent: "CLAUDE" | "CODEX";
         id: string;
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-        agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         model: string | null;
         effort: string | null;
@@ -586,9 +638,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase: number;
         extraBudgetMinutes: number | null;
         workspace: {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -609,6 +661,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         pausedUntil?: string | null | undefined;
+        agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
@@ -619,16 +672,16 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         } | undefined;
         workMode?: "DIRECT" | "BRANCH" | undefined;
     }, {
+        agent: "CLAUDE" | "CODEX";
         id: string;
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-        agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         prompt: string;
         providerSessionId: string | null;
         workspace: {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -657,6 +710,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
         pausedUntil?: unknown;
+        agentLatestVersion?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
@@ -668,9 +722,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     serverId: string;
     sessions: {
         mode: "ask" | "plan" | "auto" | "full";
+        agent: "CLAUDE" | "CODEX";
         id: string;
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-        agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         model: string | null;
         effort: string | null;
@@ -682,9 +736,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase: number;
         extraBudgetMinutes: number | null;
         workspace: {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -705,6 +759,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         pausedUntil?: string | null | undefined;
+        agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
@@ -721,16 +776,16 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     serverName: string;
     serverId: string;
     sessions: {
+        agent: "CLAUDE" | "CODEX";
         id: string;
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-        agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         prompt: string;
         providerSessionId: string | null;
         workspace: {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -759,6 +814,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
         pausedUntil?: unknown;
+        agentLatestVersion?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
@@ -825,6 +881,31 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
          * behaviour every runner had before this release.
          */
         pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+        /**
+         * The newest published version of THIS session's agent — Р13, §4.8.
+         *
+         * The API sends it only when the machine's «Auto-update agents» switch is on,
+         * so **the absence of this field is the off position**. That is why the switch
+         * needs no frame, no acknowledgement and no capability handshake: a runner
+         * older than 0.47.0 drops the field (this schema is not `.strict()`), and a
+         * runner that is told nothing does nothing.
+         *
+         * Never a package name, a URL or a command — only a version, and only for the
+         * agent this session is starting. Everything about WHAT gets installed comes
+         * from the registry compiled into this build (§6).
+         *
+         * `.catch(undefined)` like its neighbours: this rides inside `hello_ack`,
+         * which carries every session of the server, so one malformed value must cost
+         * its own session at most — and here «cost» means «no auto-update», the
+         * behaviour of every runner shipped before this one.
+         *
+         * The version pattern is stated HERE as well as inside `installAgent`, and the
+         * duplication is the point: §6 says the server may pick the version and
+         * nothing else, so the boundary that first reads the value is the boundary
+         * that should refuse anything which is not a plain `x.y.z`. Anything else
+         * arrives as `undefined`, which is the same as «auto-update is off».
+         */
+        agentLatestVersion: z.ZodCatch<z.ZodOptional<z.ZodString>>;
         workspace: z.ZodObject<{
             id: z.ZodString;
             path: z.ZodString;
@@ -870,9 +951,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             budgetUsd: z.ZodNullable<z.ZodNumber>;
             budgetMinutes: z.ZodNullable<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -883,9 +964,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             agentAllowForcePush?: boolean | undefined;
             agentAllowDestructiveGit?: boolean | undefined;
         }, {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -976,9 +1057,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         }>>;
     }, "strip", z.ZodTypeAny, {
         mode: "ask" | "plan" | "auto" | "full";
+        agent: "CLAUDE" | "CODEX";
         id: string;
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-        agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         model: string | null;
         effort: string | null;
@@ -990,9 +1071,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase: number;
         extraBudgetMinutes: number | null;
         workspace: {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -1013,6 +1094,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         pausedUntil?: string | null | undefined;
+        agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
@@ -1023,16 +1105,16 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         } | undefined;
         workMode?: "DIRECT" | "BRANCH" | undefined;
     }, {
+        agent: "CLAUDE" | "CODEX";
         id: string;
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-        agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         prompt: string;
         providerSessionId: string | null;
         workspace: {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -1061,6 +1143,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
         pausedUntil?: unknown;
+        agentLatestVersion?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
@@ -1070,9 +1153,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     type: "session_start";
     session: {
         mode: "ask" | "plan" | "auto" | "full";
+        agent: "CLAUDE" | "CODEX";
         id: string;
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-        agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         model: string | null;
         effort: string | null;
@@ -1084,9 +1167,9 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase: number;
         extraBudgetMinutes: number | null;
         workspace: {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -1107,6 +1190,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         pausedUntil?: string | null | undefined;
+        agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
@@ -1120,16 +1204,16 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
 }, {
     type: "session_start";
     session: {
+        agent: "CLAUDE" | "CODEX";
         id: string;
         status: "RUNNING" | "FAILED" | "STARTING" | "WAITING_INPUT" | "WAITING_PERMISSION" | "REVIEW" | "DONE" | "STOPPED";
-        agent: "CLAUDE" | "CODEX";
         kind: "TICKET" | "CHAT";
         prompt: string;
         providerSessionId: string | null;
         workspace: {
+            path: string;
             trustMode: "STRICT" | "NORMAL" | "AUTO";
             id: string;
-            path: string;
             projectId: string;
             budgetUsd: number | null;
             budgetMinutes: number | null;
@@ -1158,6 +1242,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
         pausedUntil?: unknown;
+        agentLatestVersion?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
@@ -1365,16 +1450,16 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     name: string;
     type: "command";
     requestId: string;
+    args?: Record<string, unknown> | undefined;
     sessionId?: string | undefined;
     workspaceId?: string | undefined;
-    args?: Record<string, unknown> | undefined;
 }, {
     name: string;
     type: "command";
     requestId: string;
+    args?: Record<string, unknown> | undefined;
     sessionId?: string | undefined;
     workspaceId?: string | undefined;
-    args?: Record<string, unknown> | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"verify_report_ack">;
     runId: z.ZodString;
@@ -1524,6 +1609,48 @@ export type RunnerFrame = {
      */
     blockingIds: string[];
     maxSessions: number;
+}
+/**
+ * Which agent CLIs this machine has, and which version of each (Р3, Р7).
+ *
+ * A frame of its own rather than a field of `hello`, and that is the whole
+ * design decision: capabilities are computed once per process and replayed on
+ * every reconnect (`ws-client.ts`), so a version put there would be frozen
+ * at daemon start and would never move after an install. This frame is sent
+ * after each `hello_ack`, after an install, and once an hour.
+ *
+ * It carries no package name, URL or command — only names from the registry
+ * mirror and plain versions. The server is not the thing that knows how an
+ * agent is installed; this runner is (§6 of the plan).
+ */
+ | {
+    type: 'agent_versions';
+    /**
+     * When the MACHINE measured this, ISO.
+     *
+     * Load-bearing: frames without a session id take the gateway's unordered
+     * fast path, so two of these can be handled out of order. The API keeps
+     * the newer measurement and drops the older one by this field.
+     */
+    at: string;
+    /** Why it was sent: a plain measurement, our button, or auto-update. */
+    reason: 'measured' | 'manual' | 'auto';
+    /**
+     * Keyed by the registry's wire name. `version: null` = not installed;
+     * `probeFailed` = the binary is there and would not answer, which is a
+     * third state and must never be read as absence.
+     */
+    agents: Record<string, {
+        version: string | null;
+        managedBy: string;
+        probeFailed?: boolean;
+    }>;
+    /** What an install actually changed, for the audit trail (Р14). */
+    changed?: {
+        agent: string;
+        from: string | null;
+        to: string;
+    };
 } | {
     type: 'pong';
 };

package/dist/protocol.js

@@ -1,11 +1,14 @@
 import { z } from 'zod';
+import { AGENT_DB_VALUES, AGENT_VERSION_PATTERN } from './agent-registry.js';
 // Wire protocol with the DevBridge API (mirror of
 // packages/api/src/modules/dev-orchestration/dev-orchestration.schema.ts —
 // the API side is the source of truth).
 export const SessionDescriptorSchema = z.object({
     id: z.string().uuid(),
     kind: z.enum(['TICKET', 'CHAT']),
-    agent: z.enum(['CLAUDE', 'CODEX']),
+    // The agents this build has adapters for — from the registry mirror, so a
+    // list that grew in `@devbridge/shared` cannot be forgotten here (Р15).
+    agent: z.enum(AGENT_DB_VALUES),
     status: z.enum([
         'STARTING',
         'RUNNING',
@@ -56,6 +59,35 @@ export const SessionDescriptorSchema = z.object({
      * behaviour every runner had before this release.
      */
     pausedUntil: z.string().max(40).nullable().optional().catch(undefined),
+    /**
+     * The newest published version of THIS session's agent — Р13, §4.8.
+     *
+     * The API sends it only when the machine's «Auto-update agents» switch is on,
+     * so **the absence of this field is the off position**. That is why the switch
+     * needs no frame, no acknowledgement and no capability handshake: a runner
+     * older than 0.47.0 drops the field (this schema is not `.strict()`), and a
+     * runner that is told nothing does nothing.
+     *
+     * Never a package name, a URL or a command — only a version, and only for the
+     * agent this session is starting. Everything about WHAT gets installed comes
+     * from the registry compiled into this build (§6).
+     *
+     * `.catch(undefined)` like its neighbours: this rides inside `hello_ack`,
+     * which carries every session of the server, so one malformed value must cost
+     * its own session at most — and here «cost» means «no auto-update», the
+     * behaviour of every runner shipped before this one.
+     *
+     * The version pattern is stated HERE as well as inside `installAgent`, and the
+     * duplication is the point: §6 says the server may pick the version and
+     * nothing else, so the boundary that first reads the value is the boundary
+     * that should refuse anything which is not a plain `x.y.z`. Anything else
+     * arrives as `undefined`, which is the same as «auto-update is off».
+     */
+    agentLatestVersion: z
+        .string()
+        .regex(new RegExp(AGENT_VERSION_PATTERN))
+        .optional()
+        .catch(undefined),
     workspace: z.object({
         id: z.string().uuid(),
         path: z.string(),

package/dist/recipe-schema.d.ts

@@ -129,17 +129,17 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
             timeoutSec?: number | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        verify?: {
+        install?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
         } | undefined;
-        build?: {
+        verify?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
         } | undefined;
-        install?: {
+        build?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
@@ -155,17 +155,17 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
             timeoutSec?: number | undefined;
         } | undefined;
     }, {
-        verify?: {
+        install?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
         } | undefined;
-        build?: {
+        verify?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
         } | undefined;
-        install?: {
+        build?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
@@ -214,17 +214,17 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     version: 1;
     steps: {
-        verify?: {
+        install?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
         } | undefined;
-        build?: {
+        verify?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
         } | undefined;
-        install?: {
+        build?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
@@ -263,17 +263,17 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
     } | undefined;
     notes?: string | undefined;
     steps?: {
-        verify?: {
+        install?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
         } | undefined;
-        build?: {
+        verify?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;
         } | undefined;
-        install?: {
+        build?: {
             run: string;
             env?: Record<string, string> | undefined;
             timeoutSec?: number | undefined;

package/dist/self-update.d.ts

@@ -45,6 +45,12 @@ export interface SelfUpdateOptions {
     packageDir?: string | null;
     /** Test seam: is this process supervised (defaults to autodetect). */
     supervised?: boolean;
+    /**
+     * Test seam for C4: whether this build runs sessions on the Claude binary
+     * bundled with it. Both branches must be provable — the `false` one is what
+     * stops every future runner update from rolling itself back.
+     */
+    bundledClaude?: boolean;
     /**
      * Test seam for the resource-limits drop-in. Injected rather than called
      * directly because the real one writes into `$HOME` — a test that exercised
@@ -134,4 +140,12 @@ export declare function manualUpdateCommand(tarballUrl: string, options?: {
     packageDir?: string | null;
 }): string;
 export declare function selfUpdate(options: SelfUpdateOptions): Promise<SelfUpdateOutcome>;
+/**
+ * The same reading of a failed child process, for `agent-install.ts`.
+ *
+ * Exported rather than copied: installing an agent CLI shells out to the very
+ * same npm, and a second implementation would drift into reporting the ERESOLVE
+ * wall this one exists to suppress.
+ */
+export declare function describeCommandFailure(error: unknown): string;
 //# sourceMappingURL=self-update.d.ts.map