Skip to content
2 changes: 1 addition & 1 deletion ci/source-architecture-budget.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
"src/lib/cli/terminal-style.ts": 43,
"src/lib/core/json-types.ts": 37,
"src/lib/core/ports.ts": 87,
"src/lib/core/shell-quote.ts": 27,
"src/lib/core/shell-quote.ts": 28,
"src/lib/core/url-utils.ts": 28,
"src/lib/core/wait.ts": 35,
"src/lib/credentials/store.ts": 46,
Expand Down
11 changes: 9 additions & 2 deletions docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2582,7 +2582,11 @@ With `--channel`, it prints the detailed status for that channel.
For an OpenClaw WhatsApp sandbox, `--channel whatsapp` probes the sandbox to separately report pairing/session state, the Noise WebSocket connection, inbound event delivery, and policy coverage.
A paired channel with no observed inbound delivery exits non-zero with verdict `idle` so an unhealthy bridge cannot pass as healthy.
The detailed WhatsApp probe stays focused on QR/session runtime diagnostics and does not include rendered-config comparison lines.
For a Hermes WhatsApp sandbox, `--channel whatsapp` probes only whether the default gateway session path and the `profiles/dashboard-home` session path contain `creds.json`.
For a Hermes WhatsApp sandbox, `--channel whatsapp` first checks the shared gateway path and the `profiles/dashboard-home` path for `creds.json`.
If the shared gateway path is empty, NemoClaw reads only `platforms.whatsapp.extra.session_path` from `/sandbox/.hermes/config.yaml`.
NemoClaw accepts an absolute configured path under `/sandbox/.hermes` that has no `.` or `..` segment.
After validation, the command checks the configured path and reports a `Session path override` signal.
An unsupported path produces a warning, and the report uses the default gateway path.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
If the dashboard path has credentials and the gateway path is empty, the report tells you to run `$$nemoclaw <sandbox> channels remove whatsapp` and then `$$nemoclaw <sandbox> channels add whatsapp`, because a rebuild restores the legacy session instead of dropping it.
Pair again from the dashboard so credentials use `/sandbox/.hermes/platforms/whatsapp/session`.
Rerun `$$nemoclaw <sandbox> channels status --channel whatsapp`.
Expand Down Expand Up @@ -2625,7 +2629,10 @@ $$nemoclaw my-assistant channels status --channel slack --wait --timeout 180 --j

Each live probe is bounded by an in-sandbox `openshell sandbox exec` with a hard timeout.
The WhatsApp probe returns strict OpenClaw status JSON to the host, where NemoClaw allowlists pairing, liveness, connection-state, and timestamp fields before rendering the report and discards phone-number and free-text error fields.
The Hermes WhatsApp probe returns only fixed session-path booleans to the host.
The Hermes WhatsApp probe returns fixed session-presence booleans to the host.
When the shared gateway path is empty, a sandbox-local parser can also return the configured WhatsApp session path.
The parser does not return other Hermes configuration values.
NemoClaw validates the path before it uses the path in a second session-presence probe.
The Telegram probe returns only matched gateway log lines to the host, where NemoClaw reduces them to fixed classifications without rendering the raw lines, message bodies, or tokens.
The Slack probe returns OpenClaw status JSON to the host.
NemoClaw reduces it to allowlisted account booleans, credential availability, probe success, fixed error categories, and timestamps; the rendered and JSON readiness reports omit tokens and free-text errors.
Expand Down
82 changes: 82 additions & 0 deletions src/lib/actions/sandbox/channel-status.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,36 @@ function hermesSessionProbeOutput(options: {
].join("\n");
}

const HERMES_DEFAULT_SESSION_DIR = "/sandbox/.hermes/platforms/whatsapp/session";
const HERMES_DASHBOARD_SESSION_DIR =
"/sandbox/.hermes/profiles/dashboard-home/platforms/whatsapp/session";

function hermesExec(options: {
readonly configuredSessionPath?: string;
readonly credsDirs: readonly string[];
}) {
const hasCreds = (credsFile: string) =>
options.credsDirs.some((dir) => credsFile === `${dir}/creds.json`);
return vi.fn((_sandbox: string, command: string, _timeoutMs?: number) => {
return command.startsWith("python3 -c ")
? options.configuredSessionPath === undefined
? { status: 1, stdout: "", stderr: "config unavailable" }
: {
status: 0,
stdout: `NEMOCLAW_HERMES_WHATSAPP_CONFIG_V1\n${JSON.stringify(options.configuredSessionPath)}`,
stderr: "",
}
: {
status: 0,
stdout: hermesSessionProbeOutput({
gatewaySessionCreds: hasCreds(/gateway='([^']*)'/.exec(command)?.[1] ?? ""),
dashboardSessionCreds: hasCreds(/dashboard='([^']*)'/.exec(command)?.[1] ?? ""),
}),
stderr: "",
};
});
}

