attention-queue.md

Attention Queue

The attention queue is the first-screen status contract for LoopX. It is designed for Codex goal ticks, heartbeat jobs, and a future UI that needs to answer one question quickly:

Which goal needs attention next, and who is it waiting on?

loopx status builds the queue from three public-safe surfaces:

• registry goals and adapter declarations,
• compact run-history indexes,
• the public/private contract check.

It does not read private run payloads beyond the compact index fields, does not inspect project-specific logs, and does not mutate files.

For the full JSON shape intended for dashboards and scripts, see status-data-contract.md.

Command

loopx status
loopx --format json status

The command intentionally stays generic. Project adapters decide their own domain-specific classifications, but status maps common classifications into a small queue model.

Queue Item Schema

{
  "goal_id": "complex-project-main-control",
  "status": "ready_for_controller_opt_in",
  "lifecycle_phase": "controller_gated",
  "lifecycle_flags": ["controller_gated", "adapter_inspected"],
  "waiting_on": "user_or_controller",
  "severity": "action",
  "recommended_action": "先在 LoopX 完成 operator 判断；同意后项目 Agent 只执行 read-only map dry-run",
  "operator_question": "是否同意 `complex-project-main-control` 先执行 read-only map opt-in？",
  "agent_command": "loopx read-only-map --goal-id complex-project-main-control --dry-run",
  "quota": {
    "compute": 0.5,
    "window_hours": 24,
    "slot_minutes": 1,
    "allowed_slots": 720,
    "spent_slots": 0,
    "state": "operator_gate",
    "reason": "planned goal needs operator opt-in before spending agent turns"
  },
  "source": "latest_run"
}

Fields:

• goal_id: stable public-safe goal id from registry or runtime.
• status: classification or derived state.
• lifecycle_phase: derived state-interaction phase for dashboard grouping.
• lifecycle_flags: all compact phases that apply to the latest goal state.
• waiting_on: one of user_or_controller, codex, external_evidence, monitor_signal, or controller.
• severity: high, action, or watch.
• recommended_action: exactly one user-facing next action from the adapter or status layer.
• operator_question: optional human-facing gate to show in the LoopX operator view. Dashboard action cards should treat this as the primary first-screen question when it is present.
• agent_command: optional target-agent command or instruction that becomes valid only after the operator gate is approved.
• quota: optional compact compute-quota state. It should explain whether a goal is eligible, throttled, waiting, paused, or operator-gated before an automation spends another agent turn.
• user_todos: optional active-state checkbox summary for the human/operator. Dashboard consumers should surface the first unfinished item before generic gate prose when present.
• agent_todos: optional active-state checkbox summary for Codex/project agents. This belongs in status/CLI and handoff context; it does not replace a user/controller gate.
• source: contract, registry, run_history, or latest_run.

Summary Counters

The queue summary keeps controller handoff visible:

• needs_user_or_controller: counts both waiting_on=user_or_controller and waiting_on=controller.
• needs_controller: counts only goals waiting for a target controller or adapter connection.
• needs_codex: counts goals ready for Codex action.
• watching_external_evidence: counts goals waiting on outside evidence or metrics.
• watching_monitor: counts monitor-only goals that should stay visible but do not require immediate Codex work.

Classification Mapping

Status treats these as user/controller attention:

• needs_controller_opt_in
• needs_human_reward
• needs_user_relay
• ready_for_controller_opt_in
• ready_for_user_relay

Status treats these as Codex-ready action:

• controller_opted_in_waiting_for_run
• design_next_experiment
• inspect_eval_result
• inspect_result
• needs_more_read_only_evidence
• needs_validation
• read_only_project_map
• run_validation
• state_refreshed

state_refreshed means a controller updated active state, ledger, or planning docs without running a project adapter. The next Codex action is to inspect the refreshed state and continue one bounded progress segment.

