code-context-control 2.81.0__tar.gz → 2.85.0__tar.gz

{code_context_control-2.81.0/code_context_control.egg-info → code_context_control-2.85.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.81.0
+Version: 2.85.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.81.0 → code_context_control-2.85.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.81.0"
+__version__ = "2.85.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -6055,6 +6055,15 @@ def _ci_main(args) -> int:
     from cli.tools.ci import handle_ci
 
     sub = getattr(args, "ci_cmd", None) or "inspect"
+    if sub == "publish":
+        if getattr(args, "dry_run", False):
+            args.job = "dry-run"
+        if getattr(args, "force", False):
+            args.allow_side_effects = True
+    if sub == "cache" and getattr(args, "clear", False):
+        # `--clear` is a flag on the CLI; the shared handler takes it
+        # positionally so both surfaces route through one code path.
+        args.job = "clear"
     project_path = getattr(args, "project_path", ".") or "."
     as_json = bool(getattr(args, "json", False))
 
@@ -6065,7 +6074,9 @@ def _ci_main(args) -> int:
         from services import ci_runner as cr
         from services.ci_workflow import inspect_project
         if sub == "inspect":
-            payload = inspect_project(project_path, event=getattr(args, "event", "") or "")
+            payload = inspect_project(
+                project_path, event=getattr(args, "event", "") or "",
+                engine=getattr(args, "engine", "auto") or "auto")
         elif sub in ("run", "rerun"):
             only = None
             if sub == "rerun":
@@ -6104,7 +6115,11 @@ def _ci_main(args) -> int:
         getattr(args, "event", "") or "",
         getattr(args, "engine", "auto") or "auto",
         bool(getattr(args, "allow_side_effects", False)),
-        getattr(args, "network", "") or "")
+        getattr(args, "network", "") or "",
+        "required" if getattr(args, "required", False) else "full",
+        getattr(args, "base", "") or "",
+        bool(getattr(args, "allow_host_mutation", False)),
+        bool(getattr(args, "no_cache", False)))
     print(out)
     # Exit code is the finding: a non-full verdict must not read as success to
     # a shell script or a pre-push hook.

{code_context_control-2.81.0 → code_context_control-2.85.0}/cli/commands/parser.py

@@ -507,6 +507,17 @@ def build_parser(version: str, parse_cli_ide_arg):
     ci_run.add_argument("--allow-side-effects", action="store_true",
                         help="Let the act engine run jobs that look like they "
                              "publish or deploy. Refused by default.")
+    ci_run.add_argument("--required", action="store_true",
+                        help="Run only the jobs a change could have broken "
+                             "(conservative; see `c3 ci plan`)")
+    ci_run.add_argument("--base", default="",
+                        help="Diff against this ref instead of the working tree")
+    ci_run.add_argument("--allow-host-mutation", action="store_true",
+                        help="Permit native steps that reconfigure this machine "
+                             "(pip/npm -g/apt install). Refused by default.")
+    ci_run.add_argument("--no-cache", action="store_true",
+                        help="Ignore cached results and execute every "
+                             "selected job")
     ci_run.add_argument("--network", default="",
                         help="Container network for the act engine (e.g. `none` "
                              "to cut egress). Default: act's own.")
@@ -530,6 +541,22 @@ def build_parser(version: str, parse_cli_ide_arg):
     ci_logs.add_argument("--tail", type=int, default=200)
 
     _ci_common(ci_subs.add_parser("runs", help="Recent local CI runs"))
+    ci_plan = _ci_common(ci_subs.add_parser(
+        "plan", help="Show which jobs a change requires, and why"))
+    ci_plan.add_argument("--base", default="",
+                         help="Diff against this ref instead of the working tree")
+    ci_pub = _ci_common(ci_subs.add_parser(
+        "publish", help="Post the last run as a GitHub commit status"))
+    ci_pub.add_argument("--run", dest="run_id", default="")
+    ci_pub.add_argument("--dry-run", action="store_true")
+    ci_pub.add_argument("--force", action="store_true",
+                        help="Publish a PARTIAL result as `pending`")
+    _ci_common(ci_subs.add_parser(
+        "history", help="Per-job pass/fail history and flake detection"))
+    ci_cache_p = _ci_common(ci_subs.add_parser(
+        "cache", help="Cached-result store: size, or --clear it"))
+    ci_cache_p.add_argument("--clear", action="store_true",
+                            help="Drop every cached result and dependency cache")
     _ci_common(ci_subs.add_parser(
         "doctor", help="Which execution engines are available on this machine"))
 

