omakit 0.5.1 → 0.6.1

package/skills/omarchy-plugin-build/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: omarchy-plugin-build
+description: Build the process and state plumbing of an Omarchy Quattro plugin with omakit's Run and Store blocks instead of a bare QML Process or a FileView write. Use whenever plugin code starts a program (a Process block, execDetached, a helper script, a poll) or keeps a file of its own (state, a cache, remembered choices), when inspect shows a process-lifecycle, unbounded-buffering, environment-trust or file-and-state-boundary row, or when a review comment names a deadline, an output cap, PATH, the environment, an orphaned process, a symlink, /tmp, an atomic write or a permission. Adds tested, versioned files the plugin owns; posts nothing.
+---
+
+# Build with the Run and Store blocks
+
+This is the build job: copy the measured process and private-state plumbing
+into the plugin before checking, tracking or proving anything around it.
+
+## Start every process through Run
+
+Whenever plugin code starts a program, it goes through the Run block, never
+through a bare `Process {`, `Quickshell.execDetached` or a shell string.
+Add the block once, from the plugin's directory:
+
+```bash
+omakit add run <path-to-the-plugin-repo>
+```
+
+That writes `omakit/Run.qml`, `omakit/run-supervisor.py` and
+`omakit/NOTICE` into the plugin's tree, each with a header naming the
+block, its version, the MIT licence, the omakit commit and the body's
+sha256, and nothing else. Commit them with the plugin: they are the
+plugin's files now. Then, in the QML that starts the program:
+
+```qml
+import "omakit"
+
+Run {
+    id: catalog
+    command: [Quickshell.env("HOME") + "/.config/omarchy/plugins/<id>/catalog.sh", "--refresh"]
+    deadlineMs: 30000
+    onFinished: result => {
+        if (result.state === "ok") model.parse(result.stdout)
+        else status.text = result.state + (result.reason ? ": " + result.reason : "")
+    }
+}
+```
+
+and `catalog.start()` where the program should run. The rules Run holds,
+and the count of review comments in one week that asked for each, are in
+`docs/BLOCKS.md`. The ones that shape the call:
+
+- `command[0]` is an absolute path. Omarchy's own commands are under
+  `Quickshell.env("HOME") + "/.local/share/omarchy/bin/"`; the plugin's
+  own helpers under its plugin directory; system tools under `/usr/bin/`.
+  A bare name is `spawn-failed` with the reason.
+- `command` is argv. `["/usr/bin/bash", "-c", "..."]` is refused; write
+  the helper as a file and pass its path. `allowShellString: true` exists
+  for the one case that cannot be a file, on its own line, where a reviewer
+  sees it.
+- The program sees `PATH=/usr/bin`, `HOME`, `LANG`, `XDG_RUNTIME_DIR` and
+  what `environment: ({ ... })` adds. Nothing else. A helper that needs a
+  variable gets it there, by name.
+- `deadlineMs` is when the run ends whatever the program does; pick it for
+  the slow case and let `timeout` be the state that tells the user.
+- `result.stdout` and `result.stderr` are bounded plain text with control
+  characters removed; bind them to a `Text` with `textFormat:
+  Text.PlainText`, never to rich text.
+- `result.state` is one of `ok`, `exit`, `timeout`, `overflow`,
+  `cancelled`, `spawn-failed`, `supervisor-lost`, `python-missing`. Handle
+  `ok` and show the state word for the rest; every failure state carries
+  `reason` or `stderr` for the details.
+- A `start()` on a live run cancels it and follows; destroying the
+  component ends the group. Do not add a `Timer` that kills, a
+  `Component.onDestruction` that signals, or a `StdioCollector`: the block
+  does those, and inspect knows it.
+
+## Never edit the block's files
+
+`omakit inspect` recognises an unmodified block by the sha256 in its header
+and lists it as one row that raises nothing; a modified copy is reported
+as modified and read like any other file, and `omakit add run --update`
+refuses to overwrite it. If the block lacks something, the fix belongs in
+omakit; open an issue there, keep the copy unmodified, and put what the
+plugin needs on the plugin's side of the API.
+
+Update the copy when omakit ships a new block version:
+
+```bash
+omakit add run <path-to-the-plugin-repo> --update
+```
+
+## Helpers that also run outside Run
+
+A helper Run starts inherits the closed environment, and so does every
+program the helper starts by bare name: `jq`, `find`, `curl` inside it
+resolve in `/usr/bin` and nowhere else, which is what the review asks for
+at that boundary. Nothing in the helper has to change for that.
+
+A helper that also runs where Run did not start it (a hook Omarchy runs
+from `hooks/`, a test, a terminal) starts with these three lines, its
+own, on the plugin's side:
+
+```bash
+PATH=/usr/bin
+unset BASH_ENV ENV
+set -euo pipefail
+```
+
+## Check the result
+
+After adding the block and moving each site to it, run the check loop of
+`skills/omarchy-plugin-check/SKILL.md`. `omakit inspect` should show one
+`blocks` line, `run 0.2.1, 2 files, unmodified: no row of its own`, each
+`Run {` site as a process with its deadline observed through the block,
+and no process-lifecycle or unbounded-buffering row at those sites. A row
+that remains names a site that still uses `Process` directly.
+
+## Keep state through Store
+
+Whenever plugin code keeps a file of its own (remembered choices, a
+cache it parses, anything under `~/.local/state` or `~/.cache`), it goes
+through the Store block, never through a `FileView` write, a shell
+redirect or a helper's own `open()`:
+
+```bash
+omakit add store <path-to-the-plugin-repo>
+```
+
+That writes `omakit/Store.qml` and `omakit/store-helper.py`, and the
+run block if it is not there yet, since Store starts its helper through
+Run. Then, in the QML that keeps the state:
+
+```qml
+import "omakit"
+
+Store {
+    id: memory
+    pluginId: "<the plugin's id>"
+    name: "memory.json"
+    schema: ({ type: "object", required: ["version"], properties: { version: { type: "integer", minimum: 1 } }, additionalProperties: false })
+    onFinished: result => {
+        if (result.op === "read" && result.state === "ok") apply(result.value)
+        else if (result.state !== "missing") status.text = result.state + ": " + result.reason
+    }
+}
+```
+
+`memory.read()`, `memory.write(value)` and `memory.remove()` queue and run
+one at a time; each answers once through `finished` with `op`, `state`
+and, for a read, `value`. The rules Store holds and the review comments
+that asked for each are in `docs/BLOCKS.md`; the ones that shape the call:
+
+- `pluginId` names the private directory, `$XDG_STATE_HOME/<pluginId>`
+  (or the cache base with `kind: "cache"`), created 0700; `name` is one
+  file in it. Nothing else of the plugin's touches that directory.
+- Always give a `schema`. A read that departs from it is `invalid` with
+  the path that departs, and the plugin shows the state word instead of
+  using the value; a write is checked the same way before it starts.
+- A write is one value of at most 64 KiB. A cache a helper downloads is
+  the helper's own transaction (`store-helper.py` is the same code,
+  importable); Store keeps the plugin's state.
+- `result.state` is one of `ok`, `missing`, `invalid`, `refused`,
+  `overflow`, `failed`, `helper-failed`. Treat `missing` as a first run
+  and every other non-`ok` state as "show the reason, keep the defaults".
+- Do not stat, test or read the file by path first; the block never does,
+  and a check before the open is what the review calls check-then-use.
+
+`omakit inspect` lists an unmodified store block as one row and each
+`Store {}` site as a write under a directory the plugin controls at mode
+0600; a `FileView` write or a shell redirect that remains names a site
+that still keeps state on its own.