A registry entry can explicitly override first-screen attention with waiting_on, attention_status, recommended_action, operator_question, and next_handoff_condition. This lets a controller keep a refreshed goal in the operator lane when the latest run is fresh but the real next step is still a human or target-controller decision. The override changes status and quota eligibility, but does not grant project-agent execution. If quota later reports safe_bypass_allowed=true, the target heartbeat may work on another bounded read-only steering or analysis item from the active state, but it still must not execute the gated command or any adapter/write/production path.

For complex goals, avoid encoding a whole reading queue in one long recommended_action. Keep recommended_action as one routing sentence, then write explicit checkbox sections in the active state. Project agents should prefer the CLI helper instead of hand-editing section names:

loopx todo add \
  --goal-id <goal-id> \
  --role user \
  --task-class user_gate \
  --blocks-agent <agent-id> \
  --text "Read the short review packet before approving delivery."

loopx todo add \
  --goal-id <goal-id> \
  --role agent \
  --text "Build the next read-only worksheet after the user decision is recorded."

The helper resolves the goal's active state from the registry, creates the canonical section when needed, and avoids duplicate exact todo text. The resulting Markdown shape is:

## User Todo / Owner Review Reading Queue

- [ ] Read the short review packet.
- [ ] Record the owner decision in the worksheet.

## Agent Todo

- [ ] Build the next read-only worksheet after the user decision is recorded.

Status lifts those checkboxes into user_todos and agent_todos, so dashboard attention stays human-readable and agent-facing status remains actionable.

Replanning an obsolete completion dependency

An open advancement Todo with an unmet todo_done wait cannot acquire an execution lease. Directly clearing its wait with released lease history remains fenced. If the original owner has evidence that the wait is obsolete, use the existing administrative lifecycle rather than inventing an execution grant:

1. Read the exact Todo, claim, inactive lease and current provider revision.
2. With a fresh CAS and stable operation identity, run todo update --status blocked --clear-resume-when --reason '<reviewed obsolete dependency>'.
3. Read back the committed blocked state, then use its fresh CAS and a different operation identity for todo update --status open --clear-resume-when --reason '<reviewed new route>'.
4. Acquire a fresh execution lease before editing copy, evidence or work results.

Both updates require the original Goal/Todo/actor arguments plus --update-operation-id and --update-expected-provider-revision. Omit old execution-proof flags and do not bundle ownership, requirements, copy, evidence or completion changes. Keep the dependency when it is still valid. A stale CAS, active holder or unauthorized actor still rejects; planning does not complete the prerequisite, release another actor's work or settle a Turn. The diagnostic recovery.lifecycle_replan describes these steps only for the same claim owner with released history under hard-lease coordination; it does not execute them.

有证据表明原依赖已经过时时，同 owner 可沿现有“blocked → open”生命周期重规划： 每步冷读原任务并用 fresh CAS 和独立幂等标识，只传 status、clear-resume-when 和 reason，不携带旧执行租约、不捆绑文案/证据/要求/归属。两步不授执行权限，之后仍须 取得新的合法 lease；原依赖仍有效时继续等待。恢复诊断提供现有入口，不放宽门禁， 不伪造前置任务完成或 Turn 结算；默认升级与 App/Lark 操作路径须分别验收。

read_only_project_map means a connected read-only project now has a standard map run from loopx read-only-map. The next Codex action should use the map's recommended action or upgrade to a project-specific adapter when needed.

Status treats blocked_by_safety as high-severity user/controller attention.

Status treats classifications prefixed with await_ or monitor_ as external evidence watches.

If a connected goal has no saved run yet, status emits connected_without_run so the next Codex action is clear: run the first read-only adapter tick and save a compact run record.

