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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.80.0
+Version: 2.81.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
@@ -202,7 +202,7 @@ C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_session` | Snapshot, restore, log decisions, compact history |
 | `c3_impact` | Blast-radius analysis before editing shared symbols |
 | `c3_locks` | Agent leases — who is working on which file, so two agents don't collide (v2.65.0) |
-| `c3_ci` | Run this repo's real `.github/workflows` locally, with structured failures, before pushing (v2.79.0) |
+| `c3_ci` | Run this repo's real `.github/workflows` locally — in containers via `act` — with structured failures, before pushing (v2.79.0) |
 | `c3_delegate` | Offload heavy work to local Ollama / Codex / Gemini |
 | `c3_agent` | Workflows: `review_changes`, `investigate`, `preflight`, `prepare_context`, `validate_compress` |
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter, `verify` (did a failed `c3_edit` still land?) |

{code_context_control-2.80.0 → code_context_control-2.81.0}/README.md

@@ -139,7 +139,7 @@ C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_session` | Snapshot, restore, log decisions, compact history |
 | `c3_impact` | Blast-radius analysis before editing shared symbols |
 | `c3_locks` | Agent leases — who is working on which file, so two agents don't collide (v2.65.0) |
-| `c3_ci` | Run this repo's real `.github/workflows` locally, with structured failures, before pushing (v2.79.0) |
+| `c3_ci` | Run this repo's real `.github/workflows` locally — in containers via `act` — with structured failures, before pushing (v2.79.0) |
 | `c3_delegate` | Offload heavy work to local Ollama / Codex / Gemini |
 | `c3_agent` | Workflows: `review_changes`, `investigate`, `preflight`, `prepare_context`, `validate_compress` |
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter, `verify` (did a failed `c3_edit` still land?) |

{code_context_control-2.80.0 → code_context_control-2.81.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.80.0"
+__version__ = "2.81.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -6079,7 +6079,10 @@ def _ci_main(args) -> int:
                 allow_foreign=bool(getattr(args, "allow_foreign", False)),
                 only=only, timeout=getattr(args, "timeout", 0) or cr.DEFAULT_STEP_TIMEOUT,
                 workflow=getattr(args, "workflow", ""),
-                event=getattr(args, "event", "") or "").to_dict()
+                event=getattr(args, "event", "") or "",
+                engine=getattr(args, "engine", "auto") or "auto",
+                allow_side_effects=bool(getattr(args, "allow_side_effects", False)),
+                network=getattr(args, "network", "") or "").to_dict()
         elif sub == "runs":
             payload = {"runs": cr.list_runs(project_path)}
         else:
@@ -6098,7 +6101,10 @@ def _ci_main(args) -> int:
         bool(getattr(args, "allow_foreign", False)),
         getattr(args, "workflow", "") or "", getattr(args, "tail", 200) or 200,
         getattr(args, "timeout", 0) or 0, svc, finalize,
-        getattr(args, "event", "") or "")
+        getattr(args, "event", "") or "",
+        getattr(args, "engine", "auto") or "auto",
+        bool(getattr(args, "allow_side_effects", False)),
+        getattr(args, "network", "") or "")
     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.80.0 → code_context_control-2.81.0}/cli/commands/parser.py

@@ -500,6 +500,16 @@ def build_parser(version: str, parse_cli_ide_arg):
                              "can never yield FULL_CI_PASS)")
     ci_run.add_argument("--timeout", type=int, default=0,
                         help="Per-step timeout in seconds (default 900)")
+    ci_run.add_argument("--engine", choices=["auto", "native", "act"],
+                        default="auto",
+                        help="auto (default) uses act for Linux jobs when act + "
+                             "Docker are present, native otherwise")
+    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("--network", default="",
+                        help="Container network for the act engine (e.g. `none` "
+                             "to cut egress). Default: act's own.")
 
     ci_rerun = _ci_common(ci_subs.add_parser(
         "rerun", help="Re-run only the jobs that failed in the last run"))
@@ -520,6 +530,8 @@ 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_common(ci_subs.add_parser(
+        "doctor", help="Which execution engines are available on this machine"))
 
     # ── Override Requests (v2.69.0, docs/override-requests.md) ──────────
     # Human-only approval surface. A grant is single-use, session-bound,

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

