riskrails 3.0.1 → 3.2.1

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

@@ -0,0 +1,164 @@
+"""dialog_cmd: the consent and decision commands -- decision open/show/settle/fallback, the pick applied, and the read-only consent view.
+
+core: SETTLE_EFFECT
+shell: cmd_decision, decision_open, decision_settle, apply_choice, cmd_consent
+"""
+# pylint: disable=unused-argument  # uniform cli dispatch: cmd_consent takes rt like every command
+import argparse
+import json
+import os
+import sys
+
+from rr_state import dialog, fs, labels, profile, questions_cmd, task
+from rr_state import ledger as rr_ledger
+from rr_state import runtime as rr_runtime
+
+SETTLE_EFFECT = {"defer": "defer", "keep": "ack", "ack": "ack", "answer": "answered"}
+
+
+def cmd_decision(args, root, rt=rr_runtime.Runtime()):
+    """decision show|open|settle|fallback (R36.3, R36.14, R36.15)."""
+    if args.action == "open":
+        decision_open(args, root, rt=rt)
+        return
+    data = rr_ledger.read_decisions(root)
+    if args.action == "show":
+        # A session sees the decisions it opened (and those that name none):
+        # the hooks' gate and Stop reminder hold only the opener to them.
+        session = os.environ.get(dialog.SESSION_ENV.get(rr_runtime.own_runtime(runtime=rt.name), ""))
+        chosen = [d for d in data["open"] if (not args.id or d["id"] == args.id) and (
+            not session or (d.get("session") in (None, "", session) and d.get("runtime") in (None, "", rr_runtime.own_runtime(runtime=rt.name))))]
+        if not chosen:
+            fs.die("no open decision%s" % (" " + args.id if args.id else ""))
+        if args.json:
+            print(json.dumps(dialog.dialog_payload(chosen, rr_runtime.own_runtime(runtime=rt.name)), ensure_ascii=False))
+        else:
+            dialog.print_dialog(chosen, rt=rt)
+        return
+    decision = next((d for d in data["open"] if d["id"] == args.id), None)
+    if decision is None:
+        fs.die("no open decision %s (open: %s)" % (args.id or "(--id)",
+                                                ", ".join(d["id"] for d in data["open"]) or "none"))
+    if args.action == "fallback":
+        if not args.why:
+            fs.die("decision fallback needs --why \"<why the dialog cannot be used>\"")
+        dialog.settle_decision(root, decision["id"], "fallback")
+        print("%s falls back to the terminal (%s). The human runs, outside the agent:"
+              % (decision["id"], fs.one_line(args.why, 200)))
+        for option in decision["options"]:
+            if option["kind"] == "command":
+                print("  %s" % option["label"])
+        return
+    decision_settle(args, root, decision, rt=rt)
+
+
+def decision_open(args, root, rt=rr_runtime.Runtime()):
+    """The one opener the model may call: commit and push, nothing else."""
+    if args.kind != "commit":
+        fs.die("decision open takes --kind commit; every other decision is opened by the command that "
+            "needs it (close, ask, the budgets, start --mode)")
+    if not args.commands:
+        fs.die("decision open --kind commit needs --command \"git commit …\" [--command \"git push <remote> <branch>\"]")
+    for command in args.commands:
+        why = labels.validate_label(command)
+        if why or command.split()[:2] not in (["git", "commit"], ["git", "push"]):
+            fs.die("CONSENT_LABEL_INVALID — %s: %s" % (why or "a commit decision offers git commit and git push only",
+                                                     command[:120]), 6)
+    if not dialog.dialog_on(root, runtime=rt.name):
+        fs.die("the dialog is off here (.ai/policies/dialog.json, the runtime's dialog tool, a session id): "
+            "suggest the commands; the human runs them outside the agent")
+    state = task.load(root, required=False, claim=False, rt=rt)
+    state = state if state and task.is_v7(state) else None
+    head = dialog.task_facts(root, state) + "\n" if state else ""
+    question = "%sbranch %s · %s\nRun these, in this order?\n%s" % (
+        head, fs.run_text(root, ["git", "rev-parse", "--abbrev-ref", "HEAD"]) or "?",
+        fs.run_text(root, ["git", "diff", "--shortstat", "HEAD"]) or "no uncommitted change",
+        "\n".join("  %s" % c for c in args.commands))
+    options = [{"kind": "choice", "effect": "defer", "label": "Not now — commit nothing"}] + \
+        [{"kind": "command", "label": c} for c in args.commands]
+    decision, why = dialog.open_decision(root, state, "commit", "Commit", question, options, "decision open",
+                                  multi=len(args.commands) > 1, rt=rt)
+    if decision is None:
+        fs.die(why, 6)
+    dialog.print_dialog([decision], rt=rt)
+
+
+def decision_settle(args, root, decision, rt=rr_runtime.Runtime()):
+    """(b) apply what the recorder wrote — a choice pick or a decline; (c) a
+    human in a terminal picks an option by number (R36.14)."""
+    if args.pick is not None:
+        via, why = dialog.human_route(rt=rt)
+        if via is None:
+            fs.die("APPROVAL_REFUSED — 'decision settle --pick' is the human's, from their own terminal.\n"
+                "Refused because %s." % why, 5)
+        option = next((o for o in decision["options"] if o["n"] == args.pick), None)
+        if option is None:
+            fs.die("%s has no option %d" % (decision["id"], args.pick))
+        if option["kind"] == "command":
+            fs.die("option %d is a command: run it in this terminal instead —\n  %s" % (args.pick, option["label"]))
+        apply_choice(root, decision, option, None, labels.human_name(root), via, rt=rt)
+        return
+    # The human's last answer decides: a decline after a pick wins, and only the
+    # latest round's choice counts.
+    ledger = rr_ledger.read_ledger(root)
+    mine = [e for e in ledger if e.get("decision") == decision["id"] and e["type"] in ("pick", "decline")]
+    choices = {o["n"]: o for o in decision["options"] if o["kind"] == "choice"}
+    picked = [e for e in rr_ledger.latest_rounds(ledger).get(decision["id"], []) if e.get("option") in choices]
+    if picked and mine[-1]["type"] == "pick":
+        apply_choice(root, decision, choices[picked[-1]["option"]], picked[-1].get("id"), labels.human_name(root),
+                     "dialog", rt=rt)
+        return
+    if mine and mine[-1]["type"] == "decline":
+        dialog.settle_decision(root, decision["id"], "declined")
+        print("%s settled: declined in the dialog (%s); nothing runs"
+              % (decision["id"], mine[-1].get("why") or "no answer"))
+        return
+    live = [p for p in rr_ledger.live_picks(ledger, (dialog.dialog_on(root, runtime=rt.name) or {}).get("session"))
+            if p.get("decision") == decision["id"]]
+    if live:
+        fs.die("%s has a live pick: run it verbatim —\n  %s" % (decision["id"], live[0].get("label")))
+    fs.die("nothing is recorded for %s: send the dialog ('state.py decision show'), or "
+        "'state.py decision fallback --id %s --why …'" % (decision["id"], decision["id"]))
+
+
+def apply_choice(root, decision, option, pick_id, by, via, rt=rr_runtime.Runtime()):
+    effect = SETTLE_EFFECT.get(option.get("effect"), "defer")
+    drift = decision.get("drift") or {}
+    if decision.get("kind") == "plan_drift" and effect == "ack" and drift.get("fingerprint"):
+        profile.write_drift_ack(drift.get("runtime") or rr_runtime.own_runtime(runtime=rt.name), drift["fingerprint"], drift.get("kept"), via)
+    if effect == "answered":
+        questions_cmd.cmd_answer(argparse.Namespace(topic=None, prose=None, by=by, via=via,
+                                      assignment=["%s=%s" % (decision.get("question_id"), option["answer"])]),
+                   root, rt=rt)
+    dialog.settle_decision(root, decision["id"], effect, pick_id)
+    print("%s settled: %s (%s)" % (decision["id"], option["label"], effect))
+
+
+def cmd_consent(args, root, rt=rr_runtime.Runtime()):
+    """Read-only: the live picks and the ledger tail; `audit` checks each pick's
+    tool_use_id against its transcript (R36.24)."""
+    ledger = rr_ledger.read_ledger(root)
+    if args.action == "audit":
+        rows = [{"id": p.get("id"), "decision": p.get("decision"), "result": dialog.audit_pick(p)}
+                for p in ledger if p["type"] == "pick"]
+        if args.json:
+            print(json.dumps(rows, ensure_ascii=False))
+        else:
+            for row in rows:
+                print("%s %s %s" % (row["id"], row["decision"], row["result"]))
+            print("%d picks: %s" % (len(rows), ", ".join("%d %s" % (sum(r["result"] == k for r in rows), k)
+                                                       for k in ("ok", "mismatch", "unverifiable"))))
+        if any(r["result"] == "mismatch" for r in rows):
+            sys.exit(1)
+        return
+    switch = dialog.dialog_on(root, runtime=rt.name)
+    live = rr_ledger.live_picks(ledger, (switch or {}).get("session"))
+    if args.json:
+        print(json.dumps({"dialog": bool(switch), "live": live, "tail": ledger[-10:]}, ensure_ascii=False))
+        return
+    print("dialog: %s · live picks: %d" % ("on" if switch else "off", len(live)))
+    for pick in live:
+        print("  %s %s until %s: %s" % (pick.get("id"), pick.get("decision"), pick.get("expires_at"),
+                                        pick.get("label")))
+    for entry in ledger[-10:]:
+        print("  %s %s %s" % (entry.get("at"), entry["type"], entry.get("id") or entry.get("decision") or ""))

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

