cs-image-system-base 0.1.1__py3-none-any.whl

cs_image_system/base/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0

cs_image_system/base/accounts_reconcile.py

@@ -0,0 +1,107 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Accounts on machines (stage 75 step 4): after an applying instance run,
+every launched, RUNNING machine whose owning group's builder renders an
+accounts script gets that script, over the runtime's session.
+
+Why after launch and not in the launch script: the launch script is the
+machine's recorded, immutable snapshot (its hash is a launch parameter), so
+a member list inside it would make every membership change a change to the
+machine. Run here, on every applying run, a membership change is neither a
+re-bake nor a replacement, and a standing machine is brought up to date in
+place.
+
+The script is the plugin's (the posix plugin's ``accounts_script``): run as
+root, idempotent, adopting what is equal and refusing what differs. Its own
+lines start ``posix accounts:``; they are the report, logged here. A
+failure is logged as an error and never stops the run -- the apply has
+happened, and the next applying run tries again -- the same rule as the
+provider aliases (stage 58). A machine that is off is the operator's
+decision (stage 57): it waits for a run that finds it running.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from . import power_state
+from .capabilities import group_builder_of
+from .lifecycles import Lifecycle
+
+if TYPE_CHECKING:
+    from .global_context import GlobalTypeContext
+
+log = logging.getLogger(__name__)
+
+REACHABLE_WAIT_SECONDS = 600     # a machine that booted this run: its session agent comes up later
+SCRIPT_TIMEOUT_SECONDS = 300
+HEREDOC = "CSIS_ACCOUNTS"
+
+
+def _group_of(ctx: "GlobalTypeContext", instance: Any) -> str:
+    image = ctx.images_map.get(str(instance.image))
+    return str(getattr(image, "group", None) or "") if image is not None else ""
+
+
+def as_root(script: str) -> str:
+    """The script, run as root whichever user the session lands in."""
+    return f"sudo bash -s <<'{HEREDOC}'\n{script.rstrip()}\n{HEREDOC}\n"
+
+
+def reconcile_accounts(ctx: "GlobalTypeContext", lifecycle: Lifecycle) -> None:
+    if lifecycle != Lifecycle.INSTANCE_IMAGE:
+        return
+    from .utils import apply_enabled
+    if not apply_enabled("instances"):
+        return
+    recorded = ctx.meta_state.launch_params()
+    for instance in ctx.instances:
+        name = instance.get_name()
+        if not apply_enabled("instances", str(instance.type_), [str(instance.runtime)]):
+            continue
+        if not (recorded.get(name) or {}).get("launched"):
+            continue
+        group = _group_of(ctx, instance)
+        gb = group_builder_of(ctx, group) if group else None
+        try:
+            script = gb.accounts_script(group) if gb is not None else None
+        except Exception as e:  # noqa: BLE001 - a provider that cannot be asked (OPA's gid): reported, never fatal
+            log.error(f"Instance {name}: the accounts script of group {group} could not be made: {e}")
+            continue
+        if not script:
+            continue
+        rtb = ctx.runtime_builders.get(str(instance.runtime)) if instance.runtime else None
+        if rtb is None:
+            continue
+        state = rtb.query_instance_power_state(name) if rtb.can_query_instance_power_state() else None
+        if state is not None and not power_state.is_on(state):
+            log.info(f"Instance {name}: {power_state.describe(state)}; its accounts wait for a run that finds it "
+                     "running (accounts are not worth starting a machine for)")
+            continue
+        if str((recorded.get(name) or {}).get("launched_run") or "") == str(ctx.run_id):
+            if not power_state.wait_until_reachable(rtb, name, timeout=REACHABLE_WAIT_SECONDS):
+                log.warning(f"Instance {name}: not reachable within {REACHABLE_WAIT_SECONDS}s of its launch; "
+                            "its accounts wait for the next applying run")
+                continue
+        try:
+            rc, out = rtb.run_session_command(name, as_root(script), timeout=SCRIPT_TIMEOUT_SECONDS)
+        except Exception as e:  # noqa: BLE001 - reported, never fatal to the run
+            log.error(f"Instance {name}: could not run the accounts script of group {group}: {e}")
+            continue
+        report = [ln.strip() for ln in out.splitlines() if ln.strip().startswith("posix accounts:")]
+        done = rc == 0 and "posix accounts: in place" in report
+        for line in report:
+            if line != "posix accounts: in place":
+                (log.warning if done else log.error)(f"Instance {name}: {line}")
+        if done:
+            log.info(f"Instance {name}: the accounts of group {group} are in place")
+        else:
+            log.error(f"Instance {name}: the accounts script of group {group} FAILED (exit {rc}); "
+                      f"{out.strip()[-300:] if not report else 'see above'}")
+
+
+def register(runner) -> None:
+    runner.register_after_apply(reconcile_accounts)

