Fix OpenClaw commit failure semantics

Author: sponge225

docs/en/api/05-sessions.md

@@ -1403,8 +1403,8 @@ Commit a session. Message archiving (Phase 1) completes immediately. Summary gen
 **Notes:**
 - Rapid consecutive commits on the same session are accepted; each request gets its own `task_id`.
 - Empty sessions, or commits where all messages remain inside `keep_recent_count`, complete synchronously with `archived: false`.
-- Background Phase 2 work is serialized by archive order: archive `N+1` waits until archive `N` writes `.done`.
-- If an earlier archive failed and left no `.done`, later commit requests fail with `FAILED_PRECONDITION` until that failure is resolved.
+- Background Phase 2 work is serialized by archive order while the direct predecessor is still pending.
+- If Phase 1 archived messages but Phase 2 later fails, the archive is marked with `.failed.json`. That failed archive is terminal and skippable: it is not returned as a completed archive, it does not provide an overview, and it does not block later commit requests.
 - If committed messages contain durable facts, judgments, preferences, or events that mention `viking://resources/...`, memory extraction preserves the resource as a markdown link and records it in `MEMORY_FIELDS.resource_refs`.
 
 **Code Entries:**

docs/zh/api/05-sessions.md

@@ -1374,8 +1374,8 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
 **注意事项**：
 - 同一 session 的多次快速连续 commit 会被接受；每次请求都会拿到独立的 `task_id`
 - 空 session，或所有消息都仍在 `keep_recent_count` 保留窗口内时，会同步完成并返回 `archived: false`
-- 后台 Phase 2 会按 archive 顺序串行推进：`archive_N+1` 会等待 `archive_N` 写出 `.done` 后再继续
-- 如果更早的 archive 已失败且没有 `.done`，后续 commit 会直接返回错误，直到该失败被处理
+- 后台 Phase 2 会按 archive 顺序串行推进；只有直接前序 archive 仍为 pending 时，后续 archive 才会等待
+- 如果 Phase 1 已经归档消息但 Phase 2 随后失败，该 archive 会写入 `.failed.json`。这个 failed archive 是终态且可跳过：它不会作为 completed archive 返回，不提供 overview，也不会阻塞后续 commit 请求
 - 如果提交的消息中包含带 `viking://resources/...` 的长期事实、评价、偏好或事件，记忆抽取会把资源保留为 markdown 链接，并写入 `MEMORY_FIELDS.resource_refs`
 
 **代码入口**：

examples/openclaw-plugin/README.md

@@ -229,6 +229,7 @@ Use it as a complement to auto-capture, not a replacement:
 - it calls `commit(wait=true)` and blocks for completion
 - when an archive exists, it re-reads `latest_archive_overview`
 - it returns updated token estimates, the latest archive id, and summary content
+- if archiving succeeds but Phase 2 reaches a failed terminal state, the compact boundary is still reported as established, with a degraded reason and the task details attached
 - if the summary is too coarse, the model can call `ov_archive_expand` to reopen a specific archive
 
 So `afterTurn()` is closer to "incremental append plus threshold-triggered async commit", while `compact()` is the explicit "wait for archive and compaction to finish" boundary.

examples/openclaw-plugin/README_CN.md

@@ -257,6 +257,7 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来
 - 它调用 `commit(wait=true)`，阻塞等待 commit 完成
 - 如果有 archive 生成，会再回读 `latest_archive_overview`
 - 返回新的 token 估算、latest archive id 和 summary
+- 如果归档已成功但 Phase 2 进入 failed 终态，仍会报告压缩边界已建立，并在 reason 和 details 中暴露降级原因
 - 如果摘要不够精确，模型可以再调用 `ov_archive_expand` 读取某个 archive 的原始消息
 
 所以 `afterTurn()` 更像"增量写入 + 条件触发异步提交"，而 `compact()` 才是"明确等待压缩与归档完成"的正式边界。

examples/openclaw-plugin/docs/openviking-openclaw-plugin-guide.md

@@ -135,7 +135,7 @@ transformContext auto recall 流程：
 
 1. 解析 OpenViking session id。
 2. 调用 `commitSession(wait=true, keepRecentCount=0)`，要求服务端归档所有当前消息：`context-engine.ts:1500`。