describe("showSandboxChannelStatus (whatsapp)", () => {
it("returns idle verdict and exit code 1 when paired but no inbound observed", async () => {
const stdout = waStatusJson({
Expand Down Expand Up @@ -286,6 +316,58 @@ describe("showSandboxChannelStatus (whatsapp)", () => {
expect(session?.severity).toBe("ok");
});

it("clears the session-path split after the documented session_path repair (#8718)", async () => {
const exec = hermesExec({
configuredSessionPath: HERMES_DASHBOARD_SESSION_DIR,
credsDirs: [HERMES_DASHBOARD_SESSION_DIR],
});
const { deps, out_lines } = makeDeps({
exec,
agentName: "hermes",
sandbox: entry(["whatsapp"], [], {}, "hermes"),
});
const result = await showSandboxChannelStatus("alpha", { deps, channel: "whatsapp" });
const signals = result && "report" in result ? result.report.signals : [];
const dump = out_lines.join("\n");
expect(result && "report" in result && result.report.verdict).not.toBe("unpaired");
expect(signals.find((signal) => signal.label === "Session location")?.severity).toBe("ok");
expect(signals.find((signal) => signal.label === "Session path override")?.severity).toBe(
"info",
);
expect(dump).not.toContain("the Hermes gateway session path is empty");
expect(dump).toContain(HERMES_DASHBOARD_SESSION_DIR);
expect(exec.mock.calls.map((call) => String(call[1] ?? "")).join("\n")).toContain(
`gateway='${HERMES_DASHBOARD_SESSION_DIR}/creds.json'`,
);
Comment thread
apurvvkumaria marked this conversation as resolved.
Resolved
});

it("keeps the default session path when the configured session path is unsupported (#8718)", async () => {
const exec = hermesExec({
configuredSessionPath: "/etc/hermes/session",
credsDirs: [HERMES_DASHBOARD_SESSION_DIR],
});
const exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
throw new Error(`process.exit(${code})`);
}) as never);
const { deps } = makeDeps({
exec,
agentName: "hermes",
sandbox: entry(["whatsapp"], [], {}, "hermes"),
});
let threw: Error | null = null;
try {
await showSandboxChannelStatus("alpha", { deps, channel: "whatsapp" });
} catch (err) {
threw = err as Error;
} finally {
exitSpy.mockRestore();
}
const commands = exec.mock.calls.map((call) => String(call[1] ?? "")).join("\n");
expect(threw?.message).toBe("process.exit(1)");
expect(commands).toContain(`gateway='${HERMES_DEFAULT_SESSION_DIR}/creds.json'`);
expect(commands).not.toContain("/etc/hermes/session");
});

it("skips the deep probe and reports paused state when WhatsApp is in disabledChannels", async () => {
// Regression guard: `channels stop whatsapp` deliberately drops the
// bridge and preset until the operator runs `channels start`. The
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,71 @@ describe("evaluateWhatsappDiagnostics", () => {
expect(session?.hint).toBe("use one active WhatsApp bridge for the paired account");
});

it("accepts credentials found through the configured session path (#8718)", () => {
const report = evaluateWhatsappDiagnostics(
baseInput({
agent: "hermes",
paired: null,
sessionLocations: {
gatewaySessionCreds: true,
dashboardSessionCreds: true,
gatewaySessionPathSource: "config",
},
}),
);
const session = report.signals.find((s) => s.label === "Session location");
const override = report.signals.find((s) => s.label === "Session path override");
expect(report.verdict).toBe("unknown");
expect(session?.severity).toBe("ok");
expect(session?.detail).toBe(
"the configured Hermes WhatsApp session path contains credentials",
);
expect(override?.severity).toBe("info");
expect(override?.detail).toContain("platforms.whatsapp.extra.session_path");
});

it("stops repeating the repair command when the configured session path is empty (#8718)", () => {
const report = evaluateWhatsappDiagnostics(
baseInput({
agent: "hermes",
paired: false,
sessionLocations: {
gatewaySessionCreds: false,
dashboardSessionCreds: true,
gatewaySessionPathSource: "config",
},
}),
);
const session = report.signals.find((s) => s.label === "Session location");
expect(report.verdict).toBe("unpaired");
expect(session?.severity).toBe("warn");
expect(session?.detail).toBe(
"the configured Hermes WhatsApp session path has no WhatsApp credentials",
);
expect(report.hints.join(" ")).not.toContain("--config-accept-new-path");
expect(report.hints.join(" ")).toContain("hermes whatsapp");
});

it("warns when the configured session path is not a supported sandbox path (#8718)", () => {
const report = evaluateWhatsappDiagnostics(
baseInput({
agent: "hermes",
paired: false,
sessionLocations: {
gatewaySessionCreds: false,
dashboardSessionCreds: true,
gatewaySessionPathSource: "unsupported",
},
}),
);
const session = report.signals.find((s) => s.label === "Session location");
const override = report.signals.find((s) => s.label === "Session path override");
expect(session?.severity).toBe("warn");
expect(session?.detail).toMatch(/dashboard-home has WhatsApp credentials/);
expect(override?.severity).toBe("warn");
expect(override?.detail).toContain("not a supported session path");
});

it("returns idle when paired with a live WebSocket but no inbound event observed", () => {
// This is the exact #4386 shape: pairing is fine, WebSocket is up, but
// lastInboundAt is still null. We MUST NOT report this as healthy.
Expand Down
47 changes: 46 additions & 1 deletion src/lib/messaging/channels/whatsapp/hooks/status-health-eval.ts
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,8 @@ export type WhatsappProbeInput = {
export type WhatsappSessionLocations = {
gatewaySessionCreds: boolean | null;
dashboardSessionCreds: boolean | null;
gatewaySessionPathSource?: "default" | "config" | "unsupported";
gatewaySessionDir?: string;
};

/**
Expand Down Expand Up @@ -186,7 +188,8 @@ function hermesDashboardOnlySession(input: WhatsappProbeInput): boolean {
return (
input.agent === "hermes" &&
input.sessionLocations?.gatewaySessionCreds === false &&
input.sessionLocations.dashboardSessionCreds === true
input.sessionLocations.dashboardSessionCreds === true &&
input.sessionLocations.gatewaySessionPathSource !== "config"
);
}

Expand All @@ -195,6 +198,23 @@ function sessionLocationSignal(input: WhatsappProbeInput): DiagnosticSignal | nu
if (!locations) return null;
const gateway = locations.gatewaySessionCreds;
const dashboard = locations.dashboardSessionCreds;
if (locations.gatewaySessionPathSource === "config" && gateway !== null) {
const configuredPath = locations.gatewaySessionDir
? ` at \`${locations.gatewaySessionDir}\``
: "";
return gateway
? {
label: "Session location",
severity: "ok",
detail: `the configured Hermes WhatsApp session path${configuredPath} contains credentials`,
}
: {
label: "Session location",
severity: "warn",
detail: `the configured Hermes WhatsApp session path${configuredPath} has no WhatsApp credentials`,
hint: "pair WhatsApp again, or set `platforms.whatsapp.extra.session_path` to the session path that holds the credentials",
};
}
if (gateway === false && dashboard === true) {
return {
label: "Session location",
Expand Down Expand Up @@ -233,6 +253,29 @@ function sessionLocationSignal(input: WhatsappProbeInput): DiagnosticSignal | nu
};
}

function sessionPathOverrideSignal(input: WhatsappProbeInput): DiagnosticSignal | null {
const source = input.sessionLocations?.gatewaySessionPathSource;
if (source === "config") {
return {
label: "Session path override",
severity: "info",
detail:
"the gateway session check used the path set in `platforms.whatsapp.extra.session_path`",
hint: "remove the override after Hermes uses one WhatsApp session path for dashboard pairing and gateway startup",
};
}
if (source === "unsupported") {
return {
label: "Session path override",
severity: "warn",
detail:
"`platforms.whatsapp.extra.session_path` is not a supported session path, so the gateway session check used the default path",
hint: "set `platforms.whatsapp.extra.session_path` to an absolute path under `/sandbox/.hermes` that has no `.` or `..` segment",
};
}
return null;
}

function websocketSignal(input: WhatsappProbeInput): DiagnosticSignal {
if (input.heartbeatParseError) {
return {
Expand Down Expand Up @@ -513,10 +556,12 @@ function buildHints(verdict: WhatsappVerdict, input: WhatsappProbeInput): string

export function evaluateWhatsappDiagnostics(input: WhatsappProbeInput): WhatsappDiagnosticReport {
const sessionSignal = sessionLocationSignal(input);
const overrideSignal = sessionPathOverrideSignal(input);
const signals: DiagnosticSignal[] = [
configCoverageSignal(input),
pairingSignal(input),
...(sessionSignal ? [sessionSignal] : []),
...(overrideSignal ? [overrideSignal] : []),
bridgeProcessSignal(input),
websocketSignal(input),
inboundSignal(input),
Expand Down
Loading
Loading