aisc-cli 0.1.0__py3-none-any.whl

aisc/application/workspace_reconcile.py

@@ -0,0 +1,318 @@
+"""Workspace reconcile (runtime-lifecycle-ux Stage 1, 02 §3).
+
+One idempotent operation answering "may this Workbench instance start a
+runtime in this workspace, and what shall it do with leftovers?" — the
+frontend never assembles list/inspect/remove sequences itself (02 §3:
+"前端不得先 list、过一段时间再无锁 remove").
+
+Classification (frozen):
+
+- ``clean``                  — nothing to do; start.
+- ``active_same_instance``   — this instance already holds the lease
+                               (frontend focuses the existing workspace).
+- ``stale_ephemeral``        — expired/legacy Workbench runtime recycled
+                               (stop -> inspect -> remove -> prune);
+                               safe to start.
+- ``active_other_instance``  — a fresh lease belongs to another instance;
+                               BLOCK (minimal block page in the UI).
+- ``unknown_owner``          — registry/Docker evidence cannot prove AISC
+                               ownership (owner missing / not workbench /
+                               unverifiable); BLOCK, diagnostic path —
+                               never auto-delete (safety invariant 1).
+- ``stale_registry``         — registry entries whose containers are gone;
+                               registry pruned (idempotently); start.
+- ``docker_unavailable``     — no destructive action, no "not_found"
+                               conclusions (safety invariant 3); BLOCK.
+
+Lock order (frozen, cross-plan): docker-maintenance lock -> workspace
+lock -> registry transaction. Reconcile is the reference implementer of
+that order. Expiry of a lease NEVER authorizes deletion by itself — the
+registry/Docker-label reconciliation below IS the required re-verification
+(invariant 2; covers sleep-resume where the clock jumped past the TTL).
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from aisc.adapters.container_registry import (
+    list_containers_readonly,
+    unregister,
+)
+from aisc.adapters.data_root_store import DataRootStore
+from aisc.adapters.maintenance_lock import docker_maintenance_lock
+from aisc.adapters.workspace_lease_store import WorkspaceLeaseStore
+from aisc.application.data_root import DataRootResolver
+from aisc.applog import append_event
+from aisc.domain.models import RuntimeErrorCode
+from aisc.domain.workspace_lease import WorkspaceLease
+
+#: Envelope schema stamp (02 §3 JSON).
+RECONCILE_SCHEMA = "aisc.runtime-reconcile/v1"
+
+#: Registry metadata: lifecycle values reconcile recycles vs keeps.
+LIFECYCLE_EPHEMERAL = "ephemeral"
+
+#: retention values that keep the container alive across close (advanced).
+RETENTION_KEEP = ("keep_stopped", "keep_running")
+
+
+def _workspace_scoped_containers(ws_key: str, executor: Any) -> List[Dict[str, str]]:
+    """Docker containers labeled ``io.aisc.workspace-key=<ws_key>``.
+
+    Machine tab format via ``docker ps`` (labels ride the AISC ownership
+    contract; the classification never trusts names alone for new
+    resources). Empty on any Docker hiccup — callers treat that as
+    "docker-side evidence unavailable", never as "no containers".
+    """
+    try:
+        result = executor.run_captured(
+            [
+                "ps", "-a",
+                "--filter", f"label=io.aisc.workspace-key={ws_key}",
+                "--format", "{{.ID}}\t{{.Names}}\t{{.Status}}\t"
+                            "{{.Label \"io.aisc.runtime-id\"}}\t"
+                            "{{.Label \"io.aisc.owner\"}}",
+            ],
+            timeout=10.0,
+        )
+    except Exception:
+        return []
+    if getattr(result, "exit_code", 1) != 0:
+        return []
+    rows: List[Dict[str, str]] = []
+    for line in (result.stdout or "").splitlines():
+        parts = [p.strip() for p in line.split("\t")]
+        if len(parts) >= 3:
+            rows.append({
+                "container_id": parts[0],
+                "container_name": parts[1],
+                "status": parts[2],
+                "runtime_id": parts[3] if len(parts) > 3 else "",
+                "owner": parts[4] if len(parts) > 4 else "",
+            })
+    return rows
+
+
+def _status_to_state(status: str) -> str:
+    if not status:
+        return "unknown"
+    return "running" if status.startswith("Up") else "stopped"
+
+
+def reconcile_workspace(
+    workspace: str,
+    instance_id: str,
+    executor: Any,
+    registry_root: Optional[Path] = None,
+    env: Optional[Dict[str, str]] = None,
+) -> Dict[str, Any]:
+    """Run one reconcile pass and return the frozen JSON envelope.
+
+    ``env`` overrides the data-root environment (hermetic tests). The
+    function reports; it never raises for classification outcomes — only
+    for programming errors. Destructive actions touch ONLY resources
+    proven owned (owner=workbench, ephemeral-or-legacy) after lease and
+    Docker-side verification, under maintenance -> workspace locks.
+    """
+    from aisc.adapters.container_registry import workspace_lock
+    from aisc.application.runtime import (
+        _check_docker,
+        _resolve_registry_root,
+        workspace_key_for,
+    )
+
+    canonical = str(Path(workspace).resolve())
+    ws_key = workspace_key_for(canonical)
+    reg_root = _resolve_registry_root(canonical, registry_root)
+
+    resolved = DataRootResolver(env=env).resolve(Path(canonical))
+    store = DataRootStore(resolved)
+    store.prepare()
+    leases = WorkspaceLeaseStore(store, ws_key)
+
+    def envelope(
+        classification: str,
+        *,
+        runtime_id: Optional[str],
+        can_proceed: bool,
+        cleanup: Dict[str, Any],
+        error_code: Optional[str] = None,
+        technical_detail: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "schema_version": RECONCILE_SCHEMA,
+            "workspace_key": ws_key,
+            "classification": classification,
+            "runtime_id": runtime_id,
+            "can_proceed": can_proceed,
+            "cleanup": cleanup,
+            "observed_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "error_code": error_code,
+            "technical_detail": technical_detail,
+        }
+        action = {"clean": "skip", "stale_ephemeral": "remove", "stale_registry": "remove"}.get(
+            classification, "block"
+        )
+        result = "ok" if error_code is None else "error"
+        append_event(
+            "runtime_reconcile", source="cli",
+            workspace_hash=ws_key,
+            classification=classification,
+            action=action, result=result,
+        )
+        return payload
+
+    # --- 1. Fresh lease short-circuits everything -------------------------
+    lease: Optional[WorkspaceLease] = leases.inspect()
+    if lease is not None and not lease.is_expired():
+        if lease.held_by(instance_id):
+            return envelope(
+                "active_same_instance", runtime_id=None, can_proceed=False,
+                cleanup=_no_cleanup(),
+            )
+        return envelope(
+            "active_other_instance", runtime_id=None, can_proceed=False,
+            cleanup=_no_cleanup(),
+            error_code=RuntimeErrorCode.ACTIVE_WORKSPACE_LEASE,
+            technical_detail="workspace leased by another Workbench instance",
+        )
+
+    # --- 2. Docker unavailable: no destructive action, no conclusions ------
+    if not _check_docker(executor):
+        return envelope(
+            "docker_unavailable", runtime_id=None, can_proceed=False,
+            cleanup=_no_cleanup(),
+            error_code=RuntimeErrorCode.DOCKER_UNAVAILABLE,
+            technical_detail="docker daemon/CLI unavailable; nothing removed",
+        )
+
+    # --- 3. Recycle stale owned runtimes under maintenance -> workspace ----
+    cleanup = _no_cleanup()
+    saw_unknown_owner = False
+    saw_recycled = False
+    saw_registry_prune = False
+    last_runtime_id: Optional[str] = None
+    failure: Optional[str] = None
+
+    with docker_maintenance_lock(store):
+        with workspace_lock(reg_root, ws_key, timeout=30.0):
+            try:
+                registry_entries = list_containers_readonly(reg_root)
+            except Exception as exc:  # corrupted registry: fail closed
+                return envelope(
+                    "unknown_owner", runtime_id=None, can_proceed=False,
+                    cleanup=cleanup,
+                    error_code=RuntimeErrorCode.RUNTIME_OWNER_UNKNOWN,
+                    technical_detail=f"registry unreadable: {exc}",
+                )
+
+            docker_rows = _workspace_scoped_containers(ws_key, executor)
+            docker_by_name = {r["container_name"]: r for r in docker_rows}
+
+            targets: List[Dict[str, Any]] = []
+            for name, meta in registry_entries.items():
+                if not isinstance(meta, dict):
+                    continue
+                if meta.get("workspace_key") != ws_key and meta.get("workspace") != canonical:
+                    continue
+                targets.append({"name": name, "meta": meta, "source": "registry"})
+            for name, row in docker_by_name.items():
+                if name not in registry_entries:
+                    targets.append({"name": name, "meta": {}, "source": "docker_only"})
+
+            for target in targets:
+                name = target["name"]
+                meta = target["meta"]
+                owner = str(meta.get("owner") or row_owner(docker_by_name.get(name)))
+                lifecycle = str(meta.get("lifecycle") or "")
+                retention = str(meta.get("retention") or "")
+                runtime_id = str(meta.get("runtime_id") or "")
+
+                # Owned = workbench-created and ephemeral (or legacy: no
+                # lifecycle field yet — product table row 3 recycles it).
+                # Anything else: non-ephemeral/keep policies are silently
+                # KEPT (advanced retention); unprovable ownership BLOCKS
+                # (unknown_owner, invariant 1 — never auto-deleted).
+                is_owned = owner == "workbench" and lifecycle in ("", LIFECYCLE_EPHEMERAL)
+                if not is_owned:
+                    saw_unknown_owner = True
+                    continue
+                if retention in RETENTION_KEEP:
+                    continue
+
+                state = docker_state(name, executor, docker_by_name)
+                cleanup["attempted"] = True
+                last_runtime_id = runtime_id or None
+                if state == "not_found":
+                    # Stale registry record: prune only, idempotent.
+                    unregister(reg_root, name)
+                    cleanup["registry_pruned"] = True
+                    saw_registry_prune = True
+                    continue
+                if state == "running":
+                    stop = executor.stop_container(name, timeout=10)
+                    if stop.exit_code != 0:
+                        failure = f"stop failed for {name}"
+                        continue
+                    cleanup["stopped"] = True
+                rm = executor.remove_container(name, force=True)
+                if rm.exit_code != 0:
+                    failure = f"remove failed for {name}"
+                    continue
+                cleanup["removed"] = True
+                saw_recycled = True
+                if name in registry_entries:
+                    unregister(reg_root, name)
+                    cleanup["registry_pruned"] = True
+
+            # Idempotency guard: a second pass must see nothing left to do
+            # (verified by tests re-running reconcile end-to-end).
+    if saw_unknown_owner:
+        return envelope(
+            "unknown_owner", runtime_id=last_runtime_id, can_proceed=False,
+            cleanup=cleanup,
+            error_code=RuntimeErrorCode.RUNTIME_OWNER_UNKNOWN,
+            technical_detail="unowned/unverifiable runtime present; nothing deleted for it",
+        )
+    if failure is not None:
+        # Cleanup attempted but incomplete: the leftovers are still there —
+        # report the stale state honestly with can_proceed=False rather
+        # than pretending any classification resolved cleanly.
+        return envelope(
+            "stale_ephemeral" if cleanup["attempted"] else "clean",
+            runtime_id=last_runtime_id, can_proceed=False,
+            cleanup=cleanup,
+            error_code=RuntimeErrorCode.RUNTIME_RECONCILE_FAILED,
+            technical_detail=failure,
+        )
+    if saw_recycled:
+        classification = "stale_ephemeral"
+    elif saw_registry_prune:
+        classification = "stale_registry"
+    else:
+        classification = "clean"
+    return envelope(
+        classification, runtime_id=last_runtime_id, can_proceed=True,
+        cleanup=cleanup,
+    )
+
+
+def row_owner(row: Optional[Dict[str, str]]) -> str:
+    return (row or {}).get("owner", "")
+
+
+def docker_state(name: str, executor: Any, docker_by_name: Dict[str, Dict[str, str]]) -> str:
+    """Docker-side state for *name*: prefer the label query row; fall back
+    to a direct inspect (also distinguishes not_found)."""
+    if name in docker_by_name:
+        return _status_to_state(docker_by_name[name]["status"])
+    from aisc.application.runtime import _get_container_state
+
+    return _get_container_state(name, executor) or "unknown"
+
+
+def _no_cleanup() -> Dict[str, Any]:
+    return {"attempted": False, "stopped": False, "removed": False, "registry_pruned": False}

aisc/applog.py

@@ -0,0 +1,103 @@
+"""Lifecycle event log (P1, lifecycle-logging round) — the CLI-side appender.
+
+One JSONL event per line in ``<shared data root>/logs/aisc.log``, appended by
+BOTH the Python CLI (``source: "cli"``) and the Workbench's Rust side
+(``source: "app"``) — a single timeline a ``run_id`` threads end to end
+(the Workbench injects ``AISC_RUN_ID`` into child env; the envelope reuses it).
+
+Red line (allowed-fields-only, mirrors the diagnostic bundle's D6-05/06
+philosophy): stdin payloads, subscription URLs, API keys, PTY content, full
+environments and absolute workspace paths NEVER enter the log. The schema is
+fixed-key by construction — redaction by design, not by filtering.
+
+Failure policy: logging must never break a command — every write is
+best-effort; resolver/IO errors are swallowed (the in-memory op path and the
+stdout envelope remain authoritative).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+#: Rotation bounds — byte sizes kept identical to the Rust side
+#: (workbench/src-tauri/src/logging.rs) so either appender rotates the file.
+MAX_BYTES = 2 * 1024 * 1024
+KEEP_ROUNATED = 2  # aisc.log + .1 + .2
+
+LOG_DIR_NAME = "logs"
+LOG_FILE_NAME = "aisc.log"
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def log_file_path(*, env=None) -> Optional[Path]:
+    """Resolve the shared log file path; None when the data root can't be
+    resolved (fail-open — callers then skip logging)."""
+    try:
+        from aisc.application.data_root import shared_root
+
+        root = shared_root(env if env is not None else os.environ)
+    except Exception:
+        return None
+    return root / LOG_DIR_NAME / LOG_FILE_NAME
+
+
+def _rotate(path: Path) -> None:
+    """Size-capped rotation: aisc.log -> aisc.log.1 -> aisc.log.2 (oldest
+    dropped)."""
+    try:
+        if not path.exists() or path.stat().st_size < MAX_BYTES:
+            return
+        for i in range(KEEP_ROUNATED - 1, 0, -1):
+            src = path.with_name(f"{path.name}.{i}")
+            dst = path.with_name(f"{path.name}.{i + 1}")
+            if src.exists():
+                src.replace(dst)
+        path.replace(path.with_name(f"{path.name}.1"))
+    except OSError:
+        pass  # rotation failure must never block the append
+
+
+def append_event(
+    event: str,
+    *,
+    level: str = "info",
+    source: str = "cli",
+    run_id: Optional[str] = None,
+    detail: Optional[str] = None,
+    env=None,
+    **fields: Any,
+) -> None:
+    """Append one lifecycle event; never raises.
+
+    ``fields`` are extra fixed-schema keys (``command``, ``exit_code``,
+    ``duration_ms``, ``error_code`` …) — callers pass only allowlisted,
+    secret-free values.
+    """
+    path = log_file_path(env=env if env is not None else os.environ)
+    if path is None:
+        return
+    record: Dict[str, Any] = {
+        "ts": _utc_now(),
+        "level": level,
+        "source": source,
+        "event": event,
+    }
+    if run_id:
+        record["run_id"] = run_id
+    if detail:
+        record["detail"] = detail
+    record.update(fields)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        _rotate(path)
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record, ensure_ascii=True, separators=(",", ":")) + "\n")
+    except Exception:
+        return  # best-effort by contract