package/skills/omarchy-plugin-check/SKILL.md

@@ -3,7 +3,10 @@ name: omarchy-plugin-check
 description: Check an Omarchy Quattro plugin while building or changing it, before committing or pushing. Use whenever you create, edit, refactor or test an Omarchy plugin, when asked whether a plugin is marketplace-ready, or before any push to its default branch. Runs the marketplace's own security baseline and submission checks locally, read-only, reports what the marketplace would refuse, and lists what the tree does (processes, hosts, writes, timers) as observations beside the review classes a human reviewer raises most.
 ---
 
-# Checking a plugin while you build it
+# Check a plugin while building it
+
+This is the check job: inspect the tree, run the marketplace's own baseline,
+and run every submission check locally before a person sees the result.
 
 ## Run this the way you run a test suite
 
@@ -111,8 +114,8 @@ fetches a sparse read-only checkout of one marketplace commit under
 
 `submit --json` ends with `outcome`:
 
-- `ready`, exit 0: every blocking check passed. The plugin would be accepted
-  by the marketplace's automated checks as it is now.
+- `ready`, exit 0: every blocking check passed and the title and body were
+  produced. This is not review approval or a safety claim.
 - `refused`, exit 1: a blocking check failed. `blocking` lists the root
   causes; each check carries `detail`, `paths`, `remedy` and `why`.
 - `listed`, exit 0: the plugin is already listed by this repository.

