Repository navigation
refactor(operator-queue): operator_queue_service becomes a package, and its collaborators are bound once in deps.py (#3785, PR 1 of 4) - #4036
Conversation
… seam create_bounded_alert(_outcome) keep their signatures and outcome contract and become a thin delegate of platform_alerts.observe, which already composes the per-(agent, type) budget inside its one locked create. The registered type names its kind; the key is read back from the item's id and context by derive_legacy_subject and must resolve to that same kind, else ALERT_FAILED_CREATE. The two kinds whose ids carry no subject (gitignore, problem report) are keyed by the request id minus the kind's prefix. observe's "updated" and "snoozed" pass through; "failed" maps to ALERT_FAILED_CREATE; every refused or failed arm logs [#1677 budget]. ALERT_FAILED_COUNT stays importable and is no longer returned. The budget episode reports through observe as kind alert_budget keyed by the budgeted type: one alert_budget:<type> row per agent, re-read by a later refusal outside the cooldown, ended by its 14-day lifetime. The bucketed id and its own operator_queue_new broadcast are gone; observe sends the thin operator_queue_sync trigger. Ratchet: create_bounded_alert_outcome and _maybe_emit_alert_budget_episode leave EMITTERS_NOT_YET_ON_SEAM; alert_budget gets a NO_CLEAR_SITE reason. Census: both leave _ALLOWED_CALLERS (no direct create left in either). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_budget: write-observation point. The harness stands in for the seam's create with the same budget arithmetic and runs what observe spawns. Id shape in test_deterministic_bucketed_id_with_reserved_prefix, test_cooldown_knob_zero_never_raises (the subject replaces the bucket) and test_under_cap_creates_item_and_notification (the seam's id). The episode raise now stays in its spawned task, so test_episode_helper_raise_swallowed_refusal_stands reads the delegate's WARNING marker; test_ws_broadcast_failure_swallowed checks the thin operator_queue_sync payload. - test_3130_flood_guard, test_1632_operator_queue_caps: write-observation point. The flood alert still rides the delegate, so its writes, the typed budget read and the I1 fault injection move to the seam's create. - test_3243_atomic_asks::test_a_cap_hold_never_fires_the_flood_alert: write-observation point. Watched at observe, since the oqs.db assertion alone would now pass whether or not the alert fired. Known until the problem report moves in its own commit: nine test_3521_problem_report_comment cases are red here. The delegate files an event-kind row under the seam's id, which the old _attach_comment (keyed on the pre-seam request id) cannot find. New: tests/unit/test_3254_budgeted_alerts.py (registry parity, reach-back imports, the delegate's outcome table over all five budgeted types, the episode's seam properties, R1 for alert_budget). Part of #3254
…s with its episode OperatorQueueSyncService._maybe_emit_flood_alert reports through platform_alerts.observe as kind queue_flood keyed by the reason: one pending row per (agent, reason), rewritten in place, budgeted by the seam. #3130's outcome rule is kept on observe's strings: a failed write releases the episode and is retried after the cooldown (I1); created, updated, snoozed and refused consume it. While an episode lasts it is re-read at most every 6 hours, so the kind's 14-day lifetime ends only a row nobody re-read, never a condition that still holds. The refresh time per (agent, reason) is a dict the method creates on the instance for itself; __init__ is unchanged. The flood's own operator_queue_new broadcast (which carried the title) is gone; observe sends the thin operator_queue_sync trigger. The two _sync_agent statements where an episode ends (_flood_episodes.discard for oversize_file and ingestion_cap) become calls to the new _end_flood_episode, which ends the episode and, only when one was running, ends its alert as the platform through platform_alerts.clear. A cycle with no episode costs no read. Ratchet: _maybe_emit_flood_alert leaves EMITTERS_NOT_YET_ON_SEAM; queue_flood's clear site is _end_flood_episode. No re-pin in this commit: the #3130 and #1632 harnesses were moved to the seam's create in the previous commit and keep their results. Tests: the flood through the real _sync_agent poll for 30 simulated days with the real expiry sweep (one row, re-read every 6 hours, ended as the platform when nothing is held), no read without an episode, two reasons two subjects, I1 on the real seam, a person's ending standing through the re-read and the clear, the thin trigger, R1 for queue_flood. Part of #3254
…ugh the seam _on_unguarded_effect reports a refused effect through platform_alerts.observe as kind effect_unguarded keyed "<effect_type>:<reason>": one row per agent, effect and reason, rewritten by each further refusal, ended by its lifetime (nothing observes an agent starting to send ids). The send is refused whatever the alarm's outcome. _alert_skill_not_found reports through observe as kind skill_not_found keyed by the truncated command: one row per agent and command, re-read by each scheduled run. The paired notification is sent only on "created": a repeat of a pending command is an "updated" reading and already had one; refused, failed and snoozed wrote no new row. The pre-create dedup read stays and now matches only a pending pre-#3246 row (no subject), which keeps standing for its command until the upgrade sweep stamps it; a seam row is re-read through observe, where a repeat is never refused at the cap. task_execution_service.py: only _alert_skill_not_found changes. Its module-level utc_now_iso import is now unused and is left in place. Ratchet: _on_unguarded_effect and _alert_skill_not_found leave EMITTERS_NOT_YET_ON_SEAM; skill_not_found gets a NO_CLEAR_SITE reason (only the dispatch path could see a command resolve, and there the detector cannot tell "resolved" from "not a slash command"). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_emitters:: test_skill_not_found_emitter_is_routed_not_allowlisted: the module must call platform_alerts.observe naming "skill_not_found" (AST), the seam that composes the budget, instead of mentioning create_bounded_alert. - test_2392_effect_guard_fail_closed: write-observation point and id shape. The alarm is recorded at platform_alerts.observe instead of a sys.modules stub of operator_queue_service, which lacks the names the seam reaches back for. The id prefix is asserted on the kind; the at-budget case returns the seam's refused_at_budget. - test_ent879_aauth_resource_route (the refused-call case): the dead create_bounded_alert patch moves to platform_alerts.observe. Tests: the effect refusal's seam properties and lifetime; the missing skill's one row per command, no notification on a repeat, a pre-seam row still standing, no notification at the cap; R1 for both kinds; the other shape, the clock 30 days ahead: a full skill_not_found budget frees itself through the real expiry sweep and a new command files. Part of #3254
_emit_gitignore_untracked_alert reports through platform_alerts.observe as kind gitignore_untracked, which stops being an event kind (platform_alerts.py: event=True dropped). It is a must-act kind: no lifetime, never ended by the platform. It is keyed by the change itself: a 32-hex digest of the canonical, direction-tagged set of paths the Push untracked and newly un-ignored (sorted removed paths, the exact removed count, sorted un-ignored paths). A repeat of the same set collapses onto one row; a different set, a different total behind a capped list, or the same path in the other direction is a different row. Keying per agent would let a later Push overwrite an earlier Push's path list on a pending must-act alert, which #2529 calls the surface that outlives the session. The legacy prefix keeps its _no_subject parser, so pre-existing rows stay pending until a person acts. Ratchet: _emit_gitignore_untracked_alert leaves EMITTERS_NOT_YET_ON_SEAM. #3254 re-pins (asserted outcomes unchanged): - test_2529_gitignore_precedence: write-observation point and id shape. The alert is watched at platform_alerts.observe (the two create.await_count == 0 checks would otherwise have gone vacuous); the per-agent id prefix is asserted on the kind, with the 32-hex key. - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: gitignore_untracked is a condition now, so it is asserted keyed and the problem report stays the event example. Tests: a repeated set is one row that never expires; distinct sets and a capped list with another total stay distinct; the direction tag holds; a person's ending stands; the 30-day case now also shows the gitignore row still pending. Part of #3254
… and day raise_problem_report reports through platform_alerts.observe as kind workspace_problem_report, which stops being an event kind (event=True dropped). It is keyed by the 32-hex digest _problem_report_id already computes: one row per person per target per UTC day, the "never duplicates" rule its docstring states. A person must act on it, so it never expires and the platform never ends it. The workspace-problem- id prefix is kept, so ent#866's owner-only rule and the machine-key "about a person" exclusion still hold. It returns True when the row was created or updated, False when snoozed, refused or failed. #3521's words-only rule moves under the seam's lock. observe gains keep_text (passed through database.create_platform_operator_queue_item to create_platform_item and _touch): with keep_text and a pending row, the reading only counts (last_seen_at, seen_count, expires_at) and the title, question, priority and context stand. The bare click passes keep_text, a reading with words does not. The click and the comment are two background requests that meet on one row inside the per-agent lock, so either order ends with the words. With no pending row the reading files as usual. update_pending_problem_report (database.py, db/operator_queue.py) and the nested _attach_comment are removed: one write path. Ratchet: raise_problem_report leaves EMITTERS_NOT_YET_ON_SEAM, which fixes the nine test_3521 cases the delegate commit left red. #3254 re-pins (asserted outcomes unchanged): - test_3521_problem_report_comment: the acknowledgement fixture goes through ask_service.answer (fixture shape; a raw status UPDATE carries no person ending for the snooze to read); the accessor test asserts the same type guard at the seam (a foreign row under the report's old id is never written); the lost-race test injects the bare click's whole reading, in its own thread, before the comment's locked create. - test_ent499_problem_report: write-observation point. The fake moves from create_bounded_alert to platform_alerts.observe; the routing AST test asserts the call to observe. - test_ent715_queue_person_fields: update_pending_problem_report leaves _NON_ROW_ACCESSORS (the accessor census forbids a stale entry). - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: no built-in kind is an event any more, so the property is pinned on a kind registered for the test, and both former events are asserted keyed. test_ent866_problem_report_owner_only is unchanged. Tests: keep_text at the sink, both interleavings keeping the words, one must-act row per person, target and day, the owner-only prefix, the delegate and the emitter landing on one subject, a person's ending not rewritten or reopened; the 30-day case now also shows the report still pending; the five-type admission test asserts every kind keyed. Part of #3254
…e's lock
observe checks the snooze before the create's lock. Two moments let a
person's ending slip past that check: an acknowledgement after observe
read the pending row but before the locked create (the locked find then
misses), and one between the locked find and _touch's compare-and-set
(the lock covers creates, not respond_to_item, so the CAS loses). Either
way the create fell through to an insert, and the alert a person had just
ended was back at once. Before this batch most of the moved writers had a
deterministic id that could not re-file after an ending, so the moves
would otherwise ship that regression.
create_platform_item gains snooze_since and a snoozed predicate. On the
insert path, after a missed find or a lost CAS and inside the same locked
transaction, it reads the newest person-ended row for the subject through
the transaction's own connection (the public lookup opens another one)
and returns {"outcome": "snoozed"} without inserting when the predicate
says so. observe passes the standard 7-day window, computed on its own
rather than from the pre-lock check's conditionally assigned cutoff, and
lambda ended: _snoozed_by(kind, ended, priority, context). The pre-lock
check stays as the fast path. A caller that passes neither keeps the old
behaviour.
The statement behind the public find_person_ended_by_subject becomes
_find_person_ended_by_subject(conn, ...), shared by both reads.
Tests: a person's acknowledgement through ask_service.answer, landed (a)
between observe's read and the locked create and (b) between the locked
find and the CAS, yields "snoozed" and no new row, for the problem
report, an inbox collision as registered on dev, and the flood alarm's
6-hourly re-read. All six cases were red before this commit (a fresh row
was created) and pass with it. On SQLite, BEGIN IMMEDIATE holds every
other writer, so moment (b) lands the ending first and hands both finds
the row as it stood just before it; two real workers are not exercised.
Review fixes carried here (the earlier commits are left as they are):
- OperatorQueueSyncService._maybe_emit_flood_alert: the cooldown is
stamped before every reading, the 6-hourly re-read included. A failed
re-read released the episode with the cooldown stamp still 6 hours
old, so it was retried on the next 5-second cycle. New test: a failed
re-read is retried no sooner than the cooldown (red before the fix).
- test_3521_problem_report_comment (the lost-race re-pin): asserts the
bare click's own request returned True and left a pending, comment-free
row before the comment's locked create ran, so the test cannot pass
without the interleaving it claims.
- gitignore_sweep: states that past the probe's 2,000-line cap the key is
the capped list plus the exact total (a full-set digest needs the
in-container probe, outside this change).
- test_1677_operator_alert_emitters: the census's guidance for an
agent-influenceable emitter now points at platform_alerts.observe, not
the delegate the #3246 ratchet counts as off the seam.
- test_3254_budgeted_alerts: the frozen clock also covers
db.operator_queue's ent#815 commit-lag check, which logged spurious
errors against the real clock.
Part of #3254
… end still clears the alert Fresh review of the #3254 budgeted slice (two findings): - A failed 6-hourly re-read of a persisting flood released the episode. If the condition then cleared before the retry, `_end_flood_episode` found no episode and the pending alert waited out its 14-day lifetime, although the code had seen the condition clear (AC 2). A failed re-read now keeps the episode, whose alert an earlier reading filed, and the re-read is retried once the cooldown has passed. A failed first reading still releases the episode (#3130 I1). New test: test_a_failed_reread_keeps_the_episode_so_its_end_still_clears_the_alert (red with the old release branch put back). - AC 8 for two kinds had no "a person's ending is never overwritten" test: `skill_not_found` (the next run is snoozed and sends no notification) and `alert_budget` (a later refusal re-reads the episode and the acknowledgement stands). Both added.
…running methods read In the full serial unit tier, test_1595_sync_health_signals evicts `database` and every `db.*` module from sys.modules and restores only some of them. Afterwards `database.db` and `ask_service.db` run on an older `db.operator_queue` module than the one this suite's clock fixture imports and patches, so the seam's create, the expiry sweep and the answer's compare-and-set read the real clock: rows filed at the frozen T0 read as long expired (five cases red, `AskConflict: expired`, a second flood row). The fixture now also freezes `utc_now_iso` and `datetime` in the globals of the live operations class (R6: patch what the running method reads). Red before: test_1595 followed by this file, 7 failed; green after: 66 passed; the file alone: 55 passed.
…ontent unchanged (#3785) The 2,840-line module moves to services/operator_queue_service/__init__.py byte for byte (100% similarity), the first step of the Invariant #1 split. Every `from services.operator_queue_service import X` and `from services import operator_queue_service` resolves as before. Six path-keyed guards name the file by its path, so their key moves with it (the PR #2487 precedent): _NOT_EMITTERS (test_3246), _ALLOWED_CALLERS (test_1677), _ALLOWED (test_1920), _OQS (test_ent715), FLEET_LEVEL_ALLOWLIST (test_ent467), and the source read in test_ent499. Only the key changes; the rule, the reason text and every assertion are untouched. Part of #3785
…split (#3785) tests/unit/test_3785_operator_queue_package.py pins what S2–S6 must keep while they move code out of __init__, each property derived from the tree so no later slice edits it: modules under 800 lines (__init__ exempt, with a staleness check); the import surface src/backend and tests/ read still resolves; no from-import between package modules; one top-level binding per name; import-time reads defined first and the _MARKER_UNCHANGED default the owner's object; a patch of a re-exported name lands where its readers read; one logger identity; owner-exact qualified reads; no submodule named like a package attribute; one rate_limiter; no method on two classes of the composed service; external imports before the first submodule import, and a failed first import, injected at that line, leaves no stale submodule. The AST scans live in _oqs_package_scan.py (pure stdlib, never imports src). The other shape, a fresh install: each consumer imported first in its own interpreter on an empty database raises a bounded alert (created; only main binds a WebSocket manager, and then exactly one thin operator_queue_sync trigger goes out). Outcomes equal on the base. Part of #3785
…eps.py (#3785) db, _queue_db, principal_reach, get_breaker_redis, ask_service, AgentClient and the audit sink _audit_sync move to services/operator_queue_service/deps.py, bound once and read as deps.X everywhere in the package. They are no longer attributes of the package, so a stale monkeypatch.setattr(oqs, "db", ...) raises AttributeError instead of patching a copy nothing reads (Invariant #1(a), the PR #2487 rule). rate_limiter stays on the package: ask_service reads oqs.rate_limiter.check. Tests that patched a collaborator on the package now patch oqs.deps.X; no assertion, expected value, fixture or control flow changes. The package guard gains G4 (deps binds exactly the collaborators, no other module imports one from its source under any alias or holds one by identity, the package has none) and refuses any reach of a package function's __globals__. Part of #3785
dolho
left a comment
There was a problem hiding this comment.
Review via /review (pre-landing structural review).
/review Report
Branch: AndriiPasternak31/issue-3785-pr1 → AndriiPasternak31/issue-3254-s7 (stacked on #4021; merge-base db8a58e89)
Files Changed: 26 (+1527/-121)
Scope: CLEAN
Plan Completion: #3785 AC for this slice: 1 done / 0 partial / 0 not done / 1 changed / 1 unverifiable
Earlier reviews: none on this PR, so there is nothing to carry forward.
Scope check
- Intent (#3785, PR 1 of 4): convert
operator_queue_service.pyinto a package with no behaviour change, pin the ownership rules in a guard, and bind the collaborators once indeps.py. - Delivered: exactly that.
a83a49dcfis a pure rename at 100% similarity, with 6 path-keyed census re-keys.89f1edf50adds the guard and its scan helper.d2c724b15addsdeps.py(the 6 imports plus the moved_audit_sync), changes 35 read sites todeps.X, and moves the test patches fromoqs.Xtooqs.deps.X.
- No drift.
Plan completion (#3785 acceptance criteria, as they apply to PR 1)
- DONE: "callers do not change". Every production import of the package still resolves. I grepped every
oqs.*,operator_queue_service.*andfrom services.operator_queue_service import …insrc/and in the enterprise submodule (the submodule has no reader). None of them reads a collaborator name that moved (db,_queue_db,principal_reach,get_breaker_redis,ask_service,AgentClient,_audit_sync). G2 of the guard pins this too. - CHANGED: AC3 says "existing tests pass unmodified". About 60 test lines are edited.
- The edits are E1 (re-keying path-keyed censuses) and E2 (moving a collaborator patch to
oqs.deps.X). - The deviation is deliberate and stated in the PR body: once the package stops binding
db, a stalesetattr(oqs, "db", …)raises. - I read every edited line. None changes an assertion, an expected value or control flow.
- The edits are E1 (re-keying path-keyed censuses) and E2 (moving a collaborator patch to
- UNVERIFIABLE: the code-health CC target. It lands in PR 2–4.
Execution coverage (Step 2.5)
| changed symbol / test file | executed by | live consumer | verdict |
|---|---|---|---|
deps.db / deps.AgentClient / deps.get_breaker_redis / deps.ask_service / deps._audit_sync / deps.principal_reach / deps._queue_db (35 read sites) |
test_1525, test_1631, test_1632, test_3130, test_3313, test_2915, test_ent815_queue_walk, … (patched via oqs.deps.X and run) |
__init__.py _sync_agent / _poll_cycle / list_for_principal / aging_hours |
✅ executed |
deps._audit_sync (moved) |
test_2915_operator_queue_sync_honesty.py (patched and asserted) |
__init__.py _apply_sync_state / _apply_delivery_state / _sync_agent |
✅ executed |
test_3785_operator_queue_package.py + _oqs_package_scan.py (AST over the package source) |
itself | the package tree / CI | 🛡 guard. It is source-text by design, its consumer is the tree, and it has runtime legs too (subprocess import order, fresh-install alert). |
6 E1 re-keys (test_3246, test_1677, test_1920, test_ent715, test_ent467, test_ent499) |
themselves | path-keyed census guards | 🛡 guard |
Fix mutation: not applicable. This is a refactor with no fix. Behaviour preservation was checked as follows:
- AST equivalence. I ran my own comparison, independent of the author's script, of the base
operator_queue_service.pyagainst__init__.py+deps.pyatd2c724b15, withdeps.Xnormalised toX. Result: 171 top-level/method units, 0 only-old, 0 only-new. The one difference isdeps.py'sgetLogger("services.operator_queue_service")literal againstgetLogger(__name__), and both resolve to the same logger. - Lint.
ruff --select F,E9is clean on the package, the guard and the scan helper, so there is no unbound name. - Tests. I ran them locally with Python 3.12 and
-p no:randomly:- every test file this PR edits: 1028 passed, 7 xfailed;
- the guard: 29 passed.
Behaviour-preservation checks (the refactor-specific questions)
- Re-exports and monkeypatch targets (Invariant #1(a))
- The seven collaborators are gone from the package (
__init__.py:35,from services import rate_limiteris the onlyservicesimport left), so a stalesetattr(oqs, "db", …)raises. - The
raising=Falseloophole is covered by G7. - No
patch("services.operator_queue_service.<collaborator>")string patch exists intests/. oqs.deps.dbis the samedatabase.dbsingleton the module bound before, so attribute patches (setattr(oqs.deps.db, "get_setting_value", …)) keep the same reach.
- The seven collaborators are gone from the package (
- Import cycles
deps.pyimportsservices.ask_serviceat module level, exactly as the old module did.ask_servicereaches back to the package only function-locally (ask_service.py:251,581,…), so moving the import later in load order creates no cycle. The guard's fresh-install leg, which imports each of the 10 consumers first in a fresh interpreter, passes.
- Duplicated module state
depsholds no package reference (G13 deps-first test) and no mutable state.rate_limiterstays a single binding on the package (O1 d), becauseask_servicereadsoqs.rate_limiter.check.
sys.moduleshygienetests/unit/conftest.py::_POP_PREFIXESpopsdependenciesafter each test.depsbindsprincipal_reachat import, which is the same early binding the old module had. No change.
Critical Findings (block merge)
None.
Informational Findings (review required)
[I1] Lint coverage: the file-level # ruff: noqa: F401 silences unused-import detection for all of __init__ (Confidence: 6/10)
File: src/backend/services/operator_queue_service/__init__.py:17
Evidence: # ruff: noqa: F401, placed above an import block that will keep shrinking through PR 2–4.
- Issue: the directive is meant to protect three names that are read only from outside the package (
time,to_utc_iso,rate_limiter) plus the G13 "external block stays whole" rule. But it switches F401 off for the whole 2.8k-line file for as long as it lives. So a genuinely dead import that PR 2–4, or a later feature, leaves behind in__init__will no longer be flagged. - Suggestion: use per-line
# noqa: F401 # read as oqs.X from outside / kept for G13on the specific imports, or narrow the directive once PR 4 settles the final import block. - This is not blocking. The guard's G13 static check makes the "keep the block whole" intent hard to violate in other ways.
[I2] Process: these stacked PRs have not had the backend unit tier in CI (Confidence: 8/10)
File: .github/workflows/backend-unit-test.yml (pull_request: branches: [dev, main])
- Issue: the base is
AndriiPasternak31/issue-3254-s7, so the checks on this PR are onlychanges,gitleaks,prod-image-smoke,schema-parity,verify-*. Nobackend-unit-testjob has run on this tree. The PR body already says the figures are re-derived at the cut ontodev. - Suggestion: merge only after the retarget to
devtriggersbackend-unit-testand it is green. That includes the 10-subprocess fresh-install leg of the new guard, which takes about 7 s on an idle machine but about 80 s on the loaded box I ran it on.
Clean Categories
- SQL & data safety: no SQL, schema or migration change.
- Race conditions: no new shared state. The leader-lease code is unchanged apart from the
deps.prefix. - Auth boundaries: no route change.
narrow_to_agent_keyreadsdeps.principal_reachwith identical logic. - Credential exposure: none.
_audit_syncis moved unchanged and still logs ids and enums only. - Enterprise disclosure: no
docs/change. - Enum completeness: no new enum or status value.
- Docs staleness: the
docs/memory/architecture/*.mdand feature-flow pointers toservices/operator_queue_service.pyare now stale paths. The PR defers this explicitly to PR 4's sweep, andarchitecture_map.pystill resolves through thesrc/backend/services/**owner glob. This is accepted as planned, not a finding.
Summary
- Critical: 0 (none found)
- Informational: 2 (review recommended)
- Scope: clean
Verdict: APPROVE. The behaviour is preserved, which I verified by AST equivalence, lint and a green local run of every edited test file. Before merging, wait for the unit tier to run after the retarget to dev.
…after an acknowledgement (#3254) A person's ending of a `queue_flood`, `alert_budget` or `gitignore_untracked` row snoozed every later reading of the subject for 7 days, because none of the three kinds had a material key, so `_snoozed_by` was vacuously true. A runaway agent's second flood, a second budget-full episode and a second untracking Push of the same paths were all silent (review C1; dolho on operator_queue_service.py:2800 and gitignore_sweep.py:335). Each reading now carries an episode marker that the kind lists in its `material_keys`: - queue_flood: `episode_started_at`, stamped when the in-memory episode starts. Re-reads of one episode share it; an episode that starts after the condition cleared does not. - alert_budget: `filled_by`, a digest of the ids of the pending rows filling the budget. Re-reads of the same full budget share it; once a slot frees and a new row fills it, it differs. - gitignore_untracked: `push_id`, one per call. The emitter runs once per Push, so every untracking Push after an acknowledgement files; repeats still collapse onto a pending row. So the snooze silences re-reads of the acknowledged episode for the snooze window and a new episode files at once, which makes the `_maybe_emit_flood_alert` docstring's #3130 edge-trigger claim true again. The budget episode's read of the filling rows is classified in the ent#780 row-reader census as internal. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
…ooldown; the oversize end is pinned (#3254) Review follow-ups on the flood alarm: - dolho on operator_queue_service.py:2778 (webmixgamer agreed): the 6-hourly re-read of one reason's episode stamped the per-agent `_flood_alert_cooldown`, so the other reason's first alert could wait up to one cooldown. The cooldown spaces episodes and a re-read is not one, so it is now stamped only before an episode's first reading. A failed re-read's retry spacing already comes from its refresh time. - webmixgamer I3: the 6-hour re-read spacing is one constant, `OPERATOR_QUEUE_FLOOD_REREAD_SECONDS`, read by the gate and by the failed re-read's retry arithmetic, so the two cannot drift. - webmixgamer I1: a `_sync_loop` case serves an oversized file and then a sane one and asserts the row ends as the platform. It goes red when `_sync_agent`'s `_end_flood_episode(agent_name, "oversize_file")` is replaced by a bare episode discard. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
|
On I2 in the review (no |
Resolves the conflict in tests/unit/test_1677_operator_alert_emitters.py: both sides deleted different entries from the same allowlist block (dev, #4018: retention_guard.announce_refusal and the two skills entries; this branch: create_bounded_alert_outcome and _maybe_emit_alert_budget_episode). Both sides' deletions are kept, so none of the five entries survive. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
…flood episode marker (#3254) The episode marker is worker-local. With Redis down the leader lease fails open, so each worker stamps its own episode_started_at and another worker's re-read can file past a person's ending, at most one extra row per extra worker per re-read window. Docstring only; no behaviour change (review L1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
…1/issue-3785-pr1 Carries #4021's review fixes (87ae20f, e3c4b8b), its merge of dev 0b11bd5 and its docstring commit b2ebb02 into the package. Git applied every hunk of the old single-file module to `__init__.py` through the rename, with no textual conflict. One hunk needed a fix that git cannot see: #4021's budget-episode digest (87ae20f) reads the collaborator as `db.list_operator_queue_items`, and this PR binds `db` only in `deps` (S2). As merged it is an unbound name inside a broad `except`, so `filled_by` would be None on every reading. It now reads `deps.db.list_operator_queue_items`, like the other 35 read sites. Ruff F821, the guard's `test_no_unresolved_module_scope_names` and `test_a_new_budget_episode_after_a_person_ending_files_again` each go red without it. AST equivalence of the package against the module at b2ebb02: 177 compared, 0 differ. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
Review I1 (dolho): the file-level `# ruff: noqa: F401` switched off unused-import detection for all of `__init__`, so a dead import left behind by a later slice or feature would go unflagged. At this PR's head `__init__` still reads every name in its import block, so the waiver hid nothing: `ruff check --select F401` gives 0 findings with it removed. It is dropped, and the block's comment now says that a name `__init__` stops reading keeps its line with a per-line waiver naming why (G13, or read as `oqs.X` from outside). PR2, PR3 and PR4 add those per-line waivers where their moves leave a name unread. `deps.py` keeps its file-level waiver: it is a binding module whose imports are its bindings, so there is no import there F401 could rightly flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
…eading (#3785) Review I1 on #4036: PR1 dropped `__init__`'s file-level F401 waiver. This slice's moves leave four of its imports unread in `__init__`; each now carries its own `noqa: F401` with the reason, so F401 keeps checking every other line: - `asyncio`, `base64`, `uuid`: kept for G13, because `listing` and `poller` import them at module level. - `from . import listing`: loads the submodule at its G6 point; the names callers read come from the re-export block. `ruff check --select F services/operator_queue_service/` is clean. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
…eading (#3785) Review I1 on #4036: PR1 dropped `__init__`'s file-level F401 waiver. This slice's moves leave these names unread in `__init__`; each now carries its own `noqa: F401` with the reason, so F401 keeps checking every other name: - `datetime`, `timedelta`, `timezone`, `Sequence`, `options_cap_violation`, `title_cap_violation`: kept for G13, because `rows`, `filechannel` and `ingest` import them at module level. - `rate_limiter`: O1(d), read as `oqs.rate_limiter` from outside (`ask_service`, tests) and as `_oq.rate_limiter` in `ingest`. - `to_utc_iso`: read as `oqs.to_utc_iso` from outside (`test_ec_operator_queue_properties.py`) and kept for G13. - `from . import filechannel` / `rows`: load the submodules at their G6 point; the names callers read come from the re-export block. The `typing` and `utils.helpers` imports become parenthesised so the waiver sits on the one unread name, not the whole line. They stay single statements: splitting one into two breaks the guard's failed-first-import leg, which injects the failure at the module's first statement. `ruff check --select F services/operator_queue_service/` is clean. With every waiver stripped in a scratch copy, the F401 findings are exactly the waived names, and an injected dead import is still reported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
…eading (#3785) Review I1 on #4036, at the slice where the import block is final. PR1 dropped `__init__`'s file-level F401 waiver; PR2, PR3 and the integration added per-line waivers for the names their moves left unread. This slice leaves two more: - `utc_now_iso`: kept for G13 (`poller`, `filechannel`, `ingest`, `write_back` and now `flood` import it at module level); - `from . import alerts`: loads the submodule at its G6 point; the names callers read come from the re-export block. `hashlib` and `deps` are read in `__init__` again since #4021's budget episode digest (`deps.db.list_operator_queue_items`, `hashlib.sha256`), so they carry no waiver. With every waiver stripped in a scratch copy, the F401 findings are exactly the waived names (16 per-line, plus the four re-export blocks), and an injected dead import is still reported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw
# Conflicts: # src/backend/services/operator_queue_service/__init__.py # tests/registry.json # tests/unit/test_1632_operator_queue_caps.py # tests/unit/test_1677_operator_alert_budget.py # tests/unit/test_1677_operator_alert_emitters.py # tests/unit/test_3130_flood_guard.py # tests/unit/test_3246_platform_alerts_registry.py # tests/unit/test_3254_budgeted_alerts.py
|
merge-train (2026-11-01): the base branch
Locally: |
tests/registry.json rebuilt from the git stages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
merge-train (2026-11-02): pushed Validated at
|
… the poller core into PollerCoreMixin (#3785, PR 2 of 4) (#4037) * fix(operator-queue): the #1677 helper delegates to the platform-alert seam create_bounded_alert(_outcome) keep their signatures and outcome contract and become a thin delegate of platform_alerts.observe, which already composes the per-(agent, type) budget inside its one locked create. The registered type names its kind; the key is read back from the item's id and context by derive_legacy_subject and must resolve to that same kind, else ALERT_FAILED_CREATE. The two kinds whose ids carry no subject (gitignore, problem report) are keyed by the request id minus the kind's prefix. observe's "updated" and "snoozed" pass through; "failed" maps to ALERT_FAILED_CREATE; every refused or failed arm logs [#1677 budget]. ALERT_FAILED_COUNT stays importable and is no longer returned. The budget episode reports through observe as kind alert_budget keyed by the budgeted type: one alert_budget:<type> row per agent, re-read by a later refusal outside the cooldown, ended by its 14-day lifetime. The bucketed id and its own operator_queue_new broadcast are gone; observe sends the thin operator_queue_sync trigger. Ratchet: create_bounded_alert_outcome and _maybe_emit_alert_budget_episode leave EMITTERS_NOT_YET_ON_SEAM; alert_budget gets a NO_CLEAR_SITE reason. Census: both leave _ALLOWED_CALLERS (no direct create left in either). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_budget: write-observation point. The harness stands in for the seam's create with the same budget arithmetic and runs what observe spawns. Id shape in test_deterministic_bucketed_id_with_reserved_prefix, test_cooldown_knob_zero_never_raises (the subject replaces the bucket) and test_under_cap_creates_item_and_notification (the seam's id). The episode raise now stays in its spawned task, so test_episode_helper_raise_swallowed_refusal_stands reads the delegate's WARNING marker; test_ws_broadcast_failure_swallowed checks the thin operator_queue_sync payload. - test_3130_flood_guard, test_1632_operator_queue_caps: write-observation point. The flood alert still rides the delegate, so its writes, the typed budget read and the I1 fault injection move to the seam's create. - test_3243_atomic_asks::test_a_cap_hold_never_fires_the_flood_alert: write-observation point. Watched at observe, since the oqs.db assertion alone would now pass whether or not the alert fired. Known until the problem report moves in its own commit: nine test_3521_problem_report_comment cases are red here. The delegate files an event-kind row under the seam's id, which the old _attach_comment (keyed on the pre-seam request id) cannot find. New: tests/unit/test_3254_budgeted_alerts.py (registry parity, reach-back imports, the delegate's outcome table over all five budgeted types, the episode's seam properties, R1 for alert_budget). Part of #3254 * fix(operator-queue): the flood alarm reports through the seam and ends with its episode OperatorQueueSyncService._maybe_emit_flood_alert reports through platform_alerts.observe as kind queue_flood keyed by the reason: one pending row per (agent, reason), rewritten in place, budgeted by the seam. #3130's outcome rule is kept on observe's strings: a failed write releases the episode and is retried after the cooldown (I1); created, updated, snoozed and refused consume it. While an episode lasts it is re-read at most every 6 hours, so the kind's 14-day lifetime ends only a row nobody re-read, never a condition that still holds. The refresh time per (agent, reason) is a dict the method creates on the instance for itself; __init__ is unchanged. The flood's own operator_queue_new broadcast (which carried the title) is gone; observe sends the thin operator_queue_sync trigger. The two _sync_agent statements where an episode ends (_flood_episodes.discard for oversize_file and ingestion_cap) become calls to the new _end_flood_episode, which ends the episode and, only when one was running, ends its alert as the platform through platform_alerts.clear. A cycle with no episode costs no read. Ratchet: _maybe_emit_flood_alert leaves EMITTERS_NOT_YET_ON_SEAM; queue_flood's clear site is _end_flood_episode. No re-pin in this commit: the #3130 and #1632 harnesses were moved to the seam's create in the previous commit and keep their results. Tests: the flood through the real _sync_agent poll for 30 simulated days with the real expiry sweep (one row, re-read every 6 hours, ended as the platform when nothing is held), no read without an episode, two reasons two subjects, I1 on the real seam, a person's ending standing through the re-read and the clear, the thin trigger, R1 for queue_flood. Part of #3254 * fix(execution): the effect guard and missing-skill alarms report through the seam _on_unguarded_effect reports a refused effect through platform_alerts.observe as kind effect_unguarded keyed "<effect_type>:<reason>": one row per agent, effect and reason, rewritten by each further refusal, ended by its lifetime (nothing observes an agent starting to send ids). The send is refused whatever the alarm's outcome. _alert_skill_not_found reports through observe as kind skill_not_found keyed by the truncated command: one row per agent and command, re-read by each scheduled run. The paired notification is sent only on "created": a repeat of a pending command is an "updated" reading and already had one; refused, failed and snoozed wrote no new row. The pre-create dedup read stays and now matches only a pending pre-#3246 row (no subject), which keeps standing for its command until the upgrade sweep stamps it; a seam row is re-read through observe, where a repeat is never refused at the cap. task_execution_service.py: only _alert_skill_not_found changes. Its module-level utc_now_iso import is now unused and is left in place. Ratchet: _on_unguarded_effect and _alert_skill_not_found leave EMITTERS_NOT_YET_ON_SEAM; skill_not_found gets a NO_CLEAR_SITE reason (only the dispatch path could see a command resolve, and there the detector cannot tell "resolved" from "not a slash command"). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_emitters:: test_skill_not_found_emitter_is_routed_not_allowlisted: the module must call platform_alerts.observe naming "skill_not_found" (AST), the seam that composes the budget, instead of mentioning create_bounded_alert. - test_2392_effect_guard_fail_closed: write-observation point and id shape. The alarm is recorded at platform_alerts.observe instead of a sys.modules stub of operator_queue_service, which lacks the names the seam reaches back for. The id prefix is asserted on the kind; the at-budget case returns the seam's refused_at_budget. - test_ent879_aauth_resource_route (the refused-call case): the dead create_bounded_alert patch moves to platform_alerts.observe. Tests: the effect refusal's seam properties and lifetime; the missing skill's one row per command, no notification on a repeat, a pre-seam row still standing, no notification at the cap; R1 for both kinds; the other shape, the clock 30 days ahead: a full skill_not_found budget frees itself through the real expiry sweep and a new command files. Part of #3254 * fix(git-sync): the gitignore sweep's alert is one row per change set _emit_gitignore_untracked_alert reports through platform_alerts.observe as kind gitignore_untracked, which stops being an event kind (platform_alerts.py: event=True dropped). It is a must-act kind: no lifetime, never ended by the platform. It is keyed by the change itself: a 32-hex digest of the canonical, direction-tagged set of paths the Push untracked and newly un-ignored (sorted removed paths, the exact removed count, sorted un-ignored paths). A repeat of the same set collapses onto one row; a different set, a different total behind a capped list, or the same path in the other direction is a different row. Keying per agent would let a later Push overwrite an earlier Push's path list on a pending must-act alert, which #2529 calls the surface that outlives the session. The legacy prefix keeps its _no_subject parser, so pre-existing rows stay pending until a person acts. Ratchet: _emit_gitignore_untracked_alert leaves EMITTERS_NOT_YET_ON_SEAM. #3254 re-pins (asserted outcomes unchanged): - test_2529_gitignore_precedence: write-observation point and id shape. The alert is watched at platform_alerts.observe (the two create.await_count == 0 checks would otherwise have gone vacuous); the per-agent id prefix is asserted on the kind, with the 32-hex key. - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: gitignore_untracked is a condition now, so it is asserted keyed and the problem report stays the event example. Tests: a repeated set is one row that never expires; distinct sets and a capped list with another total stay distinct; the direction tag holds; a person's ending stands; the 30-day case now also shows the gitignore row still pending. Part of #3254 * fix(workspace): the problem report is one seam row per person, target and day raise_problem_report reports through platform_alerts.observe as kind workspace_problem_report, which stops being an event kind (event=True dropped). It is keyed by the 32-hex digest _problem_report_id already computes: one row per person per target per UTC day, the "never duplicates" rule its docstring states. A person must act on it, so it never expires and the platform never ends it. The workspace-problem- id prefix is kept, so ent#866's owner-only rule and the machine-key "about a person" exclusion still hold. It returns True when the row was created or updated, False when snoozed, refused or failed. #3521's words-only rule moves under the seam's lock. observe gains keep_text (passed through database.create_platform_operator_queue_item to create_platform_item and _touch): with keep_text and a pending row, the reading only counts (last_seen_at, seen_count, expires_at) and the title, question, priority and context stand. The bare click passes keep_text, a reading with words does not. The click and the comment are two background requests that meet on one row inside the per-agent lock, so either order ends with the words. With no pending row the reading files as usual. update_pending_problem_report (database.py, db/operator_queue.py) and the nested _attach_comment are removed: one write path. Ratchet: raise_problem_report leaves EMITTERS_NOT_YET_ON_SEAM, which fixes the nine test_3521 cases the delegate commit left red. #3254 re-pins (asserted outcomes unchanged): - test_3521_problem_report_comment: the acknowledgement fixture goes through ask_service.answer (fixture shape; a raw status UPDATE carries no person ending for the snooze to read); the accessor test asserts the same type guard at the seam (a foreign row under the report's old id is never written); the lost-race test injects the bare click's whole reading, in its own thread, before the comment's locked create. - test_ent499_problem_report: write-observation point. The fake moves from create_bounded_alert to platform_alerts.observe; the routing AST test asserts the call to observe. - test_ent715_queue_person_fields: update_pending_problem_report leaves _NON_ROW_ACCESSORS (the accessor census forbids a stale entry). - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: no built-in kind is an event any more, so the property is pinned on a kind registered for the test, and both former events are asserted keyed. test_ent866_problem_report_owner_only is unchanged. Tests: keep_text at the sink, both interleavings keeping the words, one must-act row per person, target and day, the owner-only prefix, the delegate and the emitter landing on one subject, a person's ending not rewritten or reopened; the 30-day case now also shows the report still pending; the five-type admission test asserts every kind keyed. Part of #3254 * fix(operator-queue): decide a platform alert's snooze under the create's lock observe checks the snooze before the create's lock. Two moments let a person's ending slip past that check: an acknowledgement after observe read the pending row but before the locked create (the locked find then misses), and one between the locked find and _touch's compare-and-set (the lock covers creates, not respond_to_item, so the CAS loses). Either way the create fell through to an insert, and the alert a person had just ended was back at once. Before this batch most of the moved writers had a deterministic id that could not re-file after an ending, so the moves would otherwise ship that regression. create_platform_item gains snooze_since and a snoozed predicate. On the insert path, after a missed find or a lost CAS and inside the same locked transaction, it reads the newest person-ended row for the subject through the transaction's own connection (the public lookup opens another one) and returns {"outcome": "snoozed"} without inserting when the predicate says so. observe passes the standard 7-day window, computed on its own rather than from the pre-lock check's conditionally assigned cutoff, and lambda ended: _snoozed_by(kind, ended, priority, context). The pre-lock check stays as the fast path. A caller that passes neither keeps the old behaviour. The statement behind the public find_person_ended_by_subject becomes _find_person_ended_by_subject(conn, ...), shared by both reads. Tests: a person's acknowledgement through ask_service.answer, landed (a) between observe's read and the locked create and (b) between the locked find and the CAS, yields "snoozed" and no new row, for the problem report, an inbox collision as registered on dev, and the flood alarm's 6-hourly re-read. All six cases were red before this commit (a fresh row was created) and pass with it. On SQLite, BEGIN IMMEDIATE holds every other writer, so moment (b) lands the ending first and hands both finds the row as it stood just before it; two real workers are not exercised. Review fixes carried here (the earlier commits are left as they are): - OperatorQueueSyncService._maybe_emit_flood_alert: the cooldown is stamped before every reading, the 6-hourly re-read included. A failed re-read released the episode with the cooldown stamp still 6 hours old, so it was retried on the next 5-second cycle. New test: a failed re-read is retried no sooner than the cooldown (red before the fix). - test_3521_problem_report_comment (the lost-race re-pin): asserts the bare click's own request returned True and left a pending, comment-free row before the comment's locked create ran, so the test cannot pass without the interleaving it claims. - gitignore_sweep: states that past the probe's 2,000-line cap the key is the capped list plus the exact total (a full-set digest needs the in-container probe, outside this change). - test_1677_operator_alert_emitters: the census's guidance for an agent-influenceable emitter now points at platform_alerts.observe, not the delegate the #3246 ratchet counts as off the seam. - test_3254_budgeted_alerts: the frozen clock also covers db.operator_queue's ent#815 commit-lag check, which logged spurious errors against the real clock. Part of #3254 * fix(operator-queue): a failed flood re-read keeps the episode, so its end still clears the alert Fresh review of the #3254 budgeted slice (two findings): - A failed 6-hourly re-read of a persisting flood released the episode. If the condition then cleared before the retry, `_end_flood_episode` found no episode and the pending alert waited out its 14-day lifetime, although the code had seen the condition clear (AC 2). A failed re-read now keeps the episode, whose alert an earlier reading filed, and the re-read is retried once the cooldown has passed. A failed first reading still releases the episode (#3130 I1). New test: test_a_failed_reread_keeps_the_episode_so_its_end_still_clears_the_alert (red with the old release branch put back). - AC 8 for two kinds had no "a person's ending is never overwritten" test: `skill_not_found` (the next run is snoozed and sends no notification) and `alert_budget` (a later refusal re-reads the episode and the acknowledgement stands). Both added. * test(operator-queue): the budgeted-alert suite freezes the clock its running methods read In the full serial unit tier, test_1595_sync_health_signals evicts `database` and every `db.*` module from sys.modules and restores only some of them. Afterwards `database.db` and `ask_service.db` run on an older `db.operator_queue` module than the one this suite's clock fixture imports and patches, so the seam's create, the expiry sweep and the answer's compare-and-set read the real clock: rows filed at the frozen T0 read as long expired (five cases red, `AskConflict: expired`, a second flood row). The fixture now also freezes `utc_now_iso` and `datetime` in the globals of the live operations class (R6: patch what the running method reads). Red before: test_1595 followed by this file, 7 failed; green after: 66 passed; the file alone: 55 passed. * refactor(operator-queue): operator_queue_service becomes a package, content unchanged (#3785) The 2,840-line module moves to services/operator_queue_service/__init__.py byte for byte (100% similarity), the first step of the Invariant #1 split. Every `from services.operator_queue_service import X` and `from services import operator_queue_service` resolves as before. Six path-keyed guards name the file by its path, so their key moves with it (the PR #2487 precedent): _NOT_EMITTERS (test_3246), _ALLOWED_CALLERS (test_1677), _ALLOWED (test_1920), _OQS (test_ent715), FLEET_LEVEL_ALLOWLIST (test_ent467), and the source read in test_ent499. Only the key changes; the rule, the reason text and every assertion are untouched. Part of #3785 * test(operator-queue): pin the package's one-binding rules before the split (#3785) tests/unit/test_3785_operator_queue_package.py pins what S2–S6 must keep while they move code out of __init__, each property derived from the tree so no later slice edits it: modules under 800 lines (__init__ exempt, with a staleness check); the import surface src/backend and tests/ read still resolves; no from-import between package modules; one top-level binding per name; import-time reads defined first and the _MARKER_UNCHANGED default the owner's object; a patch of a re-exported name lands where its readers read; one logger identity; owner-exact qualified reads; no submodule named like a package attribute; one rate_limiter; no method on two classes of the composed service; external imports before the first submodule import, and a failed first import, injected at that line, leaves no stale submodule. The AST scans live in _oqs_package_scan.py (pure stdlib, never imports src). The other shape, a fresh install: each consumer imported first in its own interpreter on an empty database raises a bounded alert (created; only main binds a WebSocket manager, and then exactly one thin operator_queue_sync trigger goes out). Outcomes equal on the base. Part of #3785 * refactor(operator-queue): bind the service's collaborators once, in deps.py (#3785) db, _queue_db, principal_reach, get_breaker_redis, ask_service, AgentClient and the audit sink _audit_sync move to services/operator_queue_service/deps.py, bound once and read as deps.X everywhere in the package. They are no longer attributes of the package, so a stale monkeypatch.setattr(oqs, "db", ...) raises AttributeError instead of patching a copy nothing reads (Invariant #1(a), the PR #2487 rule). rate_limiter stays on the package: ask_service reads oqs.rate_limiter.check. Tests that patched a collaborator on the package now patch oqs.deps.X; no assertion, expected value, fixture or control flow changes. The package guard gains G4 (deps binds exactly the collaborators, no other module imports one from its source under any alias or holds one by identity, the package has none) and refuses any reach of a package function's __globals__. Part of #3785 * refactor(operator-queue): the queue listing engine moves to listing.py (#3785) QueueListError, narrow_to_agent_key, the cursor and walk-snapshot helpers and list_for_principal (trinity-enterprise#815) move whole from __init__ to services/operator_queue_service/listing.py. The two package-owned prefix tuples are read as _oq.X, collaborators as deps.X. The package re-exports exactly the six names read from outside (the router's list_for_principal and QueueListError; narrow_to_agent_key, encode_cursor, decode_cursor and CURSOR_MAX_BYTES, which tests call or compare). test_ent715's row-reader census re-keys list_for_principal to listing.py; no assertion changes. Part of #3785 * refactor(operator-queue): the poller core moves into PollerCoreMixin (#3785) The instance state, start/stop, the Redis leader lease, _poll_loop, _poll_cycle and _broadcast_sync move into PollerCoreMixin in services/operator_queue_service/poller.py. OperatorQueueSyncService is now composed in __init__ from the mixin and keeps its singleton there (the db/schedules shape). Package-owned names (DEFAULT_POLL_INTERVAL, _LEADER_KEY, _RESERVED_ID_PREFIXES, _websocket_manager) are read as _oq.X; the default poll_interval still binds 5 at import. Three path-keyed censuses re-key their poller entries to poller.py (test_1920's lease, test_ent467's operator_queue_sync trigger, test_ent715's _poll_cycle); no assertion changes. Part of #3785 * fix(operator-queue): a new flood, budget or untracking episode files after an acknowledgement (#3254) A person's ending of a `queue_flood`, `alert_budget` or `gitignore_untracked` row snoozed every later reading of the subject for 7 days, because none of the three kinds had a material key, so `_snoozed_by` was vacuously true. A runaway agent's second flood, a second budget-full episode and a second untracking Push of the same paths were all silent (review C1; dolho on operator_queue_service.py:2800 and gitignore_sweep.py:335). Each reading now carries an episode marker that the kind lists in its `material_keys`: - queue_flood: `episode_started_at`, stamped when the in-memory episode starts. Re-reads of one episode share it; an episode that starts after the condition cleared does not. - alert_budget: `filled_by`, a digest of the ids of the pending rows filling the budget. Re-reads of the same full budget share it; once a slot frees and a new row fills it, it differs. - gitignore_untracked: `push_id`, one per call. The emitter runs once per Push, so every untracking Push after an acknowledgement files; repeats still collapse onto a pending row. So the snooze silences re-reads of the acknowledged episode for the snooze window and a new episode files at once, which makes the `_maybe_emit_flood_alert` docstring's #3130 edge-trigger claim true again. The budget episode's read of the filling rows is classified in the ent#780 row-reader census as internal. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * fix(operator-queue): a flood re-read no longer stamps the per-agent cooldown; the oversize end is pinned (#3254) Review follow-ups on the flood alarm: - dolho on operator_queue_service.py:2778 (webmixgamer agreed): the 6-hourly re-read of one reason's episode stamped the per-agent `_flood_alert_cooldown`, so the other reason's first alert could wait up to one cooldown. The cooldown spaces episodes and a re-read is not one, so it is now stamped only before an episode's first reading. A failed re-read's retry spacing already comes from its refresh time. - webmixgamer I3: the 6-hour re-read spacing is one constant, `OPERATOR_QUEUE_FLOOD_REREAD_SECONDS`, read by the gate and by the failed re-read's retry arithmetic, so the two cannot drift. - webmixgamer I1: a `_sync_loop` case serves an oversized file and then a sane one and asserts the row ends as the platform. It goes red when `_sync_agent`'s `_end_flood_episode(agent_name, "oversize_file")` is replaced by a bare episode discard. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * docs(operator-queue): state the fail-open double-leader bound on the flood episode marker (#3254) The episode marker is worker-local. With Redis down the leader lease fails open, so each worker stamps its own episode_started_at and another worker's re-read can file past a person's ending, at most one extra row per extra worker per re-read window. Docstring only; no behaviour change (review L1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): __init__ drops its file-level F401 waiver (#3785) Review I1 (dolho): the file-level `# ruff: noqa: F401` switched off unused-import detection for all of `__init__`, so a dead import left behind by a later slice or feature would go unflagged. At this PR's head `__init__` still reads every name in its import block, so the waiver hid nothing: `ruff check --select F401` gives 0 findings with it removed. It is dropped, and the block's comment now says that a name `__init__` stops reading keeps its line with a per-line waiver naming why (G13, or read as `oqs.X` from outside). PR2, PR3 and PR4 add those per-line waivers where their moves leave a name unread. `deps.py` keeps its file-level waiver: it is a binding module whose imports are its bindings, so there is no import there F401 could rightly flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): per-line F401 waivers for what __init__ stops reading (#3785) Review I1 on #4036: PR1 dropped `__init__`'s file-level F401 waiver. This slice's moves leave four of its imports unread in `__init__`; each now carries its own `noqa: F401` with the reason, so F401 keeps checking every other line: - `asyncio`, `base64`, `uuid`: kept for G13, because `listing` and `poller` import them at module level. - `from . import listing`: loads the submodule at its G6 point; the names callers read come from the re-export block. `ruff check --select F services/operator_queue_service/` is clean. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…hole modules (#3785, PR 3 of 4) (#4038) * fix(operator-queue): the #1677 helper delegates to the platform-alert seam create_bounded_alert(_outcome) keep their signatures and outcome contract and become a thin delegate of platform_alerts.observe, which already composes the per-(agent, type) budget inside its one locked create. The registered type names its kind; the key is read back from the item's id and context by derive_legacy_subject and must resolve to that same kind, else ALERT_FAILED_CREATE. The two kinds whose ids carry no subject (gitignore, problem report) are keyed by the request id minus the kind's prefix. observe's "updated" and "snoozed" pass through; "failed" maps to ALERT_FAILED_CREATE; every refused or failed arm logs [#1677 budget]. ALERT_FAILED_COUNT stays importable and is no longer returned. The budget episode reports through observe as kind alert_budget keyed by the budgeted type: one alert_budget:<type> row per agent, re-read by a later refusal outside the cooldown, ended by its 14-day lifetime. The bucketed id and its own operator_queue_new broadcast are gone; observe sends the thin operator_queue_sync trigger. Ratchet: create_bounded_alert_outcome and _maybe_emit_alert_budget_episode leave EMITTERS_NOT_YET_ON_SEAM; alert_budget gets a NO_CLEAR_SITE reason. Census: both leave _ALLOWED_CALLERS (no direct create left in either). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_budget: write-observation point. The harness stands in for the seam's create with the same budget arithmetic and runs what observe spawns. Id shape in test_deterministic_bucketed_id_with_reserved_prefix, test_cooldown_knob_zero_never_raises (the subject replaces the bucket) and test_under_cap_creates_item_and_notification (the seam's id). The episode raise now stays in its spawned task, so test_episode_helper_raise_swallowed_refusal_stands reads the delegate's WARNING marker; test_ws_broadcast_failure_swallowed checks the thin operator_queue_sync payload. - test_3130_flood_guard, test_1632_operator_queue_caps: write-observation point. The flood alert still rides the delegate, so its writes, the typed budget read and the I1 fault injection move to the seam's create. - test_3243_atomic_asks::test_a_cap_hold_never_fires_the_flood_alert: write-observation point. Watched at observe, since the oqs.db assertion alone would now pass whether or not the alert fired. Known until the problem report moves in its own commit: nine test_3521_problem_report_comment cases are red here. The delegate files an event-kind row under the seam's id, which the old _attach_comment (keyed on the pre-seam request id) cannot find. New: tests/unit/test_3254_budgeted_alerts.py (registry parity, reach-back imports, the delegate's outcome table over all five budgeted types, the episode's seam properties, R1 for alert_budget). Part of #3254 * fix(operator-queue): the flood alarm reports through the seam and ends with its episode OperatorQueueSyncService._maybe_emit_flood_alert reports through platform_alerts.observe as kind queue_flood keyed by the reason: one pending row per (agent, reason), rewritten in place, budgeted by the seam. #3130's outcome rule is kept on observe's strings: a failed write releases the episode and is retried after the cooldown (I1); created, updated, snoozed and refused consume it. While an episode lasts it is re-read at most every 6 hours, so the kind's 14-day lifetime ends only a row nobody re-read, never a condition that still holds. The refresh time per (agent, reason) is a dict the method creates on the instance for itself; __init__ is unchanged. The flood's own operator_queue_new broadcast (which carried the title) is gone; observe sends the thin operator_queue_sync trigger. The two _sync_agent statements where an episode ends (_flood_episodes.discard for oversize_file and ingestion_cap) become calls to the new _end_flood_episode, which ends the episode and, only when one was running, ends its alert as the platform through platform_alerts.clear. A cycle with no episode costs no read. Ratchet: _maybe_emit_flood_alert leaves EMITTERS_NOT_YET_ON_SEAM; queue_flood's clear site is _end_flood_episode. No re-pin in this commit: the #3130 and #1632 harnesses were moved to the seam's create in the previous commit and keep their results. Tests: the flood through the real _sync_agent poll for 30 simulated days with the real expiry sweep (one row, re-read every 6 hours, ended as the platform when nothing is held), no read without an episode, two reasons two subjects, I1 on the real seam, a person's ending standing through the re-read and the clear, the thin trigger, R1 for queue_flood. Part of #3254 * fix(execution): the effect guard and missing-skill alarms report through the seam _on_unguarded_effect reports a refused effect through platform_alerts.observe as kind effect_unguarded keyed "<effect_type>:<reason>": one row per agent, effect and reason, rewritten by each further refusal, ended by its lifetime (nothing observes an agent starting to send ids). The send is refused whatever the alarm's outcome. _alert_skill_not_found reports through observe as kind skill_not_found keyed by the truncated command: one row per agent and command, re-read by each scheduled run. The paired notification is sent only on "created": a repeat of a pending command is an "updated" reading and already had one; refused, failed and snoozed wrote no new row. The pre-create dedup read stays and now matches only a pending pre-#3246 row (no subject), which keeps standing for its command until the upgrade sweep stamps it; a seam row is re-read through observe, where a repeat is never refused at the cap. task_execution_service.py: only _alert_skill_not_found changes. Its module-level utc_now_iso import is now unused and is left in place. Ratchet: _on_unguarded_effect and _alert_skill_not_found leave EMITTERS_NOT_YET_ON_SEAM; skill_not_found gets a NO_CLEAR_SITE reason (only the dispatch path could see a command resolve, and there the detector cannot tell "resolved" from "not a slash command"). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_emitters:: test_skill_not_found_emitter_is_routed_not_allowlisted: the module must call platform_alerts.observe naming "skill_not_found" (AST), the seam that composes the budget, instead of mentioning create_bounded_alert. - test_2392_effect_guard_fail_closed: write-observation point and id shape. The alarm is recorded at platform_alerts.observe instead of a sys.modules stub of operator_queue_service, which lacks the names the seam reaches back for. The id prefix is asserted on the kind; the at-budget case returns the seam's refused_at_budget. - test_ent879_aauth_resource_route (the refused-call case): the dead create_bounded_alert patch moves to platform_alerts.observe. Tests: the effect refusal's seam properties and lifetime; the missing skill's one row per command, no notification on a repeat, a pre-seam row still standing, no notification at the cap; R1 for both kinds; the other shape, the clock 30 days ahead: a full skill_not_found budget frees itself through the real expiry sweep and a new command files. Part of #3254 * fix(git-sync): the gitignore sweep's alert is one row per change set _emit_gitignore_untracked_alert reports through platform_alerts.observe as kind gitignore_untracked, which stops being an event kind (platform_alerts.py: event=True dropped). It is a must-act kind: no lifetime, never ended by the platform. It is keyed by the change itself: a 32-hex digest of the canonical, direction-tagged set of paths the Push untracked and newly un-ignored (sorted removed paths, the exact removed count, sorted un-ignored paths). A repeat of the same set collapses onto one row; a different set, a different total behind a capped list, or the same path in the other direction is a different row. Keying per agent would let a later Push overwrite an earlier Push's path list on a pending must-act alert, which #2529 calls the surface that outlives the session. The legacy prefix keeps its _no_subject parser, so pre-existing rows stay pending until a person acts. Ratchet: _emit_gitignore_untracked_alert leaves EMITTERS_NOT_YET_ON_SEAM. #3254 re-pins (asserted outcomes unchanged): - test_2529_gitignore_precedence: write-observation point and id shape. The alert is watched at platform_alerts.observe (the two create.await_count == 0 checks would otherwise have gone vacuous); the per-agent id prefix is asserted on the kind, with the 32-hex key. - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: gitignore_untracked is a condition now, so it is asserted keyed and the problem report stays the event example. Tests: a repeated set is one row that never expires; distinct sets and a capped list with another total stay distinct; the direction tag holds; a person's ending stands; the 30-day case now also shows the gitignore row still pending. Part of #3254 * fix(workspace): the problem report is one seam row per person, target and day raise_problem_report reports through platform_alerts.observe as kind workspace_problem_report, which stops being an event kind (event=True dropped). It is keyed by the 32-hex digest _problem_report_id already computes: one row per person per target per UTC day, the "never duplicates" rule its docstring states. A person must act on it, so it never expires and the platform never ends it. The workspace-problem- id prefix is kept, so ent#866's owner-only rule and the machine-key "about a person" exclusion still hold. It returns True when the row was created or updated, False when snoozed, refused or failed. #3521's words-only rule moves under the seam's lock. observe gains keep_text (passed through database.create_platform_operator_queue_item to create_platform_item and _touch): with keep_text and a pending row, the reading only counts (last_seen_at, seen_count, expires_at) and the title, question, priority and context stand. The bare click passes keep_text, a reading with words does not. The click and the comment are two background requests that meet on one row inside the per-agent lock, so either order ends with the words. With no pending row the reading files as usual. update_pending_problem_report (database.py, db/operator_queue.py) and the nested _attach_comment are removed: one write path. Ratchet: raise_problem_report leaves EMITTERS_NOT_YET_ON_SEAM, which fixes the nine test_3521 cases the delegate commit left red. #3254 re-pins (asserted outcomes unchanged): - test_3521_problem_report_comment: the acknowledgement fixture goes through ask_service.answer (fixture shape; a raw status UPDATE carries no person ending for the snooze to read); the accessor test asserts the same type guard at the seam (a foreign row under the report's old id is never written); the lost-race test injects the bare click's whole reading, in its own thread, before the comment's locked create. - test_ent499_problem_report: write-observation point. The fake moves from create_bounded_alert to platform_alerts.observe; the routing AST test asserts the call to observe. - test_ent715_queue_person_fields: update_pending_problem_report leaves _NON_ROW_ACCESSORS (the accessor census forbids a stale entry). - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: no built-in kind is an event any more, so the property is pinned on a kind registered for the test, and both former events are asserted keyed. test_ent866_problem_report_owner_only is unchanged. Tests: keep_text at the sink, both interleavings keeping the words, one must-act row per person, target and day, the owner-only prefix, the delegate and the emitter landing on one subject, a person's ending not rewritten or reopened; the 30-day case now also shows the report still pending; the five-type admission test asserts every kind keyed. Part of #3254 * fix(operator-queue): decide a platform alert's snooze under the create's lock observe checks the snooze before the create's lock. Two moments let a person's ending slip past that check: an acknowledgement after observe read the pending row but before the locked create (the locked find then misses), and one between the locked find and _touch's compare-and-set (the lock covers creates, not respond_to_item, so the CAS loses). Either way the create fell through to an insert, and the alert a person had just ended was back at once. Before this batch most of the moved writers had a deterministic id that could not re-file after an ending, so the moves would otherwise ship that regression. create_platform_item gains snooze_since and a snoozed predicate. On the insert path, after a missed find or a lost CAS and inside the same locked transaction, it reads the newest person-ended row for the subject through the transaction's own connection (the public lookup opens another one) and returns {"outcome": "snoozed"} without inserting when the predicate says so. observe passes the standard 7-day window, computed on its own rather than from the pre-lock check's conditionally assigned cutoff, and lambda ended: _snoozed_by(kind, ended, priority, context). The pre-lock check stays as the fast path. A caller that passes neither keeps the old behaviour. The statement behind the public find_person_ended_by_subject becomes _find_person_ended_by_subject(conn, ...), shared by both reads. Tests: a person's acknowledgement through ask_service.answer, landed (a) between observe's read and the locked create and (b) between the locked find and the CAS, yields "snoozed" and no new row, for the problem report, an inbox collision as registered on dev, and the flood alarm's 6-hourly re-read. All six cases were red before this commit (a fresh row was created) and pass with it. On SQLite, BEGIN IMMEDIATE holds every other writer, so moment (b) lands the ending first and hands both finds the row as it stood just before it; two real workers are not exercised. Review fixes carried here (the earlier commits are left as they are): - OperatorQueueSyncService._maybe_emit_flood_alert: the cooldown is stamped before every reading, the 6-hourly re-read included. A failed re-read released the episode with the cooldown stamp still 6 hours old, so it was retried on the next 5-second cycle. New test: a failed re-read is retried no sooner than the cooldown (red before the fix). - test_3521_problem_report_comment (the lost-race re-pin): asserts the bare click's own request returned True and left a pending, comment-free row before the comment's locked create ran, so the test cannot pass without the interleaving it claims. - gitignore_sweep: states that past the probe's 2,000-line cap the key is the capped list plus the exact total (a full-set digest needs the in-container probe, outside this change). - test_1677_operator_alert_emitters: the census's guidance for an agent-influenceable emitter now points at platform_alerts.observe, not the delegate the #3246 ratchet counts as off the seam. - test_3254_budgeted_alerts: the frozen clock also covers db.operator_queue's ent#815 commit-lag check, which logged spurious errors against the real clock. Part of #3254 * fix(operator-queue): a failed flood re-read keeps the episode, so its end still clears the alert Fresh review of the #3254 budgeted slice (two findings): - A failed 6-hourly re-read of a persisting flood released the episode. If the condition then cleared before the retry, `_end_flood_episode` found no episode and the pending alert waited out its 14-day lifetime, although the code had seen the condition clear (AC 2). A failed re-read now keeps the episode, whose alert an earlier reading filed, and the re-read is retried once the cooldown has passed. A failed first reading still releases the episode (#3130 I1). New test: test_a_failed_reread_keeps_the_episode_so_its_end_still_clears_the_alert (red with the old release branch put back). - AC 8 for two kinds had no "a person's ending is never overwritten" test: `skill_not_found` (the next run is snoozed and sends no notification) and `alert_budget` (a later refusal re-reads the episode and the acknowledgement stands). Both added. * test(operator-queue): the budgeted-alert suite freezes the clock its running methods read In the full serial unit tier, test_1595_sync_health_signals evicts `database` and every `db.*` module from sys.modules and restores only some of them. Afterwards `database.db` and `ask_service.db` run on an older `db.operator_queue` module than the one this suite's clock fixture imports and patches, so the seam's create, the expiry sweep and the answer's compare-and-set read the real clock: rows filed at the frozen T0 read as long expired (five cases red, `AskConflict: expired`, a second flood row). The fixture now also freezes `utc_now_iso` and `datetime` in the globals of the live operations class (R6: patch what the running method reads). Red before: test_1595 followed by this file, 7 failed; green after: 66 passed; the file alone: 55 passed. * refactor(operator-queue): operator_queue_service becomes a package, content unchanged (#3785) The 2,840-line module moves to services/operator_queue_service/__init__.py byte for byte (100% similarity), the first step of the Invariant #1 split. Every `from services.operator_queue_service import X` and `from services import operator_queue_service` resolves as before. Six path-keyed guards name the file by its path, so their key moves with it (the PR #2487 precedent): _NOT_EMITTERS (test_3246), _ALLOWED_CALLERS (test_1677), _ALLOWED (test_1920), _OQS (test_ent715), FLEET_LEVEL_ALLOWLIST (test_ent467), and the source read in test_ent499. Only the key changes; the rule, the reason text and every assertion are untouched. Part of #3785 * test(operator-queue): pin the package's one-binding rules before the split (#3785) tests/unit/test_3785_operator_queue_package.py pins what S2–S6 must keep while they move code out of __init__, each property derived from the tree so no later slice edits it: modules under 800 lines (__init__ exempt, with a staleness check); the import surface src/backend and tests/ read still resolves; no from-import between package modules; one top-level binding per name; import-time reads defined first and the _MARKER_UNCHANGED default the owner's object; a patch of a re-exported name lands where its readers read; one logger identity; owner-exact qualified reads; no submodule named like a package attribute; one rate_limiter; no method on two classes of the composed service; external imports before the first submodule import, and a failed first import, injected at that line, leaves no stale submodule. The AST scans live in _oqs_package_scan.py (pure stdlib, never imports src). The other shape, a fresh install: each consumer imported first in its own interpreter on an empty database raises a bounded alert (created; only main binds a WebSocket manager, and then exactly one thin operator_queue_sync trigger goes out). Outcomes equal on the base. Part of #3785 * refactor(operator-queue): bind the service's collaborators once, in deps.py (#3785) db, _queue_db, principal_reach, get_breaker_redis, ask_service, AgentClient and the audit sink _audit_sync move to services/operator_queue_service/deps.py, bound once and read as deps.X everywhere in the package. They are no longer attributes of the package, so a stale monkeypatch.setattr(oqs, "db", ...) raises AttributeError instead of patching a copy nothing reads (Invariant #1(a), the PR #2487 rule). rate_limiter stays on the package: ask_service reads oqs.rate_limiter.check. Tests that patched a collaborator on the package now patch oqs.deps.X; no assertion, expected value, fixture or control flow changes. The package guard gains G4 (deps binds exactly the collaborators, no other module imports one from its source under any alias or holds one by identity, the package has none) and refuses any reach of a package function's __globals__. Part of #3785 * refactor(operator-queue): the agent-file channel leaves __init__ as whole modules (#3785) The file-channel code moves out of __init__ in four modules, so that the channel's removal (#3438) becomes a file deletion rather than surgery: * filechannel.py: the module helpers (clamping, comparison, the ingestion marker and its _MARKER_UNCHANGED sentinel, delivery matching); * rows.py: what a row says about itself, read on both sides of the package (the audience predicates, the receipt vocabulary, aging); * ingest.py: IngestMixin (_apply_sync_state, _notice_file_channel, _sync_agent); * write_back.py: WriteBackMixin (_apply_delivery_state, _write_responses_to_agent). OperatorQueueSyncService composes the two mixins; the flood methods stay on it and _sync_agent reaches them through self. The moved code is unchanged apart from owner-exact qualifications (_oq.X, filechannel.X, rows.X). Four path-keyed censuses re-key _sync_agent to ingest.py and the write-back source read to write_back.py; two tests move their _validated_addressee patch to oqs.filechannel, its owner. No assertion changes. Part of #3785 * fix(operator-queue): a new flood, budget or untracking episode files after an acknowledgement (#3254) A person's ending of a `queue_flood`, `alert_budget` or `gitignore_untracked` row snoozed every later reading of the subject for 7 days, because none of the three kinds had a material key, so `_snoozed_by` was vacuously true. A runaway agent's second flood, a second budget-full episode and a second untracking Push of the same paths were all silent (review C1; dolho on operator_queue_service.py:2800 and gitignore_sweep.py:335). Each reading now carries an episode marker that the kind lists in its `material_keys`: - queue_flood: `episode_started_at`, stamped when the in-memory episode starts. Re-reads of one episode share it; an episode that starts after the condition cleared does not. - alert_budget: `filled_by`, a digest of the ids of the pending rows filling the budget. Re-reads of the same full budget share it; once a slot frees and a new row fills it, it differs. - gitignore_untracked: `push_id`, one per call. The emitter runs once per Push, so every untracking Push after an acknowledgement files; repeats still collapse onto a pending row. So the snooze silences re-reads of the acknowledged episode for the snooze window and a new episode files at once, which makes the `_maybe_emit_flood_alert` docstring's #3130 edge-trigger claim true again. The budget episode's read of the filling rows is classified in the ent#780 row-reader census as internal. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * fix(operator-queue): a flood re-read no longer stamps the per-agent cooldown; the oversize end is pinned (#3254) Review follow-ups on the flood alarm: - dolho on operator_queue_service.py:2778 (webmixgamer agreed): the 6-hourly re-read of one reason's episode stamped the per-agent `_flood_alert_cooldown`, so the other reason's first alert could wait up to one cooldown. The cooldown spaces episodes and a re-read is not one, so it is now stamped only before an episode's first reading. A failed re-read's retry spacing already comes from its refresh time. - webmixgamer I3: the 6-hour re-read spacing is one constant, `OPERATOR_QUEUE_FLOOD_REREAD_SECONDS`, read by the gate and by the failed re-read's retry arithmetic, so the two cannot drift. - webmixgamer I1: a `_sync_loop` case serves an oversized file and then a sane one and asserts the row ends as the platform. It goes red when `_sync_agent`'s `_end_flood_episode(agent_name, "oversize_file")` is replaced by a bare episode discard. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * docs(operator-queue): state the fail-open double-leader bound on the flood episode marker (#3254) The episode marker is worker-local. With Redis down the leader lease fails open, so each worker stamps its own episode_started_at and another worker's re-read can file past a person's ending, at most one extra row per extra worker per re-read window. Docstring only; no behaviour change (review L1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): __init__ drops its file-level F401 waiver (#3785) Review I1 (dolho): the file-level `# ruff: noqa: F401` switched off unused-import detection for all of `__init__`, so a dead import left behind by a later slice or feature would go unflagged. At this PR's head `__init__` still reads every name in its import block, so the waiver hid nothing: `ruff check --select F401` gives 0 findings with it removed. It is dropped, and the block's comment now says that a name `__init__` stops reading keeps its line with a per-line waiver naming why (G13, or read as `oqs.X` from outside). PR2, PR3 and PR4 add those per-line waivers where their moves leave a name unread. `deps.py` keeps its file-level waiver: it is a binding module whose imports are its bindings, so there is no import there F401 could rightly flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): per-line F401 waivers for what __init__ stops reading (#3785) Review I1 on #4036: PR1 dropped `__init__`'s file-level F401 waiver. This slice's moves leave these names unread in `__init__`; each now carries its own `noqa: F401` with the reason, so F401 keeps checking every other name: - `datetime`, `timedelta`, `timezone`, `Sequence`, `options_cap_violation`, `title_cap_violation`: kept for G13, because `rows`, `filechannel` and `ingest` import them at module level. - `rate_limiter`: O1(d), read as `oqs.rate_limiter` from outside (`ask_service`, tests) and as `_oq.rate_limiter` in `ingest`. - `to_utc_iso`: read as `oqs.to_utc_iso` from outside (`test_ec_operator_queue_properties.py`) and kept for G13. - `from . import filechannel` / `rows`: load the submodules at their G6 point; the names callers read come from the re-export block. The `typing` and `utils.helpers` imports become parenthesised so the waiver sits on the one unread name, not the whole line. They stay single statements: splitting one into two breaks the guard's failed-first-import leg, which injects the failure at the module's first statement. `ruff check --select F services/operator_queue_service/` is clean. With every waiver stripped in a scratch copy, the F401 findings are exactly the waived names, and an injected dead import is still reported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * test(operator-queue): ent#981's file-path case patches `_validated_addressee` on `filechannel` (#3785) test_ent981_addressee_reach arrived from dev (#4148) patching the name on the package. This slice moves `_validated_addressee` to `filechannel.py`, where `_clamp_ingested_item` reads it, so the package no longer binds it: the patch raised AttributeError, and the #3785 G7 guard refused it. Same target as test_ent734's two patches of the same name. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…d the split is complete (#3785, PR 4 of 4) (#4039) * fix(operator-queue): the #1677 helper delegates to the platform-alert seam create_bounded_alert(_outcome) keep their signatures and outcome contract and become a thin delegate of platform_alerts.observe, which already composes the per-(agent, type) budget inside its one locked create. The registered type names its kind; the key is read back from the item's id and context by derive_legacy_subject and must resolve to that same kind, else ALERT_FAILED_CREATE. The two kinds whose ids carry no subject (gitignore, problem report) are keyed by the request id minus the kind's prefix. observe's "updated" and "snoozed" pass through; "failed" maps to ALERT_FAILED_CREATE; every refused or failed arm logs [#1677 budget]. ALERT_FAILED_COUNT stays importable and is no longer returned. The budget episode reports through observe as kind alert_budget keyed by the budgeted type: one alert_budget:<type> row per agent, re-read by a later refusal outside the cooldown, ended by its 14-day lifetime. The bucketed id and its own operator_queue_new broadcast are gone; observe sends the thin operator_queue_sync trigger. Ratchet: create_bounded_alert_outcome and _maybe_emit_alert_budget_episode leave EMITTERS_NOT_YET_ON_SEAM; alert_budget gets a NO_CLEAR_SITE reason. Census: both leave _ALLOWED_CALLERS (no direct create left in either). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_budget: write-observation point. The harness stands in for the seam's create with the same budget arithmetic and runs what observe spawns. Id shape in test_deterministic_bucketed_id_with_reserved_prefix, test_cooldown_knob_zero_never_raises (the subject replaces the bucket) and test_under_cap_creates_item_and_notification (the seam's id). The episode raise now stays in its spawned task, so test_episode_helper_raise_swallowed_refusal_stands reads the delegate's WARNING marker; test_ws_broadcast_failure_swallowed checks the thin operator_queue_sync payload. - test_3130_flood_guard, test_1632_operator_queue_caps: write-observation point. The flood alert still rides the delegate, so its writes, the typed budget read and the I1 fault injection move to the seam's create. - test_3243_atomic_asks::test_a_cap_hold_never_fires_the_flood_alert: write-observation point. Watched at observe, since the oqs.db assertion alone would now pass whether or not the alert fired. Known until the problem report moves in its own commit: nine test_3521_problem_report_comment cases are red here. The delegate files an event-kind row under the seam's id, which the old _attach_comment (keyed on the pre-seam request id) cannot find. New: tests/unit/test_3254_budgeted_alerts.py (registry parity, reach-back imports, the delegate's outcome table over all five budgeted types, the episode's seam properties, R1 for alert_budget). Part of #3254 * fix(operator-queue): the flood alarm reports through the seam and ends with its episode OperatorQueueSyncService._maybe_emit_flood_alert reports through platform_alerts.observe as kind queue_flood keyed by the reason: one pending row per (agent, reason), rewritten in place, budgeted by the seam. #3130's outcome rule is kept on observe's strings: a failed write releases the episode and is retried after the cooldown (I1); created, updated, snoozed and refused consume it. While an episode lasts it is re-read at most every 6 hours, so the kind's 14-day lifetime ends only a row nobody re-read, never a condition that still holds. The refresh time per (agent, reason) is a dict the method creates on the instance for itself; __init__ is unchanged. The flood's own operator_queue_new broadcast (which carried the title) is gone; observe sends the thin operator_queue_sync trigger. The two _sync_agent statements where an episode ends (_flood_episodes.discard for oversize_file and ingestion_cap) become calls to the new _end_flood_episode, which ends the episode and, only when one was running, ends its alert as the platform through platform_alerts.clear. A cycle with no episode costs no read. Ratchet: _maybe_emit_flood_alert leaves EMITTERS_NOT_YET_ON_SEAM; queue_flood's clear site is _end_flood_episode. No re-pin in this commit: the #3130 and #1632 harnesses were moved to the seam's create in the previous commit and keep their results. Tests: the flood through the real _sync_agent poll for 30 simulated days with the real expiry sweep (one row, re-read every 6 hours, ended as the platform when nothing is held), no read without an episode, two reasons two subjects, I1 on the real seam, a person's ending standing through the re-read and the clear, the thin trigger, R1 for queue_flood. Part of #3254 * fix(execution): the effect guard and missing-skill alarms report through the seam _on_unguarded_effect reports a refused effect through platform_alerts.observe as kind effect_unguarded keyed "<effect_type>:<reason>": one row per agent, effect and reason, rewritten by each further refusal, ended by its lifetime (nothing observes an agent starting to send ids). The send is refused whatever the alarm's outcome. _alert_skill_not_found reports through observe as kind skill_not_found keyed by the truncated command: one row per agent and command, re-read by each scheduled run. The paired notification is sent only on "created": a repeat of a pending command is an "updated" reading and already had one; refused, failed and snoozed wrote no new row. The pre-create dedup read stays and now matches only a pending pre-#3246 row (no subject), which keeps standing for its command until the upgrade sweep stamps it; a seam row is re-read through observe, where a repeat is never refused at the cap. task_execution_service.py: only _alert_skill_not_found changes. Its module-level utc_now_iso import is now unused and is left in place. Ratchet: _on_unguarded_effect and _alert_skill_not_found leave EMITTERS_NOT_YET_ON_SEAM; skill_not_found gets a NO_CLEAR_SITE reason (only the dispatch path could see a command resolve, and there the detector cannot tell "resolved" from "not a slash command"). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_emitters:: test_skill_not_found_emitter_is_routed_not_allowlisted: the module must call platform_alerts.observe naming "skill_not_found" (AST), the seam that composes the budget, instead of mentioning create_bounded_alert. - test_2392_effect_guard_fail_closed: write-observation point and id shape. The alarm is recorded at platform_alerts.observe instead of a sys.modules stub of operator_queue_service, which lacks the names the seam reaches back for. The id prefix is asserted on the kind; the at-budget case returns the seam's refused_at_budget. - test_ent879_aauth_resource_route (the refused-call case): the dead create_bounded_alert patch moves to platform_alerts.observe. Tests: the effect refusal's seam properties and lifetime; the missing skill's one row per command, no notification on a repeat, a pre-seam row still standing, no notification at the cap; R1 for both kinds; the other shape, the clock 30 days ahead: a full skill_not_found budget frees itself through the real expiry sweep and a new command files. Part of #3254 * fix(git-sync): the gitignore sweep's alert is one row per change set _emit_gitignore_untracked_alert reports through platform_alerts.observe as kind gitignore_untracked, which stops being an event kind (platform_alerts.py: event=True dropped). It is a must-act kind: no lifetime, never ended by the platform. It is keyed by the change itself: a 32-hex digest of the canonical, direction-tagged set of paths the Push untracked and newly un-ignored (sorted removed paths, the exact removed count, sorted un-ignored paths). A repeat of the same set collapses onto one row; a different set, a different total behind a capped list, or the same path in the other direction is a different row. Keying per agent would let a later Push overwrite an earlier Push's path list on a pending must-act alert, which #2529 calls the surface that outlives the session. The legacy prefix keeps its _no_subject parser, so pre-existing rows stay pending until a person acts. Ratchet: _emit_gitignore_untracked_alert leaves EMITTERS_NOT_YET_ON_SEAM. #3254 re-pins (asserted outcomes unchanged): - test_2529_gitignore_precedence: write-observation point and id shape. The alert is watched at platform_alerts.observe (the two create.await_count == 0 checks would otherwise have gone vacuous); the per-agent id prefix is asserted on the kind, with the 32-hex key. - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: gitignore_untracked is a condition now, so it is asserted keyed and the problem report stays the event example. Tests: a repeated set is one row that never expires; distinct sets and a capped list with another total stay distinct; the direction tag holds; a person's ending stands; the 30-day case now also shows the gitignore row still pending. Part of #3254 * fix(workspace): the problem report is one seam row per person, target and day raise_problem_report reports through platform_alerts.observe as kind workspace_problem_report, which stops being an event kind (event=True dropped). It is keyed by the 32-hex digest _problem_report_id already computes: one row per person per target per UTC day, the "never duplicates" rule its docstring states. A person must act on it, so it never expires and the platform never ends it. The workspace-problem- id prefix is kept, so ent#866's owner-only rule and the machine-key "about a person" exclusion still hold. It returns True when the row was created or updated, False when snoozed, refused or failed. #3521's words-only rule moves under the seam's lock. observe gains keep_text (passed through database.create_platform_operator_queue_item to create_platform_item and _touch): with keep_text and a pending row, the reading only counts (last_seen_at, seen_count, expires_at) and the title, question, priority and context stand. The bare click passes keep_text, a reading with words does not. The click and the comment are two background requests that meet on one row inside the per-agent lock, so either order ends with the words. With no pending row the reading files as usual. update_pending_problem_report (database.py, db/operator_queue.py) and the nested _attach_comment are removed: one write path. Ratchet: raise_problem_report leaves EMITTERS_NOT_YET_ON_SEAM, which fixes the nine test_3521 cases the delegate commit left red. #3254 re-pins (asserted outcomes unchanged): - test_3521_problem_report_comment: the acknowledgement fixture goes through ask_service.answer (fixture shape; a raw status UPDATE carries no person ending for the snooze to read); the accessor test asserts the same type guard at the seam (a foreign row under the report's old id is never written); the lost-race test injects the bare click's whole reading, in its own thread, before the comment's locked create. - test_ent499_problem_report: write-observation point. The fake moves from create_bounded_alert to platform_alerts.observe; the routing AST test asserts the call to observe. - test_ent715_queue_person_fields: update_pending_problem_report leaves _NON_ROW_ACCESSORS (the accessor census forbids a stale entry). - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: no built-in kind is an event any more, so the property is pinned on a kind registered for the test, and both former events are asserted keyed. test_ent866_problem_report_owner_only is unchanged. Tests: keep_text at the sink, both interleavings keeping the words, one must-act row per person, target and day, the owner-only prefix, the delegate and the emitter landing on one subject, a person's ending not rewritten or reopened; the 30-day case now also shows the report still pending; the five-type admission test asserts every kind keyed. Part of #3254 * fix(operator-queue): decide a platform alert's snooze under the create's lock observe checks the snooze before the create's lock. Two moments let a person's ending slip past that check: an acknowledgement after observe read the pending row but before the locked create (the locked find then misses), and one between the locked find and _touch's compare-and-set (the lock covers creates, not respond_to_item, so the CAS loses). Either way the create fell through to an insert, and the alert a person had just ended was back at once. Before this batch most of the moved writers had a deterministic id that could not re-file after an ending, so the moves would otherwise ship that regression. create_platform_item gains snooze_since and a snoozed predicate. On the insert path, after a missed find or a lost CAS and inside the same locked transaction, it reads the newest person-ended row for the subject through the transaction's own connection (the public lookup opens another one) and returns {"outcome": "snoozed"} without inserting when the predicate says so. observe passes the standard 7-day window, computed on its own rather than from the pre-lock check's conditionally assigned cutoff, and lambda ended: _snoozed_by(kind, ended, priority, context). The pre-lock check stays as the fast path. A caller that passes neither keeps the old behaviour. The statement behind the public find_person_ended_by_subject becomes _find_person_ended_by_subject(conn, ...), shared by both reads. Tests: a person's acknowledgement through ask_service.answer, landed (a) between observe's read and the locked create and (b) between the locked find and the CAS, yields "snoozed" and no new row, for the problem report, an inbox collision as registered on dev, and the flood alarm's 6-hourly re-read. All six cases were red before this commit (a fresh row was created) and pass with it. On SQLite, BEGIN IMMEDIATE holds every other writer, so moment (b) lands the ending first and hands both finds the row as it stood just before it; two real workers are not exercised. Review fixes carried here (the earlier commits are left as they are): - OperatorQueueSyncService._maybe_emit_flood_alert: the cooldown is stamped before every reading, the 6-hourly re-read included. A failed re-read released the episode with the cooldown stamp still 6 hours old, so it was retried on the next 5-second cycle. New test: a failed re-read is retried no sooner than the cooldown (red before the fix). - test_3521_problem_report_comment (the lost-race re-pin): asserts the bare click's own request returned True and left a pending, comment-free row before the comment's locked create ran, so the test cannot pass without the interleaving it claims. - gitignore_sweep: states that past the probe's 2,000-line cap the key is the capped list plus the exact total (a full-set digest needs the in-container probe, outside this change). - test_1677_operator_alert_emitters: the census's guidance for an agent-influenceable emitter now points at platform_alerts.observe, not the delegate the #3246 ratchet counts as off the seam. - test_3254_budgeted_alerts: the frozen clock also covers db.operator_queue's ent#815 commit-lag check, which logged spurious errors against the real clock. Part of #3254 * fix(operator-queue): a failed flood re-read keeps the episode, so its end still clears the alert Fresh review of the #3254 budgeted slice (two findings): - A failed 6-hourly re-read of a persisting flood released the episode. If the condition then cleared before the retry, `_end_flood_episode` found no episode and the pending alert waited out its 14-day lifetime, although the code had seen the condition clear (AC 2). A failed re-read now keeps the episode, whose alert an earlier reading filed, and the re-read is retried once the cooldown has passed. A failed first reading still releases the episode (#3130 I1). New test: test_a_failed_reread_keeps_the_episode_so_its_end_still_clears_the_alert (red with the old release branch put back). - AC 8 for two kinds had no "a person's ending is never overwritten" test: `skill_not_found` (the next run is snoozed and sends no notification) and `alert_budget` (a later refusal re-reads the episode and the acknowledgement stands). Both added. * test(operator-queue): the budgeted-alert suite freezes the clock its running methods read In the full serial unit tier, test_1595_sync_health_signals evicts `database` and every `db.*` module from sys.modules and restores only some of them. Afterwards `database.db` and `ask_service.db` run on an older `db.operator_queue` module than the one this suite's clock fixture imports and patches, so the seam's create, the expiry sweep and the answer's compare-and-set read the real clock: rows filed at the frozen T0 read as long expired (five cases red, `AskConflict: expired`, a second flood row). The fixture now also freezes `utc_now_iso` and `datetime` in the globals of the live operations class (R6: patch what the running method reads). Red before: test_1595 followed by this file, 7 failed; green after: 66 passed; the file alone: 55 passed. * refactor(operator-queue): operator_queue_service becomes a package, content unchanged (#3785) The 2,840-line module moves to services/operator_queue_service/__init__.py byte for byte (100% similarity), the first step of the Invariant #1 split. Every `from services.operator_queue_service import X` and `from services import operator_queue_service` resolves as before. Six path-keyed guards name the file by its path, so their key moves with it (the PR #2487 precedent): _NOT_EMITTERS (test_3246), _ALLOWED_CALLERS (test_1677), _ALLOWED (test_1920), _OQS (test_ent715), FLEET_LEVEL_ALLOWLIST (test_ent467), and the source read in test_ent499. Only the key changes; the rule, the reason text and every assertion are untouched. Part of #3785 * test(operator-queue): pin the package's one-binding rules before the split (#3785) tests/unit/test_3785_operator_queue_package.py pins what S2–S6 must keep while they move code out of __init__, each property derived from the tree so no later slice edits it: modules under 800 lines (__init__ exempt, with a staleness check); the import surface src/backend and tests/ read still resolves; no from-import between package modules; one top-level binding per name; import-time reads defined first and the _MARKER_UNCHANGED default the owner's object; a patch of a re-exported name lands where its readers read; one logger identity; owner-exact qualified reads; no submodule named like a package attribute; one rate_limiter; no method on two classes of the composed service; external imports before the first submodule import, and a failed first import, injected at that line, leaves no stale submodule. The AST scans live in _oqs_package_scan.py (pure stdlib, never imports src). The other shape, a fresh install: each consumer imported first in its own interpreter on an empty database raises a bounded alert (created; only main binds a WebSocket manager, and then exactly one thin operator_queue_sync trigger goes out). Outcomes equal on the base. Part of #3785 * refactor(operator-queue): bind the service's collaborators once, in deps.py (#3785) db, _queue_db, principal_reach, get_breaker_redis, ask_service, AgentClient and the audit sink _audit_sync move to services/operator_queue_service/deps.py, bound once and read as deps.X everywhere in the package. They are no longer attributes of the package, so a stale monkeypatch.setattr(oqs, "db", ...) raises AttributeError instead of patching a copy nothing reads (Invariant #1(a), the PR #2487 rule). rate_limiter stays on the package: ask_service reads oqs.rate_limiter.check. Tests that patched a collaborator on the package now patch oqs.deps.X; no assertion, expected value, fixture or control flow changes. The package guard gains G4 (deps binds exactly the collaborators, no other module imports one from its source under any alias or holds one by identity, the package has none) and refuses any reach of a package function's __globals__. Part of #3785 * refactor(operator-queue): the queue listing engine moves to listing.py (#3785) QueueListError, narrow_to_agent_key, the cursor and walk-snapshot helpers and list_for_principal (trinity-enterprise#815) move whole from __init__ to services/operator_queue_service/listing.py. The two package-owned prefix tuples are read as _oq.X, collaborators as deps.X. The package re-exports exactly the six names read from outside (the router's list_for_principal and QueueListError; narrow_to_agent_key, encode_cursor, decode_cursor and CURSOR_MAX_BYTES, which tests call or compare). test_ent715's row-reader census re-keys list_for_principal to listing.py; no assertion changes. Part of #3785 * refactor(operator-queue): the poller core moves into PollerCoreMixin (#3785) The instance state, start/stop, the Redis leader lease, _poll_loop, _poll_cycle and _broadcast_sync move into PollerCoreMixin in services/operator_queue_service/poller.py. OperatorQueueSyncService is now composed in __init__ from the mixin and keeps its singleton there (the db/schedules shape). Package-owned names (DEFAULT_POLL_INTERVAL, _LEADER_KEY, _RESERVED_ID_PREFIXES, _websocket_manager) are read as _oq.X; the default poll_interval still binds 5 at import. Three path-keyed censuses re-key their poller entries to poller.py (test_1920's lease, test_ent467's operator_queue_sync trigger, test_ent715's _poll_cycle); no assertion changes. Part of #3785 * refactor(operator-queue): the agent-file channel leaves __init__ as whole modules (#3785) The file-channel code moves out of __init__ in four modules, so that the channel's removal (#3438) becomes a file deletion rather than surgery: * filechannel.py: the module helpers (clamping, comparison, the ingestion marker and its _MARKER_UNCHANGED sentinel, delivery matching); * rows.py: what a row says about itself, read on both sides of the package (the audience predicates, the receipt vocabulary, aging); * ingest.py: IngestMixin (_apply_sync_state, _notice_file_channel, _sync_agent); * write_back.py: WriteBackMixin (_apply_delivery_state, _write_responses_to_agent). OperatorQueueSyncService composes the two mixins; the flood methods stay on it and _sync_agent reaches them through self. The moved code is unchanged apart from owner-exact qualifications (_oq.X, filechannel.X, rows.X). Four path-keyed censuses re-key _sync_agent to ingest.py and the write-back source read to write_back.py; two tests move their _validated_addressee patch to oqs.filechannel, its owner. No assertion changes. Part of #3785 * refactor(operator-queue): the alert emitters move out; the split is complete (#3785) The bounded-alert delegates and outcome constants (create_bounded_alert, create_bounded_alert_outcome, ALERT_*) move to alerts.py, and the flood alert (_maybe_emit_flood_alert, its lazily created refresh-time dict and _end_flood_episode) moves into FloodAlertMixin in flood.py, composed into OperatorQueueSyncService. The #1677 budget episode and its cooldown state stay in __init__ with their only mutators; platform_alerts still reaches every name it reads back through the package. __init__ is now 670 lines (2,848 when this started; radon CC 0, the largest module 159), so the guard's size exemption is dropped. The package docstring records who owns what and where new code goes. The live docs that named the old single-file path, or a symbol that has since moved, are re-pointed to the owning module (path and symbol tokens only). test_3246's census re-keys create_bounded_alert to alerts.py; no assertion changes. Fixes #3785 * fix(operator-queue): a new flood, budget or untracking episode files after an acknowledgement (#3254) A person's ending of a `queue_flood`, `alert_budget` or `gitignore_untracked` row snoozed every later reading of the subject for 7 days, because none of the three kinds had a material key, so `_snoozed_by` was vacuously true. A runaway agent's second flood, a second budget-full episode and a second untracking Push of the same paths were all silent (review C1; dolho on operator_queue_service.py:2800 and gitignore_sweep.py:335). Each reading now carries an episode marker that the kind lists in its `material_keys`: - queue_flood: `episode_started_at`, stamped when the in-memory episode starts. Re-reads of one episode share it; an episode that starts after the condition cleared does not. - alert_budget: `filled_by`, a digest of the ids of the pending rows filling the budget. Re-reads of the same full budget share it; once a slot frees and a new row fills it, it differs. - gitignore_untracked: `push_id`, one per call. The emitter runs once per Push, so every untracking Push after an acknowledgement files; repeats still collapse onto a pending row. So the snooze silences re-reads of the acknowledged episode for the snooze window and a new episode files at once, which makes the `_maybe_emit_flood_alert` docstring's #3130 edge-trigger claim true again. The budget episode's read of the filling rows is classified in the ent#780 row-reader census as internal. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * fix(operator-queue): a flood re-read no longer stamps the per-agent cooldown; the oversize end is pinned (#3254) Review follow-ups on the flood alarm: - dolho on operator_queue_service.py:2778 (webmixgamer agreed): the 6-hourly re-read of one reason's episode stamped the per-agent `_flood_alert_cooldown`, so the other reason's first alert could wait up to one cooldown. The cooldown spaces episodes and a re-read is not one, so it is now stamped only before an episode's first reading. A failed re-read's retry spacing already comes from its refresh time. - webmixgamer I3: the 6-hour re-read spacing is one constant, `OPERATOR_QUEUE_FLOOD_REREAD_SECONDS`, read by the gate and by the failed re-read's retry arithmetic, so the two cannot drift. - webmixgamer I1: a `_sync_loop` case serves an oversized file and then a sane one and asserts the row ends as the platform. It goes red when `_sync_agent`'s `_end_flood_episode(agent_name, "oversize_file")` is replaced by a bare episode discard. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * docs(operator-queue): state the fail-open double-leader bound on the flood episode marker (#3254) The episode marker is worker-local. With Redis down the leader lease fails open, so each worker stamps its own episode_started_at and another worker's re-read can file past a person's ending, at most one extra row per extra worker per re-read window. Docstring only; no behaviour change (review L1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): __init__ drops its file-level F401 waiver (#3785) Review I1 (dolho): the file-level `# ruff: noqa: F401` switched off unused-import detection for all of `__init__`, so a dead import left behind by a later slice or feature would go unflagged. At this PR's head `__init__` still reads every name in its import block, so the waiver hid nothing: `ruff check --select F401` gives 0 findings with it removed. It is dropped, and the block's comment now says that a name `__init__` stops reading keeps its line with a per-line waiver naming why (G13, or read as `oqs.X` from outside). PR2, PR3 and PR4 add those per-line waivers where their moves leave a name unread. `deps.py` keeps its file-level waiver: it is a binding module whose imports are its bindings, so there is no import there F401 could rightly flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): per-line F401 waivers for what __init__ stops reading (#3785) Review I1 on #4036: PR1 dropped `__init__`'s file-level F401 waiver. This slice's moves leave four of its imports unread in `__init__`; each now carries its own `noqa: F401` with the reason, so F401 keeps checking every other line: - `asyncio`, `base64`, `uuid`: kept for G13, because `listing` and `poller` import them at module level. - `from . import listing`: loads the submodule at its G6 point; the names callers read come from the re-export block. `ruff check --select F services/operator_queue_service/` is clean. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): per-line F401 waivers for what __init__ stops reading (#3785) Review I1 on #4036: PR1 dropped `__init__`'s file-level F401 waiver. This slice's moves leave these names unread in `__init__`; each now carries its own `noqa: F401` with the reason, so F401 keeps checking every other name: - `datetime`, `timedelta`, `timezone`, `Sequence`, `options_cap_violation`, `title_cap_violation`: kept for G13, because `rows`, `filechannel` and `ingest` import them at module level. - `rate_limiter`: O1(d), read as `oqs.rate_limiter` from outside (`ask_service`, tests) and as `_oq.rate_limiter` in `ingest`. - `to_utc_iso`: read as `oqs.to_utc_iso` from outside (`test_ec_operator_queue_properties.py`) and kept for G13. - `from . import filechannel` / `rows`: load the submodules at their G6 point; the names callers read come from the re-export block. The `typing` and `utils.helpers` imports become parenthesised so the waiver sits on the one unread name, not the whole line. They stay single statements: splitting one into two breaks the guard's failed-first-import leg, which injects the failure at the module's first statement. `ruff check --select F services/operator_queue_service/` is clean. With every waiver stripped in a scratch copy, the F401 findings are exactly the waived names, and an injected dead import is still reported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): per-line F401 waivers for what the integrated __init__ stops reading (#3785) With both PR2's and PR3's moves in `__init__`, two more names go unread there: `iso_cutoff` and `parse_iso_timestamp`. Each gets its own `noqa: F401` (kept for G13: `listing`, `rows`, `filechannel` and `ingest` import them at module level). With every waiver stripped in a scratch copy, the F401 findings are exactly the waived names. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): per-line F401 waivers for what __init__ stops reading (#3785) Review I1 on #4036, at the slice where the import block is final. PR1 dropped `__init__`'s file-level F401 waiver; PR2, PR3 and the integration added per-line waivers for the names their moves left unread. This slice leaves two more: - `utc_now_iso`: kept for G13 (`poller`, `filechannel`, `ingest`, `write_back` and now `flood` import it at module level); - `from . import alerts`: loads the submodule at its G6 point; the names callers read come from the re-export block. `hashlib` and `deps` are read in `__init__` again since #4021's budget episode digest (`deps.db.list_operator_queue_items`, `hashlib.sha256`), so they carry no waiver. With every waiver stripped in a scratch copy, the F401 findings are exactly the waived names (16 per-line, plus the four re-export blocks), and an injected dead import is still reported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * docs(operator-queue): re-point the last live pointers to the deleted single-file path (#3785) Review I1 on #4039 (dolho): the sweep covered `docs/memory/**` and `db/operator_queue.py`, but a few live pointers to `services/operator_queue_service.py` survived. Each now names the package, or the module that owns the cited code: - `tests/registry.json`, the two `/edge-cases` entries' descriptions: `services/operator_queue_service/`. - `docs/requirements/OPERATOR_QUEUE_OPERATING_ROOM.md`: the §2.2 `**Location**` line and the §4 implementation-map row: `src/backend/services/operator_queue_service/`. This spec is still edited by features (#3242, ent#715), so it is a live map, not a frozen record. - `tests/unit/test_ec_operator_queue_edges.py:9,121,235`: the package directory, and `operator_queue_service/ingest.py` for the two `_sync_agent` citations (the `_ID_RE` guard and the #3243 block). - `tests/unit/test_3274_gate_wiring.py:111`: `operator_queue_service/poller.py` (`_poll_cycle` runs the sweep). The two test files change only in comments and docstrings: their ASTs with docstrings stripped are identical to before, so no assertion, value or control flow moves (not an E1–E3 test edit). Left as they are, because they are point-in-time records: the dated `docs/memory/learnings.md` entries (`:1075`, `:1323`), migration `0039_operator_queue_addressed_to.py:10`, and `docs/{archive,releases, security-reports,metrics}/`. `test_ent499_problem_report.py:247` cites the service's `_write_responses_to_agent` by symbol, not by path, and the composed service still has it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * test(operator-queue): ent#981's file-path case patches `_validated_addressee` on `filechannel` (#3785) test_ent981_addressee_reach arrived from dev (#4148) patching the name on the package. This slice moves `_validated_addressee` to `filechannel.py`, where `_clamp_ingested_item` reads it, so the package no longer binds it: the patch raised AttributeError, and the #3785 G7 guard refused it. Same target as test_ent734's two patches of the same name. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: trinity-ability <309458136+trinity-ability@users.noreply.github.com>
…4622) * feat(agents): a tag in github:owner/repo@ref pins the clone; purge_agent_now removes an agent at once, audit first (#4183) * feat(subscriptions): admission policy seam for a per-agent usage share (A) One edition-agnostic point where a registered policy may stop an agent's turn before it is admitted, on every door. With no policy registered nothing changes. The first intended policy is an agent's share of its subscription's usage, registered through this seam by an optional module. - services/admission_policy.py: register / enforce / notice. A policy refuses with chat_signals.AdmissionRefused (code, plain-words message, frees_at); any other policy error is logged and the turn is admitted. - /chat (admit_chat_request) and /task (dispatch_parallel_task) call it after the skill gate, before the idempotency claim: a refused request claims, uploads, writes and acquires nothing. - execute_task step 1c covers every other door: the row closes SKIPPED with the message (not FAILED: no schedule failure count, no breaker), error_code usage_share, and the refusal on the result. - routers/chat.py maps it to 429 + X-Trinity-Error-Code + Retry-After; a sync /task refused inside execute_task releases its claim and gets the same answer; the Workspace shows the message as category `limit`, not retryable. - ExecutionContext.usage_notice renders the policy's notice as a `- **Usage**:` line via compose_system_prompt's auto-fill. Tests: tests/unit/test_ent1059_admission_policy_seam.py (18). Each seam call, the SKIPPED write, the router mapping, the Workspace branch, the notice fill and the fail-open re-raise were removed one at a time and a named test went red each time. test_2638's pre-dispatch allowlist gains `policy_denied` with its reason. Refs abilityai/trinity-enterprise#1059 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(subscriptions): usage-share refusal survives the task backlog drain (B) A share that ran out while a sync /task waited in the backlog: the drain closes the row SKIPPED, and a long-poll that reads the terminal back from the row (another worker drained it, or the wait timed out) rebuilt a success-shaped result from a SKIPPED row. It now answers the seam's own refusal. - execute_task's policy gate stores the row error as `[usage_share] text` (the #3114 pull-sink shape), so a reconstruct can tell a share stop from any other SKIPPED; the in-memory result keeps the plain message. - _dispatch_sync_backlog's reconstruct branch rebuilds AdmissionRefused from a SKIPPED row carrying that code; _map_task_failure then releases the claim and the router answers 429 usage_share (no Retry-After: the row has no frees_at, the message says when). Tests: test_ent1059_admission_policy_seam.py +2 (20). The reconstruct removed -> the drain test red; the prefix removed -> the SKIPPED-row test red; each restored from a copy. Refs abilityai/trinity-enterprise#1059 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(subscriptions): usage share card and breakdown column (C) An agent's share of its subscription's usage, as its owner reads and changes it. Both surfaces render only when the instance is entitled to `usage_share`; an unentitled build calls nothing. - Settings > Guardrails gains a "Usage share" section (UsageShareCard): the rolling 7-day and 5-hour windows as used / budget with a meter, the warning line drawn at warn_pct, Warning / Stopped badges in words, when a stopped window frees, whether a stop ask is pending, the line the agent reads on its next turn, and where each number comes from. The owner changes it inline through the PUT; an empty field is the platform default and all three empty clears the override. Bounds are named client-side before a request; a refused PUT keeps the form open with an InlineError. Applies from the next turn, no restart. - Settings > Subscriptions per-agent breakdown gains "Share used (7d · 5h)": each agent's own percent, warning/danger tone from the share's own threshold; a share the reader cannot see renders a dash, never 0%. - stores/agents.js: getUsageShare / setUsageShare (single API client). stores/subscriptions.js: fetchAgentShares, per-agent isolated. Tests: src/frontend/tests/unit/usageShareCard.spec.js (22, mounted under jsdom). Mutations each turned it red and were restored from a copy: breakdown ungated (1 red), at_budget ignored (2), client validation bypassed (5), Guardrails section ungated (1). Raw-colour ratchet: no existing file grew; the new card carries 0 raw non-gray. Refs abilityai/trinity-enterprise#1059 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(execution): every door answers an admission-policy refusal; a refused loop iteration is skipped, not failed (abilityai/trinity-enterprise#1059 fix) Review C2, H1, the test_3274 sweep red and I5 on the pre-admission policy seam. C2: a turn an admission policy stopped inside `execute_task` is a SKIPPED row `[usage_share] <sentence>`, and `_admission_policy_gate` returned it as a result rather than raising — so every `dispatch_and_await_terminal` caller that branched on failed/cancelled only answered success-shaped with an empty reply. On the paid door that attached the execution to the claim, logged verify-ok and SETTLED a charge for a turn that never ran. - `chat_signals.admission_refusal_of(result, agent_name)` is the one rule: the in-memory attribute when the gate ran in this process, else a rebuild from the row's `skipped` + code shape. `result_from_execution_row` attaches it, so a turn refused on another worker (the backlog drain, a long-poll reading the row back) carries the same refusal; the separate rebuild in `_dispatch_sync_backlog` is that call now. - One branch per door, before failed/cancelled: paid releases the claim and neither attaches nor settles (no charge; `payment.reason` is the sentence); MCP inline chat answers 429 with the sentence and `X-Trinity-Error-Code`; a channel sends the sentence and returns before step 12 so no empty assistant turn is persisted; the public link answers 429 (sync) or stores the sentence as the reply (async); `portal_chat` reads status + code as well as the attribute; a room posts the policy's sentence and keeps its resume handle and cursor; A2A maps `skipped` to `rejected` with the message on the inline path as `_ROW_STATE` already did for the row; a refused validation turn is an ERROR verdict. The scheduler (`internal.py`), fan-out and operator-resume doors already record the skipped row with its message and need no branch; voice and the brain orb call `execute_task` directly and close SKIPPED. H1: `loop_service._close_run` counted a policy-refused SKIPPED as a failed run (only a gate-held SKIPPED was exempt), so `failed_runs` rose, `on_failure` applied, and an at-budget loop kept ticking to `max_runs`. It now reads the refusal off the row (`_split_error_code` + the predicate), closes the run `skipped`, counts nothing, and stops the loop with the code as `stop_reason`. Sweep: `usage_notice` joins the platform-controlled list in `test_3274_gate_context` — the line is composed by a policy from platform numbers and never reads requester text. I5: `fetchAgentShares` runs at most six reads in flight. Docs: `requirements/security.md` §20.5d and `architecture/execution.md` state the result-not-worker rule and each door's branch. Red before the fix, with the door code reverted and the predicate kept: all ten door tests in `test_ent1059_refusal_doors.py` (the paid one read `settled`, the Workspace one DID NOT RAISE, A2A read `failed`) and both loop variants beside the ent#751 hold test (`('failed', 'error')`); restored byte-identical. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(completion-report): a refused turn's report shows the policy's sentence, not its [usage_share] code (abilityai/trinity-enterprise#1059 re-review N1) An admission-policy refusal closes the row SKIPPED with `[usage_share] <sentence>`, and the completion report (Workspace, Slack, Telegram) posted that text as-is. The report now strips a known `[code]` prefix from a non-success terminal before sanitising; an unknown `[...]` and any success text stay as the agent wrote them. `_split_error_code` moves to the cycle-free `execution_envelope` leaf as `split_error_code` so the report uses the same parser; the old names stay importable from `task_execution_service`. Also adds an executing spec for `fetchAgentShares`' six-lane cap (re-review N3): a deferred `getUsageShare` over 15 names, high-water mark 6, every name written, a failed read as `{ error: true }`. Mutation-checked: with the cap at 100 it fails (expected 15 to be 6). Red before the fix: test_the_workspace_report_shows_the_sentence_without_the_code, test_the_channel_report_shows_the_sentence_without_the_code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(agents): a dotted tag in github:owner/repo@ref pins the clone The ref after `@` was checked against [A-Za-z0-9_-/] only, so a release tag such as v1.2.0 failed the check and was dropped without a word: the agent was created on main while the caller believed it pinned. The ref is now taken whole when it is a valid branch or tag name (dots allowed, minus the git ref-format shapes '..', a leading-dot component, a trailing '.' or '.lock'), and an unusable ref is a named 400 instead of a silent fall-back to main. The charset stays a shell-safety barrier for startup.sh's eval-built clone. Red first: tests/unit/test_4165_github_ref_tag.py — the five dotted refs returned url_branch=None and the ten unusable refs did not raise. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(agents): purge_agent_now removes an agent at once, audit first (abilityai/trinity-enterprise#1055) Agent delete is a soft delete (#834): rows, volumes and the MCP key stay for the retention window. Removing an invited member's agent, or rolling back a half-created one, must leave nothing but the audit trail, so the retention sweep's hard purge becomes an immediate, edition-agnostic primitive with no route of its own: - the agent_lifecycle:purge audit row is written while the agent still exists and outlives it; if it cannot be written nothing is destroyed (503) - a person caller must pass assert_admin (an agent key carrying an admin owner's role is refused); actor=None is the platform itself - container, queued and in-flight work, Redis state, the #816 cascade (sharing, permissions both ways, MCP key) and the data volumes under both identities of a renamed agent (#1664) go; a base another agent claims stays; a Docker fault never stops the row purge - system agents (403) and ephemeral agents (409) are refused; no row is a no-op Red first: tests/unit/test_ent1055_purge_agent_now.py (module absent). Each of five mutations turns it red: admin gate removed (2), fail-closed removed (1), soft-delete-before-purge removed (7), base-claim guard removed (1), audit moved after the container removal (2). Docs: requirements/core-agent.md §1.4.1 and §4.2 ref pinning (trinity#4165); architecture/agent-lifecycle.md pointer. Registry: both new test files. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(agents): a tag in github:owner/repo@ref survives the three ref-existence checks (trinity#4165, abilityai/trinity-enterprise#1055 review C1) The parser accepted a dotted tag and stored it in `source_branch`, but every check that consumed that value before the clone asked for a BRANCH of that name: `provisioning.check_remote_branch_exists` ran `ls-remote --heads refs/heads/<ref>`, `ref_probes._ref_arg` prefixed `refs/heads/`, and the PAT path asked `GET /repos/{repo}/branches/{ref}`. So a tag passed the parser and was refused with "Branch 'v1.2.0' not found" on every path; the public doc claimed it pinned the clone. Now all three accept a branch or a tag, the ref still a value after the URL and never an option: the anonymous check asks for `refs/heads/<ref> refs/tags/<ref>` with no `--heads`; the probes ask for both and take the branch first (as `git clone -b` does), peeling an annotated tag to its commit; the REST path answers a 404 on `/branches/{ref}` with `/git/ref/tags/{ref}` before calling the ref missing. The refusal names both: "Branch or tag '…' not found". Red first: `tests/unit/test_4165_ref_existence_checks.py` drives the real `check_remote_branch_exists`, `probe_anonymous_ref`, `probe_tokened_repo_access` and `_validate_github_access` on all three paths against a fake `ls-remote` that filters like git (so a check that asks for heads only cannot see the tag) — 9 of 15 red before the change, all green after. Three pins on the old branch-only contract moved with it (`test_3725_*`: the argv now carries both refs and a same-named tag answers when no branch does; `test_ent123_tokenless_clone`: the wording). Docs: `requirements/core-agent.md` §4.2 names the three checks and the precedence; the two flow rows that quoted `--heads` / the old wording follow. Registry entry added. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(agents): a ref in github:owner/repo@ref may not begin with '-' (trinity#4165, abilityai/trinity-enterprise#1055 review I5) `_GITHUB_REF_RE` admitted `-foo`. Safe today — every live site passes the ref as a value (`git clone -b <ref>` takes the next token whatever it starts with; the probes prefix `refs/…`) — but `startup.sh` also runs `git checkout "${SOURCE_BRANCH}"`, where a leading `-` IS parsed as an option, benign only because the clone already checked the ref out. One shell edit away from not. The regex gains `(?!-)`; the 400 names it. Red first: `TestRefRefused[-foo]` — DID NOT RAISE. Upgrade-safe: the parser has one caller (creation); no stored `source_branch` is re-parsed on boot, pull or reset, so existing agents are untouched. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(agents): an annotated tag in @ref resolves to its commit, not the tag object (trinity#4165) `ref_probes` asked `ls-remote` for `refs/heads/<r>` and `refs/tags/<r>` and took a peeled `refs/tags/<r>^{}` line when one was listed. git never listed one: it shows a ref only when a pattern names it, and the peeled line's name ends in `^{}`. So an annotated tag resolved to the TAG OBJECT, and the raw template read was pinned to an id that is not the commit the clone checks out. The probe now also asks for `refs/tags/<r>^{}` by name. The unit fake listed `^{}` lines for a bare tag pattern, which is why the old test passed. It now lists a ref only when a pattern names it, and a new file runs the probes against a real bare repository over file:// (a lightweight tag, an annotated tag, a branch and an annotated tag sharing a name). Red first: test_4165_ref_probes_real_git.py — the annotated-tag and tokened cases returned the tag object id; 4 others passed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(agent-server): a tag-pinned agent's pull cycle is a named skip, not a failure every tick (trinity#4165) `github:owner/repo@<tag>` clones with `git clone -b <tag>` in source mode, which leaves the agent on a detached HEAD: pinned to that release, by design. Pull sync is on for every `github:` agent, and `_run_pull_once` recorded `failed: detached HEAD: nothing to pull onto` on every cycle, a failure streak for an agent doing what it was asked to. A detached HEAD now records `skipped` with the reason named. A detached HEAD left by a rebase stopped part-way (its rebase-merge/rebase-apply directory exists) stays `failed`, so a stuck tree still shows. The push cycle is unchanged: it is off by default for a source-mode agent, and an owner who turns it on for a pinned agent gets an honest failure. Red first: test_4165_pull_cycle_pinned_tag.py::test_every_cycle_is_a_named_skip_not_a_failure — 'failed' == 'skipped'. Real repos, the agent cloned -b v1.0.0 (annotated). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Trinity Agent (trinity) <trinity-agent@ability.ai> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: trinity-ability <309458136+trinity-ability@users.noreply.github.com> * fix(credentials): keep the credential read inside the agent home and make the paste guard linear (#4191) * fix(agent-server): the credential read stays inside the agent home (trinity-enterprise#1066) CodeQL flagged the `os.lstat` this branch added to `GET /api/credentials/read` (path depends on a user-provided value). The finding is real at the guard, not at any current caller: - the guard (`lstrip("/").lstrip(".")`, a `".." in` test on the stripped string, `str(resolved).startswith(str(home))`) let a single leading `../` through, and its prefix compare had no separator, so `../home2/.env` READ a file in a sibling directory whose name extends the home's; - the new `lstat` ran before any containment check, so `../<anything>` came back in `missing` — an existence probe one level above the home. Not reachable before this fix through the platform: the route sits behind the agent's per-agent auth middleware (#1159) and every backend caller sends fixed relative paths (`.env`, `.mcp.json`, `.credentials.enc`) or the agent's own `/list` output. Fixed at the root with one helper, `_contained_read_target`: refuse absolute paths and any `..` component, then require both the normalised lexical path and the link-resolved path to sit under the home with a trailing separator. `lstat` runs on the contained lexical path (the absence proof); the read goes through the contained resolved path, so a link is followed only to a target that is itself inside. Red first: tests/unit/test_ent1066_credential_read_containment.py — 5 of 13 red at the previous guard (sibling read, `../` oracle, absolute path, link to a sibling file, linked parent directory), all green with the fix; the fix reverted from a scratch copy turns the same 5 red. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(sanitizer): the paste guard's KEY=value walk is linear by construction (trinity-enterprise#1066) CodeQL flagged the two regex calls in `secret_shape` (py/polynomial-redos, "may run slow on many repetitions of '!'"). Origin: the patterns pre-exist on dev — `_KV_LINE_RE` / `_KV_PAIR_RE` are the redaction's #1661/#3311 walk — but these two alerts are introduced by this branch, which feeds them a Workspace chat message (user-provided text) through the new guard. Measured before the change, CPython was already linear on every shape tried (`!`*n, `=`+`!`*n, `!`*n+`=`, `!=`*n, `k=!`*n, an unclosed quote, sensitive keys with short values): 1M characters took 0.04-1.1 s, scaling ~10x per 10x. The lookbehind pins each key to the start of its run — the engine detail CodeQL's model does not see (#1661 says the same). The route caps a message at 100k characters. The guard no longer rests on that detail. It finds each `=` with `str.find`, walks back to the key start (never past the previous `=`, so no character is visited twice), and checks the value with one fixed-width match — an optional opening quote and eight non-space, non-quote characters. No length cap, so nothing at the end of a long message is dropped. One deliberate widening: the closing quote is no longer required, because a truncated paste is still the secret. The redaction path is unchanged. Red first: tests/unit/test_ent1066_secret_guard_linear.py — red before the change on the no-unbounded-regex pin and the unclosed-quote case (2 of 43); the timing bound (1M < 3 s, 10x input < 30x time) and both-way detection were green before and after. The change reverted from a scratch copy turns the same 2 red. The 1661/2208/2398/3840 sanitizer suites and the paste-guard suite stay green (608 passed). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Trinity Agent (trinity) <trinity-agent@ability.ai> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * chore(enterprise): bump the submodule pointer to main (448cdbc -> f347a02) (#4193) Picks up abilityai/trinity-enterprise#1072 (member_agents module, ent#1055), which composes the purge_agent_now primitive from #4183. Co-authored-by: trinity-ability <309458136+trinity-ability@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * revert: an agent's share of a subscription (#4180) (#4199) * Revert "feat(subscriptions): an agent's share of a subscription, enforced at every door (#4180)" This reverts commit 9eedbbb6e0be8d5b73ccb5e8f0217a33a987b089. * chore(enterprise): bump the gitlink to the ent#1070 revert (trinity-enterprise#1076) Lands with the #4180 revert so dev never carries the usage_share module without the admission_policy seam it imports. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: trinity-ability <309458136+trinity-ability@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * fix(sub-003): the agent's auth answer outranks a prompt-length mention, and the turn-limit anchor is pinned (#4123) (#4197) * fix(workspace): keep a room's content inside the Inbox reading pane (#4160) (#4169) Every agent bubble renders PortalMarkdown's sr-only live region, which is position:absolute. The reading pane's scroll box was not positioned, so those regions resolved against the page, escaped the overflow box, and a long room stretched the document: the wheel scrolled the whole Workspace. Make the scroll box `relative`, as the list column's already is. Adds a mount spec pinning the containment structure for a long room, a room with many messages, and a thread. Fixes #4160 Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * refactor(operator-queue): the listing engine moves to listing.py, and the poller core into PollerCoreMixin (#3785, PR 2 of 4) (#4037) * fix(operator-queue): the #1677 helper delegates to the platform-alert seam create_bounded_alert(_outcome) keep their signatures and outcome contract and become a thin delegate of platform_alerts.observe, which already composes the per-(agent, type) budget inside its one locked create. The registered type names its kind; the key is read back from the item's id and context by derive_legacy_subject and must resolve to that same kind, else ALERT_FAILED_CREATE. The two kinds whose ids carry no subject (gitignore, problem report) are keyed by the request id minus the kind's prefix. observe's "updated" and "snoozed" pass through; "failed" maps to ALERT_FAILED_CREATE; every refused or failed arm logs [#1677 budget]. ALERT_FAILED_COUNT stays importable and is no longer returned. The budget episode reports through observe as kind alert_budget keyed by the budgeted type: one alert_budget:<type> row per agent, re-read by a later refusal outside the cooldown, ended by its 14-day lifetime. The bucketed id and its own operator_queue_new broadcast are gone; observe sends the thin operator_queue_sync trigger. Ratchet: create_bounded_alert_outcome and _maybe_emit_alert_budget_episode leave EMITTERS_NOT_YET_ON_SEAM; alert_budget gets a NO_CLEAR_SITE reason. Census: both leave _ALLOWED_CALLERS (no direct create left in either). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_budget: write-observation point. The harness stands in for the seam's create with the same budget arithmetic and runs what observe spawns. Id shape in test_deterministic_bucketed_id_with_reserved_prefix, test_cooldown_knob_zero_never_raises (the subject replaces the bucket) and test_under_cap_creates_item_and_notification (the seam's id). The episode raise now stays in its spawned task, so test_episode_helper_raise_swallowed_refusal_stands reads the delegate's WARNING marker; test_ws_broadcast_failure_swallowed checks the thin operator_queue_sync payload. - test_3130_flood_guard, test_1632_operator_queue_caps: write-observation point. The flood alert still rides the delegate, so its writes, the typed budget read and the I1 fault injection move to the seam's create. - test_3243_atomic_asks::test_a_cap_hold_never_fires_the_flood_alert: write-observation point. Watched at observe, since the oqs.db assertion alone would now pass whether or not the alert fired. Known until the problem report moves in its own commit: nine test_3521_problem_report_comment cases are red here. The delegate files an event-kind row under the seam's id, which the old _attach_comment (keyed on the pre-seam request id) cannot find. New: tests/unit/test_3254_budgeted_alerts.py (registry parity, reach-back imports, the delegate's outcome table over all five budgeted types, the episode's seam properties, R1 for alert_budget). Part of #3254 * fix(operator-queue): the flood alarm reports through the seam and ends with its episode OperatorQueueSyncService._maybe_emit_flood_alert reports through platform_alerts.observe as kind queue_flood keyed by the reason: one pending row per (agent, reason), rewritten in place, budgeted by the seam. #3130's outcome rule is kept on observe's strings: a failed write releases the episode and is retried after the cooldown (I1); created, updated, snoozed and refused consume it. While an episode lasts it is re-read at most every 6 hours, so the kind's 14-day lifetime ends only a row nobody re-read, never a condition that still holds. The refresh time per (agent, reason) is a dict the method creates on the instance for itself; __init__ is unchanged. The flood's own operator_queue_new broadcast (which carried the title) is gone; observe sends the thin operator_queue_sync trigger. The two _sync_agent statements where an episode ends (_flood_episodes.discard for oversize_file and ingestion_cap) become calls to the new _end_flood_episode, which ends the episode and, only when one was running, ends its alert as the platform through platform_alerts.clear. A cycle with no episode costs no read. Ratchet: _maybe_emit_flood_alert leaves EMITTERS_NOT_YET_ON_SEAM; queue_flood's clear site is _end_flood_episode. No re-pin in this commit: the #3130 and #1632 harnesses were moved to the seam's create in the previous commit and keep their results. Tests: the flood through the real _sync_agent poll for 30 simulated days with the real expiry sweep (one row, re-read every 6 hours, ended as the platform when nothing is held), no read without an episode, two reasons two subjects, I1 on the real seam, a person's ending standing through the re-read and the clear, the thin trigger, R1 for queue_flood. Part of #3254 * fix(execution): the effect guard and missing-skill alarms report through the seam _on_unguarded_effect reports a refused effect through platform_alerts.observe as kind effect_unguarded keyed "<effect_type>:<reason>": one row per agent, effect and reason, rewritten by each further refusal, ended by its lifetime (nothing observes an agent starting to send ids). The send is refused whatever the alarm's outcome. _alert_skill_not_found reports through observe as kind skill_not_found keyed by the truncated command: one row per agent and command, re-read by each scheduled run. The paired notification is sent only on "created": a repeat of a pending command is an "updated" reading and already had one; refused, failed and snoozed wrote no new row. The pre-create dedup read stays and now matches only a pending pre-#3246 row (no subject), which keeps standing for its command until the upgrade sweep stamps it; a seam row is re-read through observe, where a repeat is never refused at the cap. task_execution_service.py: only _alert_skill_not_found changes. Its module-level utc_now_iso import is now unused and is left in place. Ratchet: _on_unguarded_effect and _alert_skill_not_found leave EMITTERS_NOT_YET_ON_SEAM; skill_not_found gets a NO_CLEAR_SITE reason (only the dispatch path could see a command resolve, and there the detector cannot tell "resolved" from "not a slash command"). #3254 re-pins (asserted outcomes unchanged): - test_1677_operator_alert_emitters:: test_skill_not_found_emitter_is_routed_not_allowlisted: the module must call platform_alerts.observe naming "skill_not_found" (AST), the seam that composes the budget, instead of mentioning create_bounded_alert. - test_2392_effect_guard_fail_closed: write-observation point and id shape. The alarm is recorded at platform_alerts.observe instead of a sys.modules stub of operator_queue_service, which lacks the names the seam reaches back for. The id prefix is asserted on the kind; the at-budget case returns the seam's refused_at_budget. - test_ent879_aauth_resource_route (the refused-call case): the dead create_bounded_alert patch moves to platform_alerts.observe. Tests: the effect refusal's seam properties and lifetime; the missing skill's one row per command, no notification on a repeat, a pre-seam row still standing, no notification at the cap; R1 for both kinds; the other shape, the clock 30 days ahead: a full skill_not_found budget frees itself through the real expiry sweep and a new command files. Part of #3254 * fix(git-sync): the gitignore sweep's alert is one row per change set _emit_gitignore_untracked_alert reports through platform_alerts.observe as kind gitignore_untracked, which stops being an event kind (platform_alerts.py: event=True dropped). It is a must-act kind: no lifetime, never ended by the platform. It is keyed by the change itself: a 32-hex digest of the canonical, direction-tagged set of paths the Push untracked and newly un-ignored (sorted removed paths, the exact removed count, sorted un-ignored paths). A repeat of the same set collapses onto one row; a different set, a different total behind a capped list, or the same path in the other direction is a different row. Keying per agent would let a later Push overwrite an earlier Push's path list on a pending must-act alert, which #2529 calls the surface that outlives the session. The legacy prefix keeps its _no_subject parser, so pre-existing rows stay pending until a person acts. Ratchet: _emit_gitignore_untracked_alert leaves EMITTERS_NOT_YET_ON_SEAM. #3254 re-pins (asserted outcomes unchanged): - test_2529_gitignore_precedence: write-observation point and id shape. The alert is watched at platform_alerts.observe (the two create.await_count == 0 checks would otherwise have gone vacuous); the per-agent id prefix is asserted on the kind, with the 32-hex key. - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: gitignore_untracked is a condition now, so it is asserted keyed and the problem report stays the event example. Tests: a repeated set is one row that never expires; distinct sets and a capped list with another total stay distinct; the direction tag holds; a person's ending stands; the 30-day case now also shows the gitignore row still pending. Part of #3254 * fix(workspace): the problem report is one seam row per person, target and day raise_problem_report reports through platform_alerts.observe as kind workspace_problem_report, which stops being an event kind (event=True dropped). It is keyed by the 32-hex digest _problem_report_id already computes: one row per person per target per UTC day, the "never duplicates" rule its docstring states. A person must act on it, so it never expires and the platform never ends it. The workspace-problem- id prefix is kept, so ent#866's owner-only rule and the machine-key "about a person" exclusion still hold. It returns True when the row was created or updated, False when snoozed, refused or failed. #3521's words-only rule moves under the seam's lock. observe gains keep_text (passed through database.create_platform_operator_queue_item to create_platform_item and _touch): with keep_text and a pending row, the reading only counts (last_seen_at, seen_count, expires_at) and the title, question, priority and context stand. The bare click passes keep_text, a reading with words does not. The click and the comment are two background requests that meet on one row inside the per-agent lock, so either order ends with the words. With no pending row the reading files as usual. update_pending_problem_report (database.py, db/operator_queue.py) and the nested _attach_comment are removed: one write path. Ratchet: raise_problem_report leaves EMITTERS_NOT_YET_ON_SEAM, which fixes the nine test_3521 cases the delegate commit left red. #3254 re-pins (asserted outcomes unchanged): - test_3521_problem_report_comment: the acknowledgement fixture goes through ask_service.answer (fixture shape; a raw status UPDATE carries no person ending for the snooze to read); the accessor test asserts the same type guard at the seam (a foreign row under the report's old id is never written); the lost-race test injects the bare click's whole reading, in its own thread, before the comment's locked create. - test_ent499_problem_report: write-observation point. The fake moves from create_bounded_alert to platform_alerts.observe; the routing AST test asserts the call to observe. - test_ent715_queue_person_fields: update_pending_problem_report leaves _NON_ROW_ACCESSORS (the accessor census forbids a stale entry). - test_3246_platform_alerts_leaf::test_event_kind_has_no_subject: no built-in kind is an event any more, so the property is pinned on a kind registered for the test, and both former events are asserted keyed. test_ent866_problem_report_owner_only is unchanged. Tests: keep_text at the sink, both interleavings keeping the words, one must-act row per person, target and day, the owner-only prefix, the delegate and the emitter landing on one subject, a person's ending not rewritten or reopened; the 30-day case now also shows the report still pending; the five-type admission test asserts every kind keyed. Part of #3254 * fix(operator-queue): decide a platform alert's snooze under the create's lock observe checks the snooze before the create's lock. Two moments let a person's ending slip past that check: an acknowledgement after observe read the pending row but before the locked create (the locked find then misses), and one between the locked find and _touch's compare-and-set (the lock covers creates, not respond_to_item, so the CAS loses). Either way the create fell through to an insert, and the alert a person had just ended was back at once. Before this batch most of the moved writers had a deterministic id that could not re-file after an ending, so the moves would otherwise ship that regression. create_platform_item gains snooze_since and a snoozed predicate. On the insert path, after a missed find or a lost CAS and inside the same locked transaction, it reads the newest person-ended row for the subject through the transaction's own connection (the public lookup opens another one) and returns {"outcome": "snoozed"} without inserting when the predicate says so. observe passes the standard 7-day window, computed on its own rather than from the pre-lock check's conditionally assigned cutoff, and lambda ended: _snoozed_by(kind, ended, priority, context). The pre-lock check stays as the fast path. A caller that passes neither keeps the old behaviour. The statement behind the public find_person_ended_by_subject becomes _find_person_ended_by_subject(conn, ...), shared by both reads. Tests: a person's acknowledgement through ask_service.answer, landed (a) between observe's read and the locked create and (b) between the locked find and the CAS, yields "snoozed" and no new row, for the problem report, an inbox collision as registered on dev, and the flood alarm's 6-hourly re-read. All six cases were red before this commit (a fresh row was created) and pass with it. On SQLite, BEGIN IMMEDIATE holds every other writer, so moment (b) lands the ending first and hands both finds the row as it stood just before it; two real workers are not exercised. Review fixes carried here (the earlier commits are left as they are): - OperatorQueueSyncService._maybe_emit_flood_alert: the cooldown is stamped before every reading, the 6-hourly re-read included. A failed re-read released the episode with the cooldown stamp still 6 hours old, so it was retried on the next 5-second cycle. New test: a failed re-read is retried no sooner than the cooldown (red before the fix). - test_3521_problem_report_comment (the lost-race re-pin): asserts the bare click's own request returned True and left a pending, comment-free row before the comment's locked create ran, so the test cannot pass without the interleaving it claims. - gitignore_sweep: states that past the probe's 2,000-line cap the key is the capped list plus the exact total (a full-set digest needs the in-container probe, outside this change). - test_1677_operator_alert_emitters: the census's guidance for an agent-influenceable emitter now points at platform_alerts.observe, not the delegate the #3246 ratchet counts as off the seam. - test_3254_budgeted_alerts: the frozen clock also covers db.operator_queue's ent#815 commit-lag check, which logged spurious errors against the real clock. Part of #3254 * fix(operator-queue): a failed flood re-read keeps the episode, so its end still clears the alert Fresh review of the #3254 budgeted slice (two findings): - A failed 6-hourly re-read of a persisting flood released the episode. If the condition then cleared before the retry, `_end_flood_episode` found no episode and the pending alert waited out its 14-day lifetime, although the code had seen the condition clear (AC 2). A failed re-read now keeps the episode, whose alert an earlier reading filed, and the re-read is retried once the cooldown has passed. A failed first reading still releases the episode (#3130 I1). New test: test_a_failed_reread_keeps_the_episode_so_its_end_still_clears_the_alert (red with the old release branch put back). - AC 8 for two kinds had no "a person's ending is never overwritten" test: `skill_not_found` (the next run is snoozed and sends no notification) and `alert_budget` (a later refusal re-reads the episode and the acknowledgement stands). Both added. * test(operator-queue): the budgeted-alert suite freezes the clock its running methods read In the full serial unit tier, test_1595_sync_health_signals evicts `database` and every `db.*` module from sys.modules and restores only some of them. Afterwards `database.db` and `ask_service.db` run on an older `db.operator_queue` module than the one this suite's clock fixture imports and patches, so the seam's create, the expiry sweep and the answer's compare-and-set read the real clock: rows filed at the frozen T0 read as long expired (five cases red, `AskConflict: expired`, a second flood row). The fixture now also freezes `utc_now_iso` and `datetime` in the globals of the live operations class (R6: patch what the running method reads). Red before: test_1595 followed by this file, 7 failed; green after: 66 passed; the file alone: 55 passed. * refactor(operator-queue): operator_queue_service becomes a package, content unchanged (#3785) The 2,840-line module moves to services/operator_queue_service/__init__.py byte for byte (100% similarity), the first step of the Invariant #1 split. Every `from services.operator_queue_service import X` and `from services import operator_queue_service` resolves as before. Six path-keyed guards name the file by its path, so their key moves with it (the PR #2487 precedent): _NOT_EMITTERS (test_3246), _ALLOWED_CALLERS (test_1677), _ALLOWED (test_1920), _OQS (test_ent715), FLEET_LEVEL_ALLOWLIST (test_ent467), and the source read in test_ent499. Only the key changes; the rule, the reason text and every assertion are untouched. Part of #3785 * test(operator-queue): pin the package's one-binding rules before the split (#3785) tests/unit/test_3785_operator_queue_package.py pins what S2–S6 must keep while they move code out of __init__, each property derived from the tree so no later slice edits it: modules under 800 lines (__init__ exempt, with a staleness check); the import surface src/backend and tests/ read still resolves; no from-import between package modules; one top-level binding per name; import-time reads defined first and the _MARKER_UNCHANGED default the owner's object; a patch of a re-exported name lands where its readers read; one logger identity; owner-exact qualified reads; no submodule named like a package attribute; one rate_limiter; no method on two classes of the composed service; external imports before the first submodule import, and a failed first import, injected at that line, leaves no stale submodule. The AST scans live in _oqs_package_scan.py (pure stdlib, never imports src). The other shape, a fresh install: each consumer imported first in its own interpreter on an empty database raises a bounded alert (created; only main binds a WebSocket manager, and then exactly one thin operator_queue_sync trigger goes out). Outcomes equal on the base. Part of #3785 * refactor(operator-queue): bind the service's collaborators once, in deps.py (#3785) db, _queue_db, principal_reach, get_breaker_redis, ask_service, AgentClient and the audit sink _audit_sync move to services/operator_queue_service/deps.py, bound once and read as deps.X everywhere in the package. They are no longer attributes of the package, so a stale monkeypatch.setattr(oqs, "db", ...) raises AttributeError instead of patching a copy nothing reads (Invariant #1(a), the PR #2487 rule). rate_limiter stays on the package: ask_service reads oqs.rate_limiter.check. Tests that patched a collaborator on the package now patch oqs.deps.X; no assertion, expected value, fixture or control flow changes. The package guard gains G4 (deps binds exactly the collaborators, no other module imports one from its source under any alias or holds one by identity, the package has none) and refuses any reach of a package function's __globals__. Part of #3785 * refactor(operator-queue): the queue listing engine moves to listing.py (#3785) QueueListError, narrow_to_agent_key, the cursor and walk-snapshot helpers and list_for_principal (trinity-enterprise#815) move whole from __init__ to services/operator_queue_service/listing.py. The two package-owned prefix tuples are read as _oq.X, collaborators as deps.X. The package re-exports exactly the six names read from outside (the router's list_for_principal and QueueListError; narrow_to_agent_key, encode_cursor, decode_cursor and CURSOR_MAX_BYTES, which tests call or compare). test_ent715's row-reader census re-keys list_for_principal to listing.py; no assertion changes. Part of #3785 * refactor(operator-queue): the poller core moves into PollerCoreMixin (#3785) The instance state, start/stop, the Redis leader lease, _poll_loop, _poll_cycle and _broadcast_sync move into PollerCoreMixin in services/operator_queue_service/poller.py. OperatorQueueSyncService is now composed in __init__ from the mixin and keeps its singleton there (the db/schedules shape). Package-owned names (DEFAULT_POLL_INTERVAL, _LEADER_KEY, _RESERVED_ID_PREFIXES, _websocket_manager) are read as _oq.X; the default poll_interval still binds 5 at import. Three path-keyed censuses re-key their poller entries to poller.py (test_1920's lease, test_ent467's operator_queue_sync trigger, test_ent715's _poll_cycle); no assertion changes. Part of #3785 * fix(operator-queue): a new flood, budget or untracking episode files after an acknowledgement (#3254) A person's ending of a `queue_flood`, `alert_budget` or `gitignore_untracked` row snoozed every later reading of the subject for 7 days, because none of the three kinds had a material key, so `_snoozed_by` was vacuously true. A runaway agent's second flood, a second budget-full episode and a second untracking Push of the same paths were all silent (review C1; dolho on operator_queue_service.py:2800 and gitignore_sweep.py:335). Each reading now carries an episode marker that the kind lists in its `material_keys`: - queue_flood: `episode_started_at`, stamped when the in-memory episode starts. Re-reads of one episode share it; an episode that starts after the condition cleared does not. - alert_budget: `filled_by`, a digest of the ids of the pending rows filling the budget. Re-reads of the same full budget share it; once a slot frees and a new row fills it, it differs. - gitignore_untracked: `push_id`, one per call. The emitter runs once per Push, so every untracking Push after an acknowledgement files; repeats still collapse onto a pending row. So the snooze silences re-reads of the acknowledged episode for the snooze window and a new episode files at once, which makes the `_maybe_emit_flood_alert` docstring's #3130 edge-trigger claim true again. The budget episode's read of the filling rows is classified in the ent#780 row-reader census as internal. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * fix(operator-queue): a flood re-read no longer stamps the per-agent cooldown; the oversize end is pinned (#3254) Review follow-ups on the flood alarm: - dolho on operator_queue_service.py:2778 (webmixgamer agreed): the 6-hourly re-read of one reason's episode stamped the per-agent `_flood_alert_cooldown`, so the other reason's first alert could wait up to one cooldown. The cooldown spaces episodes and a re-read is not one, so it is now stamped only before an episode's first reading. A failed re-read's retry spacing already comes from its refresh time. - webmixgamer I3: the 6-hour re-read spacing is one constant, `OPERATOR_QUEUE_FLOOD_REREAD_SECONDS`, read by the gate and by the failed re-read's retry arithmetic, so the two cannot drift. - webmixgamer I1: a `_sync_loop` case serves an oversized file and then a sane one and asserts the row ends as the platform. It goes red when `_sync_agent`'s `_end_flood_episode(agent_name, "oversize_file")` is replaced by a bare episode discard. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * docs(operator-queue): state the fail-open double-leader bound on the flood episode marker (#3254) The episode marker is worker-local. With Redis down the leader lease fails open, so each worker stamps its own episode_started_at and another worker's re-read can file past a person's ending, at most one extra row per extra worker per re-read window. Docstring only; no behaviour change (review L1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): __init__ drops its file-level F401 waiver (#3785) Review I1 (dolho): the file-level `# ruff: noqa: F401` switched off unused-import detection for all of `__init__`, so a dead import left behind by a later slice or feature would go unflagged. At this PR's head `__init__` still reads every name in its import block, so the waiver hid nothing: `ruff check --select F401` gives 0 findings with it removed. It is dropped, and the block's comment now says that a name `__init__` stops reading keeps its line with a per-line waiver naming why (G13, or read as `oqs.X` from outside). PR2, PR3 and PR4 add those per-line waivers where their moves leave a name unread. `deps.py` keeps its file-level waiver: it is a binding module whose imports are its bindings, so there is no import there F401 could rightly flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw * lint(operator-queue): per-line F401 waivers for what __init__ stops reading (#3785) Review I1 on #4036: PR1 dropped `__init__`'s file-level F401 waiver. This slice's moves leave four of its imports unread in `__init__`; each now carries its own `noqa: F401` with the reason, so F401 keeps checking every other line: - `asyncio`, `base64`, `uuid`: kept for G13, because `listing` and `poller` import them at module level. - `from . import listing`: loads the submodule at its G6 point; the names callers read come from the re-export block. `ruff check --select F services/operator_queue_service/` is clean. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWna79vVmnezQdhpaGRKbw --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * refactor(frontend): useVoiceSession goes through the single API client (#2720) (#4185) The last bare axios call in the composable, voice stop, built its own auth header. It now uses the shared client, so it follows the interceptor's token and 401 handling (Invariant #7). The WebSocket URL still takes the store token, which is a different path. Closes #2720 Co-authored-by: trinity-ability <309458136+trinity-ability@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * test(memory): stub last_error in the remaining memory_on fixtures (#4187) The memory_on fixtures in test_ent1022_retrieval_memory and test_ent1027_model_gateway stubbed is_loaded and availability but not last_error, so an embedder error left by an earlier test on the same worker made status() report memory unavailable. The 1028 fixture got the same stub in #4145. Fixes #4137 * docs(readme): link the Trinity 1.0 complete course (#4063) * docs(readme): link the Trinity 1.0 complete course Add the 39-chapter complete course video as the first entry under "Watch more" so new visitors find the end-to-end walkthrough first. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(readme): update Complete Course link to new YouTube id and chapter count Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(readme): update Complete Course YouTube link to re-published video Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Trinity Agent (trinity) <trinity-agent@ability.ai> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> * chore(metrics): code-health dashboard 2026-11-03 @ 93658be60 (#4198) Co-authored-by: Trinity Agent (trinity) <trinity-agent@ability.ai> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> * feat(auth): terms acceptance gate and invite door (trinity-enterprise#1054) (#4195) OSS half of trinity-enterprise#1054: the terms-gate seam (services/terms_gate.py, consulted in resolve_platform_user_unfloored; @terms_route exemptions), EmailService.send_html on one HTML shell, the /terms SPA view + interceptor, and the entitlement-gated InvitesPanel. Refs abilityai/trinity-enterprise#1054 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(workspace): a Direct call — every spoken turn goes to the agent and you hear its own reply (trinity-enterprise#1046) (#4194) * feat(workspace): a Direct call, where every spoken turn goes to the agent and you hear its own reply (trinity-enterprise#1046) A second call mode beside Live, chosen from the Call control's menu (remembered per browser; Live stays the default). No model sits in the conversation: the browser endpoints an utterance, the backend transcribes it, and the browser sends the text through the same POST .../chat/stream a typed message uses, carrying the call's vd_ id. The bridge then speaks the agent's reply sentence by sentence. - Harness-agnostic: every reply is spoken from the persisted row; a runtime whose stream carries messages (Claude Code, Codex) only starts sooner, and the unspoken tail is reconciled so nothing repeats. Gemini CLI agents work, with a line saying replies take about 10 s. - Agent approvals by voice: an ask the turn raises is read aloud, and a whole-utterance yes/no after the prompt has played is posted by the browser on the person's own answer route. The socket never answers an ask and never starts a turn. - Gates: socket owner only (no admin attach); a turn may carry only the caller's own live Direct call on this agent and thread (uniform 404); a spoken run must be the caller's own execution, including one reached through an approval; one call per thread, claimed atomically when the socket opens; a vd_ id never bypasses the Live call guard; 30 utterances/min per person. - Speech providers behind services/speech (Gemini REST STT/TTS, ElevenLabs), chosen in Settings (GET/PUT /api/settings/direct-voice, admin, audit-logged). - The #2694 delta cursor treats a Direct reply as the agent's own session answering. Measured end to end with real speech: first spoken word 3.4-4.4 s after send on Claude Code, 10.7-12.0 s on Gemini CLI; STT 1.1-1.9 s. The speech providers and the bridge were written before their tests. Every gate was then mutation-checked: 16 backend gates go red when removed, run with bytecode caching off. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(workspace): two call buttons, and the Live orb in the Direct call's strip (trinity-enterprise#1046) Operator review of the first build: - The Call control's mode menu is gone. The composer has two buttons, one per call: the Live call (waveform) and the Direct call (handset). Each carries its own reason when it is off; while one call is on, its button ends it and the other says "Another call is on". Nothing is remembered per browser any more (`CALL_MODE_KEY`, `loadCallMode`, `saveCallMode` and `CallModeMenu.vue` are removed; `callButtons` is the pure rule). - The Direct strip's flat pulsing disc is replaced by the Live call's orb in a 48px disc. The overlay's smoke and core move into `chat/voiceOrbField.js` (one renderer, an instance per orb, no module state) and `VoiceOverlay.vue` draws through it unchanged. `chat/VoiceOrb.vue` draws the same field clipped to a circle on the orb's black ground, so it reads in both themes: 80 particles, a DPR-capped bitmap, the first frame drawn on mount, one still frame under reduced motion, and the core tinted with the state — green listening, amber working, blue speaking — because at this size the smoke is a rim and cannot carry it. `directOrbState` maps the Direct statuses onto the orb's vocabulary. - While the person talks, the orb moves with their voice: the composable feeds the mic RMS into `amplitude` whenever nothing is playing (`rmsOf` is exported from the endpointer). PortalConversation's raw_gray count stays at its baseline: the two buttons share one class recipe (#2662 arms) instead of repeating it. Tests: `portalDirectCall.spec.js` covers the button rule, the status→orb map and the mounted orb (draws, animates, stops on unmount, still under reduced motion); `portalDirectCall.mount.spec.js` drives both buttons in the real conversation. Verified in the browser on the local stack, light and dark, Live and Direct. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(workspace): the Direct call's strip shows four call bars, not a canvas orb (trinity-enterprise#1046) The strip's mark is now `portal/CallBars.vue`: four rounded bars in a disc tinted with the status tokens, sitting on the theme's own surface. Green bars follow the person's mic while it listens, amber bars run a slow wave while the turn is worked on, blue bars follow the agent's voice while it speaks, and muted is four flat gray dots. Four elements and no canvas; under prefers-reduced-motion it holds one still frame per state. The canvas orb and the field extracted to share with it are gone, so the Live call's VoiceOverlay.vue is back to dev's version and this PR no longer touches it. Tests mount the bars. Each of three mutations turns a test red: ignoring the sound, ignoring mute, and starting the loop under reduced motion. `portalUndefinedCalls` now lists `cancelAnimationFrame` as a browser global, next to `requestAnimationFrame`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(workspace): a Direct call answers a reply it cannot read aloud, and its strip is one quiet row (trinity-enterprise#1046) A reply that is only code, a table or links had no speakable sentence, so the call said nothing and looked dead. test-echo's fenced echo hit this on every turn. A successful reply with nothing to read aloud now gets "The reply is in the chat." (LINE_REPLY_IN_CHAT); a reply with any spoken sentence does not. The strip is now one fixed-height row, so the thread below it no longer moves when the state changes: 32px bars, one short word (Listening, Got it, Thinking, Speaking, Yes or no?), one detail line (a notice, what was heard, the tool at work, or the slow-runtime wait), a mic icon that shows a slash when muted, and a red hang-up handset. The "Direct call · runtime · speech by …" line and the first-word timing are gone; Esc moves to the hang-up's tooltip. Tests written red first: two backend (the in-chat line, and no line when something was spoken) and four frontend (the detail order, short words, and the mounted row with icon buttons and a danger-token hang-up). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(workspace): a Direct call reads a reply that is only a code block, instead of pointing at the chat (trinity-enterprise#1046) test-echo answers with nothing but a fenced block. The previous fix spoke "The reply is in the chat." for it, which is no answer. When a reply has no prose outside its code blocks, the text inside the blocks is the reply and is now read (fence markers and the language tag dropped). Code beside prose stays unsaid. The in-chat line remains only for a reply with nothing to read at all, such as a table alone. The rule lives in spoken_text.speakable, so the streamed speech and the reconciled tail agree and nothing is said twice. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Revert "fix(workspace): a Direct call reads a reply that is only a code block, instead of pointing at the chat (trinity-enterprise#1046)" This reverts commit c214c9e4d. Operator ruling: a reply that is only a code block is correctly answered with "The reply is in the chat." Code is not read aloud, whether or not prose sits beside it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(voice): a Direct call speaks an execution once (trinity-enterprise#1046) Each speak frame built a fresh SpokenBudget, and only utterances were rate-limited, so re-sending speak for the same run bought its synthesis again, up to the call's 30 minutes and across calls. The bridge now claims an execution before speaking it: Redis SET NX across calls and workers, plus a per-socket set that holds when Redis cannot answer. Also pins the store<->backend contract of a Direct call (mode on start, voice_call_id on a spoken turn, the roster's direct_voice), each of which could be deleted with every test green. merge-train 2026-11-02, mechanical per operator ruling at Gate 1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(voice): stub the Live capability in the one-call-per-thread test (trinity-enterprise#1046) The live case reached realtime_voice_capability before the cross-kind 409 and got a 503 on a host with no realtime provider key (CI). merge-train. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: trinity-ability <309458136+trinity-ability@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * chore(enterprise): bump submodule — invite door and terms acceptance (trinity-enterprise#1054) (#4200) src/backend/enterprise 47cb75a → 452ea04 (abilityai/trinity-enterprise#1074). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(auth): a grant's use leaves an audit row, and grant changes share one verb (abilityai/trinity-enterprise#871) (#4174) An agent key a grant admits now writes one `capability_used` audit row: the agent as actor, its key id, the capability, the target, the method and the endpoint. It is written inside `enforce_agent_capability`, after the owner bound, so it means the grant cleared the call, not that the change landed, and a refused call writes only `capability_refused` (a holder aiming outside its owner's agents included, code `capability_target_not_owned`, same 404). People, `user` and `system` keys write none. One row per capability and target per request; manifest deploys and an honoured skill-set probe record their own use. `skills.manage` grant changes log `capability_grant` / `capability_revoke` through every door; earlier rows keep `skill_manager_*`. Security fixes found by `/cso --diff` and review (docs/security-reports/cso-diff-2026-11-02-871-capability-used.md): - `owner_owns_agent` now refuses the system agent. Owned by the admin, it was reachable by any holder an admin owns, and what lands there runs under a key that bypasses every permission check. - The file routes apply the owner bound, so an edge to another user's agent no longer lets a holder write its instructions or skills (now 404). - The skill-gate map read uses the same bound. - The create row names the slug the agent would get, not the raw body. Also: `request_id` on the agent `delete` row; `test_ent1030_gates.py` no longer reaches the host's Docker. Out of scope: issue item 3 (outcome rows for schedule writes and the timeout PUT); `trinity_prompt` via create-mode deploy stays #4025. Fixes abilityai/trinity-enterprise#871 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(autonomy): declare get_seat_autonomy in the self-gate census; count get_autonomy in the MCP docs (ent#641) Fallout from merging dev: - test_ent719_self_gate_identity drives every assert_own_agent route with a well-formed request. The new GET /seat-autonomy needs an execution_id query parameter, like its seat-decision siblings. - tool-count-docs (ent#991 T5) reads the registered total from the user docs. dev's search_memory plus this PR's get_autonomy make 177 tools (172 operator), and decisions.ts now has 3 tools. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(gemini): dev's wall-clock and usage-statistics tests run as the owner's turn (ent#926) test_ent1003_gemini_wall_clock and test_ent986_gemini_usage_statistics came in with the dev merge and drive the Gemini runtime with an execution id. This branch's tier check asks the platform whose turn it is, and with no platform to ask it fails closed (503). These tests are about the CLI, not the turn, so they take the same owner-turn stub the branch's other Gemini tests use (turn_scope.fetch_turn). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(skills): find a skill and see what Save would do, on bounded lists (abilityai/trinity-enterprise#660) (#4178) - Assign skills dialog: text, source and category filters narrow the rows and both bulk buttons, never the draft. Each row and a footer count say what Save would do: "to add", "to remove", or "kept by set" for a skill an assigned set still holds. The list keeps one height while the filter narrows, in a panel capped to the window. - Library and the agent's Skills tab: the lists scroll in a BoundedRegion that fills the window, so the page no longer grows with the library. The Library gets the same filters and a stated total. On the tab, Own and Shared share one box, a total sits in the header, and Shared's heading docks to the box from 640 px up. - BoundedRegion is now `relative`: unpositioned, the cards' sr-only labels escaped the box and Chrome counted them in the page height. - Backend: `category` on SkillInfo, from the skill's frontmatter. No migration, no new route, no base-image or MCP change. - e2e/skills-bounded-lists.spec.js (Chromium, @smoke, hermetic) pins the geometry that jsdom and Firefox cannot see. ent#660 was re-scoped because its text predates ent#754. Edition: OSS-core, ungated (confirmed on ent#660). Fixes abilityai/trinity-enterprise#660 Fixes #3448 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(access): declare get_seat_autonomy's tier in the agent route census (#4206) #2984 added GET /api/agents/{agent_name}/seat-autonomy and #3778 added the census that requires every agent-naming route to declare a tier. They merged one after the other without seeing each other, so dev fails test_ent926_agent_route_census::test_every_agent_route_is_declared. Declared accessor, with a reason, matching its sibling decision routes' gates (assert_own_agent, then assert_agent_access). Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * fix(slack): fall back to Public URL for OAuth callback redirect (#4167) Motivation: with FRONTEND_URL empty (the .env.example default), the Slack OAuth callback redirect fell straight to http://localhost, so after Install to Workspace the admin landed on a dead page even though the install succeeded. The redirect URI for the same flow is already built from the Public URL setting. Approach: get_oauth_callback_redirect now uses FRONTEND_URL if set (unchanged precedence), else the Public URL setting, and only then the localhost fallback with the existing error log. This covers the platform and per-agent success and error redirects, since they share the function. Validation: ran tests/unit/test_slack_*.py plus the new tests/unit/test_3563_slack_oauth_redirect_base.py: 227 passed. With the fix reverted, te…
Part of #3785. This is PR 1 of 4: the module becomes a package with a guard that pins its ownership rules, and the service's collaborators are then bound once, in
deps.py. PR4, the PR that carries the closing keyword, lands last.#3785 ships as four PRs instead of six separate units.
Stacking and how it lands
db8a58e89, which already contains dev0f689db80. fix(operator-queue): the #1677 budget family reports through the platform-alert seam (#3254, budgeted slice) #4021 is the last bug: the remaining platform alert emitters still file one row per reading — move them onto the shared alert path (#3246 part 2) #3254 change to this module.devand rebased onto it with--onto. The first commit is a content-identical rename, which replays cleanly over any later change to the file.EMITTERS_NOT_YET_ON_SEAMintest_3246,_ALLOWED_CALLERSintest_1677). Whichever lands later is re-merged the same day and says so here.Commits
a83a49dcf89f1edf50d2c724b15Labels used below
__init__owns (a) the config block, (b) module state that is rebound or mutated, kept with its only mutators, (c) names read on both sides of the package boundary that tests patch, and (d) therate_limiterbinding. O2: the collaborators are bound once, indeps.py. O3: everything else has one owner module, and siblings read each other through that module. O4: every module logs asservices.operator_queue_service.deps; G5 one top-level binding per name; G6 import-time reads defined first; G7 a patch lands where its readers read; G8 one logger; G9 owner-exact qualified reads, nothing unresolved; G10–G12 names that cannot collide (a submodule named like an attribute,rate_limiter, a method on two classes); G13 import order, and a failed first import leaves nothing stale.oqs.Xtooqs.deps.X. E3: a private helper's patch moved to its owner module. No assertion, expected value, fixture data or control flow changes in any class.What changes
S1: the package conversion and its guard (
a83a49dcf,89f1edf50)The move.
src/backend/services/operator_queue_service.pybecomessrc/backend/services/operator_queue_service/__init__.py, byte for byte (100% similarity; blobae339759on both sides). Everyfrom services.operator_queue_service import X,from services import operator_queue_serviceandimport services.operator_queue_service as oqsworks as before. The image copiesservices/whole (docker/backend/Dockerfile:163), so packaging is unchanged.Six path re-keys. These guards key the file by its path, so the key moves with the file. Only the key changes; the rule, the reason text and every assertion are untouched (the PR refactor: split the four remaining oversized backend modules (#1028) #2487 precedent):
tests/unit/test_3246_platform_alerts_registry.py_NOT_EMITTERS(2 entries)tests/unit/test_1677_operator_alert_emitters.py_ALLOWED_CALLERStests/unit/test_1920_no_hand_rolled_single_flight.py_ALLOWEDtests/unit/test_ent715_queue_person_fields.py_OQStests/unit/test_ent467_ws_agent_scope.pyFLEET_LEVEL_ALLOWLISTtests/unit/test_ent499_problem_report.pyThe package guard,
tests/unit/test_3785_operator_queue_package.py, 23 tests after S1. Its AST scans live intests/unit/_oqs_package_scan.py, which is pure stdlib and reads source without importing it (the_route_census.pyshape). Onetests/registry.jsonrow is added. The ownership rules it enforces (O1–O4) are stated at the top of the guard. It pins what S2–S6 must keep while they move code out of__init__. Every property is derived from the tree, so no later PR edits it except PR4's one scheduled edit (the size exemption it drops). S2 adds two properties (G4 and the__globals__clause, which needdeps.pyto exist):__init__exempt, with a staleness check);src/backendandtests/read through the package is still found there (the scan is pinned against the known readers so it cannot go blind);manager = _oq._websocket_manageris refused);_MARKER_UNCHANGEDdefault is the owner's own object;raising=Falseorcreate=Truepatch would (added after the S5 review);rate_limiterbinding;depsis the first submodule__init__imports and holds no package reference;__init__makes every external import before its first submodule import, and a failed first import (injected at that last external statement and proven to fire there) leaves no stale submodule.In S1 most properties hold trivially, because the package has one module. Each one was made to bite in a scratch copy (Mutation, below).
Other shape, fresh install: the guard's last test imports each consumer first, in its own fresh interpreter on an empty database, and raises a bounded alert (created; only
mainbinds a WebSocket manager, and then exactly one thinoperator_queue_synctrigger is sent). It runs on its own temp database withDATABASE_URLdropped, so an exported real database is never written to.S2: the collaborators are bound once, in
deps.py(d2c724b15)deps.pyholds the collaborators. The newsrc/backend/services/operator_queue_service/deps.py(41 lines) bindsdb,_queue_db,principal_reach,get_breaker_redis,ask_serviceandAgentClient, and holds the audit-sink adapter_audit_sync, moved over unchanged.__init__no longer binds any of the seven.__init__reads them asdeps.X: 35 read sites, a one-token change each.deps._audit_sync(call are re-indented by five columns so they still line up.rate_limiterstays on the package (O1 d), because ask_service readsoqs.rate_limiter.checkin production.__init__keeps its external import block first and whole, thenfrom . import deps, so an externalImportErrorfires before any submodule has loaded. The block stays whole even where__init__itself no longer reads a name: G13 lets a submodule import at module level only what__init__already imported, andoqs.time,oqs.to_utc_isoandoqs.rate_limiterare read through the package from outside.deps.pygets a file-level# ruff: noqa: F401, because its imports are its bindings.__init__gets none: at this head it reads every import, and each later slice adds a per-line waiver, with its reason, for the names its moves leave unread (review I1).dbattribute, somonkeypatch.setattr(oqs, "db", …)raisesAttributeError. Before this change it would patch a copy that nobody reads (Invariant Fix: Add missing Docker labels to system agent container #1(a), the PR refactor: split the four remaining oversized backend modules (#1028) #2487 rule). There is one binding per collaborator, so one patch onoqs.deps.Xreaches every reader in every module the later PRs create.oqs.deps.X(class E2; table below). No assertion, expected value, fixture data or control flow changes.test_3785_operator_queue_package.py, with the AST helpers in_oqs_package_scan.pyand thetests/registry.jsonrow description updated. The guard goes from 23 tests to 29. This commit also restores the scan helperdefined_names, which the guard commit had dropped and G4 uses.depsbinds exactly the seven collaborators, plus its O4 logger.deps.py's own imports, and the check is pinned so it cannot go blind. A module the source is reached through counts too (import databasereachesdatabase.db), and so does a star import.from dependencies import db as _db._audit_sync, which has no import source.__globals__clause: no test reaches a package function's__globals__. A function's__globals__belongs to the module that defines it, so after a move asetitemon it adds a key that no reader reads.oqs.f,route.operator_queue_service.f), a from-import of a package name, or a simple assignment of either (f = oqs.list_for_principal).No change to production behaviour. No docs change: the stale path pointers in
docs/are re-pointed once, by PR4, when every module's home is final. Until then, owner lookup (scripts/docs/architecture_map.py) matchessrc/backend/services/**.Journey Impact: none: an internal module becomes a package with identical content, and module-internal name bindings move into a sibling module; no route, payload, UI, API or MCP surface changes, and no catalogued journey reads the file's path.
Where these numbers come from. Every figure below was measured on a local stack that nobody else can fetch. S1 and S2 were built as local commits (
19d16d8d7for S1,1e4910feefor S2 on it;b6d097976is an earlier S1 build) on4612e7878, #4021's tip before it merged dev0f689db80. The three commits here are those trees replayed ontodb8a58e89, #4021's current tip: each tree differs from its local build only by that dev merge (104 files; none is in the package or its guard, and no test it adds or changes names the module; it shares fourdocs/memory/files andtests/registry.jsonwith this issue's edits). The module's blob isae339759on both bases. Re-run on these commits for this body: AST equivalence on each (173 compared, 0 differ, with 0, 0 and 2 submodule header statements dropped), the module sizes and radon CC, all matching the figures below. Everything else is re-derived on the real base when the PR is cut ontodev, and this body is updated. To redo at cut: every SHA and figure below re-derived on the real base. The two result lines at the end of Validation are filled when their runs finish.Validation:
Python 3.12,
-p no:randomly,TRINITY_DB_PATHandDATABASE_URLunset. The two test selections are defined, with their commands, in the first collapsed block below.S1 (against the local base
4612e7878):-m "not slow"): 8,671 passed, 3 failed, 3 skipped, 7 xfailed on base, and the same on head, with an identical failure set. The 3test_ent751_gate_callers.py::TestPaidA2Afailures are pre-existing on the base.test_2338_journey_catalog(which reads the registry) green under pytest-randomly seeds 12345, 1 and 2 (284 passed each, measured with the 22-test guard).tests/lint_sys_modules.pyOK (133 against a baseline of 134);ruff check --select F,E9clean on the two new files. Both re-run on the final S1 tree. No temp directory left behind after a run.radon cc src/backend/services/operator_queue_service -s -n C --json, summed per file; the split starts lowering it in S3).a83a49dcfand89f1edf50. The script and its command are in the second collapsed block below; the same script serves every PR of refactor: split operator_queue_service.py — hotspot #2, highest complexity in the backend, no covering issue #3785.S2 (against S1's local build):
Core pinning set (60 files): 2,240 passed, 7 xfailed. The base gives the same.
Extended set (302 files,
-m "not slow"): 8,671 passed, 3 failed, 3 skipped, 7 xfailed. The base gives the same, with the same failing set: the 3 pre-existingtest_ent751_gate_callers.py::TestPaidA2Afailures.Which trees the pinning sets ran on: the head was S2 before its final review round, against an earlier S1 build (
b6d097976) that differs from19d16d8d7only in the guard. The final round changed only comment lines in__init__anddeps.py, guard tests and the registry row description, and neither pinning set runs the guard. The two sets were not re-run after it; the guard, AST equivalence and lint were.Guard: 29 passed (S1's 23, plus 5 for G4 and 1 for the
__globals__clause), re-run on the final tree.Order: the guard plus the 16 E2-edited files give 965 passed, 7 xfailed under each of pytest-randomly seeds 12345, 1 and 2 (measured with the 28-test guard, before S1 gained its re-export check).
Other shape, empty data (script in the last collapsed block): a fresh
-E -Pinterpreter on a fresh unit DB, with no settings row and no queue rows.DATABASE_URL, whichdb/connection.pyanddb/engine.pyprefer overTRINITY_DB_PATH, and asserts that both point at its temp file. It was run with a decoyDATABASE_URLexported.oqs.depson head, the module itself on base).db,principal_reach,get_breaker_redisandask_service._queue_db,AgentClientand_audit_syncare wrapped but not reached, so this case proves nothing about their readers; G4 and the pinning sets cover them.Base and head give identical outcomes:
aging_hours()returns 24;list_for_principalreturns an empty page (count 0, total 0, no cursor) both for an admin JWT and for an agent key narrowed throughprincipal_reach;_poll_cyclewith zero agents expires nothing, sweeps nothing and raises nothing. It stays leader,changedis False, and no warnings are logged;Lint:
tests/lint_sys_modules.pyis OK (133 violations against a baseline of 134), identical to the base;ruff check --select F,E9is clean on the package and the guard. Both re-run on the final tree.CC (radon 6.0.1,
cc -s -n C, summed per file):__init__.py298 → 298;deps.py0 (its one block,_audit_sync, scores 2, rank A).Size:
__init__.py2,840 → 2,830 lines;deps.py41.AST equivalence: 173 compared, 0 differ (2 submodule header statements dropped), re-run on
d2c724b15.Runs still in progress (filled in when they finish):
a91b0b474, which contains this PR's three commits: Full unit tier, once, on PR4's heada91b0b474(the final tree; Python 3.12,-m "not slow", pytest-randomly seed 12345, 2026-10-27 19:44–20:30 UTC): 29,697 passed, 67 failed, 96 skipped, 9 xfailed, 1 collection error. Every one of the 67 failures and the collection error (11 files:test_ent679_a2a_payment_gate,test_3940_cron_dst_fold,test_ent679_nevermined_service_bounds,test_ent679_payments_pin_parity,test_736_a2a_outbound_edges,test_3215_public_base_url,test_ent751_gate_callers,test_ent399_ipv6_origin,test_3390_module_split_guard,test_1898_sys_modules_isolation,test_3215_plan_scheme) is identical on pristine fix(operator-queue): the #1677 budget family reports through the platform-alert seam (#3254, budgeted slice) #4021 (db8a58e89) and on pristine dev (f00cca137) when the same files are run the same way, so none is caused by this change; they come from the local environment (for example, payments-py 1.2.1 lacksx402.resolve_scheme).--fullgate on this PR's headd2c724b15: passed (2026-10-27 20:31:57–20:32:47 UTC), baseAndriiPasternak31/issue-3254-s7(fix(operator-queue): the #1677 budget family reports through the platform-alert seam (#3254, budgeted slice) #4021). Its own-tests run (every changed test file undertests/unitagainst fix(operator-queue): the #1677 budget family reports through the platform-alert seam (#3254, budgeted slice) #4021, Python 3.14,-p no:randomly) gave 1,057 passed, 7 xfailed. Gitlinks untouched, no Alembic change, keyword and Journey Impact accepted.Mutation:
S1
Each row was applied to a scratch copy, the named test went red, and the copy was restored. The final guard gives 28 of 28 as intended: 27 rows red, and the one false-red check stayed green on G7 (its scaffold adds a re-export nothing reads, so the re-export check reds there, as it should). After restore, the guard plus
test_1920gave 29 passed (23 + 6). The harness is local and not attached; each row names its edit, so it can be reproduced by hand. Rows 16–19 are the fresh reviewer's escape cases and rows 20–25 Codex's, each re-run after the change it prompted; rows 26–28 came from the S3, S4 and S5 reviews.__init__drops a consumer-read namegetLogger(__name__ + ".x")_MARKER_UNCHANGED_oqread above its definition_oq.Xthat__init__only imports__init__reads its own re-export baredb.pysubmodulerate_limiter__init__never importedfrom . import _websocket_manager(a package attribute, not a submodule)services.*moduledepsmanager = _oq._websocket_managerat module levelpatchimported asmock_patchpatch.object(target=…, attribute=…)keywordsfrom . import depsin one function hiding another'sNameErrorutc_now_isowhile a submodule binds its own (S4 review)raising=Falsepatch of a name the package does not bind (S5 review)S2
Each row ran on a scratch copy of the tree. Every row behaved as expected: 19 of 19, with the two FALSE-RED rows staying green as they must. Every file was restored from an in-memory snapshot, and after restore the guard gave 28 passed (its size before S1 gained its re-export check; 29 now, green) and AST equivalence 0 differ. The harness is local and not attached; each row names its edit. Rows tagged F1 and F2 are Codex's findings (Review, below).
from database import dbto__init__(the move reverted)oqs.deps.dbpatch tooqs.db(test_1525:56)AttributeError: 3 tests red intest_1525test_ent815:100to thelist_for_principal.__globals__setitem__globals__clause, plus 16test_ent815walk testsdepsbinds one more name (rate_limiter)from database import dbinaging_hours_audit_syncdropped fromdepsfrom database import db as alternate_dbin__init__from services import ask_service as _askin_poll_cycleimport services.ask_service as _ask_modin_poll_cyclefrom dependencies import db as _db_toof = oqs.list_for_principal, thensetitem(f.__globals__, …)__globals__clausefn = route.operator_queue_service.list_for_principal, thenfn.__globals____globals__clausefrom … import list_for_principal as f, read inside a test__globals__clausef, plusdef inspect_unrelated(f): return f.__globals__fshadowed by the parameterf_audit_syncdbread throughdeps.ask_service.db(runs fine; wrong owner)aging_hoursreads a function-localfrom database import dbdb.get_setting_valueis no longer recorded)aging_hoursreads a re-added packagedbTest edits
S1's six E1 re-keys are in the first table under What changes. S2's edits are every one E2, a collaborator reference moved from
oqs.Xtooqs.deps.X:tests/unit/test_1525_operator_queue_quarantine.pydb,AgentClienttests/unit/test_1631_operator_queue_agent_scoped_ids.pydb,AgentClienttests/unit/test_1632_operator_queue_caps.pydb×6,AgentClient×3,get_breaker_redis×3tests/unit/test_1677_operator_alert_budget.pydb×2tests/unit/test_2372_platform_alert_ack.pydb,AgentClienttests/unit/test_2915_operator_queue_sync_honesty.pydb×2,AgentClient,ask_service,_audit_sync×2tests/unit/test_3130_flood_guard.pydb,AgentClientpatches;:435calls the patched factory (oqs.AgentClient("a")→oqs.deps.AgentClient("a"))tests/unit/test_3243_atomic_asks.pydb,AgentClienttests/unit/test_3254_budgeted_alerts.pydb,AgentClient(#3254 S7's suite)tests/unit/test_3274_gate_wiring.pydb,ask_servicetests/unit/test_3313_operator_queue_sync_error_logged.pysetattr(oqs.ask_service, "expire", …)→oqs.deps.ask_service;dbtests/unit/test_ec_operator_queue_edges.pysetattr(oqs.db, "get_setting_value", …)at:491and:498tests/unit/test_ent611_ask_endings.pydb×2,ask_service,AgentClient,_audit_synctests/unit/test_ent611_native_ask.pydb,AgentClient,_audit_synctests/unit/test_ent715_queue_person_fields.pydb,AgentClient,_audit_synctests/unit/test_ent815_queue_walk.pymonkeypatch.setitem(route.operator_queue_service.list_for_principal.__globals__, "get_breaker_redis", …)→monkeypatch.setattr(route.operator_queue_service.deps, "get_breaker_redis", …)at:100and:750. The fixture still patches "the service module the route actually calls".That is 52 sites in 16 files. Guard files edited by S2, for G4 and the
__globals__clause only:tests/unit/test_3785_operator_queue_package.py,tests/unit/_oqs_package_scan.py, and thetests/registry.jsonrow description.Review
S1
One fresh reviewer (Opus 5.5, high effort), briefed with the goal and the bar only, returned REVISE (1 blocker, 2 should-address, 4 nits). Every finding is addressed:
from . import NAME, sofrom . import _websocket_manager(a frozen copy of the rebound global) passed every checkfrom . importof a non-submodule; mutation red__init__:29), not at its target, so a late external import after a submodule import stayed green; the import order (external block, thendeps, then the rest) was unguarded__init__frame must be the target line; new static test: no external import below the first submodule import. Both mutations redfrom services import docker_serviceas covered byservices_MARKER_UNCHANGED_MARKER_UNCHANGED = object()existsmod = oqs,patch.multiple, an aliasedpatch)patchwas handled later (Codex finding 3, below)_oqs_package_scan.py; the test file holds only the policy tables and assertionsCodex (gpt-6.1-sol, high effort, read-only), on the guard after those changes, returned REVISE (5 × P2). Every finding is addressed:
deps' imports in any order; a package importing a submodule beforedepspassed, and a failingdepsimport left it staledepsis the first submodule import and binds no_oq; mutation redmanager = _oq._websocket_managerat module level (a detached copy) passed G3/G5/G6/G9patchimported under another name, andpatch.object(target=, attribute=)keywords, produced no patch siteunittest.mock.patchand keyword arguments are followed; both mutations redfor name in (...)produced a false redNameError__init__passes it; mutation redFound later, while the sibling units were built and reviewed, and handled here because the guard is S1's. Each is a guard property the sibling's review asked for:
rate_limiteras__init__-owned (O1 d), so a correct_oq.rate_limiterread showed as 1 differoqs.utc_now_iso(or any name a submodule binds for itself) would miss that submodule's readers, and the guard stayed greenraising=False(orcreate=True) of a name the package does not bind passed G7 and reached nothingDATABASE_URL, so a developer with a real database exported would have the fresh-install case write to itDATABASE_URLis dropped, and the case asserts it ran on its own temp database (checked with a decoyDATABASE_URLandREDIS_URLexported)S2
Codex (gpt-6.1-sol, high effort, read-only) returned REVISE with two findings. Both are addressed in S2's guard additions, and each has mutation rows above:
from database import db as alternate_dbin__init__, every ownership check stayed green while a patch onoqs.deps.dbmissed that reader__globals__scan was file-wide and ignored shadowing: a sibling's import or a parameter namedfgave a false red, andf = oqs.list_for_principalthensetitem(f.__globals__, …)gave no findingA fresh reviewer (Opus 5.5, high effort), briefed with the goal and the bar only, returned APPROVE WITH CHANGES. Every finding is addressed:
from database import db as _db(top level) or a function-localfrom services import ask_service as _askpassed while adepspatch missed that readerTRINITY_DB_PATHbut notDATABASE_URL, whichdb/connection.pyprefers, so a reviewer with a real database exported would have_poll_cyclesweep its open rowsDATABASE_URLand asserts both lookups point at its temp file; run with a decoyDATABASE_URLexported, identical on base and head__globals__check missed a function held in a variable (fn = route.operator_queue_service.list_for_principal)vars(oqs)assertionfrom database import dbinaging_hours) makes the case's own output differ from baseGuard properties added after the S3, S4 and S5 reviews hold on S2's tree too (29 passed): every re-export has an outside reader, and G7 refuses a package patch of a name a submodule binds for itself or of a name the package does not bind. The last one ends the
raising=Falsegap S2's body used to list as unverified.Unverified:
--fullgate once per head (both in Validation).mod = oqs,patch.multiple). No test uses these today.from dependencies import dbinside a function; the source scan does not know the path, and the identity check runs only at module level), and a dynamicimportlib.import_module.__globals__clause's blind spots: a function reached through an instance (svc._sync_agent.__globals__), throughgetattr(oqs, "f"), or through a container or a call's return value.verify-localon the unit trees: not run. S1 is a content-identical rename, and CI's image smoke boots it to/health. S2 changes only how collaborators are looked up, not the class or the loop; G4 and G9 check that statically, and the poller suites call_poll_cycle/_sync_agentdirectly, so a bad lookup raises in the unit tier instead of being swallowed by_poll_loop. The--fullgate above is the first end-to-end run on this PR's head.982735ffound no import of this module.The two pinning sets: the selection rule, and the commands that run them
From the repo root, on Python 3.12, with
TRINITY_DB_PATHandDATABASE_URLunset:Both rules were checked against the frozen file lists the figures were measured on: on the local base and on every unit's tree,
coregives 59 files and, withtest_ent879_aauth_resource_route.pyadded, exactly the frozen 60;{ core; consumers; }gives exactly the frozen 302.Why 60 and 302, not the 59 and 315 counted earlier on
f754dfb02:test_3254_budgeted_alerts.py, which names the module. One bug: the remaining platform alert emitters still file one row per reading — move them onto the shared alert path (#3246 part 2) #3254 commit droppedtest_ent879_aauth_resource_route.py'ssys.modulesstub of the module, so that file no longer names it. The frozen list kept it, which makes 60. It also enters the extended set through itsservices.idempotency_serviceimport, so the extended count is the same either way.f754dfb02and 302 here; the one extra file istest_3254_budgeted_alerts.py. The earlier 315 cannot be reproduced from this rule or from looser variants of it (they give 301 to 333, never 315), so it came from a broader regex that was not recorded. Every figure in this body is on the 302.services.idempotency_serviceandservices.git_service.gitignore_sweepstopped importing the module in bug: the remaining platform alert emitters still file one row per reading — move them onto the shared alert path (#3246 part 2) #3254. They stay in the consumer list, so the selection is the same before and after bug: the remaining platform alert emitters still file one row per reading — move them onto the shared alert path (#3246 part 2) #3254.AST equivalence: the script, and the command that runs it
Save the script below as
ast_equiv.py. From the repo root of a checkout with history (CI'sfetch-depth: 1cannot run it, which is why it is here and not in CI), on Python 3.12 or later:It prints
N compared, 0 differ (M submodule header statements dropped)and exits non-zero on any difference. This is the one current version of the script, used for every PR of #3785.Other shape, empty data: the script, and the command that runs it
Save the script below as
issue-3785-s2-empty-data.py, then run it once against a checkout of the base and once against the head, and compare the twooutobjects:It prints one JSON line,
{"through": "deps"|"package", "out": {...}}. On head it also asserts that no collaborator is bound on the package. It needs Python 3.12 with the backend's dependencies.