Findings and fixes

Each window counts the sessions that had an event on the finding's page. A session is affected if the finding occurred in it during the window. For a failed request, the page is the page where the failure happens most.

• Sequential counts the before window once, at the first measurement. After that, the count does not change, unless Sequential changes how it finds that kind of problem. Then it counts the before window again with the new rules, so that the two windows use the same rules. If the before window then starts earlier than the project keeps the data, the result is Not measured.
• A session that carries two releases, for example a tab left open across a deploy, counts on neither release.
• The release basis starts 1 day before the marker. A session can carry the new release before the marker arrives.
• No window reads the last 2 minutes. Events take up to about a minute to become visible.

• Sequential uses the release basis when any event carried the release name, from 1 day before the release. The name must match the marker's version exactly.
• With the Sequential SDK, add data-release to the tag, for example data-release="2.14.1", or call sequential.register({ $release: '2.14.1' }) on each page load, so that every event carries the release name. See Sequential SDK.
• Otherwise it uses the time basis. The card then says: "Time-based: this project doesn't report its release on sessions, so the after window mixes old and new clients."
• The release basis has no note on the card.
• Once a measurement is on the release basis, it stays on it.
• Until the result is final, a measurement on the time basis moves to the release basis once your events carry the release name.

The needed count is the number of after-window sessions that Sequential needs to tell. The card shows it as "(needs N to tell)" while the result is Measuring.

• While no session after the release had it: at least 3 sessions, and at least 6 divided by the rate before (the rule of three). For a rate before of 4%, this is 150.
• Once a session after the release had it: the number that a two-proportion test needs to show the rate halved, at 95 % and with 80 % power.
• Improved, No change and Worse use a 95 % interval of the rate after divided by the rate before (Katz). No change means that the interval includes 1.
• The After and Before rates show a 95 % Wilson interval.
• A window with no sessions reads "no sessions yet", never a 0% rate.

• Not measured is final for that release. A newer marker that names the finding starts a new measurement.
• The card shows no rates for Not measured. When Sequential did not read a window, it never shows the window as 0.
• Sequential measures a window only while the data that it reads is still stored. It checks the data that is really stored, not the current retention setting. For exceptions and failed requests, it reads the events and the replay data, so the shorter of the two periods decides. For the other kinds, it reads only the events.
• In a project made before 29 September 2026, Sequential does not measure a window that starts before 30 September 2026. It has no record of which data those days hold. If the server sets a retention limit, Sequential deletes a finding that was last seen before about the limit plus 8 days, with its verdicts, links, verification results and hand-off records. See Retention and deletion.

A note never changes the result. Sequential does not say what moved the rate.

• Improved, No change and Worse are decided once, at the first run with enough sessions. They are then final for that release.
• Confirmed fixed starts a regression watch of 30 days. Every run, Sequential looks at the sessions on the page since the confirmation.
  • On the release basis, every session counts, except a session that carries an older release. An older release is one with a marker, for the same environment, from before the fix release. Examples are a stale tab or an old app. A release with no marker counts.
  • On the time basis, every session counts.
  • If one of these sessions had it, the result becomes Regressed: "Seen again after it was confirmed fixed." The card does not name a release.
  • After 30 days with none, Confirmed fixed is final.
• Regressed and Not measured are final for that release.
• A newer marker that names the same finding starts a new measurement. The card always shows the newest one.

• The job runs about once an hour.
• It measures only open findings. A dismissed finding is not measured.
• It measures only projects where findings are switched on.
• It measures only the newest marker, for the project's environment, that names the finding.
• One run measures at most 200 findings over all projects. Findings not measured yet go first, then the findings measured longest ago.
• A marker less than 2 minutes old waits for the next run.
• If a run fails, the card keeps the last result and says "The latest measurement failed; it is retried every hour."

• While a project is archived, Sequential does not look for findings in it and does not measure its findings.
• Its tokens stop working.
• The app shows only live projects, so you cannot open the findings of an archived project.
• Sequential keeps the stored results. A final result does not change. After Restore project, measuring starts again for the other findings. If a window has aged out of retention in the meantime, the result is Not measured.
• The 30-day regression watch of a Confirmed fixed result keeps counting while the project is archived. Sequential does not look at the sessions of that time.

