riskrails 4.1.0 → 4.3.0

package/skills/ai-task/memory_verify.py

@@ -0,0 +1,316 @@
+"""Verification (§D6, §D10): the findings of the package and journal checks, verify and its fresh-clone form,
+the git tree reader and the range check the pre-push validator runs."""
+import collections
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+
+import memory_compact as mc
+import memory_config as mcfg
+import memory_format as mf
+import memory_io as mio
+import memory_packages as mpkg
+
+
+# ------------------------------------------------------------------ verify (§D6)
+Finding = collections.namedtuple("Finding", "check path line what fix")
+
+
+def kept_lines(events, schema=None):
+    """The journal lines V5 requires to be the src of an entry."""
+    out = []
+    for number, event in events:
+        if not event:
+            continue
+        if event.get("event") == "task_started":
+            schema = (event.get("data") or {}).get("schema", schema)
+        rule = mf.classify(event.get("event"), schema)
+        if rule not in ("seal", "summary", "drop", "verify"):
+            out.append(number)
+    return out
+
+
+def check_packages(packages, max_bytes, sizes=None, changed=None, ref_name=None):
+    """V1, V3, V4, V8 over one tree's packages."""
+    findings = []
+    sizes = sizes or {}
+    for name, (_, kept, errors) in sorted(packages.items()):
+        if changed is not None and name not in changed:
+            continue
+        over = {e["_line"]: e for e in kept if "_over" in e}
+        for line, what in errors:
+            fix = ("restore the line from git ('git checkout -- %s') or 'state.py memory verify'"
+                   % os.path.join(mio.MEMORY_REL, name))
+            if line in over and what.startswith("line is "):
+                entry = over[line]
+                sizes_of = {k: len(mf.canonical(v)) for k, v in entry.items()
+                            if k not in mf.ENVELOPE and not k.startswith("_")}
+                field = max(sizes_of, key=sizes_of.get, default="changes")
+                fix = ("shorten it: 'state.py memory redact %s --field %s --why \"…\"' (the human's route)"
+                       % (entry["rid"], field))
+            findings.append(Finding("V1", os.path.join(mio.MEMORY_REL, name), line, what, fix))
+    by_key = collections.defaultdict(list)
+    conflicts = set()
+    redacted = {}
+    for name, (_, entries, _) in packages.items():
+        for e in entries:
+            by_key[mf.key_of(e)].append((name, e))
+            if e.get("kind") == "conflict":
+                conflicts.add((e.get("key"), tuple(e.get("rids") or [])))
+            if e.get("kind") == "redaction" and e.get("replacement"):
+                redacted[e["replacement"]] = e.get("target")
+    for key, items in sorted(by_key.items()):
+        seals = [(n, e) for n, e in items if e.get("kind") == "task"]
+        unique = {e["rid"]: (n, e) for n, e in seals}
+        chained = {e.get("supersedes") for _, e in unique.values() if e.get("supersedes")}
+        live = [rid for rid in unique if rid not in chained]
+        if len(live) > 1:
+            task = key.rsplit("#", 1)[0]
+            recorded = any(k == key and set(live) <= set(r) for k, r in conflicts)
+            if mf.NEW_ID_RE.match(task) and not recorded:
+                findings.append(Finding("V3", os.path.join(mio.MEMORY_REL, unique[live[0]][0]), None,
+                                        "%s has %d seals not chained by supersedes" % (key, len(live)),
+                                        "'state.py memory export %s' records the two as a conflict" % task))
+            elif not recorded:
+                findings.append(Finding("V3", os.path.join(mio.MEMORY_REL, unique[live[0]][0]), None,
+                                        "legacy %s has %d seals and no conflict entry" % (key, len(live)),
+                                        "'state.py memory export %s' records the conflict" % task))
+        rids = {e["rid"] for _, e in items if e.get("kind") not in ("task", "conflict", "redaction")}
+        if len(live) > 1:
+            continue                      # a recorded conflict: which entries are whose is not knowable
+        for rid in live:
+            name, seal = unique[rid]
+            own = sorted({redacted.get(r, r) for r in rids if _belongs(items, r, seal)})
+            if len(own) != seal.get("entries") or mf.seal_digest(own) != seal.get("digest"):
+                findings.append(Finding("V4", os.path.join(mio.MEMORY_REL, name), seal.get("_line"),
+                                        "%s: the seal names %s entries (%s), the package has %d" % (
+                                            key, seal.get("entries"), (seal.get("digest") or "")[:19], len(own)),
+                                        "'state.py memory export %s' re-exports it" % seal.get("task")))
+    for name, size in sorted(sizes.items()):
+        if size > 2 * max_bytes:
+            findings.append(Finding("V8", os.path.join(mio.MEMORY_REL, name), None,
+                                    "%d bytes, over twice package_max_bytes (%d)" % (size, max_bytes),
+                                    "a new batch opens on the next close; 'state.py memory pack' folds old ones"))
+        elif size > max_bytes:
+            findings.append(Finding("V8-warn", os.path.join(mio.MEMORY_REL, name), None,
+                                    "%d bytes, over package_max_bytes (%d)" % (size, max_bytes),
+                                    "nothing to do now; the next close opens a new batch"))
+    del ref_name
+    return findings
+
+
+def _belongs(items, rid, seal):
+    """Entries of a key that came before its seal (seq below the seal's)."""
+    for _, e in items:
+        if e["rid"] == rid:
+            return (e.get("seq") or 0) < (seal.get("seq") or 0)
+    return False
+
+
+def check_journals(read, paths, packages, cleanup_on=False):
+    """V5 (and V7 with cleanup) against the committed journals."""
+    findings = []
+    seals = mpkg.seals_by_key(packages)
+    sealed_tasks = {k.rsplit("#", 1)[0] for k in seals}
+    srcs = collections.defaultdict(set)
+    for _, entries, _ in packages.values():
+        for e in entries:
+            for s in e.get("src") or []:
+                srcs[mf.key_of(e)].add(s)
+    journals = sorted(p for p in paths if re.match(r"^\.ai/reports/[^/]+/events\.jsonl$", p))
+    for path in journals:
+        task = path.split("/")[2]
+        data = read(path) or b""
+        if b'"task_closed"' not in data:
+            continue
+        if not (mf.NEW_ID_RE.match(task) or task in sealed_tasks):
+            continue                       # an unmigrated legacy task: 'memory status' lists it
+        events = mc.parse_journal(data)
+        instances = mc.split_instances(events)
+        for inst, lines in enumerate(instances, 1):
+            key = "%s#%d" % (task, inst)
+            closed = any(e and e.get("event") == "task_closed" for _, e in lines)
+            if not closed and inst == len(instances):
+                continue
+            if key not in seals:
+                findings.append(Finding("V5", path, None, "%s is closed but has no seal" % key,
+                                        "state.py memory export %s" % task))
+                continue
+            missing = [n for n in kept_lines(lines) if "events.jsonl:%d" % n not in srcs[key]]
+            if missing:
+                findings.append(Finding("V5", path, missing[0], "%s: %d kept line(s) are no entry's src" % (
+                    key, len(missing)), "state.py memory export %s" % task))
+        if cleanup_on and task in sealed_tasks:
+            findings.append(Finding("V7", "/".join(path.split("/")[:3]) + "/", None,
+                                    "cleanup is on and %s is sealed" % task, "state.py memory cleanup %s" % task))
+    return findings
+
+
+def verify(root, scope="all", ids=None):
+    """Findings for --all or ids over the working tree; [] is green."""
+    cfg = mcfg.load_config(root)
+    packages = mpkg.load_packages(root)
+    sizes = {n: os.path.getsize(os.path.join(mio.memory_dir(root), n)) for n in packages}
+    findings = check_packages(packages, cfg.package_max_bytes, sizes)
+    reports = os.path.join(root, ".ai", "reports")
+    paths = []
+    for name in sorted(os.listdir(reports)) if os.path.isdir(reports) else []:
+        if ids and name not in ids:
+            continue
+        if os.path.exists(os.path.join(reports, name, "events.jsonl")):
+            paths.append(".ai/reports/%s/events.jsonl" % name)
+    findings += check_journals(lambda rel: mio.read_bytes(os.path.join(root, rel)), paths, packages, False)
+    if ids:
+        findings = [f for f in findings if any(i in (f.path or "") or i in f.what for i in ids)]
+    del scope
+    return findings
+
+
+def verify_fresh_clone(root):
+    """§D6: a local clone of HEAD, rebuilt from packages alone, shows every
+    sealed key as this clone does."""
+    import memory_store  # pylint: disable=import-outside-toplevel
+    findings = []
+    here = memory_store.FileHistory(root, mcfg.load_config(root))
+    keys = sorted({mf.key_of(e) for _, entries, _ in mpkg.load_packages(root).values() for e in entries
+                   if e.get("kind") == "task"})
+    with tempfile.TemporaryDirectory(prefix="ai-memory-clone-") as tmp:
+        clone = os.path.join(tmp, "clone")
+        code, _, err = mio.git(root, "clone", "-q", "--no-hardlinks", root, clone)
+        if code != 0:
+            raise mio.MemoryError_("git clone failed: %s" % err.strip(), 3)
+        there = memory_store.FileHistory(clone, mcfg.load_config(clone))
+        for key in keys:
+            a = "\n".join(mf.render_task_md(here.entries(key)))
+            b = "\n".join(mf.render_task_md(there.entries(key)))
+            if a != b:
+                findings.append(Finding("fresh-clone", key, None, "renders differently in a fresh clone",
+                                        "commit .ai/memory/ (the clone sees HEAD only)"))
+    return findings
+
+
+def format_finding(f, ref=None):
+    where = f.path + (":%s" % f.line if f.line else "")
+    return "%s%s: %s: %s — fix: %s" % ("%s: " % ref if ref else "", f.check, where, f.what, f.fix)
+
+
+# ------------------------------------------------------------------ git trees (§D10)
+class GitTreeReader:
+    """Blobs of one commit, through one `git cat-file --batch`."""
+
+    def __init__(self, repo, sha):
+        self.repo, self.sha = repo, sha
+        self._cache = {}
+        self._paths = None
+
+    def paths(self):
+        if self._paths is None:
+            code, out, _ = mio.git(self.repo, "ls-tree", "-r", "-z", "--name-only", self.sha, binary=True)
+            self._paths = [p.decode("utf-8", "replace") for p in out.split(b"\0") if p] if code == 0 else []
+        return self._paths
+
+    def read_many(self, rels):
+        wanted = [r for r in rels if r not in self._cache]
+        if wanted:
+            stdin = "".join("%s:%s\n" % (self.sha, r) for r in wanted).encode("utf-8")
+            done = subprocess.run(["git", "-C", self.repo, "cat-file", "--batch"], input=stdin,
+                                  capture_output=True, check=False)
+            data, pos = done.stdout, 0
+            for rel in wanted:
+                end = data.find(b"\n", pos)
+                head = data[pos:end].split(b" ")
+                pos = end + 1
+                if len(head) == 2 and head[1] == b"missing" or len(head) < 3:
+                    self._cache[rel] = None
+                    continue
+                size = int(head[2])
+                self._cache[rel] = data[pos:pos + size]
+                pos += size + 1
+        return {r: self._cache.get(r) for r in rels}
+
+    def read(self, rel):
+        return self.read_many([rel])[rel]
+
+    def listdir(self, rel):
+        prefix = rel.rstrip("/") + "/"
+        return sorted({p[len(prefix):].split("/")[0] for p in self.paths() if p.startswith(prefix)})
+
+
+def rev(repo, name):
+    code, out, _ = mio.git(repo, "rev-parse", "--verify", "-q", name + "^{commit}")
+    return out.strip() if code == 0 and out.strip() else None
+
+
+def policy_at(repo, sha):
+    code, out, _ = mio.git(repo, "show", "%s:%s" % (sha, mio.POLICY_REL.replace(os.sep, "/")))
+    if code != 0:
+        return None
+    try:
+        data = json.loads(out)
+    except ValueError:
+        return {"mode": "invalid"}
+    return data if isinstance(data, dict) else {"mode": "invalid"}
+
+
+def validate_range(repo, old, new, local=False):
+    """(findings, stats) for the commits O..T (§D10). O may be None: then only
+    the structure of T is checked."""
+    started = time.time()
+    policy = policy_at(repo, new)
+    if policy is None or policy.get("mode", "files") == "files":
+        return None, {}
+    if policy.get("mode") == "invalid":
+        return [Finding("V1", mio.POLICY_REL, None, "memory.json at %s is not valid JSON" % new[:9],
+                        "fix the file, or 'state.py memory disable'")], {}
+    max_bytes = int(policy.get("package_max_bytes", mcfg.DEFAULTS["package_max_bytes"]))
+    tree = GitTreeReader(repo, new)
+    paths = tree.paths()
+    pkg_paths = [p for p in paths if p.startswith(".ai/memory/") and p.endswith(".jsonl")]
+    blobs = tree.read_many(pkg_paths)
+    packages = {p.split("/", 2)[2]: mf.parse_package(blobs[p] or b"", p.split("/", 2)[2]) for p in pkg_paths}
+    sizes = {p.split("/", 2)[2]: len(blobs[p] or b"") for p in pkg_paths}
+    changed, added = None, []
+    findings = []
+    if old:
+        code, out, _ = mio.git(repo, "diff", "--name-status", "--no-renames", old, new, "--", ".ai")
+        rows = [line.split("\t") for line in out.splitlines() if "\t" in line] if code == 0 else []
+        changed = {r[1].split("/", 2)[2] for r in rows if r[1].startswith(".ai/memory/")}
+        added = [r[1] for r in rows if r[0].startswith("A")]
+        before = GitTreeReader(repo, old)
+        old_pkgs = [p for p in before.paths() if p.startswith(".ai/memory/") and p.endswith(".jsonl")]
+        old_blobs = before.read_many(old_pkgs)
+        old_rids = set()
+        for p in old_pkgs:
+            _, entries, _ = mf.parse_package(old_blobs[p] or b"")
+            old_rids |= {e["rid"] for e in entries}
+        new_rids = mpkg.all_rids(packages)
+        redacted = {e.get("target") for _, entries, _ in packages.values() for e in entries
+                    if e.get("kind") == "redaction"}
+        lost = sorted(old_rids - new_rids - redacted)
+        if lost:
+            findings.append(Finding("V2", ".ai/memory/", None, "%d record(s) of %s are gone (%s…)" % (
+                len(lost), old[:9], lost[0]), "git checkout %s -- .ai/memory/ and merge the lines back" % old[:9]))
+    findings = check_packages(packages, max_bytes, sizes, changed) + findings
+    journals = [p for p in paths if re.match(r"^\.ai/reports/[^/]+/events\.jsonl$", p)]
+    journal_blobs = tree.read_many(journals)   # one cat-file --batch for every journal (§D10)
+    findings += check_journals(journal_blobs.get, journals, packages, bool(policy.get("cleanup")))
+    for path in added:
+        if path.startswith(".ai/reports/") and path.endswith(".log"):
+            findings.append(Finding("V6", path, None, "a log is committed under .ai/reports/",
+                                    "git rm --cached %s (logs live in .ai/state/logs/)" % path))
+    for path in paths:
+        # The index lives under .ai/local/; a project's own SQLite file elsewhere is not ours.
+        if path.startswith(".ai/local/") or path.startswith(".ai/state/logs/") or \
+                (path.startswith(".ai/") and ".sqlite3" in path):
+            findings.append(Finding("V6", path, None, "local data is committed",
+                                    "git rm --cached %s (.ai/local/ and .ai/state/logs/ stay local)" % path))
+    if local:
+        outbox = mio.local_path(repo, "outbox")
+        if os.path.isdir(outbox) and any(n.endswith(".jsonl") for n in os.listdir(outbox)):
+            findings.append(Finding("V9", os.path.join(mio.LOCAL_REL, "outbox"), None, "an export is pending",
+                                    "state.py memory export --pending, commit, push again"))
+    stats = {"packages": len(packages), "tasks": len(journals), "ms": int((time.time() - started) * 1000)}
+    return findings, stats

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

