boost-skill-cli 1.1.0__tar.gz → 1.1.2__tar.gz

{boost_skill_cli-1.1.0 → boost_skill_cli-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.1.0
+Version: 1.1.2
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.1.0 → boost_skill_cli-1.1.2}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.0'
-__version_tuple__ = version_tuple = (1, 1, 0)
+__version__ = version = '1.1.2'
+__version_tuple__ = version_tuple = (1, 1, 2)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.1.0 → boost_skill_cli-1.1.2}/boost_cli/commands/configuration.py

@@ -3,6 +3,7 @@ completions, schedule, serve, mcp, self-update."""
 from __future__ import annotations
 
 import argparse
+import difflib
 import json
 import os
 import re
@@ -659,8 +660,42 @@ def _sq(s: str) -> str:
     return s.replace("'", "'\\''")
 
 
+def _report_rc_plan(plan, install: bool, shell: str) -> None:
+    """Print what `--dry-run` would do to an rc file, and nothing else."""
+    if not plan.changes:
+        out.ok("%s already %s — no change"
+               % (_tilde(plan.path),
+                  "wired for boost completions" if install
+                  else "free of boost completions"))
+        return
+    verb = {
+        "create": "would create %s and wire boost completions into it",
+        "add": "would wire boost completions into %s",
+        # `replace` also covers collapsing a duplicated block back to one.
+        "replace": "would rewrite the boost completions block in %s",
+        "remove": "would remove boost completions from %s",
+    }[plan.action]
+    out.info(verb % _tilde(plan.path))
+    for line in _rc_plan_diff(plan):
+        out.dim("  " + line)
+    out.dim("  re-run without --dry-run to apply")
+
+
+def _rc_plan_diff(plan) -> list[str]:
+    """The +/- lines between a plan's before and after, for the dry run.
+
+    The ``---``/``+++``/``@@`` scaffolding is dropped: the file is named on the
+    line above, and line numbers earn nothing on a five-line rc edit.
+    """
+    return [ln.rstrip("\n")
+            for ln in difflib.unified_diff(plan.before.splitlines(),
+                                           plan.after.splitlines(), n=1)
+            if not ln.startswith(("---", "+++", "@@"))]
+
+
 def cmd_completions(argv) -> int:
-    """boost completions [bash|zsh|fish] [--install|--uninstall] [--eval]"""
+    """boost completions [bash|zsh|fish] [--install|--uninstall] [--eval]
+    [--dry-run]"""
     p = cliparse.parser(
         prog="boost completions",
         description="Generate shell tab-completion scripts")
@@ -669,6 +704,9 @@ def cmd_completions(argv) -> int:
     p.add_argument("--eval", action="store_true",
                    help="print the variant safe to `eval` directly "
                         "(what --install wires up)")
+    p.add_argument("--dry-run", action="store_true",
+                   help="with --install/--uninstall: report what would change "
+                        "in the rc file without writing it")
     group = p.add_mutually_exclusive_group()
     group.add_argument("--install", action="store_true",
                        help="wire completions into the shell's rc file "
@@ -679,11 +717,28 @@ def cmd_completions(argv) -> int:
 
     detected = args.shell or Path(os.environ.get("SHELL", "")).name
 
+    if args.dry_run and not (args.install or args.uninstall):
+        p.error("--dry-run qualifies --install or --uninstall; "
+                "pass one of them")
+
     if args.install or args.uninstall:
-        rc = (complete.install if args.install else complete.uninstall)(detected)
+        # Plan first either way, so a malformed rc file is reported before
+        # anything is written rather than after.
+        plan = (complete.plan_install if args.install
+                else complete.plan_uninstall)(detected)
+        if args.dry_run:
+            _report_rc_plan(plan, install=args.install, shell=detected)
+            return 0
+        complete.apply(plan)
+        if not plan.changes:
+            out.ok("%s already %s — no change"
+                   % (_tilde(plan.path),
+                      "wired for boost completions" if args.install
+                      else "free of boost completions"))
+            return 0
         out.ok("%s boost completions %s %s"
                % ("wired" if args.install else "removed",
-                  "into" if args.install else "from", _tilde(rc)))
+                  "into" if args.install else "from", _tilde(plan.path)))
         if args.install:
             out.dim("  restart your shell (or run `exec %s`) to pick it up"
                     % detected)

{boost_skill_cli-1.1.0 → boost_skill_cli-1.1.2}/boost_cli/core/complete.py

@@ -29,6 +29,7 @@ from __future__ import annotations
 import os
 import re
 from collections.abc import Callable, Sequence
+from dataclasses import dataclass
 from pathlib import Path
 
 from ..errors import BoostError
@@ -257,31 +258,78 @@ def _rc_block(shell: str) -> str:
             % (_RC_START, shell, _RC_END))
 
 
-def _merge_rc(text: str, block: str) -> str:
+def _spans(text: str, rc: Path | None = None) -> list[tuple[int, int]]:
+    """Half-open (start, end) index pairs of every managed block in ``text``.
+
+    Raises :class:`BoostError` for a start marker with no matching end, because
+    an rc file in that state cannot be edited safely by index. Both writers used
+    to pair the *first* start with the *next* end found anywhere after it, so an
+    orphan start marker sitting above real config made the next edit delete
+    every line in between — reported as ``✓ wired boost completions``. Refusing
+    costs the user one hand-edit; guessing cost them their shell config.
+
+    An orphan *end* is not an error: nothing pairs to it, it is skipped, and the
+    file keeps working. Only an unclosed block is ambiguous.
+    """
+    spans: list[tuple[int, int]] = []
+    i = 0
+    while (s := text.find(_RC_START, i)) != -1:
+        after = s + len(_RC_START)
+        e = text.find(_RC_END, after)
+        nxt = text.find(_RC_START, after)
+        # A block must close before the next one opens. Testing only `e == -1`
+        # is the original bug in a new place: an orphan start sitting above a
+        # real block finds *that* block's end and swallows every line between.
+        if e == -1 or (nxt != -1 and nxt < e):
+            where = " in %s" % paths.tilde(rc) if rc is not None else ""
+            raise BoostError(
+                "boost completions block%s starts but never ends" % where,
+                hint="%s has no matching %s — delete the stray start line (or "
+                     "close the block), then re-run"
+                     % (_RC_START, _RC_END))
+        e += len(_RC_END)
+        spans.append((s, e))
+        i = e
+    return spans
+
+
+def _outside(text: str, spans: list[tuple[int, int]]) -> list[str]:
+    """The stretches of ``text`` that sit outside every managed block."""
+    parts, prev = [], 0
+    for s, e in spans:
+        parts.append(text[prev:s])
+        prev = e
+    parts.append(text[prev:])
+    return parts
+
+
+def _merge_rc(text: str, block: str, rc: Path | None = None) -> str:
     """Idempotently set ``block`` in ``text``: replace a prior boost block in
     place, or append one after a single blank line. Mirrors
