docs: document command session tests

steipete · steipete · commit 17fc1c430fed · 2026-06-04T14:14:07.000-04:00
diff --git a/src/agents/command/cli-compaction.test.ts b/src/agents/command/cli-compaction.test.ts
@@ -1,3 +1,4 @@
+// Covers CLI turn compaction lifecycle and external CLI resume-state cleanup.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -42,6 +43,8 @@ function buildContextEngine(params: {
 }
 
 async function writeSessionFile(params: { sessionFile: string; sessionId: string }) {
+  // The lifecycle compacts canonical OpenClaw session JSONL, so tests write the
+  // same session/message envelope the real store appends.
   await fs.mkdir(path.dirname(params.sessionFile), { recursive: true });
   await fs.writeFile(
     params.sessionFile,
@@ -116,6 +119,8 @@ describe("runCliTurnCompactionLifecycle", () => {
     const compactCalls: Array<Parameters<ContextEngine["compact"]>[0]> = [];
     const maintenance = vi.fn(async () => ({ changed: false, bytesFreed: 0, rewrittenEntries: 0 }));
     const settingsCwds: string[] = [];
+    // Compaction settings should be resolved against the task cwd, not the
+    // bootstrap workspace, because CLI prompts may run from nested repos.
     setCliCompactionTestDeps({
       resolveContextEngine: async () => buildContextEngine({ compactCalls }),
       createPreparedEmbeddedAgentSettingsManager: async (params) => {
@@ -183,6 +188,8 @@ describe("runCliTurnCompactionLifecycle", () => {
     expect(maintenanceCall?.sessionKey).toBe(sessionKey);
     expect(maintenanceCall?.sessionFile).toBe(sessionFile);
     expect(updatedEntry?.compactionCount).toBe(1);
+    // Once OpenClaw rewrites the transcript, external CLI resume ids are stale
+    // and must be cleared so the next turn starts from the compacted prompt.
     expect(updatedEntry?.cliSessionBindings?.["claude-cli"]).toBeUndefined();
     expect(updatedEntry?.cliSessionIds?.["claude-cli"]).toBeUndefined();
     expect(updatedEntry?.claudeCliSessionId).toBeUndefined();
diff --git a/src/agents/command/delivery.test.ts b/src/agents/command/delivery.test.ts
@@ -1,3 +1,4 @@
+// Covers agent-command reply normalization and outbound delivery status.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import type { ChannelOutboundAdapter } from "../../channels/plugins/types.js";
@@ -46,6 +47,8 @@ const slackOutboundForTest: ChannelOutboundAdapter = {
   }),
 };
 
+// Two registries let tests switch between no-channel and Slack-capable delivery
+// without loading the full plugin runtime.
 const emptyRegistry = createTestRegistry([]);
 const slackRegistry = createTestRegistry([
   {
@@ -172,6 +175,8 @@ async function deliverMediaReplyForTest(
   outboundSession: DeliverParams["outboundSession"],
   optsOverrides: Partial<AgentCommandOpts> = {},
 ) {
+  // Media replies go through the same normalizer seam as production so relative
+  // paths are interpreted with agent/session context before delivery.
   const runtime = { log: vi.fn(), error: vi.fn() };
   return await deliverAgentCommandResult({
     cfg: {
@@ -213,6 +218,8 @@ describe("normalizeAgentCommandReplyPayloads", () => {
   });
 
   it("keeps Slack directives in text for direct agent deliveries", () => {
+    // Direct CLI deliveries preserve Slack directive markup because no channel
+    // adapter has consumed it yet.
     const normalized = normalizeAgentCommandReplyPayloads({
       cfg: {
         channels: {
diff --git a/src/agents/command/session-store.test.ts b/src/agents/command/session-store.test.ts
@@ -1,3 +1,5 @@
+// Covers command-session store updates after agent runs, CLI compaction, and
+// runtime metadata persistence.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -99,6 +101,8 @@ vi.mock("../../config/sessions.js", async () => {
           .map(([key, entry]) => [key, entry.acp]),
       );
       const result = await mutator(store);
+      // The mocked store keeps ACP metadata sticky to preserve the production
+      // merge behavior that protects persistent ACP session handles.
       for (const [key, acp] of previousAcpByKey) {
         const next = store[key];
         if (next && !next.acp) {
@@ -155,6 +159,8 @@ function acpMeta() {
 async function withTempSessionStore<T>(
   run: (params: { dir: string; storePath: string }) => Promise<T>,
 ): Promise<T> {
+  // Session-store tests exercise real JSON persistence, but each case gets an
+  // isolated file so mutation order remains deterministic.
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-session-store-"));
   try {
     return await run({ dir, storePath: path.join(dir, "sessions.json") });
@@ -206,6 +212,8 @@ describe("updateSessionStoreAfterAgentRun", () => {
         result,
       });
 
+      // The gateway write takes cache ownership and supplies single-entry
+      // persistence so large stores are not rewritten unnecessarily.
       const updateOptions = sessionStoreMocks.updateSessionStore.mock.calls.at(-1)?.[2];
       expect(updateOptions).toMatchObject({
         takeCacheOwnership: true,
diff --git a/src/agents/command/session.resolve-session-key.test.ts b/src/agents/command/session.resolve-session-key.test.ts
@@ -1,3 +1,4 @@
+// Covers cross-store session-key resolution for multi-agent session stores.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import type { SessionEntry } from "../../config/sessions/types.js";
@@ -32,6 +33,8 @@ const { resolveSessionKeyForRequest, resolveStoredSessionKeyForSessionId } =
   await import("./session.js");
 
 function mockSessionStores(storesByPath: Record<string, Record<string, SessionEntry>>): void {
+  // Store paths are the routing boundary here; returning the exact object lets
+  // tests assert whether callers borrowed or cloned the selected store.
   hoisted.loadSessionStoreMock.mockImplementation((storePath) => storesByPath[storePath] ?? {});
 }
 
@@ -83,6 +86,8 @@ describe("resolveSessionKeyForRequest", () => {
   });
 
   it("keeps a cross-store structural winner over a newer local fuzzy duplicate", () => {
+    // Structural keys beat fuzzy timestamp matches so ACP/subagent resumes do
+    // not accidentally attach to a newer generic main-session duplicate.
     const mainStore = {
       "agent:main:main": { sessionId: "sid", updatedAt: 20 },
     } satisfies Record<string, SessionEntry>;
@@ -131,6 +136,8 @@ describe("resolveSessionKeyForRequest", () => {
   });
 
   it("borrows session stores when requested", () => {
+    // clone=false is used by callers that intend to mutate the selected store,
+    // so the resolver must pass that option through every candidate load.
     const mainStore = {
       "agent:main:main": { sessionId: "sid", updatedAt: 10 },
     } satisfies Record<string, SessionEntry>;
