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

[vybe]

Fixes #3247 — third of the chain #3242 → #3243 → #3247. The base is dev: #3253 and #3255 have landed, and this branch carries a merge of dev on top.

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), 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. No entry carries the ask's title on any turn: a trigger label does not say who reads the reply, so the read behind the line does not select it, and get_my_ask returns it. A pending row the agent did not raise itself is listed as not replaceable.
• 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 0097_operator_queue_replace on 0096_a2a_internal_scope).
• 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 (later widened to every turn, see Review rounds); 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).

Review rounds

• 2026-10-06 (three blocking points, all fixed in 02ec804de): titles decided by an allowlist of triggers instead of a denylist; the order-dependent collide test; a test that a replace never edits the old ask in place. The migration was re-parented to 0097.
• 2026-10-08 (one blocking point, fixed in 4ef09d16b): the allowlist still showed titles on three triggers whose reply can go to someone other than the owner or an operator (operator_response, schedule, agent). Titles are now off the line entirely. The same commit adds the commit-lag check to the replace's two ending writes, marks rows the agent cannot replace, sends a refresh trigger when a replace expires an overdue ask, and tests 0097's upgrade().

Before merge

• Not run anywhere: an alembic upgrade from 0096 on an existing PostgreSQL with rows (CI upgrades a fresh database only), and a real end-to-end turn on the Workspace, schedule-delivery and delegated-agent routes.
• Left in place, unused since the guard moved inside the lock: db/operator_queue.py::list_pending_proposals_for_agent, database.py::list_pending_operator_queue_proposals, ask_service.AGENT_ENDING_REASONS.

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

[vybe]

Re-parented onto dev (2026-10-06). The stacked base #3253 squash-landed this morning, so the 11 branch commits were rebased onto origin/dev (git rebase --onto origin/dev origin/feature/3243-atomic-asks — clean, no conflicts) and the PR base is now dev. History is rewritten (force-with-lease); nothing else changed.

Local evidence on the rebased head 0752863a8:

• pytest tests/unit/{test_3247_replace_ask,test_1402_prompt_contract,test_ent329_operator_resume,test_ent611_ask_endings,test_ent611_native_ask,test_ent715_queue_person_fields,test_ent751_skill_gate_enforce,test_alembic_revision_id_length}.py → 591 passed
• vitest run operatorQueueReplace.spec.js workspaceReplacedAsk.mount.spec.js rawColorRatchet.spec.js loadingGateRatchet.spec.js → 37 passed
• mcp-server: tsc --noEmit clean, npm test → 720 passed
• scripts/ci/check_alembic_heads.py → 1 head (0090_operator_queue_replace, down 0089)

Still owed per the merge-train note on #3255: once #3255 lands, this branch's 0090_operator_queue_replace re-parents onto #3255's 0090 revision (disjoint tables, mechanical). It cannot be done earlier without breaking the chain on this PR's merge ref.

[github-actions]

✅ Alembic head check clear — merging this PR into dev leaves one head (0096_a2a_internal_scope).

Previously flagged; resolved.

Advisory — this check does not block merge. · head_sha: 4ef09d16b1d27c594ff342075d502d496493d3c2 · run

[AndriiPasternak31]

Reviewed at 0752863. #3253 is in (merge-base fa50b38), so the base is right.

The core works. I reverted each piece in a scratch copy, and the matching test went red every time:

• the atomic replace (cap rollback, collision rollback)
• the answered-first race and its message
• own-asks-only (other agent, gate row, platform alarms)
• the open-ask limit after a replace
• the contract text (the MCP description and both prompt copies)
• "Replaced by the agent" and the successor link on the Operating Room, /m, the Workspace and get_my_ask
  In total, 20 of 22 mutations went red.

Three changes before merge:

1. Titles on outside turns. _OUTSIDE_AUDIENCES = {"public", "paid"} (platform_prompt_service.py:55) is a denylist. Channel turns dispatch with triggered_by set to the channel type (telegram / slack / whatsapp, message_router.py:871), and voip, room and a2a aren't in it either. I checked: an ask titled "Refund 900 USD to customer X" shows its title in the Pending asks line on all of those. Could we flip it to an allowlist of owner/operator triggers, like canvas_service._OPERATOR_SIDE_TRIGGERS, and add telegram plus an unknown label to the outside-turn test?

