Skip to content
Merged
Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
3a49dc0
test(mcp): reproduce Hermes credential revision loss
rsliter Aug 25, 2026
ff64f5c
fix(mcp): preserve Hermes credential revisions
cjagwani Aug 25, 2026
dbdfb29
fix(mcp): align Hermes credential revision contract
prekshivyas Aug 25, 2026
3fa0229
test(mcp): execute Hermes config assertions
apurvvkumaria Aug 25, 2026
8a0127e
merge: refresh from main
apurvvkumaria Aug 25, 2026
0a17735
fix(mcp): preserve revision during teardown rollback
ericksoa Aug 25, 2026
bd3ce57
fix(hermes): avoid duplicate applied anchor writes
prekshivyas Aug 25, 2026
bcf9ebd
fix(mcp): retain scrub rollback revision state
ericksoa Aug 25, 2026
2547e0f
merge: resolve conflicts with main
github-actions[bot] Aug 25, 2026
1692806
fix(mcp): preserve invoked recovery command
apurvvkumaria Aug 25, 2026
98374ee
fix(mcp): reconcile Hermes revision metadata after main merge
prekshivyas Aug 25, 2026
9a4668e
merge: synchronize current main
apurvvkumaria Aug 25, 2026
6c6f0e1
test(mcp): cover Hermes lifecycle rollback revisions
prekshivyas Aug 25, 2026
7d735f9
merge: preserve concurrent PR repairs
apurvvkumaria Aug 25, 2026
6861810
merge: preserve concurrent lifecycle coverage
apurvvkumaria Aug 25, 2026
f445921
merge: synchronize current main
apurvvkumaria Aug 25, 2026
e8c1200
fix(mcp): remove Hermes helper metadata
apurvvkumaria Aug 25, 2026
d4ce801
refactor(mcp): use Hermes branding owner directly
prekshivyas Aug 25, 2026
057e5e8
merge: synchronize current main
apurvvkumaria Aug 25, 2026
f78f84a
refactor(snapshot): inject CLI name into Hermes hint
ericksoa Aug 25, 2026
2f6fc2b
fix(mcp): keep recovery branding within budget
apurvvkumaria Aug 25, 2026
9904cda
merge: preserve concurrent architecture repair
apurvvkumaria Aug 25, 2026
7b45f8a
merge: synchronize current main
apurvvkumaria Aug 25, 2026
78a6282
chore(architecture): lower branding fan-in budget
apurvvkumaria Aug 25, 2026
35ddb05
refactor(mcp): remove recovery command wrapper
apurvvkumaria Aug 25, 2026
594a508
refactor(mcp): inline Hermes recovery branding
prekshivyas Aug 25, 2026
6505f05
merge: preserve contributor architecture repair
apurvvkumaria Aug 25, 2026
302435a
chore(architecture): retain branding fan-in budget
apurvvkumaria Aug 25, 2026
42bc649
docs(mcp): describe Hermes credential revisions
rsliter Aug 25, 2026
1219dc2
fix(mcp): wait for stable credential revision
prekshivyas Aug 25, 2026
4b59c3d
test(mcp): expect stable credential revision
rsliter Aug 25, 2026
e5263dd
Merge branch 'main' into codex/fix-hermes-mcp-runtime-contract-10155
rsliter Aug 26, 2026
4d7ac91
fix(mcp): await exact credential revision
prekshivyas Aug 26, 2026
0cff15f
fix(mcp): keep credential revisions opaque
rsliter Aug 26, 2026
da46392
ci(e2e): reuse exact PR image cohort
ericksoa Aug 26, 2026
f152596
merge: synchronize exact E2E evidence
rsliter Aug 26, 2026
c87835b
ci(e2e): remove temporary exact cohort reuse
rsliter Aug 26, 2026
557b3c6
fix(mcp): fence opaque credential revisions
prekshivyas Aug 26, 2026
f7cf37c
test(mcp): mock credential revision fence
prekshivyas Aug 26, 2026
1613083
merge: synchronize latest main
prekshivyas Aug 26, 2026
286818d
fix(mcp): keep teardown revisions opaque
prekshivyas Aug 26, 2026
cbf312d
docs(mcp): document teardown revision recovery
rsliter Aug 26, 2026
90cc104
Merge remote-tracking branch 'origin/main' into codex/10155-hermes-mc…
prekshivyas Aug 26, 2026
d7a0a6a
test(repository): remove duplicate advisor watch trigger
prekshivyas Aug 26, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions agents/hermes/runtime-config-guard.py
Original file line number Diff line number Diff line change
Expand Up @@ -1455,6 +1455,28 @@ def refresh_hashes(
source_hash_text, config_path, env_path
)
current_mcp, _ = _current_mcp_servers_digest(config_path)
# The transaction helper and the managed supervisor can both observe the
# same pending reload. The helper may commit it first while the supervisor
# still retains its earlier pending observation. Replacing an already-current
# anchor with byte-identical content needlessly changes its inode and can
# make a concurrent host reconciliation reject an otherwise coherent
# snapshot. Keep the repeated apply fail-closed, but make it validation-only:
# authenticate config, env, and every relevant anchor as one stable current
# snapshot before returning without an atomic replacement.
if mcp_transition == "apply" and secrets.compare_digest(
state.intended, state.applied
):
integrity = inspect_mcp_integrity_snapshot(
hermes_dir,
state_path,
compat_hash if mode == "both" else None,
)
if integrity.state != "current":
raise UnsafePathError(
"Hermes MCP applied-state commit did not observe current state"
)
assert_mcp_integrity_snapshot_current(integrity)
return
if mcp_transition == "preserve":
if not secrets.compare_digest(current_mcp, state.intended):
raise UnsafePathError(
Expand Down
7 changes: 6 additions & 1 deletion src/lib/actions/sandbox/gateway-failure-classifier.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import net from "node:net";

import { dockerInfo } from "../../adapters/docker/info";
import { dockerCapture } from "../../adapters/docker/run";
import { CLI_NAME } from "../../cli/branding";
import { CLI_NAME, getAgentBranding } from "../../cli/branding";
import { GATEWAY_PORT } from "../../core/ports";
import { resolveSandboxContainerOwner } from "../../domain/sandbox/container-owner";
import { resolveGatewayPortFromName } from "../../onboard/gateway-binding";
Expand All @@ -19,6 +19,11 @@ import { getSandboxTargetGatewayName } from "./gateway-target";

const DOCKER_TIMEOUT_MS = 3000;
const PORT_PROBE_TIMEOUT_MS = 2000;

/** Format recovery guidance with the CLI name used for this invocation. */
export function formatGatewayRecoveryCommand(sandboxName: string): string {
return `${getAgentBranding().cli} ${sandboxName} recover`;
}
const portableRuntimeFailures = new Map<
string,
Extract<PortablePodmanReadinessResult, { ok: false }>
Expand Down
41 changes: 41 additions & 0 deletions src/lib/actions/sandbox/mcp-bridge-adapter-hermes-branding.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

const mocks = vi.hoisted(() => ({
isShieldsDown: vi.fn(),
runOpenshellProviderCommand: vi.fn(),
}));

vi.mock("../../adapters/openshell/provider-command", () => ({
runOpenshellProviderCommand: mocks.runOpenshellProviderCommand,
}));

vi.mock("../../shields", () => ({
isShieldsDown: mocks.isShieldsDown,
}));

import { assertHermesMcpMutationRuntimeCapability } from "./mcp-bridge-adapter-hermes";

describe("Hermes MCP recovery guidance", () => {
beforeEach(() => {
vi.stubEnv("NEMOCLAW_INVOKED_AS", "nemohermes");
mocks.isShieldsDown.mockReset().mockReturnValue(true);
mocks.runOpenshellProviderCommand.mockReset().mockReturnValue({
status: 1,
stdout: "",
stderr: "Hermes gateway is not running under the managed service lifecycle",
});
});

afterEach(() => {
vi.unstubAllEnvs();
});

it("uses the invoked CLI name when the managed lifecycle is unavailable", () => {
expect(() => assertHermesMcpMutationRuntimeCapability("alpha")).toThrow(
"Run `nemohermes alpha recover` and retry.",
);
});
});
10 changes: 7 additions & 3 deletions src/lib/actions/sandbox/mcp-bridge-adapter-hermes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,17 @@ import {
type AdapterRegistrationInspection,
inspectAdapterRegistrationCommand,
} from "./mcp-bridge-adapter-inspection";
import { buildHermesMcpStatusCommand, entryHeaders } from "./mcp-bridge-adapter-status";
import {
buildHermesMcpStatusCommand,
entryHeaders,
HERMES_MCP_TRANSACTION_HELPER,
} from "./mcp-bridge-adapter-status";
import { McpBridgeError } from "./mcp-bridge-contracts";
import { commandOutput, redactBridgeSecretsForDisplay } from "./mcp-bridge-output";
import type { McpAttachedCredentialRevision } from "./mcp-bridge-provider-readiness";
import { formatGatewayRecoveryCommand } from "./gateway-failure-classifier";
import { executeGatewaySupervisorAction } from "./process-recovery";

const HERMES_MCP_TRANSACTION_HELPER = "/usr/local/lib/nemoclaw/hermes-mcp-config-transaction.py";
const HERMES_MCP_EXEC_TIMEOUT_SECONDS = 620;
const HERMES_MCP_PROBE_TIMEOUT_SECONDS = 30;
const HERMES_MCP_STARTUP_TIMEOUT_SECONDS = 90;
Expand Down Expand Up @@ -148,7 +152,7 @@ export function assertHermesMcpMutationRuntimeCapability(sandboxName: string): v
if (lastDetail === HERMES_MCP_GATEWAY_NOT_READY) return false;
if (lastDetail === HERMES_MCP_LIFECYCLE_NOT_READY) {
throw new McpBridgeError(
`Hermes sandbox '${sandboxName}' is not running the managed service lifecycle required for authenticated MCP changes. Run \`nemoclaw ${sandboxName} recover\` and retry.`,
`Hermes sandbox '${sandboxName}' is not running the managed service lifecycle required for authenticated MCP changes. Run \`${formatGatewayRecoveryCommand(sandboxName)}\` and retry.`,
);
}
throw new McpBridgeError(
Expand Down
2 changes: 2 additions & 0 deletions src/lib/actions/sandbox/mcp-bridge-adapter-status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ import {
// state can never be layered over the validated registry projection.
export const DEEPAGENTS_MCP_CONFIG_PATH = "/sandbox/.deepagents/.nemoclaw-mcp.json";
export const DEFAULT_OPENCLAW_CONFIG_DIR = "/sandbox/.openclaw";
export const HERMES_MCP_TRANSACTION_HELPER =
"/usr/local/lib/nemoclaw/hermes-mcp-config-transaction.py";

/** Resolve Mcporter's project root beneath an OpenClaw agent configuration directory. */
export function openClawMcporterRoot(configDir = DEFAULT_OPENCLAW_CONFIG_DIR): string {
Expand Down
159 changes: 159 additions & 0 deletions src/lib/actions/sandbox/mcp-bridge-adapter-teardown.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

import { beforeEach, describe, expect, it, vi } from "vitest";

import type { McpBridgeEntry, SandboxEntry } from "../../state/registry";

const mocks = vi.hoisted(() => ({
assertMcpDestroyNotPending: vi.fn(),
bridgeState: vi.fn(),
discardSafeIncompleteMcpAdds: vi.fn(),
ensureSandboxGatewaySelected: vi.fn(),
getBridgeAdapter: vi.fn(),
getSandboxAgent: vi.fn(),
getSandboxOrThrow: vi.fn(),
inspectMcpProvider: vi.fn(),
observeMcpCredentialRevision: vi.fn(),
removeGeneratedPolicy: vi.fn(),
registerAgentAdapter: vi.fn(),
restoreExistingMcpBridgeRuntime: vi.fn(),
unregisterAgentAdapter: vi.fn(),
}));

vi.mock("../../state/registry", () => ({
getSandbox: vi.fn(),
updateSandbox: vi.fn(),
}));

vi.mock("./mcp-bridge-adapters", () => ({
registerAgentAdapter: mocks.registerAgentAdapter,
unregisterAgentAdapter: mocks.unregisterAgentAdapter,
}));

vi.mock("./mcp-bridge-provider-readiness", () => ({
observeMcpCredentialRevision: mocks.observeMcpCredentialRevision,
}));

vi.mock("./mcp-bridge-provider", () => ({
assertMcpProviderRecoverable: vi.fn(),
assertNoProviderCredentialCollisions: vi.fn(),
assertNoRegisteredProviderCredentialCollisions: vi.fn(),
detachProvider: vi.fn(),
inspectMcpProvider: mocks.inspectMcpProvider,
preflightMcpEntryTargets: vi.fn(),
waitForDetachedMcpCredential: vi.fn(),
}));

vi.mock("./mcp-bridge-destroy-preflight", () => ({
cloneMcpBridgeEntry: vi.fn((entry: McpBridgeEntry) => ({ ...entry, env: [...entry.env] })),
discardSafeIncompleteMcpAdds: mocks.discardSafeIncompleteMcpAdds,
inspectExactMcpDestroyProvider: vi.fn(),
}));

vi.mock("./mcp-bridge-policy", () => ({
assertGeneratedPolicyMutationSafe: vi.fn(),
assertGeneratedPolicyRegistrationMutationSafe: vi.fn(),
removeGeneratedPolicy: mocks.removeGeneratedPolicy,
}));

vi.mock("./mcp-bridge-restart", () => ({
restoreExistingMcpBridgeRuntime: mocks.restoreExistingMcpBridgeRuntime,
}));

vi.mock("./mcp-bridge-runtime-capabilities", () => ({
assertMcpAdapterConfigMutationsAllowed: vi.fn(),
assertMcpAdapterTeardownRuntimeCapabilities: vi.fn(),
}));

vi.mock("./mcp-bridge-state", () => ({
assertMcpDestroyNotPending: mocks.assertMcpDestroyNotPending,
bridgeState: mocks.bridgeState,
ensureSandboxGatewaySelected: mocks.ensureSandboxGatewaySelected,
getBridgeAdapter: mocks.getBridgeAdapter,
getSandboxAgent: mocks.getSandboxAgent,
getSandboxOrThrow: mocks.getSandboxOrThrow,
nowIso: vi.fn(() => new Date(0).toISOString()),
setBridgeState: vi.fn(),
}));

vi.mock("./mcp-bridge-validation", () => ({
assertAuthenticatedBridgeEntry: vi.fn(),
validateSandboxName: vi.fn(),
}));

import { prepareMcpBridgesForDestroy } from "./mcp-bridge-destroy";
import { prepareMcpBridgesForRebuild } from "./mcp-bridge-rebuild";
import { scrubManagedMcpAdapterOrThrow } from "./mcp-bridge-adapter-teardown";

const sandbox = { agent: "hermes" } as SandboxEntry;
const entry: McpBridgeEntry = {
server: "github",
agent: "hermes",
adapter: "hermes-config",
url: "https://api.githubcopilot.com/mcp/",
env: ["GITHUB_TOKEN"],
providerName: "alpha-mcp-github",
policyName: "mcp-bridge-github",
addedAt: new Date(0).toISOString(),
};

describe("MCP adapter teardown rollback", () => {
beforeEach(() => {
mocks.bridgeState.mockReset().mockReturnValue({ github: entry });
mocks.discardSafeIncompleteMcpAdds.mockReset().mockResolvedValue(sandbox);
mocks.ensureSandboxGatewaySelected.mockReset().mockResolvedValue(undefined);
mocks.getBridgeAdapter.mockReset().mockReturnValue("hermes-config");
mocks.getSandboxAgent.mockReset().mockReturnValue("hermes");
mocks.getSandboxOrThrow.mockReset().mockReturnValue(sandbox);
mocks.inspectMcpProvider.mockReset().mockReturnValue({ exists: false });
mocks.observeMcpCredentialRevision.mockReset().mockReturnValue("v12");
mocks.removeGeneratedPolicy.mockReset().mockImplementation(() => {
throw new Error("forced lifecycle failure after adapter scrub");
});
mocks.registerAgentAdapter.mockReset();
mocks.restoreExistingMcpBridgeRuntime.mockReset();
mocks.unregisterAgentAdapter.mockReset().mockReturnValue("removed");
});

it.each([
["rebuild", prepareMcpBridgesForRebuild],
["destroy", prepareMcpBridgesForDestroy],
] as const)(
"restores the revision observed before a later %s step fails (#10155)",
async (_lifecycle, prepare) => {
mocks.observeMcpCredentialRevision
.mockReset()
.mockReturnValueOnce("v12")
.mockReturnValueOnce("absent");

await expect(prepare("alpha")).rejects.toThrow(
"forced lifecycle failure after adapter scrub",
);
expect(mocks.unregisterAgentAdapter).toHaveBeenCalledOnce();
expect(mocks.registerAgentAdapter).toHaveBeenCalledWith(
"alpha",
"hermes-config",
expect.objectContaining({ ...entry, credentialRevision: "v12" }),
{},
{
credentialRevision: "v12",
replaceExisting: true,
teardownRollback: true,
},
);
expect(mocks.restoreExistingMcpBridgeRuntime).not.toHaveBeenCalled();
},
);

it("does not scrub Hermes when no attached revision can be proved", () => {
mocks.observeMcpCredentialRevision.mockReturnValue("absent");

expect(() => scrubManagedMcpAdapterOrThrow("alpha", sandbox, entry)).toThrow(
"Could not prove a revision-scoped credential before removing the managed adapter entry for MCP server 'github'.",
);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
expect(mocks.inspectMcpProvider).toHaveBeenCalledWith("alpha-mcp-github");
expect(mocks.unregisterAgentAdapter).not.toHaveBeenCalled();
expect(mocks.registerAgentAdapter).not.toHaveBeenCalled();
});
});
6 changes: 4 additions & 2 deletions src/lib/actions/sandbox/mcp-bridge-hermes-reconciliation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,15 @@ import { runOpenshellProviderCommand } from "../../adapters/openshell/provider-c
import { redactFull } from "../../security/redact";
import type { McpBridgeEntry, SandboxEntry } from "../../state/registry";
import * as registry from "../../state/registry";
import { buildHermesMcpIntentPayload } from "./mcp-bridge-adapter-status";
import {
buildHermesMcpIntentPayload,
HERMES_MCP_TRANSACTION_HELPER,
} from "./mcp-bridge-adapter-status";
import { McpBridgeError } from "./mcp-bridge-contracts";
import { redactBridgeSecretsForDisplay } from "./mcp-bridge-output";
import type { McpAttachedCredentialRevision } from "./mcp-bridge-provider-readiness";
import { sleepMcpBridgeRetry } from "./mcp-bridge/timing";

const HERMES_MCP_TRANSACTION_HELPER = "/usr/local/lib/nemoclaw/hermes-mcp-config-transaction.py";
const HERMES_MCP_INSPECT_TIMEOUT_SECONDS = 45;
const HERMES_MCP_INSPECT_TIMEOUT_MS = 60_000;
const HERMES_MCP_RECONCILIATION_FAILURE =
Expand Down
57 changes: 57 additions & 0 deletions test/agents/hermes/hermes-mcp-integrity-state.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -313,6 +313,63 @@ print(json.dumps({
});
});

it("validates but does not replace already-current applied-state anchors", () => {
const result = spawnSync(
"python3",
[
"-I",
"-c",
String.raw`
import importlib.util, json, os, sys, tempfile
spec = importlib.util.spec_from_file_location("hermes_guard", sys.argv[1])
guard = importlib.util.module_from_spec(spec)
sys.modules[spec.name] = guard
spec.loader.exec_module(guard)
root = tempfile.mkdtemp(prefix="hermes-mcp-current-apply-")
hermes = os.path.join(root, ".hermes")
os.mkdir(hermes)
config = os.path.join(hermes, "config.yaml")
env = os.path.join(hermes, ".env")
strict = os.path.join(root, "hermes.config-hash")
compat = os.path.join(hermes, ".config-hash")
open(config, "w", encoding="utf-8").write("model: test\n")
open(env, "w", encoding="utf-8").write("SAFE=1\n")
hash_text, _config_snapshot, _env_snapshot = guard._hash_text(config, env)
guard._write_hash(strict, hash_text)
guard._write_hash(compat, hash_text)
before = {path: os.stat(path).st_ino for path in (strict, compat)}
writes = []
original_write_hash = guard._write_hash

def captured_write_hash(path, text):
writes.append(path)
original_write_hash(path, text)

guard._write_hash = captured_write_hash
guard.refresh_hashes(hermes, strict, "both", mcp_transition="apply")
guard.refresh_hashes(hermes, strict, "compat", mcp_transition="apply")
after = {path: os.stat(path).st_ino for path in (strict, compat)}
print(json.dumps({
"state": guard.inspect_mcp_integrity(hermes, strict),
"writes": writes,
"strict_inode_stable": before[strict] == after[strict],
"compat_inode_stable": before[compat] == after[compat],
}))
`,
GUARD,
],
{ encoding: "utf-8", timeout: 10_000 },
);

expect(result.status, result.stderr).toBe(0);
expect(JSON.parse(result.stdout)).toEqual({
state: "current",
writes: [],
strict_inode_stable: true,
compat_inode_stable: true,
});
});

it("runs startup-owned MCP inspection as a direct child", () => {
const source = fs.readFileSync(START, "utf-8");
const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-hermes-mcp-parent-"));
Expand Down
Loading