code-context-control 2.127.0__py3-none-any.whl → 2.129.0__py3-none-any.whl

cli/_hook_utils.py

@@ -8,6 +8,7 @@ All hook reads/writes of enforcement state MUST go through this module.
 import json
 import os
 import re
+import shlex
 import sys
 import traceback
 from datetime import datetime, timezone
@@ -34,6 +35,27 @@ LEGACY_UNLOCK_FILE = ".c3/unlocked_files.json"
 STATE_WARNINGS: list = []
 
 
+def hook_command_arg(raw) -> str:
+    """Quote one argv element for a hook ``command`` string in settings.
+
+    Windows: a DOUBLE-quoted forward-slash path. Claude Code runs hooks through
+    Git Bash, where ``shlex.quote`` produces SINGLE quotes around a backslash
+    path — cmd.exe does not treat single quotes as quoting, so any path with a
+    space or parentheses (``Claude Code Companion (C3)``) breaks. A
+    double-quoted forward-slash path is parsed correctly by bash AND cmd.
+    Verified 2026-07-26 under Git Bash on Windows 11; the installer in
+    cli/c3.py carries the full investigation, including why no ``cmd.exe /c``
+    wrapper belongs here.
+
+    Anything that writes a hook command — the installer and the hub's
+    migration — must go through this, or the entry it writes is dead on
+    Windows.
+    """
+    if sys.platform == "win32":
+        return '"' + str(raw).replace("\\", "/") + '"'
+    return shlex.quote(str(raw))
+
+
 def ensure_utf8_stdio() -> None:
     """Force UTF-8 on the hook process's stdio pipes.
 

cli/c3.py

@@ -33,7 +33,6 @@ import json
 import logging
 import os
 import re
-import shlex
 import subprocess
 import sys
 import tempfile
@@ -92,7 +91,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.127.0"
+__version__ = "2.129.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -5542,10 +5541,10 @@ def cmd_install_mcp(args):
         # the wrapper was never needed. A double-quoted forward-slash path is parsed
         # correctly by bash AND cmd, including paths containing spaces or parentheses
         # (e.g. "Claude Code Companion (C3)"), which is why the wrapper was added.
-        def _hook_arg(raw: str) -> str:
-            if sys.platform == "win32":
-                return '"' + str(raw).replace("\\", "/") + '"'
-            return shlex.quote(str(raw))
+        # Lives in cli/_hook_utils so the hub's hook migration quotes commands
+        # the same way — it used shlex.quote and wrote entries that Windows
+        # could not run.
+        from cli._hook_utils import hook_command_arg as _hook_arg
 
         # v2.42: single dispatcher script per hook event instead of N separate
         # per-hook commands. One interpreter spawn per event; the dispatcher

cli/hook_session_open.py

@@ -22,6 +22,14 @@ Records:
 - a ``session`` notification (``kind="session"``, ``ref_id=host id``,
   ``info``, title ``Session started <short id>``).
 
+It also brings up the project's UI server when one is not already running
+(``ensure_ui`` below, v2.128.0) — the only place in C3 where "a session
+started" causes "the UI is up". It needs the project to be registered with
+the hub, and it skips a project that already has a live UI port, so a
+``resume`` or ``clear`` never stacks a second server. Opt out with
+``C3_NO_UI_AUTOSTART=1`` or
+``.c3/config.json → {"ui": {"autostart_on_session": false}}``.
+
 ``source: "compact"`` writes NOTHING: a compaction is the same session and
 the same MCP process, and a "Session started" toast on every compaction
 would teach the user to ignore the real ones.
@@ -37,6 +45,8 @@ this hook has nothing to tell the model.
 """
 from __future__ import annotations
 
+import json
+import os
 import sys
 from pathlib import Path
 
@@ -48,6 +58,98 @@ from cli.hook_session_end import short_id  # noqa: E402
 _SILENT_SOURCES = {"compact"}
 
 