-    :func:`core.rules.merge_block`'s shape with rc-file-safe markers."""
-    i = text.find(_RC_START)
-    if i != -1:
-        j = text.find(_RC_END, i)
-        if j != -1:
-            j += len(_RC_END)
-            return (text[:i] + block + text[j:]).rstrip("\n") + "\n"
-    base = text.rstrip("\n")
-    return (base + "\n\n" + block + "\n") if base else block + "\n"
-
-
-def _strip_rc(text: str) -> str:
-    """Inverse of :func:`_merge_rc`: remove the managed block, if present."""
-    i = text.find(_RC_START)
-    if i == -1:
+    :func:`core.rules.merge_block`'s shape with rc-file-safe markers.
+
+    Collapses to exactly one block. Replacing only the first left a second one
+    live, so `--install` was idempotent in content but not in count.
+    """
+    spans = _spans(text, rc)
+    if not spans:
+        base = text.rstrip("\n")
+        return (base + "\n\n" + block + "\n") if base else block + "\n"
+    parts = _outside(text, spans)
+    return (parts[0] + block + "".join(parts[1:])).rstrip("\n") + "\n"
+
+
+def _strip_rc(text: str, rc: Path | None = None) -> str:
+    """Inverse of :func:`_merge_rc`: remove every managed block, if present.
+
+    Every, not the first: `--uninstall` on a doubled block used to report
+    "removed" while the shell went on sourcing the survivor.
+    """
+    spans = _spans(text, rc)
+    if not spans:
         return text
-    j = text.find(_RC_END, i)
-    if j == -1:
-        return text  # no end marker: malformed, leave the file untouched
-    j += len(_RC_END)
-    before, after = text[:i].rstrip("\n"), text[j:].strip("\n")
-    parts = [p for p in (before, after) if p]
+    parts = [p.strip("\n") for p in _outside(text, spans)]
+    parts = [p for p in parts if p]
     return "\n\n".join(parts) + "\n" if parts else ""
 
 
@@ -295,22 +343,76 @@ def _rc_path(shell: str) -> Path:
     return paths.expand("~/" + RC_FILE[shell])
 
 
+@dataclass(frozen=True)
+class RcPlan:
+    """What an install/uninstall would do to one rc file, before it does it.
+
+    ``--dry-run`` prints this; ``install``/``uninstall`` apply it. One code path
+    computes both, so the preview cannot disagree with the write.
+    """
+    path: Path
+    action: str        # create | add | replace | remove | none
+    before: str
+    after: str
+
+    @property
+    def changes(self) -> bool:
+        """True when applying this would alter the file."""
+        return self.before != self.after
+
+
+def _read_rc(shell: str) -> tuple[Path, str, bool]:
+    rc = _rc_path(shell)
+    exists = rc.exists()
+    return rc, (rc.read_text(encoding="utf-8") if exists else ""), exists
+
+
+def plan_install(shell: str) -> RcPlan:
+    """Describe wiring ``shell``'s rc file, writing nothing.
+
+    Raises :class:`BoostError` for a shell with no rc-file install path, and for
+    an rc file holding an unclosed block — so a dry run answers the dangerous
+    question too, rather than only the safe one.
+    """
+    rc, text, exists = _read_rc(shell)
+    after = _merge_rc(text, _rc_block(shell), rc)
+    if not exists:
+        action = "create"
+    elif after == text:
+        action = "none"
+    elif _spans(text, rc):
+        action = "replace"
+    else:
+        action = "add"
+    return RcPlan(path=rc, action=action, before=text, after=after)
+
+
+def plan_uninstall(shell: str) -> RcPlan:
+    """Describe removing what :func:`install` wired up, writing nothing."""
+    rc, text, _ = _read_rc(shell)
+    after = _strip_rc(text, rc)
+    return RcPlan(path=rc, action=("remove" if after != text else "none"),
+                  before=text, after=after)
+
+
+def apply(plan: RcPlan) -> Path:
+    """Write ``plan``'s result. A no-op when it changes nothing, so an rc file
+    keeps its mtime (and its place in the user's backups) on a repeat run."""
+    if plan.changes:
+        plan.path.write_text(plan.after, encoding="utf-8")
+    return plan.path
+
+
 def install(shell: str) -> Path:
     """Idempotently wire ``shell``'s rc file to eval boost's completions on
     every startup. Returns the rc file path. Raises :class:`BoostError` for
     a shell with no rc-file install path (currently anything but bash/zsh)."""
-    rc = _rc_path(shell)
-    text = rc.read_text(encoding="utf-8") if rc.exists() else ""
-    rc.write_text(_merge_rc(text, _rc_block(shell)), encoding="utf-8")
-    return rc
+    return apply(plan_install(shell))
 
 
 def uninstall(shell: str) -> Path:
     """Remove what :func:`install` wired up. A no-op if never installed."""
-    rc = _rc_path(shell)
-    if rc.exists():
-        rc.write_text(_strip_rc(rc.read_text(encoding="utf-8")), encoding="utf-8")
-    return rc
+    return apply(plan_uninstall(shell))
 
 
 def detect_shell() -> str:

{boost_skill_cli-1.1.0 → boost_skill_cli-1.1.2}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.1.0
+Version: 1.1.2
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.1.0 → boost_skill_cli-1.1.2}/boost_skill_cli.egg-info/SOURCES.txt