cs_image_system/base/alias_pool.py

@@ -0,0 +1,258 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Stage 59: a pool of names, each spent once.
+
+``meta-state/aliases.txt`` in the configuration is a pool of pre-approved,
+memorable names, hand-written in advance, one per line. When a NEW machine
+of a durable instance is about to be launched, the system takes the first
+line that is not commented out, records it as that machine's alias in its
+launch parameters, and comments the line out IN PLACE, on the same line,
+with what took it and when. A name is therefore spent exactly once,
+permanently, and the file is both the supply and the ledger.
+
+Optional by construction: no file, no aliases, no error. The division of
+bytes with the operator is the whole contract: a human only ever APPENDS
+lines; the system only ever comments out lines that are already there.
+
+The burn is the claim and it comes first: the line is rewritten before the
+machine exists (the launch parameters are recorded at generation, the
+apply follows), so a run that dies between the two costs one name and
+never lets two machines answer to one. A dry run draws nothing and says
+what it would take. A run whose instance roots may not apply draws
+nothing either: a name is burned only by the run that can launch.
+Ephemeral instances draw nothing -- a proof machine that comes and goes
+each cycle would drain the pool for nobody. Spent is spent: a decommission
+returns nothing.
+"""
+from __future__ import annotations
+
+import fcntl
+import logging
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .global_context import GlobalTypeContext
+
+log = logging.getLogger(__name__)
+
+POOL_FILE = "aliases.txt"
+_SPENT_RE = re.compile(r"^\s*#\s*(?P<name>[A-Za-z0-9][A-Za-z0-9-]*)\s+--\s+(?P<record>.+?)\s*$")
+
+# names drawn by THIS process, per run and instance: the launch parameters
+# are computed more than once per run, and a second computation must find
+# the name the first one burned, not burn another
+_DRAWN: dict[tuple[str, str], str] = {}
+
+
+@dataclass
+class PoolLine:
+    index: int
+    text: str
+    name: str | None        # a free name, or the name a spent line records; None for blanks/other comments
+    spent: bool
+
+
+def pool_path(config_root: Path | str) -> Path:
+    from .meta_state import META_STATE_DIRNAME
+    return Path(config_root) / META_STATE_DIRNAME / POOL_FILE
+
+
+def parse(text: str) -> list[PoolLine]:
+    out: list[PoolLine] = []
+    for i, raw in enumerate(text.splitlines()):
+        line = raw.strip()
+        if not line:
+            out.append(PoolLine(i, raw, None, False))
+        elif line.startswith("#"):
+            m = _SPENT_RE.match(raw)
+            out.append(PoolLine(i, raw, m.group("name") if m else None, True))
+        else:
+            out.append(PoolLine(i, raw, line, False))
+    return out
+
+
+def read_pool(path: Path) -> list[PoolLine]:
+    return parse(path.read_text()) if path.is_file() else []
+
+
+def free_names(path: Path) -> list[str]:
+    return [ln.name for ln in read_pool(path) if not ln.spent and ln.name]
+
+
+def spent_names(path: Path) -> dict[str, str]:
+    """``{name: record}`` for every line the system has commented out."""
+    out: dict[str, str] = {}
+    for ln in read_pool(path):
+        if ln.spent and ln.name:
+            m = _SPENT_RE.match(ln.text)
+            out[ln.name] = m.group("record") if m else ""
+    return out
+
+
+def peek(path: Path) -> str | None:
+    """The name the next draw would take, without taking it."""
+    free = free_names(path)
+    return free[0] if free else None
+
+
+def pool_problems(path: Path, *, reserved: set[str] | None = None) -> list[str]:
+    """Why a free line could not be used as it stands: not a legal hostname
+    label (RFC 1123, at most 63 characters -- it goes into OPA as an
+    AltNames entry beside the canonical name, stage 58), a repeat of another
+    free line, or a name the configuration already gives an instance."""
+    from .launch_params import hostname_problems
+    problems: list[str] = []
+    seen: set[str] = set()
+    for ln in read_pool(path):
+        if ln.spent or not ln.name:
+            continue
+        for why in hostname_problems(ln.name):
+            problems.append(f"line {ln.index + 1}: {ln.name!r} {why}")
+        if ln.name in seen:
+            problems.append(f"line {ln.index + 1}: {ln.name!r} repeats an earlier free line")
+        seen.add(ln.name)
+        if reserved and ln.name in reserved:
+            problems.append(f"line {ln.index + 1}: {ln.name!r} is a name the configuration already gives an instance")
+    return problems
+
+
+def burn_record(taken_by: str, run_id: str, when: datetime | None = None) -> str:
+    when = when or datetime.now(timezone.utc)
+    return f"{taken_by} {when.isoformat(timespec='seconds').replace('+00:00', 'Z')} run {run_id}"
+
+
+def draw(path: Path, *, taken_by: str, run_id: str, when: datetime | None = None) -> str | None:
+    """Take the first free name: comment its line out in place with the
+    record, under an exclusive lock, written temp-then-replace so a reader
+    never sees a half-written pool. None when the pool is absent or empty.
+    Two drawers in one checkout serialise on the lock; across checkouts the
+    push settles it (a rejected push on this file means someone else took
+    that name: re-read and draw again, never force)."""
+    if not path.is_file():
+        return None
+    lock = path.with_suffix(path.suffix + ".lock")
+    with open(lock, "w") as lk:
+        fcntl.flock(lk, fcntl.LOCK_EX)
+        try:
+            lines = read_pool(path)          # re-read under the lock
+            target = next((ln for ln in lines if not ln.spent and ln.name), None)
+            if target is None:
+                return None
+            record = burn_record(taken_by, run_id, when)
+            raw = path.read_text().splitlines(keepends=True)
+            ending = "\n" if raw[target.index].endswith("\n") else ""
+            raw[target.index] = f"# {target.name}  -- {record}{ending}"
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            tmp.write_text("".join(raw))
+            tmp.replace(path)
+            return target.name
+        finally:
+            fcntl.flock(lk, fcntl.LOCK_UN)
+
+
+def undraw(path: Path, *, name: str, run_id: str) -> bool:
+    """Give a name back: the line ``draw`` burned for ``name`` in run
+    ``run_id`` becomes a free line again, in place, under the same lock.
+    Only a record naming THAT run is restored (a name another run gave a
+    machine is spent for good). True when a line was restored."""
+    if not path.is_file():
+        return False
+    lock = path.with_suffix(path.suffix + ".lock")
+    with open(lock, "w") as lk:
+        fcntl.flock(lk, fcntl.LOCK_EX)
+        try:
+            raw = path.read_text().splitlines(keepends=True)
+            for ln in read_pool(path):
+                if ln.spent and ln.name == name and f" run {run_id}" in raw[ln.index]:
+                    ending = "\n" if raw[ln.index].endswith("\n") else ""
+                    raw[ln.index] = f"{name}{ending}"
+                    tmp = path.with_suffix(path.suffix + ".tmp")
+                    tmp.write_text("".join(raw))
+                    tmp.replace(path)
+                    return True
+            return False
+        finally:
+            fcntl.flock(lk, fcntl.LOCK_UN)
+
+
+def release_unlaunched(ctx: "GlobalTypeContext") -> list[str]:
+    """When a run ends: every name this run drew for a machine that did not
+    come to exist goes back to the pool (hygiene VIII item 5). A draw
+    happens at generation; the machine exists only after the apply, and a
+    run can abort between the two (``tofu init`` failing to download a
+    provider did it on 2026-10-01) with nothing recorded -- the pool file on
+    disk would still show the name spent for a machine that never was, and
+    the retry would burn the next one. A name is GIVEN when the instance's
+    launch record is marked launched by this run with that alias; every
+    other draw of this run is released. Returns the names released."""
+    ms = ctx.meta_state
+    path = pool_path(ctx.working_path)
+    released: list[str] = []
+    for key in [k for k in list(_DRAWN) if k[0] == str(ctx.run_id)]:
+        run_id, name = key
+        drawn = _DRAWN[key]
+        rec = ms.launch_params().get(name) or {}
+        given = bool(rec.get("launched")) and str(rec.get("launched_run") or "") == run_id \
+            and str(rec.get("alias") or "") == drawn
+        if given:
+            continue
+        if undraw(path, name=drawn, run_id=run_id):
+            released.append(drawn)
+            log.warning(f"Instance {name}: alias {drawn!r} drawn this run goes back to the pool -- the "
+                        f"machine it was for never came to exist (the run did not launch it)")
+        _DRAWN.pop(key, None)
+    return released
+
+
+def _new_machine(ctx: "GlobalTypeContext", instance: Any) -> bool:
+    """Whether the launch parameters being computed are for a machine that
+    does not exist yet: never launched, or a pending/follow replacement."""
+    from .launch_params import will_replace
+    recorded = ctx.meta_state.launch_params().get(instance.get_name()) or {}
+    return not recorded.get("launched") or will_replace(ctx, instance)
+
+
+def alias_for(ctx: "GlobalTypeContext", instance: Any, canonical: str) -> str | None:
+    """The alias this instance's launch parameters carry: the recorded one
+    for a machine that stands, a fresh draw for a new machine of a durable
+    instance when THIS run can launch it, nothing otherwise."""
+    name = instance.get_name()
+    ms = ctx.meta_state
+    recorded = ms.launch_params().get(name) or {}
+    if not _new_machine(ctx, instance):
+        return str(recorded["alias"]) if recorded.get("alias") else None
+    if getattr(instance, "ephemeral", False):
+        return None
+    path = pool_path(ctx.working_path)
+    if not path.is_file():
+        return None
+    key = (str(ctx.run_id), name)
+    if key in _DRAWN:
+        return _DRAWN[key]
+    if str(recorded.get("run") or "") == str(ctx.run_id) and recorded.get("alias"):
+        return str(recorded["alias"])              # drawn earlier in this run, already recorded
+    from .utils import apply_enabled
+    can_launch = (not ctx.dry_run) and apply_enabled("instances", str(instance.type_), [str(instance.runtime)])
+    if not can_launch:
+        would = peek(path)
+        if would:
+            log.info(f"Instance {name}: would take alias {would!r} from the pool for {canonical} "
+                     f"({'dry run' if ctx.dry_run else 'this run cannot launch it'}; nothing drawn)")
+        else:
+            log.warning(f"Instance {name}: the alias pool is EMPTY; a launch proceeds without an alias")
+        return None
+    drawn = draw(path, taken_by=f"instance {name} as {canonical}", run_id=str(ctx.run_id))
+    if drawn is None:
+        log.warning(f"Instance {name}: the alias pool is EMPTY; launching {canonical} without an alias "
+                    f"(append names to {path.name} to refill it)")
+        return None
+    _DRAWN[key] = drawn
+    log.info(f"Instance {name}: took alias {drawn!r} from the pool for {canonical} (spent; the line is "
+             f"commented out in {path.name})")
+    return drawn

cs_image_system/base/ansible_launch.py

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Prototype: launch parameters as an ansible inventory + playbook
+(EXPLORE "Possible Other Infra-as-Code tools", step 2 -- investigation).
+
+The instance root feeds :func:`launch_params.user_data_template` through
+``templatefile`` so cloud-init runs the mounts / group subtree / enrollment
+at first boot. The same *structural* launch parameters can be rendered as
+an ansible playbook for targets that have no user-data (metal, containers,
+an already-running host): identical decisions, a different executor.
+
+Runtime values still arrive by reference, as extra-vars rather than
+terraform template variables: ``group_gid``, ``efs`` (storage ->
+{file_system_id, access_point_id}) and ``sft_enrollment_token``. Nothing
+here reads meta-state or the cloud; it is a pure rendering of what
+``compute_launch_params`` already produced.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+from .launch_enrollment import enrollment_kind_for
+
+EXTRA_VARS = ("group_gid", "efs", "sft_enrollment_token")
+
+
+def launch_inventory(params_by_instance: dict[str, dict[str, Any]]) -> str:
+    """One host per instance, grouped by owning group and identity type."""
+    hosts = {name: {"csis_image": p.get("image"), "csis_build": p.get("build")}
+             for name, p in sorted(params_by_instance.items())}
+    children: dict[str, dict[str, Any]] = {}
+    for name, p in sorted(params_by_instance.items()):
+        for key in (p.get("group"), p.get("identity_type")):
+            if key:
+                children.setdefault(f"csis_{key}", {"hosts": {}})["hosts"][name] = {}
+    inv: dict[str, Any] = {"all": {"hosts": hosts, "children": children}}
+    return yaml.safe_dump(inv, sort_keys=False)
+
+
+def launch_playbook(params: dict[str, Any], inventory_name: str | None = None) -> str:
+    """The playbook equivalent of ``user_data_template(params)``.
+    ``inventory_name`` is the instance's declared name -- the key
+    ``launch_inventory`` uses -- and is what the play TARGETS;
+    ``params["hostname"]`` is the canonical name the machine is GIVEN (since
+    stage 55 step 4 the two differ: ``test`` versus ``test-001``). Without
+    it the play targets the hostname, as it did when they coincided."""
+    host = params["hostname"]
+    target = inventory_name or host
+    group = params.get("group")
+    tasks: list[dict[str, Any]] = [
+        {"name": f"hostname {host}", "ansible.builtin.hostname": {"name": host}},
+    ]
+    for m in params.get("mounts", []):
+        mp, name, stype = m["mount_point"], m["storage"], m["type"]
+        if stype == "s3":
+            tasks.append({"name": f"storage {name} (s3): object access via the AWS CLI, no mount",
+                          "ansible.builtin.debug": {"msg": f"s3 storage {name} is not mounted"}})
+            continue
+        tasks.append({"name": f"mount point {mp} for storage {name} ({stype})",
+                      "ansible.builtin.file": {"path": mp, "state": "directory"}})
+        if stype == "ebs":
+            dev = m["device"]
+            tasks.append({"name": f"filesystem on {dev} ({name})",
+                          "community.general.filesystem": {"fstype": "xfs", "dev": dev}})
+            tasks.append({"name": f"mount {dev} at {mp}",
+                          "ansible.posix.mount": {"path": mp, "src": dev, "fstype": "xfs",
+                                                  "opts": "defaults,nofail", "state": "mounted"}})
+            if group:
+                tasks.append({"name": f"private subtree {mp}/{group} (gid by reference)",
+                              "ansible.builtin.file": {"path": f"{mp}/{group}", "state": "directory",
+                                                       "group": "{{ group_gid }}",
+                                                       "mode": str(m["share_mode"])}})
+        elif stype == "efs":
+            tasks.append({"name": f"mount EFS {name} at {mp}",
+                          "ansible.posix.mount": {
+                              "path": mp, "fstype": "efs",
+                              "src": "{{ efs['" + name + "'].file_system_id }}:/",
+                              "opts": "_netdev,tls,accesspoint={{ efs['" + name + "'].access_point_id }},nofail",
+                              "state": "mounted"}})
+    # stage 75 step 2: the identity plugin that issued the enrollment renders its tasks
+    kind = enrollment_kind_for(params)
+    if kind is not None:
+        tasks += kind.ansible_tasks(params)
+    play = {
+        "name": f"cs-image-system launch parameters for {host} (N26; immutable after launch)",
+        "hosts": target,
+        "become": True,
+        "vars": {"csis_image": params.get("image"), "csis_build": params.get("build"),
+                 "csis_group": group, "csis_session": params.get("session")},
+        "tasks": tasks,
+    }
+    return yaml.safe_dump([play], sort_keys=False, width=120)

cs_image_system/base/bake_steps.py

@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""How a bake's shell steps run, and what a bake waits for first (stage 86).
+
+A build machine is not the bake's alone. Its own first-boot script may still
+be installing something, and the account's fleet management may act on every
+new machine the moment its agent registers: found walking the daily driver
+(stage 65, finding F29), where Systems Manager's associations -- agent
+updates, a patch scan, inventory, all targeting every instance -- fired on
+each build machine within forty seconds of launch and held the package
+database while packer provisioned. ``rpm`` waits for a held transaction lock
+only when stdin is a terminal; in a bake it fails at once ("can't create
+transaction lock"), and the bake with it.
+
+Two things answer that, and both are emitted, reviewable shell:
+
+* the FIRST provisioner of every build block settles the machine -- the
+  first-boot script has ended, the runtime's fleet management is quiet
+  (``RuntimeBuilderBase.bake_settle_commands``) -- and writes a small step
+  runner to ``/run``, a tmpfs, so it is never part of the image;
+* every shell provisioner the system emits runs its script through that
+  runner (``EXECUTE_COMMAND``): a step that FAILS and whose output says the
+  package database was held is run again after a wait, a bounded number of
+  times. Any other failure is the step's own and fails at once, as before.
+
+A step the runner cannot be found for (a machine that rebooted mid-bake lost
+``/run``) runs as it always did.
+"""
+from __future__ import annotations
+
+#: Where the step runner is written on the build machine: a tmpfs, so no
+#: image ever carries it. Read with ``sh`` (Debian mounts /run noexec).
+STEP_RUNNER = "/run/csis-step"
+
+#: How many times a step is run in all, and the wait between two runs.
+STEP_TRIES = 10
+STEP_WAIT_SECONDS = 30
+
+#: What a package tool says when someone else holds the package database:
+#: rpm and dnf ("can't create transaction lock"), apt and dpkg.
+BUSY_PATTERN = ("transaction lock|Could not get lock|dpkg frontend lock|"
+                "Unable to lock the administration directory")
+
+#: How long the settle waits for the machine's first-boot script.
+BOOT_WAIT_SECONDS = 300
+
+#: The ``execute_command`` of every shell provisioner the system emits:
+#: packer's own default (``chmod +x {{ .Path }}; {{ .Vars }} {{ .Path }}``)
+#: with the script handed to the step runner when the machine has one.
+EXECUTE_COMMAND = ("chmod +x {{ .Path }}; if [ -r " + STEP_RUNNER + " ]; then {{ .Vars }} sh " + STEP_RUNNER
+                   + " {{ .Path }}; else {{ .Vars }} {{ .Path }}; fi")
+
+
+def execute_command_line(indent: str = "    ") -> str:
+    """The HCL attribute line a shell provisioner block carries."""
+    return f'{indent}execute_command = "{EXECUTE_COMMAND}"'
+
+
+def step_runner_lines() -> list[str]:
+    """The step runner, a line each. POSIX sh; it streams the step's output as
+    it comes and keeps a copy to read when the step fails."""
+    return [
+        "#!/bin/sh",
+        "# cs-image-system: runs ONE step of a bake. A step that fails while the package",
+        "# database is held by another process is run again after a wait; any other",
+        "# failure is the step's own and is returned at once.",
+        f'tries="${{CSIS_STEP_TRIES:-{STEP_TRIES}}}"',
+        f'pause="${{CSIS_STEP_WAIT:-{STEP_WAIT_SECONDS}}}"',
+        'out="$(mktemp)" || exit 1',
+        "trap 'rm -f \"$out\" \"$out.rc\"' EXIT",
+        "n=1",
+        "while :; do",
+        '  { "$@" 2>&1; echo "$?" > "$out.rc"; } | tee "$out"',
+        '  rc="$(cat "$out.rc")"',
+        '  [ "$rc" = 0 ] && exit 0',
+        '  [ "$n" -ge "$tries" ] && exit "$rc"',
+        f"  grep -Eq '{BUSY_PATTERN}' \"$out\" || exit \"$rc\"",
+        '  echo "csis-step: the package database was held by another process '
+        '(attempt $n of $tries); this step runs again in $pause seconds"',
+        "  n=$((n + 1))",
+        '  sleep "$pause"',
+        "done",
+    ]
+
+
+def settle_commands(runtime_commands: list[str] | None = None) -> list[str]:
+    """The inline commands of a bake's first provisioner: wait for the
+    machine's own first-boot script, then for whatever the runtime says acts
+    on a new machine, then write the step runner."""
+    cmds = [
+        "# before any package work: the machine's own first-boot script has ended (bounded)",
+        f"if command -v cloud-init >/dev/null 2>&1; then timeout {BOOT_WAIT_SECONDS} cloud-init status --wait "
+        ">/dev/null 2>&1 || true; fi",
+    ]
+    cmds += list(runtime_commands or [])
+    cmds += ["# the step runner: a step that fails on a held package database is run again (never in the image: "
+             "/run is a tmpfs)",
+             f"sudo tee {STEP_RUNNER} >/dev/null <<'CSIS_STEP'"]
+    cmds += step_runner_lines()
+    cmds += ["CSIS_STEP", f"sudo chmod 0755 {STEP_RUNNER}"]
+    return cmds