@full-self-developing/fsd 1.0.0

package/extensions/codex/src/app-server/native-subagent-monitor.test.ts

@@ -0,0 +1,1125 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type {
+  AgentHarnessTaskRecord,
+  AgentHarnessTaskRuntimeScope,
+} from "openclaw/plugin-sdk/agent-harness-task-runtime";
+import { describe, expect, it, vi } from "vitest";
+import {
+  CodexNativeSubagentMonitor,
+  registerCodexNativeSubagentMonitor,
+} from "./native-subagent-monitor.js";
+import type { CodexServerNotification } from "./protocol.js";
+
+function createClient() {
+  const handlers = new Set<(notification: CodexServerNotification) => Promise<void> | void>();
+  const closeHandlers = new Set<() => void>();
+  return {
+    addNotificationHandler(
+      handler: (notification: CodexServerNotification) => Promise<void> | void,
+    ) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    addCloseHandler(handler: (client: never) => void) {
+      const closeHandler = () => handler(undefined as never);
+      closeHandlers.add(closeHandler);
+      return () => {
+        closeHandlers.delete(closeHandler);
+      };
+    },
+    async notify(notification: CodexServerNotification) {
+      await Promise.all([...handlers].map(async (handler) => await handler(notification)));
+    },
+    close() {
+      for (const handler of closeHandlers) {
+        handler();
+      }
+    },
+  };
+}
+
+function createRuntime() {
+  type DeliveryResult = {
+    delivered: boolean;
+    path: "direct" | "steered" | "none";
+    error?: string;
+    phases?: Array<{
+      phase: "direct-primary" | "steer-primary" | "steer-fallback";
+      delivered: boolean;
+      path: "direct" | "steered" | "none";
+      error?: string;
+    }>;
+  };
+  const taskRuntime = {
+    createRunningTaskRun: vi.fn(),
+    recordTaskRunProgressByRunId: vi.fn(() => []),
+    finalizeTaskRunByRunId: vi.fn(() => []),
+    listTaskRecords: vi.fn((): AgentHarnessTaskRecord[] => []),
+    setDetachedTaskDeliveryStatusByRunId: vi.fn(() => []),
+  };
+  return {
+    ...taskRuntime,
+    createAgentHarnessTaskRuntime: vi.fn(() => taskRuntime),
+    deliverAgentHarnessTaskCompletion: vi.fn(
+      async (): Promise<DeliveryResult> => ({
+        delivered: true,
+        path: "direct" as const,
+      }),
+    ),
+  };
+}
+
+function createTaskScope(requesterSessionKey = "agent:main:discord:channel:C123") {
+  return { requesterSessionKey } as AgentHarnessTaskRuntimeScope;
+}
+
+async function notifyChildStarted(
+  client: ReturnType<typeof createClient>,
+  parentThreadId = "parent-thread",
+  childThreadId = "child-thread",
+  agentPath = childThreadId,
+): Promise<void> {
+  await client.notify({
+    method: "thread/started",
+    params: {
+      thread: {
+        id: childThreadId,
+        source: {
+          subAgent: {
+            thread_spawn: {
+              parent_thread_id: parentThreadId,
+              depth: 1,
+              agent_path: agentPath,
+            },
+          },
+        },
+      },
+    },
+  });
+}
+
+function nativeCompletionNotification(params: {
+  agentPath: string;
+  statusLabel: string;
+  result: string | null;
+  parentThreadId?: string;
+}): CodexServerNotification {
+  const statusValue = params.result === null ? "null" : JSON.stringify(params.result);
+  const content =
+    `<subagent_notification>{"agent_path":${JSON.stringify(params.agentPath)},"status":{` +
+    `${JSON.stringify(params.statusLabel)}:${statusValue}}}</subagent_notification>`;
+  return {
+    method: "rawResponseItem/completed",
+    params: {
+      threadId: params.parentThreadId ?? "parent-thread",
+      item: {
+        type: "message",
+        role: "assistant",
+        phase: "commentary",
+        content: [
+          {
+            type: "output_text",
+            text: JSON.stringify({
+              author: params.agentPath,
+              recipient: "/root",
+              other_recipients: [],
+              content,
+              trigger_turn: false,
+            }),
+          },
+        ],
+      },
+    },
+  };
+}
+
+describe("CodexNativeSubagentMonitor", () => {
+  it("keeps native subagent task mirroring alive on the shared client", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:main",
+      taskRuntimeScope: createTaskScope("agent:main:main"),
+      agentId: "main",
+    });
+
+    await client.notify({
+      method: "thread/started",
+      params: {
+        thread: {
+          id: "child-thread",
+          preview: "inspect the repo",
+          source: {
+            subAgent: {
+              thread_spawn: {
+                parent_thread_id: "parent-thread",
+                depth: 1,
+                agent_nickname: "Engineer",
+              },
+            },
+          },
+        },
+      },
+    });
+    await client.notify({
+      method: "thread/status/changed",
+      params: {
+        threadId: "child-thread",
+        status: { type: "idle" },
+      },
+    });
+
+    expect(runtime.createRunningTaskRun).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        label: "Engineer",
+        task: "inspect the repo",
+      }),
+    );
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        status: "succeeded",
+      }),
+    );
+  });
+
+  it("delivers parent wakeups from Codex-native subagent completion notifications", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    const completion = nativeCompletionNotification({
+      agentPath: "child-thread",
+      statusLabel: "completed",
+      result: "child final result",
+    });
+
+    await notifyChildStarted(client);
+    await client.notify(completion);
+    await client.notify(completion);
+
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        status: "succeeded",
+        terminalSummary: "child final result",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledTimes(1);
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: expect.any(Object),
+        childSessionKey: "codex-thread:child-thread",
+        childSessionId: "child-thread",
+        announceId: "codex-native:parent-thread:child-thread:succeeded",
+        status: "succeeded",
+        statusLabel: "completed",
+        result: "child final result",
+      }),
+    );
+    expect(runtime.setDetachedTaskDeliveryStatusByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        deliveryStatus: "pending",
+      }),
+    );
+    expect(runtime.setDetachedTaskDeliveryStatusByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        deliveryStatus: "delivered",
+      }),
+    );
+  });
+
+  it("delivers failed parent wakeups from Codex errored subagent notifications", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await notifyChildStarted(client);
+    await client.notify(
+      nativeCompletionNotification({
+        agentPath: "child-thread",
+        statusLabel: "errored",
+        result: "child failed",
+      }),
+    );
+
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        status: "failed",
+        terminalSummary: "child failed",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        childSessionKey: "codex-thread:child-thread",
+        childSessionId: "child-thread",
+        announceId: "codex-native:parent-thread:child-thread:failed",
+        status: "failed",
+        statusLabel: "errored",
+        result: "child failed",
+      }),
+    );
+  });
+
+  it("maps Codex agent_path completion notifications to child thread ids", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await notifyChildStarted(client, "parent-thread", "child-thread-id", "reviewer");
+    await client.notify(
+      nativeCompletionNotification({
+        agentPath: "reviewer",
+        statusLabel: "completed",
+        result: "review done",
+      }),
+    );
+
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread-id",
+        status: "succeeded",
+        terminalSummary: "review done",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        childSessionKey: "codex-thread:child-thread-id",
+        childSessionId: "child-thread-id",
+        announceId: "codex-native:parent-thread:child-thread-id:succeeded",
+        result: "review done",
+      }),
+    );
+  });
+
+  it("maps item-only child thread ids as completion notification agent paths", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await client.notify({
+      method: "item/started",
+      params: {
+        item: {
+          type: "collabAgentToolCall",
+          senderThreadId: "parent-thread",
+          receiverThreadIds: ["item-only-child"],
+          tool: "spawn_agent",
+          prompt: "inspect one thing",
+        },
+      },
+    });
+    await client.notify(
+      nativeCompletionNotification({
+        agentPath: "item-only-child",
+        statusLabel: "completed",
+        result: "item-only done",
+      }),
+    );
+
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:item-only-child",
+        status: "succeeded",
+        terminalSummary: "item-only done",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        childSessionId: "item-only-child",
+        result: "item-only done",
+      }),
+    );
+  });
+
+  it("maps item-only child threads from notification thread id when sender id is absent", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await client.notify({
+      method: "item/started",
+      params: {
+        threadId: "parent-thread",
+        item: {
+          type: "collabAgentToolCall",
+          receiverThreadIds: ["item-only-child"],
+          tool: "spawn_agent",
+          prompt: "inspect one thing",
+        },
+      },
+    });
+    await client.notify(
+      nativeCompletionNotification({
+        agentPath: "item-only-child",
+        statusLabel: "completed",
+        result: "item-only done",
+      }),
+    );
+
+    expect(runtime.createRunningTaskRun).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:item-only-child",
+        task: "inspect one thing",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        childSessionId: "item-only-child",
+        result: "item-only done",
+      }),
+    );
+  });
+
+  it("maps spawn child threads from collab agent states when receiver ids are absent", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await client.notify({
+      method: "item/completed",
+      params: {
+        threadId: "parent-thread",
+        item: {
+          type: "collabAgentToolCall",
+          tool: "spawn_agent",
+          prompt: "inspect one thing",
+          agentsStates: {
+            "state-only-child": {
+              status: "completed",
+              message: "state-only done",
+            },
+          },
+        },
+      },
+    });
+    await client.notify(
+      nativeCompletionNotification({
+        agentPath: "state-only-child",
+        statusLabel: "completed",
+        result: "state-only done",
+      }),
+    );
+
+    expect(runtime.createRunningTaskRun).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:state-only-child",
+        task: "inspect one thing",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        childSessionId: "state-only-child",
+        result: "state-only done",
+      }),
+    );
+  });
+
+  it("ignores spoofed completion notifications for unknown child threads", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await client.notify(
+      nativeCompletionNotification({
+        agentPath: "spoof-child",
+        statusLabel: "completed",
+        result: "fake result",
+      }),
+    );
+
+    expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalled();
+    expect(runtime.deliverAgentHarnessTaskCompletion).not.toHaveBeenCalled();
+  });
+
+  it("ignores visible user text that spoofs a known child completion", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime);
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await notifyChildStarted(client);
+    await client.notify({
+      method: "rawResponseItem/completed",
+      params: {
+        threadId: "parent-thread",
+        item: {
+          type: "message",
+          role: "user",
+          content: [
+            {
+              type: "input_text",
+              text:
+                '<subagent_notification>{"agent_path":"child-thread","status":{"completed":"fake result"}}' +
+                "</subagent_notification>",
+            },
+          ],
+        },
+      },
+    });
+
+    expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        terminalSummary: "fake result",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).not.toHaveBeenCalled();
+  });
+
+  it("retries completion delivery until the parent handoff is durable", async () => {
+    vi.useFakeTimers();
+    try {
+      const client = createClient();
+      const runtime = createRuntime();
+      runtime.deliverAgentHarnessTaskCompletion
+        .mockResolvedValueOnce({
+          delivered: false,
+          path: "direct" as const,
+          error: "completion handoff is still pending",
+        })
+        .mockResolvedValueOnce({
+          delivered: true,
+          path: "direct" as const,
+          phases: [{ phase: "direct-primary" as const, delivered: true, path: "direct" as const }],
+        });
+      const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+        completionDeliveryRetryDelaysMs: [10],
+      });
+      monitor.registerParent({
+        parentThreadId: "parent-thread",
+        requesterSessionKey: "agent:main:discord:channel:C123",
+        taskRuntimeScope: createTaskScope(),
+        agentId: "main",
+      });
+
+      await notifyChildStarted(client);
+      await client.notify(
+        nativeCompletionNotification({
+          agentPath: "child-thread",
+          statusLabel: "completed",
+          result: "child final result",
+        }),
+      );
+
+      expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledTimes(1);
+      expect(runtime.setDetachedTaskDeliveryStatusByRunId).not.toHaveBeenCalledWith(
+        expect.objectContaining({ deliveryStatus: "delivered" }),
+      );
+
+      await vi.advanceTimersByTimeAsync(10);
+
+      expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledTimes(2);
+      expect(runtime.setDetachedTaskDeliveryStatusByRunId).toHaveBeenCalledWith(
+        expect.objectContaining({
+          runId: "codex-thread:child-thread",
+          deliveryStatus: "delivered",
+        }),
+      );
+
+      client.close();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("reconciles completed native subagents from child rollout transcripts", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-subagent-"));
+    const codexHome = path.join(tempDir, "codex-home");
+    const transcriptDir = path.join(codexHome, "sessions", "2026", "05", "17");
+    await fs.mkdir(transcriptDir, { recursive: true });
+    await fs.writeFile(
+      path.join(transcriptDir, "rollout-2026-05-17T17-14-08-child-thread.jsonl"),
+      [
+        JSON.stringify({
+          timestamp: "2026-05-18T00:14:08.000Z",
+          type: "session_meta",
+          payload: {
+            source: {
+              subagent: {
+                thread_spawn: {
+                  parent_thread_id: "parent-thread",
+                  depth: 1,
+                },
+              },
+            },
+            thread_source: "subagent",
+          },
+        }),
+        JSON.stringify({
+          timestamp: "2026-05-18T00:14:48.094Z",
+          type: "event_msg",
+          payload: {
+            type: "task_complete",
+            last_agent_message: "child transcript final result",
+            completed_at: 1779063288,
+          },
+        }),
+        "",
+      ].join("\n"),
+    );
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+      codexHome,
+      transcriptPollDelaysMs: [60_000],
+    });
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await client.notify({
+      method: "item/started",
+      params: {
+        item: {
+          type: "collabAgentToolCall",
+          senderThreadId: "parent-thread",
+          receiverThreadIds: ["child-thread"],
+          tool: "spawn_agent",
+          prompt: "check the weather",
+        },
+      },
+    });
+
+    await expect(monitor.reconcileChildTranscript("child-thread")).resolves.toBe(true);
+
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        status: "succeeded",
+        endedAt: 1779063288000,
+        terminalSummary: "child transcript final result",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: expect.any(Object),
+        childSessionKey: "codex-thread:child-thread",
+        childSessionId: "child-thread",
+        status: "succeeded",
+        statusLabel: "task_complete",
+        result: "child transcript final result",
+      }),
+    );
+
+    client.close();
+  });
+
+  it("keeps polling after a transcript candidate belongs to a different parent", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-subagent-"));
+    const codexHome = path.join(tempDir, "codex-home");
+    const transcriptDir = path.join(codexHome, "sessions", "2026", "05", "17");
+    await fs.mkdir(transcriptDir, { recursive: true });
+    const transcriptPath = path.join(
+      transcriptDir,
+      "rollout-2026-05-17T17-14-08-child-thread.jsonl",
+    );
+    const writeTranscript = async (parentThreadId: string, message: string) => {
+      await fs.writeFile(
+        transcriptPath,
+        [
+          JSON.stringify({
+            type: "session_meta",
+            payload: {
+              source: {
+                subagent: { thread_spawn: { parent_thread_id: parentThreadId } },
+              },
+            },
+          }),
+          JSON.stringify({
+            timestamp: "2026-05-18T00:14:48.094Z",
+            type: "event_msg",
+            payload: {
+              type: "task_complete",
+              last_agent_message: message,
+              completed_at: 1779063288,
+            },
+          }),
+          "",
+        ].join("\n"),
+      );
+    };
+    await writeTranscript("other-parent-thread", "wrong parent result");
+    const client = createClient();
+    const runtime = createRuntime();
+    const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+      codexHome,
+      transcriptPollDelaysMs: [60_000],
+    });
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+    await notifyChildStarted(client);
+
+    await expect(monitor.reconcileChildTranscript("child-thread")).resolves.toBe(false);
+    expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        terminalSummary: "wrong parent result",
+      }),
+    );
+
+    await writeTranscript("parent-thread", "right parent result");
+    await expect(monitor.reconcileChildTranscript("child-thread")).resolves.toBe(true);
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:child-thread",
+        status: "succeeded",
+        terminalSummary: "right parent result",
+      }),
+    );
+
+    client.close();
+  });
+
+  it("reconciles existing running native subagent task rows when a parent registers", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-subagent-"));
+    const codexHome = path.join(tempDir, "codex-home");
+    const transcriptDir = path.join(codexHome, "sessions", "2026", "05", "17");
+    await fs.mkdir(transcriptDir, { recursive: true });
+    await fs.writeFile(
+      path.join(transcriptDir, "rollout-2026-05-17T17-14-08-stale-child.jsonl"),
+      [
+        JSON.stringify({
+          type: "session_meta",
+          payload: {
+            source: {
+              subagent: { thread_spawn: { parent_thread_id: "parent-thread" } },
+            },
+          },
+        }),
+        JSON.stringify({
+          timestamp: "2026-05-18T00:14:48.094Z",
+          type: "event_msg",
+          payload: {
+            type: "task_complete",
+            last_agent_message: "stale child final result",
+            completed_at: 1779063288,
+          },
+        }),
+        "",
+      ].join("\n"),
+    );
+    const client = createClient();
+    const runtime = createRuntime();
+    runtime.listTaskRecords.mockReturnValue([
+      {
+        taskId: "task-1",
+        runtime: "subagent",
+        taskKind: "codex-native",
+        requesterSessionKey: "agent:main:discord:channel:C123",
+        ownerKey: "agent:main:discord:channel:C123",
+        scopeKind: "session",
+        runId: "codex-thread:stale-child",
+        task: "check the weather",
+        status: "running",
+        deliveryStatus: "not_applicable",
+        notifyPolicy: "silent",
+        createdAt: 1,
+      },
+    ]);
+    const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+      codexHome,
+      transcriptPollDelaysMs: [60_000],
+    });
+
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+    await vi.waitFor(() => {
+      expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+        expect.objectContaining({
+          childSessionId: "stale-child",
+          result: "stale child final result",
+        }),
+      );
+    });
+
+    client.close();
+  });
+
+  it("does not rescan transcript directories while a child poll is already scheduled", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-subagent-"));
+    const codexHome = path.join(tempDir, "codex-home");
+    await fs.mkdir(path.join(codexHome, "sessions"), { recursive: true });
+    const client = createClient();
+    const runtime = createRuntime();
+    const readdirSpy = vi.spyOn(fs, "readdir");
+    const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+      codexHome,
+      taskRowReconcileIntervalMs: 0,
+      transcriptPollDelaysMs: [60_000],
+    });
+
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+    await notifyChildStarted(client, "parent-thread", "pending-child");
+    runtime.listTaskRecords.mockReturnValue([
+      {
+        taskId: "task-1",
+        runtime: "subagent",
+        taskKind: "codex-native",
+        requesterSessionKey: "agent:main:discord:channel:C123",
+        ownerKey: "agent:main:discord:channel:C123",
+        scopeKind: "session",
+        runId: "codex-thread:pending-child",
+        task: "check the weather",
+        status: "running",
+        deliveryStatus: "not_applicable",
+        notifyPolicy: "silent",
+        createdAt: 1,
+      },
+    ]);
+    readdirSpy.mockClear();
+    await monitor.reconcileKnownTaskRows();
+
+    expect(readdirSpy).not.toHaveBeenCalled();
+    client.close();
+  });
+
+  it("uses one transcript tree scan for multiple pending task rows", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-subagent-"));
+    const codexHome = path.join(tempDir, "codex-home");
+    await fs.mkdir(path.join(codexHome, "sessions"), { recursive: true });
+    const client = createClient();
+    const runtime = createRuntime();
+    runtime.listTaskRecords.mockReturnValue(
+      ["pending-child-a", "pending-child-b", "pending-child-c"].map((childThreadId, index) => ({
+        taskId: `task-${index}`,
+        runtime: "subagent",
+        taskKind: "codex-native",
+        requesterSessionKey: "agent:main:discord:channel:C123",
+        ownerKey: "agent:main:discord:channel:C123",
+        scopeKind: "session",
+        runId: `codex-thread:${childThreadId}`,
+        task: "check the weather",
+        status: "running",
+        deliveryStatus: "not_applicable",
+        notifyPolicy: "silent",
+        createdAt: 1,
+      })),
+    );
+    const readdirSpy = vi.spyOn(fs, "readdir");
+    const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+      codexHome,
+      taskRowReconcileIntervalMs: 0,
+      transcriptPollDelaysMs: [60_000],
+    });
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    readdirSpy.mockClear();
+    await monitor.reconcileKnownTaskRows();
+
+    expect(readdirSpy).toHaveBeenCalledTimes(1);
+    expect(runtime.deliverAgentHarnessTaskCompletion).not.toHaveBeenCalled();
+    client.close();
+  });
+
+  it("reconciles completed native subagent transcripts from task rows without live child registration", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-subagent-"));
+    const codexHome = path.join(tempDir, "codex-home");
+    const transcriptDir = path.join(codexHome, "sessions", "2026", "05", "17");
+    await fs.mkdir(transcriptDir, { recursive: true });
+    await fs.writeFile(
+      path.join(transcriptDir, "rollout-2026-05-17T19-35-43-unregistered-child.jsonl"),
+      [
+        JSON.stringify({
+          timestamp: "2026-05-18T02:35:44.420Z",
+          type: "session_meta",
+          payload: {
+            source: {
+              subagent: {
+                thread_spawn: {
+                  parent_thread_id: "parent-thread",
+                  depth: 1,
+                },
+              },
+            },
+          },
+        }),
+        JSON.stringify({
+          timestamp: "2026-05-18T02:36:05.301Z",
+          type: "event_msg",
+          payload: {
+            type: "task_complete",
+            last_agent_message: "unregistered child final result",
+            completed_at: 1779071765,
+          },
+        }),
+        "",
+      ].join("\n"),
+    );
+    const client = createClient();
+    const runtime = createRuntime();
+    runtime.listTaskRecords.mockReturnValue([
+      {
+        taskId: "task-1",
+        runtime: "subagent",
+        taskKind: "codex-native",
+        requesterSessionKey: "agent:main:discord:channel:C123",
+        ownerKey: "agent:main:discord:channel:C123",
+        scopeKind: "session",
+        runId: "codex-thread:unregistered-child",
+        task: "check the weather",
+        status: "running",
+        deliveryStatus: "not_applicable",
+        notifyPolicy: "silent",
+        createdAt: 1,
+      },
+    ]);
+    const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+      codexHome,
+      taskRowReconcileIntervalMs: 0,
+    });
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await monitor.reconcileKnownTaskRows();
+
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:unregistered-child",
+        status: "succeeded",
+        terminalSummary: "unregistered child final result",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: expect.any(Object),
+        childSessionKey: "codex-thread:unregistered-child",
+        childSessionId: "unregistered-child",
+        result: "unregistered child final result",
+      }),
+    );
+
+    client.close();
+  });
+
+  it("reconciles recent terminal native subagent rows that still need parent delivery", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-subagent-"));
+    const codexHome = path.join(tempDir, "codex-home");
+    const transcriptDir = path.join(codexHome, "sessions", "2026", "05", "17");
+    await fs.mkdir(transcriptDir, { recursive: true });
+    await fs.writeFile(
+      path.join(transcriptDir, "rollout-2026-05-17T19-50-35-mirror-finalized-child.jsonl"),
+      [
+        JSON.stringify({
+          timestamp: "2026-05-18T02:50:36.018Z",
+          type: "session_meta",
+          payload: {
+            source: {
+              subagent: {
+                thread_spawn: {
+                  parent_thread_id: "parent-thread",
+                },
+              },
+            },
+          },
+        }),
+        JSON.stringify({
+          timestamp: "2026-05-18T02:57:07.752Z",
+          type: "event_msg",
+          payload: {
+            type: "task_complete",
+            last_agent_message: "mirror finalized child final result",
+            completed_at: 1779073027,
+          },
+        }),
+        "",
+      ].join("\n"),
+    );
+    const client = createClient();
+    const runtime = createRuntime();
+    const now = Date.now();
+    runtime.listTaskRecords.mockReturnValue([
+      {
+        taskId: "task-1",
+        runtime: "subagent",
+        taskKind: "codex-native",
+        requesterSessionKey: "agent:main:discord:channel:C123",
+        ownerKey: "agent:main:discord:channel:C123",
+        scopeKind: "session",
+        runId: "codex-thread:mirror-finalized-child",
+        task: "check the weather",
+        status: "succeeded",
+        deliveryStatus: "not_applicable",
+        notifyPolicy: "silent",
+        createdAt: now,
+        endedAt: now,
+        lastEventAt: now,
+      },
+    ]);
+    const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+      codexHome,
+      taskRowReconcileIntervalMs: 0,
+    });
+    monitor.registerParent({
+      parentThreadId: "parent-thread",
+      requesterSessionKey: "agent:main:discord:channel:C123",
+      taskRuntimeScope: createTaskScope(),
+      agentId: "main",
+    });
+
+    await monitor.reconcileKnownTaskRows();
+
+    expect(runtime.setDetachedTaskDeliveryStatusByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:mirror-finalized-child",
+        deliveryStatus: "pending",
+      }),
+    );
+    expect(runtime.deliverAgentHarnessTaskCompletion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: expect.any(Object),
+        childSessionKey: "codex-thread:mirror-finalized-child",
+        childSessionId: "mirror-finalized-child",
+        result: "mirror finalized child final result",
+      }),
+    );
+    expect(runtime.setDetachedTaskDeliveryStatusByRunId).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runId: "codex-thread:mirror-finalized-child",
+        deliveryStatus: "delivered",
+      }),
+    );
+
+    client.close();
+  });
+
+  it("registers one monitor per shared app-server client", async () => {
+    const client = createClient();
+    const runtime = createRuntime();
+    registerCodexNativeSubagentMonitor({
+      client: client as never,
+      parentThreadId: "parent-1",
+      requesterSessionKey: "agent:main:main",
+      taskRuntimeScope: createTaskScope("agent:main:main"),
+      runtime,
+    });
+    registerCodexNativeSubagentMonitor({
+      client: client as never,
+      parentThreadId: "parent-2",
+      requesterSessionKey: "agent:main:main",
+      taskRuntimeScope: createTaskScope("agent:main:main"),
+      runtime,
+    });
+
+    await client.notify({
+      method: "thread/started",
+      params: {
+        thread: {
+          id: "child-2",
+          source: {
+            subAgent: {
+              thread_spawn: {
+                parent_thread_id: "parent-2",
+                depth: 1,
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(runtime.createRunningTaskRun).toHaveBeenCalledTimes(1);
+    expect(runtime.createRunningTaskRun).toHaveBeenCalledWith(
+      expect.objectContaining({ runId: "codex-thread:child-2" }),
+    );
+  });
+
+  it("clears reconcile timers when the app-server client closes", async () => {
+    vi.useFakeTimers();
+    try {
+      const client = createClient();
+      const runtime = createRuntime();
+      const monitor = new CodexNativeSubagentMonitor(client, runtime, {
+        codexHome: "/tmp/codex-home",
+        taskRowReconcileIntervalMs: 10,
+      });
+
+      client.close();
+      await vi.advanceTimersByTimeAsync(30);
+
+      expect(runtime.listTaskRecords).not.toHaveBeenCalled();
+      monitor.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});