@@ -213,6 +213,7 @@ docs/roadmap/items/codeql-job-rename-stranded-merge-protection.md
 docs/roadmap/items/command-carousel-page.md
 docs/roadmap/items/command-reference-docs-site.md
 docs/roadmap/items/completions-complete-only-command-names.md
+docs/roadmap/items/completions-install-could-eat-your-rc-file.md
 docs/roadmap/items/complexity-and-dead-code-radar-xenon-vulture.md
 docs/roadmap/items/consolidate-skill-staleness-drift-logic-into-cor.md
 docs/roadmap/items/coverage-dashboard-codecov-free-for-oss.md
@@ -399,6 +400,7 @@ docs/roadmap/items/stop-re-serializing-entry-meta-on-every-search.md
 docs/roadmap/items/structured-json-log-output-mode.md
 docs/roadmap/items/supply-chain-posture-openssf-scorecard.md
 docs/roadmap/items/surface-every-docs-page-from-the-guide.md
+docs/roadmap/items/sweep-died-at-launch-not-at-a-page.md
 docs/roadmap/items/sync-could-not-repair-a-gutted-skill.md
 docs/roadmap/items/sync-deletes-unowned-broken-symlinks.md
 docs/roadmap/items/sync-relinks-into-every-agent-ignoring-scope.md