+def _ui_autostart_enabled(project: Path) -> bool:
+    """Opt-outs, in the order a user reaches for them."""
+    if os.environ.get("C3_NO_UI_AUTOSTART") or os.environ.get("C3_BENCHMARK_MODE"):
+        return False
+    try:
+        cfg = json.loads((project / ".c3" / "config.json").read_text(encoding="utf-8"))
+    except Exception:
+        return True  # no readable config is not a reason to withhold the UI
+    ui = cfg.get("ui")
+    if isinstance(ui, dict) and "autostart_on_session" in ui:
+        return bool(ui.get("autostart_on_session"))
+    return True
+
+
+def _is_registered(pm, project: Path) -> bool:
+    """True when the hub knows this project.
+
+    The UI server is a hub-level surface: a directory the user never
+    registered gets nothing automatic (``c3 ui`` still works). This is also
+    what keeps a test fixture or a scratch clone from growing a web server.
+    """
+    target = os.path.normcase(str(project))
+    for entry in pm._read_projects():
+        raw = str(entry.get("path") or "")
+        if raw and os.path.normcase(raw) == target:
+            return True
+        try:
+            if raw and os.path.normcase(str(Path(raw).resolve())) == target:
+                return True
+        except Exception:
+            continue
+    return False
+
+
+def _ui_running(pm, project: Path) -> bool:
+    """True when a live UI server is already registered for this project.
+
+    This is what keeps `resume` / `clear` — both real SessionStart events —
+    from stacking a second server on every reconnect.
+    """
+    target = os.path.normcase(str(project))
+    for entry in pm._read_registry():
+        raw = str(entry.get("project_path") or "")
+        if not raw:
+            continue
+        try:
+            same = os.path.normcase(str(Path(raw).resolve())) == target
+        except Exception:
+            same = os.path.normcase(raw) == target
+        if same and entry.get("port") and pm._port_alive(entry["port"]):
+            return True
+    return False
+
+
+def ensure_ui(project: Path, host_session_id: str = "") -> str:
+    """Bring up this project's UI server for the session that just opened.
+
+    Nothing else in C3 connected "a session started" to "the UI is running":
+    the hub's sweep only chases projects flagged `autostart_ui`, and before
+    2.128.0 it ran once at hub startup — so a UI was only ever there because
+    an earlier session had left one behind.
+
+    Returns a short reason string (tests and diagnostics read it). Never
+    raises and never prints — SessionStart stdout becomes model context.
+    """
+    try:
+        project = Path(project).resolve()
+    except Exception:
+        project = Path(project)
+    if not _ui_autostart_enabled(project):
+        return "disabled"
+    try:
+        from services.project_manager import ProjectManager
+        pm = ProjectManager()
+        if not _is_registered(pm, project):
+            return "unregistered"
+        if _ui_running(pm, project):
+            return "already-running"
+        # launch_session copies os.environ into the detached child, which is
+        # where cli/server._register_session reads the ownership from.
+        os.environ["C3_UI_OWNER"] = "session"
+        if host_session_id:
+            os.environ["C3_UI_OWNER_SESSION"] = host_session_id
+        result = pm.launch_session(str(project))
+        if result.get("launched"):
+            return "launched"
+        return f"failed: {result.get('error', '')}".strip()
+    except Exception as exc:
+        log_hook_error("hook_session_open", exc)
+        return "error"
+
+
 def run(payload: dict, project_path: Path | None = None):
     """Core logic — importable by the dispatcher and tests. Returns None."""
     start_source = str(payload.get("source") or "").strip().lower()
@@ -76,11 +178,11 @@ def run(payload: dict, project_path: Path | None = None):
                kind="session", ref_id=host_sid)
     except Exception:
         pass
+    ensure_ui(project, host_sid)
     return None
 
 
 def main() -> None:
-    import json
     try:
         data = json.load(sys.stdin)
     except Exception as exc:

cli/hub_server.py

@@ -29,6 +29,7 @@ from flask import Flask, jsonify, redirect, request, send_from_directory
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
+from cli._hook_utils import hook_command_arg
 from core.ide import PROFILES, detect_ide, get_profile, load_ide_config, normalize_ide_name
 from services import access_guard
 from services.activity_log import ActivityLog
@@ -71,8 +72,14 @@ _HUB_CONFIG_DEFAULTS = {
     "projects_view": "list",
     "main_view": "projects",
     "oracle_url": "",
+    # Minutes of project silence, with no session heartbeat left, before a UI
+    # server that an IDE session launched is stopped. 0 = never reap.
+    "ui_reap_minutes": 30,
 }
 
+# How often the hub reaps orphaned UI servers and chases autostart projects.
+_UI_SWEEP_INTERVAL_S = 60
+
 
 def _read_hub_config() -> dict:
     cfg = dict(_HUB_CONFIG_DEFAULTS)
