@soleur/opencode 0.0.0-stage → 3.354.2

package/scripts/lib/operator-script.sh

@@ -0,0 +1,1236 @@
+#!/usr/bin/env bash
+# operator-script.sh — shared primitives for Soleur-generated operator scripts.
+#
+# SOURCED, NEVER EXECUTED. The shebang is the line-1 convention of every sibling
+# in this directory (`proc.sh`, `session-state.sh`, `domain-model-lib.sh`) and
+# is what lets shellcheck infer the dialect; the file carries no exec bit. There
+# is ONE distribution mode (the generated script `source`s this file), so there
+# is no inlined copy to drift from and no `STAGES` byte identity marker to pin.
+# Plan 2026-09-18-feat-ship-operator-bootstrap-wizard-merge-danger, revision R6.
+#
+# Home per ADR-178 §1: a shared bash primitive consumed by shipped plugin code
+# lives inside `plugins/soleur/`, alongside `proc.sh`, `session-state.sh` and
+# `domain-model-lib.sh`.
+#
+# API CONTRACT: this file exports `SOLEUR_OP_LIB_API=1`. Every consumer asserts
+# `[[ ${SOLEUR_OP_LIB_API:-0} -eq 1 ]]` right after its `source` line and exits
+# 64 with `SOLEUR_BOOTSTRAP_LIB_INCOMPATIBLE need=1 got=<n>` otherwise. EQUALITY,
+# not `-ge`: the library auto-updates with the plugin while a generated script
+# is frozen in the founder's repository, so "library newer than script" is the
+# only incompatibility that can occur — and a `-ge` gate admits exactly that
+# case, then dies mid-stage on a renamed helper (measured by the review lead).
+# Bump the number only on a change that breaks an existing consumer (a renamed
+# helper, a changed positional contract), never on an additive one.
+#
+# PORTABILITY: bash 3.2 (the /bin/bash macOS ships), the floor `proc.sh` in this
+# directory declares. So: no negative array subscripts (`${a[-1]}` is 4.3+), no
+# `${var^^}` (4.0+), no `mapfile`, no `declare -A`. `readlink -f` may be absent
+# on older macOS — every use falls back to the unresolved path.
+#
+# Sourced (NEVER executed) by:
+#   - plugins/soleur/skills/operator-bootstrap/template.sh
+#       the template every generated <feature>/bootstrap.sh is authored from
+#   - plugins/soleur/skills/provision-hetzner/scripts/provision-hetzner.sh
+#       the proving consumer (plan D11)
+#   - every script the `soleur:operator-bootstrap` skill generates
+#
+# SOURCING PRECONDITIONS — the caller satisfies all of these BEFORE the
+# `source` line (the shape of apps/cla-evidence/scripts/_cf-admin-token.sh):
+#   1. `set -euo pipefail` is already in effect. This file sets no shell options
+#      of its own except `umask`, because a sourced library that changes the
+#      caller's error handling changes the caller's control flow.
+#   2. The caller carries its OWN xtrace-refusal prologue ABOVE the `source`
+#      line. It is DUPLICATED there, never moved in here: `PROLOGUE_MAX_CMDS = 0`
+#      in scripts/lint-shell-trace-credential-refusal.py makes a `source` line
+#      itself a counted command, and `find_preamble` only ever scans a file's
+#      OWN lines — a caller sourcing a fully compliant library still fails Rule
+#      A (measured, revision R26). The caller does NOT strip SSL_CERT_FILE /
+#      SSL_CERT_DIR / CURL_CA_BUNDLE: `gh` and `hcloud` are Go clients that read
+#      those for their root CA pool, and a founder behind a TLS-inspecting proxy
+#      needs them (the linter requires only the xtrace refusal — measured).
+#   3. `grep`, `sed`, `date`, `dirname`, `mkdir`, `mv`, `chmod`, `mktemp`, `rm`,
+#      `readlink`, `printenv`, `od`, `id`, `stat`, `cut`, `tr` and one of
+#      `sha256sum` / `shasum` are on PATH — the binaries this file actually
+#      calls, and only those. `gh` is required only by the two GitHub helpers.
+#
+# LIBRARY INVARIANT (revision R26) — THIS FILE NEVER EXPANDS A SECRET-SHAPED
+# VARIABLE NAME. The credential linter's `^scripts/lib/` exclusion is
+# repo-root-anchored, so a library under `plugins/soleur/scripts/lib/` IS
+# scanned. If this file ever expanded a `*_TOKEN` / `*_KEY` / `*_SECRET` /
+# `*_PASSWORD` / `*_PAT` name — or used `${!name}` indirection — it would come
+# into scope and need its own `exit 78`, which on a `source` terminates the
+# CALLER. So: secret values arrive as POSITIONAL PARAMETERS bound to neutral
+# local names (`value`), skip variables are read with `printenv` rather than
+# `${!name}`, and every expansion of a caller-named credential stays in the
+# caller.
+#
+# EXIT CODES a generated script may return (revision R42 — the repo has no
+# central table and code 3 is already overloaded, so the table lives HERE ONLY;
+# operator-bootstrap/SKILL.md and template.sh point at this section rather than
+# restating it):
+#
+#   0   success.
+#   1   usage error; a refused call — e.g. a secret-shaped name handed to the
+#       GitHub *variable* helper, which writes on argv (remedy: fix the call); or
+#       the operator DECLINED a barrier or a destructive-write ack (the
+#       `SOLEUR_BOOTSTRAP_ABORTED stage=<kind>` marker names which).
+#   3   DPA-gate rejection (tenant provisioning scripts only). CONFLICT, stated
+#       rather than renumbered: apps/cla-evidence/scripts/sentinel-pr.sh returns
+#       3 for "missing tool on PATH" and "not inside a git repository" — a class
+#       apps/cla-evidence/infra/bootstrap.sh returns 64 for. Do NOT re-derive 3
+#       as "missing tool".
+#   64  missing input — a required binary, a required environment variable, a
+#       missing `--stage`, or a prompt that cannot be answered because stdin is
+#       not a TTY. Remedy: the sentence under the marker names it. For a
+#       class-1/class-3 prompt, set the named variable. The legacy class-2
+#       destructive-write ack (`soleur_op_ack_or_die`, scripts not yet moved to
+#       the staged contract) has NO variable to set and needs a typed `yes` at a
+#       terminal; a v2 generated script never calls it.
+#   75  approval required or not valid for a staged WRITE (EX_TEMPFAIL, ADR-264):
+#       no approval was presented, the receipt was expired / used / for another
+#       command, or the plan changed between the plan and the apply. Nothing was
+#       written. The marker's `reason=` and the sentence under it say what to do;
+#       the agent re-plans, re-issues the command, or stops and reports.
+#   78  refusing to run under shell tracing while holding a live credential
+#       (#7797). Remedy: re-run without `-x`.
+#
+#   Exit 1 has a FOURTH meaning under the caller's `set -e`: a `soleur_op_gh_*`
+#   helper that `return 1`s (write failed, verify failed, unsafe name) ends the
+#   caller with status 1 unless the call is guarded. The marker line above the
+#   exit says which.
+#
+# STDOUT MARKERS, not stderr. Agent runtimes surface stdout and swallow stderr,
+# so a stderr-only refusal is invisible on the one surface that matters
+# (provision-doppler.sh records the same reason at its own prologue). On a
+# hosted agent surface (a cloud session, a CI step) these markers are the ONLY
+# durable signal besides the ledger: grep for `SOLEUR_BOOTSTRAP_` in the step
+# log. Every refusal is the marker PLUS one plain sentence for the founder.
+#   SOLEUR_BOOTSTRAP_INPUT_REQUIRED       var=<NAME> tty=0          → exit 64
+#   SOLEUR_BOOTSTRAP_MISSING_BINARY       bin=<bin>                 → exit 64
+#   SOLEUR_BOOTSTRAP_ABORTED              stage=<barrier|ack>       → operator declined, exit 1
+#   SOLEUR_BOOTSTRAP_BAD_ARG              key=<KEY> [reason=<r>]    → refused .env write, return 1
+#                                         helper=<h> reason=<r>       (mktemp failed)
+#   SOLEUR_BOOTSTRAP_ENV_READ_FAILED      path=<path>               → grep exit 2 on the .env; no mv, return 1
+#   SOLEUR_BOOTSTRAP_ENV_KEYCOUNT_DROP    before=<n> after=<m> path=<path>
+#                                                                   → filter lost keys; no mv, return 1
+#   SOLEUR_BOOTSTRAP_UNSAFE_VARIABLE      name=<NAME> reason=secret-shaped-name-on-argv
+#                                                                   → refused argv write, return 1
+#   SOLEUR_BOOTSTRAP_SECRET_WRITE_FAILED  name=<NAME> repo=<repo>   → return 1
+#   SOLEUR_BOOTSTRAP_SECRET_VERIFY_FAILED name=<NAME> repo=<repo>   → return 1 (write may have
+#                                     landed; also sets SOLEUR_OP_WRITE_MAY_HAVE_LANDED=1 for the trap)
+#   SOLEUR_BOOTSTRAP_VARIABLE_WRITE_FAILED name=<NAME> repo=<repo>  → return 1
+#   SOLEUR_BOOTSTRAP_LEDGER_WRITE_FAILED  path=<path>               → non-fatal; the run
+#                                                                     continues, the record is lost
+#   SOLEUR_BOOTSTRAP_LIB_MISSING          path=<last-rejected>      → exit 64
+#   SOLEUR_BOOTSTRAP_LIB_INCOMPATIBLE     need=1 got=<n>            → exit 64
+#   SOLEUR_BOOTSTRAP_ENV_NOT_IGNORED      path=<path>               → exit 64 (template.sh)
+#
+# STAGED CONTRACT markers (ADR-264; every v2 generated script: --list, --stage
+# <name>, --stage <name> --apply --plan-digest <d> [--rotate-token]). One line
+# each, names and booleans only — never a value and never a hash of one:
+#   SOLEUR_BOOTSTRAP_STAGE_DECL           stage=<s> class=<read|write>   (--list)
+#   SOLEUR_BOOTSTRAP_PLAN                 stage=<s> operations=<n> digest=<hex>
+#   SOLEUR_BOOTSTRAP_PLAN_OP              stage=<s> op=<name> target=<name>
+#   SOLEUR_BOOTSTRAP_IMPACT / _ROLLBACK   stage=<s> text=<one plain sentence>
+#   SOLEUR_BOOTSTRAP_APPLY_COMMAND        stage=<s> approval_digest=<hex>  + the exact command
+#   SOLEUR_BOOTSTRAP_APPROVAL_REQUIRED    stage=<s> approval_digest=<hex> surface=<s>  → exit 75
+#   SOLEUR_BOOTSTRAP_APPROVAL_INVALID     stage=<s> reason=<no-record|expired|digest-mismatch|
+#                                         consumed|algo|perms|format>               → exit 75
+#   SOLEUR_BOOTSTRAP_PLAN_DRIFT           stage=<s>                      → exit 75, receipt burned
+#   SOLEUR_BOOTSTRAP_PRECONDITION_FAILED  stage=<s> need=<stage>         → exit 1 (settles as refused;
+#                                         run the `need` stage, then this one again)
+#   SOLEUR_BOOTSTRAP_PATH_UNSUPPORTED     stage=<s>                      → exit 64 (script path has a ')
+#   SOLEUR_BOOTSTRAP_STAGE_REQUIRED       (no marker args)               → exit 64 (no --stage: no run-all mode)
+#   SOLEUR_BOOTSTRAP_UNKNOWN_STAGE        stage=<s>                      → exit 64 (not in the stage table)
+#   SOLEUR_BOOTSTRAP_PLAN_DIGEST_REQUIRED stage=<s>                      → exit 64 (--apply without the digest)
+#   SOLEUR_BOOTSTRAP_STAGE_OK             stage=<s> changed=<0|1> [approval=<harness-receipt|tty-ack>]
+#   SOLEUR_BOOTSTRAP_STAGE_FAILED         stage=<s> rc=<n>
+#   SOLEUR_BOOTSTRAP_LIB_INCOMPATIBLE     need=stage-1 got=<n>            → exit 64 (consumer)
+
+# SOLEUR_BOOTSTRAP_LIB_MISSING, _LIB_INCOMPATIBLE and _ENV_NOT_IGNORED are
+# emitted by the CONSUMER, not by this file — a library that is not there cannot
+# announce itself. The canonical shape of that resolution (env override →
+# CLAUDE_PLUGIN_ROOT → generation-time baked path → hard exit 64, never a stub;
+# ADR-178 Context §1 records what fail-closed stubs did to `cleanup-merged`) is
+# the "library resolution" section of
+# plugins/soleur/skills/operator-bootstrap/template.sh.
+#
+# <!-- Inspired by mattpocock/skills/skills/engineering/wizard/ (MIT, Copyright (c) 2026 Matt Pocock). -->
+# What is adopted is the SHAPE — a wizard that walks named stages, one journey
+# per stage, with the operator told what will happen before it happens. The code
+# is extracted from in-repo prior art, not ported: five of the six primitives
+# already existed here (apps/cla-evidence/infra/bootstrap.sh for stage progress,
+# preflight and the closing summary; community/scripts/{x,bsky,discord}-setup.sh
+# for the exact-key `.env` upsert; operator-digest/scripts/
+# provision-operator-digest-repo.sh for the stdin-only secret write and the
+# separate argv variable write). Only cross-platform URL opening is new.
+
+# Guard against double-source within a single shell.
+if [[ "${_SOLEUR_OPERATOR_SCRIPT_LOADED:-}" == "1" ]]; then
+  return 0 2>/dev/null || true
+fi
+_SOLEUR_OPERATOR_SCRIPT_LOADED=1
+
+# The class-2 ack's in-process result (#8486, ADR-249). Cleared at load so an
+# inherited or exported value can never stand in for an ack that did not happen
+# here; soleur_op_ack_or_die assigns it (never exports it) after a typed `yes`,
+# and plugins/soleur/scripts/audit-flag-flip.sh refuses to append without it.
+unset SOLEUR_OP_ACKED
+
+# The API contract every consumer asserts after its `source` line (header §API).
+export SOLEUR_OP_LIB_API=1
+
+# The generated `.env` holds live credentials on the founder's own disk, and a
+# default umask writes it 0644 into a directory that may sit under a cloud-sync
+# client. 077 here, and `chmod 600` asserted after every upsert.
+umask 077
+
+# ---------------------------------------------------------------------------
+# Approval receipts — the algorithm shared by the approval HOOK and this library
+# ---------------------------------------------------------------------------
+#
+# The hook (plugins/soleur/hooks/operator-stage-approval.sh) SOURCES this file for
+# `soleur_approval_*`, so MINT and VERIFY share ONE digest algorithm in ONE file
+# and one diff moves both. (An earlier draft kept this in a sibling file; every
+# harness that copies the library to a sandbox then lost it. One file is the
+# distribution contract the rest of this header already states.) The independent
+# anchor is the known-answer vector set in plugins/soleur/test/operator-script.test.sh,
+# computed with python3 hashlib.
+#
+# WHAT A RECEIPT IS. When the human approves the exact command the agent is about
+# to run, the harness hook has already minted a one-time record on the human's
+# machine, and the nonce that unlocks it rides INSIDE the approved command line
+# (an environment prefix the hook rewrote in). The script recomputes the digest of
+# its own invocation, finds the record named sha256(nonce), and consumes it
+# (rename) BEFORE the first write. An environment variable or a flag the agent sets
+# by itself is therefore never an approval: the nonce is a LOOKUP KEY into a record
+# the hook wrote, and any value with no matching record is exit 75.
+#
+# HONEST THRESHOLD (ADR-264, binding): the record is a file the same OS user can
+# write. This resists an instruction-following agent that follows skill text and
+# exit markers; it does NOT resist a hijacked agent that deliberately forges a
+# record. Closing that needs a principal the agent cannot write as (credential
+# custody, ADR-249 step 2). Never describe this mechanism as stronger.
+#
+# A failure in this section is a `return`, never an `exit`: the consumer owns the
+# exit code (a library exit kills the caller).
+
+# The record format version. A record or digest carrying any other value is
+# refused with reason=algo, never as a generic failure (version skew is a
+# distinct, reportable condition).
+SOLEUR_APPROVAL_ALGO=1
+# A record is valid for five minutes. Long enough for a human to read the prompt,
+# short enough that a record the human denied is dead soon. A new mint for the same
+# session also removes that session's earlier unconsumed records (soleur_approval_mint).
+SOLEUR_APPROVAL_TTL_SECONDS=300
+
+# The presented nonce is taken OUT of the environment the moment this file is loaded
+# and held in a plain (never exported) shell variable. A child process the script
+# starts later (doppler, gh, curl, a stage helper) therefore never inherits it, and
+# the only function that ever reads it is soleur_approval_consume / _burn. The hook
+# sources this file too and presents no nonce, so it holds the empty string there.
+unset _SOLEUR_APPROVAL_NONCE_HELD
+_SOLEUR_APPROVAL_NONCE_HELD="${SOLEUR_APPROVAL_NONCE:-}"
+unset SOLEUR_APPROVAL_NONCE
+
+# soleur_approval_sha256  — stdin to a lowercase hex digest on stdout.
+soleur_approval_sha256() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | cut -d' ' -f1
+  else
+    shasum -a 256 | cut -d' ' -f1
+  fi
+}
+
+# soleur_approval_dir  — where records live: outside the worktree, per user.
+soleur_approval_dir() {
+  printf '%s' "${XDG_STATE_HOME:-${HOME:-/nonexistent}/.local/state}/soleur/approvals"
+}
+
+# soleur_approval_realpath <path>  — the resolved absolute path of an existing
+# file, falling back to the unresolved absolute path (readlink -f may be absent
+# on older macOS).
+soleur_approval_realpath() {
+  local p="$1" d
+  readlink -f -- "$p" 2>/dev/null && return 0
+  d="$(cd "$(dirname "$p")" 2>/dev/null && pwd -P)" || { printf '%s' "$p"; return 0; }
+  printf '%s/%s' "$d" "$(basename "$p")"
+}
+
+# soleur_approval_content_hash <file>  — sha256 of the file's bytes, or the fixed
+#   word `unreadable`. A receipt is bound to the script's CONTENT as well as its
+#   path: a script edited between the human's approval and the run no longer matches.
+soleur_approval_content_hash() {
+  local h
+  h="$(soleur_approval_sha256 < "$1" 2>/dev/null)" || h=""
+  [[ "$h" =~ ^[0-9a-f]{64}$ ]] && printf '%s' "$h" || printf 'unreadable'
+}
+
+# soleur_approval_binding_digest <script-realpath> <stage> <arg>...
+#   The digest an approval is bound to: the resolved script, its content hash, the
+#   stage and every argument EXACTLY as the shell handed it over. Every variable
+#   field is written as `<byte-length>:<value>` so no value, whatever characters it
+#   carries (a newline included), can read as the next field. The hook computes it
+#   from the command string it parsed; the script recomputes it from "$@". The two
+#   are equal only for the same invocation of the same script bytes.
+soleur_approval_binding_digest() {
+  local real="$1" stage="$2" a content
+  shift 2
+  content="$(soleur_approval_content_hash "$real")"
+  {
+    local LC_ALL=C
+    printf 'algo=%s\n' "$SOLEUR_APPROVAL_ALGO"
+    printf 'script=%d:%s\n' "${#real}" "$real"
+    printf 'content=%s\n' "$content"
+    printf 'stage=%d:%s\n' "${#stage}" "$stage"
+    for a in "$@"; do printf 'arg=%d:%s\n' "${#a}" "$a"; done
+  } | soleur_approval_sha256
+}
+
+# soleur_approval_nonce_ok <value>  — a 32-hex-digit (128-bit) nonce.
+soleur_approval_nonce_ok() {
+  [[ "${1:-}" =~ ^[0-9a-f]{32}$ ]]
+}
+
+# soleur_approval_new_nonce  — 128 random bits as 32 hex digits.
+soleur_approval_new_nonce() {
+  od -An -N16 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n'
+}
+
+# _soleur_approval_stat <path>  — "<uid> <octal-mode>" or empty.
+_soleur_approval_stat() {
+  stat -c '%u %a' -- "$1" 2>/dev/null || stat -f '%u %Lp' -- "$1" 2>/dev/null || true
+}
+
+# _soleur_approval_dir_ok <dir>  — a real directory (never a symlink), owned by
+# this euid, mode 0700.
+_soleur_approval_dir_ok() {
+  local d="$1" st
+  [[ -d "$d" && ! -L "$d" ]] || return 1
+  st="$(_soleur_approval_stat "$d")"
+  [[ "$st" == "$(id -u) 700" ]]
+}
+
+# _soleur_approval_file_ok <file>  — a regular file (never a symlink), owned by
+# this euid, mode 0600.
+_soleur_approval_file_ok() {
+  local f="$1" st
+  [[ -f "$f" && ! -L "$f" ]] || return 1
+  st="$(_soleur_approval_stat "$f")"
+  [[ "$st" == "$(id -u) 600" ]]
+}
+
+# _soleur_approval_housekeeping <dir> <session>
+#   Runs on every mint. (1) Removes every record, consumed or not, older than an
+#   hour: the directory never grows without bound and a stale record is not left
+#   for a later session to find. (2) Removes this session's earlier UNCONSUMED
+#   records: only the newest receipt of a session is live, so a prompt the person
+#   declined cannot be revived by a later one. Best effort; a failure here never
+#   blocks a mint.
+_soleur_approval_housekeeping() {
+  local dir="$1" session="$2"
+  # find, not a glob: the approval hook runs with pathname expansion off (`set -f`).
+  find "$dir" -maxdepth 1 -type f -mmin +60 -delete 2>/dev/null || true
+  find "$dir" -maxdepth 1 -type f ! -name '*.consumed' ! -name '.mint.*' \
+    -exec grep -aqx "session=${session}" {} \; -delete 2>/dev/null || true
+  return 0
+}
+
+# soleur_approval_mint <binding-digest> <session-id>
+#   Writes one record and prints the nonce on stdout (the ONLY place it is ever
+#   printed; the caller embeds it in the rewritten command and nowhere else).
+#   The record is named sha256(nonce) so a directory listing never reveals a live
+#   nonce. Returns 1 (prints nothing) if the directory cannot be made safe.
+soleur_approval_mint() {
+  local digest="$1" session="${2:-unknown}" dir nonce name tmp expires
+  dir="$(soleur_approval_dir)"
+  if [[ ! -e "$dir" ]]; then
+    (umask 077; mkdir -p "$dir") 2>/dev/null || return 1
+    chmod 700 "$dir" 2>/dev/null || return 1
+  fi
+  _soleur_approval_dir_ok "$dir" || return 1
+  nonce="$(soleur_approval_new_nonce)"
+  soleur_approval_nonce_ok "$nonce" || return 1
+  name="$(printf '%s' "$nonce" | soleur_approval_sha256)"
+  expires=$(( $(date +%s) + SOLEUR_APPROVAL_TTL_SECONDS ))
+  _soleur_approval_housekeeping "$dir" "${session//[^A-Za-z0-9._-]/_}"
+  tmp="${dir}/.mint.$$.${name:0:12}"
+  (
+    umask 077
+    printf 'algo=%s\ndigest=%s\nexpires=%s\nsession=%s\n' \
+      "$SOLEUR_APPROVAL_ALGO" "$digest" "$expires" "${session//[^A-Za-z0-9._-]/_}" > "$tmp"
+  ) 2>/dev/null || { rm -f "$tmp"; return 1; }
+  chmod 600 "$tmp" 2>/dev/null || { rm -f "$tmp"; return 1; }
+  mv -- "$tmp" "${dir}/${name}" 2>/dev/null || { rm -f "$tmp"; return 1; }
+  printf '%s' "$nonce"
+}
+
+# SOLEUR_APPROVAL_REASON
+#   The consume functions report WHY through this variable (never stdout: stdout
+#   of a library function is often captured). One of: no-record expired
+#   digest-mismatch consumed algo perms format. Empty means "no nonce was
+#   presented" (a different outcome: approval REQUIRED, not INVALID).
+SOLEUR_APPROVAL_REASON=""
+SOLEUR_APPROVAL_NONCE_SHA12=""
+
+# soleur_approval_consume <binding-digest>
+#   0 — a valid unexpired record for exactly this digest existed and has been
+#       renamed to <name>.consumed (single use; the rename IS the consumption and
+#       happens BEFORE the caller's first write).
+#   1 — nothing was consumed; SOLEUR_APPROVAL_REASON says why ("" = no nonce).
+soleur_approval_consume() {
+  local digest="$1" nonce dir name rec algo rdigest expires now
+  SOLEUR_APPROVAL_REASON=""
+  SOLEUR_APPROVAL_NONCE_SHA12=""
+  nonce="${_SOLEUR_APPROVAL_NONCE_HELD:-}"
+  [[ -n "$nonce" ]] || return 1
+  if ! soleur_approval_nonce_ok "$nonce"; then SOLEUR_APPROVAL_REASON=format; return 1; fi
+  dir="$(soleur_approval_dir)"
+  # No directory at all means the hook never minted anything here: no record. A
+  # directory that exists but is a symlink, foreign-owned or not 0700 is a tamper
+  # class: perms.
+  [[ -e "$dir" || -L "$dir" ]] || { SOLEUR_APPROVAL_REASON=no-record; return 1; }
+  _soleur_approval_dir_ok "$dir" || { SOLEUR_APPROVAL_REASON=perms; return 1; }
+  name="$(printf '%s' "$nonce" | soleur_approval_sha256)"
+  SOLEUR_APPROVAL_NONCE_SHA12="${name:0:12}"
+  rec="${dir}/${name}"
+  if [[ ! -e "$rec" && ! -L "$rec" ]]; then
+    if [[ -e "${rec}.consumed" ]]; then SOLEUR_APPROVAL_REASON=consumed; else SOLEUR_APPROVAL_REASON=no-record; fi
+    return 1
+  fi
+  _soleur_approval_file_ok "$rec" || { SOLEUR_APPROVAL_REASON=perms; return 1; }
+  # Field extraction without a `read` loop (the prompt census in Guard 4 treats every
+  # `read` in this file as a prompt, and these are not).
+  algo="$(grep -a '^algo=' "$rec" | head -n 1 | cut -d= -f2-)"
+  rdigest="$(grep -a '^digest=' "$rec" | head -n 1 | cut -d= -f2-)"
+  expires="$(grep -a '^expires=' "$rec" | head -n 1 | cut -d= -f2-)"
+  [[ "$algo" == "$SOLEUR_APPROVAL_ALGO" ]] || { SOLEUR_APPROVAL_REASON=algo; return 1; }
+  [[ "$rdigest" =~ ^[0-9a-f]{64}$ && "$expires" =~ ^[0-9]+$ ]] || { SOLEUR_APPROVAL_REASON=format; return 1; }
+  [[ "$rdigest" == "$digest" ]] || { SOLEUR_APPROVAL_REASON=digest-mismatch; return 1; }
+  now="$(date +%s)"
+  (( expires > now )) || { SOLEUR_APPROVAL_REASON=expired; return 1; }
+  # Single use. A lost rename race (two applies, one record) fails here and the
+  # loser writes nothing.
+  if ! mv -- "$rec" "${rec}.consumed" 2>/dev/null; then
+    # The record is gone: another run won the rename. Still there: the rename itself
+    # failed (permissions, a full disk) and that is a different, reportable condition.
+    if [[ -e "$rec" ]]; then SOLEUR_APPROVAL_REASON=perms; else SOLEUR_APPROVAL_REASON=consumed; fi
+    return 1
+  fi
+  _SOLEUR_APPROVAL_NONCE_HELD=""
+  return 0
+}
+
+# soleur_approval_burn
+#   Consume whatever record the presented nonce points at, valid or not: a plan
+#   that drifted between plan and apply must not leave a live receipt behind.
+soleur_approval_burn() {
+  local nonce dir name rec
+  nonce="${_SOLEUR_APPROVAL_NONCE_HELD:-}"
+  soleur_approval_nonce_ok "$nonce" || return 0
+  dir="$(soleur_approval_dir)"
+  _soleur_approval_dir_ok "$dir" || return 0
+  name="$(printf '%s' "$nonce" | soleur_approval_sha256)"
+  rec="${dir}/${name}"
+  [[ -f "$rec" && ! -L "$rec" ]] || return 0
+  mv -- "$rec" "${rec}.consumed" 2>/dev/null || true
+  _SOLEUR_APPROVAL_NONCE_HELD=""
+}
+
+# ---------------------------------------------------------------------------
+# Output helpers (shape from apps/cla-evidence/infra/bootstrap.sh)
+# ---------------------------------------------------------------------------
+
+SOLEUR_OP_GREEN='\033[32m'
+SOLEUR_OP_RED='\033[31m'
+SOLEUR_OP_YELLOW='\033[33m'
+SOLEUR_OP_NC='\033[0m'
+
+soleur_op_red()    { printf '%b%s%b\n' "$SOLEUR_OP_RED"    "$*" "$SOLEUR_OP_NC" >&2; }
+soleur_op_green()  { printf '%b%s%b\n' "$SOLEUR_OP_GREEN"  "$*" "$SOLEUR_OP_NC"; }
+soleur_op_yellow() { printf '%b%s%b\n' "$SOLEUR_OP_YELLOW" "$*" "$SOLEUR_OP_NC"; }
+
+# ---------------------------------------------------------------------------
+# Preflight
+# ---------------------------------------------------------------------------
+
+# soleur_op_require_bins <bin>...
+#   Exit 64 naming the first missing binary. The ladder (environment → Doppler →
+#   MCP/CLI/REST) runs BEFORE any prompt; a value outside the two interactive
+#   carve-outs that is missing is a hard failure with a named remedy, never a
+#   prompt.
+#   STDOUT marker plus one plain sentence: agent runtimes surface stdout and
+#   swallow stderr, and a founder reads the sentence, not the marker.
+soleur_op_require_bins() {
+  local bin
+  for bin in "$@"; do
+    command -v "$bin" >/dev/null 2>&1 || {
+      printf 'SOLEUR_BOOTSTRAP_MISSING_BINARY bin=%s\n' "$bin"
+      printf 'Install %s first, then run again.\n' "$bin"
+      exit 64
+    }
+  done
+}
+
+# ---------------------------------------------------------------------------
+# Run ledger — one JSON line per stage, BEFORE and AFTER. Names, never values.
+# ---------------------------------------------------------------------------
+#
+# Layer 7 (cli-stdout-artifact): stdout alone is an explicit P1 rejection because
+# it does not survive the session, so the synchronous markers above are paired
+# with this durable artifact. ONE convention: the ledger sits BESIDE the script
+# that writes it, as `bootstrap-runs.jsonl` — for a generated script that is
+# `knowledge-base/project/specs/feat-<name>/`, tracked in the FOUNDER's
+# repository, which is where the layer's "committed to the customer's own
+# repository" condition is met. Nothing is transmitted and no alert target
+# exists — the surface is the founder's own machine, and routing it to Soleur
+# infrastructure would be a data-controller event, not an observability
+# improvement.
+#
+# A write that fails (disk full, unwritable directory) is NON-FATAL — a
+# provisioning stage must not abort because its audit line could not be
+# appended — but it is never silent: `SOLEUR_BOOTSTRAP_LEDGER_WRITE_FAILED
+# path=<path>` goes to stdout so the founder knows the artifact is incomplete.
+
+# `$$` until soleur_op_ledger_init assigns the timestamped id: a helper that
+# writes a ledger line before init (the `--reset` path does) must still carry a
+# non-empty run_id, or the artifact has lines no run can be attributed to.
+SOLEUR_OP_RUN_ID="$$"
+SOLEUR_OP_TOTAL_STAGES=0
+# Resolved ONCE (first use or soleur_op_ledger_init) and cached: the default is
+# derived from the bottom of BASH_SOURCE, which may be relative, and a `cd` inside a stage
+# would otherwise split one run's lines across two files.
+SOLEUR_OP_LEDGER_FILE=""
+
+# Default: beside the MAIN script (the bottom of the source stack), never a
+# cwd-relative dotdir. `SOLEUR_BOOTSTRAP_LEDGER` overrides.
+soleur_op_ledger_path() {
+  local main_script main_dir
+  if [[ -n "$SOLEUR_OP_LEDGER_FILE" ]]; then
+    printf '%s' "$SOLEUR_OP_LEDGER_FILE"
+    return 0
+  fi
+  if [[ -n "${SOLEUR_BOOTSTRAP_LEDGER:-}" ]]; then
+    SOLEUR_OP_LEDGER_FILE="$SOLEUR_BOOTSTRAP_LEDGER"
+  else
+    # `${BASH_SOURCE[${#BASH_SOURCE[@]}-1]}`, not `[-1]`: negative subscripts
+    # are bash 4.3+ and the 3.2 that macOS ships dies here with "bad array
+    # subscript" — fatal under set -e, stderr only, no marker.
+    main_script="${BASH_SOURCE[${#BASH_SOURCE[@]}-1]:-}"
+    # Sourced with no main script (an interactive shell, `bash -c`): the bottom of
+    # the stack is this file, and "beside the library" is not a ledger home.
+    if [[ -z "$main_script" || "$main_script" == "${BASH_SOURCE[0]}" ]]; then
+      SOLEUR_OP_LEDGER_FILE="$(pwd)/bootstrap-runs.jsonl"
+    else
+      main_dir="$(cd "$(dirname "$main_script")" 2>/dev/null && pwd)" || main_dir="$(dirname "$main_script")"
+      SOLEUR_OP_LEDGER_FILE="${main_dir}/bootstrap-runs.jsonl"
+    fi
+  fi
+  printf '%s' "$SOLEUR_OP_LEDGER_FILE"
+}
+
+soleur_op_now() { date -u '+%Y-%m-%dT%H:%M:%SZ'; }
+
+# JSON string escaping for the field set below (names and small integers by
+# construction): newline and carriage return become a space FIRST, because the
+# sed that follows is line-oriented and would otherwise pass a second line
+# through unescaped; U+2028/U+2029 are stripped (JSON allows them raw, but a
+# JS-hosted reader treats them as line terminators); backslash and double quote
+# are escaped; remaining control characters collapse to a space.
+soleur_op_json_escape() {
+  local s="$1"
+  s="${s//$'\n'/ }"
+  s="${s//$'\r'/ }"
+  s="${s//$'\xe2\x80\xa8'/}"
+  s="${s//$'\xe2\x80\xa9'/}"
+  printf '%s' "$s" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/[[:cntrl:]]/ /g'
+}
+
+# soleur_op_json_int <value>
+#   A bare JSON number, or 0 when the argument is not an integer — an unquoted
+#   non-number would make the whole line unparseable.
+soleur_op_json_int() {
+  if [[ "${1:-}" =~ ^-?[0-9]+$ ]]; then printf '%s' "$1"; else printf '0'; fi
+}
+
+soleur_op_ledger_write() {
+  local path line
+  path="$(soleur_op_ledger_path)"
+  line="$1"
+  mkdir -p "$(dirname "$path")" 2>/dev/null || true
+  if ! printf '%s\n' "$line" >> "$path" 2>/dev/null; then
+    printf 'SOLEUR_BOOTSTRAP_LEDGER_WRITE_FAILED path=%s\n' "$path"
+  fi
+}
+
+# soleur_op_ledger_init <total-stages> <script-name>
+soleur_op_ledger_init() {
+  SOLEUR_OP_TOTAL_STAGES="$(soleur_op_json_int "${1:-}")"
+  SOLEUR_OP_RUN_ID="$(date -u '+%Y%m%dT%H%M%SZ')-$$"
+  soleur_op_ledger_path >/dev/null
+  soleur_op_ledger_write "$(printf '{"ts":"%s","run_id":"%s","event":"run_begin","total_stages":%s,"script":"%s"}' \
+    "$(soleur_op_now)" "$SOLEUR_OP_RUN_ID" "$SOLEUR_OP_TOTAL_STAGES" "$(soleur_op_json_escape "${2:-unknown}")")"
+}
+
+# soleur_op_ledger_note <kind> <name> <detail>
+#   `name` is a KEY NAME or a SECRET NAME. `detail` is metadata — never a value.
+#   Guard 3 drives a mutation that swaps a value into `detail` and asserts the
+#   suite reddens, because "names never values" is otherwise a comment.
+soleur_op_ledger_note() {
+  soleur_op_ledger_write "$(printf '{"ts":"%s","run_id":"%s","kind":"%s","name":"%s","detail":"%s"}' \
+    "$(soleur_op_now)" "$SOLEUR_OP_RUN_ID" \
+    "$(soleur_op_json_escape "$1")" "$(soleur_op_json_escape "$2")" "$(soleur_op_json_escape "${3:-}")")"
+}
+
+# soleur_op_stage_begin <index> <name>
+soleur_op_stage_begin() {
+  printf '\n→ [%s/%s] %s\n' "$1" "$SOLEUR_OP_TOTAL_STAGES" "$2"
+  soleur_op_ledger_write "$(printf '{"ts":"%s","run_id":"%s","event":"stage","phase":"begin","stage_index":%s,"total_stages":%s,"stage_name":"%s","outcome":"pending","exit_code":null}' \
+    "$(soleur_op_now)" "$SOLEUR_OP_RUN_ID" "$(soleur_op_json_int "$1")" "$(soleur_op_json_int "$SOLEUR_OP_TOTAL_STAGES")" "$(soleur_op_json_escape "$2")")"
+}
+
+# soleur_op_stage_end <index> <name> <outcome> <exit-code>
+soleur_op_stage_end() {
+  soleur_op_ledger_write "$(printf '{"ts":"%s","run_id":"%s","event":"stage","phase":"settle","stage_index":%s,"total_stages":%s,"stage_name":"%s","outcome":"%s","exit_code":%s}' \
+    "$(soleur_op_now)" "$SOLEUR_OP_RUN_ID" "$(soleur_op_json_int "$1")" "$(soleur_op_json_int "$SOLEUR_OP_TOTAL_STAGES")" \
+    "$(soleur_op_json_escape "$2")" "$(soleur_op_json_escape "$3")" "$(soleur_op_json_int "${4:-0}")")"
+}
+
+# There is deliberately NO resume index. Every stage opens with an "already
+# satisfied?" precondition (operator-bootstrap/SKILL.md §2), so re-running from
+# stage 1 IS resume; a start-stage variable would be a second mechanism for the
+# same property, and one the precondition already makes redundant.
+
+# ---------------------------------------------------------------------------
+# Prompts — R8's THREE carve-out classes
+# ---------------------------------------------------------------------------
+#
+#   class 1  NON-SECRET ladder value (a region, an account id, a repo slug)
+#            → named skip variable; no TTY + unset ⇒ exit 64 naming it.
+#              Credential ENTRY stays in the CALLER with its own `read -rs`
+#              behind the same gate — see provision-hetzner.sh. This helper
+#              echoes its input and must never take a secret.
+#   class 2  per-command destructive-write acknowledgement
+#            → NO SKIP VARIABLE AT ALL. No TTY ⇒ exit 64 unconditionally.
+#              An environment variable set once is exactly the "prior approval
+#              extending to a new command" hr-menu-option-ack-not-prod-write-auth
+#              forbids, so automation must not be able to supply this.
+#   class 3  out-of-band completion barrier ("Token created? Type 'yes'")
+#            → named skip variable, AND the caller MUST follow it with an
+#              independent verification of the thing attested. A barrier that is
+#              skippable and unverified attests nothing.
+#
+# A fourth class requires an ADR amendment (ADR-228).
+
+# --- MUTATION ANCHOR: start of prompt helpers ---
+
+# soleur_op_skip_value <VAR-NAME>
+#   `printenv`, deliberately, NOT `${!name}`: indirect expansion would put this
+#   file into the credential linter's scope (library invariant, above).
+soleur_op_skip_value() {
+  printenv "$1" 2>/dev/null || true
+}
+
+# soleur_op_run_halt <reason> <name>
+#   The ledger's TERMINAL line for a run that stops before its stages settle:
+#   `reason` is `input_required` or `aborted`, `name` the variable or the stage
+#   kind. Without it the ledger could only ever say "ok" (review P2-12).
+soleur_op_run_halt() {
+  soleur_op_ledger_write "$(printf '{"ts":"%s","run_id":"%s","event":"run_halt","reason":"%s","var":"%s"}' \
+    "$(soleur_op_now)" "$SOLEUR_OP_RUN_ID" "$(soleur_op_json_escape "$1")" "$(soleur_op_json_escape "$2")")"
+}
+
+# soleur_op_input_required <VAR-NAME-or-reason> [ack]
+#   The no-TTY refusal. Emitted BEFORE any read, never after. Today's behaviour
+#   in provision-hetzner.sh is fail-closed but MUTE — EOF read into an empty ACK
+#   and `exit 1` with "Aborted." — the right outcome with an unattributed cause.
+#   The marker is for the agent; the sentence after it is for the founder. The
+#   second argument `ack` selects the class-2 sentence: there is no variable to
+#   set, so the only remedy is a person at a terminal.
+soleur_op_input_required() {
+  printf 'SOLEUR_BOOTSTRAP_INPUT_REQUIRED var=%s tty=0\n' "$1"
+  if [[ "${2:-}" == "ack" ]]; then
+    # Legacy class-2 ack only (a script not yet moved to the staged contract):
+    # the approval is a typed yes at a terminal and nothing set by an agent can
+    # stand in for it. A v2 generated script never reaches this line.
+    printf 'This older script can only be approved by a person typing yes at a terminal; no setting can answer it for you. Regenerate it with the operator-bootstrap skill to get the staged form, where the approval happens at the Claude Code prompt on the exact command.\n'
+  else
+    printf 'This step needs one value. Set %s and run again; the agent can set it for you if you give it the value (a non-secret one) or point it at where the value already lives.\n' "$1"
+  fi
+  soleur_op_run_halt input_required "$1"
+  exit 64
+}
+
+# soleur_op_aborted <kind>
+#   The operator declined. Marker, plain sentence, ledger line, exit 1.
+soleur_op_aborted() {
+  printf 'SOLEUR_BOOTSTRAP_ABORTED stage=%s\n' "$1"
+  printf 'Stopped. Nothing was created.\n'
+  soleur_op_run_halt aborted "$1"
+  exit 1
+}
+
+# soleur_op_value <SKIP-VAR> <prompt> <out-var-name>   [class 1]
+#   Writes the answer into the named variable with `printf -v` rather than to
+#   stdout. Deliberate: a `$(...)` capture would run the helper in a SUBSHELL,
+#   where `exit 64` kills only the subshell and the script sails on past a
+#   prompt it never answered.
+soleur_op_value() {
+  local var_name="$1" prompt_text="$2" out_name="$3" skip reply
+  skip="$(soleur_op_skip_value "$var_name")"
+  if [[ -n "$skip" ]]; then
+    printf -v "$out_name" '%s' "$skip"
+    return 0
+  fi
+  [[ -t 0 ]] || soleur_op_input_required "$var_name"
+  read -r -p "$prompt_text" reply
+  printf -v "$out_name" '%s' "$reply"
+}
+
+# soleur_op_barrier <SKIP-VAR> <prompt>               [class 3]
+#   MUST be followed by an independent verification of the thing attested.
+soleur_op_barrier() {
+  local var_name="$1" prompt_text="$2" skip reply
+  skip="$(soleur_op_skip_value "$var_name")"
+  if [[ -n "$skip" ]]; then
+    printf '  [skip] %s (%s is set; the caller still runs its own verification)\n' "$prompt_text" "$var_name"
+    return 0
+  fi
+  [[ -t 0 ]] || soleur_op_input_required "$var_name"
+  read -r -p "$prompt_text" reply
+  [[ "$reply" == "yes" ]] || soleur_op_aborted barrier
+}
+
+# soleur_op_in_agent_harness
+#   True when this process runs under an agent harness (Claude Code sets CLAUDECODE
+#   and CLAUDE_CODE_ENTRYPOINT in every tool call's environment). A typed `yes` on a
+#   pseudo-terminal is accepted only when this is false. HONEST LIMIT: an agent that
+#   deliberately unsets these names and opens a pty defeats it; that is the
+#   hijacked-agent case the receipt threshold already excludes (ADR-264).
+soleur_op_in_agent_harness() {
+  [[ -n "${CLAUDECODE:-}" || -n "${CLAUDE_CODE_ENTRYPOINT:-}" ]]
+}
+
+# soleur_op_ack_or_die <prompt>                       [class 2]
+#   NO skip variable, by design and by rule. Do not add one.
+soleur_op_ack_or_die() {
+  local prompt_text="$1" reply
+  if soleur_op_in_agent_harness; then
+    soleur_op_input_required "destructive-write-ack(agent-harness-no-typed-ack)" ack
+  fi
+  [[ -t 0 ]] || soleur_op_input_required "destructive-write-ack(no-skip-variable-by-design)" ack
+  read -r -p "$prompt_text" reply
+  [[ "$reply" == "yes" ]] || soleur_op_aborted ack
+  SOLEUR_OP_ACKED=tty-ack
+}
+
+# --- MUTATION ANCHOR: end of prompt helpers ---
+
+# ---------------------------------------------------------------------------
+# Staged contract — agent-run stages, harness-approved writes (ADR-264)
+# ---------------------------------------------------------------------------
+#
+# A v2 generated script is driven ONE STAGE AT A TIME by an agent with no TTY:
+#
+#   bash bootstrap.sh --list
+#   bash bootstrap.sh --stage <name>                                  read stage: runs; write stage: prints the PLAN
+#   bash bootstrap.sh --stage <name> --apply --plan-digest <d>        write stage: performs the write
+#
+# Every write needs a human acknowledgement of the EXACT command. It moves out of
+# the terminal into the harness approval channel: the approval hook minted a
+# one-time receipt when the human approved the command, and the nonce for it rode
+# inside that command (the "Approval receipts" section above). This library never trusts a value
+# the caller supplies about the approval: the plan is RECOMPUTED, the digest is
+# RECOMPUTED, the nonce is only a lookup key into a record the hook wrote.
+#
+# THE ORDER INSIDE soleur_op_stage_gate IS THE CONTRACT (each step is a mutation
+# row of Guard 11): recompute the plan and compare the digest (drift burns the
+# receipt) -> validate the nonce against its record -> CONSUME the record (rename)
+# -> unset the nonce so no child inherits it -> only then may the caller write.
+# Otherwise a real TTY typed `yes` is the second valid source; otherwise exit 75.
+#
+# NO MARKER INSIDE A `$(...)` CAPTURE: a marker printed by a function whose stdout
+# is captured becomes the captured value. Every function below that prints is
+# called directly, never as `x=$(fn)`.
+
+SOLEUR_OP_PLAN_OPS=()
+SOLEUR_OP_APPROVAL=""
+# Set by soleur_op_stage_gate immediately before it exits 75. The EXIT trap of a
+# generated script settles the stage as `refused` on THIS flag, never on the bare
+# exit code: a vendor CLI that happens to exit 75 mid-write must not be reported as
+# a clean refusal.
+SOLEUR_OP_REFUSED=""
+
+# soleur_op_shquote <word>  — the word as one shell-safe token (raw when it is
+# plain, single-quoted otherwise). Returns 1 and prints nothing for a word that
+# contains a single quote: no quoting of it survives the approval hook's parser, so
+# the caller refuses (soleur_op_plan_emit) instead of printing a command the hook
+# cannot ask about.
+soleur_op_shquote() {
+  if [[ "$1" =~ ^[A-Za-z0-9_./:=@+,-]+$ ]]; then
+    printf '%s' "$1"
+  elif [[ "$1" == *"'"* ]]; then
+    return 1
+  else
+    printf "'%s'" "$1"
+  fi
+}
+
+# soleur_op_stage_lines <script>
+#   The script's own declarations, one per line: name|class|impact|rollback. The
+#   SAME lines are read by the approval hook, so there is one source of truth.
+soleur_op_stage_lines() {
+  grep -a '^# SOLEUR-STAGE ' "$1" 2>/dev/null | sed 's/^# SOLEUR-STAGE //'
+}
+
+# soleur_op_stage_field <script> <stage> <1=name 2=class 3=impact 4=rollback>
+#   Empty (return 1) when the stage is not declared.
+soleur_op_stage_field() {
+  soleur_op_stage_lines "$1" | awk -F'|' -v s="$2" -v f="$3" '$1 == s && !found { print $f; found = 1 } END { exit !found }'
+}
+
+# soleur_op_list <script>  — the machine-readable stage table.
+soleur_op_list() {
+  soleur_op_stage_lines "$1" | awk -F'|' '{ printf "SOLEUR_BOOTSTRAP_STAGE_DECL stage=%s class=%s\n", $1, $2 }'
+}
+
+# soleur_op_plan_begin / soleur_op_plan_op <op-name> <target-name>
+#   A plan is a list of operation NAMES and the container/slug/secret NAMES they
+#   touch — never a value. The digest covers exactly this list.
+soleur_op_plan_begin() { SOLEUR_OP_PLAN_OPS=(); }
+soleur_op_plan_op() { SOLEUR_OP_PLAN_OPS[${#SOLEUR_OP_PLAN_OPS[@]}]="$1|${2:-}"; }
+soleur_op_plan_count() { printf '%s' "${#SOLEUR_OP_PLAN_OPS[@]}"; }
+
+# soleur_op_plan_digest <script-real> <stage> <flags> <impact> <rollback>
+#   Deterministic digest of what an apply will do and what the human was told.
+#   The impact and rollback TEXT is inside it, so the words the human read are
+#   the words that were approved.
+soleur_op_plan_digest() {
+  local op content
+  content="$(soleur_approval_content_hash "$1")"
+  {
+    local LC_ALL=C
+    printf 'algo=%s\n' "$SOLEUR_APPROVAL_ALGO"
+    printf 'script=%d:%s\ncontent=%s\n' "${#1}" "$1" "$content"
+    printf 'stage=%d:%s\nflags=%d:%s\n' "${#2}" "$2" "${#3}" "$3"
+    printf 'impact=%d:%s\nrollback=%d:%s\n' "${#4}" "$4" "${#5}" "$5"
+    for op in ${SOLEUR_OP_PLAN_OPS[@]+"${SOLEUR_OP_PLAN_OPS[@]}"}; do printf 'op=%d:%s\n' "${#op}" "$op"; done
+  } | soleur_approval_sha256
+}
+
+# soleur_op_plan_emit <script-real> <stage> <rotate 0|1>
+#   Prints the plan a human is asked to approve and the exact command that
+#   applies it. Declared impact and rollback text come from the script's own
+#   stage line; the agent relays them verbatim and composes none of its own.
+soleur_op_plan_emit() {
+  local real="$1" stage="$2" rotate="${3:-0}" impact rollback flags="" digest op n apply_cmd approval quoted
+  impact="$(soleur_op_stage_field "$real" "$stage" 3)"
+  rollback="$(soleur_op_stage_field "$real" "$stage" 4)"
+  [[ "$rotate" == "1" ]] && flags="rotate-token"
+  digest="$(soleur_op_plan_digest "$real" "$stage" "$flags" "$impact" "$rollback")"
+  n="$(soleur_op_plan_count)"
+  printf 'SOLEUR_BOOTSTRAP_PLAN stage=%s operations=%s digest=%s\n' "$stage" "$n" "$digest"
+  for op in ${SOLEUR_OP_PLAN_OPS[@]+"${SOLEUR_OP_PLAN_OPS[@]}"}; do
+    printf 'SOLEUR_BOOTSTRAP_PLAN_OP stage=%s op=%s target=%s\n' "$stage" "${op%%|*}" "${op#*|}"
+  done
+  printf 'SOLEUR_BOOTSTRAP_IMPACT stage=%s text=%s\n' "$stage" "$impact"
+  printf 'SOLEUR_BOOTSTRAP_ROLLBACK stage=%s text=%s\n' "$stage" "$rollback"
+  if (( n == 0 )); then
+    printf 'Nothing to change for this stage: do NOT run --apply, there is nothing to approve.\n'
+    SOLEUR_OP_PLAN_DIGEST="$digest"
+    return 0
+  fi
+  if ! quoted="$(soleur_op_shquote "$real")"; then
+    printf 'SOLEUR_BOOTSTRAP_PATH_UNSUPPORTED stage=%s\n' "$stage"
+    printf 'This script lives at a path containing a single quote, which the approval prompt cannot carry. Move the script to a path without one and run the stage again; nothing was changed.\n'
+    exit 64
+  fi
+  apply_cmd="bash ${quoted} --stage ${stage} --apply --plan-digest ${digest}"
+  [[ "$rotate" == "1" ]] && apply_cmd="${apply_cmd} --rotate-token"
+  # approval_digest names the exact command printed below (script bytes included). It is an
+  # identifier for the receipt, never an approval: no variable or flag turns it into one.
+  if [[ "$rotate" == "1" ]]; then
+    approval="$(soleur_approval_binding_digest "$real" "$stage" --stage "$stage" --apply --plan-digest "$digest" --rotate-token)"
+  else
+    approval="$(soleur_approval_binding_digest "$real" "$stage" --stage "$stage" --apply --plan-digest "$digest")"
+  fi
+  printf 'SOLEUR_BOOTSTRAP_APPLY_COMMAND stage=%s approval_digest=%s\n' "$stage" "$approval"
+  printf '  %s\n' "$apply_cmd"
+  printf 'Tell the person the impact and rollback lines above in plain words, then run the command above exactly as printed (one simple command) and let the approval prompt carry their decision.\n'
+  SOLEUR_OP_PLAN_DIGEST="$digest"
+}
+SOLEUR_OP_PLAN_DIGEST=""
+
+# soleur_op_stage_ok <stage> <changed 0|1> [approval]
+soleur_op_stage_ok() {
+  if [[ -n "${3:-}" ]]; then
+    printf 'SOLEUR_BOOTSTRAP_STAGE_OK stage=%s changed=%s approval=%s\n' "$1" "$2" "$3"
+  else
+    printf 'SOLEUR_BOOTSTRAP_STAGE_OK stage=%s changed=%s\n' "$1" "$2"
+  fi
+}
+
+# soleur_op_precondition_failed <stage> <need-stage> <sentence>
+#   Stages are separately addressable, so a later stage re-proves what it depends
+#   on instead of trusting that an earlier one ran. Prints no plan digest.
+soleur_op_precondition_failed() {
+  printf 'SOLEUR_BOOTSTRAP_PRECONDITION_FAILED stage=%s need=%s\n' "$1" "$2"
+  printf '%s\n' "$3"
+  # A precondition is a refusal with a named remedy, not a failure of the stage: the
+  # EXIT trap settles it as `refused` and prints no "run the stage again" banner.
+  SOLEUR_OP_REFUSED=1
+  exit 1
+}
+
+# soleur_op_ledger_approval <stage> <approval> <nonce-sha12> <plan-digest> <surface>
+#   One ledger line per approved write: names and hashes of PLAN data only. The
+#   nonce itself is never written anywhere; `nonce_sha12` is the first twelve hex
+#   digits of sha256(nonce) — the record's file-name prefix — enough to tie a line
+#   to a record and no use as a credential.
+soleur_op_ledger_approval() {
+  soleur_op_ledger_write "$(printf '{"ts":"%s","run_id":"%s","event":"approval","stage":"%s","approval":"%s","nonce_sha12":"%s","plan":"%s","surface":"%s"}' \
+    "$(soleur_op_now)" "$SOLEUR_OP_RUN_ID" "$(soleur_op_json_escape "$1")" "$(soleur_op_json_escape "$2")" \
+    "$(soleur_op_json_escape "$3")" "$(soleur_op_json_escape "$4")" "$(soleur_op_json_escape "$5")")"
+}
+
+# --- MUTATION ANCHOR: start of stage gate ---
+
+# soleur_op_stage_gate <script-real> <stage> <computed-plan-digest> <supplied-digest> <impact> <rollback> <argv...>
+#   Returns 0 ONLY when this stage's write is approved; every other outcome exits
+#   75 (or 1 when a person typed anything but yes) with nothing written.
+#   <argv...> is the invocation exactly as the shell handed it over ("$@").
+#   A caller MUST call this before the first mutating command of the stage and
+#   MUST NOT run any child before it returns.
+soleur_op_stage_gate() {
+  local real="$1" stage="$2" computed="$3" supplied="$4" impact="$5" rollback="$6" binding surface
+  shift 6
+  surface="${CLAUDE_CODE_ENTRYPOINT:-unknown}"
+  binding="$(soleur_approval_binding_digest "$real" "$stage" "$@")"
+
+  # 1. The plan the human approved is the plan about to run, or nothing runs. The
+  #    supplied digest is only ever COMPARED, never trusted.
+  if [[ "$supplied" != "$computed" ]]; then
+    soleur_approval_burn
+    printf 'SOLEUR_BOOTSTRAP_PLAN_DRIFT stage=%s\n' "$stage"
+    printf 'The digest does not match the plan this script computes now (the state changed since the plan was shown, or the digest was not the one printed), so nothing was changed. Run --stage %s again (without --apply), use the digest it prints, tell the person what is different if anything is, and ask for approval again.\n' "$stage"
+    soleur_op_run_halt plan_drift "$stage"
+    SOLEUR_OP_REFUSED=1
+    exit 75
+  fi
+
+  # 2. A presented nonce must match a live record for exactly this invocation.
+  if soleur_approval_consume "$binding"; then
+    SOLEUR_OP_APPROVAL="harness-receipt"
+    soleur_op_ledger_approval "$stage" harness-receipt "$SOLEUR_APPROVAL_NONCE_SHA12" "$computed" "$surface"
+    return 0
+  fi
+  if [[ -n "$SOLEUR_APPROVAL_REASON" ]]; then
+    _SOLEUR_APPROVAL_NONCE_HELD=""
+    printf 'SOLEUR_BOOTSTRAP_APPROVAL_INVALID stage=%s reason=%s\n' "$stage" "$SOLEUR_APPROVAL_REASON"
+    case "$SOLEUR_APPROVAL_REASON" in
+      no-record|expired|digest-mismatch|consumed)
+        printf 'That approval is not usable for this command (%s), so nothing was changed. Issue the apply command once more exactly as printed by the plan, and the person will be asked again.\n' "$SOLEUR_APPROVAL_REASON" ;;
+      *)
+        printf 'A safety check on the approval failed (%s) and nothing was changed. Stop and report this to the person; do not retry.\n' "$SOLEUR_APPROVAL_REASON" ;;
+    esac
+    soleur_op_run_halt approval_invalid "$stage"
+    SOLEUR_OP_REFUSED=1
+    exit 75
+  fi
+
+  # 3. The second valid source: a real person typing yes at a real terminal, and
+  #    ONLY outside an agent harness. A pseudo-terminal an agent opens (script, a
+  #    python pty, expect) satisfies `-t 0`, so a bare TTY test would let the agent
+  #    type its own `yes`; inside a harness the terminal is not evidence of a person.
+  if [[ -t 0 && -t 1 ]] && ! soleur_op_in_agent_harness; then
+    printf '  If this fails: %s\n  Rollback: %s\n' "$impact" "$rollback"
+    soleur_op_ack_or_die "  Apply stage ${stage}? Type 'yes': "
+    SOLEUR_OP_APPROVAL="tty-ack"
+    soleur_op_ledger_approval "$stage" tty-ack "" "$computed" "$surface"
+    return 0
+  fi
+
+  # 4. No approval and no terminal: refuse. The agent re-issues the command as one
+  #    simple command so the approval hook can ask the person, or reports that this
+  #    surface cannot make production changes yet.
+  printf 'SOLEUR_BOOTSTRAP_APPROVAL_REQUIRED stage=%s approval_digest=%s surface=%s\n' "$stage" "$binding" "$surface"
+  printf 'This change needs the person to approve this exact command, and nothing approved it. In Claude Code with the Soleur plugin, issue the apply command as ONE simple command (no pipe, no semicolon, no &&, no substitution) and the person will be asked at the prompt. On a surface without that prompt I cannot make this change from here yet: nothing was changed, the plan is saved above, and it needs Claude Code with the Soleur plugin on the person'"'"'s computer (tracked in #9388). Tell the person exactly that; do not ask them to open a terminal.\n'
+  soleur_op_run_halt approval_required "$stage"
+  SOLEUR_OP_REFUSED=1
+  exit 75
+}
+
+# --- MUTATION ANCHOR: end of stage gate ---
+
+# ---------------------------------------------------------------------------
+# .env upsert — EXACT-KEY, and the mechanism is the trailing `=`
+# ---------------------------------------------------------------------------
+#
+# Revision R41: exact-key is the MAJORITY precedent, not a correction to one.
+# The four community setup scripts now write `.env` through `_wenv_write <env>
+# <remove-ERE> <KEY=VALUE>...` with an exact-key ERE (`^(KEY_A|KEY_B)=`); a PREFIX
+# ERE such as `^LINKEDIN_` is correct only for a fixed block of keys sharing that
+# prefix and also removes unrelated keys. Drop the `=` here and upserting
+# `X_API_KEY` silently removes `X_API_KEY_SECRET`. This library takes no lock
+# (tracked in #10204); the community helper's lock is a separate mechanism.
+#
+# No precedent fsyncs, and none handles a concurrent writer. This library
+# inherits that limitation: acceptable for a single-operator script on the
+# founder's own machine, and stated rather than assumed.
+
+# soleur_op_validate_key <KEY>
+#   ONE validator for BOTH .env writers. The key is interpolated into a BRE
+#   (`grep -v "^${key}="`), so anything outside the identifier alphabet is either
+#   a regex metacharacter (`.` matches every key; `[` is a grep exit 2) or a
+#   newline that splits the file. Refused, never escaped.
+soleur_op_validate_key() {
+  local key="$1"
+  if [[ ! "$key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+    printf 'SOLEUR_BOOTSTRAP_BAD_ARG key=%s\n' "${key//[$'\n\r']/ }"
+    return 1
+  fi
+}
+
+# soleur_op_env_key_count <file>
+#   `-a` on EVERY grep over the .env: without it grep's binary-file heuristic
+#   applies, and (measured) one cp1252 byte in a comment under a UTF-8 locale
+#   silently drops that line with rc 0, while a NUL byte anywhere makes `grep -v`
+#   print nothing at all — the mv then installs an .env holding only the new key.
+soleur_op_env_key_count() {
+  grep -a -c '^[A-Za-z_][A-Za-z0-9_]*=' "$1" 2>/dev/null || true
+}
+
+# soleur_op_env_filter_out <env-file> <KEY> <tmp>
+#   Every line but `KEY=...` into <tmp>. grep exit 1 (nothing left) is a normal
+#   outcome; exit 2 (unreadable file, a bad pattern) is NOT — the old `|| true`
+#   turned it into an empty <tmp> that the mv then installed as the .env,
+#   wiping every key and printing green. Shared by upsert and reset so the two
+#   cannot drift.
+soleur_op_env_filter_out() {
+  local env_file="$1" key="$2" tmp="$3" rc
+  grep -a -v "^${key}=" "$env_file" > "$tmp" && rc=0 || rc=$?
+  if (( rc > 1 )); then
+    printf 'SOLEUR_BOOTSTRAP_ENV_READ_FAILED path=%s\n' "$env_file"
+    rm -f "$tmp"
+    return 1
+  fi
+}
+
+# soleur_op_env_commit <env-file> <tmp> <keys-before> <min-keys-after>
+#   The mv is REFUSED when the file about to be installed holds fewer keys than
+#   the writer can legitimately produce: an upsert only adds or replaces (never
+#   shrinks), a reset shrinks by at most one. Anything else is the filter having
+#   lost lines — the failure both greps above were made loud for — caught on the
+#   artefact rather than on the mechanism.
+soleur_op_env_commit() {
+  local env_file="$1" tmp="$2" before="$3" min_after="$4" after
+  after="$(soleur_op_env_key_count "$tmp")"
+  if (( after < min_after )); then
+    printf 'SOLEUR_BOOTSTRAP_ENV_KEYCOUNT_DROP before=%s after=%s path=%s\n' "$before" "$after" "$env_file"
+    rm -f "$tmp"
+    return 1
+  fi
+  mv "$tmp" "$env_file"
+  chmod 600 "$env_file"
+}
+
+# soleur_op_has_control_char <value>
+#   Success when the value holds ANY control character: the C0 set (tab, ESC,
+#   the bell ...), DEL, and — the two the line-break check below already names —
+#   CR and LF. The class is evaluated under `local LC_ALL=C` so the verdict is
+#   BYTE-based and does not depend on the caller's locale (a bare `LC_ALL=C`
+#   assignment would leak into the sourcing caller; `local` cannot). Under C only
+#   the 0x00-0x1f and 0x7f bytes are control characters, so a UTF-8 credential is
+#   judged the same in every locale.
+#
+#   U+0085 (NEL), U+2028 and U+2029 are deliberately NOT refused, and that is
+#   stated rather than assumed: they are the Unicode "line" separators, but the
+#   sink here is a file read by `grep -a '^KEY='` and by the generated scripts'
+#   byte-oriented `read`/`source`, none of which treats them as a line end — only a
+#   consumer that Unicode-splits lines (a Python `splitlines`, a JS regexp `$`
+#   with `m`) would, and no consumer of this file does. Refusing them would also
+#   reject legitimate non-ASCII credentials. The ledger, a JSON sink that DOES care,
+#   strips them in its own writer.
+soleur_op_has_control_char() {
+  local LC_ALL=C
+  [[ "$1" == *[[:cntrl:]]* ]]
+}
+
+# soleur_op_env_upsert <env-file> <KEY> <value>
+#   ATOMIC: the new `KEY=value` line is appended to the temp file BEFORE the
+#   `mv`, so there is no instant at which the key is absent from the .env (the
+#   old shape had mv → chmod → separate append; a Ctrl-C in between lost the
+#   key). The .env is resolved through any symlink first, so a linked .env is
+#   rewritten in place rather than replaced by a regular file.
+soleur_op_env_upsert() {
+  local env_file="$1" key="$2" value="$3" tmp before_count
+  soleur_op_validate_key "$key" || return 1
+  if [[ "$value" == *$'\n'* || "$value" == *$'\r'* ]]; then
+    printf 'SOLEUR_BOOTSTRAP_BAD_ARG key=%s reason=value-contains-line-break\n' "$key"
+    return 1
+  fi
+  # Any OTHER control character (tab, ESC, DEL ...): a value written raw as `KEY=value`
+  # must stay one printable line. The marker names the KEY (already validated to the
+  # identifier alphabet) and never the value.
+  if soleur_op_has_control_char "$value"; then
+    printf 'SOLEUR_BOOTSTRAP_BAD_ARG key=%s reason=value-contains-control-char\n' "$key"
+    return 1
+  fi
+  env_file="$(readlink -f -- "$env_file" 2>/dev/null || printf '%s' "$env_file")"
+  [[ -f "$env_file" ]] || : > "$env_file"
+  before_count="$(soleur_op_env_key_count "$env_file")"
+  # `.tmp.` in the name so a `.env*` ignore pattern covers the sibling too; the
+  # template's not-ignored check probes this exact shape.
+  #
+  # A SOURCED library must not install an owning `trap ... EXIT`: it would REPLACE
+  # the consumer's — provision-hetzner.sh installs `cleanup`, the generated template
+  # installs `on_exit` — and `on_exit` is the terminal-outcome mechanism this whole
+  # feature rests on. Clobbering it to tidy a tempfile trades a bounded leak for the
+  # silent loss of the founder's stopped-at-stage report. So every path out of these
+  # two helpers removes its own temp explicitly; the temp is a full copy of the
+  # credentials file, which is why this is not merely tidiness.
+  # lint-trap-ownership: ok sourced library; an EXIT trap here would clobber the consumer's on_exit/cleanup, and every path below removes this temp explicitly
+  tmp="$(mktemp "${env_file}.tmp.XXXXXX")" || {
+    printf 'SOLEUR_BOOTSTRAP_BAD_ARG helper=env_upsert reason=mktemp-failed\n'
+    return 1
+  }
+  soleur_op_env_filter_out "$env_file" "$key" "$tmp" || { rm -f "$tmp"; return 1; }
+  printf '%s=%s\n' "$key" "$value" >> "$tmp" || { rm -f "$tmp"; return 1; }
+  # On success env_commit `mv`s the temp into place, so there is nothing to remove;
+  # on failure it leaves it, and this is the only frame that still holds the name.
+  soleur_op_env_commit "$env_file" "$tmp" "$before_count" "$before_count" || { rm -f "$tmp"; return 1; }
+  soleur_op_ledger_note env_upsert "$key" "keys_before=${before_count}"
+}
+
+# soleur_op_env_reset <env-file> <KEY>
+#   Revision R21a: a WRONG credential is otherwise permanent. The value is
+#   persisted before it can be validated, and the environment-first ladder means
+#   a re-run never re-prompts — it fails identically forever. This is the
+#   `--reset <KEY>` path every generated script exposes.
+soleur_op_env_reset() {
+  local env_file="$1" key="$2" tmp before_count
+  soleur_op_validate_key "$key" || return 1
+  env_file="$(readlink -f -- "$env_file" 2>/dev/null || printf '%s' "$env_file")"
+  [[ -f "$env_file" ]] || return 0
+  before_count="$(soleur_op_env_key_count "$env_file")"
+  # lint-trap-ownership: ok sourced library; same reason as env_upsert above — an EXIT trap here would clobber the consumer's, and every path below removes this temp explicitly
+  tmp="$(mktemp "${env_file}.tmp.XXXXXX")" || return 1
+  soleur_op_env_filter_out "$env_file" "$key" "$tmp" || { rm -f "$tmp"; return 1; }
+  soleur_op_env_commit "$env_file" "$tmp" "$before_count" "$(( before_count > 0 ? before_count - 1 : 0 ))" || { rm -f "$tmp"; return 1; }
+  soleur_op_ledger_note env_reset "$key" ""
+}
+
+# ---------------------------------------------------------------------------
+# GitHub writes — two helpers, deliberately NOT one
+# ---------------------------------------------------------------------------
+#
+# Argv is CORRECT for a login and WRONG for a credential. Merging the two "for
+# symmetry" is the mutation Guard 3 drives, because the merged helper would let
+# a secret take the argv path — visible in /proc/<pid>/cmdline to every process
+# on the machine, and in shell history when re-run by hand.
+
+# soleur_op_gh_secret_set <repo> <SECRET-NAME> <value>
+#   STDIN ONLY. The write's own output is redirected — a third-party CLI can dump
+#   unrelated secrets as a side effect of a write (the case
+#   .claude/hooks/doppler-secrets-delete-redirect.sh already blocks) — and the
+#   result is confirmed by a SEPARATE read.
+soleur_op_gh_secret_set() {
+  local repo="$1" sec_name="$2" value="$3" listed
+  printf '%s' "$value" | gh secret set "$sec_name" -R "$repo" >/dev/null 2>&1 || {
+    printf 'SOLEUR_BOOTSTRAP_SECRET_WRITE_FAILED name=%s repo=%s\n' "$sec_name" "$repo"
+    return 1
+  }
+  listed="$(gh secret list -R "$repo" 2>/dev/null || true)"
+  if ! grep -qE "^${sec_name}[[:space:]]" <<<"$listed"; then
+    # The write returned 0 and the read-back did not confirm it, so the secret
+    # MAY be live. The terminal-outcome trap must not tell the founder nothing
+    # changed — that is the one sentence that stops them revoking. Exported so
+    # a trap in the calling script can see it.
+    SOLEUR_OP_WRITE_MAY_HAVE_LANDED=1
+    export SOLEUR_OP_WRITE_MAY_HAVE_LANDED
+    printf 'SOLEUR_BOOTSTRAP_SECRET_VERIFY_FAILED name=%s repo=%s\n' "$sec_name" "$repo"
+    return 1
+  fi
+  soleur_op_ledger_note gh_secret "$sec_name" "repo=${repo}"
+}
+
+# soleur_op_gh_variable_set <repo> <VARIABLE-NAME> <value>
+#   Argv, because a repo VARIABLE is not confidential and masking it would make a
+#   delivery failure harder to diagnose (the reason
+#   provision-operator-digest-repo.sh writes OPERATOR_GH_LOGIN this way).
+#
+#   The refusal below is NOVEL — no in-repo precedent has it. It is what stops
+#   this helper from quietly becoming a secret path.
+#   Case-insensitive and CONTAINS-form (review P2-10): the old suffix-only,
+#   case-sensitive `^(.*_)?(TOKEN|KEY|SECRET|PASSWORD|PAT)$` admitted
+#   HCLOUD_TOKEN_PRD, hcloud_token, SECRET_KEY_BASE, API_KEYS, PRIVATE_KEY_PEM,
+#   CREDENTIALS, DB_PASSWD and SENTRY_DSN onto argv. `tr`, not `${var^^}`: the
+#   latter is bash 4.0+ and this file's floor is 3.2.
+soleur_op_gh_variable_set() {
+  local repo="$1" var_name="$2" value="$3" upper
+  upper="$(printf '%s' "$var_name" | tr '[:lower:]' '[:upper:]')"
+  if [[ "$upper" =~ (^|_)(TOKEN|KEY|SECRET|PASSWORD|PASSWD|PASSPHRASE|PAT|CREDENTIALS?|DSN|PRIVATE)(S?$|_) ]]; then
+    printf 'SOLEUR_BOOTSTRAP_UNSAFE_VARIABLE name=%s reason=secret-shaped-name-on-argv\n' "$var_name"
+    return 1
+  fi
+  gh variable set "$var_name" -R "$repo" --body "$value" >/dev/null 2>&1 || {
+    printf 'SOLEUR_BOOTSTRAP_VARIABLE_WRITE_FAILED name=%s repo=%s\n' "$var_name" "$repo"
+    return 1
+  }
+  soleur_op_ledger_note gh_variable "$var_name" "repo=${repo}"
+}
+
+# ---------------------------------------------------------------------------
+# Cross-platform URL opening — the one genuinely new primitive
+# ---------------------------------------------------------------------------
+#
+# ADDITIVE ONLY. The URL is printed FIRST and the opener's exit code is NEVER
+# branched on, so a headless box, a locked-down desktop or a broken handler
+# degrades to "here is the URL" rather than to a failed stage. In-repo prior art
+# (community/scripts/linkedin-setup.sh) is `xdg-open`/`open` only; the WSL arm is
+# new — `wslview`, `explorer.exe` and `$WSL_DISTRO_NAME` detection appear nowhere
+# else in this repository.
+#
+# Each opener runs in the BACKGROUND with stdin detached (review P2-11):
+# `xdg-open` on a box with no DISPLAY hands the URL to a terminal browser
+# (w3m, lynx) that seizes the tty and stdin, and the script looks hung one line
+# before its next prompt. The URL is already printed, so nothing is lost if the
+# opener never returns. It may carry a query string — a `?token=` would be
+# printed and passed on argv; do not put a secret in a URL you open this way.
+#
+# SOLEUR_OP_NO_OPEN=1 prints the URL and skips every opener — for a test
+# harness, a CI runner or a founder who does not want a tab stolen. It is the
+# only environment variable this primitive reads.
+soleur_op_open_url() {
+  local url="$1"
+  printf '  %s\n' "$url"
+  if [[ "${SOLEUR_OP_NO_OPEN:-}" == "1" ]]; then
+    return 0
+  fi
+  if [[ -n "${WSL_DISTRO_NAME:-}${WSL_INTEROP:-}" ]]; then
+    if command -v wslview >/dev/null 2>&1; then
+      (wslview "$url" || true) </dev/null >/dev/null 2>&1 &
+    elif command -v explorer.exe >/dev/null 2>&1; then
+      (explorer.exe "$url" || true) </dev/null >/dev/null 2>&1 &
+    fi
+  elif command -v xdg-open >/dev/null 2>&1; then
+    (xdg-open "$url" || true) </dev/null >/dev/null 2>&1 &
+  elif command -v open >/dev/null 2>&1; then
+    (open "$url" || true) </dev/null >/dev/null 2>&1 &
+  fi
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# Closing summary
+# ---------------------------------------------------------------------------
+
+soleur_op_summary_begin() {
+  printf '\n'
+  soleur_op_green "$1"
+  soleur_op_green "Operator follow-ups:"
+}
+
+soleur_op_summary_line() {
+  soleur_op_green "  $1"
+}