@@ -588,6 +590,7 @@ tests/unit/test_command_reference_fresh.py
 tests/unit/test_community_health_files.py
 tests/unit/test_compact.py
 tests/unit/test_complete.py
+tests/unit/test_complete_rc_block.py
 tests/unit/test_config.py
 tests/unit/test_content_dedupe.py
 tests/unit/test_crash_redaction.py
@@ -698,6 +701,7 @@ tests/unit/test_typosquat.py
 tests/unit/test_updatediff.py
 tests/unit/test_util.py
 tests/unit/test_version.py
+tests/unit/test_visual_harness_flags.py
 tests/unit/test_workflow_concurrency.py
 tests/unit/test_workflow_concurrency_groups.py
 tests/unit/test_workflow_push_has_credentials.py

{boost_skill_cli-1.1.0 → boost_skill_cli-1.1.2}/docs/commands.html

@@ -186,7 +186,7 @@
       <a class="cmd-link" href="#cmd-create" data-search="create scaffold a new skill from a template  --description description --dir dir --install name">create</a>
       <a class="cmd-link" href="#cmd-policy" data-search="policy manage &amp; enforce skill governance policies  --json {list,set,unset,check} key value">policy</a>
       <a class="cmd-link" href="#cmd-onboard" data-search="onboard add skill-tracker telemetry to a repo &amp; open a pr  --repo repo --pr --dry-run -f, --force">onboard</a>
-      <a class="cmd-link" href="#cmd-completions" data-search="completions generate shell tab-completion scripts  --eval --install --uninstall {bash,zsh,fish}">completions</a>
+      <a class="cmd-link" href="#cmd-completions" data-search="completions generate shell tab-completion scripts  --eval --dry-run --install --uninstall {bash,zsh,fish}">completions</a>
       <a class="cmd-link" href="#cmd-schedule" data-search="schedule manage automatic skill-sync scheduling  --interval {6h,12h,daily} --json {status,enable,disable}">schedule</a>
       <a class="cmd-link" href="#cmd-serve" data-search="serve browse the catalogue in a browser: search, facets and a tap graph  --port port --host host">serve</a>
       <a class="cmd-link" href="#cmd-mcp" data-search="mcp register boost as an mcp server (claude code, gemini cli) register boost as an mcp server for your agent clis --host h --stdio --seed --no-seed {register,unregister}">mcp</a>
@@ -1049,10 +1049,10 @@
           <div class="arg"><code>-f, --force</code><span>overwrite existing files without confirming</span></div>
         </div>
       </section>
-      <section class="cmd" id="cmd-completions" data-search="completions generate shell tab-completion scripts  --eval --install --uninstall {bash,zsh,fish}">
+      <section class="cmd" id="cmd-completions" data-search="completions generate shell tab-completion scripts  --eval --dry-run --install --uninstall {bash,zsh,fish}">
         <h3><span class="cname">completions</span><span class="gtag">cfg</span></h3>
         <p class="summary">Generate shell tab-completion scripts</p>
-        <pre class="syn">boost completions [--eval] [--install] [--uninstall] [{bash,zsh,fish}]</pre>
+        <pre class="syn">boost completions [--eval] [--dry-run] [--install] [--uninstall] [{bash,zsh,fish}]</pre>
         <div class="args-h">Arguments</div>
         <div class="args">
           <div class="arg"><code>{bash,zsh,fish}</code><span>target shell (default: from $SHELL)</span></div>
