Skip to content

feat!: a token names its organization, and a scroll is released by the token of its search - #567

Merged
bim-ba merged 1 commit into
mainfrom
feat/scroll-clear-next
Oct 10, 2026
Merged

bim-ba merged 1 commit into
mainfrom
feat/scroll-clear-next

Conversation

@bim-ba

@bim-ba bim-ba commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

ycli tracker issues scroll-clear --next TOKEN releases the scroll of a search before it expires, and a next token is now bound to the organization it was returned in. Decisions: #538 (5-B), the review of #534 (findings 5 and 6).

The token, second format

Field New What it is Used for
of, way, query, body, skip, seen no as before the request and the fingerprint
org yes the one organization header of the listing's request, as Name: id with the id escaped (the kind is a part of it: 7 of Yandex 360 and 7 of Yandex Cloud are two); empty where the service names none a check and its message
at yes the path the listing was asked at, escaped as it goes on the wire a message only
kept yes what the way of paging kept from the replies: empty, except for a scroll (scrollId, scrollToken) scroll-clear

What a call that goes on is told now:

Given Answer
a token of another organization this token is of another organization (X-Org-Id: 7) than this call (X-Org-Id: o): run it under the account that returned it; nothing is sent
a token at an address that differs in one part it differs in the address: DE-2 (the token holds DE-1)
a token at an address that differs in more than one part, or in shape this token is of another listing than GET /v3/queues/: give it to the call that returned it, …
a token of the same address taken another way of the same listing taken another way (ScrollPagination, where this call takes it by PageNumberPagination)
a token of the first format this token was given by an earlier version of ycli: start the listing again without it

The address is never used to build a request and never made a URL of. It is compared as text and believed only when the token's fingerprint is its own. A token whose address was written over is refused as no token, at its own listing and at the one it names.

A token is made of the address and the query as they go on the wire, escaped, so no argument (ДЕ-1, DE 1, DE[1]) and no link of a service can break the making of it; what is read back is held to the same characters. way must be a way of paging that exists, and org a header name and an escaped id.

Text taken from a token is repeated in a refusal only when it is short and plain ([A-Za-z0-9._-], 64 at most): a refusal is read on a terminal and by a model through a tool error. Anything else is told as (the token holds another), and the refusal names what the call gave.

The core does not know which parts of an address an argument filled. The rule it can hold: one part that differs is taken for an argument given again and named; more than one is another operation. So boards list -> queues list --next is told "another listing", and comments list DE-1 -> comments list DE-2 --next names DE-2. One case reads oddly and is true: the same issue's worklog given the token of its comments is told worklog (the token holds comments).

A token of the first format is not upgraded: it names no organization, so there is nothing to check it against.

scroll-clear, one argument on three surfaces

Surface Before After
SDK tracker.issues.scroll_clear(body: ScrollClear) tracker.issues.scroll_clear(next: str)
CLI scroll-clear --pair id=token scroll-clear --next TOKEN
MCP tracker_issues_scroll_clear(body) tracker_issues_scroll_clear(next)

Before this, nothing gave the pair: the scroll's token comes in the X-Scroll-Token header, which ycli did not read. A token of anything but a scroll is refused: this token is not of a scroll: only a search by a scroll has something to release.

The next of a scroll now holds the scroll's own token. It is of no use without the caller's credentials and dies with the scroll (its TTL, or the clear); the how-to (en, ru) and the docstring say so. No refusal text, no line of the debug log and no repr of the token's state prints kept: a test holds it. One place does show it and is left as it is: scroll-clear --dry-run prints the request it would send, and the body of that request is the pair.

Measured live (2026-10-10, values not printed)

Fact Result
A search by a scroll, page one X-Scroll-Id (24 chars) and X-Scroll-Token (39 chars)
The same scroll, page two the same id and the same token
POST /system/search/scroll/_clear with {id: token} 204
The next page of the released scroll 403, which ycli tells as a listing that cannot go on (exit 9)

