* feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163) Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad; Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading. Every byte and reading under test was written by hand: no report from a real controller has passed through this code. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160) Nine columns on sessions (the time in front and its four classes, the switches of method, the sources that answered, the controllers as JSON) and three on games (what a store lists of controller support), ADD COLUMN only. The .partial file gains chunk 11, so a session recovered after the Agent died keeps its readings. SessionFinalizer.Build stores them before the tier branch: hooked, unhooked and recovered sessions alike. The input series are sensor_blobs rows named input.*, which the sensors' read now leaves out and FindInputSensorsAsync returns. Nothing produces a reading yet. A ledger this build has opened cannot be opened by 0.1.0-beta.49 or earlier. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): the input reader, which the Agent does not start yet - raw input for controllers, XInput, the time of the last input (D155, D158, D159) Application.Input.InputReader takes a slice about ten times a second from Infrastructure.Input.Win32InputBackend, on the thread of InputDeviceHub, which exists only while a session has a view of it. It opens no device, sends nothing to one and registers for no keyboard or mouse. tools/input-readonly-check.ps1 holds its Windows calls to a list. With no controller at hand, what the reader does with one connected is not established. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * fix(input): an arm of XInputPad.Battery's switch said what the default says (Qodana, on #464 after it merged) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): no using that makes the file's own qualified names redundant (InspectCode) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): what InspectCode reported in the reader's tests - redundant casts, a hub disposed twice, a suppression not needed Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * wip(input): the Agent records what a session was played with - the switch, the terms, the legal texts Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * style(input): import order in the Agent's composition; no redundant qualifier in a test (InspectCode) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
108 KiB
19 — Safety & anti-cheat policy
FrameLedger injects a DLL into game processes. That is a legitimate, mainstream technique (RTSS, Special K, OBS Game Capture, ReShade, Steam/Discord overlays all do it) — but it carries one real risk that falls entirely on the user: an anti-cheat system may flag, block, or ban an account. This document defines the guard rails that make that risk manageable, and the things this project will deliberately never build.
Design principle
A performance tool should be easy for anti-cheat to see and identify, and should refuse to run where it isn't welcome.
Every decision below follows from that. The failure mode we are engineering against is not "anti-cheat detected us" — that is fine and expected. It is "a user got banned because our tool loaded somewhere it shouldn't have."
What we will never build (rule 3 in CLAUDE.md)
These are permanently out of scope. A PR implementing any of them is rejected regardless of quality:
- Manual mapping / reflective loading, or any injection that bypasses
LoadLibrary - Erasing or corrupting PE headers of the loaded module
- Unlinking the module from the PEB loader lists
- Hiding, renaming, or randomizing the DLL, its exports, or its shared-memory object names
- Thread hiding (
NtSetInformationThread/ThreadHideFromDebugger) or debugger-evasion tricks - Signature-breaking obfuscation/packing of our own binaries
- Any "bypass" setting, "stealth mode", or documentation explaining how to defeat the guard below. (The first two words left this line on 2026-09-21 and returned on 2026-09-22 — §What a finding does to the game. The one exception the owner has granted since, D33 on 2026-09-26, is not a bypass: the guard still runs every check and decides itself which family is user-mode — §The user-mode exception.)
- Reading or writing game memory outside the arguments of APIs we hooked
- Kernel drivers of our own
The DLL ships with its real filename, a populated VERSIONINFO block (CompanyName, ProductName=FrameLedger, version), and named kernel objects that clearly say FrameLedger. Being identifiable is a feature. Since beta.14 (D50) the Agent — the process that injects — and the App say the same about themselves: FrameLedger as company and product, FrameLedger Agent as the Agent's description, the native binaries' copyright line (12_BUILD §Version, Identity; tools/versioninfo-check.ps1 reads both kinds).
The anti-cheat guard (hard gate)
Implemented in FrameLedger.Injector and reached from managed code through a thin P/Invoke facade — one implementation, never two (20_OPEN_QUESTIONS §S15). Runs before every injection, and again periodically for every Tier-1 session, injected or layered.
"During a hooked session" was the original wording, and it excluded Vulkan by accident: those titles are captured by a Khronos layer and nothing is ever injected into them. The periodic re-scan is scoped to the tier, not to the mechanism.
Pre-injection checks (all must pass)
-
Target module scan — enumerate loaded modules of the target process (
EnumProcessModulesEx, read-only handle:PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_VM_READ). Match against the blocklist below by filename.LIST_MODULES_ALLis mandatory, not a preference. Measured 2026-08-02 unelevated against a live 32-bit target from this x64 process (spike-notes.md§1):ALLreturns 15 modules,LIST_MODULES_DEFAULTreturns 7 — and returns them as a success. A guard using the default would scan a 32-bit title, see under half its modules, find no anti-cheat among them and report clean.Every failure of this call means REFUSE. Two specific cases, both measured:
OpenProcessreturningERROR_ACCESS_DENIED (5)on a protected target, andEnumProcessModulesExreturningERROR_PARTIAL_COPY (299)against a suspended target (§S1). Neither is "no modules found". The read handle rights above are confirmed sufficient for every target this call can legitimately reach.Amended 2026-10-05 (owner decision D48, beta.14): one re-read, never a pass. A member of the scan set that is still being created answers
ERROR_PARTIAL_COPY(its loader has not built a module list), and one that exited between the snapshot and the open answersERROR_INVALID_PARAMETER. Both refused the whole session — and at the 30 s re-scan an engine's crash reporter starting as its game died, or any helper started a moment before the scan, turned an ordinary exit into a "safety" unhook, which ends a user-mode exception's trial for good. Such a member (Collected::kRetry,fl_guard.h) is now read once more: the pass finishes (a finding in any member still refuses at once), waitskScanRetryPauseMs(250 ms), takes a fresh scan set and scans it whole. A member still unreadable then refuseskProcessUnreadable, as before; one that has gone is not in the new set; a target that has gone leaves no set, which refuseskProcessTreeUnavailable.ERROR_ACCESS_DENIED— a protected process — is never retried, and no other answer of any source is (one more since D123, below). The sentence above stands: every failure still means REFUSE; what changed is how many times "still loading" is asked before it counts as one. ctestfl_guard[D48]holds both directions, against fakes and against the real source (a process created suspended, a pid with no process).Amended 2026-11-12 (owner decision D123): a module list that changed while it was read is read again, at most three times — never a pass. The module check lists a process's modules and then asks each one's name. A game at its launch loads and unloads modules for seconds, and a module that was in the list and could not be named a moment later made the whole answer "incomplete": a refusal before injection, or — 0.5 s after it, at the first supervision scan — a safety unhook with no frame recorded, the game then running on unrecorded. Five such ends in one PC's Agent logs in a week (Phantom Blade Zero three times on 2026-11-05, Crown & Coin on 11-10, Cyberpunk 2077 on 11-12), and twice in this repository's own gate. Asked with that, the owner chose: read it again. Such a list is now
Collected::kUnsettled; the pass finishes — a blocklisted module among those that were read still refuses at once — waitskScanRetryPauseMs, takes a fresh scan set and reads it whole, up tokMaxUnsettledRereads(3) times: four reads and 750 ms of pauses at most. A list still unsettled on the last read refuseskModuleScanFailed("a module list kept changing while it was read"). What did not change: a list too long for the guard's buffer is stillkIncompleteand refuses at once (a second read would be as long); a protected process still refuses at once; D48's re-read is still one for the whole check; every read is of the whole scan set, and the read that allows is one in which every member was read whole and none held a finding. A failure to read is still never a pass — what changed is how many times a list that is moving is asked before it counts as unreadable. The launch poll's presentation-runtime probe treats an unsettled list as "ask again" rather than deciding on half of one. ctestfl_guard[D123]: against fakes, every direction above; against the real source, a process that loads and frees a module in a loop — read some 3,600 times in three seconds, about one read in four is unsettled and none is anything else.Launch mode (2026-09-06, P1 item 2) does not weaken this.
FlGuardedInjectWhenReadypolls the same enumeration to learn when the launched target has mapped a presentation runtime, and a failing enumeration there means "not yet" — the poll continues. That is not a pass: the poll matches nothing against the blocklist, and the injection happens only after check 1 has run in full, with the enumeration succeeding, exactly as in attach mode. A launched target that never becomes scannable is never injected (LaunchNoPresentationRuntime). Which processes get scanned: the game's own subtree.04_CAPTURE§The guard writesCheck(pid)— singular — while04_CAPTURE§Process watcher says the capture target is a descendant elected from a ppid chain. Neither of the obvious readings is right (20_OPEN_QUESTIONS§S16, decided 2026-08-02):- The presenting process alone is too narrow. A game's own launcher routinely initialises anti-cheat and then spawns the renderer. Scanning only the process we inject into would miss exactly that arrangement, and it is a common one.
- Every ancestor is far too broad. The ancestor of every Steam title is
steam.exe, which loadssteamserviceand VAC modules. Scanning ancestors without limit would refuse every Steam game — not "some false refusals" but the product not working, which is precisely how a user ends up hunting for the override that does not exist.
So the scanned set is the injection target, its descendants, and its ancestors up to but excluding the first known platform launcher. That is "the game's own tree" — everything the title itself brought with it, nothing belonging to shared platform infrastructure.
The launcher list is a hardcoded array in
fl_guard_sources.cpp, and that is deliberate. This line used to say the cutoff comes fromplatformsindetection-rules.json. It does not, and it must not: that key holds sibling-glob signals for engine attribution, the guard never reads it, and a data-driven cutoff would let a rules push widen the hard gate's blind spot — one more launcher name in an updatable file and an entire branch of the tree stops being scanned. Same reasoning as §S8's absence-of-override: the boundary of what the gate looks at is code.A hit anywhere in that set refuses. A process in the set that cannot be inspected (
ERROR_ACCESS_DENIED) refuses too — there is no "scanned what we could" state.Amended 2026-10-06 (owner decision D51, beta.15): a parent link is followed only while creation times allow it. The set is walked over one process snapshot, which links a process to its parent by pid alone, and Windows reuses pids. A launcher that exits after starting its game leaves the game naming a pid that may now belong to anything: until beta.15 the walk scanned whatever held it — a protected process refused the session as unreadable, a blocklisted one turned the game's hooking off for good — and a cycle of reused pids sent the same processes round again. A parent/child link is now cut only when it is proven wrong: both creation times read (
GetProcessTimes, under the module scan's own read-only right) and the child created before the process whose pid it names as its parent, which no real child can be. A cut ancestor link ends the ancestor walk there; a cut child is not walked, nor is anything below it. A time that cannot be read keeps the link, equal times keep it, and each pid is walked and scanned once (WalkScanSet,fl_guard_scanset.cpp). Nothing else about the set moved: the launcher boundary, the depth (16 ancestors), the frontier (512 — one more refuses) and "a member that cannot be read refuses". The residual: creation times are wall-clock, so a clock set backwards between a parent's start and its child's makes a real link look wrong and drops that branch from the module check; the install-folder scan and the machine-wide driver and service checks do not depend on the tree. ctestfl_guard[D51]holds the walk against fixtures (a reused parent, an older "child", unread times, equal times, cycles, the limits) and the real source against a child this process starts.One reviewed exception, decided 2026-08-03 and implemented 2026-08-04 (§S18), then re-keyed the same day (§S22(b)). A module that is FrameLedger's own does not trip the fuzzy fragment tier. The exact blocklist still applies in full, the exception never applies to the injection target, and a seam that cannot answer does not suppress.
It asks about the MODULE, not about the process that loaded it. The first implementation asked whether the scan-set process lived in our directory, which made the exemption depend on where the host binary sits: measured, the same binary run from beside
FrameLedger.Guard.dllreachedAllow, and run from anywhere else returnedSuspiciousUnsignednaming our own DLL. The Agent worked only because a.targetsfile happens to co-locate them. The module form is also strictly narrower — a genuinely foreign suspicious module inside a FrameLedger process (an AppInit DLL, an AV user-mode hook, an IME) used to be suppressed with our own and now is not.A module whose path we could not obtain is not exempt. Failing to locate a module does not make the scan incomplete — the name is what the blocklist matches on — but we cannot exempt what we cannot identify.
The justification first written here was false, and it is worth replacing rather than deleting. It read: "our own module set is identical in every session and therefore cannot discriminate between titles; it can produce false refusals and never a true one." That is not a property of any user-mode process. Measured 2026-08-04 across 290 live processes, three carried a module matching a
nameFragment— a Microsoft key-protection provider, a .NET crypto assembly and an AV interop DLL — and none of them required write access to anything of ours. An AppInit DLL, a shell extension, an IME or an AV user-mode hook can put a fragment-matching module into a FrameLedger process, so the fragment tier could in principle say something true about one.The honest justification is narrower and rests on trust rather than on information: the fragment tier is a heuristic for the unknown, and our own install directory is not unknown to us. An attacker who can place a binary there can already replace
FrameLedger.Guard.dllitself, whichNativeAntiCheatGuardcalls a worse outcome than any other DLL-hijack in the application — so the exception grants nothing that was not already lost. What it costs is the fragment tier's opinion about our own processes, and that is the trade being made deliberately.Residual, stated: the project ships unsigned (CLAUDE.md rule 9), so there is no integrity check on the contents of that directory. The exception is as strong as the install location, and no stronger.
Identity is by directory, compared with
GetFileInformationByHandleEx(FileIdInfo)— same volume serial, same file id — never by string. A prefix compare would have to defend against 8.3 short names, junctions,subst, mapped drives,\\?\forms and a sibling folder namedFrameLedgerEvil, and it folds case with C-locale rules theja/vibuilds cannot rely on. Our own directory comes from the module containing the guard code, never from the process image: under a test host the process isdotnet.exewhile the guard DLL lives elsewhere, and §S18 rejected process identity precisely because the defect is a property of the binary.Sibling services (BattlEye's
BEService, EAC's service) are not in any process tree and are deliberately not chased here: check 3'sservicesgroup covers them by name, which is more reliable than tree walking.The runtime re-scan (§During a session) recomputes this set each time rather than caching it: level-transition relaunches re-elect the presenting pid, and a newly spawned helper must be seen.
-
System driver scan — enumerate loaded kernel drivers for always-on anti-cheat drivers that gate the whole machine (e.g. Vanguard's
vgk). Present → refuse for all titles while it is running, not just the matching game.🔴
EnumDeviceDriverscannot do this unelevated, and it fails open. Measured 2026-08-02 on Windows 11 26300 as a standard user — which is the default Agent configuration (ADR-9):EnumDeviceDrivers ok=True count=258 non-null base addresses: 0 distinct names recoverable: 1 -> ntoskrnl.exeThe call succeeds. It reports 258 drivers. It then yields no usable base address for any of them, so
GetDeviceDriverBaseNamerecovers one name. A guard built on it would report "no anti-cheat driver present" on a machine running Vanguard — a fail-open in the hard gate, in the default configuration.14_TESTINGalready insists an empty module list must never read as "clean"; the same rule was never applied to drivers, and this is what it looks like when it is missed.The defect is purely a function of elevation, measured both ways by
fl-probe-guard(spike-notes.md§1):Configuration EnumDeviceDriversresultunelevated (dev machine, the ADR-9 default) 266 drivers, 0 bases, 0 names elevated (CI runner) 260 drivers, 260 bases, 260 names So the API is not broken — it is broken for standard users, and ADR-9 makes standard user the default Agent. Anyone testing this while elevated sees a perfectly working call and concludes the note above is wrong. It is the sharpest illustration in the project of why measurements must state their configuration: the same API, on the same OS, is either fine or catastrophic depending on a token.
Use
NtQuerySystemInformation(SystemModuleInformation)instead. Measured on the same unelevated session:STATUS_SUCCESS, 258 modules, 258 distinct full driver paths, real third-party driver names legible. Corroborate withOpenServiceW/QueryServiceStatusEx, which also distinguishes absent (ERROR_SERVICE_DOES_NOT_EXIST, 1060) from denied — a distinction the guard needs, because denied must fail closed while absent must not.A service counts as present when it is RUNNING, not when it is installed. Measured 2026-08-03 and it is not a small distinction:
EasyAntiCheat_EOSis installed machine-wide by any EOS title, sits Stopped/Manual until its own game runs, and under the installed-means-present reading the guard refused every process on the machine —explorer.exeandsteam.exeincluded — for a Unity indie game with no anti-cheat anywhere in its install tree. That is this document's own failure mode: a gate that refuses everything is not a strict gate but a broken one.The machine-wide guarantee does not rest on this check. A loaded driver is check 2 and still refuses for all titles; modules inside the target are check 1. A stopped, manual-start service has no code in any process, and when its game actually runs both of those fire.
SERVICE_STOPPEDis the only state treated as absent — start-pending, paused and stop-pending all mean code is or was live — and the 30 s in-session re-scan closes the window between the check and a later start.NtQuerySystemInformationis a documented-as-unsupported API and itsRTL_PROCESS_MODULE_INFORMATIONlayout is version-sensitive; the struct offsets must be asserted, not assumed. Treat a parse failure as refuse, never as clean.(Corrected 2026-10-04: done —20_OPEN_QUESTIONS§S7 tracks the remaining work.fl_guard_sources.cppasserts the layout and refuses a parse that yields non-native paths; §S7, closed, is about handle rights and WOW64.) -
Rules blocklist —
detection-rules.jsoncarriesanticheat.blockedExecutables(exe names) andanticheat.blockedStoreIds(Steam appids etc.) for known competitive/online titles,updatable independently of app releases (shipped with each release; there is no rules-update path yet (corrected 2026-10-04:05_DETECTION§Rules updates)20_OPEN_QUESTIONS§S20 feed half;05_DETECTION§Trust and staleness of the rules feed).Both halves are wired and seeded since 2026-09-25 (owner: "as many and as strict as possible"; rules
2026.09.4). The block below is the history it replaces, kept for the reasoning.The store half reads the store's own files, through a seam the guard owns.
Sources::StoreIdentitytakes the install root the guard already derives from the pid (check 4'sImageDirectory) and answers from disk: under<library>\steamapps\common\<folder>, the oneappmanifest_<id>.acfwhoseinstalldiris<folder>→steam:<id>; agoggame-<id>.infoin the root →gog:<id>. Nothing is handed in by a caller (§S3 is untouched — the ABI still takes a pid and nothing else) and nothing is read from the game's process (rule 4).The matrix §S14 asked for: a listed identity refuses (
BlockedStoreId, naming the family); an install no store names — a loose folder, a GOG-less, manifest-less copy — is not refused, because "no store identity" is an answer, not an unknown, and refusing it would be the gate that cannot pass; a store layout whose metadata could not be read (a manifest that will not open, more than 4096 of them, a listing error) refuses asPreScanFailed. With nothing listed, nothing is read. Epic has no reader: an Epic install carries no identity to this check.What is listed, and why a title list at all:
3334 Steam app ids and 33 executable names across ten families — Valve VAC (CS2, Dota 2, TF2, Deadlock and Valve's older VAC titles), Riot Vanguard, Roblox Hyperion, Blizzard's online titles ("Blizzard Warden"), Call of Duty (Activision Ricochet), NetEase (Marvel Rivals, NARAKA, FragPunk, Once Human), ACE (Delta Force, Arena Breakout: Infinite), HoYoverse and EA (Battlefield 2042/6, EA SPORTS FC 25/26), and since 2026-10-03 (rules2026.10.1, owner's list) HyperTech's CrackProof (Umamusume: Pretty Derby3224770, Heaven Burns Red1973710, Madoka Magica Magia Exedra2987800— Steam ids only: no executable name was verified, and a guessed one is a false refusal waiting for an unrelated game). Since 2026-10-13 (rules2026.10.4, owner decision D58) Wuthering Waves3513350, under ACE, by its Steam id alone (its executable,Client-Win64-Shipping.exe, is a name Unreal games share): its ACE sits beside the executable, where check 4 did not reach until the same rules (item 4 below), and a session was hooked for 37 s on 2026-10-12 before the 30 s re-scan met the driver — a machine-wide finding, which turned nothing off (spike-notes.md§19). These are the titles whose anti-cheat leaves nothing of the game's own for checks 1, 2 and 4 to find — VAC runs inside Steam, Blizzard's scanner is built into the game — or whose kernel driver loads only after the checks run. CrackProof is the second kind: a Proton log of Umamusume shows its driver loaded fromC:\Windows\System32under a numbered name (usrdrv017864.sys, ValveSoftware/Proton#8853), outside the game's folder, so the.sysrule cannot see it before the first run and no driver token could name it. Each of the three store pages states "Uses Kernel Level Anti-Cheat" and CrackProof (read 2026-10-03); ANOTHER EDEN, which a community list also names, was left out because its store page says nothing of the kind. Every app id was checked against its Steam store page; Call of Duty's changed when Activision split CoD HQ, so only ids with a live store page are listed. The per-title lists are floored like the families: a rules file can add a title and cannot take one off.rules-validaterefuses a name engines and tools share (Game.exe,Client-Win64-Shipping.exe,hl2.exe…), an exact rule that names no.exe, and duplicates.The owner declined the bulk list (AreWeAntiCheatYet's ~250 Steam ids): community data that keeps listing a game after it drops its anti-cheat would turn hooking off for good on a title that no longer needs it.
⚠ ◐ The EXECUTABLE half is wired as of 2026-08-05; the STORE-ID half is blocked.
CheckBlockedExecutableruns insideEvaluateImplbetween the module scan and the pre-scan, and an unresolvable identity refuses withkProcessUnreadable. The list ships empty, so nothing is refused today — but populating it now does something, which it did not before.MatchesBlockedStoreIdis still uncalled and cannot be called: no component produces astore_id, the guard ABI deliberately accepts no evidence from its caller (§S3), and refusing on an identity the guard can never resolve would be a gate that cannot pass.20_OPEN_QUESTIONS§S14 carries the detail.The paragraph that follows is the state before that change, kept because the shape recurs: both arrays are empty, and
MatchesBlockedExecutable/MatchesBlockedStoreIdhad no call site anywhere —EvaluateImplnever asked them. Populating the data would therefore change nothing. The gate is not weakened, because checks 1, 2 and 4 run and every family in the seed below is caught by a module, driver, service or directory signal — but the per-title layer this bullet describes does not exist yet, in two independent ways. Which titles to list, and what an unresolvable store id means (it must read unknown, never clean), are decisions tracked as20_OPEN_QUESTIONS§S14. Stated here so that "check 3 passed" is not read as "the title is not a known online title".The parser now reads both arrays in their real, documented shape (objects carrying
family,match/store+id,valuesandreason), so the data can be written before the wiring lands. It used to read them as bare strings, which meant the first entry ever added would have refused the whole rules file — and therefore every title on the machine (§S17). -
Multiplayer heuristic — if the pre-launch file scan finds an anti-cheat SDK shipped alongside the game (e.g. EOS anti-cheat binaries,
EasyAntiCheat/directory) even when not currently loaded → refuse and explain.Any kernel driver in the install tree counts, since 2026-09-25 (owner decision). A
*.sysfile that nofilesentry names is reported asAntiCheatFileunder the family "Kernel driver in the game folder". Every driver this project has found shipped inside a game —PGameProtectDriver_X64.sys,randgrid.sys,NeacSafe64.sys,BlackCat64.sys,mhyprot*.sys— was an anti-cheat's, and naming each one in data first is how the next one walks past, as ACE's did in August. The rule is code, not data (fl_prescan.cpp,kKernelDriverInTreeFamily): no rules file can remove it or rename its family. A namedfilesentry still wins, sorandgrid.sysreads as Activision Ricochet. The cost the owner accepted: a game that ships a driver for some other purpose (a wheel, a peripheral, an old disc check) has its hooking turned off like any finding, and nothing clears it.The advisory pre-scan takes the executable and resolves the install root itself, since 2026-09-25.
FlStaticPreScan(gameDirectory)scanned the directory it was handed, and its one caller (SetHookEnabled) handed it the executable's own folder — so for an Unreal title, the scan that decides whether hooking may be turned on looked at<root>\<Project>\Binaries\Win64\, exactly where the Lies of P measurement below saysEasyAntiCheat/is not. The chokepoint always resolved the root.FlStaticPreScanGame(exePath)replaces it: the sameResolveInstallRoot, plus check 3 on the executable's name and the install's store identity.Implemented, and stated narrowly.
fl_prescan.cppwalks the target's install root and, since 2026-10-13, its executable's own folder (both derived from its pid, never from a caller-supplied path — "Which directory" below) to depth 3 — raised from 2 on 2026-08-04 (§S22,spike-notes.md§13), because a title shipping its own kernel driver two levels below the install root was invisible from where the scan starts, so the blocklist row naming it could not fire — matching entry names through the sameMatchNameas every other check: directory names against thedirectoriesgroup, file names againstfiles.Reason::kAntiCheatDirectoryandkAntiCheatFileare produced here — until now they were declared, named and mirrored while nothing produced either.It runs inside the chokepoint, as the last of the four checks in
EvaluateImpl.FlStaticPreScanFlStaticPreScanGame(since 2026-09-25 — corrected 2026-10-04) also exports it for FR-2.2's pre-launch question, but that export is advisory: it gates nothing, and a caller who never asks it — or ignores the answer — changes nothing about what injection allows.The UI cannot reach that export today, and this sentence used to say it could. Since 2026-08-04
FrameLedger.Guard.dllships beside the Agent only (FrameLedger.Guard.targets, §S18 blocker 3), soFrameLedger.Apphas noFlStaticPreScancall site and no DLL to load. FR-2.2's advisory answer reaches the UI through the Agent over IPC (07_IPC)when that exists. Recorded rather than quietly reworded: an advisory export with no consumer is a claim about the product that is not true yet.(corrected 2026-10-04: it does — the Agent'sSetHookEnabledanswer carries it since P3,HookEnabledAck.Prescan, and the library sweep'shook_prescan_statesince beta.8 is shown on the game's page).Which directory. The install root, resolved by walking up from the executable to a known platform boundary (
steamapps\common\<X>and friends) — not the directory the executable sits in.Measured 2026-08-03 on Lies of P, and the difference is the whole check: Unreal puts the exe at
<root>\<Project>\Binaries\Win64\, a folder holding seven files, none of which could ever have been an anti-cheat SDK — whileEasyAntiCheat/sits at the root three levels up. For exactly the layout most likely to carry EAC, this check scanned a directory that could not contain what it was looking for, and returned clean.The boundaries are hardcoded, like
IsPlatformLauncher, because a data-driven boundary lets a rules update move where the hard gate looks. When no boundary is recognised the executable's own directory is used — walking up blindly would reach a folder of unrelated games, and refusing a title because a sibling ships anti-cheat is a false refusal with no appeal. A nested executable outside a recognised store layout is therefore still scanned narrowly; that residual is stated, not closed.Amended 2026-11-03 (beta.33,
spike-notes§25): a GDK package root is a boundary too, andGamesInstalledis one natively. The Xbox app and the Microsoft Store install to<games folder>\<Game>\Content\under a folder the user names, which no string can bound — so for the executable the import picks there (an Unreal title'sContent\<Project>\Binaries\WinGDK\…-Shipping.exe), check 4 walkedBinaries\WinGDKalone, and anEasyAntiCheat\atContent's root would have read clean: the residual above, on a whole store. The package marks its own root —MicrosoftGame.configbesideappxmanifest.xml, both files — so only when no string boundary matched, the nearest folder at or above the executable's that holds both is the root (at most eight levels up, never a drive's root;ResolveInstallRootand the managedInstallRoot). Not a blind walk up: a marker the package writes, measured as exactly one per package atContent's root on the owner's 11 titles; and only ever a widening relative to the executable's folder — a Steam build carrying GDK files keeps its Steam root. The native list also gainsGamesInstalled\<X>, which the managed one had since #17 and the native one never did; one case list (tests/fixtures/install-roots/cases.txt), read by both suites, holds the two resolvers together from now on.Amended 2026-10-13: the root AND the executable's folder. The root replaced the executable's folder, and that was half the answer. The walk reaches three levels below where it starts, and an Unreal executable is already three below its root, so a folder beside the executable is four: MEASURED on Wuthering Waves, whose Tencent ACE lives in
Client\Binaries\Win64\AntiCheatExpert\(withACE-BASE.sysandACE-CORE.sysin it). The walk from the root listedWin64and never opened it, so the library pre-scan read the game clean three times, hooking stayed available, and the first session was hooked for 37 s until the 30 s re-scan met ACE's driver — machine-wide, so nothing was turned off (spike-notes.md§19). Neverness To Everness keeps a secondAntiCheatExpert\beside itsHTGame.exe, six levels down, that no walk had seen either. Check 4 now walks the root and then, when the executable lives below it, the executable's own folder — same walk, same reach, its own 4096-entry budget, the same matcher and the same D33 tolerance (ScanGameFolders).ImageDirectorynames the executable's folder and the checks resolve the root from it. Raising the reach instead was measured and rejected: depth 4 still misses NTE's folder, and at depth 5 three installed titles overrun 4096 entries (Yu-Gi-Oh! Master Duel: 41,251), which would refuse them. Measured across the owner's 83 Steam installs, the second walk costs at most 103 entries and newly finds exactly those two folders.What it does not cover. Beyond the above, the residual is an anti-cheat SDK sitting on disk whose service is not installed and whose module is not loaded; checks 1, 2 and 2b already cover the rest. And today the
directories+filesgroups carryonly three tokens67 tokens between them since 2026-09-25, plus any.sysby code (corrected 2026-10-04; documented names, not measured ones), so "check 4 ran" is a much narrower statement than "this game ships no anti-cheat". Widening it needs verified file and directory names — the seed table below deliberately carries "no data yet" rows rather than guesses, because a wrong token fails closed by never firing, which is a silent hole.Every uncertainty refuses, with
Reason::kPreScanFailedrather than a hit: directory absent or unlistable,either bound exceededthe 4096-entry bound exceeded, a name we could not convert, or a reparse point — which is never followed, because a junction can hide anEasyAntiCheat/beneath it. (Corrected 2026-10-13: the DEPTH bound never refused. It is a reach — a folder at the last level is named and not opened, and the walk still reads as complete — which is how Wuthering Waves' ACE was missed; the paragraph above is what answers it.) Unmeasured: how often a legitimate library trips the reparse-point rule or the 4096-entry bound. That needs a real game library, and it is a false-refusal path, so it is recorded rather than assumed benign.
Any check failing ⇒ injection is refused. The UI shows which check fired and offers Tier-2 (ETW) capture instead, which requires no injection — but does require an elevated Agent, so the offer must state that plainly and fall through to Tier 3 rather than appearing to succeed and recording nothing ( records the session unmeasured — Tier 2: its duration, the machine's sensors and the reason — which needs no injection and no elevation; there is no ETW rung and no Tier 3 since 2026-08-28 (corrected 2026-09-27: this sentence outlived the ladder it described by a month).04_CAPTURE §Frame source abstraction)
The payload is checked too, and for a long time it was not
Checks 1–4 all answer "is it safe to be inside this process". None of them
asks what we are putting there, and until 2026-08-04 nothing did: the exported
FlGuardedInject took a caller-supplied dllPath and asked only whether a file
existed at it. Measured through the shipped FrameLedger.Guard.dll with no test
seam, C:\Windows\System32\winmm.dll went into a live process and the verdict
was Allow. That is the standalone injector 20_OPEN_QUESTIONS §S9 refused to
ship, re-exported with a published calling convention — the worst possible shape
under this document's own threat model, because an anti-cheat vendor auditing the
binary would find a general-purpose loader and the rational response is to block
FrameLedger outright.
So there is now a fifth thing the guard establishes before it injects: the
payload resolves into the same directory the guard's own code was loaded from,
compared by file id, through symlinks and 8.3 names and junctions. Refusal is
Reason::kPayloadNotOurs. A seam that cannot answer refuses, exactly as
everywhere else here.
It is deliberately not listed as "check 5". Checks 1–4 are numbered in
05_DETECTION, in the managed mirror and in the reason codes, and renumbering a
gate is how stored values start meaning something else. It is a precondition of
the injection primitive, not a fifth question about the title.
What this does not buy, stated here rather than left to be assumed:
- It proves where the bytes live, not that they are
FrameLedger.Overlay.dll. Whoever can write to that directory can already replace the guard itself, so the check is exactly as strong as the install location — and the project ships unsigned (CLAUDE.md rule 9), so nothing attests to that directory's contents. - It is not atomic with the load: the remote
LoadLibraryWresolves the path again. Same trust base. - Absent is still
kInjectionFailed, notkPayloadNotOurs. A damaged install and a misuse of the ABI are different problems and must not share a reason.
There is no override.
There is one, since 2026-09-21, and it is none of the things this paragraph named(one day; withdrawn 2026-09-22): still no hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch, no global form. If a user disagrees with a specific entry, the path is still a GitHub issue against the rules file, reviewed in public. What exists is below — and since 2026-09-26 (D33), one narrow, evidence-bound exception for anti-cheat that is user-mode throughout, which lets a named family through while every check still runs (§The user-mode exception).
The target must be able to take the Overlay — beta.33 (D78)
The last question before the primitive, after checks 1–4 and the payload's identity passed: can this process take the
Overlay at all? The guard reads it from the target itself (Sources::TargetIsolationFacts, one
PROCESS_QUERY_LIMITED_INFORMATION handle — measured 2026-11-03 to answer both questions, GetProcessMitigationPolicy
needing no more):
| Read | Refusal | Why it cannot work |
|---|---|---|
TokenIsAppContainer |
kTargetAppContainer |
a Microsoft Store app of the UWP kind: the Overlay's shared memory, its Local\ names and the rules file live in the user's session namespace and profile, which an AppContainer cannot open. D78: GDK games are in, UWP apps are out |
ProcessSignaturePolicy: MicrosoftSignedOnly or StoreSignedOnly |
kTargetMitigation |
the Overlay is neither (CLAUDE.md rule 9: unsigned): the remote LoadLibraryW fails |
ProcessDynamicCodePolicy: ProhibitDynamicCode |
kTargetMitigation |
MinHook's trampolines are dynamic code: the Overlay would load and hook nothing |
ProcessUserShadowStackPolicy: strict mode, or BlockNonCetBinaries / BlockNonCetBinariesNonEhcont |
kTargetMitigation |
the Overlay is not marked CET-compatible: refused at load, or a violation ends the game |
ProcessControlFlowGuardPolicy: StrictMode |
kTargetMitigation |
native/CMakeLists.txt H1: measured safe with strict mode off only; a host in strict mode could still __fastfail on the trampolines, which no fault policy can catch (rule 5) |
The policy is the signal, and only the enforcing flags count: an Audit* flag refuses nothing, and
SetContextIpValidation without strict mode is what every CET-compatible process carries (measured: pwsh.exe
0x105). A policy the running Windows does not know answers ERROR_INVALID_PARAMETER (measured) and cannot be in
effect. "Could not tell" refuses — a seam that fails, or none wired — as kProcessUnreadable, the module check's word
for a process it could not read. ctest fl_guard [isolation] holds each refusal through fakes, and two of them against
Windows itself: a child started under "no dynamic code" and "Microsoft-signed images only".
Neither is a finding. Nothing is written to the game's row and no family is named; the session is Tier 2 with the reason, as for a 32-bit game. No game that measured before is refused now: each of these ended as a failed injection, an Overlay that installed no hooks, or a risk of ending the game. It is asked once, before the injection — never by the 30 s re-scan, which runs inside a process the Overlay is already in — and, like the payload check, it is not numbered as a check: it is a precondition of the primitive, not a question about the title.
A GDK game's tree, measured (spike-notes §25, six titles activated through their packages): the chain is
GameLaunchHelper.exe → gamingservicesui.exe → XboxPcTray.exe → the launch executable (→ an Unreal title's shipping
executable), GameLaunchHelper exits first, and its parent is the activator — the user's shell when Play starts it,
which is where the scan set already stops. Every member opened with the guard's rights as a standard user, none is an
AppContainer, none runs under any of the policies above, and no member's module matched a fuzzy fragment or a blocklist
name. So the scan set needs nothing new for these titles; an Xbox title that ships anti-cheat is unmeasured
(20_OPEN_QUESTIONS §G).
What a finding does to the game — owner decision 2026-09-22
The per-game override of 2026-09-21 is withdrawn. It shipped in 0.1.0-beta.3 and beta.4. Its first real use
(D21, below) showed that it could not reach a process an anti-cheat driver protects, and where it could inject it only
exposed the user to the risk its own disclosure described. The owner withdrew it on 2026-09-22: the native entries, the
pipe message, the App's dialog and card, the strings and the five columns of schema 0007 are gone (schema 0008 drops
them). Sessions that ran under it keep guard-bypass= in capture_notes; nothing else remembers it.
What replaced it is the opposite of an override: a finding turns the game's hooking off. The pre-scan has done
this since P2 (RecordGuardBlockAsync: hook_enabled = 0, hook_blocked_reason, hook_prescan_state = 'blocked').
Every later moment the guard can find something writes the same block — a fourth since 2026-09-25:
| Moment | Where | What it sees |
|---|---|---|
| hooking is turned on | AgentCommandHandler.SetHookEnabledAsync |
checks 3 and 4 over the executable and its install root (PreScanGameAsync; check 4 over the executable's own folder until 2026-09-25) |
| a session starts | CaptureSession.SessionAsync, after the gate |
checks 1–4 over the live process, its tree, the drivers, the folder |
| the 30 s re-scan | CaptureSession.DrainAsync, on a SafetyUnhook |
the same, for an anti-cheat that loaded late |
| the Agent's pre-scan of the library | AntiCheatPreScanSweep, under --serve |
checks 3 and 4 over every entry, whether or not its hooking was ever on |
The Agent's pre-scan of the library — owner decision 2026-09-25 (beta.8). Until then the first three moments were
the only ones, and each needs the user to have asked for hooking: a game nobody enabled stayed
hook_prescan_state = 'not_run', so the App could not tell an anti-cheat game from any other. The owner asked for the
hooking part of anti-cheat games to be hidden, which needs to know which they are, so the Agent now asks the advisory
question itself (AntiCheatPreScanHostedService: at start, every 15 s, and at once after UpdateRules):
- Which entries. Every library row not removed, once per rules version and executable — the key is its own
(schema 0010:
hook_prescan_rules_version,hook_prescan_exe_size_bytes,hook_prescan_exe_mtime_ms), so a rules update that names a game already in the library, or a game update that adds anti-cheat, is a re-scan. Skipped: a blocked row (it is never asked again), an executable that cannot be read, an entry whose session is running (that session's own checks are). Change executable clears the key with the state, so the new binary is scanned. - What it writes (
IGameConsentStore.RecordPreScanAsync): a finding about the game is the block above, the consent stamp kept; a pass is'clean'; a scan that could not answer is'unverified', which leaves the toggle alone. It never writes over a block and never adds a row — theUPDATEitself requires both, so a block written between the sweep's read and its write still stands. - What it tells. A
HookingTurnedOffevent (07_IPC) only when the entry's hooking was on: the one case where something the user switched on changed. Every other finding changes only the game's page and card. - What it is not. It gates nothing: every session start still runs checks 1–4 against the live process, whatever
the sweep wrote. It opens no process — the scan reads the executable's path, its install folder and the stores'
files. It holds the guard's lock for one walk at a time (
NativeAntiCheatGuardserialises every native call), so a session start waits for at most the one walk in flight.
Which findings — AntiCheatVerdict.IsFindingAboutTheGame: an anti-cheat named (family non-empty) in the game's
own process (BlockedModule), on its title lists (BlockedExecutable, BlockedStoreId) or in its folder
(AntiCheatDirectory, AntiCheatFile). Not a machine-wide driver or service (BlockedDriver, BlockedService):
a driver running for another game says nothing about this one, so that refuses this session and writes nothing. Not a
scan that could not look, not unusable rules, not the unsigned-module heuristic, not the latch of an earlier block.
What the user sees. The refusal or unhook notice ends with Safety_HookingTurnedOff; the game's page shows the
block (Safety_Blocked_Toggle_Format) with the toggle disabled; capture_notes carry
hooking-turned-off=<reason>/<family>; the Agent's session line carries ; hooking-turned-off; CaptureRefused and
SafetyUnhook carry hookingTurnedOff (07_IPC). CaptureOutcome.HookingTurnedOff is the loop's word for it.
Since 2026-09-25 (beta.8): the block is stored as Reason|Family|Signal so the App says what was found in the user's
language (rows written before keep "Reason: Family Signal" and are shown as stored); the library card says
Anti-cheat instead of Hooking off; and the game's page shows the finding in place of the Hooking card, whose
switch could only be refused, while ui.hide_anticheat_hooking is on — its default (08_UI §Game detail). Off, the
card is back with the finding under its disabled switch. The finding itself is on the page either way (FR-2.2).
What clears it. Nothing, as before: the block outlives Change executable and a re-import (§A game already enabled
can become blocked later). The owner asked for hooking to be turned off when anti-cheat is detected, not for a second
switch. (Still true under D33: an exception is a separate layer over the block, never a clearing of it — §The user-mode
exception.) (And under D55, beta.19: the Agent removes an entry whose game is no longer installed and that has no session,
but never one that carries a block, an exception's grant or a failed trial — the delete's own SQL refuses them
(SqliteGamePrune), so an uninstall is not how a block, a grant or D38's "never again" disappears. Only the user's
Remove… ▸ Delete sessions too deletes such a row, as before.)
D21 stands as a fact. A process an anti-cheat driver protects is SessionEndReason.TargetUnreadable (2026-09-21:
every candidate of that name exists and none can be opened; ELDEN RING under Easy Anti-Cheat on the owner's machine).
Nothing will be built that opens it — that would be defeating another product's protection, which is rule 3. The same
reason covers a game that runs as administrator while the Agent does not.
What did not change. InjectViaLoadLibrary keeps internal linkage in fl_guard.cpp and tools/chokepoint-check.ps1
still finds the injection primitives in exactly that file and the evasion primitives nowhere. IAntiCheatGuard is back
to four methods (NoSecondMatcherTests). FloorFamilies is untouched.
The user-mode exception — owner decision 2026-09-26 (D33)
Why it exists. The beta.8 library sweep turned hooking off for GIRLS' FRONTLINE 2: EXILIUM on a documented,
unmeasured rule — NetEase Yidun, AntiCheatFile NEP2.dll — after FrameLedger had measured that game hooked (three
normal Tier-1 sessions in the owner's ledger, 474,143 frames). The owner asked for a way to keep measuring a game like
that, and chose, against the rule this document had kept since 2026-09-22 and with that rule quoted back to them, an
exception the user grants per game, bound to evidence, and only for anti-cheat that is user-mode throughout. The
reasons D22 withdrew the override are answered one by one: it "did nothing where it was wanted" — an exception is only
offered where FrameLedger has already measured the game hooked (D38 below: the measurement now comes under the grant,
as its trial); it "only exposed the user to the risk its own disclosure described" — that risk stands, and the disclosure
says so, including that a ban can arrive days later and that FrameLedger cannot know.
Amended 2026-10-03 (owner decision D38): the evidence comes after the grant, as a trial. The owner deleted their ledger and found GIRLS' FRONTLINE 2 "Not eligible: 0 successful hooked session(s), two are needed" — for good. The rule below was a catch-22 for every game it could ever meet again: since beta.8 the library sweep blocks a game the moment it is added, a blocked game is never hooked without a grant (
CaptureSessionsends it to Tier 2 before the resolver), so it can never earn the two sessions, and a reset ledger loses the ones it had. D33's evidence was reachable only for a game measured before its block, and only while those rows lasted. Asked with that, the owner chose: a grant needs no session; the first two hooked sessions under it are a trial; any of them that does not go well ends the exception for good (games.ac_exception_trial_failed_at, schema 0017, which nothing clears). Every other condition is unchanged.
What may be excepted — all of it must hold:
- every finding about the game is
BlockedModule,AntiCheatFileorAntiCheatDirectoryof one family; - that family's whole footprint is user-mode — no
driversentry, noservicesentry and no*.sysamong itsfiles, in the compiled floor or the rules file (fl::guard::FamilyIsUserModeOnly). The floor cannot be shrunk, so data can make a family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain, FredaikisAntiCheat and Roblox Hyperion (Hyperion added 2026-10-04: its rows are one module and one file; its only title is on the executable list, so it is never excepted in practice); Easy Anti-Cheat, BattlEye, ACE, NetEase Anti-Cheat, mihoyo protect, Vanguard, Ricochet and every other family carry a driver or a service and are never excepted; - no
*.sysanywhere in the install tree (within check 4's reach: three levels under the install root and, since 2026-10-13, under the executable's own folder) — the kernel-driver rule (D30) is never excepted, whichever family a driver belongs to (so Aniimo, which unpacksNEPKernel.sysbesideNEP2.dllon its first run, stays blocked); - the game is on no title list (
BlockedExecutable,BlockedStoreId— the notorious titles are there by design); the ledger holds at least two successful Tier-1 sessions of the game: hooked, frames recorded,Since D38 (2026-10-03): no session is needed — and no exception of the game has ever ended during its trial (exit_status = normal(which since beta.8 includes End task's exit code 1 and a user's stop), never crashed, never unhooked for safety.ac_exception_trial_failed_atis NULL).
Never excepted, whatever the user ticked: a machine-wide BlockedDriver or BlockedService, the fuzzy tier
(SuspiciousUnsigned), a scan that could not look or finish, unusable rules, TargetUnreadable (D21), a 32-bit target,
the kill switch, and a Vulkan target (the implicit layer's own self-scan stays strict).
How the guard takes it. The four evaluating ABI entries carry toleratedFamilies — a NAME, never evidence
(fl_guard_abi.h). The guard resolves it against its own rules (ResolveTolerance), keeps only a user-mode family,
runs every check, lets that family's modules, files and folders through and keeps scanning past them, so a second
family, a suspicious module or a .sys further in still refuses. A pass that let something through is
kAllowedUserModeException (reason 28, the slot the withdrawn bypass left) with the family and the signal; the session it
starts is marked with them.
How the Overlay takes it. The Overlay stops observing when a floor module loads after injection, so the Agent
publishes the exception's family names in Local\FrameLedger.Tolerate.<pid> (fl_tolerance.h) before it asks the guard
to inject, and the Overlay's init thread reads them once, before its loader detour exists — resolving each against its
own compiled floor and honouring only a user-mode family. A mapping that names anything else tolerates nothing, and the
Agent's 30 s re-scan keeps judging every other signal.
What ends it. A new finding outside the excepted family at any of the four moments above writes the block as before and revokes the exception; a session under it that crashes, is unhooked for safety or is stopped by the Overlay's in-process floor stop revokes it; an executable change ends it with the consent it shared a fingerprint with; turning the option off suspends every exception. The block itself is never cleared — the exception is a separate layer over it, and the finding stays on the game's page (FR-2.2).
The trial (D38). Until two sessions under a grant have succeeded — hooked, stored, frames recorded, normal
(ISessionRepository.CountSuccessfulUnderGrantAsync: under that family, started at or after the grant) — the grant is in
its trial, and the App says so ("trial: 1 of 2"). During the trial any end of the list above ends the exception
for good, and so does a stored hooked session that recorded no frame or did not end normally
(UserModeExceptionLapse.TrialFailed, decided by UserModeExceptionLapsePolicy when the recorder stores the row): the
end is recorded with its own reason and ac_exception_trial_failed_at is set. While it is set the sweep writes the game
not eligible, the Agent refuses a grant (Refused.reason = TrialFailed, the signal is when) and the store refuses one in
SQL; withdrawing, a game update, Change executable and a twin merge all keep it. A session too short to be stored, or
one that was never hooked, is not judged by its frames or its exit — it neither counts toward the two nor fails the
trial that way — but an end of the list above still ends the exception for good during the trial: a crash while
hooked, however short, or a finding about the game at the start. After the trial, an end is what it was under
D33: the exception may be made again once the sweep finds the game eligible. Deleting sessions can only lengthen a trial
— the count is read, never stored as a grant's own fact.
What it is not. Not a bypass of a live refusal, not a global switch (a Settings option off by default enables the list,
and the user ticks each game), not reachable from the command line, and not evasion: the DLL stays LoadLibraryW-loaded,
named and visible (rule 3). InjectViaLoadLibrary still has internal linkage in fl_guard.cpp; tools/chokepoint-check.ps1
is unchanged.
Built in beta.9. PR-1: the guard's tolerance and the Overlay's channel. PR-2: the Agent — the option
(hooking.usermode_ac_exceptions, off), the sweep's eligibility pass (a tolerant pre-scan keyed on the rules, the
executable and the block; the session count every pass), the SetAntiCheatException command (the Agent gathers the
facts itself; the store applies the rule), the gate's one branch with the channel published before the request, the
re-scans naming the family, the session's mark, and every end (UserModeExceptionLapse) — schema 0014. PR-3: the
option and the list in Settings, the versioned disclosure (Safety_Exception_*, AntiCheatExceptionDisclosure), the
game page's exception card and its usable switch under an exception in force, the marks, and the legal text
(Disclaimer §2A 2.7, EULA 1.3, the accuracy block, SECURITY.md) — 08_UI §Games.
D38 in beta.11 (2026-10-03): UserModeExceptionRules.TrialSessions replaces RequiredSessions; eligibility is the
guard's answer and the trial mark; ac_exception_sessions is the trial's progress; schema 0017
(ac_exception_trial_failed_at); Refused.reason TrialFailed replaces TooFewSessions; the disclosure is
ac-exception-dialog/2 (its Why names no count, a new Trial paragraph); the Settings list shows only games it can act
on; and a sweep that cannot read the executable answers "could not verify" instead of leaving the row "checking" for ever.
Legal text: Disclaimer §2A 2.9, EULA 1.4, the accuracy block, SECURITY.md, LIMITATIONS.md.
The floor data cannot remove
There was a local bypass, and this paragraph is the reason it no longer works (§S21, fixed 2026-08-04). It is recorded rather than quietly patched, because the shape recurs: the sentence above was enforced against every channel anyone had thought to check, and the gate's own data file was not one of them.
Two facts combined into an override:
- The rules path was built from
_dupenv_s("LOCALAPPDATA"). The CRT environment is inherited from whoever launched the process, and in launch mode that is a shortcut, a.bat, or the Steam launch-option wrapper (04_CAPTURE§Launch mode). One variable chose the hard gate's only input, for one run. - The completeness check validated that three family names existed in the
right groups and never read their
values.
So a twelve-line file naming Easy Anti-Cheat/modules, BattlEye/modules and
Riot Vanguard/drivers with values that match nothing parsed as valid, and the
guard returned Allow on a machine running Vanguard. No admin, no write to our
install directory, nothing left behind.
The fix is §S8's mechanism applied to data instead of to symbols. A token
that escapes can be ignored; a symbol that does not exist cannot be called; a
family that data cannot remove cannot be bypassed. fl::guard::FloorFamilies
carries the blocklist inside the binary, ParseRules seeds it before it
reads a byte of the file, and nothing merges, rewrites or removes it. The file
may add families and values. It can take nothing away.
Three consequences worth stating rather than discovering:
-
Path resolution is now
SHGetKnownFolderPath, and that is a narrowing, not a guarantee. A user can still move their own Local AppData. What is gone is the per-launch, per-process vector. The floor is what makes the residual harmless. -
The completeness check still runs over the file's families only. Checking the merged set would make it a gate that cannot fail, since the floor satisfies it by construction — so an empty or incomplete rules file still refuses, and still says so.
-
The floor is GENERATED from
rules/detection-rules.jsonat build time (tools/gen-ac-floor.ps1), so it is the whole shipped blocklist plus the heuristic's name fragments.This paragraph used to read "the floor is deliberately three families, not the whole blocklist", kept small because a larger hand-written table would be a second blocklist drifting from the data. Measured, that bought 4 of the seed's 22 values, 2 of its 5 groups and none of its 5 fragments — so it closed "a crafted file makes the guard allow everything" and left open "a crafted file removes most of the blocklist". Generating it removes the objection that kept it small: a table derived from the data cannot drift from it.
trustedSignersis deliberately excluded, because flooring an ALLOW-widening list has the wrong polarity.A file family identical to a floor entry is deduplicated, so the file's own budget is half
kMaxFamilies—tools/rules-validate.ps1checks that worst case, and ctestfl_rules_budgetasserts the generated floor reproduces the shipped seed exactly. -
The fuzzy tier is floored too, which is what stops a rules file with no
heuristicblock from making it silently cease to exist. That was20_OPEN_QUESTIONS§S19(d), and a floor closes it without the newParseResultcause that entry proposed — which would have madekRulesIncomplete's signal a lie and drivenlayer.cppto machine-wide inert passthrough.
Blocklist seed
Matching is case-insensitive. This table shows the literal tokens the data
carries, not glob patterns — rules/detection-rules.schema.json rejects *
in a token outright, so a maintainer copying EasyAntiCheat*.dll out of an
earlier version of this table produced an entry that was matched literally and
therefore never fired. A silent hole in the blocklist, created by its own
normative documentation. Write tokens here exactly as the data must hold them.
| Family | Group | Match | Tokens | Added |
|---|---|---|---|---|
| Easy Anti-Cheat | modules |
prefix | EasyAntiCheat, EasyAntiCheat_EOS |
seed |
| Easy Anti-Cheat | drivers |
prefix | EasyAntiCheat — machine-wide refusal (check 2) |
seed |
| Easy Anti-Cheat | directories |
name | EasyAntiCheat, EasyAntiCheat_EOS |
seed; EasyAntiCheat_EOS 2026-09-25 |
| Easy Anti-Cheat | services |
name | EasyAntiCheat, EasyAntiCheat_EOS, EasyAntiCheat_EOSSys |
seed |
| Easy Anti-Cheat | files |
name | EasyAntiCheat_EOS_Setup.exe, EasyAntiCheat_Setup.exe, EasyAntiCheat_x64.dll, EasyAntiCheat_x86.dll, EasyAntiCheat_EOS.sys, start_protected_game.exe, eac_server64.dll |
2026-09-25 |
| BattlEye | modules |
prefix | BEClient, BEService |
seed |
| BattlEye | drivers |
exact | BEDaisy.sys — machine-wide refusal (check 2) |
2026-09-25 |
| BattlEye | directories |
name | BattlEye |
seed |
| BattlEye | services |
name | BEService, BEDaisy |
2026-09-25 |
| BattlEye | files |
name | BEService.exe, BEService_x64.exe, BEClient.dll, BEClient_x64.dll, BEDaisy.sys |
2026-09-25 |
| Denuvo Anti-Cheat | modules |
prefix | denuvo |
seed |
| Denuvo Anti-Cheat | drivers |
exact | denuvo-anti-cheat.sys — machine-wide refusal (check 2) |
2026-09-25 |
| Denuvo Anti-Cheat | services |
name | denuvo-anti-cheat |
2026-09-25 |
| Denuvo Anti-Cheat | files |
name | denuvo-anti-cheat.sys, denuvo-anti-cheat-runtime.dll, denuvo-anti-cheat-update-service.exe |
2026-09-25 |
| nProtect GameGuard | modules |
prefix | GameGuard, npgg, GameMon |
seed |
| nProtect GameGuard | directories |
name | GameGuard |
2026-09-25 |
| nProtect GameGuard | services |
name | npggsvc |
2026-09-25 |
| nProtect GameGuard | files |
name | GameGuard.des, GameMon.des, GameMon64.des, npggNT.des, npggNT64.des, npsc.des |
2026-09-25 |
| Xigncode3 | modules |
prefix | xhunter |
seed |
| Xigncode3 | modules |
exact | x3.xem |
2026-09-25 |
| Xigncode3 | drivers |
prefix | xhunter — machine-wide refusal (check 2) |
2026-09-25 |
| Xigncode3 | directories |
name | XIGNCODE, XIGNCODE3 |
2026-09-25 |
| Xigncode3 | services |
name | xhunter1 |
2026-09-25 |
| Xigncode3 | files |
name | x3.xem, xhunter1.sys |
seed; xhunter1.sys 2026-09-25 |
| PunkBuster | modules |
prefix | PnkBstr, pbcl, pbsv |
seed |
| PunkBuster | drivers |
prefix | PnkBstrK — machine-wide refusal (check 2) |
2026-09-25 |
| PunkBuster | directories |
name | PunkBuster |
2026-09-25 |
| PunkBuster | files |
name | pbsvc.exe, PnkBstrA.exe, PnkBstrB.exe, pbsv.dll, pbcl.dll, pbag.dll |
2026-09-25 |
| FACEIT | modules |
prefix | faceit |
seed |
| FACEIT | drivers |
exact | FACEIT.sys — machine-wide refusal (check 2) |
2026-09-25 |
| FACEIT | services |
name | FACEIT, FACEITService |
2026-09-25 |
| ESEA | modules |
prefix | esea |
seed |
| ESEA | drivers |
prefix | ESEADriver — machine-wide refusal (check 2) |
2026-09-25 |
| ESEA | services |
name | ESEADriver2 |
2026-09-25 |
| Riot Vanguard | drivers |
exact | vgk.sys — machine-wide refusal (check 2) |
seed |
| Riot Vanguard | services |
name | vgc, vgk |
seed; vgk 2026-09-25 |
| mihoyo protect | modules |
prefix | mhypbase |
2026-09-25 |
| mihoyo protect | drivers |
prefix | mhyprot, HoYoKProtect — machine-wide refusal (check 2) |
seed; HoYoKProtect 2026-09-25 |
| mihoyo protect | services |
name | mhyprot2, mhyprot3, HoYoKProtect |
2026-09-25 |
| mihoyo protect | files |
name | mhypbase.dll, mhyprot2.sys, mhyprot3.sys, HoYoKProtect.sys |
2026-09-25 |
| Anti-Cheat Expert | modules |
prefix | SGuard, AntiCheatExpert |
2026-09-25 |
| Anti-Cheat Expert | modules |
exact | ACE-Base64.dll |
2026-10-13 |
| Anti-Cheat Expert | drivers |
exact | ACE-BASE.sys, ACE-ADVT.sys, ACE-GAME.sys — machine-wide refusal (check 2) |
seed |
| Anti-Cheat Expert | drivers |
exact | ACE-CORE.sys — machine-wide refusal (check 2) |
2026-10-13 |
| Anti-Cheat Expert | directories |
name | AntiCheatExpert, AceAntibotClient |
2026-09-25 |
| Anti-Cheat Expert | services |
name | AntiCheatExpert Protection, AntiCheatExpert Service, ACE-BASE |
seed; ACE-BASE 2026-10-13 |
| Anti-Cheat Expert | files |
name | PGameProtectDriver_X64.sys, SGuard64.exe, SGuardSvc64.exe |
seed; SGuard64.exe, SGuardSvc64.exe 2026-09-25 |
| Anti-Cheat Expert | files |
name | ACE-BASE.sys, ACE-CORE.sys, ACE-Base64.dll, ACE-Service64.exe, ACE-Setup64.exe (measured in Wuthering Waves' folder) |
2026-10-13 |
| EA AntiCheat | modules |
prefix | EAAntiCheat |
2026-09-25 |
| EA AntiCheat | drivers |
exact | EAAntiCheat.sys — machine-wide refusal (check 2) |
2026-09-25 |
| EA AntiCheat | files |
name | EAAntiCheat.Installer.exe, EAAntiCheat.GameServiceLauncher.exe, EAAntiCheat.GameServiceLauncher.dll |
2026-09-25 |
| NetEase Anti-Cheat | modules |
prefix | NeacSafe, NeacClient |
2026-09-25 |
| NetEase Anti-Cheat | drivers |
prefix | NeacSafe — machine-wide refusal (check 2) |
2026-09-25 |
| NetEase Anti-Cheat | files |
name | NeacSafe64.sys, NeacSafe64_ex.sys |
2026-09-25 |
| NetEase Yidun | modules |
exact | NEP2.dll |
2026-09-25 |
| NetEase Yidun | files |
name | NEP2.dll |
2026-09-25 |
| Nexon Game Security | modules |
prefix | BlackCipher, BlackCall, BlackXchg |
2026-09-25 |
| Nexon Game Security | drivers |
exact | BlackCat64.sys — machine-wide refusal (check 2) |
2026-09-25 |
| Nexon Game Security | directories |
name | BlackCipher |
2026-09-25 |
| Nexon Game Security | files |
name | BlackCipher.aes, BlackCipher64.aes, BlackCall.aes, BlackCall64.aes, BlackCat64.sys |
2026-09-25 |
| TenProtect | modules |
prefix | TP3Helper, TenSafe |
2026-09-25 |
| TenProtect | drivers |
exact | TesSafe.sys — machine-wide refusal (check 2) |
2026-09-25 |
| TenProtect | files |
name | TP3Helper.exe |
2026-09-25 |
| AhnLab HackShield | modules |
prefix | EhSvc, HShield, HSInst |
2026-09-25 |
| AhnLab HackShield | directories |
name | HShield |
2026-09-25 |
| AhnLab HackShield | files |
name | HSInst.dll, EhSvc.dll |
2026-09-25 |
| Anybrain | modules |
exact | anybrainSDK.dll, Cerebro.dll |
2026-09-25 |
| Anybrain | files |
name | anybrainSDK.dll, Cerebro.dll |
2026-09-25 |
| Roblox Hyperion | modules |
exact | RobloxPlayerBeta.dll |
2026-09-25 |
| Roblox Hyperion | files |
name | RobloxPlayerBeta.dll |
2026-09-25 |
| EQU8 | modules |
prefix | equ8 |
2026-09-25 |
| EQU8 | drivers |
prefix | EQU8_HELPER — machine-wide refusal (check 2) |
2026-09-25 |
| EQU8 | files |
name | equ8_conf.json |
2026-09-25 |
| Activision Ricochet | drivers |
exact | randgrid.sys, brynhildr.sys, atvi-brynhildr.sys — machine-wide refusal (check 2) |
2026-09-25 |
| Activision Ricochet | services |
name | atvi-randgrid_sr, atvi-randgrid_msstore |
2026-09-25 |
| Activision Ricochet | files |
name | randgrid.sys |
2026-09-25 |
| FredaikisAntiCheat | directories |
name | FredaikisAntiCheat |
2026-09-25 |
| Valve VAC | — | — | blockedStoreIds, whose half of check 3 cannot be calledAllow, spike-notes.md §13 — the gap these lists close.) |
2026-09-25 |
| CrackProof | — | — | Per-title list since 2026-10-03 (check 3, rules 2026.10.1): 3 Steam app ids, no executables. Its kernel driver loads from System32 under a numbered name, so no module, driver or file of the game's own can name it — this row stays a dash on purpose, like VAC's. |
2026-10-03 |
The "no data yet" rows are deliberately kept rather than deleted. An admitted
gap is reviewable; a deleted row is invisible. Activision Ricochet's was one of them — it has data since
2026-09-25 (below above); VAC's stays until its per-title route exists VAC's became per-title lists the same day,
13 Steam ids and 8 executables (corrected 2026-10-04).
Expanded 2026-09-25 (owner: "as many anti-cheats and as strict as possible"). Eleven families became twenty-two and 19 entries became 74: EA AntiCheat, Activision Ricochet, NetEase Anti-Cheat, NetEase Yidun, Nexon Game Security, TenProtect, AhnLab HackShield, EQU8, Anybrain, FredaikisAntiCheat and Roblox Hyperion are new, and most existing families gained the groups they lacked — BattlEye's
BEDaisy.sys, FACEIT's and ESEA's drivers,HoYoKProtect.sys(which themhyprotprefix never matched), Xigncode3's driver and service, Denuvo's driver. Every new token is DOCUMENTED, not measured: the sources are SteamDB'sFileDetectionRuleSets(MIT), the vendors' own support pages (Activision RICOCHET, EA, FACEIT, BattlEye), LOLDrivers and DRML, named per entry in the data'snote. The ACE rule above still holds — a blocklist may over-cover and must never under-cover, and a wrong token fails closed by never firing — so an unmeasured token is admitted, labelled, and left for a real title to confirm.kMaxFamilieswent 64 → 256 with it (2 × 74 no longer fitted).Three services are deliberately absent, and the reason is the RUNNING rule above: a service counts while it runs, and a service that runs outside play refuses every session on the machine.
EAAntiCheatServicecan be set to start automatically; PunkBuster'sPnkBstrAruns at every boot once installed; Denuvo's update service runs apart from the game. Each family is caught through its driver, its modules or its files instead.New
modulesrows are appended, never inserted. The Overlay'sLoadLibrarydetour reports a 1-based index into this group's order (FlWriterState.earlyStopFamily→sessions.early_stop_family), so a row inserted above an existing one would change what indexes already stored mean.
Anti-Cheat Expert was added 2026-08-04 from measurement, not from reading.
ACE-BASE.sysandACE-ADVT.syswere found installed underSystem32\driverson the dev machine, and the serviceAntiCheatExpert Protectionregistered, by a title whose install also ships its own kernel driver (PGameProtectDriver_X64.sys) inside the game tree. None of it matched anything: the whole family was absent from this table and from the data, so a kernel-level anti-cheat was present on the machine and every check returnedAllow.ACE-GAME.sysandAntiCheatExpert Serviceare documented siblings and are unmeasured — recorded as such, because a blocklist may over-cover and must never under-cover.The
Easy Anti-Cheatdrivers row was added at the same time and for a sharper reason:EasyAntiCheat_EOSSyswas measured Running as a kernel driver during a live EAC session and matched nothing indrivers. The refusal came from the service check instead. A family caught through only one of five groups is one rename away from being missed, and the fact that something else fired is exactly what makes such a gap invisible.
A prefix must be at least 4 characters and must not shadow a system module. This table used to write PunkBuster as
pb*.dll; the data correctly narrows it toPnkBstr/pbcl/pbsv, andtools/rules-validate.ps1now makes the narrow form mandatory. A too-short prefix does not fail open — it refuses every title, which is how a user ends up hunting for the override that CLAUDE.md rule 2 says does not exist.
The list is data, versioned in detection-rules.json, expandable without a release a code change, still delivered by a release (§S20 feed half — corrected 2026-10-04). Unknown-but-suspicious modules (filename containing one of the nameFragments — today anticheat, antitamper, guard, protect — plus unsigned-by-known-vendor) produce a warn-and-refuse with a "report this to us" link rather than silently allowing.
Three corrections to that sentence, all recorded in §S19; one is now closed. It listed four fragments while the data carried five (
gameguardwas missing here, and nothing in CI cross-checks this list against the file).gameguardcould not fire — the match is a case-insensitive substring andguardis a substring ofgameguard, so the shorter token always won first.§S19(a) closed 2026-08-05 by removing
gameguardfrom the data, which is why the list above is four again — this time matching the file. Nothing is lost: nProtect GameGuard has its own named module family (GameGuard,npgg,GameMon), so the fragment was redundant twice over, andguardremains as the fuzzy backstop.rules-validatenow fails when any fragment contains another, so the list cannot grow a rule that cannot fire — and, more to the point, a future removal ofguardis now visibly a removal rather than somethinggameguardappears to survive.And warn-and-refuse is not configurable: the schema requires an
actionfield, but no code reads it; the policy is hardcoded infl_guard.cpp. The behaviour described here is what happens, but not for the reason the sentence implies. (§S19(c) — still open, and costing it honestly means first deciding whether a non-refusing action may exist at all, which CLAUDE.md rule 2 answers no.)
The signer comparison uses the certificate subject's O= field, not CN=
(anticheat.heuristic.signerField, a schema const). Measured 2026-08-02 on
Windows 11 26300: every WHQL-signed binary on the machine — including the
NVIDIA display driver itself — carries
CN='Microsoft Windows Hardware Compatibility Publisher', which is not a vendor
name, while O='Microsoft Corporation'. Matching on CN would therefore make
the entire driver stack read as untrusted, and combined with the guard and
protect name fragments above that is a live false-refusal path, not a
theoretical one. A signature that is absent, invalid, or simply could not be
checked stays untrusted and refuses — that direction is deliberate.
Wired 2026-09-06, the EMBEDDED half only, under a compiled-in bound (
20_OPEN_QUESTIONS§S19(b), row G1: the CI leg and the owner's adapters-disabled leg both left every verdict unchanged).Sources::ModuleSignerOrganisationverifies a fragment-matching module's embedded Authenticode signature withWinVerifyTrustunderWTD_REVOKE_NONE | WTD_CACHE_ONLY_URL_RETRIEVAL— no CRL or OCSP fetch, measured rather than assumed — and only then reads the subjectO=. The guard trusts it only if the organisation is on the rules file'strustedSignersand on the list compiled into the binary (IsCompiledTrustedSigner): the rules file may narrow that list and may never widen it, so a rules push cannot widen the hard gate — the boundary of what the gate trusts is code, as it is for the launcher list. A trusted module keeps the scan looking; it never stops it, so an untrusted module loaded after it is still judged. It applies to the injection target as well as to its ancestors — a game that loads a Microsoft-signed key-protection provider is the false refusal this half exists to remove. Fail-closed rows: no embedded signature (catalog-only system binaries such asmskeyprotect.dll— theCryptCATAdmin*half is deferred with its own rationale), an invalid signature, an unreadableO=, a null path, a null or failing seam, an organisation on one list but not the other — every one is untrusted and refuses. Cost: ~2–4 ms per verified module, reached only on a fragment hit, inside the 30 s loop.
During a session
Re-run every pre-injection check every 30 s, for every Tier-1 session — injected or layered.
A refused re-scan of a game that has already exited is that exit (owner decision D48, beta.14). When the re-scan refuses only because it could not read the game's tree (
ProcessUnreadable,ModuleScanFailed,ProcessTreeUnavailable— never a finding) and the game itself has exited by the time the session concludes, the session ends asTargetExited, its exit code deciding normal or crashed, withscan_at_exit=<reason>in its notes (Application.Capture.ExitScanRelabel). The stop was still published to the Overlay — the game it would have stopped is gone. A finding, any refusal while the game still runs, and a refusal of another check (drivers, services, the pre-scan) are a safety unhook exactly as before.CaptureSessionTests.AnUnreadableRescanOfAGameThatHasExited…and its three refusing neighbours.
This said "both the module scan and the driver scan" until 2026-08-05, and the loop runs four checks, not two (
20_OPEN_QUESTIONS§S23-4).FlGuardEvaluate→EvaluateImplrunsCheckDrivers,CheckServices,CheckModulesandCheckStaticPreScan. The two omitted from this sentence are not incidental:servicesis the only tier ever measured firing on real anti-cheat (spike-notes.md§13 — a live Easy Anti-Cheat session was caught by it, not by the module or driver tiers), and the static pre-scan is the only one that touches the filesystem, so it dominates what the loop costs and any argument about shrinking the 30 s window (§S6) has been reasoning about the cheap half.The wording is now "every pre-injection check" rather than a list, so the sentence cannot go stale again the next time a check is added. The list of checks lives in §Pre-injection checks above, once — including its ⚠ that check 3's store-id half cannot be called. The re-scan inherits that gap rather than closing it.
This clause was corrected on 2026-08-05 and it is worth saying why it went wrong. It read "including its ⚠ that check 3 is unwired … one of the four documented ones still does not [run]". #52 rewrote the ⚠ it points at, three hundred lines above, and left this sentence citing it — the restate-in-two- places failure this very entry was closed for, reintroduced by the closure. Deferring to another section is not the same as not restating it: a pointer that paraphrases what it points at is a copy.
Two things were wrong, not one. Check 3's executable half runs; and "four documented" undercounts, because 2b (
services) is a documented check and is the only tier ever measured firing on real anti-cheat. Five run.
Scoping this to "hooked" sessions was a real gap. Everything about the re-scan was written as "during a hooked session" / "loading after injection", and
04_CAPTURE§Session recorder reachesCapturingonly throughInjecting— a state a Vulkan session never enters, because the layer is loaded by the Vulkan loader and nothing is injected. Read literally, the most important runtime behaviour in the capture layer was not specified to run at all for Vulkan titles. It applies to any session capturing at Tier 1.The Agent publishes proof it ran, not proof it is alive.
guardTickscounts completed evaluations (07_IPC§Protocol rules); a capture side that sees it stop advancing stops observing. A timer-driven heartbeat would have let the capture side keep going precisely because the guard loop had died. Anti-cheat loading after injection (some titles load it late, or the user launched a multiplayer mode from a single-player menu) ⇒ clean unhook on detection, session finalized asexit_status = unhooked_safety, prominent UI notice. This is the single most important runtime behavior in the whole capture layer.
The driver scan is not optional here, and it used to be missing. This section said "the module scan" only. But a machine-wide anti-cheat driver can start after injection — the user opens Valorant while another title is hooked — and check 2 above requires refusal for all titles while such a driver is running. A module-only re-scan looks inside the hooked game and would never see it. The runtime loop must repeat every pre-injection check whose subject can change mid-session, not just the one whose subject is the game.
Be honest about the window. A 30 s poll means anti-cheat can be loaded for up to 30 s before we react — the unhook is immediate once detected, not immediate in absolute terms. Consent and disclaimer wording must say "within 30 seconds", never "immediately" (legal/DISCLAIMER.md §2). Whether to shrink the window, or to detect the load directly via the LoadLibrary hook 17_HOOK_ENGINE §DLL entry specifies for lazily-loaded graphics DLLs, is 20_OPEN_QUESTIONS §S6.
The in-process half exists since 2026-09-06 (P1 item 1), and the sentence above stays true because of what it does NOT cover. The Overlay's
LoadLibrarydetour compares every module the loader maps mid-session against the compiled floor's MODULE families — the exact prefix names, and nothing else — and stops the Overlay from inside on a match (FL_STATUS_STOPPED_BLOCKLISTED;17_HOOK_ENGINE§DLL entry step 3), within one present or one watchdog iteration. That is the same set the Agent's guard matches by name. The fragment tier and the signer tier are not in the detour, on purpose: a substring scan is not allocation-free in a hook body under the loader lock, andWinVerifyTrustfrom inside a game process is out of the question — so a module the floor knows only by a fragment, or only by its signer, is still caught by this host's 30 s scan and by nothing sooner. The disclosure therefore does not change: "within 30 seconds" remains the promise; the exact-name case is now usually much faster, and the report says which happened (EARLY STOPnaming the family, or the host's own stop). Modules loaded before the Overlay attached are the pre-injection scan's, as always. The detour supplements the poll; it replaces nothing (§S6's own ruling).
This sentence used to say the hook "already exists and is currently unused", which was false. Corrected 2026-08-04: the Overlay installs no hooks at all —
dllmain.cppexports one function and nothing in the tree callsMH_CreateHookoutside a probe. (Overtaken 2026-09-06: P1 installed the hooks and theLoadLibraryExWdetour above; the Overlay exports four functions. Marked 2026-10-04.) §S6 is therefore downstream of the whole P1 hook layer, not "the cheapest available improvement to the most important behavior in the product". A reader planning work off this paragraph was being told a mechanism was sitting there ready.
Elevated / protected targets
If OpenProcess with the needed rights fails (protected process, higher integrity), do not escalate creatively. Report "cannot attach" and offer Tier-2. Never attempt to acquire privileges beyond running the Agent elevated at the user's explicit request.
The explicit request exists since beta.10 (owner decision D34, 2026-09-27): the admin mode. An option off by default, turned on through a versioned disclosure (
Safety_AdminMode_*,agent-admin-dialog/2(/1until 2026-11-11, when Advanced metrics widened what the option adds — D101)) that states what it adds, what it does not change, how Windows asks and the risk of a per-user install; then Windows asks at every start of the Agent (01_ARCHITECTUREADR-9). What it does NOT do, each held by code rather than by this paragraph:
- It clears no finding and opens no protected process. The guard runs exactly as unelevated: the driver scan asks
NtQuerySystemInformation, and a process an anti-cheat driver protects staysTargetUnreadable(D21) — elevation turns "could not look" into an answer only where Windows would give any administrator one.- It enables no privilege. An elevated token holds
SeDebugPrivilegeandSeLoadDriverPrivilegedisabled and they stay so:AdjustTokenPrivileges,RtlAdjustPrivilege,EnterDebugModeand the debug privilege's name may not appear undersrc/(tools/chokepoint-check.ps1), andPrivilegeFootprintTestsasserts on the elevated CI runner that opening targets and LibreHardwareMonitor's CPU group enabled none.- It elevates no game. A game started from FrameLedger gets the desktop shell's token (
UnelevatedProcess); with no shell to take one from, the launch is refused with that reason (Launch_Error_1400), never made elevated instead.- It is not silent. Every start asks; a start that was declined serves as a standard user and says so; the prompt answered by another account ends that Agent before it touches anything (exit 11).
The residual risk is stated to the user, not solved: FrameLedger installs per user and unsigned, so a program running under the account could replace its files and be run as administrator the next time the user accepts the prompt.
User-facing consent
Enabling hooking is a per-game action, gated by a one-time dialog per game that states, in plain language:
- what gets injected and why (measuring the real render resolution, upscaler, frame generation and ray tracing state — which passive measurement cannot do accurately),
- that anti-cheat systems may flag or ban accounts, and that FrameLedger refuses to inject where it detects one but cannot guarantee it knows every anti-cheat,
- that the user is responsible for the terms of service of the games they play,
- what happens if they do not enable it: FrameLedger still records the session — its start,
end and duration, and whatever hardware telemetry the machine provides — and every
frame-derived value on that session reads
N/A(FR-4.9). That is Tier 2. It is what every game gets until it is individually enabled, and it needs no injection and no elevation.
REWRITTEN 2026-08-28, and the old bullet is worth reading before the new one. It said "that Tier-2 (no injection) capture is available and is the default for anything the guard is unsure about." It bundled two claims. "Is the default" is now unconditionally true and structurally so. "Is available" was false in the sense a reader takes from a frame-time tool's consent dialog — Tier 2 captures a clock and a sensor poll — and it was conditional on an elevation state the reader could not evaluate.
THE DIALOG STATES BOTH OPTIONS AT THE SAME GRAIN AND RECOMMENDS NEITHER. This is normative, because it will not survive translation review otherwise. Tier 1's data and Tier 2's data are each enumerated concretely; "limited", "reduced" and "degraded" are not acceptable descriptions of Tier 2, and neither is any sentence describing what the user loses by declining. The dialog does not describe Tier 2 as temporary or pending a better mechanism — a user deciding today decides against what exists today.
09_I18Nreviews this as legal text; a locale that softens either side fails.Removing the fallback makes declining more costly, and that is exactly why the wording gets more careful rather than more persuasive. Consent is informed when the cost of declining is stated, not when it is flattering — and naming a concrete cost next to a request to accept is textbook framing, so the rule above exists to stop this section drifting into it.
Consent is stored per game (games.hook_consent_at), stamped by the Agent, never supplied by a client (07_IPC §The pipe is not a trust boundary). Wording lives in .resx and is reviewed with the same care as the legal documents.
Built 2026-09-13 (P3 PR-4). The dialog is
FrameLedger.App'sConsentPromptover WPF UI'sContentDialog, its textFrameLedger.Shared'sSafety_Consent_*family and nothing else: the intro (which says it recommends neither choice), what is injected and why, Tier 1 and Tier 2 as two paragraphs of the same shape (each enumerating what the session records; Tier 2 is described by what it does, never as less), the anti-cheat statement including the 30 s unhook, the terms-of-service statement, and the typed acknowledgement — the primary button is disabled until the phrase is typed exactly~~, and Enter never enables~~ (Enter enables once the phrase matches since beta.30, owner decision D69 — below).enandviare written (the owner reviewsvi);jais the English verbatim, markedsafety: human review required, which the resx audit enforces (09_I18N§Safety-critical strings). The wording carries a version (Shared.Safety.SafetyDisclosure.Version = consent-dialog/1; bump on any change of meaning in any language): the Agent'sHelloAcknames the version it stamps against, the App does not open the dialog when it differs from its own (D14 — it says "restart both"), the App sends the version it showed, and the Agent'sSetHookEnabledhandler re-runs the pre-scan, compares the version to its own, and stampsConsentProvenance.ConsentDialogfrom its own clock or answersError DisclosureVersionMismatchwith nothing written.HookingConsentTests(App),AgentCommandHandlerTests(Agent side) andPipeEndToEndTests(the real pipe, the real pre-scan, the row read back) pin each half. The toggle that opens it is the game page's, PR-5.
Amended 2026-10-26 (beta.30, owner decision D69): Enter enables once the phrase is typed exactly. "Enter never enables" was built as
DefaultButton = Close, and WPF UI 4.3.0's template sends Enter to the default button (each button'sIsDefaultfollowsDefaultButton, read at the tag) — so the owner typed the phrase, pressed Enter and declined without a word, while the game page's switch went on showing on beside off. Asked with that, the owner chose: the primary button is the default; while the phrase does not match, the dialog's content keeps Enter (ConsentDialogContent.SwallowsEnter) and nothing happens; once it matches, Enter enables, as a click on the then-visible Enable hooking does. The typed phrase is still the gate: the button Enter reaches is disabled — and hidden — until the phrase is typed exactly, so a reflexive Enter cannot enable; Esc and Keep hooking off still decline. NoSafety_Consent_*string changed, soconsent-dialog/1stands.ConsentDialogKeysTestsholds both halves on the real template. The tick-box dialogs (D33's exception, D34's admin mode) are unchanged: Enter keeps them declined.
The Agent stamps one since 2026-09-10 (P2 PR-F, HANDOFF §P2 decision D4):
FrameLedger.Agent --console consent grantshowsOperatorDisclosure(the same four statements, first line naming the surface), requires the typed phrase, refuses redirected stdin, and recordsConsentProvenance.AgentConsoleOperatorwith the Agent's own clock — the property a file store could not uphold. It is still not FR-2.1's dialog, and its text says so first;P3's dialog retires itP3 PR-4's dialog (2026-09-13, above) is the user path; the verb stays as the developer path it always said it was — its provenance value stays distinguishable in the row. FR-2.4's kill switch is built the same day as the FOURTH input ofHookedCaptureGate(decision D7):settings.hooking.kill_switch = 1refuses every game withKillSwitchEngagedbefore consent is read, stops a running session at its next guard-scan boundary by publishingunhookRequested, and keeps the Vulkan layer off by never settingFRAMELEDGER_ENABLE_VK_LAYERon a launch.
The default for every newly added game is hooking off — Tier 2. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is opened either: a hooking-off row's Tier-2 session is held by the executable's name the executable's image path in the watcher's own snapshot (2026-09-23), with no OpenProcess, no resolver and no gate (04_CAPTURE §Tier selection). (Corrected 2026-10-03, beta.12, owner
decision D43: such a hold now reads the game process's own memory once a second — its video memory from performance
counters that open nothing, its system memory through a handle opened with PROCESS_QUERY_LIMITED_INFORMATION for the
read and closed after it, the same least right the watcher's snapshot already opens every process with, each second. No
handle is held, nothing is injected, the guard is not involved, and what is read is the kernel's accounting about the
process, never its memory — rule 4 is untouched. A process that refuses even that right reads N/A.)
A moved drive is the same executable — owner ask 2026-09-22
Every row is keyed on its executable's path, and consent is a record about one executable: path, size, mtime
(ExecutableFingerprint). On 2026-09-21/22 the owner's external drive came back as H: instead of D:, and
every one of 46 games read "executable unreadable" until the letter came back; a game launched from H: matched
its row by file name only and ran as a stranger, keyed on the new path, with no consent. The path is where the
bytes live; the size and the mtime are what the consent is about. So ExecutableRelocator may move a row to the
same file under another drive-letter root — and only then — with everything kept: consent, block, pre-scan state,
detection. The conditions are the safety of it:
- the file is gone from the row's path (both files present is two copies, not a move; nothing happens);
- exactly one other root holds a file with the same size and the same mtime (two is an ambiguity, and ambiguity refuses, as it does in the resolver);
- the repository's write requires the same size and mtime again (
RelocateExecutableAsync), so no caller can point a consent at a different binary through it; - no process is opened for any of this; the relocator reads files. It is asked by the 15 s sweep, by the watcher on a file-name match, and by the enable-hooking command before it says "unreadable".
- the candidate is the row's own path with only the drive letter changed — for every caller (2026-09-23). The
watcher's adopt used to accept ANY running path with the row's size and mtime, and every RPG Maker MV game ships
the same NW.js
Game.exe, byte for byte, with the mtime an unzip keeps: a hooking-on entry whose drive was unplugged could have followed another game's executable, consent and all. The adopt now requires the drive-letter twin and the same one-candidate rule as the sweep (over the drive list plus the running file's own drive). A file-name match that is not adopted records nothing at all (04_CAPTURE§Process watcher, HANDOFF D25).
Change executable is the other operation and stays what it was: a different binary, so hooking off, consent gone, pre-scan not run — it is the user saying "that file", not "that file moved".
Two more answers, 2026-09-23 (owner decisions D26, D27). Both are downgrades or neutral by construction; neither can move a consent onto a binary it was not given for.
- D27 — the file moved and changed. When the row's file is gone and the only file at its path under another
letter has OTHER bytes (the game updated while the drive had another letter), the row follows it through Change
executable's write (
ChangeExecutableAsync): the new size and mtime, hooking off, consent cleared, the pre-scan back to not run, the block kept. The user turns hooking on again for the new binary, through the disclosure, as for any changed executable. Two such files (two drives) is an ambiguity and refuses. The same rule holds for the watcher's adopt, whose session is then Tier 2 until the user does. - D26 — two entries for one file. When the move is refused because another entry already holds the target path
— a twin made while the letter was different, as the owner's
H:entries were — and the file there has the bytes the stale entry recorded, the two become one (IGameMerge, one transaction): the entry made first stays (its name, notes, consent and history), the other's sessions are re-parented to it, a block either carried is kept (hooking off; nothing clears a block, and a merge must not be how one disappears), a crash auto-disable still in force is kept, the crash counts add, and the dropped row is deleted. Nothing about consent moves between the rows: the survivor keeps its own record — which, when it is the entry that moves, is about these same bytes — and the dropped row's goes with it. A merge waits while a session of either entry runs or waits in a.partialto be recovered (a session finalized under a deleted entry would be dropped), and it is never done with an entry removed from the library. Other bytes under the twin are not merged: they do not prove the other entry is this game, so the log says so once and the user removes the entry they do not want.
A game already enabled can become blocked later
FR-2.2 disables the toggle for titles that ship anti-cheat, and FR-2.3 refuses at
runtime — but neither says what happens to a game the user enabled before it
started matching. A patch adds anti-cheat, or a rules update newly covers it.
Leaving hook_enabled = 1 in that state is the dangerous reading, and it is the
one the documents used to permit by omission (20_OPEN_QUESTIONS §S11).
The static pre-scan re-runs on every rules update and on every change to the game's executable (path, size or mtime). If it now matches:
hook_enabledis forced to0.hook_blocked_reasonis set — the column already exists (06_DATA_MODEL§games), so this needs no schema change, and a non-null value already means "toggle disabled in the UI".hook_consent_atis preserved. The user did consent; the block is not a withdrawal of consent and must not silently require them to consent againif the title is later cleared(corrected 2026-10-04: nothing clears a block since D22; the stamp is kept for the record and for a D33 exception).- The UI shows a persistent notice, not a transient toast — the user needs to understand why a game they enabled stopped being captured at Tier 1.
A rules update that removes a match does not re-enable hooking on its own.
Turning it back on is a user action, because re-enabling silently would mean the
rules feed can switch injection on for a game without anyone looking. — nothing does (corrected 2026-10-04: the block
outlives a rules change, a game update and Change executable; §What a finding does to the game).
Crash & stability safety
-
Two crashes of the same game within 60 s of injection ⇒ hooking auto-disabled for that game, UI explains, Tier-2 takes over. Recorded in
games.hook_autodisabled_reason. "Crash" here is any abnormal end: since beta.8 a session whose exit code is not an exception's (End task's 1) isnormalon its row, and this policy still counts it inside the window — a hang our hook caused, ended by the user, is the case it exists for. The row's reason says "ended abnormally twice within 60 s of injection" (04_CAPTURE§Crash & exit classification). -
Measured 2026-10-19/20 (
spike-notes§23): direct starts turned hooking off for exits no hook caused. Lies of P started by Play ▸ Start directly hands itself to Steam within seconds — its process leaves with nothing presented and Steam starts the game again —, and Clair Obscur: Expedition 33 started directly closes within five seconds and reads crashed, hooked or not (its third start, refused and unhooked, closed the same way). Each was a hooked session's early abnormal end; the policy counted them, and two turned hooking off. It cannot tell either from the hang it exists for, so it stands as written; whether a witness — the same executable started again within seconds — may exempt a hand-off is the owner's decision, not taken. Users are told inLIMITATIONS.md§Play. -
The count starts again when the user switches hooking on (owner decision D126, 0.1.0-beta.44). Until then
hook_crash_countonly ever grew: Lies of P had two such ends on 2026-10-19/20 (the hand-off above), its user switched hooking on again, and on 2026-11-12 one more early end — the game's own crash, by the owner, after a shader failed to compile — switched it off at once, under a reason that says twice. The consent grant, the only statement that turns hooking on, now sets the count to 0 (SqliteGameConsentStore). The policy still only disables, a block is still never cleared, and the user-mode exception's trial (D38) keeps its own record, which nothing sets back. -
A fault while the game is closing is not seen by a hooked session (owner decision D127: written down, not changed in 0.1.0-beta.44). Hogwarts Legacy faults in the driver's
_nvngx.dllat exit — six times in Windows' application log since 2026-11-06, hooked or not. The one unhooked session readscrashed; the five hooked ones readnormalwith exit code 0: the witness is looked for when the session is saved, which for a hooked session is before Windows has written the event. Looking again later would make every session of such a gamecrashed, and under a user-mode exception that ends the exception for good for a fault no hook caused — so it is a decision of its own, not a fix to slip in beside two new hooks. -
What reads as a crash changed in beta.14, in both directions (
04_CAPTURE§Crash & exit classification): a Windows report that is not a crash (a memory-leak or hang report) no longer makes one, and an engine's crash reporter started by a game that then left does — Unreal's crash ended with exit code 3 and readnormal. Both feed this policy, the D33 lapse and D38's trial ascrashedalways has: an Unreal game that crashes under a user-mode exception ends it now, where before beta.14 the crash went unseen; a leak report no longer ends one. -
The Overlay DLL self-disables after 3 faults in hook bodies (
17_HOOK_ENGINE§Fault policy) and reports it. -
Every hooked session writes a breadcrumb file before injection~~; if the game process dies before the first frame record arrives, the next run is recorded as suspect~~ (corrected 2026-10-04: no "suspect" mark exists; the breadcrumb is the
.partialfile, and an early death counts toward the two-within-60-s auto-disable above)."Cautious mode" is deferred to v1.1 (
20_OPEN_QUESTIONS§S12). It was described as "hooks installed, overlay drawing disabled" — but v1 draws no overlay at all (FR-15 is v1.1), so as written it disables nothing and is a no-op dressed as a safety measure. In v1 the breadcrumb is still written and still read: a second unexplained death within 60 s of injection triggers the existing auto-disable above, which is the behaviour that actually protects the user. Cautious mode returns with the overlay, when there is something for it to switch off.
What the Agent reads about input, from outside every game (owner decisions D155–D159)
Since 0.1.0-beta.50 the Agent can say what a session was played with (21_INPUT_DEVICES). It is on this page
because of what it must never become:
- It is read from Windows, by the Agent. Nothing is added to a game: no hook, no injected code, nothing in
17_HOOK_ENGINE§Hook inventory. Rule 4 is untouched, and a game the guard refuses is read like any other — nothing about it touches the game's process. - No hook of any kind.
SetWindowsHookExstays forbidden everywhere (tools/chokepoint-check.ps1); keyboard and mouse are known by one call that returns a time (GetLastInputInfo), and raw input is registered for joysticks and gamepads only — never for a keyboard or a mouse. A tool that hooks or registers for the keyboard is what security software, and some anti-cheat, look for; this is not one. - No device is opened and nothing is sent to one. A handle of FrameLedger's on a controller could make a game's own exclusive open fail; an output or feature report could change how a controller reports to the game. Neither is done.
- A committed list holds it:
tools/input-readonly-check.ps1(12_BUILDstep 14g).
Whether any anti-cheat objects to a background program that receives controllers' reports is not known; none is documented to. It reads nothing of, and does nothing to, the game.
Honest limits to document to users
The Disclaimer states these explicitly, and the UI consent dialog echoes them:
- The blocklist cannot be complete. New anti-cheat systems appear; a game can add one in a patch.
- Some anti-tamper (Denuvo) reacts to injection even in single-player titles — usually a crash, not a ban, but it can also mean lost play time.
- Even a perfectly behaved tool can be flagged by heuristics.
- FrameLedger's authors cannot restore a banned account. The refusal guard exists to make this unlikely; it is not a warranty.
Review checklist for any capture-layer PR
- Does this hook read anything beyond the arguments of the API it hooks? → reject
- Does this make FrameLedger harder for anti-cheat to identify? → reject
- Does this add a path to inject without passing the guard? → reject
- Is the new hook listed in
17_HOOK_ENGINE§Hook inventory with a stated purpose? - Does the hook body allocate, lock, log, or throw? → reject
- Does the session record
N/Arather than a fabricated value when this hook is unavailable (FR-4.9), and does it record WHY? (The old item asked whether a Tier-2 degradation path exists. Under a two-rung ladder the answer is always yes, so it was a box that could not fail — the defect class this document keeps recording.)