@@ -34,6 +34,7 @@ def memory_parsers(sub):
     m = msub.add_parser("status"); m.add_argument("--json", action="store_true")
     m = msub.add_parser("enable"); m.add_argument("--author"); m.add_argument("--period", choices=["month", "quarter", "year"])
     m.add_argument("--index", choices=["none", "sqlite"])
+    m.add_argument("--share", choices=["git", "local"])
     msub.add_parser("disable")
     m = msub.add_parser("export"); m.add_argument("ids", nargs="*"); m.add_argument("--pending", action="store_true")
     m = msub.add_parser("verify"); m.add_argument("ids", nargs="*"); m.add_argument("--all", action="store_true")

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

@@ -165,7 +165,7 @@ def memory_after_close(root, task_id):
     if not os.path.exists(os.path.join(root, ".ai", "policies", "memory.json")):
         return
     try:
-        import memory_sync                # pylint: disable=import-outside-toplevel
+        import memory_export              # pylint: disable=import-outside-toplevel
     except ImportError:
         return
-    memory_sync.after_close(root, task_id)
+    memory_export.after_close(root, task_id)

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

@@ -1,7 +1,7 @@
 """dialog: the human decision dialog and the authority that tells a human from the agent -- decisions, consent labels, picks, the approval offer.
 
-shell: human_route, human_turn, refuse_approval, DIALOG_PICK, dialog_policy, dialog_tool_verified, dialog_on, open_decision, print_dialog, offer_decision, settle_decision, settle_written, prune_decisions, mirror_ledger, sync_dialog, dialog_pick, valid_decisions, retire_approvals, task_facts, audit_pick, approve_command, offer_approval
-core: DIALOG_TOOL, SESSION_ENV, DECISIONS_MAX, QUESTION_MAX, HEADER_MAX, JSON_DEPTH_MAX, json_loads_capped, dialog_questions, option_description, part_question, dialog_payload, MIRROR, pick_data
+shell: human_route, human_turn, open_approval_id, refuse_approval, DIALOG_PICK, dialog_policy, dialog_tool_verified, dialog_on, open_decision, print_dialog, offer_decision, settle_decision, settle_written, prune_decisions, mirror_ledger, sync_dialog, dialog_pick, valid_decisions, retire_approvals, task_facts, audit_pick, approve_command, offer_approval
+core: DIALOG_TOOL, SESSION_ENV, DECISIONS_MAX, QUESTION_MAX, HEADER_MAX, JSON_DEPTH_MAX, json_loads_capped, dialog_questions, option_description, human_refusal, part_question, dialog_payload, MIRROR, pick_data
 """
 import json
 import os