If a planned high-complexity read-only-map adapter has no saved run yet, status keeps it in user/controller attention, asks the operator gate in LoopX, and exposes loopx read-only-map --goal-id <goal> --dry-run as agent_command. The command is execution context, not approval. The preview appends nothing; a real map run still waits for the target controller to move the adapter to read-only-map-ready or connected-read-only. Agent executors should use loopx --registry "$HOME/.loopx/registry.global.json" quota should-run --goal-id <goal> as the hard compute gate. While the item is still planned, that guard stays should_run=false and omits agent_command, even though status displays the preview command for the human operator. If the guard also reports safe_bypass_allowed=true, the agent can do one independent read-only steering or analysis step that does not depend on this operator gate; it cannot run the preview command until the gate is approved. Before taking that safe-bypass step, the agent should surface the current gate to the user/controller if the same unresolved question was not already asked in the recent visible thread. quota should-run exposes gate_prompt, operator_question, user_todo_summary, and agent_todo_summary so the agent can ask one concrete Chinese question and still see its own safe follow-up checklist instead of silently skipping or forcing the user to inspect the dashboard manually. Markdown status output also prints an operator_gate_dry_run helper before agent_command, so CLI-facing agents see that the operator gate is a user-owned dry-run preview before any project-agent handoff.

After the operator answers that gate, record it with loopx operator-gate. Approved gates produce operator_gate_approved and move the next action to Codex with the approved agent_command; rejected or deferred gates produce operator_gate_rejected or operator_gate_deferred and keep the goal in the user/controller lane with the recorded reason.

If runtime contains an actionable goal that is not in the registry, status emits unregistered_runtime_goal. This is a controller action: either add the goal to the registry so it becomes part of the multi-project surface, or archive the runtime record so old experiments do not look like active work. Watch-only legacy records such as await_* and monitor_* stay in run history without becoming queue items.

Use loopx archive-runtime --goal-id <goal-id> to preview cleanup of an obsolete runtime-only goal. The command only moves files when rerun with --execute.

If the contract check fails, status prepends a high-severity loopx-contract item before project goals.

Bound user-action reminder updates

Under canonical hard_lease, an OPEN role=user, task_class=user_action reminder without a claim or any retained lease may have its text, note or evidence corrected by its exact registered bound_agent. Use todo update with the current --update-expected-provider-revision and a stable --update-operation-id; preview with --dry-run, then read back the result. An exact retry replays the receipt; a changed retry or stale revision refuses. Text keeps the existing title/priority derivation.

This corrects the human-facing obligation without claiming execution authority. It does not change status, binding, ownership, decision scope, work requirements or the original action's execution state. Cross-agent and excluded actors still refuse. A reminder with retained lease history requires the bound actor's current active lease key/version as well as provider CAS. An existing lease does not require or create an agent claim. Expired/released or incorrect proofs refuse; recovery points to inspection of a live proof or acquisition of a fresh lease, never claiming the user Todo. The edit neither renews nor releases the lease. A historical replay proves prior acceptance, not current authority. User gates, unbound actions, agent Todos and bundled non-copy edits retain their ordinary admission. Completing an action uses its separate terminal lifecycle contract. CLI and other transports share the canonical typed update owner; this rule does not activate a notification provider or prove that the reminder was sent.

canonical hard_lease 下，尚无 claim 或租约历史的 OPEN user_action 可由精确绑定的 注册 Agent 更新文案、note 和 evidence。更新复用 provider CAS 与操作幂等；不得借此 改变生命周期、归属、执行要求或决策权限。有租约历史时，同绑定角色必须提供当前有效 租约的 key/version，并通过 provider CAS；无需、也不新增 agent claim。过期、released、 错误凭据仍拒绝，恢复须检查当前凭据或取得新租约；更新不续租或释放，旧回执重放不授予 当前权限。其他角色、被排除角色、user gate、未绑定待办、agent Todo 和非文案混合更新 仍执行原门禁。更新提醒不代表本人已执行， 也不证明通知送达。

Boundary

The queue is safe to show in public docs or a local UI only when goal ids and recommended actions are sanitized. It should not contain:

• local absolute paths,
• internal task ids,
• raw metric values from private systems,
• document links,
• credentials,
• raw prompts or logs.

Project-specific adapters may keep richer private evidence in their own repo or runtime payloads, but the status queue should remain compact and public-safe.

Lifecycle phases are derived by the status layer and should stay separate from adapter classifications. A queue item can keep its domain-specific status while also saying whether the goal is merely connected, mapped, refreshed, adapter-inspected, reward-judged, or controller-ready.