riskrails 4.2.0 → 4.3.0

package/hooks/guard/dialog.py

@@ -45,6 +45,7 @@ INTERPRETER_RE = re.compile(r"^python3?$")
 INTERPRETER_FLAG_RE = re.compile(r"^-[IS]+$")
 PUSH_REF_RE = re.compile(r"^[A-Za-z0-9._/-]+$")
 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. rr_state/labels.py keeps the same table
 TS = "%Y-%m-%dT%H:%M:%SZ"
 
 # hooks/guard/dialog.py -> the plugin root; the Stop reminder names its
@@ -217,12 +218,12 @@ def validate_label(label):
     if state_label_ok(tokens):
         return None
     return ("a label starts with git commit, git push, a human-only state.py command (approve, reject, "
-            "profile set, verify/review/start --by, memory enable) or npx riskrails@<v>")
+            "profile set, verify/review/start --by, batch on --by, memory enable) or npx riskrails@<v>")
 
 
 def state_label_ok(tokens):
     """python3 [-I|-S…] <…/state.py> approve|reject|profile set|verify --by|
-    review --by|start --mode … --by|memory enable [--author S] [--period month|quarter|year]
+    review --by|start --mode … --by|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. rr_state/labels.py keeps the same rule; tests/test_dialog_contract.py pins the
     two equal."""
@@ -236,6 +237,11 @@ def state_label_ok(tokens):
     rest = tokens[i + 1:]
     while rest[:1] in (["--root"], ["--runtime"]) and len(rest) >= 2:
         rest = rest[2:]
+    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"]):
@@ -589,6 +595,10 @@ def is_git_label(label):
     return (label or "").split()[:1] == ["git"]
 
 