2. Order-dependent test. test_a_colliding_insert_after_the_cas_rolls_the_replace_back fails whenever test_1595_sync_health_signals.py runs first ("created" != "replayed"), because the patch lands on a stale OperatorQueueOperations. Repro (I re-ran it: 1 failed; the file alone is 76/76):

pytest tests/unit/test_1595_sync_health_signals.py tests/unit/test_3247_replace_ask.py -p no:randomly

Fix: patch type(real_db._operator_queue_ops), both the real_cas read and the setattr, as test_ent611_native_ask does. With that, the pair passes and the test still catches a half-replace.

3. "Never edited in place" has no test. If the CAS also overwrote the predecessor's title, all 76 tests would stay green. One assertion that the old ask's title, question, options and proposal are unchanged after a replace would pin it.

Migration / rebase: #3255 has landed, so this branch now conflicts with dev (the files the PR body predicted), and 0090_operator_queue_replace forks against dev's 0090_platform_alert_subjects. #3145 (0091) and #3269 (0092) are on today's train, so re-parent onto whatever dev's head is when you merge it in. If both land, that is 0093_operator_queue_replace on 0092_portal_messages_attachments; I checked that this gives a single head. ALEMBIC_REVISION / ALEMBIC_PARENT in test_3247_replace_ask.py:36-37 move with it. The findings above are in files that don't conflict, so they still apply after the merge.

Smaller, not blocking:

• If the agent wins the race, a person who then answers is told "This ask was just answered elsewhere" (client_portal/asks/service.py:492/502). Nobody answered; the agent replaced it. That case deserves its own message.
• The Pending asks line also lists NULL-raiser rows (legacy file rows, skills-reconcile- / retention-guard- alarms). The agent is told to replace them, but replacing one gets 422 invalid_replaces.
• The PR body still says "stacked on #3253 / draft until the chain is in".

Not verified on my side: PostgreSQL (CI has no PG pytest), and shuffled full-suite seeds other than CI's 12345.

[github-actions]

✅ Nightly unit-suite clean when this PR is merged into dev, all 3 seeds (head_sha: 4ef09d16b1d27c594ff342075d502d496493d3c2).

[github-actions]

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

[vybe]

@AndriiPasternak31 your 10-06 review is addressed in 02ec804de, on top of a dev merge (d27c2d3c3). Ready for re-review.

Blocking

1. Titles by allowlist. Confirmed: _OUTSIDE_AUDIENCES = {public, paid} let channel (telegram / slack / whatsapp), voip, room and inbound a2a turns show ask titles. Replaced with _OWNER_OR_OPERATOR_TRIGGERS; any other label, and no label, gets request_id (type, age) only. test_an_outside_turn_lists_ids_type_and_age_without_titles now also covers those labels plus an unknown one, "" and None: 9 failed before, all pass after.
2. Order-dependent collide test. Reproduced (test_1595_sync_health_signals.py first: 'created' == 'replayed'). It patched a stale imported class; it now patches type(real_db._operator_queue_ops). Passes in both orders, and removing the rollback still turns it red.
3. "Never edited in place" had no test. Confirmed by mutation: with the CAS also writing title, the file stayed green. Added test_a_replace_never_edits_the_old_ask_in_place; under that mutation only it fails.

Migration. Re-parented onto dev's current head: now 0097_operator_queue_replace with down_revision = 0096_a2a_internal_scope. Heads guard: 98 revisions, 1 head. Parity guard passes. SQLite entry sits last in migrations.py.

Smaller

• (a) Fixed: a person who loses the race to a replace is now told the agent replaced the ask, not that it was answered elsewhere. Same 409 already_resolved.
• (b) Not changed, open question: the Pending asks line still lists NULL-raiser rows the agent cannot replace. Filtering it would break the deliberate line-equals-budget-predicate pin, so this needs a decision rather than a patch.

Open for discussion

• Allowlist membership. It is the canvas_service._OPERATOR_SIDE_TRIGGERS set plus user and agent. As a result self_task, fan_out, system, voice and a missing label showed titles before and now show ids only. Say if any should count as owner-side, or if agent should be outside like a2a.

Merge notes. 17 textual conflicts, both sides kept. Two were semantic: ResolvedCard.vue and queueEnding in operatorQueue.js now handle both the platform ending from dev and the agent ending from this PR.

Local results. 354 related unit files: 10890 passed. Full unit suite, seed 12345: 24536 passed, 4 failed, the same 4 local pin-parity failures as on dev. mcp-server typecheck clean, 825 tests passed. Frontend 5060 tests passed. Not run locally: a real PostgreSQL alembic upgrade head, integration tests, other seeds.