@@ -1060,6 +1060,7 @@
         <div class="args-h">Options</div>
         <div class="args">
           <div class="arg"><code>--eval</code><span>print the variant safe to `eval` directly (what --install wires up)</span></div>
+          <div class="arg"><code>--dry-run</code><span>with --install/--uninstall: report what would change in the rc file without writing it</span></div>
           <div class="arg"><code>--install</code><span>wire completions into the shell&#x27;s rc file (bash/zsh — one-shot, no manual editing)</span></div>
           <div class="arg"><code>--uninstall</code><span>remove what --install wired up</span></div>
         </div>

boost_skill_cli-1.1.2/docs/roadmap/items/completions-install-could-eat-your-rc-file.md

@@ -0,0 +1,82 @@
+---
+id: completions-install-could-eat-your-rc-file
+board: code
+section: dx
+status: inflight
+category: Bug
+complexity: S
+impact: High
+wow: 4
+note: two runs of a "no-op" command deleted the lines between two markers
+order: 113
+owner: fix/completions-malformed-block
+pr:
+title: <code>completions --install</code> could delete the config between its own markers
+---
+Found by asking a plain question — <em>is <code>boost completions</code>
+idempotent?</em> — and testing the answer rather than reading the docstring. For
+every ordinary input it is: seven paths reach a fixed point on the second run,
+and the managed block is replaced in place rather than appended. Three states
+were not ordinary, and each is reachable from one hand-edit of a shell rc file.
+
+<b>A start marker with no end deleted user config.</b> <code>_merge_rc</code>
+paired the first start marker with the next end marker found <em>anywhere</em>
+after it. With an orphan start above real config, run one appended a second
+block, and run two matched the orphan start against that new block's end and
+removed everything in between — the user's own lines — while printing
+<code>✓ wired boost completions into ~/.zshrc</code>. It converged, to a file
+with the user's aliases gone.
+
+<b>The inverse function already refused this exact input</b>, ten lines below:
+<code>_strip_rc</code> carried the comment <em>"no end marker: malformed, leave
+the file untouched."</em> So the state was recognised and only the writer failed
+to handle it. That asymmetry is the whole bug, and it is why this was worth
+fixing rather than filing: the reasoning was already in the file.
+
+<b>Uninstall had the same hole from the mirror precondition.</b>
+<code>_strip_rc</code> was safe only while the orphan start was the sole marker.
+Put a well-formed block below it and uninstall paired the orphan with that
+block's end: an rc file of <code>export A=1</code> plus four user lines came
+back as <code>export A=1</code> alone.
+
+<b>Two blocks made uninstall lie.</b> It removed the first and left the second,
+so boost reported <em>removed</em> while the shell went on sourcing
+completions — the same shape as the <code>sync</code> defect in
+<code>#515</code>, a command reporting success for work it declined to do.
+
+<b>The fix is one scan with the right invariant:</b> a block must close before
+the next one opens. Testing only for a missing end marker is the original bug in
+a new place, which the first draft of this fix reproduced and a test caught.
+Install now collapses to exactly one block, uninstall removes every block, and
+both refuse an unclosed one by name instead of guessing. An orphan
+<em>end</em> marker stays harmless and is pinned as such, so a later
+"tighten the parser" change cannot start rejecting a file that works.
+
+<b><code>--dry-run</code> makes it answerable before it is written.</b>
+<code>boost completions --install --dry-run</code> prints the exact +/- lines
+and touches nothing, and it raises on the malformed file too — a validation that
+only reports the safe cases is not a validation. Plan and apply are one code
+path (<code>plan_install</code> → <code>apply</code>), so the preview cannot
+disagree with the write, and a test pins that equality. Applying a no-op change
+now also leaves the file's mtime alone rather than rewriting identical bytes.
+
+<b>Verified exhaustively, not just by example.</b> A property test enumerates
+every arrangement of up to four fragments — user line, stray start, stray end,
+real block — and asserts three invariants over all 672 orderings: a user line
+boost does not own is never lost, a successful uninstall never leaves a block,
+and a refusal never modifies the file. Against the pre-fix code the same test
+reports <b>220 violations</b> (198 of the second, 22 of the first); against the
+fix, zero. It runs in 0.38s.
+
+That sweep also corrected its own first draft. Its initial invariant counted
+every user line, and flagged 16 "failures" that were the managed block behaving
+exactly as conda, nvm and rbenv do — content between the markers is boost's to
+replace. The real invariant is about lines boost does <em>not</em> own, and the
+reference parser has to resolve the orphan-start ambiguity the way the fix does
+rather than the way the bug did, or it under-reports the data loss it exists to
+catch.
+
+An rc file is the user's own hand-written config and the worst file boost owns
+an edit to, which is what moves this from tidy-up to High impact. The old tests
+covered only the well-formed path — a double install leaving one marker — so
+none of the three states had a failing test to find them.

