@opengsd/gsd-path 1.3.1 → 1.5.0

package/scripts/guard_hook.py

@@ -25,6 +25,7 @@ import json
 import os
 import re
 import shlex
+import stat
 import subprocess
 import sys
 from pathlib import Path, PurePosixPath
@@ -120,6 +121,10 @@ ARCHIVE_REASON = (
     "committed GSD Path archives under .project/archive/ are read-only; "
     "only the bundled pipeline helpers may write there during a ship transaction"
 )
+ARCHIVE_UNPROVEN_READ_REASON = (
+    "commands run in archive context must be provably read-only; only "
+    "recognized read commands and the bundled pipeline helpers may run there"
+)
 DESTRUCTIVE_SHAPE_REASON = (
     "destructive commands must run alone with literal paths; split compound, "
     "substituted, or expanded destructive commands into single commands"
@@ -181,7 +186,7 @@ STATUS_STATE_FIELDS = frozenset(
         "integration_source",
     }
 )
-STATUS_INTEGRATION_MODES = frozenset({"direct", "pull-request"})
+STATUS_INTEGRATION_MODES = frozenset({"direct", "pull-request", "external-landing"})
 STATUS_INTEGRATION_SOURCES = frozenset({"default", "milestone"})
 STATUS_SLUG = re.compile(r"^[a-z0-9][a-z0-9-]*$")
 STATUS_BRANCH = re.compile(r"^gsd-path/M(\d{3,})$")
