omp-conductor 0.18.0 → 0.18.2

package/src/setup-install.ts

@@ -52,6 +52,8 @@ import {
   agentRenameVerdict,
   checkEscalation,
   DEFAULT_AGENT_RENAME_DEPS,
+  defaultIdentityProbes,
+  defaultServiceRuntime,
   planHostRuntime,
   totalConfiguredWorkers,
   writeHostRuntime,
@@ -61,6 +63,7 @@ import {
   type AgentRenameDeps,
   type EscalationDeps,
   type ServiceRuntime,
+  type WorkerIdentityProbes,
 } from "./setup-host.ts";
 import type { WizardUi } from "./wizard-ui.ts";
 import type { Caps, ProjectConfig, Store } from "./types.ts";
@@ -81,6 +84,14 @@ export interface InstallDeps {
   escalation?: EscalationDeps;
   /** `"linux"` gates the systemd half. Injectable so the refusal is testable. */
   platform?: () => string;
+  /**
+   * The worker identity plan's probes (#798). `undefined` means the real
+   * host's read-only facts — production: every `setup host` installs and
+   * grants the dedicated worker account. `null` disables the identity plan
+   * entirely (the historical step list, for tests pinning it), and an object
+   * is used as given (tests pinning a specific host state).
+   */
+  workerIdentityProbes?: WorkerIdentityProbes | null;
   unitDir?: string;
   /**
    * Where the recovery playbook installs. Injectable so the idempotency gate
@@ -188,6 +199,13 @@ export async function runHostInstall(
   // happens only after consent (#510), so the prompt's "Nothing has been run
   // yet" is true of the staged tree when it is printed, and a declined run
   // leaves every staged file byte-identical.
+  // The worker identity plan rides the same consent (#798): production probes
+  // the real host (account present? grants current?); a test may pass its own
+  // probes, or `null` to plan the historical step list only.
+  const identityProbes: WorkerIdentityProbes | null =
+    deps.workerIdentityProbes === null
+      ? null
+      : deps.workerIdentityProbes ?? defaultIdentityProbes(deps.runtime ?? defaultServiceRuntime(telegramStateDir));
   const plan = planHostRuntime(
     project,
     caps,
@@ -197,6 +215,7 @@ export async function runHostInstall(
     unitDir,
     deps.recoverScriptInstallPath ?? RECOVER_SCRIPT_INSTALL_PATH,
     deps.multiProject ?? hostMultiProject(),
+    identityProbes,
   );
   // No pane-shell key is planned (unusable login shell, unparseable config):
   // the operator hears why before the consent prompt, not after an install
@@ -298,6 +317,15 @@ export async function runHostInstall(
                 ]),
           ]),
       "The unit runs as the account that staged it; nothing here changes that.",
+      ...(plan.workerIdentity === undefined
+        ? []
+        : [
+            `Establishes the dedicated worker identity ${plan.workerIdentity.account}: every worker session runs under it, ` +
+              "never under the daemon's account, and it is granted search/read access to exactly the fleet paths a worker needs.",
+            ...(plan.workerIdentity.current
+              ? ["The worker identity is already in place — nothing to change."]
+              : plan.workerIdentity.pending),
+          ]),
       "",
       liveWorkers === 0
         ? "No workers are live — nothing to drain before the restart."

package/src/setup-wizard.ts

@@ -110,11 +110,13 @@ import {
   parseOmpSettingsYaml,
   planAgainstLabels,
   planLabels,
+  readConfiguredOmpRoles,
   summariseAmend,
   summarisePlan,
   wantedLabels,
   writeOrchestratorBrief,
   type AmendAreaId,
+  type ConfiguredOmpRoles,
   type LabelPlan,
   type OperatorJudgment,
   type ScopeCheck,
@@ -126,6 +128,7 @@ import {
   BASE_FRESHNESS,
   BEHIND_BASE_ACTIONS,
   DEFAULT_CAPS,
+  DEFAULT_REVIEW_ADJUDICATOR_ROLE,
   DEFAULT_REVIEW_MAX_ROUNDS,
   DEFAULT_REVIEW_STRICTNESS,
   DENIED_RELEASE_GRANTS,
@@ -133,6 +136,7 @@ import {
   RELEASE_REQUIREMENTS,
   INTERRUPT_CATEGORIES,
   RELEASE_SHAPES,
+  REVIEW_ADJUDICATOR_RE,
   REVIEW_MAX_ROUNDS_MAX,
   REVIEW_MAX_ROUNDS_MIN,
   REVIEW_STRICTNESS,
@@ -151,6 +155,7 @@ import {
   type ReviewPolicy,
 } from "./types.ts";
 import { withProgress } from "./ui/progress.ts";
+import { modelRolesIn } from "./omp-settings.ts";
 import type { WizardUi } from "./wizard-ui.ts";
 
 /**
@@ -979,6 +984,7 @@ function seedFromDiscovery(seed: SetupAnswers, found: DiscoveredFacts): SetupAns
       inProgress: labels.get(seed.stateLabels.inProgress.toLowerCase()) ?? seed.stateLabels.inProgress,
       blocked: labels.get(seed.stateLabels.blocked.toLowerCase()) ?? seed.stateLabels.blocked,
       failed: labels.get(seed.stateLabels.failed.toLowerCase()) ?? seed.stateLabels.failed,
+      backlog: labels.get(seed.stateLabels.backlog.toLowerCase()) ?? seed.stateLabels.backlog,
     },
     targetRepos,
     policy: {
@@ -1094,19 +1100,28 @@ const askTrackerAndRepos: AreaAsker = async (ui, a, probes) => {
 
   // One confirm instead of three prompts: the namespaced defaults are right for
   // almost everyone, and three dialogs of Enter-to-accept is how a wizard earns
-  // its reputation.
+  // its reputation. The park label is in the same confirm, with its ownership
+  // stated — it is not conductor-written, but it has to exist for the operator
+  // to have the gesture (#507).
   const stateLabels: SetupAnswers["stateLabels"] = { ...a.stateLabels };
   const customiseStates = await askYesNo(
     ui,
     "customise-state-labels",
     "State labels",
     `The conductor writes back "${stateLabels.inProgress}", "${stateLabels.blocked}" and ` +
-      `"${stateLabels.failed}" so the tracker alone shows live state. Rename them?`,
+      `"${stateLabels.failed}" so the tracker alone shows live state; "${stateLabels.backlog}" is ` +
+      `yours — the conductor never writes it, but an issue carrying it is never claimed. Rename them?`,
   );
   if (customiseStates) {
     stateLabels.inProgress = await ask(ui, "state-label-in-progress", "Label for a run in progress", stateLabels.inProgress);
     stateLabels.blocked = await ask(ui, "state-label-blocked", "Label for a run parked on a human", stateLabels.blocked);
     stateLabels.failed = await ask(ui, "state-label-failed", "Label for a run that gave up", stateLabels.failed);
+    stateLabels.backlog = await ask(
+      ui,
+      "state-label-backlog",
+      "Label the operator applies to park an issue (the conductor never writes it)",
+      stateLabels.backlog,
+    );
   }
 
   const routingLabelPrefix = await ask(
@@ -1421,6 +1436,136 @@ async function askReviewRounds(ui: WizardUi, current: number): Promise<number> {
   throw new Cancelled();
 }
 
+/** The answer-file key the adjudicator question is recorded under. */
+const REVIEW_ADJUDICATOR_KEY = "review-adjudicator-role";
+
+/**
+ * Whether one role is a legitimate adjudicator answer on this host right now:
+ * it must be a single loadable role token (`REVIEW_ADJUDICATOR_RE`) AND a
+ * `modelRoles` key of the daemon's global settings or of the project's omp
+ * overlay — or the deterministic default, which setup must always be able to
+ * write back. Anything else — including a project's current role that was
+ * removed from both surfaces, or a malformed `modelRoles` key the loader
+ * would refuse — is an unavailable role and must not be accepted, whatever
+ * the config says (#875).
+ */
+function isAdjudicatorAvailable(live: ConfiguredOmpRoles, overlay: readonly string[], role: string): boolean {
+  if (!REVIEW_ADJUDICATOR_RE.test(role)) return false;
+  return role === DEFAULT_REVIEW_ADJUDICATOR_ROLE || live.global.includes(role) || overlay.includes(role);
+}
+
+/**
+ * The adjudicator roles the dialog accepts, derived from the live OMP role
+ * configuration — the daemon's global settings, then the project's omp
+ * overlay — with the current answer first and the deterministic default
+ * offered exactly once (#875). The order is the contract: an amend's Enter
+ * re-affirms the current value, and the shipped default stays expressible for
+ * a project whose operator never answered.
+ *
+ * Every role is filtered through the same token grammar the loader enforces:
+ * a `modelRoles` key the config gate would reject must never be offered (or
+ * accepted), because persisting it would write a policy the next loadConfig
+ * refuses and stop the fleet. The current answer leads the list only while it
+ * is still available: a role removed from both the global settings and the
+ * overlay must not be accepted back into the config by a bare Enter — the
+ * caller warns that it cannot be kept, and the accepted set excludes it, so
+ * Entering it refuses exactly like typing any other unavailable role.
+ */
+function adjudicatorChoices(live: ConfiguredOmpRoles, overlay: readonly string[], current: string): string[] {
+  const choices: string[] = [];
+  const seen = new Set<string>();
+  const first = isAdjudicatorAvailable(live, overlay, current) ? [current] : [];
+  for (const role of [...first, ...live.global, ...overlay, DEFAULT_REVIEW_ADJUDICATOR_ROLE]) {
+    if (REVIEW_ADJUDICATOR_RE.test(role) && !seen.has(role)) {
+      seen.add(role);
+      choices.push(role);
+    }
+  }
+  return choices;
+}
+
+/** One role row's description: what makes this role available and why. */
+function adjudicatorDescription(
+  role: string,
+  live: ConfiguredOmpRoles,
+  overlay: readonly string[],
+): string | undefined {
+  if (live.global.includes(role) || overlay.includes(role)) {
+    return role === DEFAULT_REVIEW_ADJUDICATOR_ROLE
+      ? "configured OMP model role — the deterministic default"
+      : "configured OMP model role";
+  }
+  if (role === DEFAULT_REVIEW_ADJUDICATOR_ROLE) {
+    return "the deterministic default every project loads until answered";
+  }
+  return undefined;
+}
+
+/**
+ * Which OMP model role runs a PR's terminal review-ceiling adjudication
+ * (#875). The offered roles are derived from the live OMP role configuration
+ * (the daemon account's global settings and the project's overlay, never a
+ * conductor-owned registry), the prompt opens on the current answer, and any
+ * answer that is not one of those configured roles is refused with the place
+ * to configure it named.
+ *
+ * Driven through `askValid`, not a select, on purpose: a select surface can
+ * only ever return an offered label, so the unconfigured-value refusal would
+ * be unreachable on the real UIs and the answer-file path would fail with a
+ * generic "must be a listed label" before this guidance ran. A validated text
+ * answer gives every surface — terminal, scripted and `--answers` — the same
+ * bounded three tries and the same actionable error naming the settings file.
+ */
+async function askReviewAdjudicator(
+  ui: WizardUi,
+  current: string,
+  live: ConfiguredOmpRoles,
+  overlay: readonly string[],
+): Promise<string> {
+  const choices = adjudicatorChoices(live, overlay, current);
+  if (!live.decoded) {
+    ui.notify(
+      `The daemon's OMP settings at ${live.path} could not be read — only the project's overlay roles and the default are offered.`,
+      "warning",
+    );
+  }
+  // A project whose configured role was removed from both surfaces must not be
+  // allowed to keep it: the warning names the role and the way back, and the
+  // accepted list above already excludes it — Entering it now refuses exactly
+  // like typing any other unavailable role (#875).
+  if (!isAdjudicatorAvailable(live, overlay, current)) {
+    ui.notify(
+      `"${current}" is this project's current adjudicator but not a currently configured OMP model role — it cannot be kept. ` +
+        `Add "${current}" back as a modelRoles key to ${live.path} or this project's omp settings overlay, ` +
+        `or type one of the available roles below.`,
+      "warning",
+    );
+  }
+  ui.notify(
+    choices
+      .map((role) => {
+        const described = adjudicatorDescription(role, live, overlay);
+        return `${role}${role === current ? " (current)" : ""}${described === undefined ? "" : ` — ${described}`}`;
+      })
+      .join("\n"),
+    "info",
+  );
+  return askValid(
+    ui,
+    REVIEW_ADJUDICATOR_KEY,
+    "Adjudicator for a PR at the review ceiling — one configured OMP model role, not a model",
+    current,
+    (value) => {
+      if (choices.some((choice) => choice === value)) return undefined;
+      return (
+        `"${value}" is not one of the OMP model roles available here — add it as a modelRoles key to the daemon's OMP settings ` +
+        `(${live.path}) or this project's omp settings overlay, or type an offered role. ` +
+        `A role is a single token like "task" — never a provider or model.`
+      );
+    },
+  );
+}
+
 /**
  * How green PRs are reviewed (#678), asked with the merge preconditions and
  * the arming proof: they are the same kind of declared policy — a typed,
@@ -1431,7 +1576,10 @@ async function askReviewRounds(ui: WizardUi, current: number): Promise<number> {
  * rather than between three words. The select cursor opens on the current
  * answer (the configured level on a re-run, the recommended default on a
  * first run); the rounds are a validated integer within the same range the
- * loader enforces.
+ * loader enforces; the adjudicator role is offered from the live OMP role
+ * configuration (#875) — the options and their availability come from the
+ * daemon's OMP settings and the project's overlay, never from a conductor
+ * model registry.
  */
 async function askReviewPolicy(ui: WizardUi, a: SetupAnswers): Promise<ReviewPolicy> {
   ui.notify(
@@ -1440,6 +1588,7 @@ async function askReviewPolicy(ui: WizardUi, a: SetupAnswers): Promise<ReviewPol
     ),
     "info",
   );
+  const live = readConfiguredOmpRoles();
   return {
     strictness: await askLiteral(
       ui,
@@ -1450,6 +1599,7 @@ async function askReviewPolicy(ui: WizardUi, a: SetupAnswers): Promise<ReviewPol
       a.review.strictness,
     ),
     maxRounds: await askReviewRounds(ui, a.review.maxRounds),
+    adjudicator: await askReviewAdjudicator(ui, a.review.adjudicator, live, modelRolesIn(a.ompSettings)),
   };
 }
 
@@ -2516,6 +2666,7 @@ function captureInventory(
   };
   captureIfWritten(plan.runtime.service);
   captureIfWritten(plan.runtime.herdrUnit);
+  captureIfWritten(plan.runtime.harnessMount);
   captureIfWritten(plan.runtime.herdrConfig);
   captureIfWritten(plan.runtime.herdrEnv);
   captureIfWritten(plan.runtime.recoverUnit);

package/src/setup.ts

@@ -39,7 +39,6 @@ import {
 import {
   clonePolicy,
   configPath,
-  DEFAULT_STATE_LABELS,
   defaultMirrorRoot,
   defaultWorkspaceRoot,
   resolveArmProof,
@@ -51,7 +50,7 @@ import {
   stateDir,
 } from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
-import { ompSettingsOverlay } from "./omp-settings.ts";
+import { modelRolesIn, ompSettingsOverlay } from "./omp-settings.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_ARM_PROOF,
@@ -144,7 +143,7 @@ export interface SetupAnswers {
   /** Tracker repo as `owner/repo` — the only spelling `gh` takes without a host. */
   trackerRepo: string;
   queueLabel: string;
-  stateLabels: { inProgress: string; blocked: string; failed: string };
+  stateLabels: { inProgress: string; blocked: string; failed: string; backlog: string };
   routingLabelPrefix: string;
   targetRepos: {
     name: string;
@@ -318,7 +317,12 @@ export interface LabelPlan {
  *  cannot drift apart: one spelling of "ready-for-agent" in the package. */
 export const SETUP_DEFAULTS = {
   queueLabel: "ready-for-agent",
-  stateLabels: { inProgress: "agent:in-progress", blocked: "agent:blocked", failed: "agent:failed" },
+  stateLabels: {
+    inProgress: "agent:in-progress",
+    blocked: "agent:blocked",
+    failed: "agent:failed",
+    backlog: "backlog",
+  },
   routingLabelPrefix: "repo:",
   defaultBranch: "main",
   /** Both authorities start with the human; the wizard asks to move each one. */
@@ -578,13 +582,15 @@ const POLICY_TEMPLATE_PATH = join(import.meta.dir, "briefs", "policy.md");
 const REQUIRED_SCOPES = ["repo", "project"] as const;
 
 /** GitHub's own palette, so the tracker reads at a glance: green means queued,
- *  blue means moving, amber means waiting on you, red means it gave up, and
- *  purple is routing — the operator's input, the one label the loop never writes. */
+ *  blue means moving, amber means waiting on you, red means it gave up, grey
+ *  means the operator parked it, and purple means routing — the operator's
+ *  input, the label the loop never writes. */
 const LABEL_COLOURS = {
   queue: "0e8a16",
   inProgress: "1d76db",
   blocked: "fbca04",
   failed: "b60205",
+  backlog: "8b949e",
   routing: "6f42c1",
 } as const;
 
@@ -668,14 +674,15 @@ export async function checkTokenScopes(): Promise<ScopeCheck> {
 
 /**
  * Every label setup wants on the tracker, before existence is known: the queue
- * and state labels the loop reads and writes, plus one routing label per routed
- * repo. Pure — the prefix and the repo keys are already answered at this point
- * in the interview — which is what lets a test pin the whole set without `gh`.
+ * and state labels the loop reads and writes, the operator's park label (which
+ * the loop must never write), plus one routing label per routed repo. Pure —
+ * the prefix and the repo keys are already answered at this point in the
+ * interview — which is what lets a test pin the whole set without `gh`.
  *
- * Routing labels are provisioned, never applied: `route()` requires exactly one
- * `<prefix><repo>` label per issue and treats zero or two as unroutable, so a
- * tracker without them can queue nothing. Creating them queues nothing either —
- * applying one, with the queue label, stays the operator's sign-off.
+ * The park label is provisioned like the rest but owned the other way round:
+ * it exists so the operator has a gesture, and the conductor never applies or
+ * removes it (#507). Creating it queues nothing either — applying one, with
+ * the queue label, stays the operator's sign-off.
  */
 export function wantedLabels(a: SetupAnswers): Omit<LabelPlan, "exists">[] {
   return [
@@ -699,6 +706,11 @@ export function wantedLabels(a: SetupAnswers): Omit<LabelPlan, "exists">[] {
       colour: LABEL_COLOURS.failed,
       description: "The conductor gave up on this issue after its retry budget",
     },
+    {
+      name: a.stateLabels.backlog,
+      colour: LABEL_COLOURS.backlog,
+      description: "Parked by the operator — never claimed, only the operator may set or clear it",
+    },
     ...a.targetRepos.map((r) => ({
       name: `${a.routingLabelPrefix}${r.name}`,
       colour: LABEL_COLOURS.routing,
@@ -973,7 +985,11 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
     name: a.projectName,
     tracker: { kind: "github", repo: a.trackerRepo },
     queueLabel: a.queueLabel,
-    stateLabels: { ...a.stateLabels, backlog: DEFAULT_STATE_LABELS.backlog },
+    // The park label is now an answer like the other three: the wizard offers
+    // it and every answers constructor carries it, so writing the answers as
+    // they stand is the single source — slice 1's hardcoded default bridge is
+    // gone (#507 slice 2).
+    stateLabels: { ...a.stateLabels },
     routing: { labelPrefix: a.routingLabelPrefix, repos },
     caps,
     ...(a.workerModel !== undefined && a.workerModel.trim().length > 0
@@ -1559,6 +1575,53 @@ export function detectTelegram(): TelegramPresence {
   return result;
 }
 
+/**
+ * Env override for the daemon account's global omp settings file, exactly the
+ * seam `OMP_TELEGRAM_STATE_DIR` gives telegram discovery: a test (or a second
+ * fleet on the same machine) can redirect the read without touching a real
+ * `~/.omp/agent/config.yml`.
+ */
+export const OMP_GLOBAL_SETTINGS_ENV = "OMP_CONDUCTOR_OMP_SETTINGS_PATH";
+
+/**
+ * The model roles the daemon account's global omp settings actually configure
+ * — the keys of its `modelRoles` stanza (#875) — the "live OMP role
+ * configuration" an adjudicator answer must be checked against. OMP's own
+ * settings file (`~/.omp/agent/config.yml`) is the source rather than any
+ * conductor-owned registry: conductor stores only role names, so the only
+ * place an unrelated role could be invented is here, and reading this file is
+ * what keeps setup from offering (or accepting) a role OMP never configured.
+ *
+ * A missing file is no roles; an unreadable or malformed one is also no roles
+ * but is reported through `decoded: false` so the wizard can say why instead
+ * of silently offering the default alone.
+ */
+export function readConfiguredOmpRoles(): ConfiguredOmpRoles {
+  const override = process.env[OMP_GLOBAL_SETTINGS_ENV]?.trim();
+  const path = override && override.length > 0 ? override : join(homedir(), ".omp", "agent", "config.yml");
+  if (!existsSync(path)) return { path, global: [], decoded: true };
+  try {
+    const parsed = parseYaml(readFileSync(path, "utf8"));
+    return {
+      path,
+      global: [...new Set(modelRolesIn(parsed))].sort(),
+      decoded: true,
+    };
+  } catch {
+    return { path, global: [], decoded: false };
+  }
+}
+
+/** The global omp settings read (`readConfiguredOmpRoles`) reports. */
+export interface ConfiguredOmpRoles {
+  /** The path read (the override, or the default under the operator's home). */
+  readonly path: string;
+  /** The model-role names the file's `modelRoles` stanza declares. */
+  readonly global: readonly string[];
+  /** False when the file exists but could not be read or parsed. */
+  readonly decoded: boolean;
+}
+
 /** True when `.env` carries a non-empty `TELEGRAM_BOT_TOKEN`. The value is
  *  compared against emptiness and then dropped on the floor. */
 function hasTelegramToken(envPath: string): boolean {
@@ -1780,6 +1843,7 @@ export function summarisePlan(
 
   lines.push("", "review", `  strictness     ${a.review.strictness} — ${REVIEW_STRICTNESS_CHOICES[a.review.strictness]}`);
   lines.push(`  max rounds/PR  ${a.review.maxRounds} — at the ceiling the PR is left open, the findings recorded, and it is escalated once`);
+  lines.push(`  adjudicator    ${a.review.adjudicator} — the OMP model role that runs that ceiling adjudication`);
 
   const reporting = project.reporting as ReportingPolicy;
   const briefPath = orchestratorBriefPath(a);
@@ -1997,18 +2061,20 @@ export const AMEND_AREAS: {
   },
   policy: {
     name: "merge & release preconditions",
-    asks: "the checks, base freshness, draft rule and behind-base action for a merge, then what a release requires and what it ships — and how green PRs are reviewed, and how many rounds a PR may be returned",
+    asks: "the checks, base freshness, draft rule and behind-base action for a merge, then what a release requires and what it ships — and how green PRs are reviewed, how many rounds a PR may be returned, and which OMP model role adjudicates a PR at that ceiling",
     describe: (p) => {
       const policy = resolvePolicy(p);
       const review = resolveReview(p);
       // Counted rather than listed: this row is elided at 96 characters, and the
-      // full table is in the plan summary the consent screen shows next.
+      // full table is in the plan summary the consent screen shows next. The
+      // adjudicator is the third review decision, so it is named with the other
+      // two (#875).
       return (
         `merge: ${policy.merge.requiredChecks.length === 0 ? "every check" : `${policy.merge.requiredChecks.length} check(s)`}, ` +
         `base ${policy.merge.baseFreshness}, drafts ${policy.merge.drafts}, behind → ${policy.merge.whenBehindBase}; ` +
         `release: ${policy.release.requires.length} must-land, ${policy.release.artefacts.length} artefact(s), ` +
         `${policy.release.environments.length} env(s); ` +
-        `review ${review.strictness} ×${review.maxRounds}`
+        `review ${review.strictness} ×${review.maxRounds} (adjudicator ${review.adjudicator})`
       );
     },
   },

package/src/shell.ts

@@ -0,0 +1,15 @@
+/**
+ * One CLI argument rendered exactly as an operator would type it, for surfaces
+ * that print executable commands.
+ *
+ * A command a surface prints is a command the reader copies, so an argument
+ * that could mean something else is a defect: a project named `odd $fleet`
+ * must not render `--project odd $fleet` (two arguments, and a `$` that the
+ * shell would read). Safe characters pass through unquoted; anything else is
+ * wrapped in single quotes, folding an embedded quote with the standard
+ * `'\''` — the same convention the privileged-step renderer applies to its
+ * printed `sudo …` lines (#810).
+ */
+export function shellQuote(value: string): string {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}