dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/drivers/state_diff.py

@@ -0,0 +1,274 @@
+"""dos.drivers.state_diff — the canonical-state-diff read-back witness (docs/181).
+
+The second concept lifted from the 2026 result-state-witness SOTA (docs/180):
+**Agent-Diff** (arXiv 2602.11224) defines task success as "whether the expected
+change in environment STATE was achieved", computed as a canonical state diff
+(inserted / deleted / updated entities) over containerized replicas — explicitly
+rejecting "fuzzy trace or parameter matching". This driver is DOS's domain-free,
+floor-disciplined version: it snapshots a state surface BEFORE and AFTER the agent's
+turn, computes the delta, and witnesses whether a claimed effect-key is PRESENT in
+that delta — feeding `effect_witness.witness_effect` a non-forgeable read-back.
+
+Why this is a NON-FORGEABLE witness (the VAGEN "different surface" principle)
+=============================================================================
+
+The third SOTA concept (VAGEN, arXiv 2602.00575) is that the verifier must take its
+OWN read actions — read the world from a surface the agent did not author. This
+driver reads the **state surface itself** (a snapshot of the live store), NOT the
+agent's narration of what it wrote and NOT the agent's own tool-call response bytes.
+The snapshot is authored by the store, not the agent: the agent cannot forge "row 42
+now exists in the orders table" without the row actually existing, because the
+snapshot is a fresh read of the store. So this source is tagged `OS_RECORDED` when
+the snapshot comes from a local store the kernel reads directly (a sqlite file, a
+JSON state dump the OS wrote), and a host that reads a remote third-party store
+(a SaaS API, a cloud DB) would register a `THIRD_PARTY`-tagged sibling.
+
+The honest boundary: a snapshot the AGENT produced is forgeable
+===============================================================
+
+If the "before"/"after" snapshots are bytes the agent itself emitted (it ran a query
+and pasted the result), then actor==witness and the read-back is `AGENT_AUTHORED` —
+the forgeable floor, structurally incapable of CONFIRMED under
+`effect_witness`/`believe_under_floor`. This driver is only a sound witness when the
+KERNEL reads the snapshot (it opens the sqlite file / re-fetches the dump), which is
+why the snapshot reader is a parameter (`read_state`) the HOST supplies as an
+independent reader, and why the default file reader is the safe, kernel-authored path.
+
+The delta grammar (canonical, domain-free)
+==========================================
+
+A "state" is a mapping of `entity_key -> entity_value` (rows by id, files by path,
+records by key). The canonical diff over two snapshots is:
+
+  * inserted = keys in AFTER not in BEFORE
+  * deleted  = keys in BEFORE not in AFTER
+  * updated  = keys in both whose value differs
+
+A claimed effect-key is PRESENT iff it appears in inserted ∪ updated (the agent
+claimed it *made* a change to that entity). ABSENT iff it does not. This is the
+domain-free "claim ⊆ witnessed-delta" presence check `effect_witness` wants — not a
+gold-state correctness check (which a live runtime cannot have; docs/181 §"why
+presence not correctness").
+
+Shape & layering
+================
+
+A driver — it has the I/O surface the kernel forbids (reading a state store). It
+implements the `evidence.EvidenceSource` Protocol so it drops straight into
+`gather_evidence` and the belief fold, and a thin `witness_effect_via_state_diff`
+convenience that snapshots → diffs → joins the claim. It imports the kernel; the
+kernel never imports it (the `drivers/__init__` rule). Advisory: it reports a
+read-back; it never mutates state or refuses a lease.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from typing import Mapping
+
+# Imports the kernel — never the other way round (the driver rule).
+from dos.evidence import Accountability, EvidenceFacts
+from dos.effect_witness import EffectClaim, EffectWitnessVerdict, witness_effect
+
+
+# A state snapshot: entity-key -> an opaque, comparable value (str/number/JSON-able).
+State = Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class StateDelta:
+    """The canonical diff between two snapshots — inserted / deleted / updated keys."""
+
+    inserted: frozenset[str]
+    deleted: frozenset[str]
+    updated: frozenset[str]
+
+    @property
+    def changed(self) -> frozenset[str]:
+        """Keys the agent could have CLAIMED it made: inserted ∪ updated. A delete is
+        not a 'made this entity' claim in the presence sense, so it is reported but not
+        counted as 'present' (a host that wants delete-claims checks `deleted`)."""
+        return self.inserted | self.updated
+
+    def to_dict(self) -> dict:
+        return {
+            "inserted": sorted(self.inserted),
+            "deleted": sorted(self.deleted),
+            "updated": sorted(self.updated),
+        }
+
+
+def diff_state(before: State, after: State) -> StateDelta:
+    """Canonical, domain-free diff over two snapshots. PURE — no I/O.
+
+    Values are compared by equality; a host whose values are unstable (timestamps,
+    auto-ids) should normalize them in its `read_state` reader before snapshotting, so
+    the diff reflects semantic change, not churn.
+    """
+    bkeys = set(before.keys())
+    akeys = set(after.keys())
+    inserted = akeys - bkeys
+    deleted = bkeys - akeys
+    updated = {k for k in (akeys & bkeys) if before[k] != after[k]}
+    return StateDelta(
+        inserted=frozenset(inserted),
+        deleted=frozenset(deleted),
+        updated=frozenset(updated),
+    )
+
+
+class StateDiffEvidenceSource:
+    """An `evidence.EvidenceSource`: witness whether a claimed effect-key is in a delta.
+
+    Constructed with a precomputed `StateDelta` (snapshot/diff happened at the
+    boundary) and an `accountability` rung (`OS_RECORDED` when the KERNEL read the
+    snapshots; a remote store driver passes `THIRD_PARTY`; never `AGENT_AUTHORED` for a
+    sound witness). `gather(subject, config)` reads `subject` as the effect-key and
+    answers PRESENT (ATTESTED) / ABSENT (REFUTED) against the delta — never NO_SIGNAL,
+    because a computed delta IS a reached read (the absence of a key is a positive
+    'not there', not 'could not tell'). The fail-safe degrade lives one level up in
+    the snapshot reader (`witness_effect_via_state_diff`): if the snapshots could not
+    be read, no source is built and the verdict is UNWITNESSED.
+    """
+
+    name = "state_diff"
+
+    def __init__(self, delta: StateDelta, *, accountability: Accountability = Accountability.OS_RECORDED) -> None:
+        if accountability.is_agent_authored:
+            # Guard the soundness contract loudly: a state-diff witness over
+            # agent-authored snapshots is NOT a witness (actor==witness). A host that
+            # truly has only agent-authored snapshots should not use this source.
+            raise ValueError(
+                "state_diff witness requires a non-forgeable snapshot rung "
+                "(OS_RECORDED/THIRD_PARTY); an agent-authored snapshot is not a witness"
+            )
+        self._delta = delta
+        self.accountability = accountability
+
+    def gather(self, subject: str, config: object) -> EvidenceFacts:
+        key = (subject or "").strip()
+        if not key:
+            return EvidenceFacts.no_signal(
+                self.name, self.accountability, subject,
+                detail="no effect-key given — nothing to look for in the delta",
+            )
+        if key in self._delta.changed:
+            where = "inserted" if key in self._delta.inserted else "updated"
+            return EvidenceFacts.attest(
+                self.name, self.accountability, key,
+                detail=f"effect-key {key!r} is in the state delta ({where})",
+            )
+        return EvidenceFacts.refute(
+            self.name, self.accountability, key,
+            detail=(
+                f"effect-key {key!r} is NOT in the state delta "
+                f"(inserted={len(self._delta.inserted)} updated={len(self._delta.updated)}) "
+                f"— the claimed change is absent from the world"
+            ),
+        )
+
+
+def witness_effect_via_state_diff(
+    claim: EffectClaim,
+    before: State,
+    after: State,
+    *,
+    accountability: Accountability = Accountability.OS_RECORDED,
+) -> EffectWitnessVerdict:
+    """Snapshot-diff → join: the one-call convenience for a host with two snapshots.
+
+    Computes the canonical delta, builds the state-diff witness over it, and joins the
+    claim through `effect_witness.witness_effect`. The snapshots MUST have been read by
+    the kernel/host (a non-forgeable reader), not pasted by the agent — that is the
+    `accountability` rung's contract. Returns the four-valued verdict.
+    """
+    delta = diff_state(before, after)
+    source = StateDiffEvidenceSource(delta, accountability=accountability)
+    facts = source.gather(claim.probe_subject(), None)
+    return witness_effect(claim, [facts])
+
+
+# ---------------------------------------------------------------------------
+# A safe, kernel-authored snapshot reader: a JSON state-dump file.
+# `read_state_json(path)` reads a {key: value} JSON object the STORE wrote. Because
+# the kernel opens the file (the agent did not hand us the bytes), the resulting
+# snapshot is OS_RECORDED. A host with a sqlite store / a SaaS API writes its own
+# reader and tags the rung accordingly.
+# ---------------------------------------------------------------------------
+
+
+def read_state_json(path: str) -> State:
+    """Read a `{entity_key: value}` JSON object as a state snapshot. Raises on a bad
+    read (the caller decides the fail-safe — a missing snapshot → UNWITNESSED, never a
+    fabricated empty delta that would falsely REFUTE every claim)."""
+    with open(path, "r", encoding="utf-8") as f:
+        obj = json.load(f)
+    if not isinstance(obj, dict):
+        raise ValueError(f"state snapshot at {path!r} is a {type(obj).__name__}, not an object")
+    return obj
+
+
+# ---------------------------------------------------------------------------
+# CLI — `python -m dos.drivers.state_diff KEY --before B.json --after A.json`
+# witnesses whether the claimed effect-key is present in the file-snapshot delta.
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="dos.drivers.state_diff",
+        description=__doc__.splitlines()[0],
+    )
+    ap.add_argument("effect_key", help="the claimed effect-key to look for in the state delta")
+    ap.add_argument("--before", required=True, help="path to the BEFORE state snapshot (JSON object the STORE wrote)")
+    ap.add_argument("--after", required=True, help="path to the AFTER state snapshot")
+    ap.add_argument("--narrated", default="", help="the agent's original claim phrasing (for the operator surface)")
+    ap.add_argument("--third-party", action="store_true",
+                    help="tag the snapshot rung THIRD_PARTY (a remote store) instead of OS_RECORDED")
+    ap.add_argument("--json", action="store_true", help="machine-readable verdict")
+    args = ap.parse_args(argv)
+
+    rung = Accountability.THIRD_PARTY if args.third_party else Accountability.OS_RECORDED
+    claim = EffectClaim(key=args.effect_key, narrated=args.narrated)
+
+    # Fail-safe at the boundary: an unreadable snapshot → UNWITNESSED (no claim of
+    # absence), never a fabricated empty delta.
+    try:
+        before = read_state_json(args.before)
+        after = read_state_json(args.after)
+    except (OSError, ValueError, json.JSONDecodeError) as e:
+        from dos.effect_witness import witness_effect  # local import keeps module top clean
+        v = witness_effect(claim, [])  # no read-backs → UNWITNESSED
+        v_dict = v.to_dict()
+        v_dict["reason"] = f"UNWITNESSED — could not read a state snapshot ({e}); cannot tell"
+        if args.json:
+            print(json.dumps(v_dict, indent=2))
+        else:
+            print(f"VERDICT   UNWITNESSED\nWHY       could not read a snapshot: {e}")
+        return 3
+
+    delta = diff_state(before, after)
+    v = witness_effect_via_state_diff(claim, before, after, accountability=rung)
+
+    if args.json:
+        out = v.to_dict()
+        out["delta"] = delta.to_dict()
+        print(json.dumps(out, indent=2))
+    else:
+        print(f"EFFECT    {args.effect_key}")
+        print(f"DELTA     +{len(delta.inserted)} ~{len(delta.updated)} -{len(delta.deleted)}")
+        print(f"VERDICT   {v.verdict.value}   (believe={v.believe} refuted={v.refuted})")
+        print(f"WITNESS   {v.witness or '(none)'} ({v.accountability.value if v.accountability else '-'})")
+        print(f"WHY       {v.reason}")
+
+    if v.is_refuted:
+        return 1
+    if v.is_confirmed:
+        return 0
+    return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dos/drivers/supervisor.py

@@ -0,0 +1,347 @@
+"""dos.drivers.supervisor — the long-lived watchdog that ENACTS `supervise()`.
+
+The supervisor verdict (`dos.supervise`, docs/99) is a PURE per-tick plan:
+SPAWN these free lanes, REAP these STALLED leases, FLAG these spinners. The
+kernel emits the plan and stops there — `dos loop` prints it, it never launches a
+worker or writes the journal. This driver is the layer that *acts on* the plan:
+each tick it gathers the evidence (reusing the kernel boundary helper
+`cli._supervise_evidence`), calls the pure verdict, then turns the plan into
+effects — `subprocess.Popen` a worker dispatch-loop per SPAWN, append a SCAVENGE
+to the lane journal per REAP.
+
+It is a **driver** (layer 4): the one place where subprocess + journal-write +
+policy live. The kernel never imports it (the `import dos.drivers` litmus); it
+`import dos` like any consumer. It is the population-axis analogue of the loop
+*screenplay* a host builds over `liveness` — the kernel ships the verdict, the
+driver puts it on a cadence and gives it hands.
+
+## Why a driver may write the journal (and must serialize)
+
+`lane_journal.append` is deliberately lock-free: "journal order must equal
+registry-mutation order and only the caller knows the surrounding critical
+section." Today the kernel ships no in-tree writer; this driver is the first.
+So it brings its own serialization — a single `O_CREAT|O_EXCL` lock file next to
+the journal, held only across the append. The supervisor is single-writer-per-host
+by design, so the lock serializes the supervisor's OWN appends; it does NOT (and
+need not) coordinate with a worker's `lane_journal.append` ACQUIRE, which stays
+lock-free — `seq` is cosmetic for `replay` (it folds by append order and ignores
+`seq`), so an ACQUIRE/SCAVENGE seq-collision is benign. The lock's real job is
+**crash-safety**: a supervisor killed mid-append (SIGKILL / OOM / power-loss on
+this multi-day watchdog) must not wedge every future reap. So, like
+`archive_lock`, it STEALS a lock older than a short TTL, and `run()` clears any
+pre-existing lock once at startup (safe: single-writer-per-host).
+
+## The double-spawn race belt (the driver half of the kernel guard)
+
+Between the tick that `Popen`s a worker and the tick where that worker's ACQUIRE
+lands in the journal, the lane reads FREE — so a naive re-tick would launch a
+second worker. The driver keeps a `launched: {lane: launched_at_ms}` set and, on
+the next tick, marks every lane launched within `cooldown_ms` as `pending=True`
+in the evidence. The pure verdict then counts it alive-or-coming and does not
+re-emit a SPAWN for it (the kernel's `pending` guard). The belt bounds the race
+to at most one extra worker per lane per cooldown window — never an unbounded
+stampede. A lane drops out of `launched` once its lease is visible (its ACQUIRE
+journalled), so a worker that came up healthy stops being treated as pending.
+
+## Structure (testable without real I/O)
+
+`plan_tick(cfg, *, target, now_ms, launched, cooldown_ms)` is near-pure: it
+derives `pending` from `launched`, gathers evidence, calls `supervise()`, and
+returns the verdict — NO effects. `tick(...)` calls `plan_tick` and then performs
+the effects (Popen + scavenge), returning `(verdict, actions)`. `run(...)` loops
+`tick` + sleep. Tests drive `plan_tick`/`tick` with `subprocess.Popen` and
+`lane_journal.append` monkeypatched, so no real `claude` and no real git run.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from dos import config as _config
+from dos import lane_journal, run_id, supervise
+
+# The worker launch argv the SPAWN plan turns into. Generic + host-free: it shells
+# the `/dos-dispatch-loop` slash-skill, never a host's fat script (the emitted
+# command names no host — the same rule the `dos loop` CLI emission keeps).
+WORKER_PROCESS_ID = "PROC-dos-dispatch-loop"
+DEFAULT_INTERVAL_S = 300.0       # the watchdog wakes rarely — init's reaper cadence
+DEFAULT_COOLDOWN_MS = 120_000    # ~2 min: covers a worker's cold-start + first ACQUIRE
+
+
+def _worker_argv(lane: str) -> list[str]:
+    """The argv for one worker dispatch-loop on `lane` (generic, host-free)."""
+    return ["claude", "-p", f"/dos-dispatch-loop --lane {lane}"]
+
+
+# --------------------------------------------------------------------------
+# Journal write-lock — a dedicated O_CREAT|O_EXCL lock file next to the journal,
+# held only across an append. The supervisor is single-writer-per-host by design,
+# so this lock serializes the supervisor's OWN appends (it does NOT, and need not,
+# coordinate with a worker's `lane_journal.append` ACQUIRE — that path is lock-free
+# and `seq` is cosmetic for `replay`, which folds by append order and ignores it).
+# Its real job is crash-safety: it MUST recover from a stale lock a crashed
+# supervisor (SIGKILL / OOM / power-loss) left behind, or every future reap wedges
+# forever. So, like `archive_lock`, it STEALS a lock older than a short TTL — the
+# append is sub-second, so a few seconds is ample — and `run()` clears any
+# pre-existing lock once at startup (safe: single-writer-per-host).
+# --------------------------------------------------------------------------
+_LOCK_TTL_S = 10.0  # an append is sub-second; a lock older than this is a crash orphan
+
+
+def _journal_lock_path(cfg) -> Path:
+    return Path(str(cfg.paths.lane_journal) + ".supervisor.lock")
+
+
+def _lock_age_s(lp: Path) -> "float | None":
+    """Age of the lock file in seconds by its mtime; None if it cannot be read."""
+    try:
+        return max(0.0, time.time() - lp.stat().st_mtime)
+    except OSError:
+        return None
+
+
+def _clear_stale_lock(cfg) -> None:
+    """Unlink the journal write-lock if it exists (startup cleanup / steal helper).
+
+    Safe because the supervisor is single-writer-per-host: at `run()` startup there
+    is no other legitimate holder, so any lock present is a crash orphan from a
+    prior run. Also used to STEAL a lock older than the TTL mid-run.
+    """
+    lp = _journal_lock_path(cfg)
+    try:
+        lp.unlink()
+    except OSError:
+        pass
+
+
+def _scavenge_under_lock(cfg, lease: dict, *, reason: str) -> bool:
+    """Append a SCAVENGE for `lease` to the lane journal under a write-lock.
+
+    Returns True on a clean append, False if a FRESH lock was held (the supervisor
+    is mid-append elsewhere — skip this tick, the next one retries) or the append
+    failed. A failed reap is never fatal: the lane stays STALLED and the next tick
+    re-emits the REAP, the idempotent-reconcile property.
+
+    Crash-safety: a lock older than `_LOCK_TTL_S` is a crash orphan (a real append
+    is sub-second), so it is STOLEN — unlinked and re-created — rather than
+    deferred forever. Without this, a supervisor killed mid-append would wedge
+    every future reap for the life of the host.
+    """
+    lp = _journal_lock_path(cfg)
+    lp.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        fd = os.open(str(lp), os.O_WRONLY | os.O_CREAT | os.O_EXCL)
+    except FileExistsError:
+        # A lock is present. If it is older than the TTL it is a crash orphan —
+        # steal it and retry once. A fresh lock means a real concurrent append
+        # (only possible if someone ran two supervisors); defer to the next tick.
+        age = _lock_age_s(lp)
+        if age is None or age <= _LOCK_TTL_S:
+            return False
+        _clear_stale_lock(cfg)
+        try:
+            fd = os.open(str(lp), os.O_WRONLY | os.O_CREAT | os.O_EXCL)
+        except OSError:
+            return False  # lost the steal race — retry next tick
+    except OSError:
+        return False
+    try:
+        os.write(fd, f"supervisor pid={os.getpid()}\n".encode("utf-8"))
+        os.close(fd)
+        entry = lane_journal.scavenge_entry(lease, reason=reason,
+                                            prev_holder=lease.get("host_id"))
+        lane_journal.append(entry, path=cfg.paths.lane_journal)
+        return True
+    except Exception:  # noqa: BLE001 — a failed reap is non-fatal; retry next tick
+        return False
+    finally:
+        try:
+            lp.unlink()
+        except OSError:
+            pass
+
+
+# --------------------------------------------------------------------------
+# The tick — plan (near-pure) then enact (effects).
+# --------------------------------------------------------------------------
+@dataclass
+class TickActions:
+    """What a tick actually did — the audit record a test asserts on."""
+
+    spawned: list[str] = field(default_factory=list)   # lanes a worker was Popen'd for
+    reaped: list[str] = field(default_factory=list)     # lanes a SCAVENGE was appended for
+    flagged: list[str] = field(default_factory=list)    # lanes surfaced (advisory)
+    skipped_reaps: list[str] = field(default_factory=list)  # REAPs the lock deferred
+    # Lanes a *proposed* halt was surfaced for (acting-on-spin, docs/90 §5). PURELY
+    # ADVISORY: the driver surfaces the proposal exactly as it surfaces `flagged` —
+    # it Popens nothing, writes NO OP_RELEASE / OP_SCAVENGE, kills no process. A
+    # spinner whose halt is proposed STILL holds its lease; actuation is the
+    # operator's explicit `dos halt`, never the supervisor's (the docs/99 floor).
+    proposed_halts: list[str] = field(default_factory=list)
+
+
+def _pending_from_launched(launched: dict, *, now_ms: int, cooldown_ms: int) -> frozenset:
+    """Lanes launched within the cooldown window — the race belt's `pending` set."""
+    return frozenset(
+        lane for lane, ts in launched.items() if now_ms - ts < cooldown_ms
+    )
+
+
+def plan_tick(cfg, *, target, now_ms, launched, cooldown_ms=DEFAULT_COOLDOWN_MS):
+    """Gather evidence (with the pending race-belt) and return the PURE verdict.
+
+    No effects — this is the testable seam. `launched` is the driver's
+    {lane: launched_at_ms} set; lanes inside the cooldown window are marked
+    `pending` so the verdict does not re-spawn a worker whose ACQUIRE has not yet
+    journalled. Imports `cli._supervise_evidence` so SUP and `dos loop` gather
+    through the SAME boundary code.
+
+    The population POLICY is the workspace's `dos.toml [supervise]` declaration
+    (`cfg.supervise`: count_spinning_as_alive + reap_stalled), with `target`
+    overridden by the driver's effective target for this run — the same
+    config-sourced policy the `dos loop` emitter uses, so the watchdog and the
+    hand-run emitter can never diverge on whether a spinner counts as up or the
+    dead are reaped.
+    """
+    import dataclasses
+
+    from dos import cli  # consumer→consumer import (driver may import the CLI)
+
+    pending = _pending_from_launched(launched, now_ms=now_ms, cooldown_ms=cooldown_ms)
+    ev = cli._supervise_evidence(cfg, target=target, now_ms=now_ms, pending_lanes=pending)
+    policy = dataclasses.replace(cfg.supervise, target=target)
+    return supervise.supervise(ev, policy)
+
+
+def tick(
+    cfg,
+    *,
+    target,
+    now_ms,
+    launched,
+    root_run=None,
+    cooldown_ms=DEFAULT_COOLDOWN_MS,
+    popen=subprocess.Popen,
+):
+    """One supervise tick: plan, then enact (Popen spawns + scavenge reaps).
+
+    Mutates `launched` in place (records each spawn's launch ms; drops a lane once
+    its lease is visible so it stops being treated as pending). `popen` is
+    injectable so tests record launches without a real subprocess. Returns
+    `(verdict, TickActions)`.
+    """
+    verdict = plan_tick(cfg, target=target, now_ms=now_ms, launched=launched,
+                        cooldown_ms=cooldown_ms)
+    actions = TickActions()
+
+    # Reap first (free the dead lanes' journal state before refilling). Look up the
+    # live lease dict to pass the real (loop_ts, lane) identity to scavenge_entry.
+    live = _live_leases_by_lane(cfg)
+    for plan in verdict.reap:
+        lease = live.get(plan.lane) or {"lane": plan.lane}
+        if _scavenge_under_lock(cfg, lease, reason="supervisor: STALLED"):
+            actions.reaped.append(plan.lane)
+            launched.pop(plan.lane, None)  # a reaped lane is no longer in-flight
+        else:
+            actions.skipped_reaps.append(plan.lane)
+
+    # Spawn the free admissible lanes the plan named. Each worker gets its OWN
+    # run-id minted as a CHILD of the supervisor root (process-id WORKER_PROCESS_ID),
+    # so the correlation spine records "this dispatch-loop was launched by this
+    # supervisor" across the `claude -p` boundary via the CID_* lineage env.
+    for plan in verdict.spawn:
+        env = dict(os.environ)
+        if root_run is not None:
+            child = run_id.mint(WORKER_PROCESS_ID, parent=root_run)
+            env.update(run_id.lineage_env(child))
+        try:
+            popen(_worker_argv(plan.lane), env=env)
+            launched[plan.lane] = now_ms
+            actions.spawned.append(plan.lane)
+        except Exception:  # noqa: BLE001 — a failed launch is non-fatal; retry next tick
+            pass
+
+    actions.flagged = [p.lane for p in verdict.flag]
+
+    # Acting-on-spin (docs/90 §5): surface the *proposed* halts, advisory-only.
+    # CRITICAL: this is a SURFACE, not an actuation — we record the lanes and do
+    # NOT Popen, NOT scavenge, NOT release a lease. A proposed halt of a live
+    # spinner stays the operator's to enact (`dos halt`); the supervisor never
+    # kills a live worker (the docs/99 PDP-not-PEP floor). Note we read the
+    # SEPARATE `verdict.proposed_halt` tuple, never `verdict.reap` — so a proposal
+    # can never flow into the reap/scavenge path above.
+    actions.proposed_halts = [p.lane for p in verdict.proposed_halt]
+
+    # Housekeeping: a lane whose lease is now visible (ACQUIRE journalled) is no
+    # longer in-flight — drop it from `launched` so it stops counting as pending.
+    for lane in list(launched):
+        if lane in live:
+            launched.pop(lane, None)
+
+    return verdict, actions
+
+
+def _live_leases_by_lane(cfg: _config.SubstrateConfig) -> dict:
+    """The current live leases keyed by lane (read-only; [] on a missing journal)."""
+    try:
+        entries = lane_journal.read_all(path=cfg.paths.lane_journal)
+        leases = lane_journal.replay(entries)
+    except Exception:  # noqa: BLE001
+        return {}
+    return {str(l.get("lane") or ""): l for l in leases}
+
+
+def run(
+    config=None,
+    *,
+    target: Optional[int] = None,
+    interval: float = DEFAULT_INTERVAL_S,
+    max_ticks: Optional[int] = None,
+    cooldown_ms: int = DEFAULT_COOLDOWN_MS,
+    clock_ms=None,
+    sleep=time.sleep,
+    popen=subprocess.Popen,
+) -> int:
+    """Run the supervisor watchdog until `max_ticks` or an operator interrupt.
+
+    Mints a root run-id (`PROC-dos-supervise`) so every worker it launches carries
+    the supervisor's lineage across the `claude -p` boundary (the correlation
+    spine). Each tick gathers + plans + enacts, then sleeps `interval` (long — a
+    watchdog, not a busy-poll). `clock_ms`/`sleep`/`popen` are injectable for
+    deterministic tests. Returns 0 on a clean stop.
+
+    `target` defaults to the workspace's standing `dos.toml [supervise]` target
+    (`cfg.supervise.target`) so a watchdog launched with no explicit population
+    keeps the declared one; pass an int to override it for this process. The two
+    booleans (count_spinning_as_alive / reap_stalled) always come from the config
+    policy via `plan_tick`.
+    """
+    cfg = _config.ensure(config)
+    if target is None:
+        target = cfg.supervise.target
+    # Startup crash-recovery: clear any journal write-lock a prior (crashed)
+    # supervisor left behind. Safe because the supervisor is single-writer-per-host
+    # — at startup there is no other legitimate holder, so a present lock is a
+    # crash orphan that would otherwise wedge the first reap.
+    _clear_stale_lock(cfg)
+    root_run = run_id.mint("dos-supervise")
+    launched: dict = {}
+    ticks = 0
+    _clock = clock_ms if clock_ms is not None else (lambda: int(time.time() * 1000))
+    try:
+        while max_ticks is None or ticks < max_ticks:
+            now_ms = _clock()
+            tick(cfg, target=target, now_ms=now_ms, launched=launched,
+                 root_run=root_run, cooldown_ms=cooldown_ms, popen=popen)
+            ticks += 1
+            if max_ticks is not None and ticks >= max_ticks:
+                break
+            sleep(interval)
+    except KeyboardInterrupt:
+        return 0
+    return 0