@@ -0,0 +1,220 @@
+"""The store: where the state, the session, the journal and the logs live, and the clock, the root search and the one subprocess runner.
+
+shell: ENTRY, now, now_ms, find_root, find_root_quiet, die, state_path, remove_state, read_session, safe_sensor, find_docs_root, questions_path, read_lines, run_text, read_text, current_tree, ensure_logs
+core: STATE_NAMES, session_path, journal_path, _split_files, SLUG_RE, one_line, handoff_path, decision_path, ledger_path, logs_dir, task_md_path
+"""
+
+import contextlib
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+try:
+    import sensors                        # measurement only; it never writes this file
+except ImportError:                       # an old install that shipped state.py alone
+    sensors = None
+
+ENTRY = ""      # the entry's path: the entry sets it (fs.ENTRY = os.path.abspath(__file__)), code here reads it at call time
+
+
+def now():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def now_ms():
+    """Millisecond precision, because two journal lines can share a second."""
+    stamp = datetime.now(timezone.utc)
+    return stamp.strftime("%Y-%m-%dT%H:%M:%S.") + "%03dZ" % (stamp.microsecond // 1000)
+
+
+def find_root(start):
+    d = os.path.abspath(start)
+    while True:
+        if os.path.isdir(os.path.join(d, ".ai")):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            die("no .ai/ directory found above %s — run /rr-setup first" % start)
+        d = parent
+
+
+def find_root_quiet(start):
+    """find_root without the refusal: profile runs where there is no .ai/."""
+    d = os.path.abspath(start or ".")
+    while not os.path.isdir(os.path.join(d, ".ai")):
+        if os.path.dirname(d) == d:
+            return None
+        d = os.path.dirname(d)
+    return d
+
+
+def die(message, code=1):
+    """1 validation · 2 argparse · 4 QUESTIONS_PENDING · 5 APPROVAL_REFUSED ·
+    6 SCOPE_CHANGE_REQUIRED / run budget / REVIEW_BUDGET (I1, WP4 I4) ·
+    7 RUNTIME_HANDOFF_PENDING · 8 DIRECT_MODE_CAP (WP5 I4; one meaning per code)."""
+    print("state.py: %s" % message, file=sys.stderr)
+    sys.exit(code)
+
+
+STATE_NAMES = ("state.json", "current.json")
+
+
+def state_path(root):
+    """The task's state file, read and written where it is: state.json, or
+    current.json when that is the file a task in flight sits in. A new task
+    starts in state.json (R34's contract half, migration 0009 moves an old one);
+    both names stay readable, so a revert of that move still finds the task."""
+    new, legacy = (os.path.join(root, ".ai", "state", name) for name in STATE_NAMES)
+    return legacy if not os.path.exists(new) and os.path.exists(legacy) else new
+
+
+def remove_state(root):
+    for path in (os.path.join(root, ".ai", "state", name) for name in STATE_NAMES):
+        with contextlib.suppress(FileNotFoundError):
+            os.remove(path)
+
+
+def session_path(root):
+    return os.path.join(root, ".ai", "state", "session.json")
+
+
+def ai_unattended():
+    """AI_UNATTENDED is set when it is non-empty and not 0, false or no (case
+    and blanks ignored): one rule in every reader (risk 0587)."""
+    return os.environ.get("AI_UNATTENDED", "").strip().lower() not in ("", "0", "false", "no")
+
+
+def read_session(root):
+    """The hook's sidecar (I5). Absent, half-written or unreadable is normal."""
+    try:
+        with open(session_path(root), encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError, RecursionError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def journal_path(root, task_id):
+    return os.path.join(root, ".ai", "reports", task_id, "events.jsonl")
+
+
+def safe_sensor(call, *args, **kwargs):
+    """A bug in a sensor must never be able to stop a task. Anything unexpected
+    reads as 'unavailable', which keeps every review the tier asked for."""
+    if sensors is None:
+        return None
+    try:
+        return call(*args, **kwargs)
+    except Exception:                     # pylint: disable=broad-except
+        return None
+
+
+def _split_files(text):
+    return [f.strip() for f in (text or "").split(",") if f.strip()]
+
+
+def find_docs_root(start):
+    """--topic resolves its root from docs/sdlc/, never from .ai/: an intent's
+    questions belong to the document they serve, and the sdlc-* skills must work
+    in a repository that has no .ai/ at all (I11)."""
+    d = os.path.abspath(start)
+    while True:
+        if os.path.isdir(os.path.join(d, "docs", "sdlc")):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            die("no docs/sdlc/ directory found above %s — run /rr-spec first" % start)
+        d = parent
+
+
+SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
+
+def questions_path(root, state, topic):
+    if topic:
+        # Topic mode is the one writer that runs without .ai/ and therefore
+        # without the path guard, so the slug is validated here rather than
+        # trusted: it names a file, it never steers one.
+        if not SLUG_RE.match(topic):
+            die("--topic takes a slug of lowercase letters, digits and hyphens, not %r" % topic)
+        return os.path.join(root, "docs", "sdlc", "intent", "%s.questions.md" % topic)
+    return task_md_path(root, state)
+
+
+def read_lines(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read().split("\n")
+    except OSError:
+        return None
+
+
+def one_line(text, limit=None):
+    """Everything a caller writes into a file is collapsed to one line: a newline
+    in an answer would otherwise produce a second [Answer]: line, and the file a
+    human reads would disagree with the record every command acts on.
+
+    Total on purpose. session.json is written by a hook and the journal takes
+    typed data from one, so a value that is not a string is normal input here,
+    never a reason to fail the command that was reading it."""
+    if text is None:
+        return ""
+    if not isinstance(text, str):
+        text = str(text)
+    text = " ".join(text.split())
+    return text[:limit] if limit else text
+
+
+def handoff_path(root):
+    return os.path.join(root, ".ai", "state", "handoff.md")
+
+
+def decision_path(root):
+    return os.path.join(root, ".ai", "state", "decision.json")
+
+
+def ledger_path(root):
+    return os.path.join(root, ".ai", "state", "consent.jsonl")
+
+
+def run_text(root, argv):
+    try:
+        return subprocess.run(argv, cwd=root, capture_output=True, text=True, check=False,
+                              timeout=10).stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def read_text(root, rel):
+    try:
+        with open(os.path.join(root, rel), "rb") as fh:
+            data = fh.read(1 << 20)
+    except OSError:
+        return ""
+    return "" if b"\0" in data[:8192] else data.decode("utf-8", "replace")
+
+
+def current_tree(root):
+    return safe_sensor(sensors.snapshot_tree, root)
+
+
+def logs_dir(root, task_id):
+    return os.path.join(root, ".ai", "state", "logs", task_id)
+
+
+def ensure_logs(root, task_id):
+    """.ai/state/logs/<task>/, ignored by its own .gitignore (D4), so the shipped
+    gitignore snippet stays as it is."""
+    base = os.path.join(root, ".ai", "state", "logs")
+    os.makedirs(os.path.join(base, task_id), exist_ok=True)
+    ignore = os.path.join(base, ".gitignore")
+    if not os.path.exists(ignore):
+        with open(ignore, "w", encoding="utf-8") as fh:
+            fh.write("*\n")
+
+
+def task_md_path(root, state):
+    return os.path.join(root, ".ai", "reports", state["task_id"], "task.md")

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

@@ -0,0 +1,125 @@
+"""gate: the approval gate — the pending-question guard, the gate request and its close, and what close accepts as an approval.
+
+core: gate_question_text, confirm_names, gate_approved_for
+shell: guard_pending, request_gate, close_gate
+"""
+import os
+import re
+
+from rr_state import fs
+from rr_state import journal
+from rr_state import locks
+from rr_state import questions as questions_mod   # the bodies keep a local `questions`; the module is aliased
+from rr_state import runtime as rr_runtime
+from rr_state import task
+
+
+def guard_pending(root, command, rt=rr_runtime.Runtime()):
+    """The file is re-parsed on every stage-moving command — questions.pending is
+    only a cache — and nothing is written, so exit 4 leaves the state byte-identical."""
+    state = task.load(root, required=False, claim=False, rt=rt)
+    if state is None:
+        return
+    path = fs.questions_path(root, state, None)
+    _, questions = questions_mod.parse_questions(path)
+    # For a question the file is the truth. For the gate it is not: an
+    # authorization is closed by approve or reject, so a hand-filled [Answer]: A
+    # must not unblock the pipeline on its own — the state says when the gate is
+    # done, and until then its question keeps blocking.
+    gate_id = task.open_gate(state)
+    blocking = [q for q in questions if q["kind"] != "G" and questions_mod.is_pending(q)]
+    if command != "approve" and command != "reject" and gate_id:
+        blocking += [q for q in questions if q["id"] == gate_id]
+    if not blocking:
+        return
+    ids = [q["id"] for q in blocking]
+    if any(q["kind"] == "G" for q in blocking):
+        # `answer` refuses a G id, so the general text would send the human to a
+        # command that cannot work. A gate is closed from a terminal.
+        fs.die("QUESTIONS_PENDING — %d unanswered in %s: %s. %s is the approval gate: run "
+            "'state.py approve --by \"<name>\"' or 'state.py reject --by \"<name>\" --why \"<text>\"' "
+            "in your own terminal. Stage stays at %s."
+            % (len(blocking), os.path.relpath(path, root), ", ".join(ids),
+               ", ".join(q["id"] for q in blocking if q["kind"] == "G"),
+               state.get("current_stage")), 4)
+    fs.die("QUESTIONS_PENDING — %d unanswered in %s: %s. Answer with 'state.py answer %s' or fill "
+        "the [Answer]: lines and run 'state.py questions --sync'. Stage stays at %s."
+        % (len(blocking), os.path.relpath(path, root), ", ".join(ids),
+           " ".join("%s=<letter>" % i for i in ids), state.get("current_stage")), 4)
+
+
+def gate_question_text(task_id):
+    return "Approve %s for implementation?" % task_id
+
+
+def request_gate(root, state, gate, rt=rr_runtime.Runtime()):
+    """stage human_approval is the request, and the only way to make one: it
+    writes the gate's own question, records *which* question it is, and starts
+    the gate ungranted. A grant belongs to one gate, never to the task."""
+    path = fs.questions_path(root, state, None)
+    with locks.question_lock(path):
+        lines, questions = questions_mod.parse_questions(path)
+        number = max([q["number"] for q in questions if q["kind"] == "G"] or [0]) + 1
+        gate_id = "G%d" % number
+        while lines and not lines[-1].strip():
+            lines.pop()
+        lines = questions_mod.with_preamble(path, lines, state["task_id"])
+        lines.extend(questions_mod.question_block({
+            "id": gate_id,
+            "question": "%s (gate: %s)" % (gate_question_text(state["task_id"]), gate),
+            "options": [("A", "Approve"), ("B", "Reject — answer as `B: <reason>`")],
+        }, "human_approval", None))
+        questions_mod.write_questions(path, lines)
+        _, questions = questions_mod.parse_questions(path)
+    state["human_approval"].update({
+        "required": True, "granted": False, "granted_by": None, "granted_at": None,
+        "requested_at": fs.now(), "gate_id": gate_id, "rejected_at": None,
+        "via": None, "unattended": False,
+        # The session the plan was presented in. The file route requires the
+        # human's turn to come from *this* session — comparing session.json's two
+        # own fields proves nothing, because whichever session ran last wrote
+        # both of them.
+        "requested_session": fs.read_session(root).get("session_id"),
+    })
+    questions_mod.set_pending(root, state, questions, path)
+    journal.emit(root, state, "gate_requested", "%s: %s" % (gate_id, gate),
+             {"gate": gate, "gate_id": gate_id,
+              "requested_at": state["human_approval"]["requested_at"]}, rt=rt)
+
+
+def close_gate(root, state, gate_id, choice, text, by, via):
+    """approve and reject are the gate question's `answer`. Without this its
+    question would stay pending and block the very next command (Risks 3), and
+    `answer` still refuses a G id, because this is the only route that may close
+    one. It closes the gate the state names — never "the last G in the file"."""
+    path = fs.questions_path(root, state, None)
+    with locks.question_lock(path):
+        lines, questions = questions_mod.parse_questions(path)
+        gates = [q for q in questions if q["id"] == gate_id]
+        if not gates:
+            return False
+        lines[gates[0]["answer_at"]] = questions_mod.answer_line(choice, text, by, via)
+        questions_mod.write_questions(path, lines)
+        _, questions = questions_mod.parse_questions(path)
+    questions_mod.set_pending(root, state, questions, path)
+    return True
+
+
+def confirm_names(confirm, ops):
+    """Every operation keyword (DROP, ALTER …) appears as a word in the confirm text."""
+    words = set(re.findall(r"[A-Za-z]+", (confirm or "").upper()))
+    return bool((confirm or "").strip()) and all(op.upper() in words for op in ops)
+
+
+def gate_approved_for(state, tree):
+    """The approval close accepts, whichever route granted it (terminal or the
+    questions file): granted after the gate was requested, for the tree the gate
+    was requested on — which must be the tree now — and, for full_irreversible,
+    with a confirm that names every operation."""
+    gate, approval = state.get("gate") or {}, state["human_approval"]
+    if not (approval.get("granted") and tree and gate.get("tree") == tree
+            and (approval.get("granted_at") or "") >= (gate.get("requested_at") or "~")):
+        return False
+    if state["mode"] == "full_irreversible":
+        return confirm_names(gate.get("confirm"), state["weight"].get("operations") or [])
+    return True

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

@@ -0,0 +1,128 @@
+"""gate_cmd: the approval gate's commands -- approve (the human's grant), reject, and approve with the tree check and the irreversible confirm.
+
+shell: cmd_approve, cmd_reject, cmd_approve_v7
+"""
+import os
+import sys
+
+from rr_state import dialog, fs, handoff, journal, report, task
+from rr_state import ledger as rr_ledger
+from rr_state import gate as rr_gate      # cmd_approve_v7 binds a local `gate`
+from rr_state import runtime as rr_runtime
+
+
+def cmd_approve(args, root, rt=rr_runtime.Runtime()):
+    """The one thing the agent cannot do. A pending Q blocks this at exit 4
+    before we get here; what is left is whether a gate is open and whether the
+    approval comes from outside the agent (R11)."""
+    state = task.load(root, rt=rt)
+    gate_id = task.open_gate(state)
+    if gate_id is None:
+        if state["human_approval"].get("granted"):
+            # The gate that was open has been granted and consumed. One approval
+            # per gate, or the unattended signal in the journal is unreadable.
+            print("already approved by %s at %s (via %s)"
+                  % (state["human_approval"].get("granted_by"),
+                     state["human_approval"].get("granted_at"),
+                     state["human_approval"].get("via")))
+            return
+        fs.die("APPROVAL_REFUSED — no gate was requested: 'state.py close' requests it for a full-mode "
+            "task.", 5)
+    tty = os.isatty(0)
+    # A terminal is the stronger evidence: a launcher variable left in a human's
+    # shell must not downgrade an approval they gave in person.
+    # full_irreversible never takes the dialog: its --confirm is the human's own
+    # words, so the terminal command is offered as before (R36.10).
+    via, why = dialog.human_route(root, allow_dialog=state.get("mode") != "full_irreversible", rt=rt)
+    if via is None:
+        dialog.refuse_approval(root, state, gate_id, args.by, why)
+    task.claim_runtime(root, state, rt=rt)
+    state["human_approval"].update({
+        "required": True, "granted": True, "granted_by": args.by, "granted_at": fs.now(),
+        "requested_at": None, "gate_id": None, "requested_session": None,
+        "rejected_at": None, "via": via, "unattended": via == "unattended",
+    })
+    journal.record(state, "human_approval", "granted by %s via %s" % (args.by, via))
+    handoff.write_handoff(root, state, "stage", rt=rt)
+    task.save(root, state)                     # durable first: the rest is derived
+    journal.append_journal(root, state["task_id"], journal.journal_line(
+        state["task_id"], "gate_approved", "human" if via == "terminal" else "agent",
+        state.get("current_stage"), "granted by %s via %s" % (args.by, via),
+        dict({"by": args.by, "gate_id": gate_id, "via": via,
+              "unattended": via == "unattended", "tty": tty}, **dialog.pick_data(dialog.DIALOG_PICK[0])), runtime=rt.name))
+    if not rr_gate.close_gate(root, state, gate_id, "A", args.note, args.by, via):
+        print("state.py: %s is not in %s — the gate was granted, answer it by hand"
+              % (gate_id, os.path.relpath(fs.questions_path(root, state, None), root)),
+              file=sys.stderr)
+    task.save(root, state)
+    dialog.retire_approvals(root, state["task_id"], "approved")
+    print("approved by %s (via %s)%s" % (args.by, via, " — recorded as unattended"
+                                         if via == "unattended" else ""))
+
+
+def cmd_reject(args, root, rt=rr_runtime.Runtime()):
+    """Rejection needs no terminal: it cannot let anything through. It needs an
+    open gate, though — otherwise it would erase a grant it never opened."""
+    state = task.load(root, rt=rt)
+    gate_id = task.open_gate(state)
+    if gate_id is None:
+        fs.die("APPROVAL_REFUSED — no gate was requested: 'state.py close' requests it for a full-mode "
+            "task.", 5)
+    # A rejection needs no route, but a picked reject spends its pick, so the
+    # approval decision settles.
+    pick = dialog.dialog_pick(root, rt=rt)
+    if os.path.exists(fs.decision_path(root)):
+        rr_ledger.read_decisions(root)    # an unreadable file refuses before anything is recorded (5580)
+    task.claim_runtime(root, state, rt=rt)
+    state["human_approval"].update({
+        "required": True, "granted": False, "granted_by": None, "granted_at": None,
+        "requested_at": None, "gate_id": None, "via": None, "unattended": False,
+    })
+    state["human_approval"]["rejected_at"] = fs.now()
+    state["next_action"] = "address the rejection: %s" % fs.one_line(args.why)
+    journal.record(state, "gate_rejected", "%s: %s" % (args.by, args.why))
+    handoff.write_handoff(root, state, "stage", rt=rt)
+    task.save(root, state)
+    journal.append_journal(root, state["task_id"], journal.journal_line(
+        state["task_id"], "gate_rejected", "human", state.get("current_stage"),
+        "%s: %s" % (args.by, args.why),
+        dict({"by": args.by, "gate_id": gate_id, "why": args.why}, **dialog.pick_data(pick)), runtime=rt.name))
+    rr_gate.close_gate(root, state, gate_id, "B", args.why, args.by,
+               "dialog" if pick else "terminal" if os.isatty(0) else "prose")
+    task.save(root, state)
+    dialog.retire_approvals(root, state["task_id"], "declined")
+    print("rejected by %s; stage stays at %s" % (args.by, state["current_stage"]))
+
+
+# ---------------------------------------------- the dialog (R36, step 7c)
+#
+
+
+def cmd_approve_v7(args, root, rt=rr_runtime.Runtime()):
+    """approve, plus the gate's tree and, for full_irreversible, the operation
+    the human names (--confirm). The grant itself is cmd_approve's, unchanged."""
+    state = task.load_v7(root, rt=rt)
+    ops = state["weight"].get("operations") or []
+    confirm = (args.confirm or "").strip()
+    gate = state.get("gate") or {}
+    if task.open_gate(state):
+        tree = fs.current_tree(root)
+        if gate.get("tree") != tree:
+            # The work changed after close put it up: approving now would sign
+            # a tree nobody presented.
+            fs.die("APPROVAL_REFUSED — the tree changed after close asked for this approval (%s, now %s). "
+                "Reject it ('reject --by \"<name>\" --why \"the tree changed\"'); the next close asks "
+                "again for the tree as it is." % ((gate.get("tree") or "?")[:9], (tree or "?")[:9]), 5)
+        if state["mode"] == "full_irreversible" and not rr_gate.confirm_names(confirm, ops):
+            fs.die("APPROVAL_REFUSED — full_irreversible needs --confirm \"<what it does>\" naming %s"
+                % (" and ".join(ops) or "the irreversible operation"), 5)
+    cmd_approve(args, root, rt=rt)
+    state = task.load(root, claim=False, rt=rt)
+    gate = state.get("gate") or {}
+    if state["human_approval"].get("granted") and gate and not gate.get("approved_by"):
+        gate.update(approved_by=args.by, approved_at=state["human_approval"].get("granted_at"),
+                    via=state["human_approval"].get("via"), confirm=confirm or None,
+                    approved_tree=gate.get("tree"))
+        state["gate"] = gate
+        task.save(root, state)
+        report.write_task_md(root, state)