@@ -77,16 +77,29 @@ def human_turn(root, state):
     return True, ""
 
 
+def open_approval_id(root, rt=rr_runtime.Runtime()):
+    """The id of the open approval decision, or None with the dialog off or none open: the refusals name the dialog then (R7)."""
+    if not dialog_on(root, runtime=rt.name):
+        return None
+    try:
+        with open(fs.decision_path(root), encoding="utf-8") as fh:
+            return next((d["id"] for d in json.load(fh)["open"] if d.get("kind") == "approval"), None)
+    except (OSError, ValueError, KeyError, TypeError, AttributeError, RecursionError):
+        return None                       # an unreadable decision.json names no decision: the refusal stays today's
+
+
 def refuse_approval(root, state, gate_id, by, why):
     # Quoted: this project's own path has a space in it, and the command the
     # refusal prints is the only route a human without the flag has.
-    fs.die("APPROVAL_REFUSED — approval happens outside the agent. Run in your own terminal:\n"
-        "  python3 %s --root %s approve --by %s\n"
+    cmd = "python3 %s --root %s approve --by %s" % (shlex.quote(fs.ENTRY), shlex.quote(root), shlex.quote(by))
+    asked = None if state["mode"] == "full_irreversible" else human_refusal("'state.py approve'", cmd, why, open_approval_id(root))
+    questions = os.path.relpath(fs.questions_path(root, state, None), root)
+    if asked:
+        fs.die("%s Or set [Answer]: A on %s in %s and tell the session to sync." % (asked, gate_id, questions), 5)
+    fs.die("APPROVAL_REFUSED — approval happens outside the agent. Run in your own terminal:\n  %s\n"
         "or set [Answer]: A on %s in %s and tell the session to sync. An unattended run exports "
         "AI_UNATTENDED=1 in the launcher's environment; the journal then records the approval as "
-        "unattended.\nRefused because %s."
-        % (shlex.quote(fs.ENTRY), shlex.quote(root), shlex.quote(by), gate_id,
-           os.path.relpath(fs.questions_path(root, state, None), root), why), 5)
+        "unattended.\nRefused because %s." % (cmd, gate_id, questions, why), 5)
 
 
 # ---------------------------------------------- the dialog (R36, step 7c)
