Skip to content

fix(collaboration): batch handoff query Goal lifetime guard lock per Goal - #9085

Merged
loopx-agent merged 1 commit into
mainfrom
codex/fix-handoff-query-lock-cascade-20261120
Nov 19, 2026
Merged

loopx-agent merged 1 commit into
mainfrom
codex/fix-handoff-query-lock-cascade-20261120

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Fix an O(N * 5s) lock-timeout cascade in loopx.capabilities.manager_context.tracking.query that caused Steward/manager view="handoffs" inspections to hang past the 600s turn idle watchdog when a Goal's guard lock was contended or stranded across hundreds of handoff entries:

  • loopx/control_plane/collaboration/goal_instance_scope.py:
    • Added scope_for_caller_goal_ref(scope, caller_goal_ref) to re-bind per-entry caller_goal_ref (and fail closed on malformed non-mapping refs) under an already-held CollaborationGoalScope without re-acquiring the Goal lifetime lock for every entry.
  • loopx/capabilities/manager_context/tracking.py:
    • Refactored query() into a lock-free candidate filter pass (candidates_by_goal) followed by a single collaboration_goal_scope(...) lifetime lock per matched Goal.
    • Preserves exact per-row _entry(...) and decide_collaboration_lifecycle(..., operation="history_inspect") error isolation (unreadable += 1) while failing fast once per contended Goal (unreadable += len(group_rows)) instead of paying N * 5s lock timeouts across hundreds of records.
  • tests/test_manager_context_tracking.py:
    • Added regression coverage for single-lock-per-Goal batching, fail-fast per-Goal isolation on LockAcquireTimeoutError without blocking healthy sibling Goals, and per-row goal_ref validation inside batched source_session_v1 queries.

Verification

  • uv run --extra test ruff check loopx/control_plane/collaboration/goal_instance_scope.py loopx/capabilities/manager_context/tracking.py tests/test_manager_context_tracking.py — passed (All checks passed!)
  • PYTHONPATH=tests uv run --extra test python -m pytest -n 6 tests/test_manager_context_tracking.py tests/test_manager_context_roundtrip.py tests/test_collaboration_goal_instance.py tests/test_peer_collaboration.py -q — 311 passed, 3 skipped
  • uv run --extra test python examples/control_plane/control-plane-maintainability-ratchet-smoke.py — passed
  • uv run --extra test loopx --format json canary premerge --from-git-diff --git-diff-base origin/main — passed

…Goal

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google · self_reported

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

动机 / Motivation

评审精确 head 5b0a4f0bf6d6e91be8237307a2bc627ecf0b2a3e。受影响主体为在私聊或管理视图调用 loopx_manager_read(view="handoffs") 查询多条委派交付记录的 LoopX 个人管家与工作区操作者。此前 tracking.query 在遍历每条 handoff 记录的循环内重复加锁打开 collaboration_goal_scope,当单个 Goal 存在数百条记录且守卫锁发生竞争或残留时,会在单次查询中串行阻塞 N 次 5 秒超时(实测超过 27 分钟)并触发 idle_timeout;修改后先完成无锁候选过滤并按 goal_id 分组,每个命中的 Goal 至多获取一次 collaboration_goal_scope 锁,组内再通过 scope_for_caller_goal_ref 逐行绑定与校验 goal_ref。可观测结果为:tracking.query 对每个匹配的 Goal 至多持有一次 collaboration_goal_scope 生命周期锁,同组多条记录共享该锁且保持单条记录 goal_ref 校验与 unreadable 隔离;当某 Goal 发生 LockAcquireTimeoutError 时按组快速失败(仅等待 1 次超时),不再阻塞同批其他健康 Goal 的查询与管家交互响应。本 PR 不修改守卫锁底层文件格式、不移除 source_session_v1 的逐行 goal_ref 实例校验、不涉及任何 UI 或提示词变更,也不擅自删除磁盘锁文件。

改动思路 / Approach