Tests

What Where
organization: X-Org-Id, X-Cloud-Org-Id, and a service that names none (goes on) test_continuation.py
the rewritten address test_the_address_in_a_token_is_for_a_message_and_never_asked_at
a first-format token, a recorded string made by the code of #534, through the SDK, the CLI and the MCP tool test_a_token_of_the_first_format_is_refused_by_name_on_every_surface
19 forged or broken tokens (injection through org, way and at: a line after it, an escape sequence, a sentence; an address that is no path, with a host, a control character, a query; a query with a fragment; v as 2.0, true, 1.0; another operation of as many parts; a forged kept), each through the SDK, the CLI and the MCP tool: ycli's own refusal, nothing sent, no traceback tests/unit/cli/test_forged_tokens.py
a token made from a path with Cyrillic, a space, brackets, #, ?, 300 characters, and from a service link with [ ] { } | \\ ^ and a backtick: the listing goes on to its end test_a_listing_makes_its_own_token_whatever_its_address_holds, test_a_listing_that_follows_a_link_makes_its_token_whatever_the_link_holds
an organization id that needs escaping makes its token, and is not quoted in a refusal test_an_organization_of_any_id_makes_its_token_and_only_a_plain_one_is_repeated
the same id under the other kind of organization header test_the_same_id_in_another_kind_of_organization_is_another_organization
kept of a scroll, carried from piece to piece, printed nowhere test_a_scroll_keeps_what_releases_it_and_says_it_nowhere
scroll-clear on three surfaces sends {id: token}; a token of no scroll is refused test_listing_handles.py, the contract case

The live scenario tracker/issue-options gains the round trip: a scroll in pieces, the clear, the next page refused. For the last step a scenario step can now say the exit code it must end with (exits: 9); such a step reads nothing of the output, so expect or save beside it is refused when the scenario is loaded.

Leftovers of the #534 review, closed here

  • A token of the same address taken another way is told so, where it was told an address.
  • The permanent check of listings says in its docstring what it cannot see (a constant page size put back into forms notifications list).

Breaking changes

  • tracker.issues.scroll_clear, ycli tracker issues scroll-clear and tracker_issues_scroll_clear take the token in place of the pair.
  • A next token returned by an earlier version no longer goes on: start the listing again.

After the review (eight findings, all fixed)

Finding Fix
a token whose address is no path raised InvalidURL at another listing; so did a query with a fragment (already on main) both are held to their characters when the token is read; the address goes to no URL constructor
scroll-clear with a kept that has no scrollId raised KeyError refused as not of a scroll
scroll-clear took a token of another way of paging with a forged kept the way is checked
another operation of as many parts was told as an argument, with an empty part the one-part rule above
the organization id was recorded without its kind Name: id
v: 2.0 passed and v: true was told "an earlier version" the version is an int, exactly
a step with exits passed over expect and save refused at load
two comments on the recorded string disagreed one statement

After the second round of the review (four findings, all fixed)

Finding Fix
a path argument outside the pattern (ДЕ-1, DE 1, DE[1]) broke the making of the token at truncation the token holds the escaped path, and the fingerprint is of it
the same for a raw link of a service with [ ] { } | \\ ^ the query is held to visible ASCII without #, which is what goes on the wire
org and way were echoed as written way is one of the ways that exist; org is a header name and an escaped id
a forged address with a forged fingerprint had its text named text of a token is quoted only when short and plain

Seen by the reviewer, not traced, not a matter of the token: a semicolon in the query of a Link header cut a walk short without a refusal.

Verified

On this head, over main b79c29b2 (0.136.0): ruff, ty, lint-imports (6 kept), ast-grep, pydoclint, gitleaks, rulesync and the generated reference without drift; the full suite: 7007 passed, 5 skipped, coverage 100 %.

