@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/dist/lib/monitors/state.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Native per-monitor state-diff store.
+ *
+ * This is the one genuinely new primitive monitors add over routines: a
+ * last-observed-*value* store. Routines persist per-*run* metadata but have no
+ * last-seen value, so hand-built watchers (the RUSH-1107 SSL watcher) re-invented
+ * state-diffing through a markdown memory file every time. This store kills that.
+ *
+ * Layout (sibling of the runs layout, atomic writes like writeRunMeta):
+ *   ~/.agents/.history/monitors/<name>/state.json      # last-seen hash/value + fire bookkeeping
+ *   ~/.agents/.history/monitors/<name>/fires/<id>/…    # fire history
+ */
+import type { MonitorEvent } from './config.js';
+/** Persisted last-seen state for one monitor. */
+export interface MonitorState {
+    monitorName: string;
+    /** Hash of the last-seen de-dupe signature (see hasChanged). */
+    lastHash: string;
+    /** The last-seen raw observation (truncated for storage). */
+    lastValue: string;
+    /** RFC3339 timestamp of the last observation. */
+    lastSeenAt: string;
+    /** RFC3339 timestamp of the last fire, when the monitor has ever fired. */
+    lastFiredAt?: string;
+    /** Epoch-ms timestamps of recent fires, for the rate-limit / firehose guard. */
+    fireTimes?: number[];
+}
+/** Per-monitor history root, with the (untrusted) name contained to one segment. */
+export declare function getMonitorHistoryDir(name: string): string;
+/** Directory holding a monitor's fire history. */
+export declare function getMonitorFiresDir(name: string): string;
+/** Read a monitor's last-seen state, or null if it has never been observed. */
+export declare function readState(name: string): MonitorState | null;
+/** Persist a monitor's state atomically (temp file + rename, like writeRunMeta). */
+export declare function writeStateRaw(state: MonitorState): void;
+/**
+ * Record a new observation as the monitor's last-seen state, preserving fire
+ * bookkeeping. Truncates the stored raw value so a firehose can't bloat disk.
+ */
+export declare function writeState(name: string, value: string, dedupeKey?: string, extra?: Partial<Pick<MonitorState, 'lastFiredAt' | 'fireTimes'>>): MonitorState;
+/**
+ * The de-dupe signature for an observation. When `dedupeKey` is set, the
+ * signature is the first regex match of dedupeKey against the observation (so
+ * "the same event" is same matched token); otherwise it is the full observation.
+ * An unmatched dedupeKey falls back to the full observation.
+ */
+export declare function dedupeSignature(observation: string, dedupeKey?: string): string;
+/**
+ * True when `observation`'s de-dupe signature differs from the monitor's
+ * last-seen signature (or the monitor has never been observed). Pure read — the
+ * caller persists the new value via writeState only on a real fire.
+ */
+export declare function hasChanged(name: string, observation: string, dedupeKey?: string): boolean;
+/**
+ * Append a fire timestamp and return the pruned window (fires within `windowMs`).
+ * The engine uses the returned length to decide whether the rate limit tripped.
+ */
+export declare function recordFireTime(name: string, now: number, windowMs: number): number[];
+/** Write a fire record to fires/<id>/event.json and return the fire id. */
+export declare function writeFireRecord(event: MonitorEvent, meta?: Record<string, unknown>): string;
+/** A single fire history entry (as read back from disk). */
+export interface FireRecord extends MonitorEvent {
+    runId?: string;
+    action?: string;
+    ok?: boolean;
+    error?: string;
+}
+/** List a monitor's fire history, chronologically ascending. */
+export declare function listFires(name: string): FireRecord[];

package/dist/lib/monitors/state.js