-3. 如果 Phase 2 failed/timeout，返回失败原因。
+3. 如果 Phase 1 已经归档但 Phase 2 进入 failed 终态，仍视为压缩边界已建立，并在 `reason` 中报告抽取降级。
 4. 如果没有生成 archive，返回 `commit_no_archive`。
 5. 如果归档成功，再回读 `getSessionContext`，获取最新 `latest_archive_overview` 作为 summary：`context-engine.ts:1605`。
 6. 返回 tokensBefore/tokensAfter、latest archive id 和 summary。
@@ -171,7 +171,7 @@ transformContext auto recall 流程：
 插件把 OpenClaw turn 持续写入 OpenViking session，由服务端维护 `pending_tokens` 与 archive。超过阈值时：
 
 - `afterTurn` 路径：`wait=false`，异步 Phase 2，默认保留最近 10 条消息。
-- `compact` 路径：`wait=true`，同步等待 Phase 2，`keepRecentCount=0`，形成明确压缩边界。
+- `compact` 路径：`wait=true`，同步等待 Phase 2，`keepRecentCount=0`，形成明确压缩边界。若 Phase 2 failed 且服务端返回 `archived=true`，旧消息已经离开 live session，插件会返回 `commit_archived_phase2_failed`，而不是把下一次空 session compact 误判为可重试修复。若 Phase 2 timeout，archive 仍可能处于 pending 并被 context 读取路径回放原文，因此插件仍返回 `commit_timeout`。
 
 `commitKeepRecentCount` 默认 10，`commitTokenThresholdRatio` 默认 0.5（模型上下文窗口的 50%）：`config.ts`。
 

examples/openclaw-plugin/services/context-lifecycle-service.ts

