@brainervirus/workit-core 8.15.1 → 8.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.15.1",
+  "version": "8.17.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-fanout/SKILL.md

@@ -5,13 +5,13 @@ description: Run independent slices in parallel - one worker per isolated worktr
 
 # Fan out parallel workers
 
-Fan out only independent slices: disjoint files, no shared mutable state, each
-verifiable alone. Code-coupled work stays with one owner, who fans out after
-the blocking part lands. A worker whose whole job is re-running one command is
-ceremony; do it yourself. Workit never spawns agents; you do.
+Inline-first (workspace `delegation`): fan out only past a threshold, named as
+each slice's `reason` (explore, parallel, backstop, high-risk-verify): an
+explorer past ~3 tool calls or 10k tokens; parallel writers only for 2+ disjoint
+units of ~100+ lines each. Coupled work stays with one owner. Workit never spawns.
 
 1. **Plan the slices** (workit-shape) in a plan file (`references/brief.md`):
-   per slice an id, branch, TIER, SCOPE globs, `owns` for shared files,
+   per slice an id, branch, REASON, TIER, SCOPE globs, `owns` for shared files,
    `dependsOn` only for a real dependency, and the brief fields. `workit fanout
    plan <plan.json>` refuses an empty or placeholder brief field (exit 2) and
    two slices that may write one file (exit 3) with a fix; apply it and re-run:
@@ -21,8 +21,8 @@ ceremony; do it yourself. Workit never spawns agents; you do.
 2. **Record standing orders** (`workit ledger standing add "<order>"`): every
    user directive all workers share. Directives decay across resumes.
 3. **Brief each worker verbatim** with `workit fanout brief <slice>`: plan
-   fields, standing orders, SCRATCH, session id, fan-in rule. Never hand-edit
-   it; change the plan or the standing orders and render again.
+   fields, standing orders, SCRATCH, session id, fan-in and heavy-lease rules.
+   Never hand-edit it; change the plan or the standing orders and render again.
 4. **Spawn in a rolling window**, in the background, each in its own worktree:
    keep 4-6 in flight and refill from `spawnable` in `workit fanout status` as
    each one finishes. Model: the brief's `model:` line, else TIER

package/skills/workit-fanout/references/brief.md

@@ -59,7 +59,8 @@ defaults to the trunk, or to the branch of a single `dependsOn` slice (a
 stack); `worktree` defaults to `../<repo>-wt/<id>`. `owns` claims a shared
 file another slice's glob also matches. Globs that match no file yet are compared
 through a sample path. Use `/` as the separator; a backslash only escapes
-literal brackets: `"app/\\[id\\]/page.tsx"`. A `timebox` such as `45 minutes`
+literal brackets: `"app/\\[id\\]/page.tsx"`. A `reason` (`explore`, `parallel`, `backstop` or `high-risk-verify`) is rendered as the brief's `REASON:` line and is
+required unless the workspace sets `delegation` to `lead-orchestrates`. A `timebox` such as `45 minutes`
 is the slice's STUCK threshold in `workit fanout status`. `"fanIn":
 "integration"` (with an integration branch as `trunk`) is the one-PR mode in
 `orchestration.md`; the default `"prs"` lands one PR per slice.
@@ -79,6 +80,7 @@ is the slice's STUCK threshold in `workit fanout status`. `"fanIn":
       "acceptance": ["Given no auth header, When GET /v1/usage, Then the status is 401"],
       "verify": ["workit check test"],
       "forbidden": ["no edits outside SCOPE", "no rebase or force-push"],
+      "reason": "parallel",
       "context": "docs/usage/spec.md Behavior",
       "timebox": "45 minutes"
     },

package/skills/workit-implement/SKILL.md

@@ -19,7 +19,9 @@ description: Build a requested change in small verified steps - follow local pat
    Mechanical change: the existing checks are enough. No tautological tests:
    a test must fail if the behavior breaks, never restate the implementation.
 4. Run the real checks: `workit check test` (and `lint`, `typecheck` when the
-   repo has them).
+   repo has them). Heavy work runs under one machine-wide lease: an ad-hoc
+   suite is `workit check --heavy -- <cmd>`, never a hand-made flock; a busy
+   lease waits and names its holder (`workit lock status`).
 5. Prove the feature on its real surface with the project's `verify-<app>`
    skill; none yet? Write one (workit-verify-app). Tests show branch behavior,
    not that the feature works.