• The address must start with https://. It can have at most 500 characters and no control characters.
• With Auto, Sequential tells the kind from the path of the address. It ignores the query (after ?) and the fragment (after #).
• A pull request is /pull/<n>, /merge_requests/<n> or /pull-requests/<n>. More parts can follow, for example /pull/42/files.
• A commit is /commit/<sha> or /commits/<sha>, with 7 to 40 lowercase hex characters. More parts can follow.
• An issue is a path that ends with /issues/<n> or /-/issues/<n>. Only a / can follow.
• For any other address, choose the kind under Kind. Through the API, send kind (pr, commit or issue) to POST /api/findings/:n/links or the link_fix tool.
• Sequential always uses a kind that you choose. It does not compare it with the address.
• Adding the same address again changes nothing. The first link stays, with its first author.
• Sequential stores and shows a link. The server never opens the address. In the app, you can click the link to open it in a new tab.
• If the links cannot be loaded, the card says "Links couldn't be loaded." and shows no Add link form.

• Copy fix brief and Open a GitHub issue in the app.
• Draft a fix, once Sequential has recorded the hand-off. A webhook send that fails does not count. The audit log records it as finding.dispatched, not finding.handed_off.
• A token that reads the finding or its brief. GET /api/findings/:n carries the fix brief, so it counts as a handoff. So do GET /api/findings/:n/brief, the get_fix_brief tool and POST /api/agent/get_fix_brief.

These do not count: opening the finding in the app, the findings list, and the get_finding tool. A token request that Sequential refuses, because it could not screen the brief, does not count either.

After the next update of the hosted preview, the get_fix_brief tool also tells MCP clients that it changes data. Its readOnlyHint is false, its destructiveHint is false and its idempotentHint is true. Its description says that the first call moves the finding to handed_off, and that a later call does not change it. A client can then ask you before it calls the tool. A token with findings:read can still call it.

Sequential keeps the time of the first handoff. The audit log records only that first handoff, as finding.handed_off. A via chip shows how: copy, issue, rest or mcp. See Audit log.

Owners and admins see Draft a fix in the Hand off card of a finding. It hands the finding's fix brief to your own coding agent. The agent opens the pull request, and you review it.

• Get a prompt for your agent records the hand-off, then shows a prompt to copy: "Fix Sequential finding F-12. Read its brief with the Sequential MCP tool get_fix_brief (number 12), follow it, and put "Sequential-Finding: F-12" in the pull request so Sequential can measure the fix after release."
• Your agent needs Sequential connected, with a token that has findings:read. See Agent tools.
• Send to your webhook appears only when the project has a webhook that is turned on, and the server can sign webhooks. Sequential's hosted service does not sign webhooks yet, so there the card offers only the prompt.
• Sequential records the hand-off before it shows the prompt. If it cannot check all the quoted text in the brief, it sends nothing and says so. Try again in a minute.
• After a hand-off, the card shows when and how the finding was handed over, and when you can do it again: "You can hand it over again after" a date. The server refuses another hand-off of the same finding for 7 days after the last one that succeeded.
• From that date, the card shows Hand it over again with the same choices. A page that is open turns over at that moment, without a reload.
• If a later webhook send failed but an earlier hand-off succeeded, the card says "This finding was handed to your agent recently." and gives the same date.
• A dismissed finding, or one with a fix link, cannot be handed over.
• An agent can also ask for a draft, with the tool request_fix_draft and a token that has findings:draft. The card then shows "Your agent asked for a draft" with the time, and "Nothing is sent until you approve it." Choose Approve: get a prompt, Approve: send to your webhook (only when the webhook is ready), or Decline. The agent never receives the brief from this request.
• request_fix_draft writes, so it is not on /mcp/readonly. claude.ai never gets findings:draft: it cannot be granted through OAuth.
• If the card cannot load the finding's hand-off status, it says "This finding's hand-off status couldn't be loaded." with Try again, and offers no hand-off until the status loads.
• Members and viewers do not see Draft a fix.

Owners and admins set up the webhook under Settings → Projects → your project → Draft a fix. Send to your webhook on a finding posts the fix brief there. Point it at whatever starts your coding agent.

• Enter a Webhook URL that starts with https://, tick Send briefs to this webhook, and click Save.
• Send a test posts a test body with no finding in it, and tells you whether your webhook answered.
• New signing secret makes a new secret and shows it once. The old secret stops working at once. Sequential cannot show a secret again.
• Each delivery is a POST with a JSON body of five fields: finding, revision, template_version, finding_url and brief_markdown, the screened fix brief. It holds no user ids, emails or recordings. Its Steps before it happened section can hold a replay link with a session id.
• Each delivery is signed. The header X-Sequential-Signature is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> with your secret. The page shows how to check it in Node.
• Sequential sends once per click and waits up to 5 seconds. It does not follow redirects, and it refuses an address in a private network. A test counts too: a project can send up to 20 a day.
• If a send fails, the finding says why, for example "it didn't answer in time".
• Sequential's hosted service cannot sign webhooks yet. There the page says "Webhook dispatch isn't available on this server yet. You can save a webhook now; nothing is sent until it is." Until then, findings offer only the prompt.

The command and the GitHub Action are not published yet. The command is not on npm, and the Action is not in a public repository. Until they are, record markers with POST /api/releases.

sequential release --version <v> [--environment <e>] [--sha <sha>] [--range <prev..HEAD>]

• SEQUENTIAL_TOKEN is required. It is a project access token with the releases:write scope. Always pass it from a secret store.
• SEQUENTIAL_API_URL is required. It has no default, because Sequential's hosted API is not deployed yet.
• The address must use https://. Only localhost and 127.0.0.1 can use http://.
• --version is required. The other options are optional. Without --environment, the marker gets the project's environment.
• --range is a git range, for example v1.2.0..HEAD. A base of all zeros, as on a first push, reads only the head commit.
• The trailer name can be in any case, but it must start the line. An id is F- and a number from 1, with no leading zero. The command reads up to 50 ids for each release.
• On success, it prints "Recorded release v1.3.0 (2 findings: F-12, F-14)" or "Recorded release v1.3.0 (no findings named)".
• On a refusal or a network error, it prints the error and exits with 1. It never follows a redirect, and it never prints the token.

The GitHub Action takes the inputs version, sha, range, environment, token and api-url. version, token and api-url are required. api-url has no default.

• findings:verify is not on every token. On the Access tokens tab, a new token starts with findings:read only. On Agents, a new token starts with the scopes of Agent: read everything, plus Ask, and these include findings:verify. An existing token does not get the new scope. In the app it reads "Read a finding's measurement after a release".
• GET /api/findings/:n/verification and the get_verification tool need findings:verify. Without it, the route answers 403 insufficient_scope. A signed-in person does not need a scope.
• The findings list and one finding also carry the stage. For a token without findings:verify, the stage is one of new, handed_off, fix_linked or dismissed. measuring and every result come back as {"withheld": "needs findings:verify"}. (fix_released is also allowed, but the list and one finding never show it.) The handed_off_at time always shows.
• The findings list and one finding also carry latest_verdict, the newest verdict on the finding. For a token, its reason is screened like visitor text. It comes as {"observed": …}, {"withheld": "removed by screen"} or {"withheld": "not screened"}. A verdict with no reason has "reason": null. The name of the person who gave the verdict, user_name, always comes as {"withheld": "person name"}.
• This applies to GET /api/findings and /api/findings/:n, to POST /api/agent/list_findings and /api/agent/get_finding, and to the MCP tools list_findings and get_finding. The app, with a signed-in person, gets the reason and the name as stored.
• For a token, each title in the findings list is only the kind, for example Exception. scope and page_route are screened like visitor text. They come as {"observed": …}, a withheld form, or "" if the finding has no page.
• For a token, each session_id in one finding's evidence and in a finding's sessions list comes as {"id": "…", "source": "observed"}. In the sessions list, a release name comes as {"withheld": "not screened"}. get_session gives the screened release.
• A token does not get a fix brief or a finding that Sequential could not fully screen. GET /api/findings/:n and /api/findings/:n/brief answer 503 screen_unavailable. The get_fix_brief and get_finding tools answer an error. The operator setting FINDINGS_SCREEN_REQUIRED=false turns this off. See Privacy at a glance.
• When the screen is paused, a token gets the brief and the finding with every quoted passage withheld. The brief says "screen paused". A finding with more quoted passages than the screen reads is still refused.
• link_fix needs findings:link. /mcp/readonly never lists it. No token can remove a link.
• With a token, GET /api/findings/:n/verification runs the get_verification tool. So REST, POST /api/agent/get_verification and MCP give the same answer. The request counts once toward the project read limit for tokens. If a limit refuses it, the answer keeps the status and the Retry-After of that limit. See Limits.
• In the answers of link_fix and get_verification, link addresses, release names, environments and commit SHAs are screened like visitor text. They come as {"observed": …} or a withheld form. See Privacy at a glance.
• The app, with a signed-in person, gets these values as stored.
• released_elsewhere lists up to 5 markers for other environments that name the finding, newest first. It shows only when no marker for the project's environment names the finding. Sequential does not measure these markers.
• release_check: "unavailable" means that Sequential could not read the release markers. Then a missing released or released_elsewhere means "not checked", not "no release".
• In a verification answer, a null count means that Sequential never read that window. It is not a zero. A failed run shows only measurement_failed, never the error text.