@r1z4x/tezgah 1.9.2 → 1.11.0

package/hooks/tezgah_integrity.py

@@ -31,6 +31,7 @@ import re
 import shlex
 import statistics
 import time
+import urllib.parse
 
 try:
     import fcntl
@@ -49,12 +50,17 @@ import tezgah_store as ts
 VERIFY = re.compile(
     r"(?:^|[|;&(])\s*"
     r"(?:(?:sudo|env|time|nohup|command|exec)\s+(?:\w+=\S+\s+)*(?:-\S+\s+)*)?"
-    r"(?:"    r"(?:python3?|uv run)\s+(?:-m\s+)?(?:pytest|unittest|mypy|ruff|flake8|compileall|"
-    r"(?:[\w./-]*/)?tezgah-design\s+(?:check|derive)|"
+    r"(?:"    r"(?:python3?|uv run)\s+(?:(?:--project|--with|--python|--extra|--group|-p|-w)\s+\S+\s+|-\S+\s+)*(?:python3?\s+-m\s+)?(?:pytest|unittest|mypy|ruff|flake8|compileall|"
+    r"(?:[\w./-]*/)?tezgah-design\s+(?:check|derive|slop)|"
     r"(?:[\w./-]*/)?tests[/\\]impacted\.py)|"
     r"pytest|py\.test|"
-    r"npm\s+(?:test|t\b)|npm\s+run\s+\S*(?:test|lint|typecheck|check|build|ci)|"
-    r"(?:yarn|pnpm|bun)\s+(?:test|run\s+\S*(?:test|lint|build|check))|"
+    # A runner may carry a flag (and its value) before its task: a monorepo's
+    # `pnpm --filter mobile test` was read as a plain command, so the check it
+    # ran recorded as `run` and the Stop rule refused the claim it supported
+    # (plan 135: 11 of the post-2026-10-07 window's blocked claims, 2 before).
+    r"(?:npm|yarn|pnpm|bun)\s+(?:(?:--filter|--prefix|--workspace|--cwd|--dir|-C|-w)\s+\S+\s+|-\S+\s+)*"
+    r"(?:test\b|t\b|run\s+(?:-\S+\s+)*\S*(?:test|lint|typecheck|check|build|ci)|"
+    r"workspace\s+\S+\s+(?:test\b|t\b|run\s+\S*(?:test|lint|typecheck|check|build|ci)))|"
     r"ruff|flake8|mypy|pyright|tsc|eslint|prettier|"
     r"vitest|jest|ava|mocha|"
     r"go\s+(?:test|vet)|"
@@ -66,12 +72,12 @@ VERIFY = re.compile(
     r"swift\s+test|golangci-lint|shellcheck|"
     r"playwright|cypress|storybook|chromatic|percy|lighthouse|pa11y|backstop|"
     r"axe-core|reg-suit|"
-    r"(?:[\w./-]*/)?tezgah-design\s+(?:check|derive)|"
+    r"(?:[\w./-]*/)?tezgah-design\s+(?:check|derive|slop)|"
     r"(?:[\w./-]*/)?tests[/\\]impacted\.py|"
     # a JS tool behind its runner is still the check, and the name it returns is
     # the tool's, not the runner's: `npx axe-core` matched as `axe-core` before
     # the anchor was tightened, so the runner is outside the name group here
-    r"(?:npx|npm(?:\s+run)?|pnpm(?:\s+(?:exec|dlx|run))?|yarn|bunx?|uvx)"
+    r"(?:npx|npm(?:\s+run)?|pnpm(?:\s+(?:(?:--filter|--prefix|--workspace|-C|-w)\s+\S+\s+|-\S+\s+)*(?:exec|dlx|run))?|yarn|bunx?|uvx)"
     r"\s+(?:-\S+\s+)*(?P<js>playwright|cypress|storybook|chromatic|percy|"
     r"lighthouse|pa11y|axe-core|backstop|reg-suit|vitest|jest|ava|mocha|eslint|"
     r"prettier|tsc|pyright)"
@@ -168,8 +174,14 @@ UI_TOOL_CMD = re.compile(
 # is read at a command position for `UI_CHECK`'s reason - a grep whose pattern is
 # `tezgah-design check` is text ABOUT the checker. The interpreter prefix is the
 # one the module's own refusal text and the skill both print.
+DESIGN_SLOP = re.compile(r"(?:^|[|;&(])\s*(?:python3?\s+|uv\s+run\s+)?(?:\S*/)?"
+                          r"tezgah-design\s+slop\b", re.I | re.M)
+# `slop --repo <path>`: the tree a verdict scanned
+SLOP_REPO = re.compile(r"tezgah-design\s+slop\b[^|;&]*?--repo\s+([^\s|;&]+)",
+                       re.I)
 DESIGN_CHECK = re.compile(
-    r"(?:^|[|;&(])\s*(?:python3?\s+|uv\s+run\s+)?(?:\S*/)?tezgah-design\s+check\b",
+    r"(?:^|[|;&(])\s*(?:python3?\s+|uv\s+run\s+)?(?:\S*/)?tezgah-design\s+"
+    r"(?:check|slop)\b",
     re.I | re.M)
 # A component, as opposed to the screen it sits on: a file under a
 # component/views/widgets directory, or a name that carries the convention on its
@@ -224,6 +236,9 @@ ROUGH_WORDS = re.compile(r"[;&|()]+|[^\s;&|()<>]+")
 # a redirection operator, or `&` in front of one (`&>`); shlex splits
 # `2>&1` into `2`, `>`, `&`, `1`, and none of those is an argument
 REDIRECTION = re.compile(r"^(?=[&<>]*[<>])[&<>]+$")
+# an fd number glued to its redirection (`2>`, `1<&`): bash reads `1<` as fd 1
+# and `1 <` as the program `1`, and shlex cannot tell them apart afterwards
+FD_REDIRECT = re.compile(r"(?<![\w])(\d+)([<>])")
 # what a shell line puts between the start of a command and its program; the
 # same set in the JS mirror, so the two read a line identically
 GIT_WRAPPER = frozenset(("sudo", "env", "nohup", "time", "timeout", "command",
@@ -1125,16 +1140,49 @@ def prior_calls(session_id, digest, tail=200, agent=None):
             turn[-1].get("fail_class"))
 
 
+# Any `scheme://`: an internal channel (`agent://`, `local://`), a remote URL.
+# `file://` is read by `file_url_path`, the rest name no file on this disk.
+URI_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*://")
+
+
+def file_url_path(text):
+    """The local path a `file://` URL names, `text` itself when it carries no
+    URI scheme, or None for any other URI and for a file URL that names no local
+    file (a host other than `localhost`, no path, a malformed host). Read as
+    `<cwd>/file:/x`, a URL into another checkout landed in the cwd's, one file
+    spelled both ways was two, and `agent://<id>` was a product file (plan 116).
+    ponytail: a shell redirect `> file:///x` writes `./file:/x`; it is read as
+    `/x` here, a spelling no tool produces."""
+    if not URI_SCHEME.match(text):
+        return text
+    if text[:7].lower() != "file://":
+        return None
+    try:
+        parts = urllib.parse.urlsplit(text)
+    except ValueError:  # an unclosed `[` host
+        return None
+    if parts.netloc.lower() not in ("", "localhost") or not parts.path:
+        return None
+    return urllib.parse.unquote(parts.path)
+
+
 def _abs_target(path, cwd):
-    """`path` as an absolute real path, resolved against `cwd` when relative.
+    """`path` as an absolute real path, resolved against `cwd` when relative, a
+    local `file://` URL as the file it names; a URI that names no local file
+    (`s3://b/k`, `agent://<id>`, a remote file URL) as its own spelling.
 
     The form both halves of the cross-session write guard compare: the writer
     stores it in an `edit` row's `target`, the gate resolves its own call's path
     the same way. A file that does not exist yet still resolves (realpath leaves
-    the missing tail as it is), so a new file two sessions both create matches."""
-    path = str(path or "").strip()
-    if not path:
+    the missing tail as it is), so a new file two sessions both create matches,
+    and two sessions writing one `s3://` key match on its spelling, whatever
+    their cwds. The no-plan rule skips such a target (`file_url_path` is None)."""
+    raw = str(path or "").strip()
+    if not raw:
         return None
+    path = file_url_path(raw)
+    if path is None:
+        return raw
     if not os.path.isabs(path):
         path = os.path.join(cwd or os.getcwd(), path)
     return os.path.realpath(path)
@@ -1459,6 +1507,23 @@ def _week(ts):
     return (int(ts or 0) - MONDAY) // WEEK * WEEK + MONDAY
 
 
+def day_start(text):
+    """The epoch second a `YYYY-MM-DD` date starts at, in this machine's time
+    zone, or None when the text is not that date. Whole calendar days are what
+    a reader types and what a person reads on a calendar, so the window edges
+    are local midnights; one format, never a guess at a date that was mistyped."""
+    try:
+        return int(time.mktime(time.strptime(str(text), "%Y-%m-%d")))
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def _day(ts):
+    """The calendar day a row's `ts` falls on, as `YYYY-MM-DD` (local, the same
+    edges `day_start` reads)."""
+    return time.strftime("%Y-%m-%d", time.localtime(int(ts)))
+
+
 _CATALOG = {}
 
 
@@ -1727,6 +1792,18 @@ def _reissued(rows):
     return out
 
 
+def _claim_class(detail):
+    """How a `claim` row's detail classifies: `(class, verdict)` where verdict is
+    `ok` (nothing was refused), `shape` (the class in `SHAPE_BLOCKS` refuses the
+    reply's form, not its claim) or `blocked` (the class refuses the claim).
+    One reader for `_counts` and `rates`, so a corpus total and a window cannot
+    disagree about what a `list cap` row is."""
+    if not str(detail).startswith("blocked"):
+        return None, "ok"
+    cls = str(detail)[len("blocked: "):]
+    return cls, ("shape" if cls in SHAPE_BLOCKS else "blocked")
+
+
 def _counts(rows, weeks=False, tools=False):
     """`counters`' arithmetic over rows already read: the one implementation
     both readers fold with, so a total and the sessions it sums cannot drift
@@ -1807,19 +1884,18 @@ def _counts(rows, weeks=False, tools=False):
         elif kind == "claim":
             out["claims"] += 1
             refused = False
-            if detail.startswith("blocked"):
+            cls, verdict = _claim_class(detail)
+            if verdict == "shape":
                 # a reply blocked for its shape made no false claim: the rate
                 # the module calls its effect must not count a list cap
-                if detail[len("blocked: "):] in SHAPE_BLOCKS:
-                    out["shape_blocked"] += 1
-                else:
-                    # split by the Stop class: which check refused, as a number
-                    cls = detail[len("blocked: "):]
-                    out["blocked_claims"][cls] = \
-                        out["blocked_claims"].get(cls, 0) + 1
-                    if cls not in LIST_BLOCKS:
-                        out["false_completion"] += 1
-                        refused = True
+                out["shape_blocked"] += 1
+            elif verdict == "blocked":
+                # split by the Stop class: which check refused, as a number
+                out["blocked_claims"][cls] = \
+                    out["blocked_claims"].get(cls, 0) + 1
+                if cls not in LIST_BLOCKS:
+                    out["false_completion"] += 1
+                    refused = True
             if weeks:
                 # the same bucket this row's events went into, so a claim cannot
                 # sit in a week's total and outside its ratio
@@ -1884,27 +1960,204 @@ def _counts(rows, weeks=False, tools=False):
     return out
 
 
-def _check_runs(cmd):
+# The windowed rates reader (plan 134). One bucket is filled once for the window
+# and once for each of its calendar days from the same rows, so a day and the
+# window it sits in cannot disagree, and two adjacent windows partition the span
+# because the filter is `[start, end)` on the row's own `ts`.
+def _rate_bucket():
+    """An empty rates bucket: the counts the observation rows read, and the two
+    histograms they split them by."""
+    return {"events": 0, "turns": 0, "claims": 0, "replies": 0,
+            "blocked_claims": {}, "shape_blocked": 0, "false_completion": 0,
+            "shape_flagged": 0, "shapes": {}, "denies": {}, "row_versions": {}}
+
+
+# A row's contract version as the rates name it, the label `failure_shapes`
+# already prints: `v1`, or `unversioned` for a row the writer stamped nothing on.
+def _contract(value):
+    return "unversioned" if value is None else "v%s" % value
+
+
+def _rate_row(bucket, entry):
+    """One ledger row into a rates bucket: the classification `_counts` makes,
+    and only the rows these rates read."""
+    kind = str(entry.get("kind") or "")
+    detail = str(entry.get("detail") or "")
+    bucket["events"] += 1
+    bucket["row_versions"][_contract(entry.get("v"))] = \
+        bucket["row_versions"].get(_contract(entry.get("v")), 0) + 1
+    if kind == TURN_KIND:
+        bucket["turns"] += 1
+    elif kind == "deny":
+        rule = _deny_rule(detail)
+        bucket["denies"][rule] = bucket["denies"].get(rule, 0) + 1
+    elif kind == "claim":
+        bucket["claims"] += 1
+        cls, verdict = _claim_class(detail)
+        if verdict == "shape":
+            bucket["shape_blocked"] += 1
+        elif verdict == "blocked":
+            bucket["blocked_claims"][cls] = \
+                bucket["blocked_claims"].get(cls, 0) + 1
+            if cls not in LIST_BLOCKS:
+                bucket["false_completion"] += 1
+    elif kind == "shape":
+        # one row per judged reply, its detail the flag list (`ok` when none):
+        # `shape_flagged` is the reply count the rate needs, `shapes` the class
+        # split - a count of flags, so a reply carrying two moves both
+        bucket["replies"] += 1
+        if detail and detail != "ok":
+            bucket["shape_flagged"] += 1
+        for flag in (f.strip() for f in detail.split(",")):
+            if flag:
+                bucket["shapes"][flag] = bucket["shapes"].get(flag, 0) + 1
+
+
+def _per_scale(scale, numerator, denominator):
+    """`scale * n / d`, or None with no denominator: a window with no turn or no
+    session has no rate, and a 0.0 there would read as a measured zero."""
+    return round(scale * numerator / denominator, 4) if denominator else None
+
+
+def _window_rates(bucket, sessions):
+    """The rates plan 066's rows read, off a filled bucket."""
+    blocked = sum(bucket["blocked_claims"].values())
+    return {
+        # plan 134's pair: what a block and a deny cost per unit of use
+        "blocks_per_100_turns": _per_scale(100, blocked, bucket["turns"]),
+        "denies_per_100_sessions": _per_scale(
+            100, sum(bucket["denies"].values()), sessions),
+        # 056's bar compares these two across adjacent windows, in pp: the share
+        # of claims a Stop class refused, and the share of judged replies that
+        # carried a report-only shape flag
+        "claim_block_rate": _per_scale(1, blocked, bucket["claims"]),
+        "stop_shape_rate": _per_scale(1, bucket["shape_flagged"],
+                                      bucket["replies"]),
+        # 051's bar is per class against live sessions: 1 per 500 reads 0.2 here
+        "blocked_claims_per_100_sessions": {
+            cls: _per_scale(100, n, sessions)
+            for cls, n in bucket["blocked_claims"].items()},
+    }
+
+
+def rates(since, until):
+    """Every real-session ledger's rows stamped in `[since, until)`, folded per
+    window and per calendar day: turns, `claim` rows and the Stop classes that
+    blocked them, the shape flags every judged reply carried, denies by rule,
+    and the rates plan 066's observation rows read (plan 134).
+
+    The window is this reader's; `counters_all` still folds a lifetime, because
+    a total that contradicted the sessions it sums would be the wrong answer to
+    its own question. `until` is exclusive, so two adjacent windows are a
+    partition of the span and not an approximation of one - no row is counted
+    twice or dropped at the seam. A row with no `ts` (a `ledger_damage` row
+    stands in for bytes that could not be parsed) falls outside every window: it
+    carries no time to place it in. `sessions` counts the real ledgers with at
+    least one row in the window, the denominator 051's "live sessions" names;
+    `days` is the window's own length and `by_day` holds only the days that saw
+    a row. Both dates are `YYYY-MM-DD` local calendar days; a malformed or
+    reversed pair is ValueError, never a silently empty window."""
+    start, end = day_start(since), day_start(until)
+    if start is None or end is None:
+        raise ValueError("rates wants --since and --until as YYYY-MM-DD")
+    if end <= start:
+        raise ValueError("rates wants --until after --since")
+    total = _rate_bucket()
+    days, sessions = {}, 0
+    for path in ledgers():
+        rows = _foreign_rows(path)
+        if fixture_ledger(rows):
+            continue
+        rows = [r for r in rows if isinstance(r.get("ts"), (int, float))
+                and start <= r["ts"] < end]
+        if not rows:
+            continue
+        sessions += 1
+        for entry in rows:
+            _rate_row(total, entry)
+            _rate_row(days.setdefault(_day(entry["ts"]), _rate_bucket()), entry)
+    return dict(total, since=str(since), until=str(until), sessions=sessions,
+                days=int(round((end - start) / 86400.0)),
+                by_day=[dict(bucket, day=day)
+                        for day, bucket in sorted(days.items())],
+                rates=_window_rates(total, sessions))
+
+
+def _check_runs(cmd, cwd=None):
     """(name, mode) for every check-shaped command in `cmd`, in order. `mode` is
     `check`, `info` (INFO_ARGS / INFO_SUBCOMMAND: it checks nothing) or `write`
     (FORMAT_WRITE: it changes the tree), read on the words after the tool up to
     the end of that one command, so `pytest --version; pytest` still runs a
-    check."""
+    check. With `cwd`, the repository's own declared checks (`repo_checks`)
+    follow the built-in vocabulary's."""
     text = mask(cmd)
     for m in VERIFY.finditer(text):
         name = (m.groupdict().get("js") or m.group(0)).strip()
         tool = name.split()[-1].lower()
         args = COMMAND_END.split(text[m.end():], 1)[0]
         sub = INFO_SUBCOMMAND.get(tool)
-        if INFO_ARGS.search(args) or (sub and sub.match(args)):
+        # the info flag may sit among the runner's own flags
+        # (`npm --help test` runs nothing), so the whole match is read too
+        if INFO_ARGS.search(m.group(0)) or INFO_ARGS.search(args) \
+                or (sub and sub.match(args)):
             yield name, "info"
         elif tool in FORMAT_WRITE and FORMAT_WRITE[tool].search(args):
             yield name, "write"
         else:
             yield name, "check"
+    prefixes = repo_checks(cwd)
+    if prefixes:
+        yield from _repo_check_runs(cmd, prefixes)
+
+
+# The words in front of a program that leave it the program: VERIFY's own
+# wrapper prefix, read on words instead of text.
+CHECK_WRAPPERS = frozenset(("sudo", "env", "time", "nohup", "command", "exec"))
+ASSIGNMENT_WORD = re.compile(r"^[A-Za-z_]\w*=")
 
 
-def verify_command(cmd):
+def repo_checks(cwd):
+    """[argv prefix] the repository at `cwd` declares as checks in its manifest
+    (`tezgah_extension.repo_checks`), or [] - no cwd, no manifest, a broken one,
+    or a missing extension module. Imported here, not at the top: a broken
+    extension costs the repository its declared checks, never the hook."""
+    if not cwd:
+        return []
+    try:
+        import tezgah_extension
+        return tezgah_extension.repo_checks(cwd)
+    except Exception:
+        return []
+
+
+def _repo_check_runs(cmd, prefixes):
+    """(name, mode) for each simple command of `cmd` that starts with one of
+    `prefixes`, after assignments and VERIFY's wrappers. Read with
+    `_shell_commands`, so a prefix inside a quoted argument, a commit message or
+    a QUOTED heredoc body (`<<'EOF'`, `<<"EOF"`) is an argument, not a run - the
+    masked reading VERIFY keeps. An unquoted heredoc's body (`<<EOF`, `<<-EOF`)
+    is read as commands, so `cat > x <<EOF` over a `./bin/run-tool` line counts
+    as a run, as a `pytest` line there does for VERIFY.
+    ponytail: a wrapper's own option (`sudo -u root ./bin/x`) hides the program,
+    a lost credit rather than an invented one."""
+    for words, _sep in _shell_commands(cmd):
+        i = 0
+        while i < len(words) and (words[i] in CHECK_WRAPPERS
+                                  or ASSIGNMENT_WORD.match(words[i])):
+            i += 1
+        run = words[i:]
+        if not run:
+            continue
+        head = [os.path.normpath(run[0])] + run[1:]
+        for prefix in prefixes:
+            if head[:len(prefix)] == prefix:
+                name = " ".join(run[:len(prefix)])
+                rest = " ".join(run[len(prefix):])
+                yield name, ("info" if INFO_ARGS.search(rest) else "check")
+                break
+
+
+def verify_command(cmd, cwd=None):
     """The name of the check this command runs, or None.
 
     The scan runs on the masked text, the convention `shortcut_command` already
@@ -1920,8 +2173,9 @@ def verify_command(cmd):
     (`_check_runs`), so every consumer - the evidence kind, the gate's retry
     exemption, its began `check` mark, `piped_check` and the NEUTER rule - reads
     them as the plain commands they are. A JS tool names itself, not its runner
-    (`npx axe-core` is `axe-core`)."""
-    return next((name for name, mode in _check_runs(cmd) if mode == "check"),
+    (`npx axe-core` is `axe-core`). `cwd` adds the repository's declared checks
+    (`repo_checks`); without it only the built-in vocabulary counts."""
+    return next((name for name, mode in _check_runs(cmd, cwd) if mode == "check"),
                 None)
 
 
@@ -1994,6 +2248,46 @@ def _closes(cmd, pos, tag, strip, message):
     return None, n
 
 
+# bash's metacharacters: unquoted, each one ends a word. Any other character -
+# an escaped or quoted one, a `\r`, a non-breaking space - is part of a word.
+WORD_BREAKS = " \t\n;&|()<>"
+# A line continuation: outside single quotes and comments bash deletes both
+# characters, so the words around it join (`-de\<nl>lete` is `-delete`) and
+# the word before it goes on (`x\<nl>#` is the word `x#`). After an escaped
+# backslash (`a\\<nl>`) the newline is a real one and ends the command.
+CONTINUATION = "\\\n"
+
+
+def _opens_comment(prev):
+    """True when an unquoted, unescaped `#` opens a comment: only at the start
+    of a word. `prev` is the last character bash kept before it - "" at the
+    start of the text, a non-break for an escaped or quoted one, and the one
+    before a CONTINUATION, which is no character. The one rule every shell
+    reader asks (`_heredocs`, `_shell_lines`, `mask`, `_shell_read`, and the
+    gate's `_shell_words` through `_shell_lines`), so none of them reads a
+    comment where bash runs a command (review of plan 126, round 3h)."""
+    return not prev or prev in WORD_BREAKS
+
+
+# What before a `(` makes it part of a word: a command or process substitution
+# or an arithmetic expansion (`$(`, `<(`, `>(`, `$((`) and an array (`x=(`).
+WORD_PARENS = "$<>="
+
+
+def _kept(ch, before, parens):
+    """`ch` as the `prev` `_opens_comment` asks of the character after it: a
+    `)` closing a `(` opened right after WORD_PARENS ends no word (`$(:)#x` is
+    one word, so bash runs a command after it), and reads as "_"; a subshell's,
+    an arithmetic command's or a `case` pattern's `)` is a break. `before` is
+    the character kept before `ch` and `parens` the reader's stack of open `(`
+    (review of plan 126, round 3i)."""
+    if ch == "(":
+        parens.append(bool(before) and before in WORD_PARENS)
+    elif ch == ")" and parens and parens.pop():
+        return "_"
+    return ch
+
+
 def _heredocs(cmd):
     """Every heredoc operator in `cmd`, in order, as (operator start, operator
     end, tag, quoted, body start, terminator span or None, safe).
@@ -2015,10 +2309,13 @@ def _heredocs(cmd):
     bash runs - so the reader no longer decides where such a context ends: it
     shows the text. A false refusal of data is the accepted cost
     (tests/bash_vectors.ACCEPTED_REFUSALS)."""
-    n, found, pending, i = len(cmd), [], [], 0
-    quote, depth, sure, line_start = None, 0, True, 0
+    n, found, pending, i, parens = len(cmd), [], [], 0, []
+    quote, depth, sure, line_start, last = None, 0, True, 0, ""
     while i < n:
         ch = cmd[i]
+        # `last` is the character bash kept before `ch`: a quoted or escaped
+        # one leaves "_", a non-break, unless a branch below says otherwise
+        before, last = last, "_"
         if quote in ("'", "$'"):
             if ch == "\\" and quote == "$'":
                 i += 2
@@ -2028,6 +2325,8 @@ def _heredocs(cmd):
             i += 1
             continue
         if ch == "\\":
+            if cmd.startswith(CONTINUATION, i):
+                last = before
             i += 2
             continue
         if quote == '"':
@@ -2039,7 +2338,7 @@ def _heredocs(cmd):
             continue
         if ch == "\n":
             if not pending:
-                line_start = i + 1
+                line_start, last = i + 1, ch
                 i += 1
                 continue
             pos = i + 1
@@ -2053,7 +2352,7 @@ def _heredocs(cmd):
                 pos = i + 1
             pending = []
             continue
-        if ch == "#" and (i == 0 or cmd[i - 1] in " \t\n;&|()<>"):
+        if ch == "#" and _opens_comment(before):
             end = cmd.find("\n", i)
             i = n if end < 0 else end
             continue
@@ -2078,7 +2377,7 @@ def _heredocs(cmd):
             i += 1
             continue
         if cmd.startswith("<<<", i):
-            i += 3
+            i, last = i + 3, "<"
             continue
         if cmd.startswith("<<", i):
             j = i + 2
@@ -2102,7 +2401,7 @@ def _heredocs(cmd):
             depth += 1
         elif ch in ")]}":
             depth -= 1
-        i += 1
+        i, last = i + 1, _kept(ch, before, parens)
     found += [(s, e, t, q, n, None, False) for s, e, t, q, _, _ in pending]
     return found
 
@@ -2151,50 +2450,81 @@ def _heredoc_bytes(text):
 
 def mask(text):
     """A shell line with quoted strings, comments and heredoc bodies blanked,
-    length and newlines kept, read the way bash reads it: `'...'` takes no
-    escape, `$'...'` (an unescaped `$` only) and `"..."` do, a `\\` outside
-    quotes escapes one character, and `#` starts a comment only at the start of
-    a word. So `https://x`, `a#b`, `src/*.py ... lib/*/`, `'x\\'` and `\\$'x\\'`
-    are words, not a comment or an open string that blanks the command after
-    them (gate-01). A quote left open blanks from itself to the end - bash runs
-    nothing after it - and keeps the reading before it.
+    length kept, read the way bash reads it: `'...'` takes no escape, `$'...'`
+    (an unescaped `$` only) and `"..."` do, a `\\` outside quotes escapes one
+    character, and `#` starts a comment only at the start of a word. So
+    `https://x`, `a#b`, `src/*.py ... lib/*/`, `'x\\'` and `\\$'x\\'` are words,
+    not a comment or an open string that blanks the command after them
+    (gate-01). A quote left open blanks from itself to the end - bash runs
+    nothing after it - and keeps the reading before it. A CONTINUATION bash
+    deletes (outside single quotes, `$'...'` and comments) is moved to its
+    word's start as two spaces, so every rule reads the token bash joins
+    (`tr\\<nl>ue` is `true`, `|\\<nl>|` is `||`) at offsets `joined` keeps
+    (review of plan 126, round 3i).
 
     Memoised per process: a pure function of the text, and one Stop asks it of
     the same ledger details from several readers (both Stop folds, plan 063)."""
-    return _mask(str(text or ""))
+    return _mask(str(text or ""))[0]
+
+
+def joined(text):
+    """The raw `text` with each CONTINUATION moved as `mask` moves it: the text
+    a rule slices at the offsets a masked match proved."""
+    text = str(text or "")
+    return _moved(list(text), _mask(text)[1])
+
+
+def _moved(out, cuts):
+    for word, at in cuts:
+        out[word + 2:at + 2] = out[word:at]
+        out[word:word + 2] = "  "
+    return "".join(out)
 
 
 @functools.lru_cache(maxsize=4096)
 def _mask(text):
+    """(the masked text, the (word start, offset) of each CONTINUATION moved)."""
     text = _blank_heredocs(text)
     body = _heredoc_bytes(text)
     out, i, n, start, prev = list(text), 0, len(text), True, ""
+    parens, word, cuts = [], 0, []
     while i < n:
         ch = text[i]
         if body[i]:
-            i, start, prev = i + 1, True, ""
+            i, start, prev, word = i + 1, True, "", i + 1
             continue
         if ch == "\\":
-            i, start, prev = i + 2, False, ""
+            # a CONTINUATION is no character: the word state before it goes on
+            if text.startswith(CONTINUATION, i):
+                cuts.append((word, i))
+            else:
+                start, prev = False, ""
+            i += 2
             continue
         if ch in "'\"":
             escapes = ch == '"' or prev == "$"
             end = i + 1
             while end < n and text[end] != ch:
-                end += 2 if escapes and text[end] == "\\" else 1
+                if escapes and text[end] == "\\":
+                    if ch == '"' and text.startswith(CONTINUATION, end):
+                        cuts.append((word, end))
+                    end += 1
+                end += 1
             end = min(end + 1, n)
         elif ch == "#" and start:
             end = text.find("\n", i)
             end = n if end < 0 else end
         else:
-            start, prev = ch.isspace() or ch in ";&|()<>", ch
+            start, prev = _opens_comment(_kept(ch, prev, parens)), ch
             i += 1
+            if ch in " \t\n":
+                word = i
             continue
         for k in range(i, end):
             if out[k] != "\n":
                 out[k] = " "
         i, start, prev = end, False, ""
-    return "".join(out)
+    return _moved(out, cuts), tuple(cuts)
 
 
 def _unquoted_backticks(text):
@@ -2215,6 +2545,17 @@ def _unquoted_backticks(text):
         elif ch in "'\"":
             quote = ch
         elif ch == "`":
+            # a `#` right after it, continuations aside, opens no comment
+            # (`_opens_comment` sees `;`): bash reads it mid-word after the
+            # close, and a comment inside the body ends at the close, so it is
+            # escaped here (review of plan 126, round 3i: `` `:`\<nl># ``)
+            j = i + 1
+            while text.startswith(CONTINUATION, j):
+                j += 2
+            if text.startswith("#", j):
+                out.append(";" + text[i + 1:j] + "\\#")
+                i = j + 1
+                continue
             ch = ";"
         out.append(ch)
         i += 1
@@ -2257,28 +2598,32 @@ def _for_shlex(text):
 def _shell_lines(text):
     """`text` split at the newlines that end a command in bash: none inside
     quotes (`'...'`, `"..."`, `$'...'`), each one in a heredoc body or its
-    terminator (`_heredoc_bytes`), and a comment - `#` at the start of a word -
-    dropped to its line end. A double-quoted string holding a `$( )` or a
-    backtick runs a command, so its newlines still split - the reading this had
-    before, which keeps that command visible. A quote left open at the end goes
-    back to a split at every newline from its line on."""
+    terminator (`_heredoc_bytes`), a CONTINUATION deleted outside single quotes
+    (in `$'...'` it stays, as bash keeps it), and a comment - `#` where
+    `_opens_comment` - dropped to its line end. A double-quoted string holding
+    a `$( )` or a backtick runs a command, so its newlines still split - the
+    reading this had before, which keeps that command visible. A quote left
+    open at the end goes back to a split at every newline from its line on."""
     body = _heredoc_bytes(text)
-    lines, cur, quote, start, i, n = [], [], None, True, 0, len(text)
-    opened, runs = 0, False
+    lines, cur, quote, prev, i, n = [], [], None, "", 0, len(text)
+    opened, runs, parens = 0, False, []
     while i < n:
         ch = text[i]
         if body[i] or (not quote or runs) and ch in "\r\n":
             if ch in "\r\n":
                 lines.append("".join(cur))
-                cur, quote, start, runs = [], None, True, False
-                i += 2 if text[i:i + 2] == "\r\n" else 1
+                cur, quote, runs = [], None, False
+                step = 2 if text[i:i + 2] == "\r\n" else 1
+                # a lone `\r` is no word break to bash: the split shows more
+                prev, i = text[i + step - 1], i + step
             else:
                 cur.append(ch)
                 i += 1
             continue
         if quote:
             if ch == "\\" and quote != "'" and i + 1 < n:
-                cur.append(text[i:i + 2])
+                if quote != '"' or not text.startswith(CONTINUATION, i):
+                    cur.append(text[i:i + 2])
                 i += 2
                 continue
             if ch == quote[-1]:
@@ -2286,17 +2631,19 @@ def _shell_lines(text):
             elif quote == '"' and (ch == "`" or text.startswith("$(", i)):
                 runs = True
         elif ch == "\\" and i + 1 < n:
-            cur.append(text[i:i + 2])
-            i, start = i + 2, False
+            if not text.startswith(CONTINUATION, i):
+                cur.append(text[i:i + 2])
+                prev = "_"
+            i += 2
             continue
-        elif ch == "#" and start:
+        elif ch == "#" and _opens_comment(prev):
             while i < n and text[i] not in "\r\n":
                 i += 1
             continue
         elif ch in "'\"":
             quote = "$'" if ch == "'" and cur and cur[-1] == "$" else ch
             opened = len(lines)
-        start = not quote and (ch.isspace() or ch in ";&|()<>")
+        prev = "_" if quote or ch in "'\"" else _kept(ch, prev, parens)
         cur.append(ch)
         i += 1
     lines.append("".join(cur))
@@ -2312,8 +2659,9 @@ def _shell_commands(cmd):
     A `$( )` or backtick body is a command of its own, ended by `$)`, and the
     command around it goes on after its close with a `$()` word in its place."""
     out = []
-    text = _blank_heredocs(str(cmd or "")).replace("\\\n", "  ")
+    text = _blank_heredocs(str(cmd or ""))
     for line in map(_for_shlex, _shell_lines(text)):
+        line = FD_REDIRECT.sub(r"\2", line)
         try:
             lex = shlex.shlex(line, posix=True, punctuation_chars=";&|()<>")
             lex.whitespace_split = True
@@ -2328,10 +2676,9 @@ def _shell_commands(cmd):
             if word == "&" and i < len(words) and REDIRECTION.match(words[i]):
                 continue  # `&>` is a redirection, not a separator
             if REDIRECTION.match(word):
-                # the fd before the operator (`2>`), an `&` with its fd (`>&2`),
-                # or the target after it - none of them is an argument
-                if cur and cur[-1].isdigit():
-                    cur.pop()
+                # an `&` with its fd (`>&2`), or the target after it - neither is
+                # an argument. The fd number is cut from the line before shlex
+                # (FD_REDIRECT), because `1<` is an fd and `1 <` a program word.
                 after_redir = True
                 continue
             if after_redir:
@@ -2339,6 +2686,13 @@ def _shell_commands(cmd):
                     continue  # `>&2`: the `&` belongs to the operator
                 after_redir = False
                 continue
+            if word.startswith("((") and cur and cur[-1].endswith("$"):
+                # `$(( ))` is arithmetic: its own words are no commands, though
+                # a `$( )` inside one still is and is entered below
+                cur[-1] += "()"
+                subs.append([cur, 1, True])
+                cur = []
+                continue
             if not (word and word[0] in ";&|()"):
                 cur.append(word)
                 continue
@@ -2350,21 +2704,32 @@ def _shell_commands(cmd):
                     continue
                 if subs and piece == "(":
                     subs[-1][1] += 1
+                    if len(subs[-1]) > 2:  # a grouping paren inside arithmetic
+                        cur = []
+                        continue
                 elif subs and piece == ")":
                     if not subs[-1][1]:
-                        if cur:
+                        arith = len(subs[-1]) > 2
+                        if cur and not arith:
                             out.append([cur, "$)"])
                         cur = subs.pop()[0]
                         continue
                     subs[-1][1] -= 1
+                    if len(subs[-1]) > 2:  # still the arithmetic's own paren
+                        cur = []
+                        continue
                 if cur:
                     out.append([cur, piece])
                 elif out:
                     out[-1][1] += piece
                 cur = []
-        for seg in [cur] + [outer for outer, _open in reversed(subs)]:
+        # an arithmetic sub holds no command of its own, only any `$( )` in it,
+        # which was emitted when it closed
+        for seg in [cur] + [sub[0] for sub in reversed(subs) if len(sub) < 3]:
             if seg:
                 out.append([seg, "\n"])
+            elif out:  # the line ended on a close: its newline is still a break
+                out[-1][1] += "\n"
     if out and out[-1][1] == "\n":
         out[-1][1] = ""
     return out
@@ -2374,7 +2739,8 @@ def _shell_segments(cmd):
     """The line's simple commands as word lists, read the way
     `tezgah_context.shell_programs` reads a line - shlex, posix, punctuation
     `;&|()<>` - so quotes and escapes are gone, heredoc bodies are blanked first,
-    a continued line is joined, a newline ends a command only where bash ends
+    a continued line is joined (CONTINUATION, in `_shell_lines`, which knows
+    where bash deletes one), a newline ends a command only where bash ends
     one (`_shell_lines`), a `$'...'` is one word (`_for_shlex`), and a `$( )` or
     backtick body is a command of its own (`_shell_commands`). A line shlex
     cannot read is read roughly (`ROUGH_WORDS`) rather than dropped.
@@ -2639,7 +3005,7 @@ def pipe_hides_status(cmd):
 OWNING_SEP = re.compile(r"^[()]*(?:&&|\|&?)[()]*$")
 
 
-def status_hidden(cmd):
+def status_hidden(cmd, cwd=None):
     """True when the line's exit status is not its check's: a pipe owns it
     (`pipe_hides_status`), or a command after the check does - the check is
     followed by `;` or a newline and more commands, or is sent to the background
@@ -2648,16 +3014,21 @@ def status_hidden(cmd):
     status. A heredoc body and its terminator are data here, and an `exit $?`
     (or a bare `exit`) right after the check ends the line with the check's
     status. Read with `_shell_commands`, each command re-quoted for
-    `verify_command`. ponytail: `set -e` is not read, so `set -e; pytest; echo
-    done` records as ran - a lost credit, never an invented one."""
+    `verify_command`; `cwd` reads the repository's declared checks
+    (`repo_checks`) as checks too, so `./bin/run-tool x; echo done` is hidden
+    the way `pytest; echo done` is. ponytail: `set -e` is not read, so `set -e;
+    pytest; echo done` records as ran - a lost credit, never an invented one."""
     if pipe_hides_status(cmd):
         return True
     cmd = str(cmd or "")
     body = _heredoc_bytes(cmd)
     cmds = _shell_commands("".join(" " if b and ch != "\n" else ch
                                    for ch, b in zip(cmd, body)))
+    prefixes = repo_checks(cwd)
     for i, (words, _sep) in enumerate(cmds):
-        if not verify_command(shlex.join(words)):
+        line = shlex.join(words)
+        if not (verify_command(line) or any(
+                mode == "check" for _n, mode in _repo_check_runs(line, prefixes))):
             continue
         for k in range(i, len(cmds) - 1):
             if OWNING_SEP.match(cmds[k][1]):
@@ -2685,9 +3056,10 @@ def piped_check(cmd):
     c = mask(cmd)
     if PIPEFAIL.match(c):
         return None
-    raw = str(cmd or "")
+    raw = joined(cmd)
     pos, check = 0, None
-    # mask keeps every offset, so a stage's span in `c` is its text in `raw`
+    # mask keeps every offset of `joined`, so a stage's span in `c` is its text
+    # in `raw`
     for part in re.split(r"(&&|\|\||;|\n|\|)", c):
         if part in ("&&", "||", ";", "\n"):
             check = None
@@ -2793,14 +3165,15 @@ def shortcut_edit(inp):
     return None
 
 
-def classify(tool, inp):
-    """The evidence kind for a tool call, or None. Shared by the host hooks."""
+def classify(tool, inp, cwd=None):
+    """The evidence kind for a tool call, or None. Shared by the host hooks.
+    `cwd` lets the repository's declared checks (`repo_checks`) count."""
     t = str(tool or "").lower()
     if t in WRITE_TOOLS:
         return "edit"
     if t in BASH_TOOLS:
         cmd = inp.get("command") or inp.get("cmd") or ""
-        return "verify" if verify_command(cmd) else "run"
+        return "verify" if verify_command(cmd, cwd) else "run"
     return None
 
 
@@ -2990,7 +3363,12 @@ TIER_LOCAL_ARGS = ("-h", "--help", "--use")
 UNTRUSTED_CHANNEL = {"web": "a web result", "mcp": "an MCP server",
                      "network": "a network read",
                      "tier": "an external model answer",
-                     "subagent": "a subagent's report"}
+                     "subagent": "a subagent's report",
+                     "repo": "a tool this repository declares untrusted"}
+# The sixth channel is the repository's own: its manifest's `untrusted` list
+# names programs whose output is someone else's text - a scanner reading a
+# target, a fetcher this file cannot know (`tezgah_extension.untrusted_programs`).
+REPO_CHANNEL = "repo"
 # A delegate's report is the fifth channel, and the one no host counted: what a
 # subagent hands back is prose this session did not write and cannot vouch for,
 # read by a parent that never watched it being produced. Spelled the way every
@@ -3018,14 +3396,35 @@ def _tier_read(cmd):
     return False
 
 
-def untrusted_source(tool, inp):
+def _repo_untrusted(cmd, cwd):
+    """True when this shell line runs a program the repository at `cwd` (None:
+    the hook process's directory) declares untrusted. Read at a command
+    position by `shell_programs`, so a mention in an argument is not a run.
+    Imported here for `_tier_read`'s reason; a broken extension, or a process
+    directory that is gone, costs the channel, never the call."""
+    try:
+        import tezgah_extension
+        from tezgah_context import shell_programs
+        names = tezgah_extension.untrusted_programs(cwd or os.getcwd())
+        return bool(names) and bool(names.intersection(shell_programs(cmd)))
+    except Exception:
+        return False
+
+
+def untrusted_source(tool, inp, cwd=None):
     """The untrusted channel this call's result came through, or None.
 
     Decided from the call, because that is all a PostToolUse hook sees: the
     tool's name for the two named channels, the masked command text for a shell
     read that left the machine. None means the result is the user's or this
     workspace's, which is the normal case - the label names the exception, so it
-    never becomes noise the model learns to skip."""
+    never becomes noise the model learns to skip.
+
+    `cwd` is where the repository's `untrusted` declaration is read from; None
+    reads the call's own `cwd`/`workdir`, else the hook process's directory.
+    ponytail: the callers pass no cwd today, so a host that runs its hook
+    elsewhere than the session reads no declaration - a missed label, never a
+    false one."""
     name = str(tool or "").strip().lower()
     if MCP_TOOL.match(name):
         return "mcp"
@@ -3039,6 +3438,9 @@ def untrusted_source(tool, inp):
         return "network"
     if name in BASH_TOOLS and _tier_read(cmd):
         return "tier"
+    if name in BASH_TOOLS and cmd and _repo_untrusted(
+            cmd, cwd or inp.get("cwd") or inp.get("workdir")):
+        return REPO_CHANNEL
     return None
 
 
@@ -3380,9 +3782,9 @@ def note_tool(session_id, tool, inp, failed=None, *, interrupted=False,
              workspace=root_for(cwd) if cwd else None)
         return
     cmd = str(inp.get("command") or inp.get("cmd") or "")
-    kind = classify(tool, inp)
+    kind = classify(tool, inp, cwd)
     if kind == "verify":
-        if failed is None or status_hidden(cmd) or (empty_run and not failed):
+        if failed is None or status_hidden(cmd, cwd) or (empty_run and not failed):
             kind = "verify"
         else:
             kind = "verify_fail" if failed else "verify_ok"
@@ -3692,7 +4094,15 @@ def passing_check(entry):
         return False
     if entry.get(ORPHAN) or entry.get("exit") != 0 or entry.get("out_bytes") == 0:
         return False
-    return not status_hidden(entry.get("detail"))
+    # The row carries no cwd: its one location is `repo`, which `_check_repo`
+    # sets only when the call named where it ran (a `cwd`/`workdir` argument, a
+    # leading `cd X`, path arguments in one repository) and leaves None
+    # otherwise. So this re-read sees the repository's declared checks
+    # (`repo_checks`) only on such a row; on the rest it reads the built-in
+    # vocabulary alone. The reading that holds `./bin/run-tool x; echo done` to
+    # `verify` is `note_tool`'s, with the call's own cwd - this one guards a
+    # `verify_ok` row another writer appended, as far as its `repo` reaches.
+    return not status_hidden(entry.get("detail"), entry.get("repo"))
 
 
 def _changed_write(row):
@@ -3949,7 +4359,26 @@ def _ui_evidence(rows):
     return write, proof
 
 
-def _design_evidence(rows):
+def _slop_row_holds(row, cwd):
+    """True when a `tezgah-design slop` row is evidence for THIS repository.
+
+    The verdict is a file, so the command alone is not enough: a scan pointed at
+    another tree (`--repo <fixture>`) would pass a component edit it never looked
+    at (review of plan 133, finding 5). The repo the row names, or the row's own
+    cwd when it names none, has to be the session's repository."""
+    detail = mask(str(row.get("detail") or ""))
+    named = SLOP_REPO.search(detail)
+    target = named.group(1).strip("'\"") if named else ""
+    base = os.path.realpath(os.path.abspath(cwd or os.getcwd()))
+    root = _toplevel(base) or base
+    want = os.path.realpath(root)
+    if not target or target in (".", "./"):
+        return True
+    path = os.path.realpath(os.path.join(root, os.path.expanduser(target)))
+    return path == want or path.startswith(want + os.sep)
+
+
+def _design_evidence(rows, cwd=None):
     """(component, check) as row indices for the design-contract half of the UI
     rule, -1 for either when the row is not there.
 
@@ -3966,6 +4395,8 @@ def _design_evidence(rows):
         if _ui_write(row) and DESIGN_COMPONENT.search(detail):
             component = i
         if passing_check(row) and DESIGN_CHECK.search(detail):
+            if DESIGN_SLOP.search(detail) and not _slop_row_holds(row, cwd):
+                continue
             check = i
     return component, check
 
@@ -4578,6 +5009,12 @@ GIT_BOOKKEEPING = frozenset((
 # is work - an unknown program owes the check, a known one never excuses a write.
 GIT_READS = GIT_BOOKKEEPING - {"add", "commit", "push", "fetch", "branch", "tag",
                                "remote"}
+# `set`'s flags that only change when the shell stops or what it traces: the
+# `set -o pipefail;` prefix the contract asks a check line for. Anything else
+# is no read: `-k` and `+o interactive-comments` change how the rest of the
+# line runs, a plain word sets the positional parameters.
+SET_FLAGS = re.compile(r"[-+][euxvo]+")
+SET_NAMES = frozenset(("pipefail", "errexit", "nounset", "xtrace", "verbose"))
 # ssh's options that take the next word, so the host is read after them
 SSH_VALUE_OPTS = frozenset(("-b", "-c", "-D", "-E", "-e", "-F", "-I", "-i", "-J",
                             "-L", "-l", "-m", "-O", "-o", "-p", "-Q", "-R", "-S",
@@ -4607,6 +5044,7 @@ SUBCOMMAND_READS = {"gh": (("pr", "view"), ("pr", "list"), ("issue", "view"),
 # all (review F6), as a pattern read at an argument's start: git's `--output`
 # and external diff/textconv drivers, ripgrep's `--pre`, find's actions, a
 # short-option cluster holding sort's `-o`, sed's `-i`/`-f`, awk's `-i`/`-f`,
+# printf's `-v` (it assigns a variable, PATH included: plan 126),
 # and curl's writes to a file and non-GET requests. `tree` and `file` left the
 # list instead of growing one here: tree writes through clustered short options
 # (`-fo out`) and `-R -H`, file through `-C` (review N4).
@@ -4615,6 +5053,7 @@ WRITING_OPTIONS = {
     "rg": re.compile(r"--pre"),
     "find": re.compile(r"-(?:delete|exec|execdir|ok|okdir|fprint0?|fprintf|fls)$"),
     "sort": re.compile(r"-[^-]*o|--output"),
+    "printf": re.compile(r"-v"),
     "sed": re.compile(r"-[^-]*[if]|--(?:in-place|file)"),
     "awk": re.compile(r"-[^-]*[if]|--(?:include|file|load)"),
     "gawk": re.compile(r"-[^-]*[if]|--(?:include|file|load|inplace)"),
@@ -4626,9 +5065,32 @@ WRITING_OPTIONS = {
 GIT_CONFIG_OPTS = ("-c", "--config-env", "--exec-path")
 # an fd duplication or a discard: a redirect that writes no file
 HARMLESS_REDIRECT = re.compile(r"\d*>&\d+|\d*>>?\s*/dev/null\b")
-
-
-def _shell_read(cmd):
+# The compound-command words `loops=True` reads (plan 126): an opener is no
+# program (the command after it is: `do cat "$f"`), a closer runs nothing
+SHELL_OPENERS = frozenset(("if", "then", "elif", "else", "do", "while", "until",
+                           "!", "{"))
+SHELL_CLOSERS = frozenset(("done", "fi", "}"))
+# a loop variable no shell reads: one lowercase letter. A longer lowercase
+# name can be one zsh ties to a setting (`path` is PATH, and `cdpath`, `fpath`,
+# `manpath`, `module_path`, `psvar`, `watch`, `histchars`, `prompt`, `status`
+# and the modules' `options`, `mapfile`... are its own), and its list grows
+# with every loaded module
+LOOP_NAME = re.compile(r"[a-z]")
+# A word this reader passes on: bash expands neither a brace list nor an
+# operator form to anything it can read. `{-delete,-print}` is two words,
+# `${x:--delete}` an option, `$[x]`, `$((x))` and `${a[x]}` evaluate x as
+# arithmetic, which runs a `$( )` in its value. Read on `_shell_read`'s masks.
+BRACE_EXPANSION = re.compile(r"\{[^\s;|&<>()]*(?:,|\.\.)[^\s;|&<>()]*\}")
+PLAIN_DOLLAR = re.compile(r"\$(?:[A-Za-z_]\w*|\{(?:[A-Za-z_]\w*|[0-9@*#?$!-])\}|"
+                          r"[0-9@*#?$!-]|(?![\[{(]))")
+# a function's arguments: values this reader never sees
+POSITIONAL = re.compile(r"\$\{?[0-9@*#]")
+# the readers no option of which writes or runs: the only ones a value this
+# reader never sees (a loop word, a substitution's output) may reach
+OPTION_FREE = READ_ONLY_PROGRAMS - set(WRITING_OPTIONS)
+
+
+def _shell_read(cmd, subst=False):
     """(effect, text) for `cmd`: whether bash would run a command or process
     substitution, or redirect into a file, anywhere in it - or this reader
     cannot tell - and the command with what is not a command blanked for
@@ -4645,7 +5107,16 @@ def _shell_read(cmd):
 
     Fails closed (effect True): an unquoted heredoc expands `$(` in its body,
     an unterminated one or an empty delimiter cannot be read, and a quote still
-    open at the end means the reading lost sync with bash (review N1)."""
+    open at the end means the reading lost sync with bash (review N1).
+
+    Also an effect: a brace expansion (unquoted `{a,b}`), a function definition
+    (`name()`: its body runs with arguments read nowhere), and a word whose `$`
+    is more than a plain `$name`/`${name}` or holds a `[` (`PLAIN_DOLLAR`;
+    double quotes still expand it, single quotes do not).
+
+    `subst=True` reads an unquoted `$(` as no effect of its own: its body is a
+    command `_shell_segments` returns, and its redirects are in the bare text;
+    inside double quotes it stays one word that reader never splits."""
     n, out = len(cmd), list(cmd)
 
     def blank(a, b):
@@ -4659,7 +5130,8 @@ def _shell_read(cmd):
         blank(start, stop)
         blank(body, term[1])
     cmd = "".join(out)
-    bare, quote, i = [], None, 0
+    bare, lit, dq, quote, i = [], [], [], None, 0
+    kept, parens = "", []  # lit's last character as `_opens_comment` asks it
     while i < n:
         ch = cmd[i]
         if quote == "'":
@@ -4670,14 +5142,25 @@ def _shell_read(cmd):
             elif ch == "'":
                 quote = None
         elif ch == "\\":
+            # a CONTINUATION: bash deletes both, so `$\<nl>1` is `$1` and
+            # nothing is left in the word
+            if cmd.startswith(CONTINUATION, i):
+                i += 2
+                continue
             i += 2
             bare.append(" ")
+            lit.append("_")
+            dq.append("_")
+            kept = "_"
             continue
-        elif ch == "`" or cmd.startswith("$(", i):
+        elif ch == "`" or (cmd.startswith("$(", i) and (quote or not subst)):
             return True, ""
         elif quote == '"':
             quote = None if ch == '"' else quote
-        elif ch == "#" and (i == 0 or cmd[i - 1] in " \t\n;&|()<>"):
+        # a `#` opens a comment only at a word's start (`_opens_comment`): after
+        # an escaped or quoted character (`x\ #...`) or a substitution's `)`
+        # (`_kept`) it is part of the word
+        elif ch == "#" and _opens_comment(kept):
             end = cmd.find("\n", i)
             end = n if end < 0 else end
             blank(i, end)
@@ -4690,19 +5173,53 @@ def _shell_read(cmd):
             quote = ch
         else:
             bare.append(ch)
+            lit.append(ch)
+            dq.append(ch)
+            kept = _kept(ch, kept, parens)
             i += 1
             continue
         bare.append(" ")
+        # `lit` keeps only unquoted text, `dq` double-quoted text too
+        lit.append("_")
+        kept = "_"
+        dq.append(ch if quote == '"' or ch == '"' and not quote else "_")
         i += 1
     if quote:
         return True, ""
+    lit, dq = "".join(lit), "".join(dq)
+    if BRACE_EXPANSION.search(lit) or re.search(r"\(\s*\)", lit) or "$((" in dq:
+        return True, ""
+    for word in re.split(r"[\s;&|()<>]+", dq):
+        if "$" in word and ("[" in word or "$" in PLAIN_DOLLAR.sub("", word)):
+            return True, ""
+    # a positional parameter is a value no read here sees: where loops read
+    # (`subst`), a `$1` the shell expands - unquoted or double-quoted, never one
+    # inside single quotes, a comment or a heredoc body - makes the command work
+    if subst and POSITIONAL.search(dq):
+        return True, ""
     text = HARMLESS_REDIRECT.sub(" ", "".join(bare))
     # every `<` left is an input redirect or a here-string, both reads; blanking
     # them keeps `_shell_segments`' own heredoc pass from reading one again
     return ">" in text or "<(" in text, "".join(out).replace("<", " ")
 
 
-def _bookkeeping_command(cmd, git=GIT_BOOKKEEPING):
+def _set_options(args):
+    """True when `set`'s words are only SET_FLAGS, each `o` in them followed by
+    a SET_NAMES name or by nothing (`set -o` prints the options). A bare `set`
+    prints every variable, and stays work like any other unlisted shape."""
+    j = 0
+    while j < len(args):
+        if not SET_FLAGS.fullmatch(args[j]):
+            return False
+        for _ in range(args[j].count("o")):
+            j += 1
+            if j < len(args) and args[j] not in SET_NAMES:
+                return False
+        j += 1
+    return bool(args)
+
+
+def _bookkeeping_command(cmd, git=GIT_BOOKKEEPING, loops=False):
     """True when every simple command of `cmd` reads, or runs a git subcommand
     in `git` (VCS bookkeeping that changes no working-tree file by default,
     GIT_READS for a pure read). A redirect, a substitution, an env assignment
@@ -4713,21 +5230,40 @@ def _bookkeeping_command(cmd, git=GIT_BOOKKEEPING):
     `codegraph` with a read verb (`SUBCOMMAND_READS`). `sqlite3` reads with a
     read-only open (the option, or `mode=ro` in the database URI) and no
     writing dot-command or stdin (`SQLITE_WRITE`), `ssh` with a remote command
-    that is itself one of these reads.
+    that is itself one of these reads, `set` with shell options only
+    (`_set_options`).
+
+    `loops=True` (plan 126) also reads a `for NAME in WORDS` loop, the
+    `if`/`while`/`{` openers and closers around reads, and an unquoted `$( )`
+    whose body reads. The values those bind - a loop word, a substitution's
+    output, a positional parameter (`POSITIONAL`) - are text this reader never
+    sees, so in such a command a `$` word may only reach a reader no option of
+    which writes (`OPTION_FREE`), and the loop variable is one letter no shell
+    reads (`LOOP_NAME`).
 
     ponytail: `git commit` and `git push` run the repository's hooks, and a
     pre-commit autofixer can rewrite files the row never names. They stay on
     the list because refusing every commit was the measured cost (audit CHAT-04);
     a hook that rewrites the tree is invisible here."""
     raw = str(cmd or "").replace(FAILED_MARK, "")
-    effect, text = _shell_read(raw) if raw.strip() else (True, "")
+    effect, text = _shell_read(raw, loops) if raw.strip() else (True, "")
     if effect:
         return False
     segs = _shell_segments(text)
+    unseen = loops and any("for" in w or any("$(" in a for a in w) for w in segs)
     for words in segs:
         i = 0
-        while i < len(words) and words[i] in GIT_WRAPPER:
+        while i < len(words) and (words[i] in GIT_WRAPPER
+                                  or loops and words[i] in SHELL_OPENERS):
             i += 1
+        if loops and all(w in SHELL_OPENERS for w in words[:i]) and (
+                i == len(words) or words[i:] == words[-1:] and words[i] in SHELL_CLOSERS):
+            continue
+        if loops and words[i:i + 1] == ["for"]:
+            if not (words[i + 1:] and LOOP_NAME.fullmatch(words[i + 1])
+                    and words[i + 2:i + 3] in ([], ["in"])):
+                return False
+            continue
         if i >= len(words) or ENV_WORD.match(words[i]):
             return False
         # a program named by a path is whatever that file is, not the
@@ -4735,6 +5271,8 @@ def _bookkeeping_command(cmd, git=GIT_BOOKKEEPING):
         if "/" in words[i]:
             return False
         program, args = words[i], words[i + 1:]
+        if unseen and program not in OPTION_FREE and any("$" in a for a in args):
+            return False
         writes = WRITING_OPTIONS.get(program)
         if writes and any(writes.match(a) for a in args):
             return False
@@ -4745,6 +5283,10 @@ def _bookkeeping_command(cmd, git=GIT_BOOKKEEPING):
             if any(SCRIPT_WRITE[program].search(a) for a in plain):
                 return False
             continue
+        if program == "set":
+            if not _set_options(args):
+                return False
+            continue
         if program == "uniq":
             # `uniq IN OUT` writes its second operand
             if len(plain) > 1:
@@ -4786,7 +5328,7 @@ def _bookkeeping_command(cmd, git=GIT_BOOKKEEPING):
     return bool(segs)
 
 
-def _bookkeeping_turn(rows, git=GIT_BOOKKEEPING):
+def _bookkeeping_turn(rows, git=GIT_BOOKKEEPING, loops=False):
     """True when every work row in `rows` is a shell call that read or ran a
     git subcommand in `git` (`_bookkeeping_command`) and was not seen to
     change a file.
@@ -4800,7 +5342,7 @@ def _bookkeeping_turn(rows, git=GIT_BOOKKEEPING):
         r.get("kind") == "run" and not _change_row(r)
         and len(str(r.get("detail") or "")) < DETAIL_MAX
         and "[redacted:" not in str(r.get("detail") or "")
-        and _bookkeeping_command(r.get("detail"), git) for r in steps)
+        and _bookkeeping_command(r.get("detail"), git, loops) for r in steps)
 
 
 def _settled(rows):
@@ -4915,7 +5457,12 @@ def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None):
     # `tail` or a read-only query owes no check. Its claim words are read the
     # same way, and a claim is judged against the session's earlier turns below.
     quiet = _bookkeeping_turn(rows, GIT_READS)
-    if not worked or quiet:
+    # A turn of reads that loop over files or read a read's output (plan 126:
+    # `for f in $(find src); do cat -n "$f"; done`, refused in 4 of 6 live
+    # advice turns) ends like one with no work - but only on a reply that
+    # claims nothing. A done/tested claim over it keeps the worked turn's fold.
+    read = quiet or _bookkeeping_turn(rows, GIT_READS, loops=True)
+    if not worked or read:
         # With no work, the words are the whole trigger, so a question or a
         # negation is not read as the claim it names (`asserted_claims`).
         done, verified = asserted_claims(t)
@@ -4939,7 +5486,7 @@ def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None):
     # exit below - "nothing was done and nothing was claimed" - is exactly the
     # shape that used to leave such a claim unjudged.
     external = _external_claim(t)
-    if (not worked or quiet) and not (done or verified) and not external:
+    if (not worked or read) and not (done or verified) and not external:
         return _residual_block(t, rows, shape, session_id=session_id, cwd=cwd)
     if lost:
         return _residual_block(t, rows, shape,
@@ -5070,12 +5617,12 @@ def _evidence_text(cls, rows, external, where="this turn"):
                     % (where, shown or "a UI file"))
         return ("no ui_ok",
                 "Design contract: %s changed a component (%s) and no "
-                "`tezgah-design check` ran over a measurement, so nothing "
+                "`~/.config/tezgah/bin/tezgah-design check` ran over a measurement, so nothing "
                 "says the component is on the repository's floor - a read of "
                 "the screen says what it looks like, not whether it is on "
-                "that floor. Run `tezgah-design check --contract "
+                "that floor. Run `~/.config/tezgah/bin/tezgah-design check --contract "
                 ".tezgah/design-contract.md --measured <measurement.json>` "
-                "(`tezgah-design derive` writes the contract when the repo "
+                "(`~/.config/tezgah/bin/tezgah-design derive` writes the contract when the repo "
                 "has none; the measurement is the per-component styles and "
                 "states the analyze-app loop produces) and report every "
                 "violation it prints; if the check cannot run here, write "
@@ -5487,9 +6034,9 @@ RESIDUAL_WORK = (
 # twice more.
 STOPPED_SLICE = (
     "{SLICE_LEAD}Slice %s, spawned by this session, stopped (%s) and "
-    "its work is not resumed. Resume it with `tezgah-task slice resume %s` - "
+    "its work is not resumed. Resume it with `~/.config/tezgah/bin/tezgah-task slice resume %s` - "
     "the native path first, else the re-dispatch brief it prints - or, if the "
-    "work was finished another way, record that with `tezgah-task slice done "
+    "work was finished another way, record that with `~/.config/tezgah/bin/tezgah-task slice done "
     "%s`.")
 
 # The `ready steps` class (plan 086, S1): the newest todo list (`note_todo`)