架构定位与边界:复用既有 collaboration_goal_scope 与 CollaborationGoalScope 生命周期校验契约,仅将“按行加锁”收敛为“按 Goal 分组加锁 + scope_for_caller_goal_ref 逐行重绑”,未绕过受控生命周期隔离。仅优化 tracking.query 的 Goal 生命周期锁获取粒度并补充回归测试,不修改锁实现本身、不跳过 goal_ref 实例检查,也不调整 UI 或运维调度策略。

  1. 按 Goal 分组持锁(loopx/capabilities/manager_context/tracking.py):将 query() 拆为两阶段——第一阶段先完成文件读取与 goal_id/agent_id/request_id/受众过滤,收集为 candidates_by_goal;第二阶段对每个 goal_id 仅调用一次 collaboration_goal_scope,在持有同一把生命周期锁的上下文中逐条执行 _entry 与 decide_collaboration_lifecycle 校验,既保住 source_session_v1 实例检查,又彻底消除 O(N * 5s) 锁超时级联。
  2. 复用单一 goal_ref 校验逻辑(loopx/control_plane/collaboration/goal_instance_scope.py):新增 scope_for_caller_goal_ref,借助 dataclasses.replace 与现有 _caller_ref 校验每条记录的 goal_ref(对非映射类型的损坏字段显式拒绝为 TypeError 并计入单条 unreadable),不向 tracking.py 扩散规则细节。

具体改动 / Changes

  • loopx/control_plane/collaboration/goal_instance_scope.py (+24/-2): 新增 scope_for_caller_goal_ref 支持在已持有 Goal 生命周期锁内安全切换单条记录的 caller_goal_ref。
  • loopx/capabilities/manager_context/tracking.py (+36/-19): 将 query() 重构为先过滤分组、再按 goal_id 持锁逐行校验,锁竞争按组快速失败计入 unreadable 而不波及兄弟 Goal。
  • tests/test_manager_context_tracking.py (+197): 新增三项回归测试,覆盖按 Goal 单锁批量校验、跨 Goal LockAcquireTimeoutError 快速失败隔离,以及 source_session_v1 下混合有效/过期/损坏 goal_ref 的逐行校验。

对主干的风险 / Risks

极低风险(仅 3 个 Python 文件,无 schema、UI 或提示词改动):

  • rebased exact head 5b0a4f0bf6d6e91be8237307a2bc627ecf0b2a3e 上 ruff check 零告警;
  • tests/test_manager_context_tracking.py 与 tests/test_collaboration_goal_instance.py 共 110 passed(0 失败);
  • 既有 control-plane-maintainability-ratchet-smoke.py、semantic-vocabulary-drift-smoke.py 及 canary premerge 10/10 全数通过;
  • 所有健康输入的返回值、排序与 unreadable 语义与基线完全等价。

我的整体评价 / Verdict

该修复精准解决了管家调用 handoffs 查询时因单 Goal 数百条记录叠加守卫锁超时导致的 O(N * 5s) 阻塞与 idle_timeout 根因,在完整保留 source_session_v1 逐行实例校验和错误隔离的前提下将每个 Goal 的锁获取收敛为一次;长期可维护性与用户体验均获明确改善(UI visual review 不适用)。全部测试与预合并检查已在精确提交 5b0a4f0bf6d6e91be8237307a2bc627ecf0b2a3e 验证通过。

English Verdict: APPROVE - Verified at exact head 5b0a4f0; batching collaboration_goal_scope per Goal eliminates O(N * 5s) handoff query lock cascades while preserving source_session_v1 per-row goal_ref validation and unreadable isolation (110/110 rebased pytests, ruff, ratchet, and 10/10 canary premerge pass).

@loopx-agent
loopx-agent merged commit fac7d35 into main Nov 19, 2026
26 of 31 checks passed
@loopx-agent
loopx-agent deleted the codex/fix-handoff-query-lock-cascade-20261120 branch November 19, 2026 16:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant