riskrails 3.1.0 → 3.2.1

package/skills/ai-task/rr_state/handoff.py

@@ -0,0 +1,226 @@
+"""handoff: the resume point, the recent notes, the handoff file and the move of a task to the other runtime.
+
+core: TIERS, RESUME_COMMAND
+shell: set_resume_point, recent_notes, handoff_lines, write_handoff, handoff_to
+"""
+import os
+import shlex
+
+from rr_state import fs
+from rr_state import journal
+from rr_state import policy as rr_policy
+from rr_state import profile
+from rr_state import questions
+from rr_state import runtime as rr_runtime
+from rr_state import task
+
+# weight.py sits beside state.py; the entry puts that directory on sys.path.
+try:
+    import weight                         # pure computation; it writes nothing
+except ImportError:
+    weight = None
+
+TIERS = ["T0", "T1", "T2", "T3", "T4", "T5", "T6"]
+
+
+def set_resume_point(state, rt=rr_runtime.Runtime()):
+    """Where a session that lost its context picks the work up again."""
+    plan = state.get("approved_plan") or {}
+    state["resume_point"] = {
+        "stage": state.get("current_stage"),
+        "step_id": plan.get("current_step_id"),
+        "next_action": state.get("next_action"),
+        "at": fs.now(),
+        "runtime": rt.name if rt.name in rr_runtime.RUNTIMES else state.get("owner_runtime"),
+    }
+
+
+def recent_notes(root, state, limit=3):
+    """One pass for all three kinds — the journal is read on every stage-moving
+    command — and only this task's own notes: a report directory can be deleted,
+    and then next_task_id hands the same id to a different task."""
+    events, _ = journal.read_journal(root, state.get("task_id"))
+    found = {"decision": [], "rejected": [], "failed": []}
+    for event in reversed(events):
+        # A report directory can be deleted, and next_task_id then hands the same
+        # id to a different task. The scan stops at this task's own task_started
+        # rather than at a timestamp: two tasks can share a second, but not a
+        # position in an append-only file.
+        if event.get("event") == "task_started":
+            break
+        if event.get("event") != "note":
+            continue
+        kind = (event.get("data") or {}).get("kind")
+        if kind in found and len(found[kind]) < limit:
+            found[kind].append(event)
+    return found
+
+
+def handoff_lines(root, state, reason, rt=rr_runtime.Runtime()):
+    """The six parts of I4, ≤ 30 lines by construction: a header, the three
+    facts a session needs first, three sections of three notes, and the user's
+    own last words. Everything here is a fact the runtime cannot lose — the
+    state, the journal, task.md §Questions and session.json — never a transcript."""
+    plan = state.get("approved_plan") or {}
+    steps = plan.get("steps") or []
+    # step ids and file scopes come from a model-authored plan file, so they are
+    # collapsed like every other free text before they reach the frame.
+    step = " · step %s/%d" % (fs.one_line(plan.get("current_step_id"), 40) or "-", len(steps)) if steps else ""
+    out = ["# Handoff — %s (%s, %s) · stage %s%s · owner %s · written %s (%s)"
+           % (state.get("task_id"), state.get("workflow"),
+              state.get("risk_tier") or state.get("mode") or "untiered",
+              state.get("current_stage"), step, state.get("owner_runtime") or "unknown",
+              fs.now(), reason),
+           "Goal: %s" % fs.one_line(state.get("goal"))[:160]]
+
+    resume = state.get("resume_point") or {}
+    allowed = [s for s in steps if s.get("step_id") == resume.get("step_id")]
+    where = ""
+    if resume.get("step_id") and allowed:
+        # A step the plan no longer has is not a resume point: saying nothing
+        # beats pointing a context-less session at a deleted scope.
+        where = "   ← resume point (step %s: %s)" % (
+            fs.one_line(resume["step_id"], 40),
+            fs.one_line(", ".join(str(f) for f in (allowed[0].get("allowed_files") or [])[:2]), 120))
+    out.append("Next: %s%s" % (fs.one_line(state.get("next_action"), 200) or "none recorded", where))
+
+    path = fs.questions_path(root, state, None)
+    pending = [q["id"] for q in questions.parse_questions(path)[1] if questions.is_pending(q)]
+    out.append("Pending questions: %s" % (
+        "%s — %s" % (", ".join(pending), os.path.relpath(path, root)) if pending else "none"))
+    if rr_policy.batch_on(state):
+        try:
+            policy = weight.load_policy(root)[0] if weight else {}
+        except (OSError, ValueError, RecursionError):
+            policy = {}                       # best effort: the handoff never fails a command
+        out.append("Batch: on · ready %s · review %d/%d · suite %d/%d" % (
+            ", ".join(fs.one_line(s["id"], 40) for s in task.ready_steps(state)) or "none",
+            (state.get("review") or {}).get("passes", 0), rr_policy.budget(policy, state, "review_rounds_max")[0],
+            (state.get("verify") or {}).get("suite_runs", 0), rr_policy.budget(policy, state, "max_suite_runs")[0]))
+
+    notes = recent_notes(root, state)
+    for kind, heading in (("decision", "Decisions"), ("rejected", "Rejected"),
+                          ("failed", "Failed attempts")):
+        out.append("## %s (latest 3)" % heading)
+        if not notes[kind]:
+            out.append("- none")
+            continue
+        for note in notes[kind]:
+            data = note.get("data") or {}
+            text = fs.one_line(data.get("text"), 200)
+            if kind == "failed":
+                out.append("- %s — error: %s" % (text, fs.one_line(data.get("error"), 160) or "none given"))
+            else:
+                why = fs.one_line(data.get("why"), 200)
+                out.append("- %s%s" % (text, " — because %s" % why if why else ""))
+
+    pending_to = (state.get("handoff") or {}).get("pending_to")
+    if pending_to:
+        review = state.get("cross_vendor_review") or {}
+        out.append("Handed to %s at %s%s — resume there with /rr-build" % (
+            pending_to, (state.get("handoff") or {}).get("pending_since"),
+            " for the cross-vendor review" if review.get("status") == "requested" else ""))
+    advice = profile.advisory_line(state, rt=rt)
+    if advice:
+        out.append(advice)
+
+    session = fs.read_session(root)
+    out.append("## Latest user instruction (verbatim, %s, %s)"
+               % (session.get("last_prompt_at") or "never", session.get("runtime") or "unknown"))
+    if os.environ.get("AI_HANDOFF_NO_PROMPT"):
+        # The prompt may carry a secret; recording it is the default, not a duty.
+        out.append("> omitted (AI_HANDOFF_NO_PROMPT=1)")
+    else:
+        out.append("> %s" % (fs.one_line(session.get("last_prompt"), 300) or "none recorded"))
+    return out
+
+
+def write_handoff(root, state, reason, rt=rr_runtime.Runtime()):
+    """A pure function of the state, the journal, task.md §Questions and session.json,
+    written atomically — rendering it twice gives the same file but its
+    timestamp. Best effort end to end, rendering included: a handoff that cannot
+    be built or written must never fail the command that moved the stage, and
+    its inputs include a hook-written sidecar and an append-only journal that
+    nothing validates.
+
+    It mutates `state` in memory only. The caller that is already changing the
+    task persists it; `handoff` on its own never writes the state file, because
+    the hook calls it while another command may be mid-write."""
+    path = fs.handoff_path(root)
+    try:
+        lines = handoff_lines(root, state, reason, rt=rt)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        tmp = "%s.%d.tmp" % (path, os.getpid())
+        with open(tmp, "w", encoding="utf-8") as fh:
+            fh.write("\n".join(lines) + "\n")
+        # It carries the user's verbatim instruction, so it is theirs to read.
+        # events.jsonl is committed with the task and stays 0644; this one is
+        # git-ignored and describes a session.
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except Exception:  # pylint: disable=broad-exception-caught  # derived artefact: never fatal
+        return None
+    # Updated, not replaced: pending_to/pending_since (schema 5) live here too.
+    if not isinstance(state.get("handoff"), dict):
+        state["handoff"] = {}
+    state["handoff"].update({"file": os.path.relpath(path, root), "written_at": fs.now(), "reason": reason})
+    # Journal-only, like note: the handoff is derived, and history[] records
+    # what changed the task, not what was rendered from it.
+    journal.append_journal(root, state.get("task_id"), journal.journal_line(
+        state.get("task_id"), "handoff_written", "agent", state.get("current_stage"),
+        reason, {"reason": reason, "lines": len(lines)}, runtime=rt.name))
+    return lines
+
+
+RESUME_COMMAND = {"claude": "claude -p '/rr-build'", "codex": "codex exec '/rr-build'"}
+
+
+def handoff_to(args, root, rt=rr_runtime.Runtime()):
+    """Move the task to the other runtime on purpose (WP5 R10). Ownership moves
+    now; the receiving runtime's first change completes it, and until then any
+    other runtime's change is refused with exit 7. Pending questions do not
+    block it: they travel with the task."""
+    state = task.load(root, claim=False, rt=rt)
+    source = state.get("owner_runtime") or (rt.name if rt.name in rr_runtime.RUNTIMES else None)
+    if not state.get("owner_runtime") and args.to == source:
+        fs.die("task %s is already with %s; nothing to hand over" % (state.get("task_id"), args.to), 2)
+    if args.to == state.get("owner_runtime"):
+        fs.die("task %s is already owned by %s%s" % (
+            state.get("task_id"), args.to,
+            " (handed over, waiting for it to resume)" if (state.get("handoff") or {}).get("pending_to") else ""), 2)
+    if state.get("current_stage") == "done":
+        fs.die("task %s is closed; start a new one with start" % state.get("task_id"), 2)
+    if not rr_runtime.installed(args.to):
+        fs.die("%s is not installed here (%s has no skills/ai-task/state.py); run npx riskrails --target %s"
+            % (args.to, rr_runtime.runtime_home(args.to), args.to), 2)
+    tier = state.get("risk_tier")
+    via = "review" if args.for_ == "review" else "manual"
+    review = state.get("cross_vendor_review")
+    if isinstance(review, dict) and review.get("status") == "requested":
+        # Any move of the task ends an open request: taken back, it was not done;
+        # handed on again, a new --for review opens a fresh one. Left open, it
+        # sent a later plain handoff straight into an unasked-for review.
+        review.update({"status": "cancelled", "cancelled_at": fs.now(), "by_runtime": rt.name})
+    data = {"from": source, "to": args.to, "via": via, "reason": args.why or "", "tier": tier,
+            "tty": bool(os.isatty(0) and os.isatty(1))}
+    if via == "review":
+        threshold = (profile.read_profile(rt=rt).get("preferred_runtime") or {}).get("cross_vendor_review_from") or "T5"
+        if tier in TIERS and threshold in TIERS and TIERS.index(tier) >= TIERS.index(threshold):
+            state["cross_vendor_review"] = {"from": source, "to": args.to, "tier": tier,
+                                            "requested_at": fs.now(), "status": "requested",
+                                            "by_runtime": None}
+        else:
+            data["below_threshold"] = threshold
+            print("note: %s is below cross_vendor_review_from %s — handed over for review anyway, "
+                  "not recorded as a cross-vendor review" % (tier or "an untiered task", threshold))
+    state["owner_runtime"] = args.to
+    set_resume_point(state, rt=rt)
+    state["resume_point"]["runtime"] = args.to
+    state["handoff"]["pending_to"] = args.to
+    state["handoff"]["pending_since"] = fs.now()
+    journal.emit(root, state, "runtime_handoff", "%s -> %s (%s)" % (source, args.to, via), data, rt=rt)
+    write_handoff(root, state, "manual", rt=rt)
+    task.save(root, state)
+    print("Handed %s to %s (%s). In %s, run /rr-build: it resumes from the state file in .ai/state/."
+          % (state.get("task_id"), args.to, via, args.to))
+    print("headless (not run): cd %s && %s" % (shlex.quote(root), RESUME_COMMAND[args.to]))

