fix(tasks): keep diagnostics json-only and wedged-aware

efpiva · efpiva · commit 7ea32f0b5394 · 2026-05-20T17:46:03.000-07:00
diff --git a/src/commands/tasks.test.ts b/src/commands/tasks.test.ts
@@ -11,6 +11,7 @@ import {
   resetTaskRegistryDeliveryRuntimeForTests,
   resetTaskRegistryForTests,
 } from "../tasks/task-registry.js";
+import * as taskRegistryMaintenance from "../tasks/task-registry.maintenance.js";
 import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";
 import type { OpenClawTestState } from "../test-utils/openclaw-test-state.js";
 import { tasksAuditCommand, tasksMaintenanceCommand } from "./tasks.js";
@@ -269,6 +270,20 @@ describe("tasks commands", () => {
     });
   });
 
+  it("does not build JSON-only diagnostics for text maintenance output", async () => {
+    await withTaskCommandStateDir(async () => {
+      const diagnosticsSpy = vi.spyOn(
+        taskRegistryMaintenance,
+        "getTaskRegistryMaintenanceDiagnostics",
+      );
+      const runtime = createRuntime();
+
+      await tasksMaintenanceCommand({ json: false, apply: false }, runtime);
+
+      expect(diagnosticsSpy).not.toHaveBeenCalled();
+    });
+  });
+
   it("keeps tasks maintenance JSON additive for TaskFlow state", async () => {
     await withTaskCommandStateDir(async () => {
       const now = Date.now();
diff --git a/src/commands/tasks.ts b/src/commands/tasks.ts
@@ -665,9 +665,9 @@ export async function tasksMaintenanceCommand(
   const taskMaintenance = opts.apply
     ? await runTaskRegistryMaintenance()
     : previewTaskRegistryMaintenance();
-  // Diagnostics explain the task-maintenance decision above, before the
+  // JSON diagnostics explain the task-maintenance decision above, before the
   // separate session-registry sweep can prune backing session rows.
-  const diagnostics = getTaskRegistryMaintenanceDiagnostics();
+  const diagnostics = opts.json ? getTaskRegistryMaintenanceDiagnostics() : undefined;
   const flowMaintenance = opts.apply
     ? await runTaskFlowRegistryMaintenance()
     : previewTaskFlowRegistryMaintenance();
diff --git a/src/tasks/task-registry.maintenance.issue-60299.test.ts b/src/tasks/task-registry.maintenance.issue-60299.test.ts
@@ -316,10 +316,14 @@ describe("task-registry maintenance issue #60299", () => {
 
   it("marks subagent tasks lost when their child session recovery is tombstoned", async () => {
     const childSessionKey = "agent:main:subagent:wedged-child";
+    const staleAt = Date.now() - 45 * 60_000;
     const task = makeStaleTask({
       runtime: "subagent",
       runId: "run-wedged-child",
       childSessionKey,
+      createdAt: staleAt,
+      startedAt: staleAt,
+      lastEventAt: staleAt,
     });
 
     const { currentTasks } = createTaskRegistryMaintenanceHarness({
@@ -341,6 +345,14 @@ describe("task-registry maintenance issue #60299", () => {
     });
 
     expectMaintenanceCounts(previewTaskRegistryMaintenance(), { reconciled: 1 });
+    expect(getTaskRegistryMaintenanceDiagnostics().staleRunningTasks).toContainEqual(
+      expect.objectContaining({
+        taskId: task.taskId,
+        decision: "would_reconcile",
+        reason: "subagent_recovery_wedged",
+        detail: "subagent orphan recovery blocked after 2 rapid accepted resume attempts",
+      }),
+    );
     expectMaintenanceCounts(await runTaskRegistryMaintenance(), { reconciled: 1 });
     const storedTask = requireTaskRecord(currentTasks, task.taskId);
     expect(storedTask.status).toBe("lost");
diff --git a/src/tasks/task-registry.maintenance.ts b/src/tasks/task-registry.maintenance.ts
@@ -173,7 +173,9 @@ export type TaskRegistryMaintenanceTaskDiagnostic = {
     | "backing_session_missing"
     | "backing_session_present"
     | "cron_runtime_not_authoritative"
-    | "lost_grace_pending";
+    | "lost_grace_pending"
+    | "subagent_recovery_wedged";
+  detail?: string;
   ageMs: number;
   childSessionKey?: string;
   runId?: string;
@@ -981,10 +983,20 @@ function explainActiveTaskRetention(params: {
   task: TaskRecord;
   now: number;
   context: BackingSessionLookupContext;
-}): Pick<TaskRegistryMaintenanceTaskDiagnostic, "decision" | "reason"> {
+}): Pick<TaskRegistryMaintenanceTaskDiagnostic, "decision" | "reason" | "detail"> {
   if (!hasLostGraceExpired(params.task, params.now)) {
     return { decision: "retained", reason: "lost_grace_pending" };
   }
+  if (params.task.runtime === "subagent") {
+    const entry = findTaskSessionEntry(params.task, params.context);
+    if (entry && isSubagentRecoveryWedgedEntry(entry)) {
+      return {
+        decision: "would_reconcile",
+        reason: "subagent_recovery_wedged",
+        detail: formatSubagentRecoveryWedgedReason(entry),
+      };
+    }
+  }
   if (!hasBackingSession(params.task, params.context)) {
     return { decision: "would_reconcile", reason: "backing_session_missing" };
   }
@@ -1025,6 +1037,7 @@ export function getTaskRegistryMaintenanceDiagnostics(): TaskRegistryMaintenance
       decision: decision.decision,
       reason: decision.reason,
       ageMs,
+      ...(decision.detail ? { detail: decision.detail } : {}),
       ...(task.childSessionKey ? { childSessionKey: task.childSessionKey } : {}),
       ...(task.runId ? { runId: task.runId } : {}),
     });