@@ -372,7 +372,7 @@ export async function commitOpenVikingSession({
         `openviking: commit Phase 2 failed for session=${sessionId}: ${commitResult.error ?? "unknown"}, ` +
           `trace_id=${commitResult.trace_id ?? "none"}`,
       );
-      return false;
+      return commitResult.archived === true;
     }
     if (commitResult.status === "timeout") {
       logger.warn?.(
@@ -1072,45 +1072,45 @@ export async function compactOpenVikingSession({
       keepRecentCount: 0,
     });
     const memCount = totalExtractedMemories(commitResult.memories_extracted);
-
-    if (commitResult.status === "failed") {
-      logger.warn?.(
-        `openviking: compact commit Phase 2 failed for session=${ovSessionId}: ` +
-          `${commitResult.error ?? "unknown"}, trace_id=${commitResult.trace_id ?? "none"}`,
-      );
+    const archived = commitResult.archived === true;
+    let compactReason = "commit_completed";
+    const failCommit = (reason: string, extra: Record<string, unknown> = {}) => {
       diag("compact_result", ovSessionId, {
         ok: false,
         compacted: false,
-        reason: "commit_failed",
+        reason,
         status: commitResult.status,
         archived: commitResult.archived ?? false,
         taskId: commitResult.task_id ?? null,
-        error: commitResult.error ?? null,
+        ...extra,
       });
-      return compactFailureResult("commit_failed", tokensBefore, { commit: commitResult });
+      return compactFailureResult(reason, tokensBefore, { commit: commitResult });
+    };
+
+    if (commitResult.status === "failed") {
+      logger.warn?.(
+        `openviking: compact commit Phase 2 failed for session=${ovSessionId}: ` +
+          `${commitResult.error ?? "unknown"}, trace_id=${commitResult.trace_id ?? "none"}`,
+      );
+      if (!archived) {
+        return failCommit("commit_failed", { error: commitResult.error ?? null });
+      }
+      compactReason = "commit_archived_phase2_failed";
     }
 
     if (commitResult.status === "timeout") {
       logger.warn?.(
         `openviking: compact commit Phase 2 timed out for session=${ovSessionId}, ` +
           `task_id=${commitResult.task_id ?? "none"}, trace_id=${commitResult.trace_id ?? "none"}`,
       );
-      diag("compact_result", ovSessionId, {
-        ok: false,
-        compacted: false,
-        reason: "commit_timeout",
-        status: commitResult.status,
-        archived: commitResult.archived ?? false,
-        taskId: commitResult.task_id ?? null,
-      });
-      return compactFailureResult("commit_timeout", tokensBefore, { commit: commitResult });
+      return failCommit("commit_timeout");
     }
 
     logger.info(
       `openviking: compact committed session=${ovSessionId}, archived=${commitResult.archived ?? false}, memories=${memCount}, task_id=${commitResult.task_id ?? "none"}, trace_id=${commitResult.trace_id ?? "none"}`,
     );
 
-    if (!commitResult.archived) {
+    if (!archived) {
       logger.info(
         `openviking: compact no archive for session=${ovSessionId}, ` +
           `tokensBefore=${tokensBefore}, tokensAfter=${tokensBefore}`,
@@ -1203,7 +1203,7 @@ export async function compactOpenVikingSession({
     diag("compact_result", ovSessionId, {
       ok: true,
       compacted: true,
-      reason: "commit_completed",
+      reason: compactReason,
       status: commitResult.status,
       archived: commitResult.archived ?? false,
       taskId: commitResult.task_id ?? null,
@@ -1217,7 +1217,7 @@ export async function compactOpenVikingSession({
     return {
       ok: true,
       compacted: true,
-      reason: "commit_completed",
+      reason: compactReason,
       result: {
         summary,
         firstKeptEntryId,

examples/openclaw-plugin/tests/ut/context-engine-compact.test.ts

@@ -73,24 +73,41 @@ describe("context-engine commitOVSession()", () => {
     expect(ok).toBe(true);
   });
 
-  it("returns false on failed commit", async () => {
-    const { engine } = makeEngine({
-      status: "failed",
-      error: "extraction error",
-    });
-
-    const ok = await engine.commitOVSession({ sessionId: "test-session" });
-    expect(ok).toBe(false);
-  });
-
-  it("returns false on timeout commit", async () => {
-    const { engine } = makeEngine({
-      status: "timeout",
-      task_id: "task-timeout",
-    });
+  it.each([
+    {
+      name: "failed commit without archive",
+      commitResult: { status: "failed", error: "extraction error" },
+      expected: false,
+    },
+    {
+      name: "Phase 1 archived before Phase 2 failed",
+      commitResult: {
+        status: "failed",
+        archived: true,
+        error: "extraction error",
+        task_id: "task-failed",
+      },
+      expected: true,
+    },
+    {
+      name: "timeout commit without archive",
+      commitResult: { status: "timeout", task_id: "task-timeout" },
+      expected: false,
+    },
+    {
+      name: "Phase 1 archived but Phase 2 is still pending after timeout",
+      commitResult: {
+        status: "timeout",
+        archived: true,
+        task_id: "task-timeout",
+      },
+      expected: false,
+    },
+  ])("returns $expected for $name", async ({ commitResult, expected }) => {
+    const { engine } = makeEngine(commitResult);
 
     const ok = await engine.commitOVSession({ sessionId: "test-session" });
-    expect(ok).toBe(false);
+    expect(ok).toBe(expected);
   });
 
   it("returns false when commit throws", async () => {
@@ -268,6 +285,36 @@ describe("context-engine compact()", () => {
     );
   });
 
+  it("returns compacted=true when Phase 1 archived before Phase 2 failed", async () => {
+    const { engine, logger } = makeEngine({
+      status: "failed",
+      archived: true,
+      archive_uri: "viking://user/default/sessions/s3/history/archive_001",
+      error: "extraction pipeline error",
+      task_id: "task-3",
+    });
+
+    const result = await engine.compact({
+      sessionId: "s3",
+      sessionFile: "",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.compacted).toBe(true);
+    expect(result.reason).toBe("commit_archived_phase2_failed");
+    expect(result.result?.firstKeptEntryId).toBe("archive_001");
+    expect(result.result?.details).toMatchObject({
+      commit: {
+        status: "failed",
+        archived: true,
+        error: "extraction pipeline error",
+      },
+    });
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("Phase 2 failed"),
+    );
+  });
+
   it("returns ok=false when commit status is 'timeout'", async () => {
     const { engine, logger } = makeEngine({
       status: "timeout",
@@ -287,6 +334,34 @@ describe("context-engine compact()", () => {
     );
   });
 
+  it("returns compacted=false when Phase 1 archived but Phase 2 is still pending after timeout", async () => {
+    const { engine, logger } = makeEngine({
+      status: "timeout",
+      archived: true,
+      archive_uri: "viking://user/default/sessions/s4/history/archive_001",
+      task_id: "task-4",
+    });
+
+    const result = await engine.compact({
+      sessionId: "s4",
+      sessionFile: "",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.compacted).toBe(false);
+    expect(result.reason).toBe("commit_timeout");
+    expect(result.result?.details).toMatchObject({
+      commit: {
+        status: "timeout",
+        archived: true,
+        archive_uri: "viking://user/default/sessions/s4/history/archive_001",
+      },
+    });
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("Phase 2 timed out"),
+    );
+  });
+
   it("commit passes wait=true for synchronous extraction", async () => {
     const { engine, client } = makeEngine({
       status: "completed",