package/skills/ai-task/rr_state/journal.py

@@ -0,0 +1,126 @@
+"""journal: the event vocabulary, the journal line and its append-only file, and the one function that records a state change in both the history and the journal.
+
+core: EVENT_TYPES, FORGEABLE_EVENTS, JOURNAL_MAX_BYTES, DETAIL_MAX, ERROR_MAX
+shell: journal_line, append_journal, read_journal, record, emit
+"""
+import json
+import os
+
+try:
+    import fcntl
+except ImportError:                       # not POSIX: the journal falls back to O_APPEND alone
+    fcntl = None
+
+from rr_state import fs
+from rr_state import runtime as rr_runtime
+
+# The journal vocabulary (I3): flat, append-only, one type per command that
+# changes something. A new type is added only when it has its own reader.
+EVENT_TYPES = [
+    "task_started", "stage_started", "tier_set", "tier_raised", "plan_registered",
+    "scope_change", "step_started", "step_done", "field_set", "question_asked",
+    "question_answered", "gate_requested", "gate_approved", "gate_rejected", "note",
+    "handoff_written", "runtime_handoff", "model_fallback", "missed_reroute", "schema_migrated",
+    "task_closed", "findings_closed", "review_budget_refused", "human_set",
+    # schema 7 (redesign 2.2a): the weight model's surface.
+    "weight_set", "weight_raised", "mode_set", "verify_run", "review_verdict",
+    # R36 (7c): the dialog's decisions and the consent ledger, mirrored by state.py.
+    "decision_opened", "consent_recorded", "consent_used", "consent_voided", "decision_declined",
+    "decision_settled", "decision_fallback", "plan_drift",
+    # compact-project-memory §D9: a risk recorded with `memory risk`, compacted at close.
+    "risk_recorded",
+    # the batch loop (/rr-build-all): the switch, at start or during the task.
+    "batch_set",
+]
+# The types `event` will not write: each is the record of an authorization or a
+# lifecycle decision, and is emitted by the transition that made it. `event` is
+# for a hook reporting something that happened outside the state machine.
+FORGEABLE_EVENTS = {"gate_requested", "gate_approved", "gate_rejected",
+                    "task_started", "task_closed", "weight_set", "weight_raised", "mode_set",
+                    "verify_run", "review_verdict", "decision_opened", "consent_recorded",
+                    "consent_used", "consent_voided", "decision_declined", "decision_settled",
+                    "decision_fallback", "plan_drift", "risk_recorded", "batch_set"}
+
+JOURNAL_MAX_BYTES = 4096
+DETAIL_MAX = 500
+ERROR_MAX = 1000
+
+
+def journal_line(task_id, event, actor, stage, detail, data, runtime="unknown"):
+    line = {
+        "ts": fs.now_ms(), "task": task_id, "event": event, "actor": actor,
+        "runtime": runtime, "stage": stage or "", "detail": (detail or "")[:DETAIL_MAX],
+        "data": dict(data or {}),
+    }
+    if isinstance(line["data"].get("error"), str):
+        line["data"]["error"] = line["data"]["error"][:ERROR_MAX]
+    text = json.dumps(line, ensure_ascii=False) + "\n"
+    if len(text.encode("utf-8")) > JOURNAL_MAX_BYTES:
+        # A line that cannot fit loses its payload, never its existence. The cap
+        # covers the terminator too: it is the precondition for the single write.
+        line["data"] = {"truncated": True}
+        text = json.dumps(line, ensure_ascii=False) + "\n"
+    return text
+
+
+def append_journal(root, task_id, text):
+    """One complete line, one os.write, O_APPEND. Best effort: every failure is
+    swallowed, because the state write is the contract and the journal is not."""
+    if not task_id:
+        return False
+    path = fs.journal_path(root, task_id)
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o644)
+    except OSError:
+        return False
+    payload = text.encode("utf-8")
+    try:
+        if fcntl is not None:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        # A short write (ENOSPC) returns a count rather than raising, and a torn
+        # line is exactly what the single write exists to prevent — so say so.
+        written = os.write(fd, payload)
+    except OSError:
+        return False
+    finally:
+        os.close(fd)
+    return written == len(payload)
+
+
+def read_journal(root, task_id):
+    """Tolerant by design (I3): an unparseable line is counted, never fatal."""
+    events, skipped = [], 0
+    try:
+        with open(fs.journal_path(root, task_id), encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    events.append(json.loads(line))
+                except (ValueError, RecursionError):
+                    skipped += 1
+    except OSError:
+        return [], skipped
+    return events, skipped
+
+
+def record(state, event, detail=""):
+    state.setdefault("history", []).append(
+        {"at": fs.now(), "event": event, "detail": detail}
+    )
+
+
+def emit(root, state, event, detail="", data=None, legacy=None, actor="agent", rt=rr_runtime.Runtime()):
+    """One state change: today's history entry plus one journal line.
+
+    `legacy` keeps history[]'s original event name where the journal's is newer,
+    so every reader and every test written before the journal still sees what it
+    expects and the two records stay one-to-one.
+    """
+    if event not in EVENT_TYPES:
+        fs.die("unknown event type '%s' (have: %s)" % (event, ", ".join(EVENT_TYPES)))
+    record(state, legacy or event, detail)
+    append_journal(root, state.get("task_id"), journal_line(
+        state.get("task_id"), event, actor, state.get("current_stage"), detail, data, runtime=rt.name))

package/skills/ai-task/rr_state/labels.py

@@ -0,0 +1,99 @@
+"""labels: the consent labels a decision may offer as commands -- the one-simple-command rule, the state.py command a label runs, and the absolute command the agent and the human share.
+
+shell: validate_label, human_name, state_label
+core: LABEL_MAX, LABEL_FORBIDDEN, INTERPRETER_RE, PUSH_REF_RE, INTERPRETER_FLAG_RE, NPX_PACKAGE_RE, label_argv, subcommand, state_label_ok, subcommand_prefix
+"""
+
+import os
+import re
+import shlex
+
+from rr_state import fs
+
+LABEL_MAX = 400
+LABEL_FORBIDDEN = (";", "&", "|", "\n", "\r", "`", "$(", "<", ">")
+INTERPRETER_RE = re.compile(r"^python3?$")   # a bare name: a path could be any program
+PUSH_REF_RE = re.compile(r"^[A-Za-z0-9._/-]+$")  # no '+' (a force push), no ':' (a refspec), no option
+INTERPRETER_FLAG_RE = re.compile(r"^-[IS]+$")
+NPX_PACKAGE_RE = re.compile(r"^riskrails@[0-9A-Za-z.+-]+$")
+
+
+def label_argv(label):
+    """(script, argv) when a label runs a state.py, else None."""
+    try:
+        tokens = shlex.split(label)
+    except ValueError:
+        return None
+    if not tokens or not INTERPRETER_RE.match(tokens[0]):
+        return None
+    i = 1
+    while i < len(tokens) and INTERPRETER_FLAG_RE.match(tokens[i]):
+        i += 1
+    if i >= len(tokens) or os.path.basename(tokens[i]) != "state.py":
+        return None
+    return tokens[i], tokens[i + 1:]
+
+
+def subcommand(argv):
+    """argv without the global options: what the command is."""
+    rest = list(argv)
+    while rest[:1] in (["--root"], ["--runtime"]) and len(rest) >= 2:
+        rest = rest[2:]
+    return rest
+
+
+def state_label_ok(argv):
+    """approve | reject | profile set | verify --by | review --by | start --mode … --by."""
+    rest = subcommand(argv)
+    if rest[:1] in (["approve"], ["reject"]) or rest[:2] == ["profile", "set"]:
+        return True
+    if rest[:1] in (["verify"], ["review"]):
+        return "--by" in rest
+    return rest[:1] == ["start"] and "--mode" in rest and "--by" in rest
+
+
+def validate_label(label):
+    """None when `label` may be offered as a command (R36.4), else why not."""
+    if not isinstance(label, str) or not label or label != label.strip():
+        return "a label is a non-empty string without surrounding blanks"
+    if len(label) > LABEL_MAX or not label.isprintable():
+        return "a label is at most %d printable characters" % LABEL_MAX
+    bad = [c for c in LABEL_FORBIDDEN if c in label]
+    if bad:
+        return "a label is one simple command (it contains %s)" % " ".join(repr(c) for c in bad)
+    try:
+        tokens = shlex.split(label)
+    except ValueError as exc:
+        return "a label must split as a shell command (%s)" % exc
+    if tokens[:2] == ["git", "commit"]:
+        return None
+    if tokens[:2] == ["git", "push"]:
+        return None if len(tokens) == 4 and all(PUSH_REF_RE.match(t) and not t.startswith("-")
+                                                for t in tokens[2:]) else \
+            "a push label is exactly 'git push <remote> <branch>', no '+', ':' or option"
+    if tokens[:1] == ["npx"] and len(tokens) >= 3 and NPX_PACKAGE_RE.match(tokens[1]) and tokens[-1] == "--yes":
+        return None
+    script = label_argv(label)
+    if script and os.path.realpath(script[0]) == os.path.realpath(fs.ENTRY) \
+            and state_label_ok(script[1]):
+        return None
+    return ("a label starts with git commit, git push <remote> <branch>, state.py approve|reject|"
+            "profile set|verify --by|review --by|start --mode --by, or npx riskrails@<v> … --yes")
+
+
+def human_name(root):
+    """Who the labels name as --by: the repository's git user, else $USER."""
+    return fs.one_line(fs.run_text(root, ["git", "config", "user.name"]) or os.environ.get("USER") or "human", 80)
+
+
+def state_label(root, argv):
+    """The command that runs this state.py with argv: absolute, quoted, with
+    --root, so the human's pick and the agent's call are one string."""
+    if "--root" not in subcommand_prefix(argv):
+        argv = ["--root", root] + list(argv)
+    return "python3 %s %s" % (shlex.quote(fs.ENTRY), shlex.join(argv))
+
+
+def subcommand_prefix(argv):
+    """The global options in front of the subcommand."""
+    return list(argv)[:len(argv) - len(subcommand(argv))]

package/skills/ai-task/rr_state/ledger.py

@@ -0,0 +1,145 @@
+"""ledger: the consent ledger and the decision file, read and written as plain data.
+
+core: LEDGER_LINE_MAX, LEDGER_TYPES, parse_ts, latest_rounds, next_decision_id
+shell: ledger_append, read_ledger, live_picks, read_decisions, write_decisions
+"""
+import contextlib
+import json
+import os
+import re
+from datetime import datetime, timezone
+
+from rr_state import fs
+
+LEDGER_LINE_MAX = 4096
+LEDGER_TYPES = {"offer", "pick", "use", "void", "decline", "settle"}
+
+
+def ledger_append(root, entry):
+    """One line, one write, O_APPEND; called under ledger_lock."""
+    line = dict({"v": 1}, **entry)
+    line["at"] = fs.now()
+    payload = (json.dumps(line, ensure_ascii=False, separators=(",", ":")) + "\n").encode("utf-8")
+    if len(payload) > LEDGER_LINE_MAX:
+        raise OSError("a consent line is over %d bytes" % LEDGER_LINE_MAX)
+    fd = os.open(fs.ledger_path(root), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o644)
+    try:
+        if os.write(fd, payload) != len(payload):
+            raise OSError("short write to consent.jsonl")
+    finally:
+        os.close(fd)
+
+
+def read_ledger(root, path=None):
+    """Every well-formed line, in order. A torn or foreign line is skipped, so a
+    damaged ledger can only show fewer picks than were written (fails closed).
+    The hooks keep their own reader (hooks/guard/dialog.py, 7d1); the contract
+    test feeds both the same fixtures."""
+    entries = []
+    try:
+        with open(path or fs.ledger_path(root), encoding="utf-8") as fh:
+            for raw in fh:
+                try:
+                    entry = json.loads(raw)
+                except (ValueError, RecursionError):
+                    continue
+                if isinstance(entry, dict) and entry.get("v") == 1 and entry.get("type") in LEDGER_TYPES:
+                    entries.append(entry)
+    except OSError:
+        return []
+    return entries
+
+
+def parse_ts(text):
+    try:
+        return datetime.strptime(text, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    except (TypeError, ValueError):
+        return None
+
+
+def latest_rounds(ledger):
+    """decision -> the picks of its latest dialog call (one tool_use_id). A
+    re-offer's picks replace the earlier round's whatever became of them, so an
+    expired, voided or other-session pick never blocks the new one (R36.8)."""
+    rounds = {}
+    for entry in ledger:
+        if entry["type"] == "pick" and isinstance(entry.get("order"), int):
+            call, picks = rounds.get(entry.get("decision"), (None, []))
+            if not picks or call != entry.get("tool_use_id"):
+                rounds[entry.get("decision")] = (entry.get("tool_use_id"), [entry])
+            else:
+                picks.append(entry)
+    return {decision: picks for decision, (_, picks) in rounds.items()}
+
+
+def live_picks(ledger, session, at=None):
+    """The picks a command may consume now (R36.7): of each decision's latest
+    round, unused, not voided, the decision not settled, same session, inside
+    the window — and only the first unused one in its order. A later pick's
+    window restarts when the one before it is used."""
+    at = at or datetime.now(timezone.utc)
+    used, voided, settled = {}, set(), set()
+    for entry in ledger:
+        kind = entry["type"]
+        if kind == "use":
+            used[entry.get("id")] = parse_ts(entry.get("at"))
+        elif kind == "void":
+            voided.update(entry.get("ids") or [])
+        elif kind == "settle":
+            settled.add(entry.get("decision"))
+    live = []
+    for decision, chain in latest_rounds(ledger).items():
+        if decision in settled:
+            continue
+        previous_use = None
+        for pick in sorted(chain, key=lambda p: p["order"]):
+            if pick.get("id") in used:
+                previous_use = used[pick.get("id")]
+                continue
+            picked, expires = parse_ts(pick.get("at")), parse_ts(pick.get("expires_at"))
+            if pick.get("id") in voided or pick.get("session") != session or not picked or not expires:
+                break
+            if previous_use and previous_use > picked:
+                expires = previous_use + (expires - picked)
+            if at <= expires:
+                live.append(pick)
+            break
+    return live
+
+
+def read_decisions(root):
+    """decision.json, or an empty document when there is none."""
+    try:
+        with open(fs.decision_path(root), encoding="utf-8") as fh:
+            data = json.load(fh)
+    except FileNotFoundError:
+        return {"version": 1, "open": []}
+    except (OSError, ValueError, RecursionError) as exc:
+        fs.die("%s is unreadable (%s); only state.py writes it. Remove it to drop every open decision."
+            % (fs.decision_path(root), exc))
+    if not isinstance(data, dict) or not isinstance(data.get("open"), list):
+        fs.die("%s is not a decision document; remove it to drop every open decision." % fs.decision_path(root))
+    return data
+
+
+def write_decisions(root, data):
+    """Atomic; the file is deleted when nothing is open (R36.14)."""
+    path = fs.decision_path(root)
+    if not data["open"]:
+        with contextlib.suppress(FileNotFoundError):
+            os.remove(path)
+        return
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = "%s.%d.tmp" % (path, os.getpid())
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+    os.replace(tmp, path)
+
+
+def next_decision_id(data, ledger):
+    """One more than any id the file or the ledger has seen: ids are never reused."""
+    seen = [d.get("id") for d in data["open"]] + [e.get("decision") for e in ledger] + \
+        [d for e in ledger for d in (e.get("decisions") or [])]
+    numbers = [int(x[1:]) for x in seen if isinstance(x, str) and re.match(r"^D\d+$", x)]
+    return "D%d" % (max(numbers or [0]) + 1)