openclaw - 💡(How to fix) Fix Bug: sessions_yield can leave parent session transcript lock held, causing subagent completion callback timeout

Summary

When a parent run starts a subagent and then calls sessions_yield, the subagent completion callback may fail to resume/write back to the yielded parent session because the parent session transcript lock remains held by the live gateway process.

The observed error is:

session file locked (timeout 60000ms): pid=<gateway-pid> /root/.openclaw/agents/main/sessions/<session-id>.jsonl.lock

This causes subagent completion events/callback messages to be missed by the parent session.

Environment

• OpenClaw package version: 2026.5.22
• Runtime: gateway process, Node v24.15.0
• Repo/package: openclaw/openclaw
• Session transcript directory: /root/.openclaw/agents/main/sessions

What happened

A parent session spawned a subagent and used sessions_yield to wait for completion. After the yield/abort path, the session lock file remained present. The lock payload showed that the owner was the still-running gateway PID, not a dead process:

{
  "pid": <gateway-pid>,
  "createdAt": "2026-05-24T05:04:42.710Z",
  "maxHoldMs": 1020000,
  "starttime": <gateway-starttime>
}

ps confirmed the PID was the active gateway process:

/root/.nvm/versions/node/v24.15.0/bin/node .../openclaw/dist/index.js gateway --port 19000

The affected session transcript ended around a sessions_yield call followed by an assistant message with stopReason: "aborted". After that, subagent completion/resume writes contended on the same .jsonl.lock and timed out after the default 60000ms acquire timeout.

Expected behavior

After sessions_yield causes the parent run to yield/abort for subagent completion, the parent session transcript write lock should be released reliably so that the completion event can be written back to the yielded parent session.

Actual behavior

The gateway process can keep the parent session .jsonl.lock held in-process after the sessions_yield abort path. Since the owner PID is alive and recognized as OpenClaw, other writers do not reclaim the lock. They wait until session.writeLock.acquireTimeoutMs and then fail with SessionWriteLockTimeoutError.

Suspected cause

The lock lifecycle around the embedded attempt controller appears to lack a final unconditional release for all exit paths.

Relevant code areas observed in the built package:

• createEmbeddedAttemptSessionLockController(...)
• releaseForPrompt() / reacquireAfterPrompt()
• the yieldAborted branch for sessions_yield
• acquireForCleanup(...) / cleanupEmbeddedAttemptResources(...)
• session-write-lock watchdog behavior

The current flow appears to allow a lock to be reacquired/held after the prompt abort/yield path, then not released if the run exits through a particular aborted/yielded path. Because maxHoldMs may be extended (observed 1020000ms), the watchdog does not release it before subagent completion callbacks hit the 60000ms acquire timeout.

Suggested fix direction

Add a defensive final-release path to the embedded attempt session lock controller, for example:

1. Add a controller method that releases any currently held lock regardless of whether normal cleanup completed, e.g. forceReleaseHeldLock().
2. Call it from the outer attempt finally block so every abort/error/yield path releases the transcript lock.
3. Ensure sessions_yield transitions to its waiting state only after the parent session write lock has been released.
4. Consider using a shorter/non-run-timeout-derived maxHoldMs for locks held around yield state, since subagent completion needs to write back much sooner than a long run timeout.

Workaround

Avoid sessions_yield for now. Let subagents write results to files or retrieve child results via sessions_history/manual inspection instead of relying on push-back completion into the parent session.

Related issues

This may overlap with or be related to:

• #81490 (subagent completion spawns a fresh run on the parent's route instead of resuming the yielded session)
• #43367 (Multi-agent orchestration is unstable... session-lock failures...)