@@ -254,6 +267,9 @@ def open_decision(root, state, kind, header, question, options, opened_by, multi
         "question": (question or "").strip()[:QUESTION_MAX],
         "options": [dict(option, n=n) for n, option in enumerate(options, 1)],
     }, **extra)
+    for option in decision["options"]:
+        if option["kind"] == "command" and not option.get("description"):
+            option["description"] = labels.describe(shlex.split(option["label"]))
     data["open"].append(decision)
     rr_ledger.write_decisions(root, data)
     if state and state.get("task_id"):
@@ -270,6 +286,15 @@ def option_description(option):
     return "the session runs exactly this, once" if option["kind"] == "command" else "nothing runs"
 
 
+def human_refusal(what, cmd, why, decision):
+    """The refusal text that names the dialog first, or None without a decision: the site prints its own text then (R7)."""
+    if not decision:
+        return None
+    return ("APPROVAL_REFUSED — %s is the human's. Ask them in the dialog: send DIALOG_PENDING %s (printed above), "
+            "then run the command they pick, verbatim, once. Or they run, in their own terminal:\n  %s\n"
+            "Refused because %s." % (what, decision, cmd, why))
+
+
 def part_question(question, i, n):
     """The question text of part i of n: a split decision's parts must differ,
     Claude keys tool_response.answers by text; cut so the whole fits QUESTION_MAX."""

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