boost_skill_cli-1.1.2/docs/roadmap/items/sweep-died-at-launch-not-at-a-page.md

@@ -0,0 +1,64 @@
+---
+id: sweep-died-at-launch-not-at-a-page
+board: code
+section: pipeline
+status: inflight
+category: CI · Bug
+complexity: S
+impact: High
+wow: 4
+note: a comment in the sibling file predicted this exact failure
+order: 114
+owner: fix/visual-sweep-single-process
+pr:
+title: The <code>sweep</code> gate died at browser launch, not at a page
+---
+Every <code>sweep</code> run failed from 2026-08-15 onward — on <code>main</code>
+and on every branch — and the failure was not a visual regression at all. Chrome
+died during the CDP startup handshake, before a single page loaded:
+
+<code>TargetCloseError: Protocol error (Target.setAutoAttach): Target closed</code>
+out of <code>ChromeLauncher.launch</code>.
+
+<b>The trigger was the environment, and the evidence is an A/B on identical
+trees.</b> <code>#515</code>'s own PR run passed on 2026-08-13 at 17:22; the
+byte-identical squash-merge failed on 2026-08-15 at 22:10. Same content, opposite
+result, two days apart — the <code>ubuntu-latest</code> runner image bumped
+Chrome underneath it. Nothing in the repo changed;
+<code>visual_check.mjs</code> had carried the same flags since <code>#209</code>.
+
+<b>The sibling file predicted it, in a comment, by name.</b>
+<code>a11y_check.mjs</code> was fixed earlier to scope <code>--single-process</code>
+to the <code>chrome-headless-shell</code> binary, and its comment recorded why the
+other half of the directory was still exposed: <em>"visual_check.mjs already
+passes the flag … <code>--single-process</code> is a debug-only flag there whose
+interaction with new headless nothing in this repo exercises."</em> That is
+exactly the interaction that broke.
+
+<b>Two candidate causes, both addressed, because the CI path cannot be
+reproduced locally.</b> <code>--single-process</code> is debug-only and
+unsupported against full Chrome; and <code>headless: "shell"</code> asks for the
+old headless mode, which Chrome removed from the main binary and now ships only
+as the separate <code>chrome-headless-shell</code> executable. Both are now
+conditioned on the same predicate the a11y harness uses, so against
+<code>/usr/bin/google-chrome</code> the sweep launches in new headless with
+neither flag — the shape <code>a11y_check.mjs</code> has been driving on this
+runner all along. Keyed on the <em>binary</em> rather than on
+<code>process.platform</code>: a macOS run pointed at full Chrome must not
+inherit a flag meant for the shell.
+
+<b>What was verified, and what was not.</b> The harness runs end to end and
+passes <b>10 pages × 5 widths clean</b> against a downloaded
+<code>chrome-headless-shell</code> 152 — which also proves the docs pages
+themselves were never the problem. The flag selection was evaluated directly for
+four binary paths. The <em>CI</em> path is not locally reproducible and this card
+says so rather than implying otherwise: full Chrome cannot start under this macOS
+sandbox at all, aborting with <code>The browser is already running for
+&lt;fresh profile dir&gt;</code> from ProcessSingleton — a different error from
+CI's, so it is interference, not a reproduction. CI is the verifier.
+
+<b>The ratchet.</b> <code>tests/unit/test_visual_harness_flags.py</code> fails
+the build if either harness hands a sandbox-only flag to a full Chrome, and if
+the two stop agreeing on the predicate. The bug here was not the flag — it was
+that one file was fixed and the other was not, and the only thing recording that
+was a comment. A comment cannot fail a build.