omakit 0.5.1 → 0.6.1

package/README.md

@@ -1,24 +1,12 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/banner.gif" alt="omakit" width="440">
+  <img src="https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/banner.gif" alt="Animated Omakit wordmark above the line tested plumbing for plugins" width="512">
 </p>
 
-The marketplace validates one exact commit of your plugin. Push a fix or comment "fixed", and nothing re-runs ([M6](docs/MEASUREMENTS.md#m6-the-validated-commit-falls-behind-silently-and-that-is-the-centre-of-this-tool)). omakit runs the marketplace's own checks locally, watches your submission and posts nothing.
+**Tested plumbing, the marketplace's own checks, and a disposable Omarchy to test in.**
 
-[![Built for Omarchy: App](https://raw.githubusercontent.com/tcballard/omarchy-badges/75975e5b5bf75e7ede3764bcd2950046f7abfe2c/badges/v1/omarchy-app.svg)](https://github.com/tcballard/omarchy-badges) [![npm version](https://img.shields.io/npm/v/omakit)](https://www.npmjs.com/package/omakit) [![CI status](https://img.shields.io/github/actions/workflow/status/mtolhuys/omakit/ci.yml?branch=main)](https://github.com/mtolhuys/omakit/actions/workflows/ci.yml) [![Socket](https://socket.dev/api/badge/npm/package/omakit)](https://socket.dev/npm/package/omakit)
+The three parts are the Run and Store blocks a plugin copies into its own tree, the marketplace's own checks run locally, and repository suites run in a disposable guest. Behind the first are M13's 1,001 security blocker comments from one measured week: 587 raise a Run line, 527 a Store line, and runner plus store handle 777 of 1,001 when read as an upper bound, not as a result for any plugin ([M13](docs/MEASUREMENTS.md#m13-what-the-review-blocks-on-over-one-week-of-comments-and-which-of-it-a-block-can-own)). No reviewer has seen a ported plugin yet.
 
-## What it delivers
-
-| Command | What you get | Read more |
-| --- | --- | --- |
-| `omakit submit <plugin-repo>` | Run the marketplace's own checks before you open the issue, and get the issue text ready to paste. Nothing is posted for you. | [submit](docs/SUBMIT.md) |
-| `omakit inspect <plugin-dir>` | See what needs attention in your plugin before a reviewer does: the longest functions, and the things reviewers flag most often, each with the file and line. | [inspect](docs/INSPECT.md) |
-| `omakit watch <issue-url>` | Know whether the commit the marketplace checked is still the one you are shipping, and what to do when it is not. | [watch](docs/VALIDATION_WATCH.md) |
-| `omakit audit` | Find installed plugins that are running code the marketplace never checked. | [audit](docs/AUDIT.md) |
-| `omakit weigh <plugin>` | Find out what a plugin costs the shell in memory and CPU. | [weigh](docs/WEIGH.md) |
-| `omakit verify <plugin-repo>` | Get the marketplace's security result for your commit, exactly as it would see it. | [commands](docs/COMMANDS.md) |
-| `omakit doctor`, `omakit setup` | Check what is installed and pinned, or set everything up once, with tab completion. | [install](docs/INSTALL.md) |
-
-Every number a command prints has a measured origin in [MEASUREMENTS.md](docs/MEASUREMENTS.md); nothing is a guess and nothing is a grade.
+[![Built for Omarchy: App](https://raw.githubusercontent.com/tcballard/omarchy-badges/75975e5b5bf75e7ede3764bcd2950046f7abfe2c/badges/v1/omarchy-app.svg)](https://github.com/tcballard/omarchy-badges) [![npm version](https://img.shields.io/npm/v/omakit)](https://www.npmjs.com/package/omakit) [![CI status](https://img.shields.io/github/actions/workflow/status/mtolhuys/omakit/ci.yml?branch=main)](https://github.com/mtolhuys/omakit/actions/workflows/ci.yml) [![Socket package report](https://socket.dev/api/badge/npm/package/omakit)](https://socket.dev/npm/package/omakit)
 
 ## Install
 
@@ -27,54 +15,59 @@ npm i -g omakit && omakit setup
 npx skills add mtolhuys/omakit
 ```
 
-Runs where [Node 22+](package.json) and Git run; `weigh` and `audit` need a running Omarchy shell.
+Omakit needs [Node 22+](package.json) and Git. `omakit setup` prepares the pinned marketplace checkout and shell completion. The blocks also need `/usr/bin/python3`. Audit and weigh need a running Omarchy shell. The lab needs KVM, QEMU and OVMF; `omakit doctor` reports what is missing and installs nothing.
 
-Licence: [MIT](LICENSE).
+## Build
 
-## `omakit submit <plugin-repo>`
+`omakit add run <plugin-dir>` and `omakit add store <plugin-dir>` copy versioned process and private-state plumbing into the plugin's `omakit/` directory; the plugin owns those files, and an edited copy is never overwritten. Commit the copied files before checking, because check reads committed `HEAD` unless you pass `--allow-dirty`.
 
-![submit refusing a fixture plugin before any issue is posted](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/submit.gif)
+![Recorded terminal showing inspect before omakit add run, the copied Run files, and inspect after the fixture is ported](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/add-run.gif)
 
-Checks the exact commit with the marketplace's own baseline and, when ready, prints the exact issue title and body for you to paste. The GIF shows a refusal with three blocking checks and their fixes.
+## Check
 
-## `omakit watch --all`
+`omakit inspect <plugin-dir>` shows what the tree does, `omakit verify <plugin-repo>` runs the marketplace's baseline, and `omakit submit <plugin-repo>` runs every submission check and prints a title and body without posting them.
 
-![watch counts and two current issues, including human discussion](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/watch-all.gif)
+![Recorded terminal showing inspect ranking two long functions and listing the review class observed in a fixture](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/inspect.gif)
 
-Checks your submission commits and names the action that re-runs stale validation: edit the issue body. The GIF shows five CURRENT issues in the counts and the first two issues with a discussion; CURRENT means matching commits, not approval.
+![Recorded terminal showing submit refusing a fixture with three blocking checks and printing their remedies](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/submit.gif)
 
-## `omakit audit`
+## Track
 
-![audit keeping drift rows and the DRIFT summary visible together](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/audit.gif)
+`omakit watch --all` compares open submissions with the commits the marketplace validated, while `omakit audit` compares installed third-party plugins with their validated commits; both are read-only.
 
-Compares your installed plugin commits with the marketplace's validated commits. The GIF shows drift rows first: on the author's desktop, 9 of 18 audited plugins ran commits the marketplace never validated.
+![Recorded terminal showing watch-all count two current submissions and display their validation and discussion records](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/watch-all.gif)
 
-## `omakit inspect <plugin-dir>`
+![Recorded terminal showing audit list installed plugin drift and close with the 13-of-19 drift summary](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/audit.gif)
 
-![inspect showing a fixture's size score, its two long functions with their ranks, and the one review class it shows](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/inspect.gif)
+## Prove
 
-Reads a plugin's tree and prints what needs attention, biggest first: a size score (the share of its function lines that sit in functions over the measured size, placed among the listed trees' shares, so a tree with no long function scores 10.00, [M12](docs/MEASUREMENTS.md#m12-how-long-a-plugins-functions-are-in-listed-trees)), the functions over what 90 of 100 listed functions stay under, then each review class the tree shows with the class's measured share of review findings ([M11](docs/MEASUREMENTS.md#m11-what-the-human-review-raises-by-class)) and up to five sites. No verdict, nothing run from the tree; `--full` is every site, `--json` the document. Over 18 listed plugins read at their validated commits, the extraction counted 515 process sites (57 QML `Process` blocks, 458 shell lines), 17 hosts, 63 writes and 40 timers, left 15 rows it could not resolve, and printed 73 pattern rows across 17 of the 18 ([record](docs/evidence/inspect/2026-09-15-listed-sample.json)).
+After one `omakit lab setup`, `omakit lab prove <suite>` boots a fresh overlay from the verified base, prints the guest identity, runs Run, Store or weigh in that guest, records the result, removes the overlay and checks the base unchanged.
 
-## `omakit weigh <plugin>`
+![Recorded terminal showing omakit lab prove run identify the disposable guest, complete all 19 Run scenarios, remove the overlay, verify the unchanged base and close PROVED](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/lab-prove.gif)
 
-![completed three-run desktop weighing with baseline samples and the noise floor](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/weigh.gif)
+`omakit weigh <plugin>` is the supporting desktop measurement: after explicit consent it restarts the shell without and with the plugin, reports CPU and child processes against the baseline's own spread, and restores `shell.json`.
 
-Measures the shell with and without your plugin, reading Pss and CPU. The GIF shows three completed runs on the author's desktop, with baseline and plugin samples and a 0.33% CPU floor ([method](docs/WEIGH.md)).
+![Recorded terminal showing all six Theme Manager weigh samples, shell restoration, the CPU noise floor and the completed report](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/weigh.gif)
 
-## Evidence, not claims
+## Evidence
 
-| Measurement | Evidence |
+| What was measured | Record |
 | --- | --- |
-| Baseline parity | 30/30 identical results, [recorded corpus](docs/evidence/parity/2026-09-12-local-vs-github-2.json), 2026-09-12 |
-| Stale validated commit | 326/519 readable comparisons stale (62.8%); 64/583 unknown, [2026-09-15 data](docs/evidence/staleness/2026-09-15.json) |
-| Registry churn | 4,201/4,293 registry-only commits in 30 days, 2026-09-13, [M7](docs/MEASUREMENTS.md#m7-the-registry-moves-by-the-hour-the-code-and-the-rules-move-by-the-week) |
-| GIFs are recorded output | 6 GIFs with [captures and scenes](docs/media/README.md) |
-| Posts nothing | 0 marketplace writes, [M10](docs/MEASUREMENTS.md#m10-readme-evidence-and-command-captures) |
-| Zero dependencies | 0 runtime and 0 development dependencies, counted in [package.json](package.json) |
+| Review plumbing | 1,001 blocker comments; Run 587, Store 527, either 777, [M13 record](docs/evidence/blocks/2026-09-17-review-blockers.json) |
+| Run | 19 of 19 on the desktop and 19 of 19 on the stock 4.0.3 guest at Run 0.2.1, [desktop](docs/evidence/blocks/2026-09-18-run-lab-desktop.json), [fresh guest](docs/evidence/lab/20260919-143209-run/runlab.json) |
+| Store | 15 of 15 on the desktop and stock guest, including the simulated foreign owner, [desktop](docs/evidence/blocks/2026-09-18-store-lab-desktop.json), [guest](docs/evidence/lab/20260918-161230-store/storelab.json) |
+| The disposable guest | guest `omarchy 4.0.3-1`, skew false, 2m 42.2s, 440,209,408 B overlay removed, base unchanged, [fresh run](docs/evidence/lab/20260919-143209-run/run.json) |
+| The two ports | [Theme Manager through Run](docs/evidence/blocks/2026-09-17-theme-manager-port.json), [Sidecar through Store](docs/evidence/blocks/2026-09-17-sidecar-port.json); neither submitted, no reviewer has seen either |
+| Validation drift | 326 of 519 readable open-submission comparisons stale, 64 of 583 unknown, [dated record](docs/evidence/staleness/2026-09-15.json) |
+| README captures | eight GIFs made from committed captures and scenes, with commands, hashes, dimensions and timings in the [M10 record](docs/evidence/readme/2026-09-19-positioning.json) |
+| First-reader path | packaged install, blocks, checks, tracking and a 19-scenario guest run exercised from `/tmp`, [dated record](docs/evidence/ux/2026-09-19-readme-test.json) |
+| Package boundary | 0 runtime and 0 development dependencies in [package.json](package.json); 0 marketplace writes enforced by the read-only tests |
 
 ## Documentation
 
-- Using: [install](docs/INSTALL.md), [commands](docs/COMMANDS.md), [audience](docs/MARKETPLACE.md).
-- Checks and measurements: [submit](docs/SUBMIT.md), [inspect](docs/INSPECT.md), [watch](docs/VALIDATION_WATCH.md), [audit](docs/AUDIT.md), [evidence](docs/MEASUREMENTS.md).
-- Method docs: [how](docs/HOW.md), [weigh](docs/WEIGH.md), [upstream contract](docs/UPSTREAM_CONTRACT.md), [palette](docs/PALETTE.md), [terminal](docs/TUI.md).
-- Contributing: [repository rules](AGENTS.md), [releasing](docs/RELEASING.md), [media](docs/media/README.md).
+- [Blocks](docs/BLOCKS.md) and [their design spike](docs/BLOCKS_SPIKE.md)
+- [Commands](docs/COMMANDS.md), [inspect](docs/INSPECT.md), [submit](docs/SUBMIT.md), [watch](docs/VALIDATION_WATCH.md), [audit](docs/AUDIT.md) and [weigh](docs/WEIGH.md)
+- [The disposable lab](docs/LAB.md) and [every measurement](docs/MEASUREMENTS.md)
+- [Installation](docs/INSTALL.md), [media recipes](docs/media/README.md) and [repository rules](AGENTS.md)
+
+Licence: [MIT](LICENSE).

package/blocks/history.json

@@ -0,0 +1,68 @@
+[
+ {
+  "block": "run",
+  "version": "0.1.0",
+  "file": "Run.qml",
+  "sha256": "7055007d082b81f328b8c3e7f41e648ed27c111ef546220277f0fb7f18332e28"
+ },
+ {
+  "block": "run",
+  "version": "0.1.0",
+  "file": "run-supervisor.py",
+  "sha256": "3a1c8e18c56592e046e1ac1dfe35df5745c39cc60405dfb6d408ee4eb287ef5f"
+ },
+ {
+  "block": "store",
+  "version": "0.1.0",
+  "file": "Store.qml",
+  "sha256": "c71b5646e0b6ccc4b45e5c57a8c7ed08a089319f4ee7d3ce74ef5e28d8af3801"
+ },
+ {
+  "block": "store",
+  "version": "0.1.0",
+  "file": "store-helper.py",
+  "sha256": "28576b8189c9d2547c11b273243731a6c954644b7135186e57257addc3c99dd9"
+ },
+ {
+  "block": "store",
+  "version": "0.1.0",
+  "file": "store-helper.py",
+  "sha256": "3ef0c3f5df90ef93d3ff7cdd979159cce590a4a61b3351f42ea5123fa49f0720"
+ },
+ {
+  "block": "store",
+  "version": "0.1.0",
+  "file": "store-helper.py",
+  "sha256": "cec3fcc9573ce7c12f1365e106cc65a936e213553bfe4e3128e8a87eea511dc5"
+ },
+ {
+  "block": "run",
+  "version": "0.2.0",
+  "file": "Run.qml",
+  "sha256": "0e54a5a82aacbdcd2e61163091bbeebb597787abb285df86bf85d7d835451419"
+ },
+ {
+  "block": "run",
+  "version": "0.2.0",
+  "file": "run-supervisor.py",
+  "sha256": "07c3d5fa103fcbfc40eb081206fdd8571c6e3852a188389d79bbac12db00170d"
+ },
+ {
+  "block": "store",
+  "version": "0.2.0",
+  "file": "Store.qml",
+  "sha256": "6fafd2ec98b4d4fe18ead2ae1f1221386e9714eb9a33ef0f1b9cf48520f2c743"
+ },
+ {
+  "block": "store",
+  "version": "0.2.0",
+  "file": "store-helper.py",
+  "sha256": "2dd4d6ad308bbed473936c29844793411d8849415812b96ca5e7a6688097e37c"
+ },
+ {
+  "block": "run",
+  "version": "0.2.1",
+  "file": "run-supervisor.py",
+  "sha256": "d872a5fc91f648ba4f9b9654d5cb19bba17a8afa4abb618502a04f47f66a6be1"
+ }
+]

package/blocks/run/NOTICE

@@ -0,0 +1,12 @@
+omakit blocks in this directory
+
+Each file below was copied from omakit (https://github.com/mtolhuys/omakit),
+MIT licence, Copyright (c) 2026 Maarten Tolhuijs, by `omakit add`. The body
+sha256 is over everything after the file's header line
+`end of omakit block header`; `omakit inspect` reports a file whose body differs as
+modified, and `omakit add --update` refuses to overwrite one. Modifications
+are to be listed here by the plugin's author.
+
+block run 0.2.1, from omakit commit unstamped
+  Run.qml  sha256 0e54a5a82aacbdcd2e61163091bbeebb597787abb285df86bf85d7d835451419
+  run-supervisor.py  sha256 d872a5fc91f648ba4f9b9654d5cb19bba17a8afa4abb618502a04f47f66a6be1

package/blocks/run/Run.qml

@@ -0,0 +1,242 @@
+// omakit block: run 0.2.1
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Maarten Tolhuijs
+// Source: omakit blocks/run/Run.qml, commit unstamped
+// Body sha256: 0e54a5a82aacbdcd2e61163091bbeebb597787abb285df86bf85d7d835451419
+// end of omakit block header
+//
+// Run: starts one program for a plugin and always ends it. The program is
+// started by run-supervisor.py, next to this file, through
+// /usr/bin/python3 -I -S -B: absolute path, argv only, a closed environment,
+// a hard deadline, byte and line caps while reading, TERM then grace then
+// KILL to the whole process group, the leader reaped last, cancel on
+// destruction and on supersession, one result object. The protocol between
+// this file and the supervisor is a per-run token this file writes to the
+// supervisor's stdin: every line the supervisor reports carries it, and a
+// line without it, which is what the program can write into the same pipe,
+// changes nothing. docs/BLOCKS.md is the contract and says which review
+// comments each line answers.
+//
+//   Run {
+//     id: catalog
+//     command: [Quickshell.shellDir + "/catalog.sh", "--refresh"]
+//     deadlineMs: 30000
+//     onFinished: result => { if (result.state === "ok") parse(result.stdout) }
+//   }
+//   catalog.start()
+import QtQuick
+import Quickshell
+import Quickshell.Io
+
+QtObject {
+    id: run
+
+    // argv; command[0] an absolute path. A shell string (an interpreter with
+    // its string flag, through a wrapper or not) is refused as spawn-failed
+    // unless allowShellString; the forms it knows are in docs/BLOCKS.md.
+    property list<string> command: []
+    property bool allowShellString: false
+    // Added to the base environment, never replacing it. The base is
+    // PATH=/usr/bin, HOME, LANG=C.UTF-8 and XDG_RUNTIME_DIR; nothing else
+    // of the shell's environment reaches the program.
+    property var environment: ({})
+    property int deadlineMs: 10000
+    property int graceMs: 1000
+    // Per stream, counted while reading; over either the run ends as overflow.
+    property int maxBytes: 1048576
+    property int maxLines: 10000
+    // Per stream, what the result carries; the rest is counted and dropped.
+    property int keepBytes: 65536
+
+    readonly property bool running: _state === "running"
+    // One object: state is one of ok, exit, timeout, overflow, cancelled,
+    // spawn-failed, supervisor-lost, python-missing; stdout and stderr are
+    // plain text of at most keepBytes each, control characters removed,
+    // meant for Text.PlainText; outBytes, outLines, errBytes, errLines as
+    // counted; exitCode (null when signalled), termSignal, ms, pgid,
+    // survivors, and reason for the three failure states.
+    signal finished(var result)
+
+    readonly property string supervisor: decodeURIComponent(Qt.resolvedUrl("run-supervisor.py").toString().replace(/^file:\/\//, ""))
+    readonly property var states: ["ok", "exit", "timeout", "overflow", "cancelled", "spawn-failed", "supervisor-lost", "python-missing"]
+    property string _state: "idle"
+    property bool _started: false
+    property bool _pending: false
+    property int _pgid: 0
+    property double _t0: 0
+    property var _result: null
+    property string _supervisorErr: ""
+    property string _token: ""
+    property string _buffer: ""
+
+    readonly property var _baseEnvironment: ({
+        PATH: "/usr/bin",
+        HOME: Quickshell.env("HOME"),
+        LANG: "C.UTF-8",
+        XDG_RUNTIME_DIR: Quickshell.env("XDG_RUNTIME_DIR")
+    })
+
+    function _now() { return Date.now() - _t0 }
+
+    /** Start the program. A run already live is cancelled first, reports cancelled, and this start follows it. */
+    function start() {
+        if (_state === "running") { _pending = true; cancel(); return }
+        if (_proc.running) { _pending = true; return }    // the last supervisor is still being reaped (a backstop); it follows on runningChanged
+        _t0 = Date.now()
+        _state = "running"
+        _started = false
+        _result = null
+        _supervisorErr = ""
+        _buffer = ""
+        _pgid = 0
+        _token = _newToken()
+        _proc.command = _argv()
+        _proc.environment = Object.assign({}, _baseEnvironment, environment)
+        _proc.stdinEnabled = true
+        _backstop.interval = deadlineMs + graceMs + 3000
+        _backstop.start()
+        _proc.running = true
+    }
+
+    /** End the run now: TERM to the group, the grace, KILL; the result comes back as cancelled. */
+    function cancel() {
+        if (_state === "running") _proc.signal(15)
+    }
+
+    // 128 bits from the engine's securely seeded generator; the program never
+    // sees a value of it (stdin is consumed by the supervisor before the fork).
+    function _newToken() {
+        let token = ""
+        for (let i = 0; i < 8; i += 1) token += ("000" + Math.floor(Math.random() * 65536).toString(16)).slice(-4)
+        return token
+    }
+
+    function _argv() {
+        const options = ["--deadline-ms", String(deadlineMs), "--grace-ms", String(graceMs),
+            "--max-bytes", String(maxBytes), "--max-lines", String(maxLines), "--keep-bytes", String(keepBytes)]
+        if (allowShellString) options.push("--allow-shell-string")
+        return ["/usr/bin/python3", "-I", "-S", "-B", supervisor].concat(options, ["--"], command)
+    }
+
+    // The supervisor's stdout, delivered as it arrives: lines are cut here,
+    // and the unfinished line is bounded, so a stream without a newline
+    // cannot grow inside the shell process.
+    function _chunk(text) {
+        _buffer += text
+        let end = _buffer.indexOf("\n")
+        while (end >= 0) {
+            _line(_buffer.slice(0, end))
+            _buffer = _buffer.slice(end + 1)
+            end = _buffer.indexOf("\n")
+        }
+        const bound = 6 * keepBytes + 65536
+        if (_buffer.length > bound) _buffer = _buffer.slice(-bound)
+    }
+
+    // A protocol line carries the token; anything else on the pipe is the
+    // program's and is dropped. The first leader and the first result count.
+    function _line(line) {
+        const at = _token ? line.indexOf(_token + " ") : -1
+        if (at < 0) return
+        let event
+        try { event = JSON.parse(line.slice(at + _token.length + 1)) } catch (error) { return }
+        if (event.ev === "leader") _leader(event)
+        else if (event.ev === "result" && !_result) _result = _checked(event)
+    }
+
+    // The first leader line names the group; the acknowledgement releases the
+    // supervisor's gate, and stdin closes behind it.
+    function _leader(event) {
+        if (_pgid !== 0 || _int(event.pgid) === 0) return
+        _pgid = _int(event.pgid)
+        _proc.write("go\n")
+        _proc.stdinEnabled = false
+    }
+
+    function _int(value) { return Number.isInteger(value) && value >= 0 ? value : 0 }
+    function _intOrNull(value) { return Number.isInteger(value) ? value : null }
+    function _text(value, max) { return _plain(String(value == null ? "" : value)).slice(0, max) }
+
+    /** The result as this file reports it: the closed set of states, the numbers as integers, the text stripped here as well. */
+    function _checked(event) {
+        if (!states.includes(event.state)) return null
+        return {
+            state: event.state, exitCode: _intOrNull(event.exitCode), termSignal: _intOrNull(event.termSignal),
+            outBytes: _int(event.outBytes), outLines: _int(event.outLines), errBytes: _int(event.errBytes), errLines: _int(event.errLines),
+            survivors: _int(event.survivors), stdout: _text(event.stdout, keepBytes), stderr: _text(event.stderr, keepBytes),
+            reason: event.reason == null ? null : _text(event.reason, 4096),
+            signals: Array.isArray(event.signals) ? event.signals.filter(s => s && typeof s.sig === "string").map(s => ({ sig: s.sig.slice(0, 8), atMs: _int(s.atMs), esrch: s.esrch === true })) : []
+        }
+    }
+
+    function _plain(text) {
+        return String(text).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "")
+    }
+
+    function _lost(reason) {
+        return { state: "supervisor-lost", reason: reason, stderr: _plain(_supervisorErr).slice(0, 4096) }
+    }
+
+    // The supervisor is gone without a valid result: whatever it started is
+    // ended by the detached reaper, and the result says so.
+    function _reap(reason) {
+        if (_pgid !== 0) {
+            Quickshell.execDetached(["/usr/bin/python3", "-I", "-S", "-B", supervisor, "--kill-group", String(_pgid), "--grace-ms", String(graceMs)])
+            reason += "; the group " + _pgid + " was sent TERM and, after the grace, KILL by a detached reaper"
+        }
+        _finish(_lost(reason))
+    }
+
+    function _onExited(code, status) {
+        if (_state !== "running") return
+        _backstop.stop()
+        if (_result) { _finish(_result); return }
+        if (code === 2 && /can.t open file/.test(_supervisorErr)) { _reap("run-supervisor.py is not readable at " + supervisor); return }
+        _reap("the supervisor " + (status === 1 ? "died on signal " : "exited ") + code + " without a result")
+    }
+
+    function _onRunningChanged() {
+        // Never started: the interpreter itself could not be run (stock
+        // Omarchy has it; docs/BLOCKS.md says why it is checked anyway).
+        if (!_proc.running && _state === "running" && !_started) {
+            _backstop.stop()
+            _finish({ state: "python-missing", reason: "/usr/bin/python3 could not be started" })
+        } else if (!_proc.running && _pending) { _pending = false; start() }
+    }
+
+    function _finish(result) {
+        _state = "done"
+        result.pgid = _pgid
+        result.ms = _now()
+        finished(result)
+        if (_pending && !_proc.running) { _pending = false; start() }
+    }
+
+    property Timer _backstop: Timer {
+        onTriggered: {
+            if (run._pgid !== 0) Quickshell.execDetached(["/usr/bin/kill", "-s", "KILL", "--", "-" + run._pgid])
+            run._proc.signal(9)
+            run._finish(run._lost("no result " + run._backstop.interval + " ms after start; the group was sent KILL"))
+        }
+    }
+
+    property Process _proc: Process {
+        clearEnvironment: true
+        stdinEnabled: true
+        stdout: SplitParser { splitMarker: ""; onRead: text => run._chunk(text) }
+        stderr: SplitParser { splitMarker: ""; onRead: text => { if (run._supervisorErr.length < 4096) run._supervisorErr += String(text).slice(0, 4096) } }
+        onStarted: { run._started = true; run._proc.write(run._token + "\n") }
+        onExited: (code, status) => run._onExited(code, status)
+        onRunningChanged: run._onRunningChanged()
+    }
+
+    Component.onDestruction: {
+        // The Process destructor SIGKILLs the supervisor right after this, so
+        // the group is ended by a detached reaper: TERM, the grace, KILL. A
+        // run whose leader this file never learned is still behind the
+        // supervisor's gate and exits unrun when the supervisor dies.
+        if (_state === "running" && _pgid !== 0) {
+            Quickshell.execDetached(["/usr/bin/python3", "-I", "-S", "-B", supervisor, "--kill-group", String(_pgid), "--grace-ms", String(graceMs)])
+        }
+    }
+}