aisc/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package — argument parsing and command dispatch."""

aisc/cli/build_progress_parser.py

@@ -0,0 +1,217 @@
+"""v2.1.7 S4 (Gate-S4): docker build output → structured build.progress.
+
+Pure, stateful parser fed with the raw docker stdout/stderr chunks (the same
+bytes that ride ``build.output``). Emits at most one ``ProgressUpdate`` per
+recognised line; unrecognised lines are ignored — the raw log is the only
+place they matter (honest-progress rule: never fabricate a step).
+
+Two output formats are recognised (the docker argv deliberately stays
+untouched — forcing ``--progress=plain`` would break the legacy builder):
+
+* BuildKit plain (piped stdout uses it automatically):
+  ``#12 [3/7] RUN apt-get update`` / ``#12 CACHED`` / ``#12 DONE ...`` /
+  ``#12 exporting to image`` / ``naming to docker.io/super-claude:latest``.
+* Legacy builder: ``Step 3/12 : RUN ...`` / ``Successfully built <id>``.
+
+Honesty invariants enforced here (Gate-S4 §1):
+  * ``percent`` only when a step mapping is known; monotonic, never lower;
+  * never reaches 100 (capped at 99.9) — only build.complete means done;
+  * pull work is its own indeterminate phase (no fake byte percent).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+# BuildKit plain: "#12 [3/7] RUN apt-get update" (inner stage step) or
+# "#12 exporting to image" (phase text without [i/t]).
+_BUILDKIT_STEP = re.compile(r"^#\d+ \[(\d+)/(\d+)\] (.*)$")
+_BUILDKIT_PHASE = re.compile(r"^#\d+ (.+)$")
+
+# "transferring context: 247.12MB 5.2s" / "... 1.2GB done" — cumulative
+# bytes WITHOUT a total (BuildKit never announces the context size), so the
+# prepare bar can only be determinate against an ESTIMATED denominator.
+_CONTEXT_BYTES = re.compile(
+    r"^transferring context: ([\d.]+)\s*(B|kB|MB|GB|TB)\b", re.I
+)
+_UNIT_MULT = {"b": 1.0, "kb": 1e3, "mb": 1e6, "gb": 1e9, "tb": 1e12}
+
+
+def _fmt_mb(n: float) -> str:
+    return f"{n / 1e6:.1f}MB"
+
+
+def parse_context_bytes(line: str) -> Optional[float]:
+    """Cumulative transferred bytes from a `transferring context:` line."""
+    m = _CONTEXT_BYTES.match(line)
+    if not m:
+        return None
+    return float(m.group(1)) * _UNIT_MULT[m.group(2).lower()]
+# Legacy builder: "Step 3/12 : RUN ..." / bare "Step 3 : ..."
+_LEGACY_STEP = re.compile(r"^Step (\d+)(?:/(\d+))? : (.*)$")
+
+_PHASE_PATTERNS = (
+    (re.compile(r"^(?:resolve|pulling|sha256:|docker\.io|Downloading|extracting|Pulling)", re.I), "pull"),
+    (re.compile(r"^(?:transferring context|load build definition|load \.dockerignore|load metadata)", re.I), "prepare"),
+    (re.compile(r"^exporting (?:to image|layers|manifest)", re.I), "export"),
+    (re.compile(r"^(?:naming to|writing image|loaded image|tagged)", re.I), "export"),
+    (re.compile(r"^Successfully (?:built|tagged)", re.I), "done"),
+)
+
+
+@dataclass
+class ProgressUpdate:
+    """One build.progress payload (Gate-S4 §1 field contract)."""
+
+    phase: str
+    step_current: Optional[int]
+    step_total: Optional[int]
+    percent: Optional[float]
+    progress_kind: str  # determinate | indeterminate
+    summary: str
+
+
+class BuildProgressParser:
+    """Feed raw chunks; collect :class:`ProgressUpdate` for each recognised
+    line. Monotonic by construction: percent only ever rises."""
+
+    def __init__(self, context_total_bytes: Optional[float] = None) -> None:
+        self._step_current = 0
+        self._step_total: Optional[int] = None
+        self._last_percent = 0.0
+        self._phase = "prepare"
+        # Estimated context denominator from the PREVIOUS build's log
+        # (Gate-S4 §1 amendment): enables a determinate prepare bar that is
+        # explicitly marked ≈ in the summary and capped at 95.
+        self._context_total_bytes = context_total_bytes
+
+    # -- helpers -----------------------------------------------------------
+
+    def _percent(self, current: int, total: Optional[int]) -> Optional[float]:
+        if not total or total <= 0 or current < 1:
+            return None
+        raw = min(current / total, 1.0) * 100.0
+        # Never 100 before build.complete, never regress.
+        raw = min(raw, 99.9)
+        if raw < self._last_percent:
+            raw = self._last_percent
+        self._last_percent = raw
+        return round(raw, 1)
+
+    def _update(
+        self,
+        phase: str,
+        summary: str,
+        *,
+        step_current: Optional[int] = None,
+        step_total: Optional[int] = None,
+    ) -> ProgressUpdate:
+        self._phase = phase
+        cur = step_current if step_current is not None else self._step_current
+        tot = step_total if step_total is not None else self._step_total
+        if step_total is not None and (self._step_total is None or step_total > self._step_total):
+            self._step_total = step_total
+        if cur is not None and cur >= 0:
+            self._step_current = cur
+        percent = self._percent(cur, tot) if phase == "steps" else None
+        return ProgressUpdate(
+            phase=phase,
+            step_current=cur if phase == "steps" else None,
+            step_total=tot if phase == "steps" else None,
+            percent=percent,
+            progress_kind="determinate" if percent is not None else "indeterminate",
+            summary=summary,
+        )
+
+    def _context_update(self, line: str) -> ProgressUpdate:
+        """`transferring context` — cumulative bytes only. With an estimated
+        denominator from the previous build, emit a determinate ≈ percent
+        (capped at 95 — the real total is unknown); otherwise stay
+        indeterminate with the live byte count as the summary."""
+        self._phase = "prepare"
+        cur = parse_context_bytes(line)
+        total = self._context_total_bytes
+        if cur is not None and total and total > 0:
+            raw = min(cur / total, 0.95) * 100.0
+            if raw < self._last_percent:
+                raw = self._last_percent
+            self._last_percent = raw
+            return ProgressUpdate(
+                phase="prepare",
+                step_current=None,
+                step_total=int(total),
+                percent=round(raw, 1),
+                progress_kind="determinate",
+                summary=f"≈ {_fmt_mb(cur)} / ≈ {_fmt_mb(total)}",
+            )
+        return ProgressUpdate(
+            phase="prepare",
+            step_current=None,
+            step_total=None,
+            percent=None,
+            progress_kind="indeterminate",
+            summary=line,
+        )
+
+    # -- api ---------------------------------------------------------------
+
+    @property
+    def phase(self) -> str:
+        return self._phase
+
+    def feed(self, chunk: str) -> list[ProgressUpdate]:
+        """Parse one raw chunk; return the updates for its recognised lines."""
+        updates: list[ProgressUpdate] = []
+        for line in chunk.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                continue
+            upd = self._parse_line(stripped)
+            if upd is not None:
+                updates.append(upd)
+        return updates
+
+    def _parse_line(self, line: str) -> Optional[ProgressUpdate]:
+        m = _BUILDKIT_STEP.match(line)
+        if m:
+            cur, tot, desc = int(m.group(1)), int(m.group(2)), m.group(3)
+            return self._update("steps", desc, step_current=cur, step_total=tot)
+
+        m = _LEGACY_STEP.match(line)
+        if m:
+            cur = int(m.group(1))
+            tot = int(m.group(2)) if m.group(2) else None
+            return self._update("steps", m.group(3), step_current=cur, step_total=tot)
+
+        for pattern, phase in _PHASE_PATTERNS:
+            if pattern.match(line):
+                if phase == "prepare":
+                    return self._context_update(line)
+                return self._update(phase, line)
+
+        # BuildKit bare phase lines ("#12 exporting to image", "#7 DONE").
+        m = _BUILDKIT_PHASE.match(line)
+        if m:
+            text = m.group(1).strip()
+            if text.lower() == "done":
+                # completion of a single step — not the build's end
+                return None
+            # 2026-08-27 manual test (full-cache build): a CACHED step carries
+            # no [i/t] header, so a fully-cached build otherwise shows ZERO
+            # motion. Surface it as an indeterminate steps-phase update — no
+            # fabricated step number, percent stays honest (null).
+            if text.lower() == "cached":
+                return ProgressUpdate(
+                    phase="steps",
+                    step_current=None,
+                    step_total=self._step_total,
+                    percent=None,
+                    progress_kind="indeterminate",
+                    summary="CACHED",
+                )
+            mapped = next((p for pat, p in _PHASE_PATTERNS if pat.match(text)), None)
+            if mapped:
+                return self._update(mapped, text)
+        return None

aisc/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command implementations."""