@@ -1293,11 +1293,12 @@ _ci_runs: dict = {}          # project path -> in-flight state
 _ci_lock = threading.Lock()
 
 
-def _ci_worker(project: str, job: str, allow_foreign: bool, workflow: str) -> None:
+def _ci_worker(project: str, job: str, allow_foreign: bool, workflow: str,
+               engine: str = "auto") -> None:
     from services import ci_runner as cr
     try:
         result = cr.run_ci(project, selector=job, allow_foreign=allow_foreign,
-                           workflow=workflow)
+                           workflow=workflow, engine=engine)
         payload = {"running": False, "done": True, "error": None,
                    "run_id": result.run_id, "verdict": result.verdict,
                    "note": result.note}
@@ -1320,7 +1321,12 @@ def api_ci_inspect():
     except ValueError as e:
         return jsonify({"error": str(e)}), 404
     try:
-        return jsonify(inspect_project(resolved))
+        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)
     except Exception as e:
         return jsonify({"error": f"{type(e).__name__}: {e}"}), 500
 
@@ -1391,7 +1397,8 @@ def api_ci_run_start():
     threading.Thread(
         target=_ci_worker,
         args=(resolved, str(data.get("job") or ""),
-              bool(data.get("allow_foreign")), str(data.get("workflow") or "")),
+              bool(data.get("allow_foreign")), str(data.get("workflow") or ""),
+              str(data.get("engine") or "auto")),
         daemon=True,
     ).start()
     return jsonify({"started": True})

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

@@ -142,6 +142,7 @@ function HubCI({ projects, onOpenDrill }) {
   };
 
   const jobs = (inspect && inspect.jobs) || [];
+  const engines = inspect && inspect.engines;
   const runJobs = ((run && run.jobs) || []).filter(j => j.status !== 'deselected');
 
   return (
@@ -172,8 +173,16 @@ function HubCI({ projects, onOpenDrill }) {
         border: `1px solid ${T.border}`, borderRadius: 6, padding: '8px 10px', lineHeight: 1.5,
       }}>
         Runs the repository's real <span className="mono">.github/workflows</span> here —