package/skills/omarchy-plugin-submit/SKILL.md

@@ -3,7 +3,10 @@ name: omarchy-plugin-submit
 description: Submit an Omarchy Quattro plugin to the plugin marketplace on its owner's behalf. Use when asked to submit, list or publish a plugin to the Omarchy marketplace, or to check whether a plugin is ready to submit. Runs every pre-submission check, produces the exact issue title and body, and posts nothing.
 ---
 
-# Submitting an Omarchy plugin
+# Check before submitting
+
+Submission is the last part of the check job. The command produces the exact
+title and body after the local checks, and the owner decides what happens next.
 
 ## The one thing to get right
 

package/skills/omarchy-plugin-validation-watch/SKILL.md

@@ -3,7 +3,10 @@ name: omarchy-plugin-validation-watch
 description: Diagnose an Omarchy marketplace plugin submission that has gone quiet or is stuck waiting. Use when a submission issue has had no progress, when a reviewer asked for a fresh validation, or when fixes were pushed but nothing happened. Checks whether the validated commit has fallen behind the repository and names the one action that re-runs validation.
 ---
 
-# A submission that has gone quiet
+# Track a submission that has gone quiet
+
+This is one half of the track job: compare the commit the marketplace validated
+with the repository's current commit, then name the next action without posting.
 
 ## The mechanism, first
 
@@ -23,7 +26,7 @@ comparisons were stale (62.8%), with 64 of 583 issues unknown. The older
 2026-09-12 sample found 68/93 readable issues stale (73.1%); that rate was
 not a measurement of all 464 issues in the queue.
 