[vybe]

merge-train: pushed 2203d37ce to this branch — a merge of dev (f6bedcd81) with tests/registry.json rebuilt from the merge stages (dev's entries plus this branch's three #3247 entries, 453 unique). That was the only conflict; no other file was touched. Alembic heads on the merged tree: 98 revisions, 1 head (0097_operator_queue_replace).

Not merged this batch: it waits for @AndriiPasternak31's re-review. Validation at 02ec804de confirmed his three blocking points by mutation (adding telegram to the allowlist turns the outside-turn test red; the #1595 + #3247 pair passes in both orders; overwriting title in the CAS turns only test_a_replace_never_edits_the_old_ask_in_place red), with no CRITICALs.

Open for that re-review:

• agent is in _OWNER_OR_OPERATOR_TRIGGERS, while canvas_service._OPERATOR_SIDE_TRIGGERS leaves it out. A caller agent may itself be serving a channel or public turn, so titles could relay outward.
• self_task, fan_out, system and voice turns now get ids only (fails closed).
• Dead after the guard moved inside the lock: db/operator_queue.py::list_pending_proposals_for_agent, database.py::list_pending_operator_queue_proposals, ask_service.AGENT_ENDING_REASONS.
• The PR body still says "Stacked on feat(operator-queue): atomic asks — authoring rules in the ask_operator contract, option and title limits (#3243) #3253 / draft" and 0090… on 0089….

[AndriiPasternak31]

Blockers 2 and 3 from 10-06 and the migration are fixed, and I checked each by mutation. Blocker 1 is fixed for channels but not for the whole class: three triggers on the new allowlist also run turns whose reply goes to someone who is not the owner or an operator.

Re-reviewed at 02ec804de (merge d27c2d3c3 on dev 82b99c302, plus F4). Full unit suite, CI's command (seed 12345, --dist loadfile, Python 3.13): 24548 passed, 0 failed. The base 82b99c302 gives 24456 passed, 0 failed. The nine touched backend test files: 630 passed on each of seeds 12345, 67890 and 99999. Touched frontend specs: 37 passed. pg-migrations on this head ran 0096_a2a_internal_scope -> 0097_operator_queue_replace.

Since then, 2203d37ce (the merge-train's merge of dev) landed. It touches none of the files cited here except tests/registry.json, so everything below still holds at that head. The suite numbers above are from 02ec804de.

What I verified from the 10-06 review

• 1. Titles by allowlist (platform_prompt_service.py:59-64, :1028). I put the {public, paid} denylist back, and 9 cases went red on 3/3 seeds: telegram, slack, whatsapp, voip, room, a2a, an unknown label, "" and None. Adding telegram to the allowlist turns exactly that case red. Setting inside = False turns the five owner-side cases and both composer tests red. So the test catches errors in both directions. The membership still has a problem; see Blocking 1.
• 2. Order-dependent collide test (test_3247_replace_ask.py:270-288). With the old import back, your repro pair goes red ('created' == 'replayed') and the file alone stays green. So the fix is what makes it order-independent. Removing the collision rollback (operator_queue.py:473-474) goes red alone and after test_1595, on 3/3 seeds. The pair now passes in both orders (99/99).
• 3. Never edited in place (test_3247_replace_ask.py:159-182). I made the CAS also write title, then options, then proposal. Each time that one test went red and nothing else did, on 3/3 seeds.
• Migration. 0097_operator_queue_replace sits on 0096_a2a_internal_scope. check_alembic_heads.py reports 98 revisions and 1 head, both on this tree and on an in-memory merge with today's dev (a18b02437). The SQLite entry is last (migrations.py:5693), ALEMBIC_REVISION / ALEMBIC_PARENT moved (test:36-37), and nothing still refers to 0090_operator_queue_replace.
• (a) Race message (client_portal/asks/service.py:506-509). Removing it turns test_answering_an_ask_the_agent_just_replaced_says_so red on 3/3 seeds. When a person wins the race, the message still reads "answered elsewhere".
• (b) NULL-raiser rows. This is partly resolved, but by the dev merge, not by this PR. #3246 reserved skills-reconcile- and retention-guard- (operator_queue_service.py:253-255), so those alarms are off the line now. I probed it: a reserved alarm row is not listed, but a legacy NULL-raiser row still is, with "replace it". Replacing it gets 422 invalid_replaces.
• (c) PR body. Still says "Stacked on #3253", "Draft until the chain is in", and 0090.

Blocking

1. Ask titles still reach people outside the owner and operators, on three allowlisted triggers. The allowlist decides by trigger label, but these labels also run turns whose reply goes to someone else:

   • operator_response. When the addressee answered in the Workspace, the resumed run takes their discussion chat as its destination. The run is told "Your final reply is posted to them in that chat, verbatim" (operator_resume_service.py:98, :136-161, :276).
   • schedule (and a manual or webhook fire of that schedule). A schedule with deliver_to_workspace_email runs as that person's seat and posts its result to them (src/scheduler/service.py:1223, routers/internal.py:511-525).
   • agent. A delegated child copies its parent's Slack or Telegram thread onto its own row and reports into it (chat_execution_service.py:1228-1243, :1705).

   I probed compose_system_prompt with each of these labels and an agent ask titled "Refund 900 USD to customer X": the full title is on the Pending asks line every time. I traced the delivery side in the code but did not run a real turn.

   Two weaker cases are on the same list. mcp is also the inline email sign-in path, which the code itself treats as public-facing (mcp_auth_service.py:64, :355-378). And chat / mcp are what a connector key produces (dependencies.py:745-760).

   Either fix is fine with me:

   • (a) Drop titles from the line. request_id (type, age) is enough for "don't re-ask", and get_my_ask returns the title when the agent needs it. This is the simplest fix, and the allowlist goes away with it.
   • (b) Keep titles, but decide by where the reply goes, not by the label. Show titles only when the trigger is on the list AND the execution row has no source_channel or Workspace destination. That is the question turn_audience.audience_of already answers (turn_audience.py:155-186). ExecutionContext has execution_id but not the destination, so this needs plumbing plus a test for each of the three routes above.

   This also answers your open question about agent: going by the label alone, it can't count as owner-side.

Should fix

• The replace's ending write skips the lag check from the dev merge. _note_commit_lag (operator_queue.py:31-52) arrived with the merge, and its docstring says it is "called by the five writers that end an ask". The replace CAS (operator_queue.py:505-521) and the expire-now in the same function (:534-538) are two more writers that stamp disposed_at, and neither calls it. test_ent815_queue_walk.py:296 also walks only the five. The fix is one call after the replace transaction commits, plus adding the replace to that test's writer list.
• (b), what's left. Keep the NULL-raiser rows on the line so it still equals the budget, but stop telling the agent to replace those entries. Mark them instead, e.g. legacy-1 (approval, 7d, not replaceable). That needs one more selected column (raised_by) in list_pending_asks_for_agent (operator_queue.py:994-1021), and it keeps the line-equals-budget pin.
• PR body. Update the stacked, draft and 0090 lines.
• Merge dev again. Done in 2203d37ce. The only conflict was tests/registry.json.

Nits

• ask_service.py:958-961 still says the platform files alarms "with a NULL raiser and an unreserved prefix (skills-reconcile-, retention-guard-, …)". Those prefixes have been reserved since #3246.
• No test runs 0097's upgrade(). I emptied it and every test stayed green. pg-migrations can't catch that either: 0001_baseline builds the head schema, so on a fresh PostgreSQL 0097 does nothing. Only an existing PostgreSQL install ever runs that ALTER. Other revisions follow the same pattern. One test that calls upgrade() against a recording op would pin it.
• The expire-now on a replace (ask_service.py:624-634) is announced with no broadcast trigger, and outside the poller cycle that normally sends one. So an open page shows the ask as pending until its next poll. It's small.

Not verified on my side: an alembic upgrade from 0096 on an existing PostgreSQL with rows (CI only upgrades a fresh database), full-suite seeds other than 12345, and real end-to-end delivery on the three routes in Blocking 1.

Dismissed on the author's instruction to merge. The 2026-10-08 blocking point (ask titles on the Pending asks line) is fixed in 4ef09d1 by option (a): titles are off the line and the read no longer selects them. The same commit adds the commit-lag check to both replace writers, marks non-agent rows not replaceable, sends the refresh trigger and tests 0097's upgrade(). All checks green at that SHA. Not re-run by mutation here.

[trinity-ability]

Approved at 4ef09d1 on the author's instruction after /validate-pr: Lane C+schema, all checks green, one Alembic head against dev. The fix for the 10-08 review was confirmed by reading, not by mutation.