Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .vscode/tasks.json
Original file line number Diff line number Diff line change
Expand Up @@ -67,16 +67,16 @@
"problemMatcher": ["$rustc"]
},
{
"label": "Watcher: restart the logon task",
"detail": "stop it, wait for the process to actually go, start it again",
"label": "Watcher: restart the installed one",
"detail": "hand a game session over, then have Explorer start it again from its startup entry",
"type": "shell",
"command": "pwsh",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-Command",
"Stop-ScheduledTask -TaskPath '\\GameModeExecutor\\' -TaskName Watcher; $d=(Get-Date).AddSeconds(20); while((Get-Date) -lt $d -and @(Get-Process gamemode-executorw -ErrorAction Ignore).Count){Start-Sleep -Milliseconds 250}; Start-ScheduledTask -TaskPath '\\GameModeExecutor\\' -TaskName Watcher; Start-Sleep 2; Get-Process gamemode-executorw -ErrorAction Ignore | Select-Object Id, StartTime"
"$gme = \"$env:LOCALAPPDATA\\Programs\\GameModeExecutor\\gamemode-executor.exe\"; & $gme stop --handover; & $gme add-to-startup; Start-Sleep 2; Get-Process gamemode-executorw -ErrorAction Ignore | Select-Object Id, StartTime"
],
"problemMatcher": []
},
Expand All @@ -90,7 +90,7 @@
"-ExecutionPolicy",
"Bypass",
"-Command",
"Get-Content -Wait -Tail 30 \"$env:LOCALAPPDATA\\GameModeExecutor\\logs\\gamemode-executor.log\""
"Get-ChildItem \"$env:LOCALAPPDATA\\GameModeExecutor\\logs\\gamemode-executor.*.log\" | Sort-Object LastWriteTime | Select-Object -Last 1 | Get-Content -Wait -Tail 30"
],
"isBackground": true,
"problemMatcher": []
Expand Down
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ This file says how to work here. The *why* is in
the rules — the engine's session, `update`'s phase, the supervisor's
verdict — what to draw and what a click means.
- **The setup commands are a contract with three callers.** `stop`, `init`,
`install-task` and `uninstall-task` are sequenced by the package
`add-to-startup` and `remove-from-startup` are sequenced by the package
(`scripts/msi.ps1`), by the zip's after-exit shell in `update`, and by
`purge`. A change to any of them is verified on all three paths.
- Module doc comments carry the rules a module is shaped by: read them
Expand Down Expand Up @@ -138,7 +138,7 @@ This file says how to work here. The *why* is in
user's commands: `cargo test -- --ignored a_real_activation_drives_a_session`.
- **Verify as the user runs it:** `gamemode-executor stop`, copy the two
release executables over the installed ones, `gamemode-executor
install-task`, and read the log at `debug` through a real game. A package
add-to-startup`, and read the log at `debug` through a real game. A package
change: uninstall from *Programs and Features*, install the new `dist\`
package — the product code is fixed per version. Never restart the
watcher while a game runs: that fires the stop commands.
Expand Down
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,20 @@ a section is written.
- Each release file comes with GitHub's attestation that the release workflow
built it from the tagged commit:
`gh attestation verify <file> --repo Geeooff/GameModeExecutor`.
- The watcher appears in Settings, *Apps → Startup*, as *GameModeExecutor
watcher*, with a switch to stop it starting at logon.

### Changed

- Windows starts the watcher at logon from your `Run` key instead of a
scheduled task; an upgrade removes the old task.
- `install-task` and `uninstall-task` are now `add-to-startup` and
`remove-from-startup`. The old names work until 1.0.0; `--delay` is gone.

### Fixed

- Office's updates no longer stop the watcher. They ended whatever a
scheduled task had started, the watcher included.
- `purge` removes its folders even when they are marked read-only, as a
folder copied back from a OneDrive backup is.

Expand Down
4 changes: 4 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,10 @@ windows = { version = "0.62", features = [
# CoInitializeEx: the apartment Microsoft asks for before ShellExecuteEx,
# in the helper that opens what the menu offers.
"Win32_System_Com",
# IShellBrowser and IShellView, and the VARIANTs IShellDispatch2 takes:
# `add-to-startup` asks Explorer to start the watcher (Lot 19).
"Win32_System_Ole",
"Win32_System_Variant",
# The updater: WinHTTP for the release, CNG for the SHA-256 of what it
# fetched. Microsoft's libraries, no HTTP or hashing crate.
"Win32_Networking_WinHttp",
Expand Down
72 changes: 69 additions & 3 deletions docs/design/19-startup-list.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,23 @@
# Lot 19 — Starting from Windows' Startup list

**Status: spike done 2026-11-16; proposed for a decision.** The maintainer
**Status: decided 2026-11-16, being built; ships in 0.5.0.** The maintainer
wants GameModeExecutor in *Settings → Apps → Startup*, with its switch,
instead of a logon task that page does not show. The spike adds a second
reason: Office's updates end what a logon task started, and spare what the
`Run` key started.

- [x] Spike: survival, what a `Run` entry gives, the cost per caller — 2026-11-16, below
- [x] `startup`: the `Run` value written and removed, the watcher started through Explorer, `task` reduced to removing a 0.4 task — 2026-11-16
- [x] `add-to-startup` and `remove-from-startup`, the old names as hidden aliases; the package, the zip's updater and `purge` on them — 2026-11-16
- [x] The user pages, the reference, the changelog — 2026-11-16
- [x] Explorer starts the watcher from a person's terminal and from the package's action — 2026-11-16, below; from the zip's shell at the 0.5.0 update
- [x] The 0.4 task removed by `add-to-startup`; `uninstall-task` works as an alias — 2026-11-16, below
- [ ] An upgrade from the published 0.4.0, by the package and by the zip
- [x] The switch: off, then a logon; on again — 2026-11-16, below
- [x] `remove-from-startup` takes the switch's entry too; `purge` lists the entry and no task — 2026-11-16, below
- [ ] `purge` carried out, at the next full purge
- [ ] The watcher outlives an Office update

## Why

- **Transparency.** The Startup page, and Task Manager's, list three sources:
Expand Down Expand Up @@ -79,7 +91,9 @@ The setup commands' three callers each meet the change
| The zip's after-exit shell | calls the new binary's `install-task` | unchanged, so the verb must keep working: a 0.4 copy's shell calls it |
| `update`, a failed install | `schtasks /Run` restarts the old watcher | a 0.4 copy's shell still does that; the new version's shell starts the watcher the new way |
| `purge` | removes the task | removes the value, its `StartupApproved` entry, and a task left over |
| `status` | says whether the task is there | says whether the value is there and points at this copy |

*A `status` row said `status` reported the task; it never did, and needs
nothing here. Corrected 2026-11-16.*

Two edge cases, neither leaving the program unstartable:

Expand Down Expand Up @@ -125,7 +139,59 @@ command must start it itself:
**Recommended: 2**, measured on all three paths. It gives the parent that
was measured rather than one that might hold.

## Done when, proposed
## Decided 2026-11-16

The maintainer took the lot and the recommendation, and named the verbs.

- **`add-to-startup` and `remove-from-startup`**: *startup* as the page
says it, with a verb in plain English. `enable`/`disable` were turned
down: they are what the switch does, and the switch keeps the entry.
- **The old names live in the command line, not in the package.** Only a
0.4 zip copy's updater calls `install-task` on the new binary; nothing
automatic calls `uninstall-task`, since the 0.4 package runs its own
executable and skips that action on an upgrade. So both are hidden
aliases, accepted until 1.0.0, and the package names only the new
actions, `AddToStartup` and `RemoveFromStartup`, in the old ones' places
and conditions.
- **The migration lives in the commands.** `add-to-startup` removes the
0.4 task after writing the value; `remove-from-startup` and `purge`
remove one left over. That removal stays past 1.0.0: it protects a copy
that skips versions.
- **No `Registry` row**: the program stays the one writer of the value.
- **A failure to start the watcher now is a `warn`**, not an error: the
install goes on, and the next logon starts it.

## Measured in the field, 2026-11-16

On the maintainer's machine, with the branch's release build (`54802623`),
from the log and the process list, the maintainer's eyes on the Settings
page:

- **From a terminal**, a game session open. The installed copy stopped with
`--handover` and the executables replaced, then `add-to-startup` at
15:40:22: the value written, *Logon task of an earlier version removed*,
*Watcher started through Explorer*. The new watcher's parent was
`explorer.exe`; it started 16 ms after the request and resumed the session.
- **From the package.** 0.4.0 uninstalled from Settings: its action ran
`uninstall-task` on the new executables, and the alias removed the value
at 15:43:08. The branch's package installed: *Configuration kept*, the
value added, *Watcher started through Explorer* at 15:43:27, from the
deferred action. The watcher's parent: `explorer.exe`. So Explorer takes
the request from Windows Installer's custom action, the case that was
least certain.
- **On the page**: *GameModeExecutor watcher — Geoffrey Vancoetsem*, the
green controller, *On*, *Not measured*.
- **The switch.** Turned off at 15:46: the running watcher went on, and
Explorer wrote `01` and a timestamp in `StartupApproved\Run`. At the next
logon, no watcher. Turned on at 15:48: `00` and zeros, and at the next
logon the watcher started 7 s after Explorer, its child. The value itself
never changed: the switch is Windows' alone, as the module keeps it.
- **Removal**, from the maintainer's terminal at 15:51: `remove-from-startup`
removed the value and the switch's entry, which was then gone;
`add-to-startup` put the value back. `purge`, answered no, listed *remove
the startup entry `GameModeExecutor` and its switch* and no task.

## Done when

The watcher starts at logon from the `HKCU` `Run` key and shows on the
Startup page with its switch; an install, an upgrade and a zip update each
Expand Down
2 changes: 1 addition & 1 deletion docs/design/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ the pages keep the history.
| 16 | [What the watcher keeps](16-footprint.md) | done 2026-09-23; memory at rest to measure again against 0.3.0 |
| 17 | [A log that turns over each day](17-log-rotation.md) | done 2026-09-26; its last checks seen 2026-10-17 |
| 18 | [When the game is gone and nobody is there](18-game-gone-nobody-there.md) | proposed, not decided |
| 19 | [Starting from Windows' Startup list](19-startup-list.md) | spike done: Office spares `Run` starts; proposed |
| 19 | [Starting from Windows' Startup list](19-startup-list.md) | being built, for 0.5.0; field checks open |
| 20 | [The build chain, official and kept current](20-build-chain.md) | built 2026-10-17; the first wait and the first attested release to see |
| 21 | [Moving to windows-rs 0.100](21-windows-rs-0100.md) | proposed; waiting for `windows` 0.100 |

Expand Down
15 changes: 10 additions & 5 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ Run one thing when a game starts, another when it stops. Five minutes.

**The installer** (`.msi`) needs no administrator rights. It installs for you
alone in `%LOCALAPPDATA%\Programs\GameModeExecutor`, writes a starter
configuration, registers the logon task and starts the watcher. Windows warns
configuration, adds the watcher to the programs Windows starts at logon and
starts it. Windows warns
because it is not signed; the release page says how to check it came from this
repository. A newer release installs over it and keeps your configuration.

Expand All @@ -27,10 +28,10 @@ OneDrive. Then, once:

```bash
gamemode-executor init
gamemode-executor install-task
gamemode-executor add-to-startup
```

Moving the folder later means `install-task --force` again.
Moving the folder later means `add-to-startup --force` again.

There are two executables. `gamemode-executorw.exe` is the watcher: no window,
started at logon, never by you. `gamemode-executor.exe` is the one you type
Expand Down Expand Up @@ -92,7 +93,8 @@ Not visible? Click the `^` next to the clock and drag it onto the taskbar.
| **Quit** | stops the watcher, running the stop commands first |

After *Quit*, it starts again at the next logon, or from **GameModeExecutor**
in the Start menu.
in the Start menu. Settings lists it under *Apps → Startup* as
*GameModeExecutor watcher*; its switch there stops it starting at logon.

## Updating

Expand Down Expand Up @@ -164,9 +166,12 @@ running; a second one is refused.

## Turning it off

*Quit*, then turn *GameModeExecutor watcher* off in Settings, *Apps →
Startup*. Or, from a terminal:

```bash
gamemode-executor stop
gamemode-executor uninstall-task
gamemode-executor remove-from-startup
```

To remove it entirely: *Programs and Features*, or `purge` — see
Expand Down
33 changes: 19 additions & 14 deletions docs/how-it-works.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,20 +75,23 @@ processor in all.
A Windows program is built either as a console program, which can print, or
as a windowless one, which cannot. One file cannot be both.
`gamemode-executor.exe` answers your commands in a terminal, and the shell
waits for its result. `gamemode-executorw.exe` runs the watcher from the logon
task and the installer's steps, with no window to flash; it writes to the log
waits for its result. `gamemode-executorw.exe` runs the watcher at logon and
the installer's steps, with no window to flash; it writes to the log
instead. Python does the same with `python.exe` and `pythonw.exe`.

A named lock allows one watcher at a time: a second one is refused, so the
Start menu's **GameModeExecutor** is safe to click.

## What starts it

A per-user scheduled task, at logon, fifteen seconds in. Not a service:
services run in a separate session and cannot see the desktop the game is on.
The task is registered from XML, because the usual shortcut would leave a
72-hour execution limit and two battery conditions on it. The installer stops
the watcher before it replaces or removes the files.
Windows, at logon, from your `Run` key: Settings lists it under *Apps →
Startup* as *GameModeExecutor watcher*, with a switch to turn it off. Not a
service: services run in a separate session and cannot see the desktop the
game is on. The installer adds the entry, has Explorer start the watcher
right away, and stops it before it replaces or removes the files.

*Up to 0.4 a scheduled task started it, and Office's updates ended what that
task started: measured in [Lot 19](design/19-startup-list.md).*

The watcher owns one hidden window: the icon hangs off it, and it is how
Windows tells the watcher the session is ending.
Expand Down Expand Up @@ -142,7 +145,7 @@ for a hand-installed copy), checks its SHA-256 against the release's
watcher with a handover, replaces the files and starts the new version. A
zip copy is updated by a hidden shell that waits for the watcher to exit,
unpacks the zip over the folder, keeping the old executables as `.old`, and
runs `install-task`.
runs `add-to-startup`.

The hash proves the file is the one the release published; the program has no
code signature ([why](design/13-updating.md)). Each release file also carries
Expand All @@ -152,16 +155,17 @@ checks.

## Removing it

*Programs and Features* removes the executables and the logon task, and keeps
your configuration and log, as Windows applications do.
*Programs and Features* removes the executables and the startup entry, and
keeps your configuration and log, as Windows applications do.

```
gamemode-executor purge
```

removes every trace after a `yes`: the task, the configuration, every log
file, the session marker, the updates folder, then the executables. It refuses
during a game, and leaves what it did not create, such as a recipe's tasks.
removes every trace after a `yes`: the startup entry, the configuration,
every log file, the session marker, the updates folder, then the executables.
It refuses during a game, and leaves what it did not create, such as a
recipe's tasks.

## What it does not do

Expand All @@ -180,7 +184,8 @@ during a game, and leaves what it did not create, such as a recipe's tasks.
| The program | `%LOCALAPPDATA%\Programs\GameModeExecutor`, or wherever you unzipped it |
| Configuration | `config.toml` next to the executable if there is one, else `%APPDATA%\GameModeExecutor\config.toml` (roams with your profile) |
| Log | `%LOCALAPPDATA%\GameModeExecutor\logs`, one file a day, seven kept; the day changes at midnight UTC |
| Scheduled tasks | the `GameModeExecutor` folder in Task Scheduler |
| Startup entry | `GameModeExecutor` under `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`; its switch in Settings, *Apps → Startup* |
| A recipe's scheduled tasks | the `GameModeExecutor` folder in Task Scheduler |

The [design record](design/) has the measurements behind all this, starting
with [Detection](design/00-detection.md); the [reference](reference.md) has
Expand Down
4 changes: 2 additions & 2 deletions docs/recipes/fancontrol-fan-profiles/config.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@
# chosen when the tasks are registered and lives in the task, so this file is
# the same for everyone and never has to know what you called yours.
#
# The backslash is a Task Scheduler folder, not a path on disk: everything this
# program installs lives under \GameModeExecutor rather than loose at the root.
# The backslash is a Task Scheduler folder, not a path on disk: the recipe's
# tasks live under \GameModeExecutor rather than loose at the root.
# Note the single quotes -- TOML takes those literally, so the backslash needs
# no doubling.
#
Expand Down
4 changes: 2 additions & 2 deletions docs/recipes/fancontrol-fan-profiles/uninstall-tasks.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@
# \GameModeExecutor\FanControl Game
#
# What stays: FanControl and its configurations, the \GameModeExecutor folder
# in Task Scheduler and every other task in it -- the watcher's own logon task
# lives there -- and GameModeExecutor's config.toml, which still names the two
# in Task Scheduler and every other task in it, and GameModeExecutor's
# config.toml, which still names the two
# tasks until you edit it. This script is the recipe's counterpart to
# install-tasks.ps1; GameModeExecutor itself does not know which recipe you
# followed and never removes a task it did not register.
Expand Down
Loading