-## Check it
+## Run the check
 
 ```bash
 omakit watch https://github.com/omacom/omarchy-plugin-marketplace/issues/<number>

package/skills/omarchy-plugin-weigh/SKILL.md

@@ -3,7 +3,11 @@ name: omarchy-plugin-weigh
 description: Weigh an Omarchy Quattro plugin on the shell, in CPU and child processes, by restarting the shell without it and with it. Use before a submission, after a change that adds a timer, a process or a file watcher, or when asked how heavy a plugin is. Restarts the person's shell, so it must never run without their explicit agreement.
 ---
 
-# What a plugin weighs on the shell
+# Measure what a plugin weighs on the shell
+
+Weigh supplies supporting evidence beside the four jobs. Prove remains the
+disposable guest through `omakit lab prove`; weigh is the consented desktop A/B
+measurement of CPU and child processes.
 
 ## The one thing to get right
 
@@ -34,7 +38,14 @@ one sentence naming what is missing, is how it refuses an Omarchy it cannot
 weigh on: no `omarchy-shell` (an install older than the Quattro shell), no
 `omarchy-restart-shell`, no readable version, a shell that does not answer
 `ping`, or an IPC target without the four methods it relies on. Report that
-sentence to the person as it is; do not work around it.
+sentence to the person as it is; do not work around it. A
+`shell.json.omakit-backup-<stamp>` already beside `shell.json` is refused
+the same way (`backup-present`): an earlier measurement did not finish its
+restore. Show the person the sentence and the restore it names; never copy,
+move or remove that backup yourself, and never run the measurement in a
+way that can be killed without notice (a tool timeout, a closing terminal):
+a `SIGKILL` is the one exit that leaves `shell.json` on the measurement's
+configuration.
 
 ## When to run it
 

package/tests/fixtures/weigh/clean/Widget.qml

@@ -0,0 +1,19 @@
+import QtQuick
+
+// Nothing here wakes up. The word "Timer" in this comment must not count,
+// and neither must the string below.
+Item {
+  id: root
+  property var bar: null
+  property string moduleName: ""
+  property var settings: ({})
+  property string label: "Timer { interval: 1 }"
+
+  implicitWidth: text.implicitWidth
+  implicitHeight: text.implicitHeight
+
+  Text {
+    id: text
+    text: "clean"
+  }
+}

package/tests/fixtures/weigh/clean/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "id": "fixture.clean",
+  "name": "Fixture: clean",
+  "version": "0.0.1",
+  "description": "A bar widget that declares no timers, processes or watchers.",
+  "kinds": ["bar-widget"],
+  "entryPoints": { "barWidget": "Widget.qml" }
+}

package/tests/fixtures/weigh/clean/tests/harness.qml

@@ -0,0 +1,7 @@
+import QtQuick
+
+// A test harness that ships with the plugin. The shell never loads it, so
+// its timer must not count.
+Item {
+  Timer { interval: 10; repeat: true; running: true }
+}

package/tests/fixtures/weigh/idle-panel/Panel.qml

@@ -0,0 +1,65 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import Quickshell.Hyprland
+
+Item {
+  id: root
+  property var shell: null
+  property bool opened: false
+  property int brightness: 0
+  property string state: ""
+
+  function open(payloadJson) { opened = true; refresh() }
+  function close() { opened = false; retry.stop() }
+  function refresh() { stateProc.running = true }
+  function setBrightness(value) { brightness = value; brightnessDebounce.restart() }
+
+  // Runs only while the panel is open: conditional, zero declared wakeups.
+  Timer {
+    interval: 5000
+    running: root.opened
+    repeat: true
+    onTriggered: root.refresh()
+  }
+
+  // One-shot debounce: never a wakeup source on its own.
+  Timer {
+    id: brightnessDebounce
+    interval: 180
+    repeat: false
+    onTriggered: root.setBrightness(root.brightness)
+  }
+
+  // Declared off, started from code in two places.
+  Timer {
+    id: retry
+    interval: 1000
+    repeat: true
+    onTriggered: root.refresh()
+  }
+
+  Process {
+    id: stateProc
+    command: ["omarchy-monitor-state"]
+    stdout: StdioCollector { waitForEnd: true; onStreamFinished: root.state = String(text) }
+  }
+
+  FileView {
+    id: toggles
+    path: Quickshell.env("HOME") + "/.local/state/omarchy/toggles"
+    watchChanges: true
+    onFileChanged: { reload(); retry.start() }
+  }
+
+  Connections {
+    target: Hyprland
+    function onRawEvent(event) { retry.running = true }
+  }
+
+  // Quickshell's clock ticks at its precision, once a minute here.
+  SystemClock {
+    id: clock
+    precision: SystemClock.Minutes
+  }
+}

package/tests/fixtures/weigh/idle-panel/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "id": "fixture.idle-panel",
+  "name": "Fixture: idle when closed",
+  "version": "0.0.1",
+  "description": "A panel whose 5 s timer runs only while open, plus a debounce, a code-started timer and a once-a-minute SystemClock.",
+  "kinds": ["panel"],
+  "entryPoints": { "panel": "Panel.qml" }
+}

package/tests/fixtures/weigh/poller/Service.qml

@@ -0,0 +1,50 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+
+QtObject {
+  id: root
+  property string loadavg: ""
+  property string helperPath: Quickshell.env("HOME") + "/.config/omarchy/plugins/fixture.poller/bin/helper"
+
+  // A poller: the timer restarts the process every 5 seconds (60 * 1000 / 12).
+  property Timer poll: Timer {
+    interval: 60 * 1000 / 12
+    repeat: true
+    running: true
+    triggeredOnStart: true
+    onTriggered: reader.running = true
+  }
+
+  property Process reader: Process {
+    id: reader
+    command: ["cat", "/proc/loadavg"]
+    stdout: StdioCollector {
+      waitForEnd: true
+      onStreamFinished: root.loadavg = String(text).trim()
+    }
+  }
+
+  // Long-lived: a watcher that stays up for the life of the service.
+  property Process watcher: Process {
+    id: watcher
+    command: [
+      "inotifywait", "-m", "-q",
+      "-e", "close_write",
+      "/tmp"
+    ]
+    running: true
+    stdout: SplitParser { onRead: function(line) { root.loadavg = line } }
+  }
+
+  // Dynamic: the executable is built from the plugin's own directory.
+  property Process helper: Process { id: helper; command: [root.helperPath, "status"]; running: true }
+
+  function refresh() {
+    helper.command = [root.helperPath, "refresh", "--now"]
+    helper.running = true
+    Quickshell.execDetached(["notify-send", "fixture", "refreshed"])
+  }
+
+  Component.onCompleted: Quickshell.execDetached([root.helperPath, "hello"])
+}

package/tests/fixtures/weigh/poller/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "id": "fixture.poller",
+  "name": "Fixture: poller",
+  "version": "0.0.1",
+  "description": "A service that runs a command every 5 s, one long-lived watcher process, and one dynamic command.",
+  "kinds": ["service"],
+  "entryPoints": { "service": "Service.qml" }
+}

package/tests/fixtures/weigh/timer-180ms/Widget.qml

@@ -0,0 +1,25 @@
+import QtQuick
+
+Item {
+  id: root
+  property var bar: null
+  property string moduleName: ""
+  property var settings: ({})
+  property int ticks: 0
+
+  implicitWidth: text.implicitWidth
+  implicitHeight: text.implicitHeight
+
+  Text {
+    id: text
+    text: String(root.ticks)
+  }
+
+  Timer {
+    id: tick
+    interval: 180
+    repeat: true
+    running: true
+    onTriggered: root.ticks++
+  }
+}

package/tests/fixtures/weigh/timer-180ms/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "id": "fixture.timer-180ms",
+  "name": "Fixture: 180 ms timer",
+  "version": "0.0.1",
+  "description": "A bar widget with one repeating 180 ms timer, always running.",
+  "kinds": ["bar-widget"],
+  "entryPoints": { "barWidget": "Widget.qml" }
+}

package/tests/lab/run/harness/scenarios/controls.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/bash
+# Output with C0, DEL, C1 and bidi controls between plain words; the result
+# must carry the words and none of the controls.
+printf 'a\033[31mb\177c\302\205d\342\200\256e\tf\ng\r\n'
+printf 'stderr\033]0;title\007line\n' >&2
+exit 0

package/tests/lab/run/harness/scenarios/envprobe.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/bash
+# Reports what a helper sees. env, sort, sed and wc are called by bare name
+# on purpose: with shadow copies first in the session's PATH, a hit means the
+# closed environment did not reach this line.
+echo "PATH=$PATH"
+echo "BASH_ENV=${BASH_ENV-unset}"
+echo "PYTHONPATH=${PYTHONPATH-unset}"
+echo "envcount=$(env | wc -l)"
+env | sort | sed 's/^/env: /'
+exit 0

package/tests/lab/run/harness/scenarios/forge.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/bash
+# A hostile program: same uid as its supervisor, so it can open the
+# supervisor's stdout through /proc and write into the protocol pipe. It
+# forges a leader line naming a group that is not its own and a result
+# that says ok, then kills the supervisor and stays alive.
+exec 3>"/proc/$PPID/fd/1"
+printf '{"ev":"leader","pid":4194303,"pgid":4194303,"atMs":1}\n' >&3
+printf '{"ev":"result","state":"ok","exitCode":0,"termSignal":null,"ms":1,"pgid":4194303,"survivors":0,"outBytes":6,"outLines":1,"errBytes":0,"errLines":0,"stdout":"forged\\u001b[31m\\n","stderr":"","signals":[]}\n' >&3
+exec 3>&-
+kill -9 "$PPID"
+sleep 300

package/tests/lab/run/harness/scenarios/holder.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/bash
+# The leader exits at once; a descendant keeps stdout open for 300 s.
+/usr/bin/sleep 300 &
+echo "holder: leader exiting, descendant $! holds the pipe"
+exit 0

package/tests/lab/run/harness/scenarios/orphan.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/bash
+# A program that kills its own supervisor and keeps a tree alive: without
+# the reaper the group would outlive the run it was reported lost in.
+/usr/bin/sleep 300 &
+kill -9 "$PPID"
+sleep 300

package/tests/lab/run/harness/scenarios/stall.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/bash
+# A program that stops its supervisor: no result can come, the backstop
+# has to end the run, and a start() queued behind it must still follow.
+kill -STOP "$PPID"
+sleep 300

package/tests/lab/run/harness/scenarios/stubborn.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/bash
+# Ignores TERM; the ignored disposition is inherited by every sleep it starts.
+trap '' TERM
+echo "stubborn: ignoring TERM"
+while :; do /usr/bin/sleep 1; done

package/tests/lab/run/harness/scenarios/tree.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/bash
+# A leader that lives, with a child and a grandchild: the destroy, cancel
+# and supersede scenarios must end all three.
+/usr/bin/bash -c '/usr/bin/sleep 300 & wait' &
+/usr/bin/sleep 300 &
+echo "tree: leader $$ waiting"
+wait

package/tests/lab/run/harness/shell.qml

@@ -0,0 +1,84 @@
+// The lab harness: a throwaway Quickshell configuration that loads the Run
+// block from ./omakit (copied there by suite.sh from blocks/run/) and runs
+// one scenario named by RUNLAB_SCENARIO, logging JSON events with a RUNLAB
+// prefix for the driver to read. Never loaded into omarchy-shell.
+import QtQuick
+import Quickshell
+import "omakit"
+
+ShellRoot {
+    id: root
+    property string scenario: Quickshell.env("RUNLAB_SCENARIO")
+    property string base: Quickshell.env("RUNLAB_BASE")
+    property int keep: Number(Quickshell.env("RUNLAB_KEEP") || 65536)
+    property var table: ({
+        "producer":        { command: ["/usr/bin/head", "-c", "1073741824", "/dev/zero"], deadlineMs: 60000, graceMs: 1000, maxBytes: 1048576 },
+        "producer-stream": { command: ["/usr/bin/head", "-c", "1073741824", "/dev/zero"], deadlineMs: 120000, graceMs: 1000, maxBytes: 2147483647 },
+        "holder":          { command: ["/usr/bin/bash", base + "/scenarios/holder.sh"], deadlineMs: 10000, graceMs: 1000, maxBytes: 65536 },
+        "stubborn":        { command: ["/usr/bin/bash", base + "/scenarios/stubborn.sh"], deadlineMs: 2000, graceMs: 1000, maxBytes: 65536 },
+        "hostile":         { command: ["/usr/bin/bash", base + "/scenarios/envprobe.sh"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 },
+        "destroy":         { command: ["/usr/bin/bash", base + "/scenarios/tree.sh"], deadlineMs: 10000, graceMs: 1000, maxBytes: 65536, destroyAfterMs: 500 },
+        "cancel":          { command: ["/usr/bin/bash", base + "/scenarios/tree.sh"], deadlineMs: 10000, graceMs: 1000, maxBytes: 65536, cancelAfterMs: 500 },
+        "supersede":       { command: ["/usr/bin/bash", base + "/scenarios/tree.sh"], deadlineMs: 10000, graceMs: 1000, maxBytes: 65536, supersedeAfterMs: 500 },
+        "shell-string":    { command: ["/usr/bin/bash", "-c", "echo never"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 },
+        "relative":        { command: ["bash", base + "/scenarios/envprobe.sh"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 },
+        "missing":         { command: ["/usr/bin/no-such-program-runlab"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 },
+        "controls":        { command: ["/usr/bin/bash", base + "/scenarios/controls.sh"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 },
+        "concurrency":     { command: ["/usr/bin/head", "-c", "1048576", "/dev/zero"], deadlineMs: 30000, graceMs: 1000, maxBytes: 2097152, count: 10 },
+        "forge":           { command: ["/usr/bin/bash", base + "/scenarios/forge.sh"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 },
+        "orphan":          { command: ["/usr/bin/bash", base + "/scenarios/orphan.sh"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 },
+        "stalled-supersede": { command: ["/usr/bin/bash", base + "/scenarios/stall.sh"], deadlineMs: 2000, graceMs: 500, maxBytes: 65536, supersedeAfterMs: 500 },
+        "destroy-early":   { command: ["/usr/bin/bash", base + "/scenarios/tree.sh"], deadlineMs: 10000, graceMs: 1000, maxBytes: 65536, destroyBusyMs: 300 },
+        "shell-string-option": { command: ["/usr/bin/bash", "-o", "pipefail", "-c", "echo never"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 },
+        "shell-string-wrapper": { command: ["/usr/bin/env", "bash", "-c", "echo never"], deadlineMs: 5000, graceMs: 1000, maxBytes: 65536 }
+    })
+    property var runs: []
+    property int finishedCount: 0
+
+    function log(o) { console.log("RUNLAB " + JSON.stringify(o)) }
+
+    property Component runComponent: Component { Run {} }
+
+    function create(spec, index) {
+        const object = root.runComponent.createObject(root, { command: spec.command, deadlineMs: spec.deadlineMs, graceMs: spec.graceMs, maxBytes: spec.maxBytes, keepBytes: root.keep })
+        object.finished.connect(result => { result.ev = "result"; result.index = index; root.finishedCount += 1; root.log(result); if (root.finishedCount === (spec.count || 1)) root.log({ ev: "all-finished", t: Date.now() }) })
+        return object
+    }
+
+    property Timer starter: Timer {
+        interval: 3000; running: true
+        onTriggered: {
+            const spec = root.table[root.scenario]
+            const count = spec.count || 1
+            const objects = []
+            for (let index = 0; index < count; index += 1) objects.push(root.create(spec, index))
+            root.runs = objects
+            root.log({ ev: "start", scenario: root.scenario, count: count, t: Date.now() })
+            for (const object of objects) object.start()
+            if (spec.destroyBusyMs) {
+                // The event loop is held after start(), so the supervisor has
+                // forked the program but this side has not read its leader line
+                // when the object is destroyed on the next turn.
+                const until = Date.now() + spec.destroyBusyMs
+                while (Date.now() < until) {}
+                root.log({ ev: "destroy", pgid: objects[0]._pgid, t: Date.now() })
+                objects[0].destroy(); root.runs = []
+            }
+            if (spec.destroyAfterMs) { root.later.mode = "destroy"; root.later.interval = spec.destroyAfterMs; root.later.start() }
+            if (spec.cancelAfterMs) { root.later.mode = "cancel"; root.later.interval = spec.cancelAfterMs; root.later.start() }
+            if (spec.supersedeAfterMs) { root.later.mode = "supersede"; root.later.interval = spec.supersedeAfterMs; root.later.start() }
+        }
+    }
+    property Timer later: Timer {
+        property string mode: ""
+        onTriggered: {
+            const object = root.runs[0]
+            root.log({ ev: mode, pgid: object._pgid, t: Date.now() })
+            if (mode === "destroy") { object.destroy(); root.runs = [] }
+            else if (mode === "cancel") object.cancel()
+            else if (mode === "supersede") { object.command = ["/usr/bin/bash", root.base + "/scenarios/envprobe.sh"]; object.start() }
+        }
+    }
+
+    Component.onCompleted: log({ ev: "ready", pid: Quickshell.processId, scenario: scenario })
+}