@@ -41,6 +43,11 @@ description: Build a requested change in small verified steps - follow local pat
 
 Independent slices that could run in parallel: fan them out (workit-fanout).
 
+Stay inline by default (workspace `delegation: inline-first`). Hand work off
+only past the thresholds: an explorer after about 3 tool calls or 10k tokens
+of searching, parallel writers for 2 or more disjoint units of about 100+
+lines each.
+
 ## Example
 
 Bad: "Done - added the --since flag, tests pass." (no check ran this turn; the

package/skills/workit-review/SKILL.md

@@ -24,7 +24,8 @@ independent; `type-check-only` never proves a behavior change.
    - **Standards:** repo rules first (`CODING_STANDARDS.md` when present),
      then a smell baseline (unclear name, long function, duplicated logic,
      leaky abstraction). Judgment only; lint owns nits.
-4. **Tests:** `workit test-audit --diff`. Would each new test fail if the
+4. **Tests:** run suites under the heavy-check lease (`workit check test`,
+   `workit check --heavy -- <cmd>`); `workit test-audit --diff`. Would each new test fail if the
    behavior broke? Triage the findings (workit-test-audit).
 5. **Blast radius:** for each touched contract, caller, config or migration,
    state the one fact it is safe because of and run the proof. Anything

package/skills/workit-verify-app/SKILL.md

@@ -21,6 +21,8 @@ way a user would.
    `.cursor/skills/`; other hosts: the directory their docs name). If the repo
    already has a project skills directory, use it:
    - **Launch:** one command, its ready signal (log line, port, exit 0), a timeout.
+     Builds, installs and e2e suites run under the heavy-check lease
+     (`workit check --heavy -- <cmd>`); a long-running server does not.
    - **Doctor:** each precondition and its fix (deps, env vars, ports, services).
    - **Drive:** how to exercise it: CLI invocations, `curl` against routes, a
      browser tool for UI, with fixture data.

package/src/check-config.ts

@@ -29,6 +29,26 @@ import path from "node:path";
 export const SCRIPT_CHECKS = ["test", "lint", "typecheck", "check"] as const;
 export const CHECKS_FILE = "workit.checks.json";
 