@@ -4373,28 +4380,168 @@ def method_not_allowed(e):
 
 # ─── Hook migration ──────────────────────────────────────────────────────────
 
-def _migrate_project_hooks():
-    """Idempotently add new C3 hooks to all registered projects' Claude and Gemini settings.
+def _has_matcher(value: str):
+    return lambda entries: any(e.get("matcher") == value for e in entries)
+
+
+def _has_command(fragment: str):
+    return lambda entries: any(
+        fragment in (hk.get("command") or "")
+        for e in entries
+        for hk in e.get("hooks", [])
+    )
+
+
+def c3_hook_migrations(cli_dir: Path | None = None) -> list:
+    """C3's own hook entries, per settings file and hook event.
+
+    Adding a hook to the installer (``cli/c3.py``) does NOT reach a project
+    that is already installed. The v2.126.0 SessionStart / SessionEnd entries
+    landed in the installer only, so every existing project kept writing no
+    ``session_open`` / ``session_end`` rows at all — 60 projects on the
+    machine this was found on, including C3's own. This table is how they
+    catch up: the hub applies it at startup, additively and idempotently.
 
-    Runs at hub startup so that existing projects pick up hook changes
-    without requiring a manual 'c3 mcp install' on each project.
+    ``present`` decides "C3's entry for this event is already here", so a
+    re-run is a no-op and a user's own entries for the same event survive.
     """
-    cli_dir = Path(__file__).parent
-    hook_c3read_cmd = (
-        f"{shlex.quote(sys.executable)} "
-        f"{shlex.quote(str(cli_dir / 'hook_c3read.py'))}"
+    cli_dir = cli_dir or Path(__file__).parent
+    # hook_command_arg, not shlex.quote: on Windows the latter writes a
+    # single-quoted backslash path that cmd.exe does not unquote, so every
+    # command this table produced for a path with a space — every path under
+    # "1. Projects", say — was dead on arrival. The installer has used the
+    # double-quoted forward-slash form since 2026-07-26; this now matches it.
+    dispatch = (
+        f"{hook_command_arg(sys.executable)} "
+        f"{hook_command_arg(str(cli_dir / 'hook_dispatch.py'))}"
     )
-    new_hook = {
+    c3read_entry = {
         "matcher": "mcp__c3__c3_read",
-        "hooks": [{"type": "command", "command": hook_c3read_cmd}],
+        "hooks": [{
+            "type": "command",
+            "command": (f"{hook_command_arg(sys.executable)} "
+                        f"{hook_command_arg(str(cli_dir / 'hook_c3read.py'))}"),
+        }],
     }
+    c3read_present = _has_matcher("mcp__c3__c3_read")
+    dispatch_present = _has_command("hook_dispatch.py")
+
+    def _lifecycle(event: str, arg: str) -> dict:
+        return {
+            "settings": ".claude/settings.local.json",
+            "event": event,
+            "present": dispatch_present,
+            "entry": {"matcher": "",
+                      "hooks": [{"type": "command",
+                                 "command": f"{dispatch} {arg}"}]},
+        }
 
-    # (settings_path, hook_event) pairs to check per project
-    _HOOK_TARGETS = [
-        (".claude/settings.local.json", "PostToolUse"),
-        (".gemini/settings.json", "AfterTool"),
+    return [
+        {"settings": ".claude/settings.local.json", "event": "PostToolUse",
+         "present": c3read_present, "entry": c3read_entry},
+        {"settings": ".gemini/settings.json", "event": "AfterTool",
+         "present": c3read_present, "entry": c3read_entry},
+        # Claude only — Gemini has no session-lifecycle event to hang these on.
+        _lifecycle("SessionStart", "start"),
+        _lifecycle("SessionEnd", "end"),
     ]
 
+
+def _command_cli_dir(command: str) -> Path | None:
+    """The C3 ``cli/`` directory a hook command points at, if any."""
+    try:
+        tokens = shlex.split(str(command or ""), posix=False)
+    except ValueError:
+        tokens = str(command or "").split()
+    for token in tokens:
+        token = token.strip("'\"")
+        if not token.endswith(".py"):
+            continue
+        candidate = Path(token)
+        if not candidate.name.startswith("hook_"):
+            continue
+        parent = candidate.parent
+        if (parent / "hook_dispatch.py").is_file():
+            return parent
+    return None
+
+
+def detect_project_cli_dir(path: str) -> Path | None:
+    """The ``cli/`` directory this project's existing C3 hooks already use.
+
+    The hub runs from wherever C3 is installed, so building commands from its
+    own location writes install paths into a project that was installed from a
+    checkout — C3's own repo above all, where the working tree IS the runtime.
+    A hook edited there would then change nothing until the next install. Match
+    what the project already points at; the caller falls back to ours.
+    """
+    for rel_settings in (".claude/settings.local.json", ".gemini/settings.json"):
+        settings_path = Path(path) / rel_settings
+        if not settings_path.exists():
+            continue
+        try:
+            with open(settings_path, encoding="utf-8") as f:
+                hooks = (json.load(f).get("hooks") or {})
+        except Exception:
+            continue
+        for entries in hooks.values():
+            for entry in entries or []:
+                for hook in (entry or {}).get("hooks", []):
+                    found = _command_cli_dir((hook or {}).get("command") or "")
+                    if found is not None:
+                        return found
+    return None
+
+
+def migrate_hooks_for_project(path: str, migrations: list | None = None) -> int:
+    """Apply the hook table to one project. Returns settings files changed.
+
+    Never creates a settings file that is not already there: a project with no
+    ``.claude/settings.local.json`` has not been installed for Claude, and the
+    hub is not the place to decide that it should be.
+    """
+    if migrations is None:
+        migrations = c3_hook_migrations(detect_project_cli_dir(path))
+    by_file: dict = {}
+    for migration in migrations:
+        by_file.setdefault(migration["settings"], []).append(migration)
+
+    changed_files = 0
+    for rel_settings, items in by_file.items():
+        settings_path = Path(path) / rel_settings
+        if not settings_path.exists():
+            continue
+        try:
+            with open(settings_path, encoding="utf-8") as f:
+                settings = json.load(f)
+        except Exception:
+            continue
+        changed = False
+        for migration in items:
+            event = migration["event"]
+            existing = list(settings.get("hooks", {}).get(event, []))
+            if migration["present"](existing):
+                continue
+            existing.append(migration["entry"])
+            settings.setdefault("hooks", {})[event] = existing
+            changed = True
+        if not changed:
+            continue
+        try:
+            with open(settings_path, "w", encoding="utf-8") as f:
+                json.dump(settings, f, indent=2)
+            changed_files += 1
+        except Exception:
+            pass
+    return changed_files
+
+
+def _migrate_project_hooks():
+    """Idempotently add missing C3 hooks to every registered project.
+
+    Runs at hub startup so existing projects pick up hook changes without a
+    manual 'c3 install-mcp' per project.
+    """
     try:
         projects = _pm().list_projects()
     except Exception:
@@ -4405,32 +4552,13 @@ def _migrate_project_hooks():
         path = p.get("path", "")
         if not path:
             continue
-        for rel_settings, hook_event in _HOOK_TARGETS:
-            settings_path = Path(path) / rel_settings
-            if not settings_path.exists():
-                continue
-            try:
-                with open(settings_path, encoding="utf-8") as f:
-                    settings = json.load(f)
-            except Exception:
-                continue
-
-            existing = settings.get("hooks", {}).get(hook_event, [])
-            if any(h.get("matcher") == "mcp__c3__c3_read" for h in existing):
-                continue  # already present — skip
-
-            existing.append(new_hook)
-            settings.setdefault("hooks", {})[hook_event] = existing
-            try:
-                with open(settings_path, "w", encoding="utf-8") as f:
-                    json.dump(settings, f, indent=2)
-                updated += 1
-            except Exception:
-                pass
+        # No shared table: each project's entries are built against the cli_dir
+        # that project's existing C3 hooks already point at.
+        updated += migrate_hooks_for_project(path)
 
     if updated:
         logging.getLogger(__name__).info(
-            "[c3] Migrated hook_c3read to %d project settings file(s)", updated
+            "[c3] Migrated C3 hooks into %d project settings file(s)", updated
         )
 
 
@@ -4478,21 +4606,39 @@ def run_hub(
         pass
     _migrate_project_hooks()
 
-    # Auto-launch UI servers for projects with autostart_ui=True
-    def _autostart_ui_servers():
+    # Periodic UI sweep. Before 2.128 this ran ONCE, two seconds after
+    # startup, over autostart_ui projects — so a project whose session started
+    # after the hub (the normal case), or whose UI died mid-session, never got
+    # one. Now it also reaps the session-owned servers whose session is gone.
+    def _ui_sweep_loop():
         import time
         time.sleep(2)  # Give Flask a moment to bind
-        try:
-            pm = _pm()
-            for proj_path in pm.get_autostart_projects():
-                try:
-                    pm.launch_session(proj_path)
-                except Exception:
-                    pass
-        except Exception:
-            pass
+        first_pass = True
+        while True:
+            try:
+                pm = _pm()
+                pm.sweep_registry()
+                wanted = set(pm.get_autostart_projects())
+                if wanted:
+                    for proj in pm.list_projects():
+                        if proj.get("path") not in wanted or proj.get("ui_active"):
+                            continue
+                        # First pass keeps the old contract ("autostart launches
+                        # the UI when the hub starts"); later passes only chase
+                        # projects that actually have a live session.
+                        if not (first_pass or proj.get("session_active")):
+                            continue
+                        try:
+                            pm.launch_session(proj["path"])
+                        except Exception:
+                            pass
+            except Exception:
+                pass
+            first_pass = False
+            time.sleep(_UI_SWEEP_INTERVAL_S)
 
-    threading.Thread(target=_autostart_ui_servers, daemon=True).start()
+    threading.Thread(target=_ui_sweep_loop, daemon=True,
+                     name="c3-hub-ui-sweep").start()
 
     bind_host = str(cfg.get("host", "127.0.0.1") or "127.0.0.1").strip()
     if bind_host not in ("127.0.0.1", "localhost", "::1") and not quiet:

cli/hub_ui/components/project_card.js

@@ -493,7 +493,12 @@ function ProjectCard({ p, isChild, rollup, expanded, onToggleExpand, onChanged,
     } catch (err) { notify('IDE: ' + err.message, 'err'); }
   };
 
-  const portLabel = p.port ? `:${p.port}` : (p.session_active ? 'MCP' : '—');
+  // session_count > 1 = two IDEs / a repo and its worktrees on one project.
+  const sessionCount = p.session_count || (p.session_active ? 1 : 0);
+  const mcpLabel = sessionCount > 1 ? `MCP×${sessionCount}` : 'MCP';
+  const portLabel = p.port
+    ? (sessionCount > 1 ? `:${p.port} · ${mcpLabel}` : `:${p.port}`)
+    : (p.session_active ? mcpLabel : '—');
   const metaText = `${ideLabel(p.ide)} · ${portLabel} · ${p.last_session ? timeAgo(p.last_session) : 'never'}`;
 
   const identity = (

cli/mcp_server.py

@@ -321,6 +321,33 @@ async def lifespan(server):
             **({"host_session_id": _host_sid} if _host_sid else {}),
         })
 
+    # Liveness heartbeat: THIS process is the session, so say so in a file a
+    # reader can trust. Without it the hub has to infer liveness from tool
+    # activity, which calls a quiet-but-open session dead after 20 min and a
+    # closed one live for 20 min. Refreshed on a 60 s daemon thread (same
+    # shape as _bg_convo_sync) and removed in the finally block below.
+    _heartbeat_stop = threading.Event()
+    _live_session_id = str((services.session_mgr.current_session or {}).get("id") or "")
+    if _live_session_id:
+        from services import session_live
+
+        def _do_beat():
+            session_live.beat(services.project_path, _live_session_id,
+                              host_session_id=_host_session_id(services) or "",
+                              ide=_IDE_NAME)
+
+        _do_beat()
+
+        def _bg_heartbeat():
+            while not _heartbeat_stop.wait(timeout=session_live.HEARTBEAT_INTERVAL_S):
+                try:
+                    _do_beat()
+                except Exception:
+                    pass
+
+        threading.Thread(target=_bg_heartbeat, daemon=True,
+                         name="c3-session-heartbeat").start()
+
     # Auto-restore latest snapshot if recent (< 30 min).
     # Deferred to background thread so first tool call isn't blocked.
     # Skipped in benchmark mode to prevent snapshot budget from carrying over between tasks.
@@ -391,6 +418,15 @@ async def lifespan(server):
         yield services
     finally:
         _convo_sync_stop.set()
+        # Stop claiming to be alive before anything slow runs: a reader that
+        # polls during teardown should already see this session as gone.
+        _heartbeat_stop.set()
+        if _live_session_id:
+            try:
+                from services import session_live as _sl
+                _sl.clear(services.project_path, _live_session_id)
+            except Exception:
+                pass
         # Auto-memory: extract remaining learnings and generate session summary.
         if hasattr(services, "auto_memory"):
             try:
@@ -698,7 +734,10 @@ async def c3_read(file_path: str, symbols: Any = None, lines: Any = None,
     """READ source, or MAP a file when called with only file_path (read-only, plan-mode safe).
     file_path: single or comma-separated. symbols: names as the map prints them (Class.method ok).
     lines: int, [start,end], or list of ranges. No symbols/lines = one line per symbol with