+def is_npx_label(label):
+    return (label or "").split()[:1] == ["npx"]
+
+
 def used_note(pick):
     """What a deny after the gate spent a git pick adds (review focus 1)."""
     return ("\n\nThe pick %s was used by this call and is spent; the command did not run. To ask the human "

package/hooks/guard/ere.py

@@ -528,11 +528,18 @@ class _Found:                               # pylint: disable=too-few-public-met
 
 
 class Compiled:
-    """One pattern in one mode. `rx` is None when the pattern is invalid."""
-    __slots__ = ("rx", "required", "anchored", "dfa")
+    """One pattern in one mode. `rx` is None when the pattern is invalid.
+
+    The pattern is parsed here (parse errors are caught here), but the regex
+    and the DFA are built on the first read of `rx`: `search` runs the cheap
+    `required` prefilter first, so a subject it rejects never pays for
+    `re.compile` (a fresh process holds ~34 patterns, most never get past it).
+    """
+    __slots__ = ("_rx", "_pending", "required", "anchored", "dfa")
 
     def __init__(self, pattern, mode, capture):
-        self.rx = None
+        self._rx = None
+        self._pending = None                # (tree, mode, capture) until built
         self.required = None
         self.anchored = False
         self.dfa = None
@@ -546,18 +553,30 @@ class Compiled:
                 tree = _strip_leading(tree)
             elif capture:
                 self.anchored = _starts_with_dotstar(tree)
-            flags = re.ASCII if mode == "b" else 0
-            self.rx = re.compile(_emit(tree, mode), flags)
-            if not capture and _nested(tree) and _dfa_ok(tree):
-                self.dfa = _Dfa(tree, mode)
+            self._pending = (tree, mode, capture)
         except (EreError, re.error, RecursionError, OverflowError):
-            self.rx = None
+            self._pending = None
+
+    @property
+    def rx(self):
+        if self._pending is not None:
+            tree, mode, capture = self._pending
+            self._pending = None
+            try:
+                flags = re.ASCII if mode == "b" else 0
+                self._rx = re.compile(_emit(tree, mode), flags)
+                if not capture and _nested(tree) and _dfa_ok(tree):
+                    self.dfa = _Dfa(tree, mode)
+            except (EreError, re.error, RecursionError, OverflowError):
+                self._rx = None
+                self.dfa = None
+        return self._rx
 
     def search(self, subject):
-        if self.rx is None:
-            return None
         if self.required is not None and not any(r in subject for r in self.required):
             return None
+        if self.rx is None:
+            return None
         if self.dfa is not None:
             return _Found() if self.dfa.search(subject) else None
         return self.rx.match(subject) if self.anchored else self.rx.search(subject)

package/hooks/guard/git.py

@@ -285,7 +285,8 @@ class GitGuard:
                     return
         except Exception:                   # pylint: disable=broad-exception-caught
             pass
-        raise Deny(text_to_b("CONSENT_REQUIRED \u2014 no live pick of this session is this command.") + WHY_CONSENT)
+        raise Deny(text_to_b("CONSENT_REQUIRED \u2014 no live pick of this session is this command. Ask the human in "
+                                 "the dialog; or they run it in their own terminal.") + WHY_CONSENT)
 
     def _drop_status(self, path):
         """`[ "${#path}" -lt 3 ] || path="${path:3}"`, counted in the locale's characters."""

package/hooks/guard/paths_base.py

@@ -42,6 +42,13 @@ WHY_APPROVE = T(
     "and tells the session to run state.py questions --sync. An unattended run\n"
     "exports AI_UNATTENDED=1 in the launcher's environment, and the journal then\n"
     "records the approval as unattended for ever. See .ai/policies/safety.md.")
+WHY_APPROVE_DIALOG = T(
+    "\n\nApproval is the human's. Ask them in the dialog: when the task's gate is open, state.py has opened the\n"
+    "approval decision; send it ('state.py decision show'), then run the command they pick, verbatim, once.\n"
+    "Or they run, in their own terminal:\n"
+    "  python3 <plugin>/skills/ai-task/state.py --root . approve --by \"<name>\"\n"
+    "An unattended run exports AI_UNATTENDED=1 in the launcher's environment, and the journal then\n"
+    "records the approval as unattended for ever. See .ai/policies/safety.md.")
 WHY_WORK_CAP = T(
     "This command names more paths than the guard can check within its timeout; split it into "
     "smaller commands, or pass the list through a file and xargs.")

package/hooks/guard/paths_bash.py

@@ -7,8 +7,8 @@ Moved from paths.py in WP5 (small-oop-modules), unchanged.
 import re
 from guard.common import (Allow, Deny, abs_path, chomp_all, ere_escape, exists, herestring_lines,
                           real_path, realpath_strict, strip1)
-from guard.paths_base import (SEGMENT, T, WHY_APPROVE, WHY_HUMAN, WHY_PICK, WHY_PROTECTED,
-                              WHY_SENSITIVE, WHY_TASK)
+from guard.paths_base import (SEGMENT, T, WHY_APPROVE, WHY_APPROVE_DIALOG, WHY_HUMAN, WHY_PICK,
+                              WHY_PROTECTED, WHY_SENSITIVE, WHY_TASK)
 from guard.paths_shell import shell_segments
 from guard.paths_human import (APPROVE_RE, DIALOG_GATE_RE, HUMAN_BY_RE, PROFILE_SET_RE,
                                START_LIGHT_RE)
@@ -56,7 +56,7 @@ def check_bash(self, unattended):           # pylint: disable=too-many-branches,
                    "('state.py decision settle --id D<n> --pick <n>'). See .ai/policies/safety.md.")
     on, picked = self.dialog_consent(cmd)
     if m.ere_match(APPROVE_RE, cmd_joined) and not unattended and self.task_in_flight() and not picked:
-        raise Deny("Refusing 'state.py approve' from an agent session." + WHY_APPROVE)
+        raise Deny("Refusing 'state.py approve' from an agent session." + (WHY_APPROVE_DIALOG if on else WHY_APPROVE))
     if on and not picked and not unattended and m.ere_match(PROFILE_SET_RE, cmd_joined):
         raise Deny("Refusing 'state.py profile set' from an agent session." + WHY_PICK)
     if not picked and not unattended and m.ere_match(HUMAN_BY_RE, cmd_joined):

package/hooks/runtime-gate.py

@@ -1160,6 +1160,90 @@ def git_branch(cwd):
     return ""
 
 
+def read_json_file(path):
+    """The parsed JSON file, or None when it is missing, unreadable or not JSON."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return json.load(fh)
+    except (OSError, ValueError, RecursionError):
+        return None
+
+
+def still_waiting(decisions, path):
+    """The decisions guard/dialog.py `pending` keeps, from the consent ledger at path: not
+    settled, and not every command pick of the latest dialog call used. A missing or
+    torn ledger leaves them all."""
+    used, settled, rounds = set(), set(), {}
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for raw in fh:
+                try:
+                    entry = json.loads(raw)
+                except (ValueError, RecursionError):
+                    continue
+                kind = entry.get("type") if isinstance(entry, dict) and entry.get("v") == 1 else None
+                if kind == "use":
+                    used.add(entry.get("id"))
+                elif kind == "settle":
+                    settled.add(entry.get("decision"))
+                elif kind == "pick" and isinstance(entry.get("order"), int) and not isinstance(entry["order"], bool):
+                    call, chain = rounds.get(entry.get("decision"), (None, []))
+                    if chain and call == entry.get("tool_use_id"):
+                        chain.append(entry)
+                    else:
+                        rounds[entry.get("decision")] = (entry.get("tool_use_id"), [entry])
+    except OSError:
+        return decisions
+    out = []
+    for decision in decisions:
+        options = decision.get("options")
+        commands = {o.get("n") for o in options if isinstance(o, dict) and o.get("kind") == "command"} \
+            if isinstance(options, list) else set()
+        picks = [p for p in rounds.get(decision.get("id"), (None, []))[1] if p.get("option") in commands]
+        if decision.get("id") not in settled and not (picks and all(p.get("id") in used for p in picks)):
+            out.append(decision)
+    return out
+
+
+def waiting_ids(decisions, state):
+    """The ids that wait on the human, `D3 D4 Q2 G1`: at most three per kind, then `+n`."""
+    state = state or {}
+    asked, approval = state.get("questions"), state.get("human_approval")
+    questions = asked.get("pending") if isinstance(asked, dict) else None
+    approval = approval if isinstance(approval, dict) else {}
+    kinds = ([d.get("id") for d in decisions],
+             [q for q in questions if not str(q).startswith("G")] if isinstance(questions, list) else [],
+             [approval["gate_id"]] if approval.get("requested_at") and approval.get("gate_id") else [])
+    out = []
+    for ids in kinds:
+        ids = [str(i) for i in ids if i]
+        out += ids[:3] + (["+%d" % (len(ids) - 3)] if len(ids) > 3 else [])
+    return " ".join(out)
+
+
+def task_segment(cwd):
+    """`<task> · <mode> · <stage> waiting on you: D3 Q2`, or `riskrails · waiting on you: D3`
+    with no task, read from the .ai/state files at or above cwd; "" when nothing is in flight
+    or waits."""
+    here = os.path.abspath(cwd)
+    while not os.path.isdir(os.path.join(here, ".ai", "state")):
+        parent = os.path.dirname(here)
+        if parent == here:
+            return ""
+        here = parent
+    folder = os.path.join(here, ".ai", "state")
+    state = read_json_file(os.path.join(folder, "state.json"))
+    state = state if isinstance(state, dict) and state.get("task_id") else None
+    decisions = read_json_file(os.path.join(folder, "decision.json"))
+    opened = decisions.get("open") if isinstance(decisions, dict) else None
+    opened = [d for d in opened if isinstance(d, dict)] if isinstance(opened, list) else []
+    waiting = waiting_ids(still_waiting(opened, os.path.join(folder, "consent.jsonl")) if opened else [], state)
+    if not state:
+        return "riskrails · waiting on you: " + waiting if waiting else ""
+    return " · ".join(str(state.get(k)) for k in ("task_id", "mode", "stage")) \
+        + (" waiting on you: " + waiting if waiting else "")
+
+
 def second_line(payload):
     """`user@host:cwd | branch | 5h:12% (↻14:00) 7d:41% (↻Fri 03:04) | $1.23`, the
     colours of a Debian colour PS1; each part after the prompt is skipped when its
@@ -1180,6 +1264,9 @@ def second_line(payload):
     branch = git_branch(cwd) if os.path.isdir(cwd) else ""
     if branch:
         out += "%s\033[35m%s%s" % (SL_SEP, branch, SL_RESET)
+    segment = task_segment(cwd)
+    if segment:
+        out += "%s\033[36m%s%s" % (SL_SEP, segment, SL_RESET)
     limits = payload.get("rate_limits")
     limits = limits if isinstance(limits, dict) else {}
     parts = []

package/hooks/update_notice.py

@@ -80,8 +80,9 @@ def spawn_refresh(path):
         pass
 
 
-def notice(runtime, home, plugin_root, now):
-    """(systemMessage, additionalContext) when the cache knows a newer release, else ("", "")."""
+def notice(runtime, home, plugin_root, now, dialog=False):
+    """(systemMessage, additionalContext) when the cache knows a newer release, else ("", "").
+    dialog: the caller's answer to "is the dialog on"; the message then names the dialog first."""
     if disabled():
         return "", ""
     riskrails = os.path.join(home, "riskrails")
@@ -95,12 +96,26 @@ def notice(runtime, home, plugin_root, now):
     have, new = parse(installed), parse(latest)
     if not have or not new or new <= have:
         return "", ""
-    message = (f"RiskRails {latest} is available (installed {installed}). Update: {COMMAND} "
-               f"— inside Claude Code or Codex CLI: ! {COMMAND} — then /rr-setup --update in each project.")
-    context = (f"RiskRails {latest} is available on npm; {installed} is installed. The user updates it "
-               f"with `{COMMAND}` in a terminal, or `! {COMMAND}` inside Claude Code or Codex CLI, "
-               "then `/rr-setup --update` in each project. Mention this once to the user if it is "
-               "relevant; never run the update yourself — installing is the user's act.")
+    if dialog:
+        message = (f'RiskRails {latest} is available (installed {installed}). Say "update RiskRails" and the '
+                   f"session asks you in the dialog — or run {COMMAND} in a terminal; "
+                   "then /rr-setup --update in each project.")
+    else:
+        message = (f"RiskRails {latest} is available (installed {installed}). Update: {COMMAND} "
+                   f"— inside Claude Code or Codex CLI: ! {COMMAND} — then /rr-setup --update in each project.")
+    if dialog:
+        context = (f"RiskRails {latest} is available on npm; {installed} is installed. When the user asks to "
+                   "update, open the install decision — state.py decision open --kind install "
+                   f'--command "npx riskrails@{latest} --yes" — send the dialog it prints and run the '
+                   "command the user picks, verbatim, once; never run the update without that pick — "
+                   "installing is the user's act. A task in flight refuses it (INSTALL_DURING_TASK): close "
+                   "the task first. Afterwards the user starts a new session and runs /rr-setup --update "
+                   "in each project. Mention this once to the user if it is relevant.")
+    else:
+        context = (f"RiskRails {latest} is available on npm; {installed} is installed. The user updates it "
+                   f"with `{COMMAND}` in a terminal, or `! {COMMAND}` inside Claude Code or Codex CLI, "
+                   "then `/rr-setup --update` in each project. Mention this once to the user if it is "
+                   "relevant; never run the update yourself — installing is the user's act.")
     return message, context
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riskrails",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "RiskRails: a weight-based engineering pipeline for Claude Code and Codex — scoped steps, enforcement hooks, adversarial review, model routing.",
   "keywords": ["claude-code", "codex", "sdlc", "agents", "guardrails", "code-review"],
   "homepage": "https://github.com/vanssata/claude-agentic-sdlc-module#readme",

package/skills/ai-init/templates/.ai/policies/coding.md

@@ -18,6 +18,15 @@
   install and reviewable in git.
 - Dead code is deleted only in a task that is about deleting it, with evidence
   that it is dead.
+- A function does one thing and its name says which. When the name needs
+  "and", split it.
+- Inputs come in as parameters and the result goes out as the return value;
+  files, the network and the clock stay at the edge, in the caller.
+- An error message says what failed, what was expected, what was found, and
+  the way out.
+
+In existing code the file's conventions win; the last three lines hold for the
+functions you add.
 
 ## Comments
 

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."

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

@@ -280,10 +280,11 @@ def close_gate_from_file(root, state, question, by, rt=rr_runtime.Runtime()):
         state.update(fresh)
         seen, why = (True, "") if unattended else dialog.human_turn(root, state)
         if not seen:
-            fs.die("APPROVAL_REFUSED — %s. Fill the answer, tell the session, and sync again, or run "
-                "in your own terminal:\n  python3 %s --root %s approve --by %s"
-                % (why, shlex.quote(fs.ENTRY), shlex.quote(root),
-                   shlex.quote(by)), 5)
+            cmd = "python3 %s --root %s approve --by %s" % (shlex.quote(fs.ENTRY), shlex.quote(root), shlex.quote(by))
+            asked = dialog.human_refusal("'state.py approve'", cmd, why, dialog.open_approval_id(root, rt=rt))
+            fs.die(asked + " Or fill the [Answer]: line, tell the session, and sync again." if asked else
+                   "APPROVAL_REFUSED — %s. Fill the answer, tell the session, and sync again, or run "
+                   "in your own terminal:\n  %s" % (why, cmd), 5)
         approved = question["choice"] == "A"
         session = fs.read_session(root)
         task.claim_runtime(root, state, rt=rt)