- CLI/plugins: route lazy plugin command-registration chatter to stderr only during JSON-output command registration, keeping plugin-backed `--json` stdout parseable without changing parse-only or pass-through `--json` behavior. Fixes #81535. (#81536) Thanks @ScientificProgrammer and @vincentkoc.

- Plugins: treat git plugin install refs as refs instead of checkout flags, so option-like selectors fail checkout instead of silently installing the default branch. Fixes #79898. (#79901) Thanks @afurm and @vincentkoc.

- Doctor/memory: stop warning that no memory plugin is active when an enabled alternate memory plugin explicitly owns the memory slot, while preserving the warning for missing or disabled slot entries. Fixes #78540. (#78557) Thanks @carladams1299-lab and @vincentkoc.

- Plugins: keep process-local plugin metadata snapshot memo freshness tied to the cached registry snapshot so policy-stale derived plugin metadata edits invalidate the memo instead of returning stale owners or command aliases. (#81064) Thanks @Kaspre.

- Plugins: keep derived plugin metadata snapshots uncached when the persisted registry is missing, disabled, or stale, so newly added plugins are discovered without restarting. (#81064) Thanks @Kaspre.

- Plugins: discover provider plugins from `setup.providers[].envVars` credentials during provider discovery while keeping the deprecated `providerAuthEnvVars` fallback. (#81542) Thanks @JARVIS-Glasses.

- Docs/Codex harness: clarify that per-agent `CODEX_HOME` isolates `~/.codex` while inherited `HOME` intentionally keeps `.agents` discovery and subprocess user-home state available.

- CLI/plugins: keep bare plugin and parent-command help on the lightweight path, avoiding plugin registry discovery before rendering help.

function createSnapshot(

params: {

config?: Parameters<typeof resolveInstalledPluginIndexPolicyHash>[0];

registrySource?: PluginMetadataSnapshot["registrySource"];

workspaceDir?: string;

} = {},

): PluginMetadataSnapshot {

return {

policyHash: resolveInstalledPluginIndexPolicyHash(params.config),

...(params.registrySource ? { registrySource: params.registrySource } : {}),

...(params.workspaceDir ? { workspaceDir: params.workspaceDir } : {}),

index: {

version: 1,

expect(getCurrentPluginMetadataSnapshot()).toBeUndefined();

});

it("does not keep derived registry snapshots as the current snapshot", () => {

const persisted = createSnapshot({ registrySource: "persisted" });

setCurrentPluginMetadataSnapshot(persisted);

setCurrentPluginMetadataSnapshot(createSnapshot({ registrySource: "derived" }));

expect(getCurrentPluginMetadataSnapshot()).toBeUndefined();

});

it("restores a captured current snapshot state", () => {

const firstConfig = { plugins: { allow: ["first"] } };

const secondConfig = { plugins: { allow: ["second"] } };

});

}

export function isReusableCurrentPluginMetadataSnapshot(

snapshot: PluginMetadataSnapshot,

): boolean {

return snapshot.registrySource !== "derived";

}

// Single-slot Gateway-owned handoff. Replace or clear it at lifecycle boundaries;

// never accumulate historical metadata snapshots here.

export function setCurrentPluginMetadataSnapshot(

workspaceDir?: string;

} = {},

): void {

if (snapshot && !isReusableCurrentPluginMetadataSnapshot(snapshot)) {

clearCurrentPluginMetadataSnapshotState();

return;

}

const compatiblePolicyHashes = snapshot

? options.compatibleConfigs?.map((config) => resolveInstalledPluginIndexPolicyHash(config))

: undefined;

expect(second.byPluginId.get("demo")).toBe(second.plugins[0]);

});

it("memoizes policy-stale derived snapshots used by validation callers", () => {

it("does not memoize policy-stale derived snapshots", () => {

const stateDir = tempStateDir();

touchPersistedIndex(stateDir);

loadPluginRegistrySnapshotWithMetadata.mockReturnValue({

loadPluginMetadataSnapshot({ config: {}, env: {}, stateDir });

loadPluginMetadataSnapshot({ config: {}, env: {}, stateDir });

expect(loadPluginRegistrySnapshotWithMetadata).toHaveBeenCalledOnce();

expect(loadPluginRegistrySnapshotWithMetadata).toHaveBeenCalledTimes(2);

});

it("refreshes policy-stale derived snapshots when derived plugin files change", () => {

registrySource: PluginRegistrySnapshotSource;

snapshot: PluginMetadataSnapshot;

}): boolean {

if (result.snapshot.index.plugins.length === 0) {

return false;

}

if (result.registrySource !== "derived") {

return true;

}

return (

result.snapshot.registryDiagnostics.length > 0 &&

result.snapshot.registryDiagnostics.every(

(diagnostic) => diagnostic.code === "persisted-registry-stale-policy",

)

);

return result.registrySource !== "derived" && result.snapshot.index.plugins.length > 0;

}

function loadPluginMetadataSnapshotImpl(params: LoadPluginMetadataSnapshotParams): {

registrySource: registryResult.source,

snapshot: {

policyHash: index.policyHash,

registrySource: registryResult.source,

configFingerprint: resolvePluginMetadataControlPlaneFingerprint({

config: params.config,

env: params.env,

import type { InstalledPluginIndex } from "./installed-plugin-index.js";

import type { PluginManifestRecord, PluginManifestRegistry } from "./manifest-registry.js";

import type { PluginDiagnostic } from "./manifest-types.js";

import type { PluginRegistrySnapshotSource } from "./plugin-registry-snapshot.js";

export type PluginMetadataSnapshotOwnerMaps = {

channels: ReadonlyMap<string, readonly string[]>;

export type PluginMetadataSnapshot = {

policyHash: string;

configFingerprint?: string;

registrySource?: PluginRegistrySnapshotSource;

workspaceDir?: string;

index: InstalledPluginIndex;

registryDiagnostics: readonly PluginMetadataSnapshotRegistryDiagnostic[];

const loadPluginMetadataSnapshotMock = vi.fn(() => metadataSnapshot);

const getCurrentPluginMetadataSnapshotMock = vi.fn(() => undefined);

const setCurrentPluginMetadataSnapshotMock = vi.fn();

const clearCurrentPluginMetadataSnapshotMock = vi.fn();

let resolvePluginRuntimeLoadContext: typeof import("./load-context.js").resolvePluginRuntimeLoadContext;

let buildPluginRuntimeLoadOptions: typeof import("./load-context.js").buildPluginRuntimeLoadOptions;

}));

vi.mock("../current-plugin-metadata-snapshot.js", () => ({

clearCurrentPluginMetadataSnapshot: clearCurrentPluginMetadataSnapshotMock,

getCurrentPluginMetadataSnapshot: getCurrentPluginMetadataSnapshotMock,

isReusableCurrentPluginMetadataSnapshot: (

snapshot: typeof metadataSnapshot & { registrySource?: "derived" },

) => snapshot.registrySource !== "derived",

setCurrentPluginMetadataSnapshot: setCurrentPluginMetadataSnapshotMock,

}));

loadPluginMetadataSnapshotMock.mockClear();

getCurrentPluginMetadataSnapshotMock.mockClear();

setCurrentPluginMetadataSnapshotMock.mockClear();

clearCurrentPluginMetadataSnapshotMock.mockClear();

resolveAgentWorkspaceDirMock.mockClear();

resolveDefaultAgentIdMock.mockClear();

expect(resolveAgentWorkspaceDirMock).toHaveBeenCalledWith(resolvedConfig, "default");

});

it("does not store derived metadata as the reusable runtime snapshot", () => {

const derivedSnapshot = { ...metadataSnapshot } as typeof metadataSnapshot & {

registrySource: "derived";

};

derivedSnapshot.registrySource = "derived";

loadPluginMetadataSnapshotMock.mockReturnValueOnce(derivedSnapshot);

resolvePluginRuntimeLoadContext({

config: { plugins: {} },

env: { HOME: "/tmp/openclaw-home" } as NodeJS.ProcessEnv,

});

expect(setCurrentPluginMetadataSnapshotMock).not.toHaveBeenCalled();

expect(clearCurrentPluginMetadataSnapshotMock).toHaveBeenCalledOnce();

});

it("uses the source runtime snapshot for plugin activation source config", () => {

const runtimeConfig = { plugins: {} };

const sourceConfig = {

import { createSubsystemLogger } from "../../logging.js";

import { resolvePluginActivationSourceConfig } from "../activation-source-config.js";

import {

clearCurrentPluginMetadataSnapshot,

getCurrentPluginMetadataSnapshot,

isReusableCurrentPluginMetadataSnapshot,

setCurrentPluginMetadataSnapshot,

} from "../current-plugin-metadata-snapshot.js";

import { extractPluginInstallRecordsFromInstalledPluginIndex } from "../installed-plugin-index-install-records.js";

const workspaceDir =

options?.workspaceDir ?? resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));

if (metadataSnapshot) {

setCurrentPluginMetadataSnapshot(metadataSnapshot, {

config: rawConfig,

compatibleConfigs: [config, activationSourceConfig],

env,

workspaceDir,

});

if (isReusableCurrentPluginMetadataSnapshot(metadataSnapshot)) {

setCurrentPluginMetadataSnapshot(metadataSnapshot, {

config: rawConfig,

compatibleConfigs: [config, activationSourceConfig],

env,

workspaceDir,

});

} else {

clearCurrentPluginMetadataSnapshot();

}

}

return {

rawConfig,