-    signature and [La-Lb] range at ~10% of the file's tokens; then read the symbols you need."""
+    signature and [La-Lb] range at ~10% of the file's tokens; then read the symbols you need.
+    Paths OUTSIDE the project root are read too (sibling repo, extra working dir, installed
+    package source): tagged [c3-read:external], served from a transient record, never added
+    to this project's index or related facts. Access Guard rules still apply there."""
     path_err = validate_file_path(file_path)
     if path_err:
         return f"[c3_read:error] {path_err}"

cli/server.py

@@ -108,11 +108,18 @@ def _register_session(port: int, project_path: str, project_name: str):
         entries = _registry_read()
         # Remove our own port and any stale (dead) entries
         entries = [e for e in entries if e.get("port") != port and _port_alive(e.get("port", 0))]
+        # owner says who asked for this server: "session" when an IDE session
+        # start launched it (cli/hook_session_open), "user" for `c3 ui`, the
+        # hub's Open UI button and the TUI. Only session-owned servers are
+        # ever reaped automatically (ProjectManager.sweep_registry).
         entries.append({
             "port": port,
             "project_path": project_path,
             "project_name": project_name,
             "started_at": time.time(),
+            "pid": os.getpid(),
+            "owner": (os.environ.get("C3_UI_OWNER") or "user").strip().lower(),
+            "owner_session": (os.environ.get("C3_UI_OWNER_SESSION") or "").strip(),
         })
         _registry_write(entries)
 

