feat(operator-queue): an agent sees its pending asks and can replace one (#3247)

[vybe]

Fixes #3247 — third of the chain #3242 → #3243 → #3247. Stacked on #3253 — base is feature/3243-atomic-asks; the stack merges together (operator, 2026-10-05). Draft until the chain is in.

What

A scheduled run no longer has to re-ask what is already pending: it is shown its own open asks, and it can replace one.

• The agent sees its pending asks. Every composed turn (push, chat and pull-claimed) lists the agent's own pending asks beside the ended ones — request_id (type, age) "title", oldest first, at most 8, then "and N more". It reads the same rows that count toward the open-ask limit, is omitted when empty, and never fails the turn. On public and paid turns the entries carry no title.
• replaces on ask_operator. The predecessor ends as cancelled / disposed_by = agent / reason replaced, the successor is created, and the two are linked (replaces / replaced_by) — one step inside the per-agent locked transaction. An approval is never changed in place.
• A person's answer wins. A predecessor that was answered, cancelled or expired is never touched; the agent gets 409 replaces_ended with ids and enums only. A predecessor past its deadline is expired on the spot and the replace is refused, so supersedes_expired works at once.
• Ownership. Only the agent's own rows with raised_by = 'agent' can be replaced — never a platform-raised, gate or NULL-raiser row, never another agent's. Every such attempt gets one uniform 422 invalid_replaces, and the compare-and-set repeats the check.
• already_pending. An agent-raised approval whose proposal equals one of the agent's own pending agent-raised approvals is refused with 409 already_pending {request_id} unless replaces names it. It runs inside the lock, applies to approvals with a non-empty proposal only, and never refuses or counts a gate or platform raise.
• Surfaces. A replaced ask reads "Replaced by the agent" and names its successor; the successor shows "Replaces …" — Operations cards and detail, /m, the Workspace ask views, get_my_ask. The Workspace names the other ask only when the same person could already see it. No wake fires for the replaced ask.
• Schema. Two nullable link columns on both tracks (Alembic 0090_operator_queue_replace on 0089…).
• Contract text. One clause in the ask_operator description (1,762 characters, under the 1,800 test from feat(operator-queue): atomic asks — authoring rules in the ask_operator contract, option and title limits (#3243) #3253) and the full rule in the replaces parameter; the prompt gains "do not re-ask what is still pending; if the facts changed, replace it".

Rulings carried (orchestrator, on the operator's behalf — plan file)

• T1–T8 as the plan recommended, ruled by the operator 2026-10-05, including T3 the schema change and T8 the already_pending guard (added by the plan, not in the issue).
• Accepted deviation: the two asks name each other by request_id in a badge; the Operating Room has no deep link to a single item.
• This is the narrow slice of abilityai/trinity-enterprise#619; priority inheritance, withdrawal without a successor and the wider correction flow stay there.

Review + security

Correctness + security review (claude-fable-5-1, by reading): MERGEABLE, no critical finding. A separate wide test sweep then found what reading had missed:

• Fixed in b12152f9: the already_pending guard also refused the skill-approval gate's deliberate one-approval-per-occurrence raises (four ent#751 tests red on the branch, green on its base). The guard is now the agent's own. The same commit fixes an older bug the refusal exposed: skill_gate_service read e.status where the exception carries status_code.
• Fixed in cdd31c0f: the guard moved inside the lock (two concurrent identical raises could both insert); approvals with a real proposal only; replaces_ended carries disposed_by and no longer calls every cancel an operator's; no ask titles on public and paid turns; stale "person | timeout" strings.
• b8ad5960 restores docs/user-docs/agents/recommended-fleet-prompt.md to its base content: that page mirrors a canonical prompt owned elsewhere, and its sentence "Only a person ends an ask" is the owner's to reword.
• /cso --diff: nothing supported.

Tests

Reported by the builders on the fix tip: named sets 581 + 382 passed; the 43-file importer sweep in shuffled order 461 + 478 + 489 passed; mcp-server 697 passed, tsc --noEmit clean; frontend unit 267 files / 4,670 passed (before the fix commits, which touch no frontend file). One pre-existing collection error at the base too: test_inter_agent_timeout_unit.py (dispatch_breaker_active missing).

Before merge

• CI on this PR is a reduced set: its base is a feature branch, so backend-unit-test (the shuffled, parallel run) does not run here. That run found an order-dependent failure on the chain's other PR today that no engineer-side run had shown — read the full run once this PR retargets dev before merging.
• Migration number: 0090_operator_queue_replace is the third 0090 in open work (fix(operator-queue): platform alerts are conditions — one pending row per subject (#3246, part 1) #3255, feat(pull): /chat on the durable queue for pull pilots (#3127) #3145). The later ones renumber: file name, revision id and docstring, down_revision, the SQLite migration docstring, ALEMBIC_REVISION in test_3247_replace_ask.py, the database architecture line.
• Conflicts with fix(operator-queue): platform alerts are conditions — one pending row per subject (#3246, part 1) #3255 (platform alerts, same session): 16 files — the queue db layer and schema tracks, the Workspace ask projection, the three operator components, utils/operatorQueue.js, operator_queue.ts, docs. Both add an ending author (platform there, agent here): keep both. Landing fix(operator-queue): platform alerts are conditions — one pending row per subject (#3246, part 1) #3255 first means resolving them once, here.
• Other open PRs: beyond the feat(operator-queue): atomic asks — authoring rules in the ask_operator contract, option and title limits (#3243) #3253 base this branch adds a conflict with feat(workspace): Discuss and Dismiss on asks (abilityai/trinity-enterprise#747, #748) #3181 (operating-room.md) and feat(pull): /chat on the durable queue for pull pilots (#3127) #3145 (db/migrations.py).
• The whole stack merges cleanly with live dev (493d2a6).

Handoffs

• The canonical fleet prompt's rule "Only a person ends an ask" — owner's decision whether to mention the agent's own replace.
• abilityai/trinity-enterprise#619 keeps the rest of the correction flow.

🤖 Generated with Claude Code