Normative behavior lives in SPEC.md. This file explains why the shim is shaped this way, which decisions are load-bearing, and which traps have already caused real bugs. If this file and the specification disagree, the specification wins.
A launcher, not a wrapper. It reads a small text file, prepares a process, spawns it, waits, and exits with the child's code. Everything it does exists to make that invisible: no configuration of its own, no output of its own, no behavior the user has to learn twice.
Two consequences run through the whole design.
Nothing may be in the way. The shim holds the console while the child runs, so anything the shim prints or reacts to lands between the user and the program they asked for. That is why errors go directly to the stderr handle -- WriteConsoleW when it is a console, UTF-8 via WriteFile otherwise -- and never through stdio: a block-buffered stream would hold the shim's diagnostic until exit and print it after everything the child had already said. A pure-ASCII fragment may go through either writer, which is why the rust and zig lanes bypass the routing for a few literals.
There is no runtime to install and nothing to clean up. The shim is one source file per lane compiled to a single executable. Direct Win32 calls, no wrapper library, no helper process.
Each lane is an independent implementation in its own language, with no code shared between them -- duplicated build scripts and version files included, on purpose, so that working on one lane never requires touching another. The shared test suite is the only thing holding them together.
That makes parity across the four the hard constraint: anything observable has to be specified rather than left to emerge, because emerging means differing somewhere. It is also why a rule that looks arbitrary usually has a real input behind it -- getting it wrong costs four behaviors, not one. Build and test infrastructure is duplicated for the same reason: each lane's build cleans only its own target directory and rejects stale output, and the suite pins UTF-8 decoding so a non-ASCII assertion does not depend on the host console.
- Read the shim file and classify every line.
- Apply the environment overrides to the shim's own environment.
- Create the child suspended, put it in a job object, resume it.
- Wait for it and exit with its code.
Step 2 happens before step 3 for two reasons: CreateProcessW with a null environment inherits the shim's, so the overrides have to be in place first; and the target is resolved while the file is parsed, because %~dp0 in the other fields is its directory.
Arguments come from two places -- the args field and the shim's own command line -- so the command line has to be rebuilt rather than appended to, and the user's arguments re-quoted on the way. QuoteArg implements the CreateProcessW rules for exactly that reason: the child must see the arguments the user typed, not a re-parse of them.
CommandLineToArgvW returns a signed count, and a negative value is a failed parse, so every lane clamps it before using it as a capacity or loop bound. Each lane's version file is the source of truth: the build validates it and packs the resource's versions from it, with the Rust lane overriding winres's Cargo.toml default so the two cannot drift apart.
Every shim carries a longPathAware manifest. Windows only lets a process hand a path beyond MAX_PATH to CreateProcessW if it opts in, and the opt-in is a manifest. The resource has to be written as type 24 by number: a cross-compiling llvm-rc does not resolve the RT_MANIFEST symbol and produces a named resource instead, which carries the manifest's bytes and is ignored by the loader -- nothing fails, and searching the binary finds it. The suite's probe reads the resource by ID and type number, which makes that trap observable rather than silent. The Rust lane embeds the manifest through the unmaintained winres; replacing it changes how the manifest lands, so the swap has to keep the manifest-presence test watching it.
The shim is not supposed to outlive its job, and the child is not supposed to outlive the shim.
A job object ties them together. JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE means the child dies when the shim does, so a closed console window does not leave an orphaned process behind. JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK scopes that to the direct child: a process the tool deliberately detaches, or a server it spawns, is its own business. Owning the whole tree would break the tools a launcher exists to run.
The child is created suspended. It has to be in the job before it can spawn anything of its own. Without CREATE_SUSPENDED there is a window between creation and job assignment in which the child can start a grandchild, and that grandchild escapes the job. This holds for the CreateProcessW path only; ShellExecuteExW has no suspended option, so the elevated path and its ERROR_ELEVATION_REQUIRED retry keep that window open (see Elevation).
A job that could not be created is not fatal -- every lane reports each job-object failure (create, set limits, assign) and runs ungoverned, and the resume-failure branch terminates the child directly, since a child that never resumes would sit suspended holding its image.
The console belongs to the child. The shim swallows every console control event and returns TRUE. The user is interacting with the program the shim launched, so Ctrl+C has to reach it and not the shim -- and if the shim died on Ctrl+C, KILL_ON_JOB_CLOSE would take the child down with it. The handler is installed before the spawn, closing the window where a Ctrl event would kill both.
The exit code is forwarded unmangled, including values above 255 and the 0xC0000005 family, so a caller can match on a specific crash code. Only an internal failure produces exit 1.
Rust buys size with panic = "abort" (see rust/README.md), which sends a panic down the fast-fail path instead of the exit-1 path above, so shim.rs has to stay panic-free: no unwrap, expect or panic!, and no indexing that can go out of bounds.
A GUI-subsystem shim would flash a console window on every launch, so the shim calls FreeConsole when its own PE subsystem is IMAGE_SUBSYSTEM_WINDOWS_GUI. If that same shim is given arguments, it is being used as a command-line tool, so it calls AttachConsole(ATTACH_PARENT_PROCESS) instead and the target's output has somewhere to go. Nothing downstream re-attaches: a failed CONOUT$ open is the policy for the no-argument case, not a problem to work around. The check reads the PE header, which lives in the module's first page, so an e_lfanew outside it is a bogus offset rather than a malformed image.
The standard handles are seeded from the shim's own only where the creator left a slot empty, and the CONIN$/CONOUT$ fallback only fires when the creator passed a null stream under STARTF_USESTDHANDLES -- which is what Go's os/exec does whenever only some of the three streams are set. Both blocks are inert for a creator that omits STARTF_USESTDHANDLES entirely, because CreateProcessW then ignores the seeded handles and the child resolves its own. They read as load-bearing and mostly are not: a defect in either one stays invisible until something passes a null stream.
CREATE_NO_WINDOW does not survive a second creation. A console target created with no console to attach to is given a fresh one, and that one has a window -- so a host that spawns the shim detached, where the CREATE_NO_WINDOW it passed was ignored beside the DETACHED_PROCESS it also set, would get a window flashed on every call. The shim therefore passes the flag on only when it has no console of its own and the creator owns the target's output. The probe is GetConsoleProcessList over a real one-element buffer -- a null list with a count of 0 is documented misuse that returns 0 regardless -- because the answer is what separates "nothing to share" from "something to share". GetConsoleWindow cannot make that separation: it is null both with no console and with a windowless one, and a windowless console must still be shared, not replaced. It is conditional for that reason too: passing it unconditionally would take a target that could have shared the shim's console and hand it its own. The host that exposed this calls Node's spawn with detached: true, windowsHide: true and every stream piped, which is the shape probe create --detached --stdin exists to express.
The creator decides where the target's output goes, and so whether a console window opens. A window is only worth opening when nothing else owns the output: the creator set STARTF_USESTDHANDLES, meaning it took over the standard handles, or the shim's own stdout is a valid handle, meaning the creator left the child somewhere to write. Node's and Bun's spawn always set the first. With neither, the creator left the target with nowhere to write -- the Explorer, Win+R and Start-Menu shape -- and the target then gets a console of its own, with a window, exactly as a direct launch of that executable gives it. That is the difference between a console app the user double-clicked and one a program started: the first has to be seen, the second must not flash. Getting it wrong the other way is upstream issue #18. The rule reads the creator's intent out of the startup info the shim was given, which is also what EnsureStandardHandles reads: that function only ever sets STARTF_USESTDHANDLES when the creator had already set it. A target carrying its own detached policy is out of reach either way -- the policy overrides CREATE_NEW_CONSOLE, so such a target runs without a console however it is started.
A GUI-subsystem shim given no arguments reaches the same state by a second route: FreeConsole leaves it with no console either, and its target follows the same rule. No shipped binary is affected, because every lane builds a console-subsystem shim. The route is unreachable by test: any target that reports something has arguments, and arguments take the AttachConsole branch instead.
The manifest decides whether the shim holds a console at all. consoleAllocationPolicy=detached leaves a launch with nothing to inherit console-less instead of giving it a visible allocated console -- the Start-Menu-shortcut and Explorer shapes, where a GUI-app target used to flash a window, and exactly the state the conditional CREATE_NO_WINDOW above handles. Terminal launches are untouched: the policy governs only the nothing-to-inherit case, and console inheritance proceeds as normal. Only Windows 11 24H2 (build 26100) and Server 2025 honour it; older Windows gives the shim the console the loader allocates, and the target inherits it. The policy is the shim's own manifest and does not reach the target. The accepted cost, the same one kiennq/scoop-better-shimexe PR #23 took: a broken .shim's error text from Explorer is no longer visible.
elevate goes through ShellExecuteExW, not CreateProcessW: it is the only way to get a UAC consent dialog. That call takes params rather than a command line, which is why the two are built separately. The child still joins the job object, so its lifetime is governed the same way once it does -- but not from the first instant, because it was already running when AssignProcessToJobObject was called. It takes no creation flags, so an elevated launch from a console-less creator still opens one.
Lines are decoded one at a time, strictly. A line that is not valid UTF-8 is reported as Shim: invalid UTF-8 line in shim file and dropped; the rest of the file still loads. Converting the whole file in one call is simpler and wrong: it replaces the bad bytes with U+FFFD, producing an environment variable whose name the user can neither type nor reference. A variable you cannot name is indistinguishable from a bug. The file is sized with GetFileSizeEx, because GetFileSize's INVALID_FILE_SIZE is also a legitimate 4GB-1 size.
A byte order mark is skipped off the front of the raw bytes, before lines are split out, rather than by checking whether a decoded line is the first one. A BOM only ever appears at byte 0, so tracking "is this the first line" would be state the format never needs -- and state that four implementations would have to agree on.
Line endings are LF and CRLF. Every implementation splits on \n and drops a trailing \r as whitespace.
The whitespace set is fixed. A line holding only whitespace is a blank line, so the set decides whether such a line is ignored or fatal. It is the full 25-code-point Unicode White_Space set, and every lane has to agree on it exactly -- a set that is too small turns a blank line into a fatal one in some implementations and not others.
The separator is the first =, so the value stays free to contain more of them -- args has to carry --flag=a=b intact.
The line is right-trimmed before it is split, so trailing spaces in a value are eaten: a trailing space would otherwise defeat the double-quote unquote test on a path value. The key is trimmed on both sides and the value on the left, so a misindented key still works.
A line that is not blank, a comment, or a field is fatal. A shim file has no legitimate content beyond fields and comments, so such a line means the file is broken, and the worst outcome for a launcher is to run a half-configured program. The check runs while the file is being read, the one place that sees every line: it cannot live in either of the later expansion passes, because the one that resolves the target path scans path lines only, and the one that reads every field would report the same line twice.
%~dp0 means the shim's own directory inside path, and the target's directory everywhere else. The target's directory is not known until path has been resolved, so the first pass finds and absolutises path and the second expands every other field against it -- the only reason the parser needs two passes, and the reason %~dp0 means two different things in the same file. The target's directory is what GetFullPathNameW answers for the resolved path; when that call fails, the shim reports it and falls back to the input with its last component dropped, because expanding %~dp0 into a value that still ends in the target's file name puts a path where a directory belongs.
A path value is either drive-qualified (an ASCII drive letter and :) or relative; a leading separator is rejected. A leading separator anchors the target to the current drive, so the same shim would find a different target depending on where it was run from; rejecting it keeps the target a function of the shim's own location alone.
A relative value is resolved by the shim, not by CreateProcessW: that order is the directory the image loaded from, the current directory, the system directories, the Windows directory, and only then PATH, so path = curl.exe launches System32\curl.exe even when an earlier PATH entry holds the one the caller meant. It is the order for loading an image, not for resolving a command a person typed, and it depends on the machine's SafeProcessSearchMode and on the process being 32-bit (the system directory is then SysWOW64). PATHEXT is not consulted either: most of its entries are scripts or association targets CreateProcessW rejects, and honouring them would mean ShellExecute and yet another order. A name that is not found is a launch failure rather than a fallback, because a fallback would silently launch the system copy this rule exists to reject. The shim's own directory is not special: Scoop puts it on PATH, and a shim beside its target names it explicitly.
A value that carries its own separators is resolved against the shim's current directory, so it does not shift with the platform's order either. Resolving once, while the file is parsed, is what lets %~dp0 and the launch share an answer: the search reads the started-in PATH, so an override cannot move the target away from the directory the other fields were expanded against.
Reserved keys are matched case-insensitively, so PATH = x is the path field: it overwrites the target executable instead of the PATH variable, and there is no way to override PATH otherwise. env: and env!: mark the key as an environment variable name; the prefix is stripped case-insensitively and the remainder is used verbatim. env: supplies a default, env!: forces the value. Neither reaches the reserved-key table, so no field can shadow it and adding one later cannot break a shim that already uses it. Reserved keys and the prefixes fold ASCII A-Z/a-z only, because matching through a Unicode case table would make the format depend on the runtime's tables.
Each of these was a real bug at least once.
- Strip the prefix constant, never a literal length. Cutting the prefix itself means the length and the comparison cannot drift apart; a hardcoded length silently truncates variable names.
- Strip in the key dispatch, not in the line parser. The first expansion pass scans for
pathalone to resolve the target's directory. A strip in the parser hands it a prefixedpathinstead, and the shim launches whatever that points at. - Share the value pipeline. A default or forced value goes through the same expansion and unquoting as any other. A second code path for it will drift, and it will only ever fail for the new syntax.
- The prefix guard must accept the prefix as the whole key. A stricter guard makes the empty-name check unreachable, and
env:/env!:then quietly defines a junk variable instead of saying anything. - A bare
env:/env!:is not fatal. It names no variable, so the line is reported and skipped and the target still starts. That is a different failure from a malformed line, and merging the two turns a typo into an outage.
All %VAR% in a value expand when the file is read, against the environment the shim was started in. Every value therefore sees the same starting environment, which makes a shim file order-independent and means a value cannot reference a variable the shim itself defines. Expanding as each line was applied instead would make the file's meaning depend on line order. args is the exception: %VAR% is passed through unexpanded, so the child can expand it against the environment it actually receives.
%~dp0 is separate from %VAR%: it is expanded in args as well as in path, cwd, and environment values. In path it is the shim's own directory; everywhere else it is the target's directory.
A syntax error in the shim file is fatal: the shim reports it, exits 1, and never starts the target. A problem with one line -- an undecodable line, an env:/env!: key with no name, a variable the platform refuses -- is reported and that line is skipped. Nothing else stops the launch. The error channel is allocation-free -- a diagnostic is what is left when something has already gone wrong -- and the cpp lane writes through a segmented fixed stack buffer, so no wide character is split.
SPEC.md adds one branch, not a subsystem. It exists so Scoop can ask a shim what it is and which optional fields it implements before generating a .shim file.
Only the canonical, unpaired shim.exe answers. A generated shim is renamed to the command it launches; its arguments belong to that command. Reserving --version on every shim would steal an argument from real targets. Reserving it only on shim.exe makes the one exception explicit. shim.shim still wins: a .shim file makes the executable a shim, so its arguments are the target's. The branch is therefore exactly: name shim, no shim.shim, and zero user arguments or one --version/-v.
Two lines, curl-style. The first line identifies the binary and its version; the second lists optional features:
shim <version> (<impl>)
Features: cwd env env-force expand dp0 elevate
A single line would parse too, but the separate Features: line is easier to read and easier to extend without redefining the first line. It mirrors curl's Features: rather than inventing a compact grammar. The output is ASCII, one line per fact, stdout, exit 0.
Only optional features are advertised. utf8 and exitcode are required; child-lifetime behavior and longpath are SHOULD-level. None are feature branches. path and args are baseline. The feature list is the set of fields a producer could choose to emit: cwd, env, env-force, expand, dp0, elevate.
env: is the default form: it fills an absent or empty value and leaves a user-provided value alone. env!: is the forced form. This lets a package manifest carry defaults without taking ownership of the user's environment.
The list is static and build-time. Runtime probing would add code and could lie under a different environment. A shim advertises what it was built to implement.
The same facts travel in the version resource. An installed shim is named after its target, so --version belongs to the target there; its PE metadata is the only way to ask a deployed copy what it is without running it. Comments carries the Features: line because FileVersionInfo reads it with no P/Invoke. The requirement is SHOULD: the resource is a binary-layout detail, and a conforming shim need not be a PE. The compiler and the resource generator read the same version file -- version on line 1, feature list on line 2 -- and the suite compares the resource against --version.
No --help and no JSON. Self-description is the one command Scoop needs. Adding more surface now would create compatibility obligations before the contract is settled.