+/** Where the repo's checks config lives under the repository top `root` (the one path resolver). */
+export const checksConfigFile = (root: string): string => path.join(root, CHECKS_FILE);
+
+/**
+ * `resources.heavyCommands` of the repo's checks config under `root`, read
+ * leniently (no git, no check validation): the heavy-command gate's patterns.
+ */
+export function repoHeavyCommands(root: string): string[] {
+  try {
+    const value: unknown = JSON.parse(fs.readFileSync(checksConfigFile(root), "utf8"));
+    const resources = isRecord(value) ? value.resources : undefined;
+    const list = isRecord(resources) ? resources.heavyCommands : undefined;
+    return Array.isArray(list)
+      ? list.filter((item): item is string => typeof item === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
 export type NamedCheck = {
   name: string;
   /** The argv `workit check <name>` runs. */
@@ -171,7 +191,7 @@ const GATES = ["testing", "verification"] as const;
 /** The named checks for the repository containing `cwd` (see the header). */
 export function loadCheckConfig(cwd: string): CheckConfig {
   const root = checkRoot(cwd);
-  const file = path.join(root, CHECKS_FILE);
+  const file = checksConfigFile(root);
   const none = (error: string | null = null): CheckConfig => ({
     source: error ? CHECKS_FILE : "none",
     root,

package/src/core/heavy-rules.ts

@@ -0,0 +1,373 @@
+// Host permission rules the heavy-command gate must not override (#325,
+// ruling mvid5onk). A heavy command is wrapped through the lease only when no
+// readable deny/ask rule names it and wrapping does not raise its permission
+// (an allow that covers `workit` but not the command itself). The matcher is
+// conservative: anything it cannot read for sure counts as naming the
+// command, so the gate steps aside and the host decides.
+//
+// Sources, per host:
+//   - Claude Code: managed-settings.json, the user settings
+//     ($CLAUDE_CONFIG_DIR or ~/.claude), <project>/.claude/settings.json and
+//     settings.local.json: permissions.deny/ask/allow `Bash(...)` and `Bash`;
+//   - OpenCode: ~/.config/opencode/opencode.json(c), opencode.json(c) and
+//     .opencode/opencode.json(c) up to the git top, OPENCODE_CONFIG,
+//     OPENCODE_CONFIG_CONTENT: permission.bash / permission.shell and every
+//     agent.*.permission;
+//   - Codex: ~/.codex/rules/*.rules and <project>/.codex/rules/*.rules
+//     (`prefix_rule(pattern=[…], decision=…)`);
+//   - Cursor: ~/.cursor/cli-config.json and <project>/.cursor/cli.json,
+//     permissions.deny/allow `Shell(x)`.
+// Hook-safe: node built-ins only.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** One rule: its pattern (`npx jest:*`, `*`, `` for a bare tool rule). */
+export type Rules = { deny: string[]; allow: string[] };
+/** Rules read from the host, or `unreadable` when any source could not be read for sure. */
+export type RuleRead = Rules | "unreadable";
+
+const EMPTY = (): Rules => ({ deny: [], allow: [] });
+
+const readText = (file: string): string | null => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** JSON with `//` and `/* *\/` comments and trailing commas (opencode.jsonc). */
+export function parseJsonc(text: string): unknown {
+  let out = "";
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '"') {
+      const end = /"(?:[^"\\]|\\.)*"/y;
+      end.lastIndex = index;
+      const match = end.exec(text);
+      if (!match) throw new Error("unterminated string");
+      out += match[0];
+      index += match[0].length - 1;
+    } else if (char === "/" && text[index + 1] === "/") {
+      while (index < text.length && text[index] !== "\n") index += 1;
+      out += "\n";
+    } else if (char === "/" && text[index + 1] === "*") {
+      const close = text.indexOf("*/", index + 2);
+      if (close < 0) throw new Error("unterminated comment");
+      index = close + 1;
+    } else out += char;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/gu, "$1"));
+}
+
+/** The git top of `cwd` (the nearest directory with `.git`), or null. */
+export function gitTop(cwd: string): string | null {
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/** `cwd` and its parents up to the git top (or just `cwd` outside git). */
+const projectDirs = (cwd: string): string[] => {
+  const top = gitTop(cwd);
+  const dirs: string[] = [];
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    dirs.push(dir);
+    if (!top || dir === top || path.dirname(dir) === dir) return dirs;
+  }
+};
+
+const homeOf = (env: NodeJS.ProcessEnv) => env.HOME || os.homedir();
+
+// --- Claude Code -----------------------------------------------------------
+
+const CLAUDE_MANAGED: Partial<Record<NodeJS.Platform, string>> = {
+  linux: "/etc/claude-code/managed-settings.json",
+  darwin: "/Library/Application Support/ClaudeCode/managed-settings.json",
+  win32: "C:\\Program Files\\ClaudeCode\\managed-settings.json",
+};
+
+/** The Claude Code settings files the gate reads, most authoritative first. */
+export function claudeSettingsFiles(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  const project = env.CLAUDE_PROJECT_DIR || gitTop(cwd) || cwd;
+  const user = env.CLAUDE_CONFIG_DIR || path.join(homeOf(env), ".claude");
+  return [
+    ...(CLAUDE_MANAGED[platform] ? [CLAUDE_MANAGED[platform]] : []),
+    path.join(user, "settings.json"),
+    path.join(project, ".claude", "settings.json"),
+    path.join(project, ".claude", "settings.local.json"),
+  ];
+}
+
+/** `Bash(x)` → `x`, `Bash` → ``, any other tool → null. */
+const bashPattern = (entry: string): string | null => {
+  const match = /^Bash(?:\((.*)\))?$/su.exec(entry.trim());
+  return match ? (match[1] ?? "") : null;
+};
+
+export function claudeRules(cwd: string, env: NodeJS.ProcessEnv = process.env): RuleRead {
+  const rules = EMPTY();
+  try {
+    for (const file of claudeSettingsFiles(cwd, env)) {
+      const text = readText(file);
+      if (text === null) continue;
+      const value: unknown = JSON.parse(text);
+      if (!isRecord(value)) return "unreadable";
+      const permissions = value.permissions;
+      if (permissions === undefined) continue;
+      if (!isRecord(permissions)) return "unreadable";
+      for (const [key, bucket] of [
+        ["deny", rules.deny],
+        ["ask", rules.deny],
+        ["allow", rules.allow],
+      ] as const) {
+        const list = permissions[key];
+        if (list === undefined) continue;
+        if (!Array.isArray(list)) return "unreadable";
+        for (const entry of list) {
+          if (typeof entry !== "string") return "unreadable";
+          const pattern = bashPattern(entry);
+          if (pattern !== null) bucket.push(pattern);
+        }
+      }
+    }
+  } catch {
+    return "unreadable";
+  }
+  return rules;
+}
+
+// --- OpenCode ---------------------------------------------------------------
+
+const OPENCODE_NAMES = ["opencode.json", "opencode.jsonc"];
+
+/** A `permission` block's bash/shell rules into `rules`; false when it cannot be read. */
+const opencodePermission = (permission: unknown, rules: Rules): boolean => {
+  if (permission === undefined) return true;
+  if (typeof permission === "string") {
+    // A blanket permission covers every tool, the shell included.
+    (permission === "allow" ? rules.allow : rules.deny).push("");
+    return ["allow", "ask", "deny"].includes(permission);
+  }
+  if (!isRecord(permission)) return false;
+  for (const key of ["bash", "shell"]) {
+    const value = permission[key];
+    if (value === undefined) continue;
+    if (typeof value === "string") {
+      if (!["allow", "ask", "deny"].includes(value)) return false;
+      (value === "allow" ? rules.allow : rules.deny).push("");
+      continue;
+    }
+    if (!isRecord(value)) return false;
+    for (const [pattern, action] of Object.entries(value)) {
+      if (action !== "allow" && action !== "ask" && action !== "deny") return false;
+      (action === "allow" ? rules.allow : rules.deny).push(pattern);
+    }
+  }
+  return true;
+};
+
+const opencodeConfig = (value: unknown, rules: Rules): boolean => {
+  if (!isRecord(value)) return false;
+  if (!opencodePermission(value.permission, rules)) return false;
+  if (value.agent === undefined) return true;
+  if (!isRecord(value.agent)) return false;
+  return Object.values(value.agent).every(
+    (agent) => isRecord(agent) && opencodePermission(agent.permission, rules),
+  );
+};
+
+export function opencodeRules(cwd: string, env: NodeJS.ProcessEnv = process.env): RuleRead {
+  const rules = EMPTY();
+  try {
+    const config = env.XDG_CONFIG_HOME || path.join(homeOf(env), ".config");
+    const files = [
+      ...OPENCODE_NAMES.map((name) => path.join(config, "opencode", name)),
+      ...projectDirs(cwd).flatMap((dir) =>
+        OPENCODE_NAMES.flatMap((name) => [path.join(dir, name), path.join(dir, ".opencode", name)]),
+      ),
+      ...(env.OPENCODE_CONFIG ? [env.OPENCODE_CONFIG] : []),
+    ];
+    for (const file of files) {
+      const text = readText(file);
+      if (text !== null && !opencodeConfig(parseJsonc(text), rules)) return "unreadable";
+    }
+    if (
+      env.OPENCODE_CONFIG_CONTENT &&
+      !opencodeConfig(parseJsonc(env.OPENCODE_CONFIG_CONTENT), rules)
+    )
+      return "unreadable";
+  } catch {
+    return "unreadable";
+  }
+  return rules;
+}
+
+// --- Codex ------------------------------------------------------------------
+
+/**
+ * `prefix_rule(pattern=["npx", "jest"], decision="forbidden")` → its rule
+ * (the words joined), or null when in doubt: no pattern list, a nested
+ * alternatives list, a non-string word, or no known decision.
+ */
+const codexRule = (body: string): { pattern: string; decision: string } | null => {
+  const open = /\bpattern\s*=\s*\[/u.exec(body);
+  if (!open) return null;
+  const words: string[] = [];
+  let index = open.index + open[0].length;
+  for (;;) {
+    while (/[\s,]/u.test(body[index] ?? "")) index += 1;
+    if (body[index] === "]") break;
+    if (body[index] !== '"') return null;
+    const literal = /"((?:[^"\\]|\\.)*)"/y;
+    literal.lastIndex = index;
+    const match = literal.exec(body);
+    if (!match) return null;
+    words.push(JSON.parse(`"${match[1]}"`) as string);
+    index = literal.lastIndex;
+  }
+  const decision = /\bdecision\s*=\s*"(\w+)"/u.exec(body)?.[1];
+  if (!words.length || !decision || !["allow", "prompt", "forbidden"].includes(decision))
+    return null;
+  return { pattern: words.join(" "), decision };
+};
+
+export function codexRules(cwd: string, env: NodeJS.ProcessEnv = process.env): RuleRead {
+  const rules = EMPTY();
+  try {
+    const home = env.CODEX_HOME || path.join(homeOf(env), ".codex");
+    const top = gitTop(cwd) ?? cwd;
+    for (const dir of [path.join(home, "rules"), path.join(top, ".codex", "rules")]) {
+      let files: string[];
+      try {
+        files = fs.readdirSync(dir).filter((name) => name.endsWith(".rules"));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+        return "unreadable";
+      }
+      for (const name of files) {
+        const text = readText(path.join(dir, name)) ?? "";
+        for (const part of text.split(/\bprefix_rule\s*\(/u).slice(1)) {
+          const rule = codexRule(part);
+          if (!rule) return "unreadable";
+          (rule.decision === "allow" ? rules.allow : rules.deny).push(rule.pattern);
+        }
+      }
+    }
+  } catch {
+    return "unreadable";
+  }
+  return rules;
+}
+
+// --- Cursor -----------------------------------------------------------------
+
+export function cursorRules(cwd: string, env: NodeJS.ProcessEnv = process.env): RuleRead {
+  const rules = EMPTY();
+  try {
+    const top = gitTop(cwd) ?? cwd;
+    for (const file of [
+      path.join(homeOf(env), ".cursor", "cli-config.json"),
+      path.join(top, ".cursor", "cli.json"),
+    ]) {
+      const text = readText(file);
+      if (text === null) continue;
+      const value: unknown = JSON.parse(text);
+      if (!isRecord(value)) return "unreadable";
+      if (value.permissions === undefined) continue;
+      if (!isRecord(value.permissions)) return "unreadable";
+      for (const [key, bucket] of [
+        ["deny", rules.deny],
+        ["allow", rules.allow],
+      ] as const) {
+        const list = value.permissions[key];
+        if (list === undefined) continue;
+        if (!Array.isArray(list)) return "unreadable";
+        for (const entry of list) {
+          if (typeof entry !== "string") return "unreadable";
+          const match = /^Shell(?:\((.*)\))?$/su.exec(entry.trim());
+          if (match) bucket.push(match[1] ?? "");
+        }
+      }
+    }
+  } catch {
+    return "unreadable";
+  }
+  return rules;
+}
+
+// --- the matcher --------------------------------------------------------------
+
+const baseName = (word: string): string =>
+  (word.split(/[\\/]/u).at(-1) ?? "").toLowerCase().replace(/\.(?:exe|cmd|bat)$/u, "");
+
+/** A pattern's first token: cut at `:` or a space. */
+const firstToken = (pattern: string): string => pattern.trim().split(/[:\s]/u)[0] ?? "";
+
+/** Does a deny/ask `pattern` name a command with these words? */
+export function names(pattern: string, words: readonly string[]): boolean {
+  const token = firstToken(pattern);
+  if (!token || token === "*" || token.includes("*")) return true;
+  const wanted = baseName(token);
+  return words.some((word) => baseName(word) === wanted);
+}
+
+/** A pattern's literal prefix, without a trailing `:*`, ` *` or `*`. */
+const literalPrefix = (pattern: string): string => pattern.trim().replace(/(?::\*| \*|\*)$/u, "");
+
+/**
+ * Could an allow `pattern` cover the wrapper (`workit check --heavy -- …`)?
+ * A bare rule, a first word with a glob, or a literal prefix of the wrapper
+ * (`workit`, `workit check`). `workit git push:*` cannot match it.
+ */
+const coversWrapper = (pattern: string): boolean => {
+  const token = firstToken(pattern);
+  if (!token || token.includes("*")) return true;
+  const words = literalPrefix(pattern).split(/\s+/u);
+  if (baseName(words[0]) !== "workit") return false;
+  return ["check", "--heavy"].slice(0, words.length - 1).every((word, at) => {
+    const given = words[at + 1];
+    return given === word || word.startsWith(given);
+  });
+};
+
+/** Does an allow `pattern` cover `command` by a literal prefix? */
+const coversCommand = (pattern: string, command: string): boolean => {
+  const prefix = literalPrefix(pattern);
+  if (!prefix) return true;
+  return !prefix.includes("*") && command.trim().startsWith(prefix);
+};
+
+export type RuleVerdict = { ok: true } | { ok: false; why: "named" | "allowlisted" };
+
+/**
+ * May the gate wrap a heavy command? Not when a deny/ask rule names a word
+ * of it (`words`), and not when an allow covers `workit` but not `command`
+ * (wrapping would raise its permission; skipped with `bypass`).
+ */
+export function wrapAllowed(
+  read: RuleRead,
+  words: readonly string[],
+  command: string,
+  options: { bypass?: boolean } = {},
+): RuleVerdict {
+  if (read === "unreadable") return { ok: false, why: "named" };
+  if (read.deny.some((pattern) => names(pattern, words))) return { ok: false, why: "named" };
+  if (
+    !options.bypass &&
+    read.allow.some(coversWrapper) &&
+    !read.allow.some((pattern) => coversCommand(pattern, command))
+  )
+    return { ok: false, why: "allowlisted" };
+  return { ok: true };
+}

package/src/core/heavy-scope.ts

@@ -0,0 +1,131 @@
+// The systemd user scope a heavy check runs in (issue #282), and the probe
+// `workit doctor` uses to say whether its limits really apply (#325). Node
+// built-ins only, so the doctor and the install-time doctor load it without
+// the check runner or the hook graph.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const readText = (file: string): string | null => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+export type ScopeSupport = { ok: true } | { ok: false; reason: string };
+
+const onPath = (command: string, env: NodeJS.ProcessEnv): boolean =>
+  (env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .some((dir) => {
+      try {
+        fs.accessSync(path.join(dir, command), fs.constants.X_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+
+/**
+ * Can heavy checks run in their own `systemd-run --user --scope`? Needs Linux,
+ * `systemd-run` on PATH, a running user manager, and the memory and cpu
+ * controllers delegated to it (cgroup v2).
+ */
+export function scopeSupport(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+  read: (file: string) => string | null = readText,
+): ScopeSupport {
+  if (platform !== "linux") return { ok: false, reason: `no systemd scopes on ${platform}` };
+  if (!onPath("systemd-run", env)) return { ok: false, reason: "systemd-run is not on PATH" };
+  const uid = process.getuid?.() ?? 0;
+  const runtime = env.XDG_RUNTIME_DIR || `/run/user/${uid}`;
+  if (!fs.existsSync(path.join(runtime, "systemd", "private")))
+    return { ok: false, reason: "no user systemd manager is running" };
+  const controllers = read(
+    `/sys/fs/cgroup/user.slice/user-${uid}.slice/user@${uid}.service/cgroup.controllers`,
+  );
+  if (controllers === null)
+    return { ok: false, reason: "cgroup v2 is not mounted for the user manager" };
+  const missing = ["memory", "cpu"].filter((name) => !controllers.split(/\s+/u).includes(name));
+  if (missing.length)
+    return { ok: false, reason: `the user manager is not delegated ${missing.join(" and ")}` };
+  return { ok: true };
+}
+
+/** The `systemd-run` prefix that runs a command in its own limited scope. */
+export function scopePrefix(unit: string, settings: { memoryMax: string; cpuQuota: string }) {
+  return [
+    "systemd-run",
+    "--user",
+    "--scope",
+    "--quiet",
+    "--collect",
+    `--unit=${unit}`,
+    "-p",
+    `MemoryMax=${settings.memoryMax}`,
+    "-p",
+    `CPUQuota=${settings.cpuQuota}`,
+    "--",
+  ];
+}
+
+export type ScopeProbe =
+  | { effective: true; memoryMax: string; cpuMax: string; delegate: string | null }
+  | { effective: false; supported: boolean; reason: string; delegate: string | null };
+
+const PROBE_MEMORY = "268435456";
+const PROBE_CPU = "50%";
+const PROBE_SCRIPT =
+  'cg=$(sed -n "s/^0:://p" /proc/self/cgroup); cat "/sys/fs/cgroup$cg/memory.max" "/sys/fs/cgroup$cg/cpu.max"';
+
+/** `Delegate=` and `DelegateControllers=` of the user manager's unit, as systemd reports them. */
+function userManagerDelegate(env: NodeJS.ProcessEnv): string | null {
+  const uid = process.getuid?.() ?? 0;
+  const shown = spawnSync(
+    "systemctl",
+    ["show", `user@${uid}.service`, "-p", "Delegate", "-p", "DelegateControllers"],
+    { env, encoding: "utf8", timeout: 5000 },
+  );
+  const text = shown.status === 0 ? shown.stdout.trim().split(/\n/u).join(", ") : "";
+  return text || null;
+}
+
+/**
+ * Do heavy-check scopes really get their limits here? Starts a throwaway
+ * scope the way a heavy check does (MemoryMax 256 MiB, CPUQuota 50%) and
+ * reads the limits back from its own cgroup, so a manager that accepts the
+ * properties but cannot apply them (no delegation) is told apart.
+ */
+export function probeScope(env: NodeJS.ProcessEnv = process.env): ScopeProbe {
+  const support = scopeSupport(env);
+  const delegate = process.platform === "linux" ? userManagerDelegate(env) : null;
+  if (!support.ok) return { effective: false, supported: false, reason: support.reason, delegate };
+  const unit = `workit-probe-${process.pid}-${Date.now().toString(36)}`;
+  // The same `systemd-run …` prefix a heavy check runs under.
+  const [runner, ...prefix] = scopePrefix(unit, { memoryMax: PROBE_MEMORY, cpuQuota: PROBE_CPU });
+  const probe = spawnSync(runner, [...prefix, "sh", "-c", PROBE_SCRIPT], {
+    env,
+    encoding: "utf8",
+    timeout: 10_000,
+  });
+  if (probe.status !== 0)
+    return {
+      effective: false,
+      supported: true,
+      reason: `systemd-run failed: ${(probe.stderr || probe.error?.message || `exit ${probe.status}`).trim().split("\n")[0]}`,
+      delegate,
+    };
+  const [memoryMax = "", cpuMax = ""] = probe.stdout.trim().split(/\n/u);
+  if (memoryMax.trim() === PROBE_MEMORY && cpuMax.trim().startsWith("50000 "))
+    return { effective: true, memoryMax: memoryMax.trim(), cpuMax: cpuMax.trim(), delegate };
+  return {
+    effective: false,
+    supported: true,
+    reason: `the scope started but its cgroup reads memory.max=${memoryMax.trim() || "?"} cpu.max=${cpuMax.trim() || "?"} (asked ${PROBE_MEMORY} and 50000 100000)`,
+    delegate,
+  };
+}