Run
--trace-input-dispatch adds bounded CLI input timing observations (at most
1,000 records plus one suppression notice per process). It works with
--quiet-api --quiet-blocks; without the trace flag, existing output stays
unchanged. [input-schedule] records the requested scheduledBatch and the
actual injection batch, before the action runs; it does not prove an event was
queued. [input-enqueue] identifies raw scripted MSG objects actually queued.
[input-dequeue] records when h.check_input consumes an event, with full
32-bit wParam/lParam, source and a per-consumption dequeueId.
[input-dequeue-route] uses that ID for the polling guest's focus routing result
(hwnd 0 lets WAT select its default). Empty polls produce no new timing record.
[dispatch-input] records mouse/key MSG contents when the main CLI instance
enters DispatchMessageA/W, before its handler runs. These observations do not
cover independent worker API loggers, DirectInput polling or completed wndproc
execution.
Each record includes the observed batch and a non-advancing guestMs from
the existing guest clock's publish path. clock=batch means its current batch
base, including clock rebases/pauses. clock=real uses the existing
scaled/mapped elapsed clock. lastGuestTick records the last actual return
through the main host's guest-clock reader, after startup dilation or other
mapping, in either mode. Before its first observed call it is unavailable.
This value can be stale, including across startup release: publishing time does
not change it. Host hooks that share this reader also update the observation;
it does not report independent worker threads' last API reads or QPC's separate
microsecond interpolation. It is never the raw underlying batch-clock state.
Neither value is computed from the scheduled batch, and tracing spends no
guest clock probe. Raw enqueues retain enqueueId/scheduledBatch at dequeue
only by object identity. Renderer actions may suppress, combine or generate
multiple events, so their schedule-to-dequeue identity is unavailable.
Dispatch always says correlation=unavailable: an identical MSG tuple cannot
prove which host dequeue produced it, especially with repeated keys or mouse
events. Compare observed windows without treating matching tuples as IDs.
For a separately authorized Penguin follow-up with its registered original
assets installed, retain the matched schedule and add
--screen=800x600 --trace-input-dispatch --quiet-api --quiet-blocks to
node test/run.js --app=penguin_command_1611 --no-build ....
--screen=WxH is the existing host viewport option; review captures for the
full client/cannon area. Use observed dequeue/dispatch batches to place later
capture brackets; scheduled 34800:keydown:65,34900:keyup:65 alone does not
establish delivery time. This diagnostic change has source-level regression
coverage, not a new Penguin gameplay qualification. Run the lightweight test
with node --max-old-space-size=256 test/test-cli-tick-ms-input.js --source-only;
it executes production CLI hook bodies with real clock/trace code and controlled
queues/MSG memory, without instantiating the guest VM.
Browser: Open
index.html(at repo root), select an app, click Launch. Live build deployed at https://wine-assembly.berrry.app viatools/deploy-berrry.js --update.CLI:
node test/run.js --exe=path/to/exe [options]— headless execution with auto-build. A registered EXE gets that app's explicit file manifest; an arbitrary bare--exemounts only the executable. Add repeatable/comma-separated--vfs-include='*.dat,plugins/**/*.dll'patterns (relative to the EXE directory) for ad-hoc companion assets, or prefer--app=ID. Repeatable--vfs-mount=HOSTPATH=GUESTPATHmounts one host file at an exact guest path, and is applied after the app's manifest, so it replaces a single manifest file for one run without touching disk (e.g. a test INI:--vfs-mount=scratch/x.ini=c:\System\UnrealTournament.ini; mount every alias the manifest gives that file). Key flags:--verbose,--trace,--trace-api,--trace-gdi,--trace-host=fn1,fn2,--no-close,--break=0xADDR,--break-api=Name,--watch=0xADDR,--dump-gdi=DIR,--max-batches=N,--batch-size=N,--tick-ms-per-batch=N--quiet-apiis close to free speed on any API-heavy app, so pass it unless you are reading the API log. Every Win32 call prints an[API]line by default — Diablo emits 96,787 of them by its main menu and 724,015 by the time it reaches gameplay — and that write is blocking I/O on the thread the guest runs on. Measured back to back on the same 1000-batch Diablo command line: 3:53 wall / 25.1s user CPU by default against 1:17 wall / 25.1s user CPU with the flag. Identical CPU, three times the wall clock — the whole difference is the process waiting on stdout, and on a loaded box it is the difference between a run finishing and a run being SIGKILLed at its timeout.--trace-apiand friends are unaffected; this only suppresses the unconditional one-liner.--tick-ms-per-batch=N(default 200) sets how much guest time one batch is worth on the headless batch-driven clock. Reach for it whenever a game's engine steps on aWM_TIMERand the capture shows the clock already expired: at the default 200ms/batch Chip's Challenge burns its entire 100-second level timer in 500 batches and puts up "Ooops! Out of time!" before any--inputlands.--real-ticksis not the fix — a 16-bit app runs 5000 batches in a third of a second of wall clock, so its 110ms timer fires about three times in a whole run and nothing ever moves.--tick-ms-per-batch=5reaches real gameplay. An app that always needs another clock registers it inlib/apps.jsascliTickMsPerBatch(the flag still wins; the browser never reads it). A batch is a fixed block budget, so for a CPU-bound renderer 200 ms/batch reads as a machine that takes minutes per frame: the seven Plus! 98 D3DRM savers register2, because at 200 their scene timers expire before the first Flip and the device is rebuilt after every frame.The guest calendar is pinned by default to
1999-06-01T12:00:00Z(it then advances with guest time), so two runs of one command are the same run even when the guest seeds from the time of day — Deus Ex diverged per wall-clock second before this.--wall-clock-ms=Nor an app'swallClockinlib/apps.jspicks another date;--real-calendargives today's date;--real-tickskeeps the real calendar unless a calendar pin takes precedence. The time zone is pinned too, to UTC, soGetLocalTimereads 12:00 on a PDT laptop and on a UTC box alike, and agrees withGetTimeZoneInformation's zero bias.--tz=IANA/Namepicks a zone;--real-timezone,--real-calendarand--real-tickskeep the host's. The browser always uses the real date and zone.An explicit
--wall-clock-msstill advances the calendar by batch time, even with--real-ticks. For interactive captures whose deadlines use CRTtime()and must track elapsed wall time, use--real-calendar --real-ticksand omit--wall-clock-ms; specify--tz=UTCif the capture needs a fixed zone. Barrage 1.0.5 usestime(NULL) + 180for its round deadline: its clock audit found that the pinned calendar expired the round early, while the unpinned real-calendar run matched host and guest tick intervals and preserved the full round deadline. This applies to calendar-based deadlines; retain the batch-timer guidance above for short 16-bitWM_TIMERruns.--batch-sizeis a budget of BLOCKS, not steps, and a block is not a fixed amount of work.run(N)spends one$block_budgetper basic block, and the$stepsquantum is 256 block transfers per visit to the run loop, counted at block ends rather than in every dispatch — so one block can be a 3-instruction loop head or an entire folded sprite row. Measured on Diablo (--batch-stats+--handler-hist): 6.9 ops per block in its Smacker intro against 282 ops per block in its menu, a 41x spread inside one app. Ops per second is flat at ~7-9M across both, so the emulator is not "slower" in the menu at all — batches are simply a meaningless unit of work, and any per-batch number (batches/s, ms/batch) silently changes meaning when the guest's code shape changes. Quote ops, or quote wall time for fixed work.This is also why time-paced content stalls. The headless clock is
batch * TICK_MS_PER_BATCH, so guest time advances per batch while work per batch varies 41x — and it varies the wrong way: an app sitting in a tight polling loop retires tiny blocks, so it is granted the fewest ops per guest-second exactly when it is waiting for time to pass. At the defaults that intro is being run on a machine doing ~35,000 ops per guest-second against ~100M for a real Pentium. Anything pacing itself offtimeGetTime/GetTickCount— an intro video, an animated menu, a timed fade — then renders a fraction of a frame per guest second and looks stalled, which reads convincingly as a broken decoder. Diablo's Blizzard North logo is byte-identical for 23,000 batches for exactly this reason (--trace-schedhas the main thread inside smackw32 working the whole time, and an API census counts 10,068timeGetTimecalls against 62 surface Lock/Unlock pairs) and plays straight through at--batch-size=200000. When a timed animation appears frozen, raise--batch-sizebefore you go looking for a decoder bug.CLI, by app id:
node test/run.js --app=sol— takes the exe, its DLLs, its data files and its command line fromlib/apps.js, the same registry the desktop icons read, so the CLI mounts exactly what the browser mounts.--app=with an unknown id prints the full id list. An explicit--exe/--argsoverrides the registry.PNG render:
node test/run.js --exe=path/to/exe --png=output.pngGPU stream dump:
--gpu-stream-dump=FILEtees every GPU stream v2 record (plus the arena bytes it reads) into aGPSDdump fortools/gpu-stream.js list|stats|replay(format).Remote/headless control: add
--control-stdinfor newline-delimited JSON commands on stdin. Add--frozento park before the first batch and advance only through{"action":"step","n":N}commands; snapshots and PNG captures remain available while parked. Use--max-seconds=Nas the in-process wall clock guard for controlled runs, so no externaltimeout -s KILLwrapper is needed.Real threads (CLI): guest threads use the cooperative scheduler by default;
--no-threadsselects that mode explicitly for reproducible A/B commands.--threadsinstead gives every guest thread its own nodeworker_threadover the one shared memory — the headless twin of the browser's Worker backend. The guest's main thread stays in-process, so this is not identical to the browser, but it is the only automated coverage of the shared-memory locks, the per-thread RPC blocks and the wait-completion path. The two mode flags are mutually exclusive. Add--threads-serialto run one guest thread at a time (splits "race" from "wrong per-thread state" in one run) and--thread-batch-size=Nto set the steps per worker slice (default--batch-size, min 1000 — the browser's own rule: host.js hands its main step count to every worker, so main and workers retire work at parity. The old default,--batch-size×--thread-sliceswith a 20000 floor, let workers outrun main ~27× and manufactured a startup race in Hype that no real machine and no page run has).--trace-threadalso reports why a thread got no slice this batch. Runs print acritical sections:line, aheld critical sections at exitlist (each section's owner,LockCountandRecursionCount) and a per-threadcsPark/steal,csBadLeave,waitingOnCS=… heldBy=…column whenever a guest thread blocked on aCRITICAL_SECTION. Read the held list first on any threads hang: a climbingcsParksays somebody is waiting, but only the owner/counter state says why — a section whose counters sit below the valuesInitializeCriticalSectionwrites (lock=-1 recursion=0) can never be released by the guest again, and a nonzerocsBadLeavenames the thread that put it there. A section owned by a thread that has already exited is released automatically at exit. Sections are never taken by force by default, because doing so rewritesLockCount/RecursionCountunder the owner and the guest CRT reads those —--cs-steal-after=Nturns it back on for the one measurement it is good for, telling "waiting forever" apart from "took it". Seedocs/design-real-threads.mdfor what worker mode does and does not get right yet.Child processes (CLI): a guest CreateProcess with redirected std handles always runs as a real child emulator (pipes over the vlan wire,
docs/design-anonymous-pipes.md). Any other CreateProcess only does with--spawn-processes(orspawnProcesses: trueon the app inlib/apps.js); without it the call reports success and no child runs, which installer-extraction tests rely on. A spawned child gets a snapshot of the guest's C:\ and registry, finds its exe on that C:\ (current dir, exe dir, SYSTEM, WINDOWS), and what it leaves is merged back before the parent's wait on it returns — soinstmsi -> msiinst -> msiexecinstalls Windows Installer in one run.--pipe-child-args="..."passes flags to every child down the tree (--input=B:dlg-cmd:IDanswers a grandchild's dialog). Each child is another 512 MB guest: a three-level chain is boat-sized. The browser does the same with visible in-page instances (host.jsprocess_spawn,VirtualFS.mergeChildFrom).Memory child handoff:
--spawn-processes --child-transport=memoryforks real CLI hosts for ordinary CreateProcess/ShellExecute/WinExec children and grandchildren. The default--child-transport=diskretains the host-tree transport. Memory mode sends PE bytes, the private writable C: namespace, empty directories, file names, attributes, FILETIMEs, C: volume metadata and registry/INI state over token-bound, sequenced, hashed Node IPC chunks. It preserves raw command-line spelling, quotes and spacing in GetCommandLineA/W, and explicit/inherited cwd. The current startup layout supports ASCII raw lines up to 383 bytes and parsed arguments up to 200 bytes; memory launches outside those bounds fail closed, rather than silently truncating them. Readonly drives carry source-owned mount recipes and pins; children reopen and verify the original sources without exporting media bytes. Writable lazy entries must support synchronous materialization. Other writable drives and redirected-pipe children are currently refused in memory mode. Launch faults fail closed instead of falling back to a trace-only process ACK.Each child sees a fork-time snapshot, not live parent/sibling edits. After a normal guest ExitProcess (including nonzero exit), a complete validated delta merges changed files, directories and whiteouts before its wait is signaled. Untouched parent files and registry keys survive. Conflicting parent writes, open parent file handles, changed registry keys, altered volume/source ownership, malformed/incomplete IPC, host failure and cancellation reject the delta. Refused writes restore the original namespace, bytes, metadata and registry before returning failure; watcher notifications are deferred until commit. A hook with irreversible external side effects is outside that transaction; an exceptional rollback failure is explicitly
partialApplied. A guest-exit message alone never permits merging: the native host must exit and both output pipes must close. Guest process handles keep virtual IDs; optionalWINE_COM_PROTOCOL_DIRreceipts correlate them with actual OS PIDs, exits, EOFs and merge results. A normally exiting parent keeps its host and desktop authority until its children drain. Cancellation terminates children and discards their deltas. Volatile installation lasts only for that process tree; this provides no durable installation or concurrent shared filesystem.Prefer the CLI's own
--max-seconds=Nguard. Controlled test harnesses should launchrun.jsdirectly and ask it to stop or quit over stdio; do not wrap normal runs intimeout -s KILL. The internal guard is checked between batches, preserves shutdown diagnostics and lets the process clean up. An external SIGKILL deadline is only a last-resort harness guard for an untrusted regression that might never return from one WASM batch.
Superseded shared-worktree defaults (preserved baseline)
The paragraph below preserves the pre-reconciliation shared text verbatim. The current defaults and instructions are in the Run section above.
- Real threads (CLI): guest threads use the cooperative scheduler by default;
--no-threadsselects that mode explicitly for reproducible A/B commands.--threadsinstead gives every guest thread its own nodeworker_threadover the one shared memory — the headless twin of the browser's Worker backend. The guest's main thread stays in-process, so this is not identical to the browser, but it is the only automated coverage of the shared-memory locks, the per-thread RPC blocks and the wait-completion path. The two mode flags are mutually exclusive. Add--threads-serialto run one guest thread at a time (splits "race" from "wrong per-thread state" in one run) and--thread-batch-size=Nto set the steps per worker slice (default--batch-size×--thread-slices, min 20000 — not--batch-size, which is tuned for the opposite constraint).--trace-threadalso reports why a thread got no slice this batch. Runs print acritical sections:line, aheld critical sections at exitlist (each section's owner,LockCountandRecursionCount) and a per-threadcsPark/steal,csBadLeave,waitingOnCS=… heldBy=…column whenever a guest thread blocked on aCRITICAL_SECTION. Read the held list first on any threads hang: a climbingcsParksays somebody is waiting, but only the owner/counter state says why — a section whose counters sit below the valuesInitializeCriticalSectionwrites (lock=-1 recursion=0) can never be released by the guest again, and a nonzerocsBadLeavenames the thread that put it there. A section owned by a thread that has already exited is released automatically at exit. Sections are never taken by force by default, because doing so rewritesLockCount/RecursionCountunder the owner and the guest CRT reads those —--cs-steal-after=Nturns it back on for the one measurement it is good for, telling "waiting forever" apart from "took it". Seedocs/design-real-threads.mdfor what worker mode does and does not get right yet.