cli/tools/_helpers.py

@@ -147,6 +147,40 @@ _HEREDOC_MARKERS = {
 _GHOST_NAMES = _PYTHON_TYPE_NAMES | _HEREDOC_MARKERS
 
 
+EXTERNAL_TAG = "[c3-read:external]"
+
+
+def external_banner(path: str) -> str:
+    """The one line every outside-the-root response opens with.
+
+    One definition so c3_read and c3_compress cannot drift apart on it.
+    """
+    return (f"{EXTERNAL_TAG} {path} — outside the project root; served but "
+            f"not indexed, and absent from this project's search, map cache "
+            f"and related facts.\n")
+
+
+def project_key(full, project_path) -> tuple[str, bool]:
+    """``(key, external)`` for an already-resolved-or-not path.
+
+    Inside the root the key is the project-relative posix path — how
+    file_memory, the edit ledger and related facts all address a file.
+    Outside it there is no such key, so the absolute posix path stands in and
+    ``external`` tells the caller to serve from a transient record rather than
+    the index (docs/file-map.md § Outside the root).
+
+    This used to be a bare ``relative_to`` whose ValueError escaped as a tool
+    crash. It is not a containment check and must not become one: Access Guard
+    already rules on the absolute canonical path, and it runs before this.
+    """
+    resolved = Path(full).resolve()
+    try:
+        rel = resolved.relative_to(Path(project_path).resolve())
+        return str(rel).replace("\\", "/"), False
+    except ValueError:
+        return resolved.as_posix(), True
+
+
 def validate_file_path(file_path: str) -> str | None:
     """Return an error message if file_path looks like a ghost-file path, else None.
 

cli/tools/ci.py

@@ -385,6 +385,15 @@ def handle_ci(action: str, job: str, run_id: str, allow_foreign: bool,
                 f"            runs Linux jobs in a container "
                 f"({ci_act.DEFAULT_IMAGE}), real `uses:` actions included",
             ]
+            if state.get("warning"):
+                lines.append(f"            WARNING: {state['warning']}")
+            # An image that is present locally is still not proof act can pull
+            # it: act sends the stored registry credential where the CLI sends
+            # none, so an expired token fails a public pull (issue #173). Say
+            # so rather than let `available` read as a guarantee.
+            lines.append("            a runner failure before any step runs is "
+                         "reported as a container-setup failure, not as 0 "
+                         "parsed failures")
         else:
             lines += ["  act       UNAVAILABLE", f"            {state['reason']}"]
         lines += [