-        C3 does not define a second CI config. Jobs targeting another OS are refused
-        unless you opt in, and a cross-OS result is indicative, never equivalent.
+        C3 does not define a second CI config.{' '}
+        {engines && engines.ok ? (
+          <span>Linux jobs run in a container via <span className="mono">act</span>{' '}
+            ({engines.act_version}, docker {engines.docker_version}), real actions included.</span>
+        ) : (
+          <span style={{ color: T.warn }}>
+            Container engine unavailable — {(engines && engines.reason) || 'checking…'}
+          </span>
+        )}{' '}
+        macOS jobs can never run locally: there are no macOS containers.
       </div>
 
       {err && (
@@ -236,8 +245,12 @@ function HubCI({ projects, onOpenDrill }) {
                 <span className="mono" style={{
                   color: T.text, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
                 }}>{j.key}</span>
-                {j.cross_os && j.status === 'passed' && (
-                  <span className="mono" title={`Ran on this host, but targets ${j.runs_on}.`}
+                {j.status === 'passed' && j.fidelity === 'container' && (
+                  <span className="mono" title={`Ran in a container of ${j.runs_on} via act — real actions included.`}
+                    style={{ fontSize: 10, color: T.accent }}>container</span>
+                )}
+                {j.status === 'passed' && j.fidelity === 'cross-os' && (
+                  <span className="mono" title={`Ran on this host, but targets ${j.runs_on}. Indicative, not equivalent.`}
                     style={{ fontSize: 10, color: T.blue }}>cross-OS</span>
                 )}
                 <div style={{ flex: 1 }} />
@@ -277,9 +290,12 @@ function HubCI({ projects, onOpenDrill }) {
               borderTop: `1px solid ${T.border}`, fontSize: 11,
             }}>
               <CiStatusPill
-                status={!j.supported ? 'unsupported' : (j.foreign_runner ? 'foreign' : 'passed')}
-                title={!j.supported ? (j.blockers || []).join('; ')
-                  : (j.foreign_runner ? `targets ${j.runs_on}` : 'runnable on this host')} />
+                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'))} />
               <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.80.0 → code_context_control-2.81.0}/cli/mcp_server.py

@@ -770,10 +770,11 @@ async def c3_locks(action: str = "list", paths: str = "", intent: str = "",
 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 = "",
-                ctx: Context = None) -> str:
+                engine: str = "auto", allow_side_effects: bool = False,
+                network: str = "", 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 (default) | run | rerun | status | failures | logs | runs.
+    actions: inspect | run | rerun | status | failures | logs | runs | doctor.
     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
@@ -796,7 +797,8 @@ async def c3_ci(action: str = "inspect", job: str = "", run_id: str = "",
     from cli.tools.ci import handle_ci
     return await asyncio.to_thread(handle_ci, action, job, run_id,
                                    allow_foreign, workflow, tail, timeout,
-                                   svc, finalize, event)
+                                   svc, finalize, event, engine,
+                                   allow_side_effects, network)
 
 
 @mcp.tool()

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

@@ -39,7 +39,12 @@ def _job_rows(jobs: list, include_deselected: bool = False) -> list:
         if status == cr.DESELECTED and not include_deselected:
             continue
         mark = _MARK.get(status, status.upper())
-        cross = " [cross-OS]" if job.get("cross_os") and status == cr.PASSED else ""
+        fid = job.get("fidelity", "")
+        cross = ""
+        if status == cr.PASSED and fid == cr.FIDELITY_CONTAINER:
+            cross = " [container]"
+        elif status == cr.PASSED and fid == cr.FIDELITY_CROSS_OS:
+            cross = " [cross-OS]"
         ms = job.get("duration_ms") or 0
         timing = f"  {ms / 1000:.1f}s" if ms else ""
         line = f"  {mark:<9} {job.get('key', '?')}{cross}{timing}"
@@ -75,7 +80,8 @@ 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 = "") -> str:
+              event: str = "", engine: str = "auto",
+              allow_side_effects: bool = False, network: str = "") -> str:
     """Route c3_ci actions."""
     project = str(svc.project_path)
     action = (action or "inspect").strip().lower()
@@ -151,7 +157,9 @@ def handle_ci(action: str, job: str, run_id: str, allow_foreign: bool,
 
         result = cr.run_ci(project, selector=job, allow_foreign=allow_foreign,
                            only=only, timeout=timeout or cr.DEFAULT_STEP_TIMEOUT,
-                           workflow=workflow, event=event)
+                           workflow=workflow, event=event, engine=engine,
+                           allow_side_effects=allow_side_effects,
+                           network=network)
         run = result.to_dict()
         lines = [_verdict_line(run), f"run {run['run_id']}  host={run['host_os']}"]
         fp = run.get("fingerprint") or {}
@@ -224,6 +232,34 @@ 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")
 
+    # ── doctor ───────────────────────────────────────────────────────────
+    if action == "doctor":
+        from services import ci_act
+        state = ci_act.availability()
+        lines = [
+            "Local CI execution engines:",
+            "",
+            f"  native    available — runs jobs whose runs-on matches "
+            f"{cr.host_os()}",
+        ]
+        if state["ok"]:
+            lines += [
+                f"  act       available — {state['act_version']}, "
+                f"docker {state['docker_version']}",
+                f"            runs Linux jobs in a container "
+                f"({ci_act.DEFAULT_IMAGE}), real `uses:` actions included",
+            ]
+        else:
+            lines += ["  act       UNAVAILABLE", f"            {state['reason']}"]
+        lines += [
+            "",
+            "macOS jobs cannot run locally on any engine — there are no macOS "
+            "containers, so a matrix containing them can never reach "
+            "FULL_CI_PASS here.",
+        ]
+        return finalize("c3_ci", args, "\n".join(lines),
+                        "act ready" if state["ok"] else "act unavailable")
+
     return finalize("c3_ci", args,
                     f"Unknown action '{action}'. Use: inspect, run, rerun, "
-                    "status, failures, logs, runs.", "unknown action")
+                    "status, failures, logs, runs, doctor.", "unknown action")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.80.0
+Version: 2.81.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
@@ -202,7 +202,7 @@ C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_session` | Snapshot, restore, log decisions, compact history |
 | `c3_impact` | Blast-radius analysis before editing shared symbols |
 | `c3_locks` | Agent leases — who is working on which file, so two agents don't collide (v2.65.0) |
-| `c3_ci` | Run this repo's real `.github/workflows` locally, with structured failures, before pushing (v2.79.0) |
+| `c3_ci` | Run this repo's real `.github/workflows` locally — in containers via `act` — with structured failures, before pushing (v2.79.0) |
 | `c3_delegate` | Offload heavy work to local Ollama / Codex / Gemini |
 | `c3_agent` | Workflows: `review_changes`, `investigate`, `preflight`, `prepare_context`, `validate_compress` |
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter, `verify` (did a failed `c3_edit` still land?) |

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

@@ -185,6 +185,7 @@ services/auto_memory.py
 services/benchmark_dashboard.py
 services/bitbucket_client.py
 services/bitbucket_credentials.py
+services/ci_act.py
 services/ci_expr.py
 services/ci_failures.py
 services/ci_runner.py
@@ -281,6 +282,7 @@ tests/test_bitbucket_tool.py
 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_expr.py
 tests/test_ci_runner.py
 tests/test_ci_workflow.py

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.80.0"
+version = "2.81.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/services/ci_act.py

@@ -0,0 +1,274 @@
+"""AgentCI — the `act` execution engine (Linux jobs in real containers).
+
+The native engine runs a job's shell steps on this machine. That is faithful
+when `runs-on` matches the host and an approximation otherwise, and it cannot
+run `uses:` actions at all. This engine hands a Linux job to `nektos/act`,
+which runs it in a container using GitHub's own workflow semantics — real
+actions included.
+
+What that buys, measured on this repository from Windows: 3 of 15 jobs
+runnable natively, 11 with containers. The remaining four are macOS cells, and
+no amount of Docker fixes those — **there are no macOS containers**, so a full
+local pass on a matrix containing them stays out of reach. Saying so is part of
+the job.
+
+Three things learned by probing rather than by reading, all load-bearing:
+
+1. **`--bind` is required on Windows.** act's default copies the workspace into
+   the container; against a Windows host path that silently produced an empty
+   directory and every step failed on missing files. `--bind` mounts the real
+   working tree and works even on a mapped drive whose path contains spaces and
+   parentheses. The trade-off is that the container writes into the real tree —
+   the same thing the native engine already does, so behaviour is consistent.
+
+2. **`-P <label>=<image>` must always be passed.** Without it act prompts
+   interactively on first use to choose an image size, which would hang any
+   automated run.
+
+3. **`-W <file>` is mandatory when two workflows share a job name.** act says so
+   itself on this repo, where `CI` and `Release` both define `build` — the same
+   collision the DAG scopes around.
+
+Safety: this engine never passes real secrets or tokens. act reads `.secrets`
+and `.env` from the repository by default, so both are explicitly pointed at
+empty files. A publish step therefore executes and fails at authentication
+instead of publishing, which is the intended outcome for a local run.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+# act's community runner images. These mirror a good deal of the GitHub
+# runner's preinstalled toolchain; a bare `ubuntu:24.04` does not, and a job
+# that assumes a preinstalled tool then fails locally while passing in CI. A
+# false red is the safe direction, but it is still noise, so default to the
+# image built for the purpose.
+DEFAULT_IMAGE = "catthehacker/ubuntu:act-latest"
+RUNNER_IMAGES = {
+    "ubuntu-latest": DEFAULT_IMAGE,
+    "ubuntu-24.04": "catthehacker/ubuntu:act-24.04",
+    "ubuntu-22.04": "catthehacker/ubuntu:act-22.04",
+    "ubuntu-20.04": "catthehacker/ubuntu:act-20.04",
+}
+
+# Pulling a runner image is ~1 GB on first use, so the act engine gets its own,
+# larger default ceiling than a native shell step.
+DEFAULT_ACT_TIMEOUT = 3600
+
+
+def image_for(runs_on: str) -> str:
+    label = str(runs_on or "").strip().lower()
+    return RUNNER_IMAGES.get(label, DEFAULT_IMAGE)
+
+
+def find_act() -> str:
+    """Path to the act binary. C3_ACT_PATH wins, then PATH."""
+    override = (os.environ.get("C3_ACT_PATH") or "").strip()
+    if override and Path(override).is_file():
+        return override
+    return shutil.which("act") or ""
+
+
+def _probe(cmd: list, timeout: int = 30) -> tuple:
+    try:
+        out = subprocess.run(cmd, capture_output=True, text=True,
+                             timeout=timeout, stdin=subprocess.DEVNULL,
+                             **({"creationflags": subprocess.CREATE_NO_WINDOW}
+                                if os.name == "nt" else {}))
+        return out.returncode, (out.stdout or "") + (out.stderr or "")
+    except Exception as exc:
+        return 127, f"{type(exc).__name__}: {exc}"
+
+
+def availability() -> dict:
+    """Can this engine run at all? Reports WHY not, never just False.
+
+    Both halves are checked because they fail independently and a user with
+    act installed but Docker stopped deserves to be told which one to fix.
+    """
+    act = find_act()
+    info: dict = {"ok": False, "act": act, "act_version": "",
+                  "docker": False, "docker_version": "", "reason": ""}
+    if not act:
+        info["reason"] = ("`act` is not installed. Install it with "
+                          "`winget install nektos.act` (Windows), "
+                          "`brew install act` (macOS), or see "
+                          "https://nektosact.com — then re-run.")
+        return info
+    rc, out = _probe([act, "--version"])
+    if rc != 0:
+        info["reason"] = f"`act --version` failed: {out.strip()[:200]}"
+        return info
+    info["act_version"] = out.strip().splitlines()[0] if out.strip() else ""
+
+    rc, out = _probe(["docker", "version", "--format", "{{.Server.Version}}"])
+    if rc != 0:
+        info["reason"] = ("Docker is not reachable — the act engine needs a "
+                          "running daemon. Start Docker Desktop (or dockerd) "
+                          f"and retry. Probe said: {out.strip()[:160]}")
+        return info
+    info["docker"] = True
+    info["docker_version"] = out.strip().splitlines()[-1] if out.strip() else ""
+    info["ok"] = True
+    return info
+
+
+# ── Side-effect gate ────────────────────────────────────────────────────────
+# With a real action runner, jobs that were previously unrunnable become
+# runnable — including ones whose entire purpose is to publish. Capability no
+# longer protects anybody, so policy has to.
+PUBLISHING_ACTIONS = (
+    "pypa/gh-action-pypi-publish",
+    "softprops/action-gh-release",
+    "ncipollo/release-action",
+    "actions/create-release",
+    "docker/build-push-action",
+    "peaceiris/actions-gh-pages",
+    "actions/deploy-pages",
+    "js-devtools/npm-publish",
+    "gradle/gradle-publish",
+    "cycjimmy/semantic-release-action",
+)
+_PUBLISH_CMD = re.compile(
+    r"\b(twine\s+upload|npm\s+publish|cargo\s+publish|gh\s+release\s+create"
+    r"|docker\s+push|poetry\s+publish|aws\s+s3\s+(cp|sync)|kubectl\s+apply"
+    r"|terraform\s+apply|gcloud\s+.*deploy)\b", re.IGNORECASE)
+
+
+def side_effects(inst) -> list:
+    """Reasons this job looks like it publishes or deploys something."""
+    found: list = []
+    for step in getattr(inst, "steps", []):
+        base = str(getattr(step, "uses", "") or "").split("@", 1)[0].lower()
+        if base in PUBLISHING_ACTIONS:
+            found.append(f"step {step.index} uses `{step.uses}`")
+        match = _PUBLISH_CMD.search(str(getattr(step, "run", "") or ""))
+        if match:
+            found.append(f"step {step.index} runs `{match.group(0)}`")
+    return found
+
+
+# ── Command construction ────────────────────────────────────────────────────
+
+def build_command(inst, project, act_path: str, event: str = "",
+                  image: str = "", network: str = "",
+                  secret_file: str = "", env_file: str = "",
+                  artifact_dir: str = "", pull: bool = True) -> list:
+    """The exact argv handed to act. Pure, so it is unit-testable."""
+    cmd: list = [act_path]
+    if event:
+        cmd.append(event)
+
+    workflow_path = getattr(inst, "workflow_path", "") or ""
+    if workflow_path:
+        try:
+            rel = Path(workflow_path).resolve().relative_to(Path(project).resolve())
+            cmd += ["-W", str(rel).replace("\\", "/")]
+        except ValueError:
+            cmd += ["-W", str(workflow_path)]
+
+    cmd += ["-j", inst.job_id]
+
+    for key, value in sorted((inst.matrix or {}).items()):
+        cmd += ["--matrix", f"{key}:{value}"]
+
+    cmd += ["-P", f"{inst.runs_on}={image or image_for(inst.runs_on)}"]
+
+    # See the module docstring: without --bind the workspace arrives empty on
+    # Windows and every step fails on missing files.
+    cmd.append("--bind")
+    cmd.append(f"--pull={'true' if pull else 'false'}")
+
+    if network:
+        cmd += ["--network", network]
+    # Never let act source the repository's real .secrets / .env.
+    cmd += ["--secret-file", secret_file or os.devnull]
+    cmd += ["--env-file", env_file or os.devnull]
+    if artifact_dir:
+        cmd += ["--artifact-server-path", artifact_dir]
+    return cmd
+
+
+# act prefixes every line it emits with `[Workflow/job]`, and marks actual
+# program output with a `|` gutter:
+#
+#     [CI/lint] ⭐ Run Main ruff check .        <- act's own narration
+#     [CI/lint]   | app/x.py:3:1: F401 ...      <- what the command printed
+#
+# Handing the raw log to the failure parsers captures the prefix as part of the
+# filename — `file=[CI/lint] ⭐ Run Main echo "app/x.py` — which makes the
+# structured failure useless. Parse the gutter lines only.
+_ACT_OUTPUT_LINE = re.compile(r"^\[[^\]]*\]\s{0,3}\|\s?(.*)$")
+
+
+def program_output(text: str) -> str:
+    """Just what the commands printed, with act's prefixes removed.
+
+    Falls back to the raw text when nothing matches, so an act failure that
+    never reached a command (a bad image, a daemon error) still reaches the
+    parsers and the reader rather than becoming an empty log.
+    """
+    lines = [m.group(1) for m in
+             (_ACT_OUTPUT_LINE.match(ln) for ln in (text or "").splitlines())
+             if m]
+    return "\n".join(lines) if lines else (text or "")
+
+
+def run_job(inst, project, timeout: int = DEFAULT_ACT_TIMEOUT,
+            event: str = "", network: str = "", artifact_dir: str = "",
+            act_path: str = "") -> dict:
+    """Run one job through act. Returns {exit_code, output, timed_out, command}."""
+    act_path = act_path or find_act()
+    if not act_path:
+        return {"exit_code": 127, "output": "act is not installed",
+                "timed_out": False, "command": ""}
+
+    tmpdir = tempfile.mkdtemp(prefix="c3act-")
+    empty = Path(tmpdir) / "empty"
+    empty.write_text("", encoding="utf-8")
+
+    cmd = build_command(inst, project, act_path, event=event, network=network,
+                        secret_file=str(empty), env_file=str(empty),
+                        artifact_dir=artifact_dir)
+
+    from cli.tools.shell import _kill_tree, _popen_kwargs
+
+    start = time.time()
+    timed_out = False
+    try:
+        proc = subprocess.Popen(
+            cmd, cwd=str(project), stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT, text=True, encoding="utf-8",
+            errors="replace", **_popen_kwargs(),
+        )
+    except (OSError, ValueError) as exc:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+        return {"exit_code": 126, "output": f"{type(exc).__name__}: {exc}",
+                "timed_out": False, "command": " ".join(cmd)}
+
+    try:
+        output, _ = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        _kill_tree(proc)
+        try:
+            output, _ = proc.communicate(timeout=5)
+        except Exception:
+            output = ""
+        timed_out = True
+        output = (output or "") + (
+            f"\n[c3:ci] act exceeded {timeout}s and its container tree was killed\n")
+
+    shutil.rmtree(tmpdir, ignore_errors=True)
+    return {
+        "exit_code": -1 if timed_out else (proc.returncode or 0),
+        "output": output or "",
+        "timed_out": timed_out,
+        "duration_ms": round((time.time() - start) * 1000),
+        "command": " ".join(cmd),
+    }