@@ -205,6 +210,7 @@ ARCHIVE_READ_COMMANDS = frozenset(
         "tail",
         "grep",
         "rg",
+        "sed",
         "ls",
         "stat",
         "wc",
@@ -232,6 +238,147 @@ CLOSED_LISTING_GIT_OPTIONS = {
     "symbolic-ref": frozenset({"-q", "--quiet", "--short"}),
 }
 GIT_READ_WRITE_OPTIONS = frozenset({"--output", "--ext-diff", "--textconv"})
+# Options whose value git writes to or runs as a command: one unknown word is
+# already enough, so a parameter in or after them is never accepted.
+GIT_PARAMETER_DENIED_OPTIONS = GIT_READ_WRITE_OPTIONS | {
+    "--upload-pack", "--receive-pack", "--exec", "-c", "--config-env",
+}
+
+
+# -c/--config keys whose value git executes as a program. A literal value is
+# as dangerous as a parameter here: git -c core.fsmonitor=<path> status runs
+# the configured program while the subcommand stays nominally read-only.
+GIT_EXECUTED_CONFIG_KEYS = frozenset({
+    "core.fsmonitor", "core.editor", "sequence.editor", "core.sshcommand",
+    "core.askpass", "core.pager", "core.gitproxy", "interactive.difffilter",
+})
+GIT_EXECUTED_CONFIG_SECTIONS = {
+    "filter": (".clean", ".smudge", ".process", ".command"),
+    "diff": (".command", ".textconv", ".external"),
+    "merge": (".driver",),
+    "remote": (".uploadpack", ".receivepack"),
+    "gpg": (".program",),
+    "credential": (".helper",),
+    "pager": ("",),
+}
+# Keys whose value is a path or URL git loads code through: an included file
+# can set every key above, and a rewritten URL can retarget the transport.
+# No value of these is a disabling form.
+GIT_LOADED_CONFIG_KEYS = frozenset({"core.hookspath", "include.path"})
+GIT_LOADED_CONFIG_SECTIONS = {
+    "includeif": (".path",),
+    "url": (".insteadof", ".pushinsteadof"),
+}
+GIT_CONFIG_DISABLING_VALUES = frozenset({"", "false"})
+
+
+def config_key_in(key, keys, sections):
+    if key in keys:
+        return True
+    section, _, remainder = key.partition(".")
+    return bool(remainder) and key.endswith(tuple(sections.get(section, ())))
+
+
+def loaded_config_key(key):
+    """Whether a config key's value is a path or URL git loads code through."""
+    return config_key_in(key, GIT_LOADED_CONFIG_KEYS, GIT_LOADED_CONFIG_SECTIONS)
+
+
+def executed_config_key(key):
+    """Whether a config key's value is a program git runs or code it loads."""
+    return loaded_config_key(key) or config_key_in(
+        key, GIT_EXECUTED_CONFIG_KEYS, GIT_EXECUTED_CONFIG_SECTIONS
+    )
+
+
+# Real read-only git options that are a strict prefix of a denied option name.
+GIT_SAFE_PREFIX_OPTIONS = frozenset({"--text"})
+
+
+def git_option_in(token, options):
+    """Whether a token names one of the options, by full name or any long-option prefix.
+
+    git accepts each unique prefix of a long option; matching every prefix is
+    stricter than git and so only fails closed. A prefix that is itself the
+    exact name of a read-only option is that option, not an abbreviation.
+    """
+    name = token.split("=", 1)[0]
+    if name in GIT_SAFE_PREFIX_OPTIONS and name not in options:
+        return False
+    if name.startswith("--") and len(name) > 2:
+        return any(option.startswith(name) for option in options)
+    return name in options
+GIT_CONFIG_READ_MODES = frozenset({
+    "--get", "--get-all", "--get-regexp", "--get-urlmatch", "--get-color",
+    "--get-colorbool", "-l", "--list", "--unset", "--unset-all",
+})
+GIT_CONFIG_READ_SUBCOMMANDS = frozenset({"get", "unset", "list"})
+GIT_CONFIG_DENIED_MODES = frozenset({"--rename-section", "--remove-section", "--edit"})
+GIT_CONFIG_DENIED_SUBCOMMANDS = frozenset({"rename-section", "remove-section", "edit"})
+GIT_CONFIG_VALUE_OPTIONS = frozenset({
+    "--file", "--blob", "--type", "--default", "--comment", "--value", "--url",
+})
+GIT_CONFIG_EDIT_SHORT_OPTION = re.compile(r"-[A-Za-z]*e[A-Za-z]*")
+# An unquoted word the shell can turn into several arguments: a glob, or a
+# brace list or range.
+PLAIN_QUOTED_SEGMENT = re.compile(r"'[^']*'|\"[^\"]*\"")
+ANSI_QUOTE_START = re.compile(r"\$['\"]")
+GIT_CONFIG_EXPANDING_WORD = re.compile(r"[*?\[]|\{.*(?:,|\.\.)")
+
+
+def denied_git_config_argument(arguments):
+    """The git config argument that persists or runs a program git executes.
+
+    A section rename can carry a key into an executed section and --edit runs
+    the editor, so both are denied outright. Otherwise only a set denies: an
+    executed key with a value operand after it and no read or unset mode.
+    Only a trailing redirection is dropped: the operator, its target and a
+    file descriptor digit written against it. A separate digit (5 >file) and a
+    quoted operator are operands.
+    """
+    arguments = list(arguments)
+    while (
+        len(arguments) >= 2
+        and getattr(arguments[-2], "redirection", False)
+        and not arguments[-2].isdigit()
+    ):
+        del arguments[-2:]
+        if (
+            arguments
+            and getattr(arguments[-1], "redirection", False)
+            and arguments[-1].isdigit()
+        ):
+            del arguments[-1]
+    separator = arguments.index("--") if "--" in arguments else len(arguments)
+    options = arguments[:separator]
+    for token in options:
+        if (
+            git_option_in(token, GIT_CONFIG_DENIED_MODES)
+            or GIT_CONFIG_EDIT_SHORT_OPTION.fullmatch(token)
+            or token.casefold() in GIT_CONFIG_DENIED_SUBCOMMANDS
+        ):
+            return token
+    if options[:1] and options[0].casefold() in GIT_CONFIG_READ_SUBCOMMANDS:
+        return None
+    for position, token in enumerate(options):
+        # A mode word that is the value of the option before it is no mode.
+        if token in GIT_CONFIG_READ_MODES and not (
+            position
+            and (
+                options[position - 1] == "-f"
+                or git_option_in(options[position - 1], GIT_CONFIG_VALUE_OPTIONS)
+            )
+        ):
+            return None
+    operands = [
+        token for token in options if not token.startswith("-")
+    ] + arguments[separator + 1:]
+    for token in operands[:-1]:
+        if executed_config_key(token.casefold()):
+            return token
+    return None
+
+
 ARCHIVE_READ_EXECUTION_OPTIONS = {"rg": frozenset({"--pre"})}
 AMBIGUOUS_SHELL_SYNTAX = re.compile(r"[\r\n|;&<>`]|\$\(|@\(")
 SUBSTITUTION_PLACEHOLDER = "COMMAND_SUBSTITUTION_"
@@ -239,10 +386,6 @@ SUBSTITUTION_PLACEHOLDER_SYNTAX = re.compile(
     r"\$\{" + SUBSTITUTION_PLACEHOLDER + r"(\d+)\}"
 )
 LINE_CONTINUATION = re.compile(r"(?<!\\)((?:\\\\)*)\\\r?\n")
-HEREDOC_PATTERN = re.compile(
-    r"<<(?P<dash>-?)\s*(?:'(?P<single>[^']+)'|\"(?P<double>[^\"]+)\""
-    r"|\\?(?P<bare>[A-Za-z_][A-Za-z0-9_]*))"
-)
 SHELL_WRITE_REDIRECTION_CHARS = frozenset("<>&|")
 SHELL_PARAMETER_SYNTAX = re.compile(
     r"\$(?:[A-Za-z_][A-Za-z0-9_]*|[0-9]+|[-*@#?$!]|\{[^}\r\n]+\})"
@@ -250,9 +393,12 @@ SHELL_PARAMETER_SYNTAX = re.compile(
 NAMED_SHELL_PARAMETER_SYNTAX = re.compile(
     r"\$(?:([A-Za-z_][A-Za-z0-9_]*)|\{([A-Za-z_][A-Za-z0-9_]*)\})"
 )
+ZSH_EXPANSION_FLAG_SYNTAX = re.compile(r"\$[=~^+]")
 CMD_PARAMETER_SYNTAX = re.compile(
     r"%([A-Za-z_][A-Za-z0-9_]*)%|!([A-Za-z_][A-Za-z0-9_]*)!"
 )
+# The shell reassigns these on every cd, so a tracked value is stale.
+SHELL_DIRECTORY_VARIABLES = frozenset({"PWD", "OLDPWD"})
 DIRECTORY_CHANGE_COMMANDS = frozenset(
     {"cd", "chdir", "pushd", "set-location", "sl"}
 )
@@ -305,6 +451,8 @@ MISSING_COMMAND_STRING_REASON = "{executable} {option} lacks a command string"
 UNVALIDATED_EXECUTION_REASONS = {
     ".": SCRIPT_FILE_REASON,
     "source": SCRIPT_FILE_REASON,
+    "readonly": "readonly changes shell assignment behavior the guard cannot validate; "
+    "avoid readonly declarations",
     "start": "start launches a detached process the guard cannot inspect; run the program directly",
     "setenv": ENV_BUILTIN_REASON,
     "unsetenv": ENV_BUILTIN_REASON,
@@ -369,7 +517,64 @@ SHELL_WRITE_COMMANDS = DESTRUCTIVE_SHELL_COMMANDS | frozenset(
     }
 )
 IN_PLACE_EDITORS = frozenset({"perl", "sed"})
+SED_SAFE_OPTIONS = frozenset(
+    {
+        "--debug",
+        "--help",
+        "--null-data",
+        "--posix",
+        "--quiet",
+        "--regexp-extended",
+        "--sandbox",
+        "--separate",
+        "--silent",
+        "--unbuffered",
+        "--version",
+        "-E",
+        "-n",
+        "-r",
+        "-s",
+        "-u",
+    }
+)
 FIND_EXECUTION_ACTIONS = frozenset({"-exec", "-execdir", "-ok", "-okdir"})
+# Programs that run the command in their arguments, with the options of each
+# that take a separate value. The guard checks the command they run.
+EXEC_PREFIX_VALUE_OPTIONS = {
+    "nice": frozenset({"-n", "--adjustment"}),
+    "nohup": frozenset(),
+    "setsid": frozenset(),
+    "stdbuf": frozenset({"-i", "-o", "-e", "--input", "--output", "--error"}),
+    "sudo": frozenset({
+        "-u", "-g", "-h", "-p", "-C", "-T", "-U", "-r", "-t",
+        "--user", "--group", "--host", "--prompt", "--close-from",
+        "--command-timeout", "--other-user", "--role", "--type",
+    }),
+    "time": frozenset({"-f", "--format"}),
+    "timeout": frozenset({"-s", "-k", "--signal", "--kill-after"}),
+    "watch": frozenset({"-n", "-q", "--interval", "--equexit"}),
+}
+# Runner options that write, edit or enter a file or directory by themselves.
+EXEC_PREFIX_FILE_OPTIONS = {
+    "sudo": frozenset({"-e", "-D", "-R", "--edit", "--chdir", "--chroot"}),
+    "time": frozenset({"-o", "--output"}),
+    "watch": frozenset({"-s", "--shotsdir"}),
+}
+# The short option letters of each runner that take no value.
+EXEC_PREFIX_FLAG_LETTERS = {
+    "nice": "",
+    "nohup": "",
+    "setsid": "cfw",
+    "stdbuf": "",
+    "sudo": "AbBEHiKklnNPSsVv",
+    "time": "ahlpqvV",
+    "timeout": "fpv",
+    "watch": "bcCdegprtwx",
+}
+EXEC_PREFIX_INTERVAL_OPTIONS = frozenset({"-n", "--interval"})
+RUNNER_DURATION = re.compile(
+    r"(?:(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?|inf(?:inity)?)[smhd]?", re.IGNORECASE
+)
 SHELL_CONTROL_WORDS = frozenset(
     {
         "!",
@@ -474,6 +679,20 @@ def collect(
             )
 
 
+def is_link_like(path):
+    """A symlink, or on Windows any name-surrogate reparse point such as a junction.
+
+    Path.is_symlink() is false for a junction, which still redirects the path.
+    """
+    try:
+        status = os.lstat(path)
+    except OSError:
+        return False
+    return stat.S_ISLNK(status.st_mode) or bool(
+        getattr(status, "st_reparse_tag", 0) & 0x20000000  # IO_REPARSE_TAG name surrogate
+    )
+
+
 def normalize_posix(path):
     text = path.replace("\\", "/").strip()
     if not text:
@@ -536,7 +755,7 @@ def repository_root():
     result = subprocess.run(
         ["git", "rev-parse", "--show-toplevel"],
         cwd=candidate,
-        text=True,
+        encoding="utf-8", errors="replace",
         capture_output=True,
         check=False,
     )
@@ -544,7 +763,7 @@ def repository_root():
         state = candidate / ".project" / "STATE.md"
         if (
             candidate.is_dir()
-            and not candidate.is_symlink()
+            and not is_link_like(candidate)
             and os.path.lexists(state)
         ):
             return candidate
@@ -560,7 +779,7 @@ def project_status(repo):
     result = subprocess.run(
         [sys.executable, "-B", str(launcher), "--repo", str(repo)],
         cwd=repo,
-        text=True,
+        encoding="utf-8", errors="replace",
         capture_output=True,
         check=False,
     )
@@ -697,13 +916,29 @@ def valid_status_branch(value):
 
 def target_paths(path, working_directories, repo):
     repo = repo.resolve()
-    candidate = Path(path)
+    candidate = Path(native_path_text(path))
     if not candidate.is_absolute():
         base = Path(working_directories[0]) if working_directories else repo
         if not base.is_absolute():
             base = repo / base
         candidate = base / candidate
-    return Path(os.path.abspath(candidate)), candidate.resolve(strict=False)
+    return Path(os.path.abspath(candidate)), resolve_lenient(candidate)
+
+
+def resolve_lenient(path):
+    """Path.resolve(strict=False) that still follows links on Windows.
+
+    Python 3.9 raises OSError on Windows for names it cannot open (rep*) and
+    for some links to missing files; the archive checks must not skip those
+    (a symlinked archive path would be allowed), so fall back to
+    os.path.realpath, which resolves what it can and keeps the remainder.
+    """
+    try:
+        return path.resolve(strict=False)
+    except OSError:
+        if os.name != "nt":
+            raise
+        return Path(os.path.realpath(path))
 
 
 @lru_cache(maxsize=None)
@@ -712,7 +947,7 @@ def repository_control_roots(repo):
     result = subprocess.run(
         ["git", "rev-parse", "--git-common-dir"],
         cwd=repo,
-        text=True,
+        encoding="utf-8", errors="replace",
         capture_output=True,
         env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"},
         check=False,
@@ -789,6 +1024,51 @@ def path_kind(candidate, repo, control_roots=()):
     return "product"
 
 
+def member_target_kind(candidate, repo):
+    """'product' when the path lies in a verified member of this coordinator.
+
+    A member follows its coordinator's phase. A stale member of this
+    coordinator raises MembersError, so the caller denies the write.
+    """
+    directory = candidate if candidate.is_dir() else candidate.parent
+    while not directory.is_dir() and directory != directory.parent:
+        directory = directory.parent
+    found = subprocess.run(
+        ["git", "-C", str(directory), "rev-parse", "--path-format=absolute",
+         "--show-toplevel", "--git-common-dir"],
+        encoding="utf-8", errors="replace", capture_output=True, check=False,
+        env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"},
+    )
+    lines = found.stdout.splitlines()
+    if found.returncode != 0:
+        if found.stderr.strip().startswith("fatal: not a git repository"):
+            return None
+        raise RuntimeError(found.stderr.strip() or "Git inspection failed")
+    if len(lines) != 2:
+        raise RuntimeError("Git inspection returned an unexpected result")
+    toplevel, common = Path(lines[0]), Path(lines[1])
+    if not os.path.lexists(common / "gsd-path" / "member.json"):
+        return None
+    import members  # the guard's runtime directory; only paths in a member need it
+    coordinator = members.marker_coordinator(toplevel)
+    if coordinator is None:
+        return None
+    if coordinator.resolve() != repo.resolve():
+        for member in members.read_members(repo):
+            try:
+                listed_common = members._common_dir(Path(member["checkout"]))
+            except (members.MembersError, OSError):
+                continue
+            if listed_common == common.resolve():
+                raise members.MembersError(
+                    "member marker names an old coordinator; "
+                    "run members.py repair --repo <coordinator>"
+                )
+        return None
+    members.member_role(toplevel)
+    return "product"
+
+
 def target_kind(path, working_directories, repo, control_roots=None):
     lexical, resolved = target_paths(path, working_directories, repo)
     repo = repo.resolve()
@@ -798,10 +1078,21 @@ def target_kind(path, working_directories, repo, control_roots=None):
         _canonical_control_alias(lexical, repo, control_roots),
         _canonical_control_alias(resolved, repo, control_roots),
     )
-    kinds = {
+    resolved_kind = path_kind(resolved, repo, control_roots)
+    kinds = {resolved_kind} | {
         path_kind(candidate, repo, control_roots)
-        for candidate in (lexical, resolved, *aliases)
+        for candidate in (lexical, *aliases)
     }
+    if resolved_kind == "external" and "protected" not in kinds:
+        try:
+            member_kind = member_target_kind(resolved, repo)
+        except Exception as error:
+            deny(
+                f"member write refused: {error}; "
+                "run members.py repair --repo <coordinator>"
+            )
+        if member_kind:
+            kinds.add(member_kind)
     for kind in ("protected", "product", "artifact", "external"):
         if kind in kinds:
             return kind
@@ -824,12 +1115,12 @@ def pipeline_target_kinds(targets):
 def closed_target_reason(targets):
     for path, working_directories in targets:
         for target in dict.fromkeys(target_paths(path, working_directories, repository_root())):
-            directory = target if target.is_dir() and not target.is_symlink() else target.parent
+            directory = target if target.is_dir() and not is_link_like(target) else target.parent
             while not directory.exists() and directory != directory.parent:
                 directory = directory.parent
             root = subprocess.run(
                 ["git", "-C", str(directory), "rev-parse", "--show-toplevel"],
-                capture_output=True, text=True,
+                capture_output=True, encoding="utf-8", errors="replace",
             )
             if root.returncode == 0:
                 reason = closed_milestone_reason(Path(root.stdout.strip()))
@@ -838,30 +1129,29 @@ def closed_target_reason(targets):
     return None
 
 
-def enforce_pipeline_reentry(paths, working_directories):
-    reason = closed_target_reason((path, working_directories) for path in paths)
-    if reason:
-        deny(reason)
-    classified = pipeline_target_kinds((path, working_directories) for path in paths)
+def pipeline_product_phase_reason(classified):
+    """Why product writes are denied outside the routed build phase, or None when allowed."""
     if classified is None:
-        return
+        return None
     repo, state, kinds = classified
     for path, kind in kinds:
         if kind == "protected":
-            deny(f"{CONTROL_FILE_REASON} {path}")
-    kinds = [kind for _, kind in kinds]
-    if all(kind == "external" for kind in kinds):
-        return
+            return f"{CONTROL_FILE_REASON} {path}"
+    kind_values = [kind for _, kind in kinds]
+    if all(kind == "external" for kind in kind_values):
+        return None
+    if not any(kind == "product" for kind in kind_values):
+        return None
     try:
         status = project_status(repo)
     except (OSError, ValueError, json.JSONDecodeError):
-        deny(REENTRY_FAILURE_REASON)
+        return REENTRY_FAILURE_REASON
     route = status.get("route")
     state_data = status.get("state") if isinstance(status.get("state"), dict) else {}
     completion = status.get("completion")
     if (state_data.get("phase") == "shipped"
             and isinstance(completion, dict) and completion.get("status") == "verified"):
-        return
+        return None
     routed_build = (
         state_data.get("phase") == "build"
         and isinstance(route, dict)
@@ -869,20 +1159,31 @@ def enforce_pipeline_reentry(paths, working_directories):
         and route.get("phase") == "build"
     )
     if routed_build:
-        return
-    if all(kind in {"external", "artifact"} for kind in kinds):
-        return
+        return None
+    if all(kind in {"external", "artifact"} for kind in kind_values):
+        return None
     phase = state_data.get("phase", "unknown")
     if isinstance(route, dict) and route.get("action") != "run-phase":
         next_step = f"{route.get('action', 'route')}: {route.get('reason', 'no reason')}"
     else:
         next_step = status.get("next_skill") or "gsd-path"
-    deny(
+    return (
         f"GSD Path is {phase}; direct product-file changes require the routed "
         f"build phase. Review {status.get('path', state)}; next: {next_step}"
     )
 
 
+def enforce_pipeline_reentry(paths, working_directories):
+    reason = closed_target_reason((path, working_directories) for path in paths)
+    if reason:
+        deny(reason)
+    reason = pipeline_product_phase_reason(
+        pipeline_target_kinds((path, working_directories) for path in paths)
+    )
+    if reason:
+        deny(reason)
+
+
 def in_archive(path):
     # Casefold: APFS and Windows resolve `.Project/Archive` to the archive.
     normalized = normalize_posix(path).casefold()
@@ -919,10 +1220,35 @@ def expansion_can_match_archive(path):
     )
 
 
+# Git Bash (Claude Code's shell on Windows) names drive C: as /c or /cygdrive/c.
+MSYS_DRIVE_PATH = re.compile(r"^/(?:cygdrive/)?([A-Za-z])(?=/|$)")
+
+
+def native_path_text(value):
+    """On Windows, the drive path that a Git Bash path such as /c/repo names.
+
+    Python reads /c/repo as a folder named c at the root of the current drive,
+    which would hide an archive from the containment checks.
+    """
+    if os.name != "nt":
+        return value
+    text = value.replace("\\", "/")
+    match = MSYS_DRIVE_PATH.match(text)
+    if match is None:
+        return value
+    return f"{match.group(1).upper()}:{text[match.end():] or '/'}"
+
+
 def path_values(value):
-    yield value
+    values = [value]
     if value.startswith("-") and "=" in value:
-        yield value.split("=", 1)[1]
+        values.append(value.split("=", 1)[1])
+    for candidate in values:
+        yield candidate
+        # Deny when either reading of an ambiguous Windows path reaches an archive.
+        native = native_path_text(candidate)
+        if native != candidate:
+            yield native
 
 
 def is_absolute_path(path):
@@ -932,7 +1258,7 @@ def is_absolute_path(path):
 
 def contains_existing_archive(path, working_directories):
     try:
-        target = Path(path).resolve(strict=False)
+        target = resolve_lenient(Path(path))
     except (OSError, RuntimeError):
         return False
     search_paths = [target, Path.cwd(), *(Path(value) for value in working_directories)]
@@ -940,7 +1266,7 @@ def contains_existing_archive(path, working_directories):
         if os.name != "nt" and re.match(r"^[A-Za-z]:[/\\]", str(search_path)):
             continue
         try:
-            resolved = search_path.resolve(strict=False)
+            resolved = resolve_lenient(search_path)
         except (OSError, RuntimeError):
             continue
         for parent in (resolved, *resolved.parents):
@@ -973,7 +1299,7 @@ def path_in_archive(path, working_directories=(), ancestors=True):
             if os.name != "nt" and re.match(r"^[A-Za-z]:[/\\]", combined):
                 continue
             try:
-                resolved = Path(combined).resolve(strict=False)
+                resolved = resolve_lenient(Path(combined))
             except (OSError, RuntimeError):
                 continue
             if in_archive(resolved.as_posix()) or (
@@ -997,7 +1323,7 @@ def working_directory_in_archive(path):
         if os.name != "nt" and re.match(r"^[A-Za-z]:[/\\]", value):
             continue
         try:
-            resolved = Path(value).resolve(strict=False)
+            resolved = resolve_lenient(Path(value))
         except (OSError, RuntimeError):
             continue
         if in_archive(resolved.as_posix()):
@@ -1035,10 +1361,10 @@ def directory_change_target(arguments):
     return operands[-1]
 
 
-def segment_directories(tokens, working_directories):
+def segment_directories(tokens, working_directories, contexts=None):
     """Yield each command segment with the working directories in effect for it."""
     current_directories = list(working_directories)
-    for segment in command_segments(tokens):
+    for position, segment in enumerate(command_segments(tokens)):
         yield segment, current_directories
         invocation = command_invocation(segment)
         if invocation is None:
@@ -1051,16 +1377,31 @@ def segment_directories(tokens, working_directories):
         if command not in DIRECTORY_CHANGE_COMMANDS:
             continue
         target = directory_change_target(arguments)
-        if SHELL_PARAMETER_SYNTAX.search(target):
+        tracked = {}
+        if contexts is not None and position < len(contexts):
+            tracked = {
+                name: value
+                for name, value in contexts[position].items()
+                if name not in SHELL_DIRECTORY_VARIABLES
+            }
+        expanded = expand_environment_parameters(target, tracked, tracked_only=True)
+        if SHELL_PARAMETER_SYNTAX.search(expanded) or CMD_PARAMETER_SYNTAX.search(expanded):
             raise ValueError(
                 f"cd target {target} cannot be resolved by the guard; "
                 "run that command first and cd to the literal result"
             )
-        if is_absolute_path(target):
-            current_directories = [target]
+        if (
+            (SHELL_PARAMETER_SYNTAX.search(target) or CMD_PARAMETER_SYNTAX.search(target))
+            and any(character.isspace() or character in "*?[]" for character in expanded)
+        ):
+            raise ValueError(
+                f"cd target {target} may split or glob; pass a literal path"
+            )
+        if is_absolute_path(expanded):
+            current_directories = [expanded]
         else:
             bases = current_directories or ["."]
-            current_directories = [f"{base}/{target}" for base in bases]
+            current_directories = [f"{base}/{expanded}" for base in bases]
 
 
 def command_can_destroy_files(invocation):
@@ -1076,9 +1417,11 @@ def command_can_destroy_files(invocation):
 def literal_path(operand):
     if len(operand) >= 2 and operand[0] in "\"'" and operand[-1] == operand[0]:
         operand = operand[1:-1]
-    pattern = r"[A-Za-z0-9._/-]+"
+    # A space is safe here: the operand is one shlex unit, so it cannot carry a
+    # second word; injection-relevant characters stay excluded.
+    pattern = r"[A-Za-z0-9._/ -]+"
     if os.name == "nt":
-        pattern = r"(?:[A-Za-z]:(?=[/\\]))?[A-Za-z0-9._/\\-]+"
+        pattern = r"(?:[A-Za-z]:(?=[/\\]))?[A-Za-z0-9._/\\ -]+"
     return operand if re.fullmatch(pattern, operand) is not None else None
 
 
@@ -1091,19 +1434,27 @@ def literal_destructive_operand(operand):
     return literal
 
 
-def command_references_archive(tokens, working_directories):
-    for segment, directories in segment_directories(tokens, working_directories):
-        invocation = command_invocation(segment)
-        ancestors = command_can_destroy_files(invocation)
-        operands = segment
-        if ancestors:
-            operands = [literal_destructive_operand(operand) for operand in invocation[1]]
-        if any(path_in_archive(operand, directories, ancestors) for operand in operands):
-            return True
-        wrapped = wrapped_command_tokens(segment, expand_parameters=False)
-        if wrapped is not None and command_references_archive(wrapped, directories):
-            return True
-    return False
+def segment_references_archive(segment, directories, assignments=None):
+    invocation = command_invocation(segment)
+    ancestors = command_can_destroy_files(invocation)
+    # A here-document body survives tokenization only inside a wrapped payload
+    # (bash -c '...'), where it is data, not commands; keep its text from
+    # flipping the segment into archive context.
+    def searchable(token):
+        return strip_heredoc_bodies(token) if "\n" in token else token
+
+    operands = [
+        expand_environment_parameters(searchable(token), assignments)
+        for token in segment
+    ]
+    if ancestors:
+        resolved = command_invocation(operands)
+        operands = [literal_destructive_operand(operand) for operand in resolved[1]]
+    if any(path_in_archive(operand, directories, ancestors) for operand in operands):
+        return True
+    return unresolved_archive_expansion(
+        " ".join(searchable(token) for token in segment), assignments
+    )
 
 
 def copy_destinations(arguments, directories, assignments=None):
@@ -1159,7 +1510,7 @@ def copy_destinations(arguments, directories, assignments=None):
         lexical, source_path = target_paths(source, directories, repository_root())
         if source_path.is_dir():
             # ponytail: reject ambiguous directory links instead of emulating cp flags.
-            if lexical.is_symlink():
+            if is_link_like(lexical):
                 raise ValueError("cp directory source is a symlink; pass a literal directory")
 
             def unreadable(error):
@@ -1168,49 +1519,264 @@ def copy_destinations(arguments, directories, assignments=None):
             for root, folders, files in os.walk(source_path, onerror=unreadable):
                 for name in folders + files:
                     entry = Path(root) / name
-                    if entry.is_symlink() and entry.is_dir():
+                    if is_link_like(entry) and entry.is_dir():
                         raise ValueError("cp source contains a directory symlink; copy it separately")
                     for output in outputs:
                         yield str(output / entry.relative_to(source_path))
 
 
+def sed_delimited_end(script, index, delimiter):
+    while index < len(script):
+        if script[index] == "\\":
+            index += 2
+        elif script[index] == delimiter:
+            return index + 1
+        else:
+            index += 1
+    return None
+
+
+def sed_address_end(script, index):
+    if index >= len(script):
+        return index
+    if script[index].isdigit():
+        while index < len(script) and script[index].isdigit():
+            index += 1
+        if index < len(script) and script[index] == "~":
+            index += 1
+            while index < len(script) and script[index].isdigit():
+                index += 1
+    elif script[index] == "$":
+        index += 1
+    elif script[index] == "/":
+        end = sed_delimited_end(script, index + 1, "/")
+        return len(script) if end is None else end
+    elif script[index] == "\\" and index + 1 < len(script):
+        end = sed_delimited_end(script, index + 2, script[index + 1])
+        return len(script) if end is None else end
+    return index
+
+
+def sed_script_is_read_only(script):
+    """Accept only sed scripts whose commands cannot write or execute."""
+    # Sed blocks require recursively validating their nested command grammar;
+    # reject them until that grammar is modeled explicitly.
+    safe_commands = frozenset("aAcCdDgGhHiIlLnNpPqQrstTxv=:")
+    index = 0
+    while index < len(script):
+        while index < len(script) and (script[index].isspace() or script[index] == ";"):
+            index += 1
+        if index >= len(script):
+            break
+        address_start = index
+        index = sed_address_end(script, index)
+        if index < len(script) and script[index] == ",":
+            index = sed_address_end(script, index + 1)
+        if index > address_start and index < len(script) and script[index] == "!":
+            index += 1
+        while index < len(script) and script[index].isspace():
+            index += 1
+        if index >= len(script):
+            break
+        command = script[index]
+        index += 1
+        if command in {"w", "W", "e"}:
+            return False
+        if command == "#":
+            newline = script.find("\n", index)
+            index = len(script) if newline < 0 else newline + 1
+            continue
+        if command == "s":
+            if index >= len(script):
+                return False
+            delimiter = script[index]
+            index = sed_delimited_end(script, index + 1, delimiter)
+            if index is None:
+                return False
+            index = sed_delimited_end(script, index, delimiter)
+            if index is None:
+                return False
+            end = index
+            while end < len(script) and script[end] not in ";\n":
+                end += 1
+            if any(flag in "wWe" for flag in script[index:end]):
+                return False
+            index = end
+            continue
+        if command == "y":
+            if index >= len(script):
+                return False
+            delimiter = script[index]
+            index = sed_delimited_end(script, index + 1, delimiter)
+            if index is None:
+                return False
+            index = sed_delimited_end(script, index, delimiter)
+            if index is None:
+                return False
+            continue
+        if command not in safe_commands:
+            return False
+        while index < len(script) and script[index] not in ";\n":
+            index += 1
+    return True
+
+
+def sed_arguments(arguments):
+    """Return (in_place, input_files, script_is_read_only) for sed arguments."""
+    in_place = False
+    scripts = []
+    inputs = []
+    script_seen = False
+    scripts_are_literal = True
+    index = 0
+    while index < len(arguments):
+        argument = arguments[index]
+        index += 1
+        if argument == "--":
+            positional = arguments[index:]
+            if not script_seen and positional:
+                scripts.append(positional[0])
+                positional = positional[1:]
+                script_seen = True
+            inputs.extend(positional)
+            break
+        if argument in {"-e", "--expression"}:
+            if index >= len(arguments):
+                return in_place, inputs, False
+            scripts.append(arguments[index])
+            script_seen = True
+            index += 1
+            continue
+        if argument == "-f" or argument == "--file":
+            if index >= len(arguments):
+                return in_place, inputs, False
+            script_seen = True
+            scripts_are_literal = False
+            index += 1
+            continue
+        if argument.startswith("--expression="):
+            scripts.append(argument.split("=", 1)[1])
+            script_seen = True
+            continue
+        if argument.startswith("--file="):
+            script_seen = True
+            scripts_are_literal = False
+            continue
+        if argument == "--in-place" or argument.startswith("--in-place="):
+            in_place = True
+            continue
+        if argument.startswith("--"):
+            if argument not in SED_SAFE_OPTIONS:
+                scripts_are_literal = False
+            continue
+        if argument.startswith("-") and argument != "-":
+            options = argument[1:]
+            cursor = 0
+            while cursor < len(options):
+                option = options[cursor]
+                cursor += 1
+                if option == "i":
+                    in_place = True
+                    break
+                if option == "e":
+                    if cursor < len(options):
+                        scripts.append(options[cursor:])
+                        script_seen = True
+                    elif index < len(arguments):
+                        scripts.append(arguments[index])
+                        script_seen = True
+                        index += 1
+                    else:
+                        return in_place, inputs, False
+                    break
+                if option not in "nErsu":
+                    scripts_are_literal = False
+            continue
+        if not script_seen:
+            scripts.append(argument)
+            script_seen = True
+        else:
+            inputs.append(argument)
+    if not scripts or not scripts_are_literal:
+        return in_place, inputs, False
+    return in_place, inputs, all(sed_script_is_read_only(script) for script in scripts)
+
+
 def shell_write_targets(tokens, working_directories, assignments=None):
-    """Yield (target, directories) for every path a shell command may write."""
-    assignments = {**(assignments or {}), **shell_assignment_values(tokens)}
-    for segment, directories in segment_directories(tokens, working_directories):
+    """Yield (target, directories, variables) for every path a shell command may write."""
+    for segment, directories, segment_assignments, _ in shell_segment_contexts(
+        tokens, working_directories, assignments
+    ):
         for index, token in enumerate(segment[:-1]):
             if ">" not in token or not set(token) <= SHELL_WRITE_REDIRECTION_CHARS:
                 continue
             target = segment[index + 1]
             if token.endswith("&") and (target.isdigit() or target == "-"):
                 continue
-            yield target, directories
+            yield target, directories, segment_assignments
         wrapped = wrapped_command_tokens(segment)
         if wrapped is not None:
-            yield from shell_write_targets(wrapped, directories, assignments)
+            yield from shell_write_targets(wrapped, directories, segment_assignments)
             continue
         invocation = command_invocation(segment)
         if invocation is None:
             continue
         command, arguments = invocation
+        command = command.removesuffix(".exe")
+        if command == "sed":
+            in_place, inputs, _ = sed_arguments(arguments)
+            if in_place:
+                for target in inputs:
+                    yield target, directories, segment_assignments
+            continue
         in_place = command in IN_PLACE_EDITORS and (
             has_short_option(arguments, "i")
             or any(argument.startswith("--in-place") for argument in arguments)
         )
-        if command.removesuffix(".exe") == "cp":
-            for destination in copy_destinations(arguments, directories, assignments):
-                yield destination, directories
+        if command == "cp":
+            for destination in copy_destinations(arguments, directories, segment_assignments):
+                yield destination, directories, segment_assignments
             continue
-        if command.removesuffix(".exe") in SHELL_WRITE_COMMANDS or in_place:
+        if command in SHELL_WRITE_COMMANDS or in_place:
             for argument in arguments:
                 if argument and not argument.startswith("-"):
-                    yield argument, directories
+                    yield argument, directories, segment_assignments
+
+
+def shell_write_needs_build_phase_gate(targets):
+    """Phase-gate shell product writes only on bound milestone branches in-tree."""
+    repo = repository_root()
+    branch = subprocess.run(
+        ["git", "-C", str(repo), "branch", "--show-current"],
+        capture_output=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if branch.returncode or not STATUS_BRANCH.fullmatch(branch.stdout.strip()):
+        return False
+    for path, working_directories in targets:
+        for target in dict.fromkeys(target_paths(path, working_directories, repo)):
+            directory = (
+                target
+                if target.is_dir() and not is_link_like(target)
+                else target.parent
+            )
+            while not directory.exists() and directory != directory.parent:
+                directory = directory.parent
+            root = subprocess.run(
+                ["git", "-C", str(directory), "rev-parse", "--show-toplevel"],
+                capture_output=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if root.returncode != 0 or Path(root.stdout.strip()) != repo:
+                return False
+    return True
 
 
 def protected_shell_write_reason(tokens, working_directories):
-    assignments = shell_assignment_values(tokens)
     targets = []
-    for target, directories in shell_write_targets(tokens, working_directories):
+    for target, directories, assignments in shell_write_targets(tokens, working_directories):
         expanded = expand_environment_parameters(target, assignments)
         if SHELL_PARAMETER_SYNTAX.search(expanded) or CMD_PARAMETER_SYNTAX.search(
             expanded
@@ -1230,44 +1796,141 @@ def protected_shell_write_reason(tokens, working_directories):
     for target, kind in classified[2]:
         if kind == "protected":
             return f"{PROTECTED_SHELL_WRITE_REASON} {target}"
+    if shell_write_needs_build_phase_gate(targets):
+        return pipeline_product_phase_reason(classified)
     return None
 
 
-def environment_parameter_value(match, assignments):
+def environment_parameter_value(match, assignments, tracked_only=False):
     name = match.group(1) or match.group(2)
     if name.startswith(SUBSTITUTION_PLACEHOLDER):
         return match.group(0)  # command substitution output is never resolved
-    return assignments.get(name, os.environ.get(name, ""))
+    if name in assignments:
+        return assignments[name]
+    if tracked_only:
+        return match.group(0)
+    return os.environ.get(name, match.group(0))
 
 
-def expand_environment_parameters(command, assignments=None):
+def expand_environment_parameters(command, assignments=None, tracked_only=False):
     values = assignments or {}
 
     def substitute(match):
-        return environment_parameter_value(match, values)
+        return environment_parameter_value(match, values, tracked_only)
 
     expanded = NAMED_SHELL_PARAMETER_SYNTAX.sub(substitute, command)
     return CMD_PARAMETER_SYNTAX.sub(substitute, expanded)
 
 
-def shell_assignment_values(tokens):
-    values = {}
-    for segment in command_segments(tokens):
-        variable_command = segment[0].casefold() in VARIABLE_COMMANDS
+def shell_segment_flow(tokens):
+    """Return whether each segment is conditional or runs in a subshell."""
+    flows = []
+    segment = []
+    conditional = False
+    subshell_depth = 0
+    control_depth = 0
+    separators = set("|;&()\n\r")
+    for token in tokens:
+        if token and set(token) <= separators:
+            if segment:
+                flows.append(
+                    (conditional or control_depth > 0, subshell_depth > 0 or token in {"|", "&"})
+                )
+                segment = []
+            if token == "(":
+                subshell_depth += 1
+                conditional = True
+            elif token == ")":
+                subshell_depth = max(0, subshell_depth - 1)
+                conditional = False
+            elif token in {"&&", "||", "|", "&"}:
+                conditional = True
+            else:
+                conditional = False
+            continue
+        word = token.casefold()
+        if not segment and word in SHELL_CONTROL_WORDS:
+            if word in {"if", "while", "until", "for", "select", "case", "coproc"}:
+                control_depth += 1
+            elif word in {"fi", "done", "esac"}:
+                control_depth = max(0, control_depth - 1)
+            if word in {"then", "else", "elif", "do", "in"}:
+                conditional = True
+            continue
+        segment.append(token)
+    if segment:
+        flows.append((conditional or control_depth > 0, subshell_depth > 0))
+    return flows
+
+
+def shell_assignment_changes(segment, values):
+    """Return variables changed by a persistent assignment or variable builtin."""
+    index = 0
+    prefix = []
+    while index < len(segment) and SHELL_ASSIGNMENT_PATTERN.match(segment[index]):
+        prefix.append(segment[index])
+        index += 1
+    executable = segment[index].casefold() if index < len(segment) else None
+    updates = {}
+    removes = set()
+    if executable is None:
+        assignments = prefix
+    elif executable in {"export", "declare", "typeset"}:
+        assignments = [*prefix, *segment[index + 1 :]]
+    else:
+        assignments = []
+    for assignment in assignments:
+        if SHELL_ASSIGNMENT_PATTERN.match(assignment):
+            name, value = assignment.split("=", 1)
+            updates[name] = expand_environment_parameters(value, {**values, **updates})
+    if executable == "unset":
+        removes = {
+            name for name in segment[index + 1 :] if not name.startswith("-")
+        }
+    return updates, removes
+
+
+def shell_assignment_contexts(tokens, initial=None):
+    """Return the persistent shell variables visible before each segment."""
+    values = dict(initial or {})
+    contexts = []
+    segments = list(command_segments(tokens))
+    flows = shell_segment_flow(tokens)
+    if len(segments) != len(flows):
+        raise ValueError("shell command segments cannot be aligned")
+    for segment, (conditional, subshell) in zip(segments, flows):
+        contexts.append(dict(values))
+        updates, removes = shell_assignment_changes(segment, values)
+        if subshell:
+            continue
+        for name in removes:
+            if conditional:
+                values[name] = f"${name}"
+            else:
+                values.pop(name, None)
+        for name, value in updates.items():
+            values[name] = f"${name}" if conditional else value
+    return contexts, values
+
+
+def shell_segment_contexts(tokens, working_directories, initial=None):
+    """Yield each segment with its working directory and prior shell variables."""
+    contexts, _ = shell_assignment_contexts(tokens, initial)
+    segments = list(segment_directories(tokens, working_directories, contexts))
+    if len(segments) != len(contexts):
+        raise ValueError("shell command segments cannot be aligned")
+    for (segment, directories), assignments in zip(segments, contexts):
+        prefix = {}
         for token in segment:
             if not SHELL_ASSIGNMENT_PATTERN.match(token):
-                if variable_command:
-                    continue
                 break
             name, value = token.split("=", 1)
-            if name in values:
-                raise ValueError(f"shell variable {name} is reassigned; split the commands")
-            values[name] = expand_environment_parameters(value, values)
-    return values
+            prefix[name] = expand_environment_parameters(value, assignments)
+        yield segment, directories, assignments, prefix
 
 
-def unresolved_archive_expansion(command, tokens, working_directories):
-    expanded = expand_environment_parameters(command, shell_assignment_values(tokens))
+def unresolved_archive_expansion(command, assignments=None):
+    expanded = expand_environment_parameters(command, assignments)
     return ARCHIVE_REFERENCE.search(expanded) is not None
 
 
@@ -1296,32 +1959,194 @@ def substitution_end(command, start):
     raise ValueError("command substitution $( is not closed")
 
 
+def heredoc_requests(line):
+    """Find literal here-document delimiters, excluding here-strings and quotes."""
+    requests = []
+    quote = None
+    index = 0
+    while index < len(line):
+        character = line[index]
+        if quote:
+            if character == "\\" and quote == '"':
+                index += 2
+                continue
+            if character == quote:
+                quote = None
+            index += 1
+            continue
+        if character == "\\":
+            index += 2
+            continue
+        if character == "#" and (
+            index == 0
+            or line[index - 1].isspace()
+            or line[index - 1] in ";|&()<>"
+        ):
+            break
+        if character in "'\"":
+            quote = character
+            index += 1
+            continue
+        if line.startswith("$(", index):
+            index = substitution_end(line, index + 2) + 1
+            continue
+        if character == "`":
+            end = index + 1
+            while end < len(line) and line[end] != "`":
+                end += 2 if line[end] == "\\" else 1
+            index = min(end + 1, len(line))
+            continue
+        if line.startswith("<<<", index):
+            index += 3
+            continue
+        if not line.startswith("<<", index):
+            index += 1
+            continue
+        cursor = index + 2
+        strip_tabs = cursor < len(line) and line[cursor] == "-"
+        if strip_tabs:
+            cursor += 1
+        while cursor < len(line) and line[cursor] in " \t":
+            cursor += 1
+        delimiter = []
+        delimiter_quote = None
+        quoted = False
+        while cursor < len(line):
+            value = line[cursor]
+            if delimiter_quote:
+                if value == delimiter_quote:
+                    delimiter_quote = None
+                else:
+                    delimiter.append(value)
+                cursor += 1
+                continue
+            if value in "'\"":
+                delimiter_quote = value
+                quoted = True
+                cursor += 1
+                continue
+            if value == "\\" and cursor + 1 < len(line):
+                quoted = True
+                delimiter.append(line[cursor + 1])
+                cursor += 2
+                continue
+            if value.isspace() or value in ";|&()<>":
+                break
+            delimiter.append(value)
+            cursor += 1
+        if not delimiter:
+            raise ValueError("here-document delimiter cannot be validated")
+        requests.append(("".join(delimiter), strip_tabs, quoted))
+        index = cursor
+    return requests
+
+
+def heredoc_modes(command):
+    """Mark here-document bodies as data or shell-expanded input."""
+    lines = command.splitlines(keepends=True)
+    modes = ["shell"] * len(command)
+    offsets = []
+    offset = 0
+    for line in lines:
+        offsets.append(offset)
+        offset += len(line)
+    line_index = 0
+    while line_index < len(lines):
+        requests = heredoc_requests(lines[line_index].rstrip("\r\n"))
+        line_index += 1
+        for delimiter, strip_tabs, quoted in requests:
+            found = False
+            while line_index < len(lines):
+                line = lines[line_index]
+                content = line.rstrip("\r\n")
+                if strip_tabs:
+                    content = content.lstrip("\t")
+                start = offsets[line_index]
+                stop = start + len(line)
+                mode = "literal" if quoted or content == delimiter else "heredoc"
+                modes[start:stop] = [mode] * (stop - start)
+                line_index += 1
+                if content == delimiter:
+                    found = True
+                    break
+            if not found:
+                raise ValueError(f"here-document {delimiter} is not terminated")
+    return modes
+
+
 def split_command_substitutions(command):
-    """Replace every $(...) and `...` with a placeholder; return (outer, inner)."""
-    if "@(" in command:
-        raise ValueError(
-            "@( expansion cannot be validated; write the list as literal arguments"
-        )
-    if "$(" not in command and "`" not in command:
-        return command, []
-    outer, inner, index = [], [], 0
+    """Replace executable substitutions, leaving quoted text as shell data."""
+    modes = heredoc_modes(command)
+    outer, inner, index, quote = [], [], 0, None
     while index < len(command):
+        mode = modes[index]
+        character = command[index]
+        if mode == "literal":
+            outer.append(character)
+            index += 1
+            continue
+        if mode == "heredoc":
+            if character == "\\" and index + 1 < len(command) and command[index + 1] in "\\$`":
+                outer.append(command[index : index + 2])
+                index += 2
+                continue
+            if command.startswith("$(", index):
+                end = substitution_end(command, index + 2)
+                inner.append(command[index + 2 : end])
+            elif character == "`":
+                end = index + 1
+                while end < len(command) and command[end] != "`":
+                    end += 2 if command[end] == "\\" else 1
+                if end >= len(command):
+                    raise ValueError("backtick command substitution is not closed")
+                inner.append(command[index + 1 : end])
+            elif command.startswith("@(", index):
+                raise ValueError(
+                    "@( expansion cannot be validated; write the list as literal arguments"
+                )
+            else:
+                outer.append(character)
+                index += 1
+                continue
+            outer.append(f"${{{SUBSTITUTION_PLACEHOLDER}{len(inner) - 1}}}")
+            index = end + 1
+            continue
+        if quote == "'":
+            outer.append(character)
+            if character == "'":
+                quote = None
+            index += 1
+            continue
+        if character == "\\":
+            outer.append(command[index : index + 2])
+            index += 2
+            continue
+        if quote is None and character == "'":
+            quote = character
+            outer.append(character)
+            index += 1
+            continue
+        if character == '"':
+            quote = None if quote == '"' else '"'
+            outer.append(character)
+            index += 1
+            continue
         if command.startswith("$(", index):
             end = substitution_end(command, index + 2)
             inner.append(command[index + 2 : end])
-        elif command[index] == "`":
+        elif character == "`":
             end = index + 1
             while end < len(command) and command[end] != "`":
                 end += 2 if command[end] == "\\" else 1
             if end >= len(command):
                 raise ValueError("backtick command substitution is not closed")
             inner.append(command[index + 1 : end])
-        elif command[index] == "\\":
-            outer.append(command[index : index + 2])
-            index += 2
-            continue
+        elif command.startswith("@(", index):
+            raise ValueError(
+                "@( expansion cannot be validated; write the list as literal arguments"
+            )
         else:
-            outer.append(command[index])
+            outer.append(character)
             index += 1
             continue
         outer.append(f"${{{SUBSTITUTION_PLACEHOLDER}{len(inner) - 1}}}")
@@ -1342,11 +2167,8 @@ def strip_heredoc_bodies(command):
         line = lines[index]
         kept.append(line)
         index += 1
-        for match in HEREDOC_PATTERN.finditer(line):
-            delimiter = (
-                match.group("single") or match.group("double") or match.group("bare")
-            )
-            strip = "\t\r" if match.group("dash") else "\r"
+        for delimiter, strip_tabs, _ in heredoc_requests(line):
+            strip = "\t\r" if strip_tabs else "\r"
             while index < len(lines) and lines[index].strip(strip) != delimiter:
                 index += 1
             if index >= len(lines):
@@ -1385,14 +2207,222 @@ def decode_patch_path(raw_path, strip_prefix):
     return path
 
 
-def shell_tokens(command):
-    command = strip_heredoc_bodies(LINE_CONTINUATION.sub(r"\1 ", command))
+PARAMETER_MARKERS = frozenset("$%!")
+
+
+class ShellToken(str):
+    """A token that keeps, per parameter marker character, whether double quotes enclosed it.
+
+    `redirection` is true for an unquoted redirection operator and for one
+    ASCII file descriptor digit written against one (the 2 of 2>file, not of
+    2 >file). zsh passes a longer or non-ASCII digit word on as an argument.
+    `literal` is "bare" for a word written with no quote or escape, "quoted"
+    for a word inside one pair of plain quotes, "mixed" for plain quoted and
+    unquoted parts where no unquoted part can expand, and None when the shell
+    may build the word in another way (escapes, an expanding unquoted part, a
+    line continuation in the word or one that joins it to the next word).
+    """
+
+    double_quoted = ()
+    redirection = False
+    literal = None
+
+
+def double_quoted_markers(command):
+    """Return, per parameter marker in order, whether plain double quotes enclose it.
+
+    None means the command uses quoting outside the plain constructs this scan
+    models (plain single quotes, plain double quotes, unquoted text), so no
+    marker in it can be proven quoted.
+    """
+    flags = []
+    quote = None
+    comment = False
+    braces = 0
+    previous = " "
+    index = 0
+    while index < len(command):
+        character = command[index]
+        following = command[index + 1 : index + 2]
+        if comment:
+            if character in "\r\n":
+                comment = False
+            elif character in "'\"\\`":
+                return None
+        elif quote == "'":
+            if character == "'":
+                quote = None
+        elif character == "\\":
+            if following and following in PARAMETER_MARKERS:
+                # The shell executes the escaped marker as literal text; the
+                # token keeps the bare marker, so the pair is never provable.
+                flags.append(False)
+            previous = character
+            index += 2
+            continue
+        elif character == "`" or (character == "$" and following == "("):
+            return None
+        elif character == "$" and following == "{":
+            braces += 1
+        elif character == "}" and braces:
+            braces -= 1
+        elif character in "'\"" and braces:
+            return None
+        elif character == '"':
+            quote = None if quote else '"'
+        elif quote is None:
+            if character == "'":
+                quote = "'"
+            elif character == "$" and following and following in "'\"":
+                return None
+            elif character == "<" and following == "<":
+                return None
+            elif character == "#" and previous in " \t\r\n;&|()<>":
+                comment = True
+        if character in PARAMETER_MARKERS:
+            flags.append(quote == '"' and not comment)
+        previous = character
+        index += 1
+    return flags if quote is None and not braces else None
+
+
+def zsh_expansion_flag(text):
+    """Whether the text holds an unbraced zsh expansion flag ($=x, $~x, $^x, $+x).
+
+    These match no parameter syntax, so without this check they never enter
+    the parameter proof at all — while zsh word-splits them exactly like the
+    forms the proof denies. Any other unmatched $ is inert literal text.
+    """
+    return ZSH_EXPANSION_FLAG_SYNTAX.search(text)
+
+
+def parameters_double_quoted(token):
+    """Whether every parameter in the token expands inside double quotes to one word.
+
+    Only plain $name and ${name} qualify: flags, operators, subscripts,
+    positional and special parameters can split even inside double quotes.
+    A backslash-escaped marker stays one flag short of proven: the shell
+    executes the literal text while the guard's token still shows the bare
+    marker, so nothing about its expansion is provable.
+    """
+    flags = getattr(token, "double_quoted", ())
+    positions = [
+        index for index, character in enumerate(token) if character in PARAMETER_MARKERS
+    ]
+    if len(flags) != len(positions):
+        return False
+    quoted = dict(zip(positions, flags))
+    plain = {
+        match.start(): match.end() for match in NAMED_SHELL_PARAMETER_SYNTAX.finditer(token)
+    }
+    if any(
+        character == "$" and index not in plain for index, character in enumerate(token)
+    ) or any(token[end : end + 1] == "[" for end in plain.values()):
+        return False
+    return all(
+        quoted[match.start()] and quoted.get(match.end() - 1, True)
+        for syntax in (SHELL_PARAMETER_SYNTAX, CMD_PARAMETER_SYNTAX)
+        for match in syntax.finditer(token)
+    )
+
+
+def shell_tokens(command, direct=True):
+    """Tokenize a command; `direct` is False for a string that a second shell parses.
+
+    Only a directly parsed command keeps quote flags: an outer shell expands
+    parameters before the inner parse, so inner quotes prove nothing.
+    """
+    breaks = set()
+    if LINE_CONTINUATION.search(command):
+        mark = next(
+            character for character in map(chr, range(0xE000, 0xF900))
+            if character not in command
+        )
+        marked = strip_heredoc_bodies(
+            LINE_CONTINUATION.sub(lambda match: match.group(1) + mark, command)
+        )
+        command = strip_heredoc_bodies(LINE_CONTINUATION.sub(r"\1 ", command))
+        breaks = (
+            {index for index, character in enumerate(marked) if character == mark}
+            if marked.replace(mark, " ") == command
+            else None
+        )
+    else:
+        command = strip_heredoc_bodies(command)
+    joins = set()
+    for index in breaks or ():
+        left, right = index - 1, index + 1
+        while left >= 0 and marked[left] == mark:
+            left -= 1
+        while right < len(marked) and marked[right] == mark:
+            right += 1
+        if left >= 0 and marked[left].strip() and marked[right:right + 1].strip():
+            joins.add(index)
     lexer = shlex.shlex(command, posix=True, punctuation_chars="|;&()<>\n\r")
     lexer.whitespace = " \t"
     lexer.whitespace_split = True
     lexer.commenters = ""
+    tokens = []
+    previous_end = 0
     try:
-        tokens = list(lexer)
+        for token in lexer:
+            end = lexer.instream.tell() - len(lexer._pushback_chars)
+            if command[end - 1:end] in (" ", "\t"):
+                end -= 1
+            word_start = previous_end
+            while word_start < end and command[word_start] in " \t":
+                word_start += 1
+            previous_end = end
+            word = command[word_start:end]
+            literal = None
+            if (
+                breaks is not None
+                and "\\" not in word
+                and not ANSI_QUOTE_START.search(word)
+                and breaks.isdisjoint(range(word_start, end))
+                and end not in joins
+                and word_start - 1 not in joins
+                and PLAIN_QUOTED_SEGMENT.sub(lambda match: match.group(0)[1:-1], word) == token
+            ):
+                unquoted = PLAIN_QUOTED_SEGMENT.sub("", word)
+                if (
+                    "'" not in unquoted
+                    and '"' not in unquoted
+                    and not GIT_CONFIG_EXPANDING_WORD.search(unquoted)
+                ):
+                    literal = "mixed"
+            for quote in ("", "'", '"'):
+                start = end - len(token) - 2 * len(quote)
+                if (
+                    breaks is not None
+                    and start >= 0
+                    and command[start:end] == quote + token + quote
+                    and (start == 0 or command[start - 1] in " \t|;&()<>\n\r")
+                    and breaks.isdisjoint(range(start, end))
+                    and end not in joins
+                    and start - 1 not in joins
+                ):
+                    literal = "quoted" if quote else "bare"
+                    break
+            start = end - len(token)
+            before = command[start - 1:start] if start > 0 else ""
+            redirection = command[start:end] == token and (
+                (
+                    set(token) <= SHELL_WRITE_REDIRECTION_CHARS
+                    and ("<" in token or ">" in token)
+                    and before != "\\"
+                )
+                or (
+                    len(token) == 1
+                    and token in "0123456789"
+                    and command[end:end + 1] in ("<", ">")
+                    and (not before or before in " \t|;&()<>\n\r")
+                )
+            )
+            token = ShellToken(token)
+            token.redirection = redirection
+            token.literal = literal
+            tokens.append(token)
     except ValueError as error:
         raise ValueError(
             f"shell command cannot be tokenized ({error}); balance the quotes "
@@ -1400,7 +2430,20 @@ def shell_tokens(command):
         ) from None
     if not tokens:
         raise ValueError("shell command is empty")
-    return tokens
+    flags = double_quoted_markers(command) if direct else None
+    if flags is None or len(flags) != sum(
+        character in PARAMETER_MARKERS for token in tokens for character in token
+    ):
+        return tokens
+    marked = []
+    for token in tokens:
+        count = sum(character in PARAMETER_MARKERS for character in token)
+        redirection, literal = token.redirection, token.literal
+        token = ShellToken(token)
+        token.redirection, token.literal = redirection, literal
+        token.double_quoted, flags = tuple(flags[:count]), flags[count:]
+        marked.append(token)
+    return marked
 
 
 def command_segments(tokens):
@@ -1460,56 +2503,163 @@ def xargs_command(arguments):
 
 
 def require_read_command(wrapper, wrapped):
-    if wrapped and not archive_command_is_read_only(" ".join(wrapped), wrapped, True):
+    segments = list(command_segments(wrapped))
+    if wrapped and (
+        not segments
+        or not all(
+            archive_command_is_read_only(shlex.join(segment), segment, True)
+            for segment in segments
+        )
+    ):
         raise ValueError(
             f"{wrapper} runs {wrapped[0]} on operands the guard cannot check; "
             f"only read commands may follow {wrapper}, or pass the paths as literals"
         )
 
 
-def command_invocation(segment):
+def runner_value_option(prefix, token):
+    """The option in a runner option word whose value is the next word, if any.
+
+    Raises for an option that writes, edits or enters a file or directory. A
+    long option matches by each prefix, as getopt accepts it. A short word is
+    read as getopt reads it: flag letters, then the first value option letter,
+    whose value is the rest of the word or, with no rest, the next word.
+    """
+    value_options = EXEC_PREFIX_VALUE_OPTIONS[prefix]
+    file_options = EXEC_PREFIX_FILE_OPTIONS.get(prefix, frozenset())
+    denial = ValueError(
+        f"{prefix} {token} writes, edits or enters a file or directory that the "
+        "guard cannot check; run the command without this option and redirect "
+        "its output instead"
+    )
+    if token.startswith("--"):
+        name = token.split("=", 1)[0]
+        if any(option.startswith(name) for option in file_options):
+            raise denial
+        option = next((option for option in value_options if option.startswith(name)), None)
+        return option if "=" not in token else None
+    for position, letter in enumerate(token[1:], start=1):
+        option = f"-{letter}"
+        if option in file_options:
+            raise denial
+        if option in value_options:
+            return option if position == len(token) - 1 else None
+        if letter not in EXEC_PREFIX_FLAG_LETTERS[prefix]:
+            return None
+    return None
+
+
+def nonliteral_runner_option(token):
+    literal = getattr(token, "literal", "bare")
+    return (
+        SHELL_PARAMETER_SYNTAX.search(token)
+        or CMD_PARAMETER_SYNTAX.search(token)
+        or zsh_expansion_flag(token)
+        or literal is None
+        or (literal == "bare" and GIT_CONFIG_EXPANDING_WORD.search(token))
+    )
+
+
+def unresolved_runner_word(token):
+    return (
+        SHELL_PARAMETER_SYNTAX.search(token)
+        or CMD_PARAMETER_SYNTAX.search(token)
+        or zsh_expansion_flag(token)
+    ) and not parameters_double_quoted(token)
+
+
+def command_invocation(segment, unwrap_runners=True):
+    """`unwrap_runners` is False where a command runner itself must be judged."""
     index = 0
-    while index < len(segment) and SHELL_ASSIGNMENT_PATTERN.match(segment[index]):
-        validate_shell_assignment(segment[index])
-        index += 1
-    if index >= len(segment):
-        return None
-    executable = segment[index].replace("\\", "/").rsplit("/", 1)[-1].casefold()
-    if executable == "env":
+    # The shell word `time` is already removed; its only option can remain.
+    while unwrap_runners and index < len(segment) and segment[index] == "-p":
         index += 1
-        while index < len(segment):
-            token = segment[index]
-            if token == "--":
-                index += 1
+    while True:
+        while index < len(segment) and SHELL_ASSIGNMENT_PATTERN.match(segment[index]):
+            validate_shell_assignment(segment[index])
+            index += 1
+        if index >= len(segment):
+            return None
+        executable = segment[index].replace("\\", "/").rsplit("/", 1)[-1].casefold()
+        prefix = executable.removesuffix(".exe")
+        if executable == "env":
+            index += 1
+            while index < len(segment):
+                token = segment[index]
+                if token == "--":
+                    index += 1
+                    break
+                if SHELL_ASSIGNMENT_PATTERN.match(token):
+                    validate_shell_assignment(token)
+                    index += 1
+                    continue
+                option = token.split("=", 1)[0]
+                if option in ENV_OPTIONS_WITHOUT_VALUES:
+                    index += 1
+                    continue
+                if option in ENV_OPTIONS_WITH_VALUES:
+                    if option in {"-C", "--chdir"}:
+                        raise ValueError(
+                            f"env {option} changes the working directory the guard "
+                            "tracks; use cd with a literal path instead"
+                        )
+                    index += 1
+                    if "=" not in token:
+                        if index >= len(segment):
+                            raise ValueError(f"env {option} lacks a value")
+                        index += 1
+                    continue
+                if token.startswith("-"):
+                    raise ValueError(
+                        f"env {token} cannot be validated; use env NAME=VALUE <command>"
+                    )
+                if SHELL_PARAMETER_SYNTAX.search(token) or zsh_expansion_flag(token):
+                    raise ValueError(
+                        f"env word {token} cannot be resolved by the guard; env "
+                        "assignments must be literal NAME=VALUE words and the "
+                        "program a literal name"
+                    )
                 break
-            if SHELL_ASSIGNMENT_PATTERN.match(token):
-                validate_shell_assignment(token)
+        elif unwrap_runners and prefix in EXEC_PREFIX_VALUE_OPTIONS:
+            index += 1
+            while index < len(segment):
+                token = segment[index]
+                if token == "--":
+                    index += 1
+                    break
+                if not token.startswith("-") or token == "-":
+                    break
                 index += 1
-                continue
-            option = token.split("=", 1)[0]
-            if option in ENV_OPTIONS_WITHOUT_VALUES:
+                if nonliteral_runner_option(token):
+                    raise ValueError(
+                        f"{prefix} option {token} cannot be resolved by the guard; "
+                        f"{prefix} options must be literal words"
+                    )
+                option = runner_value_option(prefix, token)
+                if option is None or index >= len(segment):
+                    continue
+                value = segment[index]
                 index += 1
-                continue
-            if option in ENV_OPTIONS_WITH_VALUES:
-                if option in {"-C", "--chdir"}:
+                if prefix == "watch" and option in EXEC_PREFIX_INTERVAL_OPTIONS:
+                    if not RUNNER_DURATION.fullmatch(value):
+                        raise ValueError(
+                            f"watch interval {value} cannot be resolved by the guard; "
+                            "the interval must be a literal number"
+                        )
+                elif unresolved_runner_word(value):
+                    raise ValueError(
+                        f"{prefix} option value {value} cannot be resolved by the "
+                        f"guard; {prefix} option values must be literal words"
+                    )
+            if prefix == "timeout" and index < len(segment):
+                if not RUNNER_DURATION.fullmatch(segment[index]):
                     raise ValueError(
-                        f"env {option} changes the working directory the guard "
-                        "tracks; use cd with a literal path instead"
+                        f"timeout duration {segment[index]} cannot be resolved by the "
+                        "guard; the duration must be a literal number"
                     )
                 index += 1
-                if "=" not in token:
-                    if index >= len(segment):
-                        raise ValueError(f"env {option} lacks a value")
-                    index += 1
-                continue
-            if token.startswith("-"):
-                raise ValueError(
-                    f"env {token} cannot be validated; use env NAME=VALUE <command>"
-                )
+        else:
             break
-    if index >= len(segment):
-        return None
-    executable = segment[index].replace("\\", "/").rsplit("/", 1)[-1].casefold()
     arguments = segment[index + 1 :]
     if SHELL_PARAMETER_SYNTAX.search(executable):
         raise ValueError(
@@ -1533,19 +2683,103 @@ def command_invocation(segment):
     return executable, arguments
 
 
-def git_command(segment):
+def require_resolved_git_word(word, mixed=True):
+    """Deny a git word the shell can turn into other or several arguments."""
+    literal = getattr(word, "literal", "bare")
+    if (
+        literal is None
+        or (literal == "mixed" and not mixed)
+        or (literal == "bare" and GIT_CONFIG_EXPANDING_WORD.search(word))
+    ):
+        raise ValueError(
+            f"git argument {word} cannot be resolved by the guard; "
+            "pass a literal value"
+        )
+
+
+def git_command(segment, assignments=None):
     invocation = command_invocation(segment)
     if invocation is None:
         return None
     executable, arguments = invocation
     if executable not in {"git", "git.exe"}:
         return None
-    for argument in arguments:
-        if SHELL_PARAMETER_SYNTAX.search(argument):
-            raise ValueError(
-                f"git argument {argument} cannot be resolved by the guard; pass a "
-                "literal value (for commit messages use -F <file>)"
+    resolved_arguments = []
+    parameter_arguments = []
+    unproven_parameters = []
+    argument_index = 0
+    while argument_index < len(arguments):
+        argument = arguments[argument_index]
+        attached_directory = argument.startswith("-C") and len(argument) > 2
+        if argument == "-C" and argument_index + 1 < len(arguments):
+            argument_index += 1
+            directory = arguments[argument_index]
+            require_resolved_git_word(directory)
+            expanded = expand_environment_parameters(directory, assignments)
+            if (
+                SHELL_PARAMETER_SYNTAX.search(expanded)
+                or CMD_PARAMETER_SYNTAX.search(expanded)
+                or zsh_expansion_flag(expanded)
+            ):
+                raise ValueError(
+                    f"git argument {directory} cannot be resolved by the guard; "
+                    "pass a literal path"
+                )
+            if (
+                (SHELL_PARAMETER_SYNTAX.search(directory) or CMD_PARAMETER_SYNTAX.search(directory))
+                and any(character.isspace() or character in "*?[]" for character in expanded)
+            ):
+                raise ValueError(
+                    f"git -C path {directory} may split or glob; pass a literal path"
+                )
+            resolved_arguments.extend((argument, expanded))
+        elif attached_directory:
+            require_resolved_git_word(argument)
+            directory = argument[2:]
+            expanded = expand_environment_parameters(directory, assignments)
+            if (
+                SHELL_PARAMETER_SYNTAX.search(expanded)
+                or CMD_PARAMETER_SYNTAX.search(expanded)
+                or zsh_expansion_flag(expanded)
+            ):
+                raise ValueError(
+                    f"git argument {directory} cannot be resolved by the guard; "
+                    "pass a literal path"
+                )
+            if (
+                (SHELL_PARAMETER_SYNTAX.search(directory) or CMD_PARAMETER_SYNTAX.search(directory))
+                and any(character.isspace() or character in "*?[]" for character in expanded)
+            ):
+                raise ValueError(
+                    f"git -C path {directory} may split or glob; pass a literal path"
+                )
+            resolved_arguments.append(f"-C{expanded}")
+        else:
+            parameter = (
+                SHELL_PARAMETER_SYNTAX.search(argument)
+                or CMD_PARAMETER_SYNTAX.search(argument)
+                or zsh_expansion_flag(argument)
             )
+            if parameter:
+                parameter_arguments.append(argument)
+                literal = re.split(r"[$%!]", argument, maxsplit=1)[0]
+                expanded = expand_environment_parameters(argument, assignments)
+                if (
+                    not literal
+                    or (literal.startswith("-") and "=" not in literal)
+                    or git_option_in(literal, GIT_PARAMETER_DENIED_OPTIONS)
+                    or git_option_in(arguments[argument_index - 1], GIT_PARAMETER_DENIED_OPTIONS)
+                    or (literal.startswith("-c") and literal != "-c")
+                    or "::" in literal
+                    or not parameters_double_quoted(argument)
+                    or SUBSTITUTION_PLACEHOLDER in argument
+                    or SUBSTITUTION_PLACEHOLDER in expanded
+                ):
+                    unproven_parameters.append(argument)
+            expanded = expand_environment_parameters(argument, assignments)
+            resolved_arguments.append(argument if expanded == argument else expanded)
+        argument_index += 1
+    arguments = resolved_arguments
     index = 0
     git_options = []
     while index < len(arguments) and arguments[index].startswith("-"):
@@ -1556,18 +2790,32 @@ def git_command(segment):
             option = token.split("=", 1)[0]
             value = token.split("=", 1)[1] if "=" in token else None
         index += 1
+        if option != "-C":
+            require_resolved_git_word(token)
         if option in GIT_GLOBAL_OPTIONS_WITH_VALUES and value is None:
             if index >= len(arguments):
                 raise ValueError(f"git option {option} lacks a value")
             value = arguments[index]
+            if option != "-C":
+                require_resolved_git_word(value)
             index += 1
         if option in {"-c", "--config-env"}:
-            config_key = str(value).split("=", 1)[0].casefold()
+            config_key, _, config_value = str(value).partition("=")
+            config_key = config_key.casefold()
             if config_key.startswith("alias."):
                 raise ValueError(
                     f"git -c {config_key} defines an alias the guard cannot inspect; "
                     "run the underlying git command directly"
                 )
+            if executed_config_key(config_key) and not (
+                option == "-c"
+                and not loaded_config_key(config_key)
+                and config_value.casefold() in GIT_CONFIG_DISABLING_VALUES
+            ):
+                raise ValueError(
+                    f"git -c {config_key} configures a program git executes; "
+                    "the guard cannot allow it"
+                )
             if config_key == "clean.requireforce":
                 raise ValueError(
                     "git -c clean.requireForce disables the git clean safety check; "
@@ -1576,8 +2824,47 @@ def git_command(segment):
         if option in GIT_GLOBAL_OPTIONS_WITH_VALUES:
             git_options.extend((option, str(value)))
     if index >= len(arguments):
+        if parameter_arguments:
+            raise ValueError(
+                f"git argument {parameter_arguments[0]} cannot be resolved by the guard; "
+                "pass a literal value (for commit messages use -F <file>)"
+            )
         return None
-    return arguments[index].casefold(), arguments[index + 1:], git_options
+    require_resolved_git_word(arguments[index], mixed=False)
+    subcommand = arguments[index].casefold()
+    if subcommand == "config":
+        for argument in arguments[index + 1:]:
+            literal = getattr(argument, "literal", None)
+            if not getattr(argument, "redirection", False) and (
+                literal in (None, "mixed")
+                or (
+                    literal == "bare"
+                    and (argument.startswith("#") or GIT_CONFIG_EXPANDING_WORD.search(argument))
+                )
+            ):
+                raise ValueError(
+                    f"git argument {argument} cannot be resolved by the guard; "
+                    "pass a literal value"
+                )
+        denied = denied_git_config_argument(arguments[index + 1:])
+        if denied is not None:
+            raise ValueError(
+                f"git config {denied} persists a program git executes; "
+                "the guard cannot allow it"
+            )
+    read_only_subcommands = ARCHIVE_READ_GIT_COMMANDS | CLOSED_READ_GIT_COMMANDS
+    if subcommand in read_only_subcommands:
+        # Read-only subcommands still write through --output. A parameter
+        # passes only inside plain double quotes, where its expansion stays
+        # one word; an unquoted one can word-split into an option, and
+        # command substitution output is never known.
+        parameter_arguments = unproven_parameters
+    if parameter_arguments:
+        raise ValueError(
+            f"git argument {parameter_arguments[0]} cannot be resolved by the guard; "
+            "pass a literal value (for commit messages use -F <file>)"
+        )
+    return subcommand, arguments[index + 1:], git_options
 
 
 def wrapped_command_tokens(segment, expand_parameters=True):
@@ -1586,7 +2873,7 @@ def wrapped_command_tokens(segment, expand_parameters=True):
         return None
     executable, arguments = invocation
     if executable == "eval":
-        return shell_tokens(" ".join(arguments)) if arguments else None
+        return shell_tokens(" ".join(arguments), direct=False) if arguments else None
     if executable in COMMAND_WRAPPERS:
         if executable == "command" and arguments[:1] in (["-v"], ["-V"]):
             return None
@@ -1611,7 +2898,7 @@ def wrapped_command_tokens(segment, expand_parameters=True):
                             executable=executable, option=argument
                         )
                     )
-                return shell_tokens(arguments[index + 1])
+                return shell_tokens(arguments[index + 1], direct=False)
         raise ValueError(SHELL_FILE_REASON.format(executable=executable))
     if executable in POWERSHELL_WRAPPERS or executable in {"cmd", "cmd.exe"}:
         switches = {"-c", "-command", "/c", "/k"}
@@ -1630,8 +2917,8 @@ def wrapped_command_tokens(segment, expand_parameters=True):
                         for argument in payload
                     ]
                 if len(payload) == 1:
-                    return shell_tokens(payload[0])
-                return payload
+                    return shell_tokens(payload[0], direct=False)
+                return [str(argument) for argument in payload]
         raise ValueError(SHELL_FILE_REASON.format(executable=executable))
     return None
 
@@ -1648,7 +2935,7 @@ def has_short_option(arguments, option):
 def git_alias(command, git_options):
     result = subprocess.run(
         ["git", *git_options, "config", "--get", f"alias.{command}"],
-        text=True,
+        encoding="utf-8", errors="replace",
         capture_output=True,
         check=False,
     )
@@ -1686,14 +2973,18 @@ def update_ref_deletes(arguments):
     )
 
 
-def destructive_git_reason(tokens, resolved_aliases=frozenset()):
-    for segment in command_segments(tokens):
+def destructive_git_reason(
+    tokens, resolved_aliases=frozenset(), initial_assignments=None
+):
+    segments = list(command_segments(tokens))
+    contexts, _ = shell_assignment_contexts(tokens, initial_assignments)
+    for segment, assignments in zip(segments, contexts):
         wrapped = wrapped_command_tokens(segment)
         if wrapped is not None:
-            reason = destructive_git_reason(wrapped, resolved_aliases)
+            reason = destructive_git_reason(wrapped, resolved_aliases, assignments)
             if reason is not None:
                 return reason
-        invocation = git_command(segment)
+        invocation = git_command(segment, assignments)
         if invocation is None:
             continue
         command, arguments, git_options = invocation
@@ -1716,8 +3007,9 @@ def destructive_git_reason(tokens, resolved_aliases=frozenset()):
                     "git command directly"
                 )
             reason = destructive_git_reason(
-                ["git", *git_options, *shell_tokens(alias), *arguments],
+                ["git", *git_options, *shell_tokens(alias, direct=False), *arguments],
                 resolved_aliases | {command},
+                assignments,
             )
             if reason is not None:
                 return reason
@@ -1791,13 +3083,13 @@ def closed_milestone_reason(repo=None):
     repo = repo or repository_root()
     branch = subprocess.run(
         ["git", "-C", str(repo), "branch", "--show-current"],
-        capture_output=True, text=True,
+        capture_output=True, encoding="utf-8", errors="replace",
     )
     if not re.fullmatch(r"gsd-path/M\d{3,}", branch.stdout.strip()):
         return None
     result = subprocess.run(
         [sys.executable, "-B", str(Path(__file__).with_name("git_guard.py")),
-         "closed-milestone"], cwd=repo, capture_output=True, text=True,
+         "closed-milestone"], cwd=repo, capture_output=True, encoding="utf-8", errors="replace",
     )
     if result.returncode:
         return result.stderr.strip() or "closed milestone inspection failed"
@@ -1807,7 +3099,7 @@ def closed_milestone_reason(repo=None):
 def bundled_helper_invocation(command, tokens, working_directories, helpers=PIPELINE_HELPERS):
     """Allow one plain ``python[3] [-B] <script>`` from the guard-owned runtime.
 
-    The interpreter token must be exactly python or python3, and the script
+    The interpreter must be exactly python, python3, or py -3, and the script
     operand is the exact parsed token, with expansions and parent traversal refused.
     The resolved helper must be a regular file inside runtime/ beside this guard,
     or beside the guard itself in the repository layout. Resolve only in supplied
@@ -1826,9 +3118,12 @@ def bundled_helper_invocation(command, tokens, working_directories, helpers=PIPE
     _, substitutions = split_command_substitutions(command)
     if substitutions or wrapped_command_tokens(segments[0]) is not None:
         return False
-    if tokens[0] not in ("python", "python3"):
+    if tokens[:2] == ["py", "-3"]:
+        rest = tokens[2:]
+    elif tokens[0] in ("python", "python3"):
+        rest = tokens[1:]
+    else:
         return False
-    rest = tokens[1:]
     if rest[:1] == ["-B"]:
         rest = rest[1:]
     if not rest:
@@ -1853,7 +3148,8 @@ def bundled_helper_invocation(command, tokens, working_directories, helpers=PIPE
     runtime = runtime.resolve()
     for base in working_directories or [os.getcwd()]:
         try:
-            script = (Path(base) / operand).resolve()
+            # A Git Bash /c/... operand names the C: drive, not a folder named c.
+            script = (Path(base) / native_path_text(operand)).resolve()
             if (
                 script.name in helpers
                 and (script.is_relative_to(runtime) or (
@@ -1867,28 +3163,76 @@ def bundled_helper_invocation(command, tokens, working_directories, helpers=PIPE
     return False
 
 
-def archive_command_is_read_only(command, tokens, archive_context=False, git_commands=ARCHIVE_READ_GIT_COMMANDS):
+def archive_command_is_read_only(
+    command, tokens, archive_context=False, git_commands=ARCHIVE_READ_GIT_COMMANDS,
+    source=None,
+):
+    """`source` is the unexpanded (segment, assignments) whose tokens keep their quote flags."""
     if archive_context and AMBIGUOUS_SHELL_SYNTAX.search(command):
         return False
     if not archive_context:
         return True
-    executable = tokens[0].replace("\\", "/").rsplit("/", 1)[-1].casefold()
+    invocation = command_invocation(tokens, unwrap_runners=False)
+    if invocation is None:
+        return True
+    executable, arguments = invocation
+    executable = executable.removesuffix(".exe")
+    if executable in DIRECTORY_CHANGE_COMMANDS:
+        return True
+    if executable in {"export", "declare", "typeset", "unset"}:
+        return True
     denied_options = ARCHIVE_READ_EXECUTION_OPTIONS.get(executable, ())
     if any(
         token == option or token.startswith(f"{option}=")
-        for token in tokens[1:]
+        for token in arguments
         for option in denied_options
     ):
         return False
+    if executable == "sed":
+        in_place, _inputs, script_is_read_only = sed_arguments(arguments)
+        return not in_place and script_is_read_only
     if executable in ARCHIVE_READ_COMMANDS:
         return True
-    if executable != "git" or len(tokens) < 2:
+    if executable != "git":
         return False
-    if tokens[1].casefold() not in git_commands:
+    git = git_command(*(source or (tokens,)))
+    if git is None:
+        return False
+    subcommand, git_arguments, _options = git
+    if subcommand not in git_commands:
         return False
     return not any(
-        token in GIT_READ_WRITE_OPTIONS or token.startswith("--output=")
-        for token in tokens[2:]
+        git_option_in(token, GIT_READ_WRITE_OPTIONS) for token in git_arguments
+    )
+
+
+def archive_write_attempt(segment, source=None):
+    """Whether a segment denied in archive context attempts a write there."""
+    if any(
+        token
+        and (set(token) <= SHELL_WRITE_REDIRECTION_CHARS
+             or re.fullmatch(r"\d*[<>]+&?", token))
+        for token in segment
+    ):
+        return True
+    invocation = command_invocation(segment)
+    if invocation is None:
+        return False
+    executable, arguments = invocation
+    executable = executable.removesuffix(".exe")
+    if executable in SHELL_WRITE_COMMANDS:
+        return True
+    if executable in IN_PLACE_EDITORS and (
+        has_short_option(arguments, "i")
+        or any(argument.startswith("--in-place") for argument in arguments)
+    ):
+        return True
+    git = git_command(*(source or (segment,)))
+    if git is None:
+        return False
+    subcommand, git_arguments, _options = git
+    return subcommand not in ARCHIVE_READ_GIT_COMMANDS or any(
+        git_option_in(token, GIT_READ_WRITE_OPTIONS) for token in git_arguments
     )
 
 
@@ -2010,22 +3354,28 @@ def closed_git_listing(tokens):
     return not positionals
 
 
-def closed_shell_execution_reason(command, tokens, working_directories):
+def closed_shell_execution_reason(
+    command, tokens, working_directories, initial_assignments=None
+):
     helpers = PIPELINE_HELPERS | {"pipeline_git.py", "status_runtime.py", "promote_lookahead.py", "pipeline_diagnose.py"}
     rest = tokens[3:] if tokens[1:2] == ["-B"] else tokens[2:]
     if rest[:1] == ["pending"]:
         helpers = helpers | {"discussion_records.py"}
     if bundled_helper_invocation(command, tokens, working_directories, helpers):
         return None
-    for segment, directories in segment_directories(tokens, working_directories):
+    for segment, directories, assignments, _prefix in shell_segment_contexts(
+        tokens, working_directories, initial_assignments
+    ):
         wrapped = wrapped_command_tokens(segment)
         if wrapped is not None:
-            reason = closed_shell_execution_reason(shlex.join(wrapped), wrapped, directories)
+            reason = closed_shell_execution_reason(
+                shlex.join(wrapped), wrapped, directories, assignments
+            )
             if reason:
                 return reason
             continue
         metadata_closed = None
-        git = git_command(segment)
+        git = git_command(segment, assignments)
         checked_segment = segment
         if git is not None:
             subcommand, arguments, options = git
@@ -2035,7 +3385,7 @@ def closed_shell_execution_reason(command, tokens, working_directories):
                 for directory in directories:
                     result = subprocess.run(
                         ["git", *options, "rev-parse", "--show-toplevel", "--absolute-git-dir"],
-                        cwd=directory, capture_output=True, text=True,
+                        cwd=directory, capture_output=True, encoding="utf-8", errors="replace",
                     )
                     if result.returncode:
                         raise ValueError("git target repository cannot be resolved")
@@ -2064,14 +3414,16 @@ def closed_shell_execution_reason(command, tokens, working_directories):
 def command_denial(command, working_directories, allow_destructive=True):
     """Return why a shell command is denied, or None when it may run."""
     working_directories = working_directories or [os.getcwd()]
+    command = re.sub(r"(?i:(\.project)\\(archive))", r"\1/\2", command)
     outer, substitutions = split_command_substitutions(command)
     try:
         tokens = shell_tokens(outer)
         if tokens in (
-            [interpreter, "-B", "-c", "import sys; raise SystemExit(sys.version_info < (3, 9))"]
-            for interpreter in ("python3", "python")
+            [*interpreter.split(), "-B", "-c", "import sys; raise SystemExit(sys.version_info < (3, 9))"]
+            for interpreter in ("python3", "python", "py -3")
         ):
             return None
+        bundled_helper = bundled_helper_invocation(command, tokens, working_directories)
         destructive = list(destructive_shell_invocations(tokens))
         if destructive and (
             not allow_destructive
@@ -2092,16 +3444,31 @@ def command_denial(command, working_directories, allow_destructive=True):
             reason = command_denial(inner, working_directories, allow_destructive=False)
             if reason is not None:
                 return reason
-        archive_context = (
-            any(working_directory_in_archive(path) for path in working_directories)
-            or bool(ARCHIVE_REFERENCE.search(outer))
-            or command_references_archive(tokens, working_directories)
-            or unresolved_archive_expansion(outer, tokens, working_directories)
-        )
-        if not archive_command_is_read_only(command, tokens, archive_context) and not (
-            archive_context and bundled_helper_invocation(command, tokens, working_directories)
+        for segment, directories, assignments, prefix in shell_segment_contexts(
+            tokens, working_directories
         ):
-            return ARCHIVE_REASON
+            resolved_segment = [
+                expand_environment_parameters(token, assignments) for token in segment
+            ]
+            archive_context = (
+                any(working_directory_in_archive(path) for path in directories)
+                or segment_references_archive(segment, directories, assignments)
+                or any(
+                    ARCHIVE_REFERENCE.search(value)
+                    or path_in_archive(value, directories, ancestors=False)
+                    for value in prefix.values()
+                )
+            )
+            if not archive_command_is_read_only(
+                shlex.join(resolved_segment), resolved_segment, archive_context,
+                source=(segment, assignments),
+            ) and not (
+                archive_context
+                and bundled_helper
+            ):
+                if archive_write_attempt(resolved_segment, (segment, assignments)):
+                    return ARCHIVE_REASON
+                return ARCHIVE_UNPROVEN_READ_REASON
         reason = destructive_git_reason(tokens) or protected_shell_write_reason(
             tokens, working_directories
         )
@@ -2116,8 +3483,14 @@ def allow(event):
 
 
 def main():
+    # Hosts exchange hook input and output as UTF-8; a Windows pipe would
+    # default to cp1252. In-process callers may substitute text streams.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
     try:
-        event = json.load(sys.stdin)
+        stdin = getattr(sys.stdin, "buffer", None)
+        event = json.loads(stdin.read().decode("utf-8") if stdin is not None else sys.stdin.read())
         if not isinstance(event, dict):
             raise ValueError("hook event must be an object")
         evaluate(event)