@@ -0,0 +1,144 @@
+/**
+ * Native per-monitor state-diff store.
+ *
+ * This is the one genuinely new primitive monitors add over routines: a
+ * last-observed-*value* store. Routines persist per-*run* metadata but have no
+ * last-seen value, so hand-built watchers (the RUSH-1107 SSL watcher) re-invented
+ * state-diffing through a markdown memory file every time. This store kills that.
+ *
+ * Layout (sibling of the runs layout, atomic writes like writeRunMeta):
+ *   ~/.agents/.history/monitors/<name>/state.json      # last-seen hash/value + fire bookkeeping
+ *   ~/.agents/.history/monitors/<name>/fires/<id>/…    # fire history
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { getMonitorsHistoryDir, ensureAgentsDir } from '../state.js';
+import { safeJoin } from '../paths.js';
+const MAX_STORED_VALUE = 4096;
+/** Per-monitor history root, with the (untrusted) name contained to one segment. */
+export function getMonitorHistoryDir(name) {
+    return safeJoin(getMonitorsHistoryDir(), name);
+}
+function getStatePath(name) {
+    return path.join(getMonitorHistoryDir(name), 'state.json');
+}
+/** Directory holding a monitor's fire history. */
+export function getMonitorFiresDir(name) {
+    return path.join(getMonitorHistoryDir(name), 'fires');
+}
+/** Read a monitor's last-seen state, or null if it has never been observed. */
+export function readState(name) {
+    const statePath = getStatePath(name);
+    if (!fs.existsSync(statePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist a monitor's state atomically (temp file + rename, like writeRunMeta). */
+export function writeStateRaw(state) {
+    ensureAgentsDir();
+    const dir = getMonitorHistoryDir(state.monitorName);
+    fs.mkdirSync(dir, { recursive: true });
+    const statePath = path.join(dir, 'state.json');
+    const tmp = `${statePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf-8');
+    fs.renameSync(tmp, statePath);
+}
+/**
+ * Record a new observation as the monitor's last-seen state, preserving fire
+ * bookkeeping. Truncates the stored raw value so a firehose can't bloat disk.
+ */
+export function writeState(name, value, dedupeKey, extra = {}) {
+    const prev = readState(name);
+    const state = {
+        monitorName: name,
+        lastHash: hashSignature(value, dedupeKey),
+        lastValue: value.length > MAX_STORED_VALUE ? value.slice(0, MAX_STORED_VALUE) : value,
+        lastSeenAt: new Date().toISOString(),
+        ...(prev?.lastFiredAt ? { lastFiredAt: prev.lastFiredAt } : {}),
+        ...(prev?.fireTimes ? { fireTimes: prev.fireTimes } : {}),
+        ...extra,
+    };
+    writeStateRaw(state);
+    return state;
+}
+/**
+ * The de-dupe signature for an observation. When `dedupeKey` is set, the
+ * signature is the first regex match of dedupeKey against the observation (so
+ * "the same event" is same matched token); otherwise it is the full observation.
+ * An unmatched dedupeKey falls back to the full observation.
+ */
+export function dedupeSignature(observation, dedupeKey) {
+    if (!dedupeKey)
+        return observation;
+    try {
+        const m = new RegExp(dedupeKey).exec(observation);
+        if (m)
+            return m[1] ?? m[0];
+    }
+    catch {
+        /* invalid regex — fall back to full observation */
+    }
+    return observation;
+}
+function hashSignature(observation, dedupeKey) {
+    return createHash('sha256').update(dedupeSignature(observation, dedupeKey)).digest('hex');
+}
+/**
+ * True when `observation`'s de-dupe signature differs from the monitor's
+ * last-seen signature (or the monitor has never been observed). Pure read — the
+ * caller persists the new value via writeState only on a real fire.
+ */
+export function hasChanged(name, observation, dedupeKey) {
+    const prev = readState(name);
+    if (!prev)
+        return true;
+    return prev.lastHash !== hashSignature(observation, dedupeKey);
+}
+/**
+ * Append a fire timestamp and return the pruned window (fires within `windowMs`).
+ * The engine uses the returned length to decide whether the rate limit tripped.
+ */
+export function recordFireTime(name, now, windowMs) {
+    const prev = readState(name);
+    const times = [...(prev?.fireTimes ?? []), now].filter((t) => now - t <= windowMs);
+    return times;
+}
+/** Write a fire record to fires/<id>/event.json and return the fire id. */
+export function writeFireRecord(event, meta = {}) {
+    ensureAgentsDir();
+    const fireId = event.firedAt.replace(/[:.]/g, '-');
+    const fireDir = safeJoin(getMonitorFiresDir(event.monitorName), fireId);
+    fs.mkdirSync(fireDir, { recursive: true });
+    fs.writeFileSync(path.join(fireDir, 'event.json'), JSON.stringify({ ...event, ...meta }, null, 2), 'utf-8');
+    return fireId;
+}
+/** List a monitor's fire history, chronologically ascending. */
+export function listFires(name) {
+    const dir = getMonitorFiresDir(name);
+    if (!fs.existsSync(dir))
+        return [];
+    const ids = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    const fires = [];
+    for (const id of ids) {
+        const eventPath = path.join(dir, id, 'event.json');
+        if (!fs.existsSync(eventPath))
+            continue;
+        try {
+            fires.push(JSON.parse(fs.readFileSync(eventPath, 'utf-8')));
+        }
+        catch {
+            /* skip corrupt record */
+        }
+    }
+    return fires;
+}

package/dist/lib/picker.d.ts

@@ -52,3 +52,56 @@ export declare function itemPicker<T>(config: PickerConfig<T>): Promise<PickedIt
  * row, so a quick single-pick still works.
  */
 export declare function multiItemPicker<T>(config: MultiPickerConfig<T>): Promise<T[] | null>;
+/** Configuration for the dynamic (async-refetch) picker prompt. */
+export interface DynamicPickerConfig<T, F> {
+    message: string;
+    /** The initial filter state. Changing it (via a keybinding) re-runs {@link load}. */
+    initialFilter: F;
+    /** Async loader for the current filter state. Its result is the row pool. */
+    load: (filter: F) => Promise<T[]>;
+    labelFor: (item: T, query: string) => string;
+    /** Stable identity for an item (used for the active-row cursor across reloads). */
+    keyFor: (item: T) => string;
+    /** Client-side text filter over the loaded pool (the `S` search). */
+    matches?: (item: T, query: string) => boolean;
+    buildPreview?: (item: T) => string;
+    /** Dim summary of the current filter state, rendered in the header. */
+    headerFor?: (filter: F) => string;
+    /** The hotkey-legend help line; receives the mode so it can adapt. */
+    helpFor?: (filter: F, mode: 'nav' | 'search') => string;
+    /**
+     * Single-key bindings (by key name) that transform the filter. Returning the
+     * SAME reference is a no-op; a new object triggers a reload.
+     */
+    keyBindings?: Record<string, (filter: F) => F>;
+    /**
+     * Side-effecting keys that don't change the filter (e.g. `y` copies a command).
+     * Receives the live search `query` so the effect can be search-aware. Return a
+     * short string to flash under the list.
+     */
+    onKey?: (name: string, filter: F, active: T | undefined, query: string) => string | void;
+    /** Key that enters search mode (default `s`). */
+    searchKey?: string;
+    /** Key that toggles the preview pane (default `tab`). */
+    previewKey?: string;
+    pageSize?: number;
+    emptyMessage?: string;
+    loadingMessage?: string;
+    enterHint?: string;
+}
+/** The result returned when the user selects a row: the item plus the live filter. */
+export interface DynamicPicked<T, F> {
+    item: T;
+    filter: F;
+}
+/**
+ * Async-refetch variant of {@link itemPicker}. Holds a `filter` object in state and
+ * re-runs `load(filter)` whenever a keybinding mutates it (with a loading placeholder
+ * while the fetch — e.g. an SSH fleet fan-out — is in flight). A separate `S` search
+ * mode filters the loaded pool client-side. `enter` returns the active row + the live
+ * filter; `esc` cancels (from search mode, `esc` first exits search).
+ *
+ * Same render/pagination/preview machinery as the static pickers — only the data
+ * source and keymap are dynamic.
+ */
+export declare function dynamicPicker<T, F>(config: DynamicPickerConfig<T, F>): Promise<DynamicPicked<T, F> | null>;

package/dist/lib/picker.js

@@ -12,7 +12,7 @@
  * display, and keyboard navigation. Used by sessions, teams, and other
  * interactive pickers throughout the CLI.
  */
-import { createPrompt, useState, useKeypress, useEffect, useMemo, usePagination, usePrefix, makeTheme, isEnterKey, isUpKey, isDownKey, isSpaceKey, Separator, } from '@inquirer/core';
+import { createPrompt, useState, useKeypress, useEffect, useMemo, useRef, usePagination, usePrefix, makeTheme, isEnterKey, isUpKey, isDownKey, isSpaceKey, isBackspaceKey, Separator, } from '@inquirer/core';
 import chalk from 'chalk';
 import { stripVTControlCharacters } from 'node:util';
 const DEFAULT_TERMINAL_ROWS = 24;
@@ -324,3 +324,216 @@ export function multiItemPicker(config) {
     });
     return prompt(config);
 }
+/**
+ * Async-refetch variant of {@link itemPicker}. Holds a `filter` object in state and
+ * re-runs `load(filter)` whenever a keybinding mutates it (with a loading placeholder
+ * while the fetch — e.g. an SSH fleet fan-out — is in flight). A separate `S` search
+ * mode filters the loaded pool client-side. `enter` returns the active row + the live
+ * filter; `esc` cancels (from search mode, `esc` first exits search).
+ *
+ * Same render/pagination/preview machinery as the static pickers — only the data
+ * source and keymap are dynamic.
+ */
+export function dynamicPicker(config) {
+    const prompt = createPrompt((cfg, done) => {
+        const theme = makeTheme({});
+        const [status, setStatus] = useState('idle');
+        const [filter, setFilter] = useState(() => cfg.initialFilter);
+        const [items, setItems] = useState([]);
+        const [loading, setLoading] = useState(true);
+        const [query, setQuery] = useState('');
+        const [mode, setMode] = useState('nav');
+        const [previewOpen, setPreviewOpen] = useState(false);
+        const [active, setActive] = useState(0);
+        const [flash, setFlash] = useState('');
+        const prefix = usePrefix({ status, theme });
+        // Guards against a slow load resolving after a newer filter superseded it.
+        const gen = useRef(0);
+        useEffect(() => {
+            const my = ++gen.current;
+            setLoading(true);
+            Promise.resolve(cfg.load(filter))
+                .then((rows) => {
+                if (my !== gen.current)
+                    return;
+                setItems(rows);
+                setLoading(false);
+                setActive(0);
+            })
+                .catch(() => {
+                if (my !== gen.current)
+                    return;
+                setItems([]);
+                setLoading(false);
+            });
+        }, [filter]);
+        const results = useMemo(() => {
+            const q = query.trim();
+            const pool = q && cfg.matches ? items.filter((it) => cfg.matches(it, q)) : items;
+            return pool.slice(0, 200).map((item) => ({
+                value: item,
+                label: cfg.labelFor(item, q),
+            }));
+        }, [items, query]);
+        useEffect(() => {
+            if (active >= results.length)
+                setActive(0);
+        }, [results]);
+        const selected = results[active];
+        const finish = () => {
+            if (!selected)
+                return;
+            setStatus('done');
+            done({ item: selected.value, filter });
+        };
+        useKeypress((key, rl) => {
+            if (isEnterKey(key)) {
+                finish();
+                return;
+            }
+            // Search mode: we own the query buffer (readline's line doesn't survive
+            // across renders here, so we build it from key events). Clear readline
+            // every keystroke so nothing leaks, then append the typed character.
+            if (mode === 'search') {
+                if (key.name === 'escape') {
+                    // Exit search but KEEP the query as an active filter, so hotkeys (and
+                    // the y copy-cmd) operate on the searched view. A second esc in nav
+                    // clears it. Enter also confirms the highlighted row directly.
+                    rl.clearLine(0);
+                    setMode('nav');
+                    return;
+                }
+                if (isUpKey(key)) {
+                    rl.clearLine(0);
+                    if (results.length > 0)
+                        setActive((active - 1 + results.length) % results.length);
+                    return;
+                }
+                if (isDownKey(key)) {
+                    rl.clearLine(0);
+                    if (results.length > 0)
+                        setActive((active + 1) % results.length);
+                    return;
+                }
+                if (isBackspaceKey(key)) {
+                    rl.clearLine(0);
+                    setQuery(query.slice(0, -1));
+                    return;
+                }
+                const seq = key.sequence;
+                rl.clearLine(0);
+                if (seq && seq.length === 1 && seq >= ' ' && !key.ctrl) {
+                    setQuery(query + seq);
+                }
+                return;
+            }
+            // Nav mode: single keys are hotkeys — clear the readline buffer so a hotkey
+            // letter (r/b/c/…) never accumulates as stray input.
+            rl.clearLine(0);
+            if (key.name === 'escape') {
+                // First esc clears an active search filter; a second (no filter) cancels.
+                if (query) {
+                    setQuery('');
+                    return;
+                }
+                done(null);
+                return;
+            }
+            if (isUpKey(key)) {
+                if (results.length > 0)
+                    setActive((active - 1 + results.length) % results.length);
+                return;
+            }
+            if (isDownKey(key)) {
+                if (results.length > 0)
+                    setActive((active + 1) % results.length);
+                return;
+            }
+            if (flash)
+                setFlash('');
+            if (key.name === (cfg.searchKey ?? 's')) {
+                setMode('search');
+                return;
+            }
+            if (cfg.buildPreview && key.name === (cfg.previewKey ?? 'tab')) {
+                setPreviewOpen(!previewOpen);
+                return;
+            }
+            const binding = cfg.keyBindings?.[key.name ?? ''];
+            if (binding) {
+                const next = binding(filter);
+                if (!Object.is(next, filter))
+                    setFilter(next);
+                return;
+            }
+            if (cfg.onKey) {
+                const msg = cfg.onKey(key.name ?? '', filter, selected?.value, query);
+                if (msg)
+                    setFlash(msg);
+            }
+        });
+        const message = theme.style.message(cfg.message, status);
+        if (status === 'done') {
+            return `${prefix} ${message}`;
+        }
+        const headerBits = [prefix, message];
+        if (cfg.headerFor)
+            headerBits.push(chalk.gray(cfg.headerFor(filter)));
+        if (mode === 'search') {
+            headerBits.push(query ? chalk.cyan('/' + query) : chalk.gray('/ (type to filter)'));
+        }
+        else if (query) {
+            headerBits.push(chalk.cyan('/' + query));
+        }
+        const header = headerBits.filter(Boolean).join(' ');
+        const page = usePagination({
+            items: results,
+            active,
+            renderItem({ item, isActive }) {
+                if (Separator.isSeparator(item))
+                    return ` ${item.separator}`;
+                const cursor = isActive ? chalk.cyan('>') : ' ';
+                const row = isActive ? chalk.bold(item.label) : item.label;
+                return `${cursor} ${row}`;
+            },
+            pageSize: cfg.pageSize ?? 12,
+            loop: false,
+        });
+        const help = chalk.gray(cfg.helpFor
+            ? cfg.helpFor(filter, mode)
+            : mode === 'search'
+                ? '↑↓ navigate · esc exit search · ⏎ ' + (cfg.enterHint ?? 'select')
+                : 's search · ↑↓ navigate · ⏎ ' + (cfg.enterHint ?? 'select') + ' · esc cancel');
+        const parts = [header];
+        if (loading) {
+            parts.push(chalk.gray(`  ${cfg.loadingMessage ?? 'Loading…'}`));
+        }
+        else {
+            parts.push(page);
+            if (results.length === 0) {
+                parts.push(chalk.gray(`  ${cfg.emptyMessage ?? 'No matches.'}`));
+            }
+        }
+        if (previewOpen && selected && cfg.buildPreview && !loading) {
+            const width = terminalWidth();
+            const separator = chalk.gray('─'.repeat(Math.min(width, 80)));
+            const flashRows = flash ? renderedRows(flash, width) : 0;
+            const fixedRows = renderedRows(header, width) +
+                renderedRows(parts.slice(1).join('\n'), width) +
+                renderedRows(separator, width) +
+                renderedRows(help, width) +
+                flashRows;
+            const availablePreviewRows = terminalRows() - fixedRows;
+            const preview = limitPreviewHeight(cfg.buildPreview(selected.value), availablePreviewRows, width);
+            if (preview) {
+                parts.push(separator);
+                parts.push(preview);
+            }
+        }
+        if (flash)
+            parts.push(chalk.green(flash));
+        parts.push(help);
+        return [header, parts.slice(1).join('\n')];
+    });
+    return prompt(config);
+}

package/dist/lib/platform/exec.d.ts

@@ -66,3 +66,19 @@ export declare function quoteWin32ExecArg(arg: string): string;
  * line is byte-identical to the old unquoted join for the common case.
  */
 export declare function composeWin32CommandLine(command: string, args: string[]): string;
+/**
+ * DEP0190-safe execFile/spawn spec when the binary may need `shell: true` on Windows.
+ *
+ * When `needsWindowsShell(bin)` is true, compose ONE fully-quoted command line via
+ * `composeWin32CommandLine` and return an EMPTY args array so Node never concatenates
+ * user-controlled argv (MCP command/args, prompts, …) into the cmd.exe line unescaped.
+ * Off that path the original bin+args are returned unchanged.
+ *
+ * Call as: `const s = execFileShellSpec(bin, args); execFile(s.command, s.args, { shell: s.shell })`.
+ * Pure; optional `platform` override keeps the win32 branch unit-testable on any host.
+ */
+export declare function execFileShellSpec(bin: string, args: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};

package/dist/lib/platform/exec.js

@@ -119,3 +119,20 @@ export function quoteWin32ExecArg(arg) {
 export function composeWin32CommandLine(command, args) {
     return [command, ...args].map(quoteWin32ExecArg).join(' ');
 }
+/**
+ * DEP0190-safe execFile/spawn spec when the binary may need `shell: true` on Windows.
+ *
+ * When `needsWindowsShell(bin)` is true, compose ONE fully-quoted command line via
+ * `composeWin32CommandLine` and return an EMPTY args array so Node never concatenates
+ * user-controlled argv (MCP command/args, prompts, …) into the cmd.exe line unescaped.
+ * Off that path the original bin+args are returned unchanged.
+ *
+ * Call as: `const s = execFileShellSpec(bin, args); execFile(s.command, s.args, { shell: s.shell })`.
+ * Pure; optional `platform` override keeps the win32 branch unit-testable on any host.
+ */
+export function execFileShellSpec(bin, args, platform = process.platform) {
+    if (!needsWindowsShell(bin, platform)) {
+        return { command: bin, args, shell: false };
+    }
+    return { command: composeWin32CommandLine(bin, args), args: [], shell: true };
+}

package/dist/lib/plugins.d.ts

@@ -316,7 +316,37 @@ export declare function getUpstreamManifestVersion(info: PluginSourceInfo): stri
  * Update an installed plugin by re-pulling from its original source.
  * Returns true if the update succeeded.
  */
-export declare function updatePlugin(name: string): Promise<{
+/**
+ * Labels of exec surfaces present in `after` that were NOT present in `before`.
+ * Used by updatePlugin to distinguish a newly-appearing execution surface
+ * (upstream compromise → renewed consent required) from one the user already
+ * trusted (leave enablement alone).
+ */
+export declare function newExecSurfaceLabels(before: PluginCapabilities, after: PluginCapabilities): string[];
+/**
+ * Re-fetch a plugin from its recorded source and apply the update to disk.
+ *
+ * Security (RUSH-1757): a plugin's upstream is mutable. `updatePlugin` never
+ * mutates the live plugin tree before it has inspected the incoming content —
+ * the new revision is fetched into a **quarantine** dir first, its capabilities
+ * are diffed against the current on-disk baseline, and the update is applied to
+ * `plugin.root` only after the trust decision. If the update introduces a NEW
+ * executable surface (hooks/, .mcp.json, bin/, scripts/, settings.json,
+ * permissions/) that the current revision did not carry, the update is refused
+ * unless `options.allowExecSurfaces` is set — the last-good content is kept in
+ * place, so a benign-then-compromised upstream can never execute on the next
+ * update without renewed consent. A surface the user already trusted is not a
+ * "new" surface and does not re-trigger the gate.
+ */
+export declare function updatePlugin(name: string, options?: {
+    allowExecSurfaces?: boolean;
+}): Promise<{
     success: boolean;
     error?: string;
+    /** True when the update was refused because it introduced new exec surfaces. */
+    blockedByExecSurfaces?: boolean;
+    /** Labels of exec surfaces newly introduced by this update, if any. */
+    newExecSurfaces?: string[];
+    /** Whether the applied revision carries executable surfaces (for the caller's re-sync). */
+    hasExecSurfaces?: boolean;
 }>;