{code_context_control-2.81.0 → code_context_control-2.85.0}/cli/hub_server.py

@@ -1321,12 +1321,9 @@ def api_ci_inspect():
     except ValueError as e:
         return jsonify({"error": str(e)}), 404
     try:
-        from services import ci_act
-        data = inspect_project(resolved)
-        # The UI has to be able to say WHY a job cannot run here, and
-        # "install act" is a different answer from "macOS is impossible".
-        data["engines"] = ci_act.availability()
-        return jsonify(data)
+        # inspect_project owns the engine partition, so the Hub, the CLI
+        # and the tool text can never disagree about what is runnable.
+        return jsonify(inspect_project(resolved))
     except Exception as e:
         return jsonify({"error": f"{type(e).__name__}: {e}"}), 500
 

{code_context_control-2.81.0 → code_context_control-2.85.0}/cli/hub_ui/components/hub_ci.js

@@ -18,6 +18,11 @@ const CI_STATUS_STYLE = {
   unsupported: ['UNSUP', 'warn'],
   foreign: ['OTHER-OS', 'blue'],
   deselected: ['—', 'textDim'],
+  // capability labels, used by the job graph only
+  cap_native: ['NATIVE', 'accent'],
+  cap_container: ['CONTAINER', 'accent'],
+  cap_unreachable: ['OTHER-OS', 'blue'],
+  cap_unsupported: ['UNSUP', 'warn'],
 };
 
 function CiStatusPill({ status, title }) {
@@ -143,6 +148,9 @@ function HubCI({ projects, onOpenDrill }) {
 
   const jobs = (inspect && inspect.jobs) || [];
   const engines = inspect && inspect.engines;
+  const runnableNative = new Set((inspect && inspect.runnable_native) || []);
+  const runnableContainer = new Set((inspect && inspect.runnable_container) || []);
+  const unsupportedKeys = new Set(((inspect && inspect.unsupported) || []).map(u => u.key));
   const runJobs = ((run && run.jobs) || []).filter(j => j.status !== 'deselected');
 
   return (
@@ -152,7 +160,8 @@ function HubCI({ projects, onOpenDrill }) {
         <span style={{ fontSize: 14, color: T.text }}>Local CI</span>
         <span className="mono" style={{ fontSize: 11, color: T.textMuted }}>
           {inspect
-            ? `${(inspect.runnable || []).length} of ${jobs.length} job(s) runnable on ${inspect.host_os}`
+            ? `${(inspect.runnable || []).length} of ${jobs.length} runnable here`
+              + ` (${runnableNative.size} native, ${runnableContainer.size} container)`
             : 'loading…'}
         </span>
         <div style={{ flex: 1 }} />
@@ -289,13 +298,22 @@ function HubCI({ projects, onOpenDrill }) {
               display: 'flex', alignItems: 'center', gap: 9, padding: '5px 10px',
               borderTop: `1px solid ${T.border}`, fontSize: 11,
             }}>
+              {/* Read the server's partition; never re-derive it here. The
+                  first attempt inferred runnability in JS from act_could_run,
+                  which means "act has no blockers with this job" and NOT "act
+                  can run it here" — act only does Linux. Every macOS cell
+                  rendered as a green PASS it could never earn. */}
               <CiStatusPill
-                status={(!j.supported && !j.act_could_run) ? 'unsupported'
-                  : ((j.foreign_runner && !(j.act_could_run && engines && engines.ok))
-                    ? 'foreign' : 'passed')}
-                title={(!j.supported && !j.act_could_run) ? (j.blockers || []).join('; ')
-                  : (j.act_could_run && !j.supported ? 'the act engine can run this'
-                    : (j.foreign_runner ? `targets ${j.runs_on}` : 'runnable on this host'))} />
+                status={runnableNative.has(j.key) ? 'cap_native'
+                  : runnableContainer.has(j.key) ? 'cap_container'
+                    : unsupportedKeys.has(j.key) ? 'cap_unsupported'
+                      : 'cap_unreachable'}
+                title={runnableNative.has(j.key) ? 'runnable natively on this host'
+                  : runnableContainer.has(j.key)
+                    ? `runs in a container (${j.runs_on}) via act`
+                    : unsupportedKeys.has(j.key)
+                      ? (j.blockers || []).join('; ')
+                      : `targets ${j.runs_on} — no available engine can run it here`} />
               <span className="mono" style={{ color: T.textMuted }}>{j.key}</span>
               {!!(j.needs || []).length && (
                 <span className="mono" style={{ fontSize: 10, color: T.textDim }}>

{code_context_control-2.81.0 → code_context_control-2.85.0}/cli/mcp_server.py

@@ -771,10 +771,25 @@ async def c3_ci(action: str = "inspect", job: str = "", run_id: str = "",
                 allow_foreign: bool = False, workflow: str = "",
                 tail: int = 200, timeout: int = 0, event: str = "",
                 engine: str = "auto", allow_side_effects: bool = False,
-                network: str = "", ctx: Context = None) -> str:
+                network: str = "", mode: str = "full", base: str = "",
+                allow_host_mutation: bool = False,
+                no_cache: bool = False, ctx: Context = None) -> str:
     """RUN THIS REPO'S REAL CI LOCALLY — before pushing, not after.
     Reads .github/workflows/*.yml as the source of truth (no second CI config).
-    actions: inspect | run | rerun | status | failures | logs | runs | doctor.
+    actions: inspect | plan | run | rerun | status | failures | logs | runs |
+      cache | history | publish | doctor. publish posts the last run as a
+      GitHub COMMIT STATUS via your gh auth; it refuses a dirty tree, an
+      unpushed commit, and (unless forced) a PARTIAL result. history reports per-job fail rates and
+      flags FLAKY jobs — ones that both passed and failed on identical
+      inputs, so the code cannot be the cause. A job whose inputs are unchanged since it last passed
+      is reused (status `cached`, nothing executed); no_cache forces it.
+    mode: full (default) | required. required runs only the jobs a change
+      could have broken; it is CONSERVATIVE — anything unmapped runs. Use
+      action='plan' to see the decision and reason for every job first.
+    allow_host_mutation: the NATIVE engine refuses steps that would
+      reconfigure this machine (pip/npm -g/apt/brew install...). It has no
+      isolation; running this repo's own CI natively once uninstalled C3.
+      Prefer engine='act'.
     inspect: workflows, the job DAG, and which jobs are runnable on THIS host.
     run: execute in dependency order; job='lint' or 'test (ubuntu-latest, 3.12)'
       selects one (bare job name = all its matrix cells). A job whose dependency
@@ -798,7 +813,9 @@ async def c3_ci(action: str = "inspect", job: str = "", run_id: str = "",
     return await asyncio.to_thread(handle_ci, action, job, run_id,
                                    allow_foreign, workflow, tail, timeout,
                                    svc, finalize, event, engine,
-                                   allow_side_effects, network)
+                                   allow_side_effects, network,
+                                   mode, base, allow_host_mutation,
+                                   no_cache)
 
 
 @mcp.tool()

{code_context_control-2.81.0 → code_context_control-2.85.0}/cli/tools/ci.py

@@ -12,13 +12,14 @@ That distinction is the product.
 """
 from __future__ import annotations
 
+from services import ci_impact
 from services import ci_runner as cr
 from services.ci_workflow import inspect_project
 
 _MARK = {
     cr.PASSED: "PASS", cr.FAILED: "FAIL", cr.SKIPPED: "SKIP",
     cr.UNSUPPORTED: "UNSUP", cr.FOREIGN: "OTHER-OS", cr.TIMEOUT: "TIMEOUT",
-    cr.DESELECTED: "-",
+    cr.DESELECTED: "-", cr.CACHED: "CACHED",
 }
 
 # Verdicts an agent may treat as "safe to push". Deliberately one item long.
@@ -81,7 +82,10 @@ def _failure_rows(jobs: list, limit: int = 25) -> list:
 def handle_ci(action: str, job: str, run_id: str, allow_foreign: bool,
               workflow: str, tail: int, timeout: int, svc, finalize,
               event: str = "", engine: str = "auto",
-              allow_side_effects: bool = False, network: str = "") -> str:
+              allow_side_effects: bool = False, network: str = "",
+              mode: str = "full", base: str = "",
+              allow_host_mutation: bool = False,
+              no_cache: bool = False) -> str:
     """Route c3_ci actions."""
     project = str(svc.project_path)
     action = (action or "inspect").strip().lower()
@@ -91,7 +95,7 @@ def handle_ci(action: str, job: str, run_id: str, allow_foreign: bool,
 
     # ── inspect ──────────────────────────────────────────────────────────
     if action in ("", "inspect", "jobs"):
-        data = inspect_project(project, event=event)
+        data = inspect_project(project, event=event, engine=engine)
         if not data["workflows"]:
             return finalize(
                 "c3_ci", args,
@@ -105,26 +109,39 @@ def handle_ci(action: str, job: str, run_id: str, allow_foreign: bool,
             lines.append(f"  {wf['name']}  [{', '.join(wf['triggers']) or 'no triggers'}]"
                          f"  jobs={len(wf['jobs'])}{err}")
 
+        native = set(data.get("runnable_native") or [])
+        container = set(data.get("runnable_container") or [])
+
         lines.append("\nJob graph (dependency order):")
         by_key = {j["key"]: j for j in data["jobs"]}
         for key in data["order"]:
             j = by_key[key]
             needs = f"  needs={','.join(j['needs'])}" if j["needs"] else ""
-            if not j["supported"]:
+            if key in native:
+                state = "runnable here"
+            elif key in container:
+                state = "runnable (container)"
+            elif not j["supported"] and not j.get("act_could_run"):
                 state = "UNSUPPORTED"
-            elif j["foreign_runner"]:
-                state = f"other-OS ({j['runs_on']})"
             else:
-                state = "runnable here"
+                state = f"other-OS ({j['runs_on']})"
             lines.append(f"  {key:<42} {state}{needs}")
 
+        engines = data.get("engines") or {}
         lines.append(
-            f"\nRunnable on this host: {len(data['runnable'])} of {len(data['jobs'])}")
+            f"\nRunnable here: {len(data['runnable'])} of {len(data['jobs'])}"
+            f"  ({len(native)} native, {len(container)} container)")
+        if engines.get("ok"):
+            lines.append(f"  engines: native + act ({engines.get('act_version', '')})")
+        else:
+            lines.append(
+                f"  engines: native only — {engines.get('reason', 'act unavailable')}")
         if data["foreign"]:
             lines.append(
-                f"  other-OS ({len(data['foreign'])}): these target a different "
-                "runner. c3_ci(action='run', allow_foreign=true) attempts them "
-                "anyway and labels the result cross-OS.")
+                f"  other-OS ({len(data['foreign'])}): these target a runner no "
+                "available engine can reproduce. c3_ci(action='run', "
+                "allow_foreign=true) attempts them on this OS anyway and labels "
+                "the result cross-OS.")
         if data["unsupported"]:
             lines.append(f"  unsupported ({len(data['unsupported'])}):")
             for item in data["unsupported"][:8]:
@@ -139,6 +156,43 @@ def handle_ci(action: str, job: str, run_id: str, allow_foreign: bool,
         return finalize("c3_ci", args, "\n".join(lines),
                         f"{len(data['jobs'])} jobs, {len(data['runnable'])} runnable")
 
+    # ── plan (required mode, no execution) ───────────────────────────────
+    if action == "plan":
+        from services.ci_workflow import (
+            build_dag,
+            discover_workflows,
+            git_context,
+            parse_workflow,
+        )
+        wfs = [parse_workflow(p) for p in discover_workflows(project)]
+        dag = build_dag([w for w in wfs if not w.error],
+                        event=event, git=git_context(project))
+        try:
+            ordered = dag.topo_order()
+        except Exception:
+            ordered = dag.instances
+        plan = ci_impact.plan_required(project, ordered, wfs, base=base,
+                                       event=event)
+        lines = [
+            f"Required-mode plan ({len(plan.selected)} run / "
+            f"{len(plan.skipped)} skip) vs {base or 'the working tree'}",
+            f"changed files: {len(plan.changed)}",
+        ]
+        for path in plan.changed[:10]:
+            lines.append(f"  {path}")
+        if len(plan.changed) > 10:
+            lines.append(f"  ... and {len(plan.changed) - 10} more")
+        lines.append("")
+        for decision in plan.decisions:
+            mark = "RUN " if decision.decision == ci_impact.RUN else "skip"
+            lines.append(f"  {mark} {decision.job}")
+            lines.append(f"       {decision.reason}")
+        if plan.note:
+            lines.append(f"\n{plan.note}")
+        lines.append("\nRun it: c3_ci(action='run', mode='required')")
+        return finalize("c3_ci", args, "\n".join(lines),
+                        f"{len(plan.selected)} required")
+
     # ── run / rerun ──────────────────────────────────────────────────────
     if action in ("run", "rerun"):
         only = None
@@ -159,7 +213,9 @@ def handle_ci(action: str, job: str, run_id: str, allow_foreign: bool,
                            only=only, timeout=timeout or cr.DEFAULT_STEP_TIMEOUT,
                            workflow=workflow, event=event, engine=engine,
                            allow_side_effects=allow_side_effects,
-                           network=network)
+                           network=network, mode=mode, base=base,
+                           allow_host_mutation=allow_host_mutation,
+                           no_cache=no_cache)
         run = result.to_dict()
         lines = [_verdict_line(run), f"run {run['run_id']}  host={run['host_os']}"]
         fp = run.get("fingerprint") or {}
@@ -232,6 +288,86 @@ def handle_ci(action: str, job: str, run_id: str, allow_foreign: bool,
                          f"{row.get('started_at', '')[:19]}  {tally}")
         return finalize("c3_ci", args, "\n".join(lines), f"{len(rows)} runs")
 
+    # ── history / intelligence ───────────────────────────────────────────
+    if action in ("history", "intel", "flaky"):
+        from services import ci_intel
+        data = ci_intel.analyse(project)
+        if not data["runs_analysed"]:
+            return finalize("c3_ci", args, data["note"], "no history")
+        lines = [data["note"], ""]
+        if data["flaky"]:
+            lines.append("FLAKY — passed AND failed on identical inputs:")
+            for job in data["flaky"]:
+                lines.append(f"  {job['key']}  {job['failed']}/{job['executed']} failed")
+                lines.append("      same fingerprint gave both answers, so the "
+                             "code did not change between them")
+            lines.append("")
+        lines.append(f"{'job':<40}{'exec':>5}{'fail':>6}{'rate':>7}{'avg':>8}")
+        for job in data["jobs"][:15]:
+            rate = f"{job['fail_rate']:.0%}" if job["executed"] else "-"
+            avg = f"{job['avg_ms'] / 1000:.1f}s" if job["avg_ms"] else "-"
+            mark = "" if job["confident"] else "  (low n)"
+            lines.append(f"  {job['key']:<38}{job['executed']:>5}"
+                         f"{job['failed']:>6}{rate:>7}{avg:>8}{mark}")
+        if data["slowest"]:
+            lines.append("\nSlowest: " + ", ".join(
+                f"{j['key']} {j['avg_ms'] / 1000:.1f}s" for j in data["slowest"][:3]))
+        return finalize("c3_ci", args, "\n".join(lines),
+                        f"{len(data['flaky'])} flaky")
+
+    # ── publish (GitHub commit status) ───────────────────────────────────
+    if action == "publish":
+        from services import ci_github
+        run = cr.load_run(project, run_id)
+        if not run:
+            return finalize("c3_ci", args, "No run to publish.", "no runs")
+        res = ci_github.publish(project, run,
+                                force=allow_side_effects,
+                                dry_run=(job or "").lower() == "dry-run")
+        if res.get("dry_run"):
+            body = "\n".join([
+                f"Would POST {res['endpoint']}",
+                f"  state={res['state']}",
+                f"  {res['description']}",
+            ])
+            return finalize("c3_ci", args, body, "dry run")
+        if not res.get("published"):
+            return finalize("c3_ci", args,
+                            f"Not published: {res.get('reason')}", "refused")
+        body = (f"Published {res['state']} to {res['sha'][:8]} "
+                f"as {res['context']}.\n  {res['description']}")
+        return finalize("c3_ci", args, body, res["state"])
+
+    # ── cache ────────────────────────────────────────────────────────────
+    if action == "cache":
+        from services import ci_cache
+        if (job or "").strip().lower() == "clear" or run_id == "clear":
+            freed = ci_cache.clear(project)
+            return finalize("c3_ci", args,
+                            f"Cleared the CI cache ({freed / 1024:.0f} KB).",
+                            "cache cleared")
+        info = ci_cache.stats(project)
+        rules = ci_impact.load_rules(project)
+        lines = [
+            f"Cached results: {info['results']}",
+            f"Dependency cache keys: {info['dependency_keys']}",
+            f"Location: {info['dir']}",
+            "",
+            "A job is reused when its definition, engine and inputs are all "
+            "unchanged since it last passed.",
+        ]
+        if rules:
+            lines.append(
+                f"{len(rules)} job(s) declare inputs via ci.required_map, so "
+                "only those paths invalidate them.")
+        else:
+            lines.append(
+                "No ci.required_map: every job is fingerprinted over the whole "
+                "tree, so any edit invalidates every cached result. Declaring "
+                "inputs is what makes the cache bite.")
+        return finalize("c3_ci", args, "\n".join(lines),
+                        f"{info['results']} cached")
+
     # ── doctor ───────────────────────────────────────────────────────────
     if action == "doctor":
         from services import ci_act

{code_context_control-2.81.0 → code_context_control-2.85.0/code_context_control.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.81.0
+Version: 2.85.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.81.0 → code_context_control-2.85.0}/code_context_control.egg-info/SOURCES.txt

@@ -186,8 +186,12 @@ services/benchmark_dashboard.py
 services/bitbucket_client.py
 services/bitbucket_credentials.py
 services/ci_act.py
+services/ci_cache.py
 services/ci_expr.py
 services/ci_failures.py
+services/ci_github.py
+services/ci_impact.py
+services/ci_intel.py
 services/ci_runner.py
 services/ci_workflow.py
 services/circuit_breaker.py
@@ -283,7 +287,10 @@ tests/test_c3_bridge_project_artifacts.py
 tests/test_c3_shell.py
 tests/test_chat_poll.py
 tests/test_ci_act.py
+tests/test_ci_cache.py
 tests/test_ci_expr.py
+tests/test_ci_impact.py
+tests/test_ci_intel.py
 tests/test_ci_runner.py
 tests/test_ci_workflow.py
 tests/test_circuit_breaker.py

{code_context_control-2.81.0 → code_context_control-2.85.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.81.0"
+version = "2.85.0"
 description = "Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub."
 readme = "README.md"
 requires-python = ">=3.10"

{code_context_control-2.81.0 → code_context_control-2.85.0}/services/ci_act.py

@@ -154,6 +154,42 @@ def side_effects(inst) -> list:
     return found
 
 
+# ── Host-mutation gate (native engine only) ─────────────────────────────────
+# Learned the hard way, on this repository. A required-mode run selected every
+# job and the native engine executed C3's own `test` job, whose steps are
+# `python -m pip install -e ".[dev]"`. That uninstalled the copied C3 from
+# site-packages and replaced it with an editable install pointing at the repo;
+# the run then timed out mid-write and left the package — and every project's
+# hooks — broken.
+#
+# The native engine has no isolation: a `run:` step executes as the user, on
+# the user's machine, against the user's interpreter. Most CI jobs begin by
+# installing dependencies, so "run the repo's real CI natively" means "let a
+# YAML file reconfigure this machine". Under act the same step is contained and
+# harmless, which is why the refusal points there rather than just saying no.
+_HOST_MUTATION = re.compile(
+    r"(?:^|[\s;&|])(?:"
+    r"pip\s+(?:install|uninstall)|pip3\s+(?:install|uninstall)"
+    r"|python\s+-m\s+pip\s+(?:install|uninstall)"
+    r"|npm\s+(?:i|install)\s+(?:-g|--global)|npm\s+uninstall\s+(?:-g|--global)"
+    r"|yarn\s+global\s+add|pnpm\s+add\s+(?:-g|--global)"
+    r"|apt(?:-get)?\s+(?:install|remove|purge)|yum\s+install|dnf\s+install"
+    r"|brew\s+(?:install|uninstall)|choco\s+install|winget\s+install"
+    r"|cargo\s+install|go\s+install|gem\s+install"
+    r"|rustup\s|nvm\s+install|conda\s+(?:install|remove)"
+    r")\b", re.IGNORECASE)
+
+
+def host_mutations(inst) -> list:
+    """Steps that would reconfigure THIS machine if run without a container."""
+    found: list = []
+    for step in getattr(inst, "steps", []):
+        match = _HOST_MUTATION.search(str(getattr(step, "run", "") or ""))
+        if match:
+            found.append(f"step {step.index} runs `{match.group(0).strip()}`")
+    return found
+
+
 # ── Command construction ────────────────────────────────────────────────────
 
 def build_command(inst, project, act_path: str, event: str = "",