@@ -1,12 +1,13 @@
 """dialog_cmd: the consent and decision commands -- decision open/show/settle/fallback, the pick applied, and the read-only consent view.
 
-core: SETTLE_EFFECT, SETUP_VALUES, SETUP_VALUE_MAX, SETUP_SPEC_MAX, setup_option_why, setup_decision_why, setup_spec_why
-shell: cmd_decision, decision_open, read_setup_spec, setup_command_why, check_setup_labels, setup_open, decision_settle, apply_choice, cmd_consent
+core: SETTLE_EFFECT, INSTALL_RE, SETUP_VALUES, SETUP_VALUE_MAX, SETUP_SPEC_MAX, setup_option_why, setup_decision_why, setup_spec_why
+shell: cmd_decision, decision_open, install_open, read_setup_spec, setup_command_why, check_setup_labels, setup_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 re
 import shlex
 import sys
 
@@ -22,6 +23,7 @@ SETUP_VALUES = {"memory": ("off", "keep"), "runtime": ("auto", "claude", "codex"
                 "survey": ("light", "full", "keep"), "verify": ("", "other", "keep", "edit")}
 SETUP_VALUE_MAX = 200
 SETUP_SPEC_MAX = 262144
+INSTALL_RE = re.compile(r"^npx riskrails@(\d+\.\d+\.\d+) --yes$")   # the one command an install decision offers
 
 
 def cmd_decision(args, root, rt=rr_runtime.Runtime()):
@@ -61,13 +63,17 @@ def cmd_decision(args, root, rt=rr_runtime.Runtime()):
 
 
 def decision_open(args, root, rt=rr_runtime.Runtime()):
-    """The openers the model may call: --kind commit (git commit and git push) and --kind setup (the /rr-setup
-    questions: choices that set a value, and this project's `memory enable`); nothing else."""
+    """The openers the model may call: --kind commit (git commit and git push), --kind setup (the /rr-setup
+    questions: choices that set a value, and this project's `memory enable`) and --kind install (one
+    `npx riskrails@X.Y.Z --yes`); nothing else."""
     if args.kind == "setup":
         setup_open(args, root, rt=rt)
         return
+    if args.kind == "install":
+        install_open(args, root, rt=rt)
+        return
     if args.kind != "commit":
-        fs.die("decision open takes --kind commit or --kind setup; every other decision is opened by the "
+        fs.die("decision open takes --kind commit or --kind setup (or --kind install, one npx riskrails@X.Y.Z --yes); every other decision is opened by the "
             "command that needs it (close, ask, the budgets, start --mode)")
     if args.spec is not None:
         fs.die("decision open --kind commit takes --command, not --spec", 2)
@@ -97,6 +103,33 @@ def decision_open(args, root, rt=rr_runtime.Runtime()):
     dialog.print_dialog([decision], rt=rt)
 
 
+def install_open(args, root, rt=rr_runtime.Runtime()):
+    """decision open --kind install --command "npx riskrails@X.Y.Z --yes": the update offered in the dialog (R4).
+    The command is exactly that, once; no task may be in flight, because the install rewrites the hooks."""
+    match = INSTALL_RE.match(args.commands[0]) if len(args.commands) == 1 else None
+    if args.spec is not None or not match:
+        fs.die("CONSENT_LABEL_INVALID — decision open --kind install takes one --command, exactly "
+               "\"npx riskrails@X.Y.Z --yes\" (X.Y.Z a plain version); found: %s"
+               % (" | ".join(args.commands)[:120] or "none"), 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 command; the human runs it outside the agent")
+    state = task.in_flight(root, rt=rt)
+    if state:
+        fs.die("INSTALL_DURING_TASK — an install rewrites the hooks and skills this task runs on, and task %s is in "
+               "flight; finish or abandon it, then open the install decision again" % state["task_id"], 6)
+    runtime = rr_runtime.own_runtime(runtime=rt.name)
+    have = profile.read_profile(runtime, rt=rt).get("plugin_version") or "unknown"
+    question = ("Install RiskRails %s (installed %s)? It rewrites the hooks, skills and settings under %s; "
+                "restart the session afterwards." % (match.group(1), have, rr_runtime.runtime_home(runtime)))
+    options = [{"kind": "choice", "effect": "defer", "label": "Not now — keep %s" % have},
+               {"kind": "command", "label": args.commands[0]}]
+    decision, why = dialog.open_decision(root, None, "install", "Install", question, options, "decision open", rt=rt)
+    if decision is None:
+        fs.die(why, 6)
+    dialog.print_dialog([decision], rt=rt)
+
+
 def read_setup_spec(path):
     """--spec FILE|- as JSON: a spec that cannot be read, is longer than SETUP_SPEC_MAX characters, is not JSON or
     nests deeper than the dialog's own cap is a bad spec (exit 2)."""

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

@@ -5,8 +5,9 @@ shell: guard_pending, request_gate, close_gate
 """
 import os
 import re
+import shlex
 
-from rr_state import fs
+from rr_state import dialog, 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
@@ -36,12 +37,17 @@ def guard_pending(root, command, rt=rr_runtime.Runtime()):
     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.
+        gates = ", ".join(q["id"] for q in blocking if q["kind"] == "G")
+        cmd = "python3 %s --root %s approve --by \"<name>\"" % (shlex.quote(fs.ENTRY), shlex.quote(root))
+        asked = dialog.human_refusal("the approval gate", cmd, "approve and reject are the human's, and %s is open" % gates,
+                                     dialog.open_approval_id(root, rt=rt))
+        if asked:
+            fs.die("QUESTIONS_PENDING — %d unanswered in %s: %s. Stage stays at %s.\n%s"
+                % (len(blocking), os.path.relpath(path, root), ", ".join(ids), state.get("current_stage"), asked), 4)
         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)
+            % (len(blocking), os.path.relpath(path, root), ", ".join(ids), gates, 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),

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

@@ -1,7 +1,7 @@
 """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
+core: BATCH_ON, DESCRIPTIONS, describe, 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
@@ -16,6 +16,17 @@ INTERPRETER_RE = re.compile(r"^python3?$")   # a bare name: a path could be any
 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.+-]+$")
+BATCH_ON = {"--by": True, "--why": False}   # `batch on` options, each at most once; True = required. hooks/guard/dialog.py keeps the same table
+DESCRIPTIONS = {   # what each offered command does, in words a person without a terminal reads
+    ("approve",): "Approve the task's result as it is now, so it can be closed.",
+    ("reject",): "Reject the task's result and send it back for changes.",
+    ("profile", "set"): "Change the plan profile, which sets the models the work runs on.",
+    ("verify",): "Run the test suite once more, past the number of runs this task allows.",
+    ("review",): "Record the next review verdict as yours, past the review passes this task allows.",
+    ("start",): "Start the task in the mode the command names instead of the one its weight gives.",
+    ("memory", "enable"): "Turn on the project's compact record of tasks.",
+    ("batch", "on"): "Turn the batch loop on for this task: more test runs and review passes before you are asked.",
+}
 
 
 def label_argv(label):
@@ -44,10 +55,15 @@ def subcommand(argv):
 
 def state_label_ok(argv):
     """approve | reject | profile set | verify --by | review --by | start --mode … --by |
-    memory enable [--author S] [--period month|quarter|year] [--index none|sqlite]: each option at most
+    batch on --by S [--why S] | memory enable [--author S] [--period month|quarter|year] [--index none|sqlite]: each option at most
     once, as two words, in any order, and no other memory verb. hooks/guard/dialog.py keeps the same
     rule; tests/test_dialog_contract.py pins the two equal."""
     rest = subcommand(argv)
+    if rest[:2] == ["batch", "on"]:
+        names, values = rest[2::2], rest[3::2]
+        return (len(names) == len(values) == len(set(names)) and set(names) <= set(BATCH_ON)
+                and all(n in names for n, need in BATCH_ON.items() if need)
+                and all(v[:1] not in ("", "-") for v in values))
     if rest[:1] in (["approve"], ["reject"]) or rest[:2] == ["profile", "set"]:
         return True
     if rest[:1] in (["verify"], ["review"]):
@@ -89,8 +105,8 @@ def validate_label(label):
             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|memory enable [--author S] "
-            "[--period P] [--index none|sqlite], or npx riskrails@<v> … --yes")
+            "profile set|verify --by|review --by|start --mode --by|batch on --by S [--why S]|memory enable "
+            "[--author S] [--period P] [--index none|sqlite], or npx riskrails@<v> … --yes")
 
 
 def human_name(root):
@@ -109,3 +125,16 @@ def state_label(root, argv):
 def subcommand_prefix(argv):
     """The global options in front of the subcommand."""
     return list(argv)[:len(argv) - len(subcommand(argv))]
+
+
+def describe(argv):
+    """One plain-words line for the command a label runs; argv is the label split into words."""
+    if argv[:2] == ["git", "commit"]:
+        return "Save the finished work as a commit in git."
+    if argv[:2] == ["git", "push"]:
+        return "Send the committed work to the remote repository."
+    if argv[:1] == ["npx"]:
+        return "Install this RiskRails version into your runtime's home; start a new session afterwards."
+    script = label_argv(shlex.join(argv))
+    rest = subcommand(script[1]) if script else []
+    return DESCRIPTIONS.get(tuple(rest[:2])) or DESCRIPTIONS.get(tuple(rest[:1])) or "Run a command you have read."