Live, on this exact commit: YCLI_E2E=1 pytest e2e -m live -k "tracker and issue": 3 passed, the scroll round trip included; output kept in a file. An earlier run on the previous head failed in two of three scenarios: the one failure read was a connect timeout to the Tracker API (exit 6), the cause of the other was not read before re-running and its output was not kept; the re-run passed, and the sandbox held no object of the failed run (janitor, --dry-run).

NOT RUN: the full live run over every service (CI runs it); a live check of the organization refusal with a second real organization (there is one account; unit tests with both header kinds hold it).

🤖 Generated with Claude Code

…e token of its search

`ycli tracker issues scroll-clear --next TOKEN` releases the scroll a search
goes on by, before it expires (#538). The command took `--pair id=token`, and
nothing gave the pair: the scroll's own token came in a header ycli did not
read. The `next` of a search by a scroll now holds it, so the SDK, the CLI and
the MCP tool all take the one token.

The token has a second format, which holds three things more:

- the organization the listing was asked in, with the header that names it
  (organization 7 of Yandex 360 and 7 of Yandex Cloud are two). A token given
  under another account is refused and names both; it used to go on with the
  other organization's listing.
- the address the listing was asked at, for a message only: a token of one
  issue's comments given to another issue is told what differs (`DE-2 (the
  token holds DE-1)`). It never builds a request and is never made a URL of:
  it is held to the characters of a path where the token is read, and a token
  whose address was written over is no token.
- what the way of paging kept from the replies: nothing, except for a scroll,
  where it is the scroll's id and token. No refusal, no line of the log and no
  repr prints it. It is of no use without the caller's credentials and dies
  with the scroll.

A token of the same address taken another way (a search by pages given the
token of one by a scroll) is told so, where it was told an address.

A token is made of the address and the query as they go on the wire, escaped,
so no argument and no link of a service can break the making of it. Text taken
from a token is repeated in a refusal only when it is short and plain: a
refusal is read on a terminal and by a model.

A token that is not what a listing gave (a field gone wrong or rewritten) is
refused in ycli's own words on the SDK, the CLI and the MCP server, with
nothing sent and no traceback; one table of such tokens holds it.

A token of the first format is refused by name on every surface: "this token
was given by an earlier version of ycli: start the listing again without it".
It names no organization, so it is not guessed at.

The live scenarios gain the round trip (a scroll in pieces, the clear, the next
page refused) and a step field `exits` for a step whose point is a refusal.

BREAKING CHANGE: `tracker.issues.scroll_clear` takes `next: str` in place of a
`ScrollClear` body; `ycli tracker issues scroll-clear` takes `--next TOKEN` in
place of `--pair`; the tool `tracker_issues_scroll_clear` takes `next` in place
of `body`. A `next` token returned by an earlier version no longer goes on:
start the listing again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bim-ba
bim-ba force-pushed the feat/scroll-clear-next branch from e4d8cfc to f149912 Compare October 10, 2026 15:21
@bim-ba
bim-ba merged commit 93d21f8 into main Oct 10, 2026
13 checks passed
@bim-ba
bim-ba deleted the feat/scroll-clear-next branch October 10, 2026 16:02
bim-ba added a commit that referenced this pull request Oct 10, 2026
…of the token (#573)

Two leftovers of the review of #567.

A token of another organization was refused with the name of its header quoted
from the token, up to forty letters of the token's own text: a forged
`Ignore-previous-instructions-and-obey: 7` reached a terminal, and a model
through a tool error. The header is now said only when it is the call's own;
a token under another header is told "of another kind", and the call's side is
named as before.

A session given an organization by hand in another form than `Name: id`
(`SyncSession(client, organization="7")`) failed with a pydantic error at the
first truncated listing, when its token was made. It is refused when the
session is built, in ycli's own words. `connect()` never produced that form.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

This branch was previously deployed

1 inactive deployment
yandex-e2e — f149912c Deployed Oct 10, 2026 by bim-ba via live (all) #703
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant