riskrails 4.1.0 → 4.2.0

package/hooks/guard/paths_base.py

@@ -0,0 +1,59 @@
+"""The shared texts of the path guard: the text converter T, the regex fragments Q, END, VAR and
+SEGMENT, and the deny messages (the WHY_* texts) that more than one rule module raises.
+
+R16: every name here is core (no file, clock or subprocess access).
+Moved from paths.py in WP5 (small-oop-modules), unchanged.
+"""
+from guard.common import text_to_b
+
+
+T = text_to_b
+
+Q = "['\"]?"
+END = "([[:space:]]|['\"]|$)"
+VAR = "\\$\\{?[A-Za-z_][A-Za-z0-9_]*\\}?"
+
+WHY_CONFIRM_DELETE = T(
+    "\n\n--confirm-delete is a human confirming an irreversible deletion, and the name\n"
+    "typed is the audit trail. A human runs the same command in a terminal\n"
+    "outside Claude Code or Codex (not through the ! prefix: that shell is the\n"
+    "agent's). An unattended run exports AI_UNATTENDED=1 in the launcher's environment, and the\n"
+    "record then says via: unattended. See skills/project-update/SKILL.md.")
+WHY_SENSITIVE = T(
+    "\n\nProduction secrets and data dumps must not enter the model context.\n"
+    "If this path is genuinely safe (a .dist/.example file, a fixture), add a regex to\n"
+    "\"allow_patterns\" in .ai/policies/path-guard.json. See .ai/policies/security.md.")
+WHY_PROTECTED = T(
+    "\n\nThese files are the guard configuration and the task state. State is written by\n"
+    "skills/ai-task/state.py, and during a schema migration by\n"
+    "skills/project-update/update.py; policy files are edited by a human outside an\n"
+    "agent run, so a change to them is reviewable. See .ai/policies/safety.md.")
+WHY_TASK = T(
+    "\n\nWhile a task is in flight the runtime's own configuration is frozen: settings,\n"
+    "agent and skill definitions, commands, hooks, and the pipeline's policies and\n"
+    "workflows. A run that edits the rules it is being judged by is how scope and\n"
+    "review quietly get weaker. Finish or archive the task\n"
+    "(skills/ai-task/state.py close), then change this through /project-update or by\n"
+    "hand outside a run. See .ai/policies/safety.md.")
+WHY_APPROVE = T(
+    "\n\nApproval happens outside the agent. A human runs, in their own terminal:\n"
+    "  python3 <plugin>/skills/ai-task/state.py --root . approve --by \"<name>\"\n"
+    "or sets [Answer]: A on the gate question in .ai/reports/<task-id>/task.md\n"
+    "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_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.")
+
+WHY_HUMAN = T(
+    "\n\nThis command is the human's, whether or not the dialog is on. A human runs it in their\n"
+    "own terminal, outside the agent session; an unattended run exports AI_UNATTENDED=1 in the\n"
+    "launcher's environment. See .ai/policies/safety.md.")
+WHY_PICK = T(
+    "\n\nWith the dialog on, this command runs from an agent session only as the human's pick.\n"
+    "The command that needs it opened a decision: 'state.py decision show' prints the dialog;\n"
+    "send it and run the picked command verbatim, once. Otherwise the human runs it in their\n"
+    "own terminal. See .ai/policies/safety.md.")
+
+SEGMENT = "^[[:space:]]*"

package/hooks/guard/paths_bash.py

@@ -0,0 +1,176 @@
+"""The Bash rule of the path guard: the verb tables (readers, copiers, writers, removers, fetchers,
+ln, dd) and check_bash, which walks the segments of one command and applies every other rule.
+
+R16: shell (they read the file system, the clock or a subprocess): check_bash; every other name here is core.
+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_shell import shell_segments
+from guard.paths_human import (APPROVE_RE, DIALOG_GATE_RE, HUMAN_BY_RE, PROFILE_SET_RE,
+                               START_LIGHT_RE)
+from guard.paths_movers import GLOBBY
+
+
+VERBS_RE = ("(^|[^A-Za-z0-9_.-])(cp|mv|install|rsync|rm|rmdir|unlink|tee|truncate|shred|touch|ln|chmod|chown|"
+            "dd|sed|perl|ruby)([^A-Za-z0-9_.-]|$)")
+
+READERS = ("(^|[|;&[:space:]])(cat|bat|less|more|head|tail|strings|xxd|od|hexdump|base64|nl|tac|rev)"
+           "([[:space:]]+-[^[:space:]]+)*[[:space:]]+")
+COPIERS = "(^|[|;&[:space:]])(cp|mv|rsync|scp|install|tar|zip|curl|wget)([[:space:]]+[^;&|[:space:]]+)*[[:space:]]+"
+WRITERS = SEGMENT + "(tee|truncate|shred|touch|ln)([[:space:]]+-[^[:space:]]+)*[[:space:]]+"
+REMOVERS = SEGMENT + "(rm|rmdir|unlink)([[:space:]]+[^;&|[:space:]]+)*[[:space:]]+"
+MODES = SEGMENT + "(chmod|chown)([[:space:]]+-[^[:space:]]+)*[[:space:]]+[^-][^[:space:]]*[[:space:]]+"
+DDWRITE = SEGMENT + "dd([[:space:]]+[^;&|[:space:]]+)*[[:space:]]+"
+INPLACE = SEGMENT + "(sed|perl|ruby)([[:space:]]+-[^[:space:]]*i[^[:space:]]*)([[:space:]]+[^;&|[:space:]]+)*[[:space:]]+"
+LN_RE = "(^|[|;&[:space:]])ln([[:space:]]+-[^[:space:]]+)*[[:space:]]"
+LN_SRC_RE = ".*(^|[|;&[:space:]])ln([[:space:]]+-[^[:space:]]+)*[[:space:]]+([^[:space:];&|]+).*"
+# Words that make a long command worth a full check; past LONG_CMD the guard
+# refuses rather than run its patterns over the text (R22, D3).
+LONG_CMD = 4096
+# Whole words only, so --cov, --config and approve_invoice do not trip it.
+LONG_TRIGGER_RE = ("(^|[^A-Za-z0-9_])approve([^A-Za-z0-9_]|$)|--by(=|[[:space:]]|$)|"
+                   "--con?f?i?r?m?-?(d?e?l?e?t?e?|c?l?e?a?n?u?p?)(=|[[:space:]]|$)|state\\.py|update\\.py")
+# Tools that write a file named on their command line without a redirect; the
+# movers do not parse them, so any protected path they name is refused (H1).
+FETCHERS = "(^|[|;&[:space:]])(scp|tar|zip|unzip|curl|wget)([[:space:]]+[^;&|[:space:]]+)*[[:space:]]+"
+
+
+def check_bash(self, unattended):           # pylint: disable=too-many-branches,too-many-statements
+    m = self.m
+    cmd = chomp_all(self.p.bash_command())
+    if not cmd:
+        raise Allow()
+    cmd_joined = cmd.replace("\\\n", " ")
+    length = self.loc.length
+    if length(cmd) > LONG_CMD and (m.search_c(LONG_TRIGGER_RE, cmd) or m.matches_joined(cmd, self.loose)):
+        raise Deny("Refusing a %d-character shell command that names a guarded path or a state.py or "
+                   "update.py verb: write it to a file and run that, or split it." % length(cmd))
+    if m.ere_match(DIALOG_GATE_RE, cmd_joined):
+        raise Deny("Refusing to run hooks/dialog-gate.py from a shell: it records the human's answer to "
+                   "the dialog, and only the runtime calls it, after the dialog tool. To answer a decision, "
+                   "send the dialog ('state.py decision show'); a human settles one in their own terminal "
+                   "('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)
+    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):
+        raise Deny(T("Refusing a verdict with 'state.py … --by' from an agent session.")
+                   + (WHY_PICK if on else WHY_HUMAN))
+    if not on and not picked and not unattended and m.ere_match(START_LIGHT_RE, cmd_joined):
+        raise Deny(T("Refusing 'state.py start --mode light … --by' from an agent session: lowering the "
+                     "mode is the human's.") + WHY_HUMAN)
+    self.interpreter_text(cmd)
+
+    # Top-level splitting only: the string a sh -c or an eval runs is not
+    # re-parsed (R22, SQ13; the bypass is accepted in known-risks.md).
+    segs = shell_segments(cmd) if m.ere_match(VERBS_RE, cmd) else ""
+    self.movers(segs)
+
+    if not (m.matches_joined(cmd, self.loose) or m.ere_match(LN_RE, cmd)):
+        raise Allow()
+
+    tokens = []
+    words = [w for w in re.split("[ \t\n]+", re.sub("[|;&()<>]", " ", cmd + "\n")) if w]
+    stripped = []
+    for w in words:
+        w = w.lstrip("\"'").rstrip("\"'")
+        if w:
+            stripped.append(w)
+    for token in self.sort_u(stripped):
+        self.work_clock()
+        if not token or token.startswith("-"):
+            continue
+        tokens.append(token)
+    short, abs_lines = [], []
+    for token in tokens:
+        self.work_clock()
+        if length(token) > 4096:
+            if any(c in GLOBBY for c in token):
+                raise Deny("Refusing a shell command with a %d-character argument that holds a glob or "
+                           "expansion character: the guard cannot check what it expands to." % length(token))
+            after = token.split("=", 1)[1] if "=" in token else token
+            if m.ere_match(self.loose_joined, abs_path(token, self.cwd) + "\n" + abs_path(after, self.cwd)):
+                raise Deny("Refusing a shell command with a %d-character argument that matches a guarded "
+                           "path pattern: no path that long names a file, and the guard does not check it."
+                           % length(token))
+            continue
+        short.append(token)
+        abs_lines.append(token if token.startswith("/") else strip1(self.cwd, "/") + "/" + token)
+    exist = []
+    for i in range(len(short)):
+        self.work_clock()
+        if exists(abs_lines[i]):
+            exist.append(i)
+    resolved = []
+    if exist:
+        for i in exist:
+            r = realpath_strict(abs_lines[i])
+            if r is not None:
+                resolved.append(chomp_all(r))
+        if len(resolved) != len(exist):
+            resolved = []
+            for i in exist:
+                self.work_cap("token")
+                resolved.append(real_path(short[i], self.cwd))
+    real_lines = list(abs_lines)
+    for j, i in enumerate(exist):
+        real_lines[i] = resolved[j]
+    lines = []
+    for i, token in enumerate(short):
+        eq = abs_lines[i]
+        if "=/" in token:
+            eq = token.split("=", 1)[1]
+        elif "=" in token:
+            eq = strip1(self.cwd, "/") + "/" + token.split("=", 1)[1]
+        lines += [abs_lines[i], real_lines[i], eq]
+    thits = {(n - 1) // 3 for n in self.loose_hits(lines)}
+    self.work_clock()
+    for token in [short[i] for i in range(len(short)) if i in thits]:
+        self.work_cap("token")
+        verdict = self.classify(abs_path(token, self.cwd)) or self.classify(real_path(token, self.cwd))
+        if "=" in token and verdict is None:
+            verdict = self.classify(abs_path(token.split("=", 1)[1], self.cwd))
+        if verdict is None:
+            continue
+        kind, pattern = verdict
+        esc = ere_escape(token)
+        # Reading is refused for a secret only; a control file is read freely (R22),
+        # unless it also matches a secret pattern (.ai/state/x.pem).
+        secret = kind == "sensitive" or m.matches_any(self.deny_p, abs_path(token, self.cwd)) is not None
+        if secret and (m.ere_match(READERS + "[\"']?" + esc, cmd)
+                                    or m.ere_match(COPIERS + "[\"']?" + esc, cmd)
+                                    or m.ere_match("<[[:space:]]*[\"']?" + esc, cmd)):
+            raise Deny("Refusing a shell command that would expose a sensitive path: %s (matched: %s)%s"
+                       % (token, pattern, WHY_SENSITIVE))
+        how = ""
+        if m.ere_match(">>?[[:space:]]*[\"']?" + esc, cmd):
+            how = "redirect into"
+        elif m.ere_match(FETCHERS + "[\"']?" + esc, cmd):
+            how = "command that writes"
+        for rx, what in ((WRITERS, "command that writes"), (MODES, "command that writes"),
+                         (DDWRITE, "command that writes"), (INPLACE, "in-place edit of"),
+                         (REMOVERS, "removal of")):
+            if not how and m.ere_match(rx + "[\"']?" + esc, segs):
+                how = what
+        if how:
+            if kind == "protected":
+                raise Deny("Refusing a shell %s a RiskRails control file: %s%s" % (how, token, WHY_PROTECTED))
+            if kind == "task" and self.task_in_flight():
+                raise Deny("Refusing a shell %s runtime configuration while task %s is in flight: %s%s"
+                           % (how, self.task_id, token, WHY_TASK))
+
+    if m.ere_match(LN_RE, cmd):
+        src = []
+        for line in herestring_lines(strip1(cmd, "\n")):
+            g = m.groups(LN_SRC_RE, line)
+            if g is not None:
+                src.append(g[3] + "\n")
+        src = chomp_all("".join(src))
+        if src and self.classify(abs_path(src, self.cwd)):
+            raise Deny("Refusing to create a symlink to a sensitive path: %s%s" % (src, WHY_SENSITIVE))

package/hooks/guard/paths_classify.py

@@ -0,0 +1,205 @@
+"""Pattern loading and path classification: the sensitive and protected patterns, their anchors, and
+classify and check_path, which decide what a path is.
+
+R16: shell (they read the file system, the clock or a subprocess): load_patterns, setup_anchors, classify, check_path; every other name here is core.
+phys_path, which classify calls through self, stays a PathGuard method in paths.py (it reads no self).
+Moved from paths.py in WP5 (small-oop-modules), unchanged.
+"""
+from guard.common import (Deny, abs_path, chomp_all, env_b, herestring_lines, is_dir, is_file,
+                          is_jq_string, jq_iter, load_json_file, real_path, strip1)
+from guard.paths_base import T, WHY_PROTECTED, WHY_SENSITIVE, WHY_TASK
+from guard.paths_fs import anchor_list, cd_physical, lexnorm
+
+
+TOKEN_END = "([[:space:]\"';&|)<>]|$)"
+
+
+# -------------------------------------------------------------- patterns
+
+def load_patterns(self):
+    files = [f for f in (self.ctx.hook_dir + "/ai-path-guard-defaults.json",
+                         self.root + "/.ai/policies/path-guard.json") if is_file(f)]
+    tagged = []
+    for f in files:
+        loaded = load_json_file(f)
+        if loaded is None:
+            continue
+        for doc in loaded[0]:
+            if doc is not None and not isinstance(doc, dict):
+                continue
+            for tag, key in (("d", "deny_patterns"), ("a", "allow_patterns"),
+                             ("p", "protected_config_patterns"), ("k", "task_protected_patterns")):
+                v = doc.get(key) if doc else None
+                for item in jq_iter(v if v is not None and v is not False else []):
+                    if is_jq_string(item) and item != "":
+                        tagged.extend((tag, T(piece)) for piece in item.split("\n"))
+    key = self.loc.sort_key
+    seen, lists = set(), {"d": "", "a": "", "p": "", "k": ""}
+    for tag, pat in sorted(tagged, key=lambda t: (key(t[0]), key(t[1]))):
+        k = (key(tag), key(pat))
+        if k in seen:
+            continue
+        seen.add(k)
+        lists[tag] += pat + "\n"
+    self.deny_p = chomp_all(lists["d"])
+    self.allow_p = chomp_all(lists["a"])
+    self.prot_p = chomp_all(lists["p"])
+    self.task_p = chomp_all(lists["k"])
+
+
+def build_loose(self):
+    interesting, loose_all = [], []
+    for pattern in herestring_lines(self.deny_p + "\n" + self.prot_p + "\n" + self.task_p):
+        if not pattern:
+            continue
+        interesting.append(pattern + "\n")
+        loose = pattern[5:] if pattern.startswith("(^|/)") else pattern
+        loose = loose[1:] if loose.startswith("^") else loose
+        loose = strip1(loose, "$")
+        loose_all.append(loose.replace("$", TOKEN_END) + "\n")
+    self.interesting = chomp_all("".join(interesting))
+    self.loose = chomp_all("".join(loose_all))
+    self.loose_joined = self.loose.replace("\n", "|")
+
+
+# -------------------------------------------------------------- anchoring
+
+def setup_anchors(self):
+    self.roots, self.prefixes, self.renamed = [], [], []
+
+    def anchor_root(d, prefix):
+        if not d.startswith("/"):
+            return
+        norm = lexnorm(d)
+        self.roots.append(norm)
+        self.prefixes.append(prefix)
+        self.renamed.append(bool(prefix) and norm.rsplit("/", 1)[-1] + "/" != prefix)
+
+    anchor_root(self.root, "")
+    anc = self.root.rsplit("/", 1)[0] if "/" in self.root else ""
+    while anc:
+        if is_dir(anc + "/.ai"):
+            anchor_root(anc, "")
+        anc = anc.rsplit("/", 1)[0] if "/" in anc else ""
+    if self.root != "/" and is_dir("/.ai"):
+        anchor_root("/", "")
+    if self.home:
+        anchor_root(self.home + "/.claude", ".claude/")
+        anchor_root(self.home + "/.codex", ".codex/")
+    ccd, cxh = env_b("CLAUDE_CONFIG_DIR"), env_b("CODEX_HOME")
+    if ccd:
+        anchor_root(ccd, ".claude/")
+    if cxh:
+        anchor_root(cxh, ".codex/")
+    self.anch = {"PROT": anchor_list(self.prot_p), "TASK": anchor_list(self.task_p)}
+
+
+def anchor_rels(self, path, roots, rels):
+    np = lexnorm(path)
+    tail = "/" if path.endswith("/") or path.endswith("/.") else ""
+    for i, r in enumerate(roots):
+        if r == "/":
+            rel = np[1:] if np.startswith("/") else np
+        elif np == r:
+            rel = ""
+        elif np.startswith(r + "/"):
+            rel = np[len(r) + 1:]
+        else:
+            continue
+        rel = self.prefixes[i] + rel if rel else strip1(self.prefixes[i], "/")
+        if rel:
+            rels.append(rel + tail)
+
+
+def anchored_hit(self, kind, path, rels):
+    for rx, orig, absolute in self.anch[kind]:
+        if absolute:
+            if self.m.ere_match(rx, path):
+                return orig
+            continue
+        for r in rels:
+            if self.m.ere_match(rx, r):
+                return orig
+    return None
+
+
+def unanchored_hit(self, kind, path):
+    for _, orig, _ in self.anch[kind]:
+        if self.m.ere_match(orig, path):
+            return orig
+    return None
+
+
+# -------------------------------------------------------------- classify
+
+def classify(self, p):
+    """(kind, pattern) or None: protected, task or sensitive."""
+    m = self.m
+    subject = p
+    for i, r in enumerate(self.roots):
+        if self.renamed[i] and p.startswith(r + "/"):
+            subject += "\n" + self.prefixes[i] + p[len(r) + 1:]
+    if not m.matches_joined(subject, self.interesting):
+        return None
+    if m.matches_any(self.allow_p, p) is not None:
+        return None
+    anchored = not (any(c in p for c in "$`~*?{[") or self.loc.length(p) > 4096)
+    task_hit = None
+    if not anchored:
+        hit = self.unanchored_hit("PROT", p)
+        if hit is not None:
+            return ("protected", hit)
+        if self.task_p:
+            task_hit = self.unanchored_hit("TASK", p)
+    else:
+        rels = []
+        self.anchor_rels(p, self.roots, rels)
+        hit = self.anchored_hit("PROT", p, rels)
+        if hit is not None:
+            return ("protected", hit)
+        task_hit = self.anchored_hit("TASK", p, rels)
+        if task_hit is None and (self.unanchored_hit("PROT", p) is not None
+                                 or self.unanchored_hit("TASK", p) is not None):
+            resolved = self.phys_path(p)
+            if resolved is not None:
+                phys_roots = [cd_physical(r) or r for r in self.roots]
+                rels = []
+                self.anchor_rels(resolved, self.roots, rels)
+                self.anchor_rels(resolved, phys_roots, rels)
+                hit = self.anchored_hit("PROT", resolved, rels)
+                if hit is not None:
+                    return ("protected", hit)
+                task_hit = self.anchored_hit("TASK", resolved, rels)
+    if task_hit is not None:
+        return ("task", task_hit)
+    hit = m.matches_any(self.deny_p, p)
+    if hit is not None:
+        return ("sensitive", hit)
+    return None
+
+
+def check_path(self, literal, verb):
+    a = abs_path(literal, self.cwd)
+    real = real_path(literal, self.cwd)
+    for cand in [a] if real == a else [a, real]:
+        v = self.classify(cand)
+        if v is None:
+            continue
+        kind, pattern = v
+        if verb == "read" and kind != "sensitive":
+            hit = self.m.matches_any(self.deny_p, cand)
+            if hit is not None:
+                raise Deny("Refusing to read a sensitive path: %s (matched: %s)%s"
+                           % (literal, hit, WHY_SENSITIVE))
+        if kind == "protected":
+            if verb == "read":
+                continue
+            raise Deny("Refusing to %s a RiskRails control file: %s (matched: %s)%s"
+                       % (verb, literal, pattern, WHY_PROTECTED))
+        if kind == "task":
+            if verb == "read" or not self.task_in_flight():
+                continue
+            raise Deny("Refusing to %s runtime configuration while task %s is in flight: %s (matched: %s)%s"
+                       % (verb, self.task_id, literal, pattern, WHY_TASK))
+        raise Deny("Refusing to %s a sensitive path: %s (matched: %s)%s"
+                   % (verb, literal, pattern, WHY_SENSITIVE))

package/hooks/guard/paths_fs.py

@@ -0,0 +1,137 @@
+"""The path guard's stand-ins for the shell's file tools: realpath -m (realpath_m), find -prune -o
+-print (find_print), the lexical clean-up (lexnorm), cd -P (cd_physical) and the anchored-pattern list
+(anchor_list), with the LoopError they raise.
+
+R16: shell (they read the file system, the clock or a subprocess): realpath_m, find_print, cd_physical; every other name here is core.
+Moved from paths.py in WP5 (small-oop-modules), unchanged.
+"""
+import os
+import stat
+from guard.common import b_bytes, bytes_b, herestring_lines, is_dir
+
+
+class LoopError(OSError):
+    """A path that does not resolve: realpath prints an error, not a line."""
+
+
+def realpath_m(path):
+    """`realpath -m` of one absolute path: every link that exists resolved,
+    what does not exist appended as written, `..` after resolution; a symlink
+    loop raises LoopError."""
+    seen = {}
+
+    def join(base, rest):
+        if rest.startswith(b"/"):
+            base = b"/"
+        for name in rest.split(b"/"):
+            if name in (b"", b"."):
+                continue
+            if name == b"..":
+                base = os.path.dirname(base) if base != b"/" else base
+                continue
+            new = base.rstrip(b"/") + b"/" + name
+            try:
+                is_link = stat.S_ISLNK(os.lstat(new).st_mode)
+            except OSError:
+                is_link = False
+            if not is_link:
+                base = new
+                continue
+            if new in seen:
+                if seen[new] is None:
+                    raise LoopError()
+                base = seen[new]
+                continue
+            seen[new] = None
+            try:
+                target = os.readlink(new)
+            except OSError as exc:
+                raise LoopError() from exc
+            base = join(base, target)
+            seen[new] = base
+        return base
+
+    try:
+        return bytes_b(join(b"/", b_bytes(path)))
+    except RecursionError as exc:
+        raise LoopError() from exc
+
+
+def find_print(start, maxdepth, prune):
+    """`find START -maxdepth N \\( -name A -o … \\) -prune -o -print`, in
+    name order (not find's readdir order), links not followed, errors silent."""
+    def walk(path, name, depth):
+        if name in prune:
+            return
+        yield path
+        if depth >= maxdepth:
+            return
+        try:
+            with os.scandir(b_bytes(path)) as it:
+                entries = list(it)
+        except OSError:
+            return
+        # by name, not readdir order: which held file a refusal names must not depend
+        # on the filesystem (ext4 here put .ai/policies first, the CI runner .ai/state)
+        for e in sorted(entries, key=lambda e: e.name):
+            try:
+                is_d = e.is_dir(follow_symlinks=False)
+            except OSError:
+                is_d = False
+            child = (path.rstrip("/") if path != "/" else "") + "/" + bytes_b(e.name)
+            if is_d:
+                yield from walk(child, bytes_b(e.name), depth + 1)
+            elif bytes_b(e.name) not in prune:
+                yield child
+    base = start.rstrip("/").rsplit("/", 1)[-1] if start.rstrip("/") else "/"
+    try:
+        st = os.lstat(b_bytes(start))
+    except OSError:
+        return
+    if stat.S_ISLNK(st.st_mode):
+        if base not in prune:
+            yield start                     # -P: a start that is a link is not entered
+        return
+    yield from walk(start, base, 0)
+
+
+def lexnorm(path):
+    """lexnorm: //, /./ and /../ resolved by text, no trailing slash."""
+    out = []
+    rest = path[1:] if path.startswith("/") else path
+    for seg in (rest + "/").split("/"):
+        if seg in ("", "."):
+            continue
+        if seg == "..":
+            if out:
+                out.pop()
+        else:
+            out.append(seg)
+    return "/" + "/".join(out) if out else "/"
+
+
+def cd_physical(d):
+    """$PWD after `cd -P -- "$d"`, or None when cd fails."""
+    try:
+        if not (is_dir(d) and os.access(b_bytes(d), os.X_OK)):
+            return None
+        return bytes_b(os.path.realpath(b_bytes(d)))
+    except (OSError, ValueError):
+        return None
+
+
+def anchor_list(patterns):
+    """[(anchored regex, pattern as written, matched against the absolute path)]."""
+    out = []
+    for p in herestring_lines(patterns):
+        if not p:
+            continue
+        if p.startswith("(^|/)"):
+            out.append(("^" + p[5:], p, False))
+        elif p.startswith("^"):
+            out.append((p, p, True))
+        elif p.startswith("/"):
+            out.append(("^" + p[1:], p, False))
+        else:
+            out.append(("(^|/)(" + p + ")", p, False))
+    return out