@michaelxwb/code-flow 0.6.0 → 0.6.2

package/src/core/code-flow/scripts/cf_spec_context.py

@@ -14,12 +14,12 @@ from pathlib import Path
 import subprocess
 import sys
 import tempfile
+import time
 from typing import IO, Mapping, Optional, Sequence
 
-import yaml
-
 from cf_spec_metadata import SpecHashes, SpecMetadata, SpecRule, load_spec_metadata
 from cf_spec_resolver import SpecCandidate, resolve_candidates
+from cf_core import phase_timing
 
 
 CONTEXT_VERSION = 1
@@ -28,12 +28,17 @@ STAGE_STATUSES = frozenset(
 )
 DECISION_KINDS = frozenset(("not_applicable", "waived", "manual_verification"))
 _AGENT_IDENTITIES = frozenset(("agent", "assistant", "codex", "claude", "opencode", "costrict"))
+_FILE_HASH_CACHE: dict[str, tuple[int, int, int, str]] = {}
+_PERSISTENT_HASH_CACHE: dict[str, dict[str, object]] = {}
+_PERSISTENT_HASH_PATHS: set[str] = set()
+_MAX_HASH_CACHE_ENTRIES = 4096
 ACTIVE_STATUSES = frozenset(("activating", "active", "paused", "blocked", "completed"))
 DEFAULT_ACTIVE_EXCLUDES = (
     ".code-flow/tasks/*",
     ".code-flow/specs/_session/*",
     ".code-flow/migrations/*",
     ".code-flow/.*state*",
+    ".code-flow/.*cache*",
     ".code-flow/.session-log.jsonl",
     ".code-flow/.active-task.json",
     ".code-flow/.active-task.lock",
@@ -208,7 +213,7 @@ def _active_paths(root: str) -> tuple[Path, Path]:
 def _run_git(root: str, arguments: Sequence[str]) -> str:
     try:
         result = subprocess.run(
-            ("git", *arguments), cwd=root, text=True, capture_output=True, check=False
+            ("git", *arguments), cwd=root, text=True, encoding="utf-8", capture_output=True, check=False
         )
     except OSError as exc:
         raise ContextError("git_unavailable", "git", str(exc), root) from exc
@@ -249,10 +254,17 @@ def _git_changes(root: str) -> Mapping[str, str]:
         if len(record) < 4:
             raise ContextError("invalid_git_status", "git.status", record, root)
         code, path = record[:2], record[3:]
+        index += 1
         if "R" in code or "C" in code:
-            raise ContextError("unsupported_git_status", "git.status", code, path)
+            # porcelain -z rename/copy emits two records: "XY <new>" then "<old>"
+            if index >= len(records) or not records[index]:
+                raise ContextError("invalid_git_status", "git.status", f"{code} {path}", root)
+            old_path = records[index]
+            index += 1
+            changes[path] = _status_name(code)
+            changes[old_path] = "deleted"
+            continue
         changes[path] = _status_name(code)
-        index += 1
     return changes
 
 
@@ -260,16 +272,6 @@ def _is_excluded(path: str, patterns: Sequence[str]) -> bool:
     return any(fnmatchcase(path, pattern) for pattern in patterns)
 
 
-def _path_hash(root: str, path: str) -> str:
-    target = Path(root) / path
-    digest = hashlib.sha256()
-    if target.is_file():
-        with target.open("rb") as handle:
-            for chunk in iter(lambda: handle.read(65536), b""):
-                digest.update(chunk)
-    return digest.hexdigest()
-
-
 def _active_data(active: ActiveTask) -> dict[str, object]:
     changes = {
         path: {"status": item.status, "content_sha256": item.content_sha256}
@@ -293,9 +295,10 @@ def _active_data(active: ActiveTask) -> dict[str, object]:
 
 def _snapshot_from_data(value: object, path: str) -> PathSnapshot:
     data = _mapping(value, "preexisting_changes[]", path)
+    content_hash = data.get("content_sha256")
     return PathSnapshot(
         _string(data.get("status"), "status", path),
-        _string(data.get("content_sha256"), "content_sha256", path),
+        content_hash if isinstance(content_hash, str) else "",
     )
 
 
@@ -348,13 +351,76 @@ def load_active_task(root: str) -> ActiveTask:
         raise ContextError("invalid_active_marker", "active", str(exc), str(marker)) from exc
 
 
+def resync_active_hash(root: str, task_dir: str, current_sha256: str) -> bool:
+    """Re-sync the active marker's context hash after toolchain-initiated
+    context edits (bind/decision/refresh) so they never surface as
+    unrecoverable active_context_drift. No-op without an active marker or when
+    the hash already matches; never raises on a missing marker."""
+    marker = Path(root) / ".code-flow" / ".active-task.json"
+    if not marker.exists():
+        return False
+    active = load_active_task(root)
+    if active.context_sha256 == current_sha256:
+        return False
+    save_active_task(root, replace(active, context_sha256=current_sha256))
+    return True
+
+
+def _find_root(task_dir: str) -> Optional[str]:
+    """Walk up from a task dir to the project root that owns its marker."""
+    current = Path(task_dir).resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / ".code-flow" / ".active-task.json").exists():
+            return str(candidate)
+    return None
+
+
+def _resync_after_save(args: argparse.Namespace, context_path: Path) -> bool:
+    """Post-save marker re-sync used by CLI commands that persist the context."""
+    root = getattr(args, "root", "") or _find_root(str(context_path.parent)) or ""
+    if not root:
+        return False
+    current = context_sha256(load_context(str(context_path)))
+    return resync_active_hash(root, str(context_path.parent), current)
+
+
+def _lock_stale(lock: Path) -> bool:
+    """A lock is stale when its file is unreadable, carries no valid PID, or the
+    owning process is gone. A lock we cannot prove dead is never deleted (PID
+    reuse is accepted as a rare race)."""
+    try:
+        data = json.loads(lock.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return True
+    pid = data.get("pid")
+    if not isinstance(pid, int) or pid <= 0:
+        return True
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return True
+    except (PermissionError, OSError):
+        return False
+    return False
+
+
 def _acquire_active_lock(root: str) -> Path:
     marker, lock = _active_paths(root)
     lock.parent.mkdir(parents=True, exist_ok=True)
-    try:
-        descriptor = os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
-    except FileExistsError as exc:
-        raise ContextError("active_lock_exists", "active.lock", "运行 doctor 检查残留 lock", str(lock)) from exc
+    descriptor = -1
+    for _attempt in range(2):
+        try:
+            descriptor = os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            break
+        except FileExistsError:
+            if not _lock_stale(lock):
+                raise ContextError("active_lock_exists", "active.lock", "运行 doctor 检查残留 lock", str(lock)) from None
+            try:
+                lock.unlink()
+            except OSError as exc:
+                raise ContextError("active_lock_exists", "active.lock", f"残留 lock 清理失败: {exc}", str(lock)) from exc
+    else:
+        raise ContextError("active_lock_exists", "active.lock", "残留 lock 无法清理", str(lock))
     with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
         handle.write(json.dumps({"pid": os.getpid(), "marker": str(marker)}))
     return lock
@@ -390,8 +456,11 @@ def _new_active(
         raise ContextError("unknown_owned_path", "owned_paths", ", ".join(unknown), root)
     if unowned:
         raise ContextError("unowned_changes", "owned_paths", ", ".join(unowned), root)
+    # content_sha256 was a per-file hash but is never consumed by any gate (only
+    # baseline.head is compared); keep the schema field empty so start never hashes
+    # every uncommitted file.
     snapshots = {
-        path: PathSnapshot(status, _path_hash(root, path)) for path, status in changes.items()
+        path: PathSnapshot(status, "") for path, status in changes.items()
     }
     baseline = ActiveBaseline(_git_head(root), _now(), snapshots)
     return ActiveTask(
@@ -427,8 +496,11 @@ def _transition_active(root: str, expected: Sequence[str], target: str) -> Activ
         active = load_active_task(root)
         if active.status not in expected:
             raise ContextError("invalid_active_transition", "status", f"{active.status} -> {target}", root)
-        if active.baseline.head != _git_head(root):
-            raise ContextError("baseline_head_changed", "baseline.head", "Git HEAD 已变化，请运行 doctor", root)
+        current_head = _git_head(root)
+        if active.baseline.head != current_head:
+            # Mid-task commits are a normal workflow; re-baseline instead of
+            # bricking pause/resume/complete on any unrelated commit.
+            active = replace(active, baseline=replace(active.baseline, head=current_head))
         updated = replace(active, status=target)
         save_active_task(root, updated)
         return updated
@@ -466,7 +538,9 @@ def complete_active_task(root: str, gate_passed: bool) -> ActiveTask:
     return completed
 
 
-def doctor_active_task(root: str, expected_context_sha256: str, abandon: bool = False) -> DoctorResult:
+def doctor_active_task(
+    root: str, expected_context_sha256: str, abandon: bool = False, resync: bool = False
+) -> DoctorResult:
     marker, lock = _active_paths(root)
     try:
         active = load_active_task(root)
@@ -476,6 +550,15 @@ def doctor_active_task(root: str, expected_context_sha256: str, abandon: bool =
         marker.unlink()
         _release_active_lock(lock)
         return DoctorResult("abandoned", replace(active, status="completed"))
+    if resync:
+        # Self-heal: the context file is authoritative and the marker hash is a
+        # cache. Accept the current context when the marker is the only
+        # inconsistency; bind/decision/refresh already re-sync automatically,
+        # so this covers legacy markers and manual context edits.
+        repaired = replace(active, status="active", context_sha256=expected_context_sha256)
+        save_active_task(root, repaired)
+        _release_active_lock(lock)
+        return DoctorResult("resynced", repaired)
     proven = active.context_sha256 == expected_context_sha256
     proven = proven and active.baseline.head == _git_head(root)
     if active.status != "activating" or not proven:
@@ -690,6 +773,59 @@ def context_to_data(context: SpecContext) -> dict[str, object]:
     }
 
 
+def context_to_identity(context: SpecContext) -> dict[str, object]:
+    """Stable identity projection for marker drift detection.
+
+    Excludes volatile runtime state (`updated_at`, `stage_status` including
+    evidence timestamps) so the active marker only invalidates when the bound
+    rules themselves change (rule/spec text, bindings, sources).
+    """
+    return {
+        "version": context.version,
+        "task": context.task,
+        "enforcement": context.enforcement,
+        "sources": [{"type": item.type, "ref": item.ref} for item in context.sources],
+        "bindings": [
+            {
+                "spec_id": binding.spec_id,
+                "path": binding.path,
+                "status": binding.status,
+                "hashes": {
+                    "file_sha256": binding.hashes.file_sha256,
+                    "metadata_sha256": binding.hashes.metadata_sha256,
+                    "rules_sha256": binding.hashes.rules_sha256,
+                },
+                "selected_by": binding.selected_by,
+                "reason": binding.reason,
+                "enforcement": binding.enforcement,
+                "stages": list(binding.stages),
+                "rules": [
+                    {
+                        "ref": rule.ref,
+                        "summary": rule.summary,
+                        "text_sha256": rule.text_sha256,
+                        "enforcement": rule.enforcement,
+                        "verifier_ref": rule.verifier_ref,
+                    }
+                    for rule in binding.rules
+                ],
+            }
+            for binding in context.bindings
+        ],
+    }
+
+
+def context_sha256(context: SpecContext) -> str:
+    """Deterministic identity hash binding the active marker to the bound rules.
+
+    Computed from the stable identity projection (never volatile runtime state),
+    so evidence timestamps and stage statuses cannot drift the marker.
+    """
+    import yaml
+    data = yaml.safe_dump(context_to_identity(context), sort_keys=True, allow_unicode=True).encode()
+    return hashlib.sha256(data).hexdigest()
+
+
 def new_context(task: str, sources: Sequence[tuple[str, str]]) -> SpecContext:
     if not task.strip():
         raise ContextError("invalid_context", "task", "必须是非空字符串")
@@ -698,6 +834,7 @@ def new_context(task: str, sources: Sequence[tuple[str, str]]) -> SpecContext:
 
 
 def load_context(path: str) -> SpecContext:
+    import yaml
     try:
         loaded = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
     except (OSError, UnicodeError, yaml.YAMLError) as exc:
@@ -726,6 +863,7 @@ def load_context(path: str) -> SpecContext:
 
 
 def save_context(path: str, context: SpecContext) -> None:
+    import yaml
     target = Path(path)
     target.parent.mkdir(parents=True, exist_ok=True)
     text = yaml.safe_dump(context_to_data(context), sort_keys=False, allow_unicode=True)
@@ -792,6 +930,8 @@ def bind_specs(context: SpecContext, selections: Sequence[BindingInput]) -> Spec
             )
         bindings[incoming.spec_id] = incoming
     ordered = tuple(bindings[key] for key in sorted(bindings))
+    if ordered == context.bindings:
+        return context
     return replace(context, updated_at=_now(), bindings=ordered)
 
 
@@ -827,7 +967,57 @@ def _removed_rule(rule: RuleBinding) -> RuleBinding:
 
 def _file_sha256(path: Path) -> str:
     try:
-        return hashlib.sha256(path.read_bytes()).hexdigest()
+        stat = path.stat()
+        key = str(path)
+        cached = _FILE_HASH_CACHE.get(key)
+        signature = (stat.st_mtime_ns, stat.st_size, stat.st_ino)
+        if cached is not None and cached[:3] == signature:
+            return cached[3]
+        cache_path = next(
+            (parent / ".artifact-hash-cache.json" for parent in path.parents if parent.name == ".code-flow"),
+            None,
+        )
+        cache_key = str(cache_path) if cache_path is not None else ""
+        if cache_key and cache_key not in _PERSISTENT_HASH_PATHS:
+            try:
+                loaded = json.loads(cache_path.read_text(encoding="utf-8"))
+                if isinstance(loaded, dict):
+                    _PERSISTENT_HASH_CACHE.update({str(k): v for k, v in loaded.items() if isinstance(v, dict)})
+            except (OSError, ValueError):
+                pass
+            _PERSISTENT_HASH_PATHS.add(cache_key)
+        persistent = _PERSISTENT_HASH_CACHE.get(key)
+        if (
+            isinstance(persistent, dict)
+            and persistent.get("mtime_ns") == stat.st_mtime_ns
+            and persistent.get("size") == stat.st_size
+            and persistent.get("ino") == stat.st_ino
+        ):
+            digest = persistent.get("sha256")
+            if isinstance(digest, str) and digest:
+                _FILE_HASH_CACHE[key] = (signature[0], signature[1], signature[2], digest)
+                return digest
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        _FILE_HASH_CACHE[key] = (signature[0], signature[1], signature[2], digest)
+        if cache_key:
+            _PERSISTENT_HASH_CACHE[key] = {
+                "mtime_ns": stat.st_mtime_ns,
+                "size": stat.st_size,
+                "ino": stat.st_ino,
+                "sha256": digest,
+            }
+            while len(_PERSISTENT_HASH_CACHE) > _MAX_HASH_CACHE_ENTRIES:
+                _PERSISTENT_HASH_CACHE.pop(next(iter(_PERSISTENT_HASH_CACHE)))
+            try:
+                temporary = cache_path.with_suffix(".json.tmp")
+                temporary.write_text(
+                    json.dumps(_PERSISTENT_HASH_CACHE, ensure_ascii=False, sort_keys=True),
+                    encoding="utf-8",
+                )
+                temporary.replace(cache_path)
+            except OSError:
+                pass
+        return digest
     except OSError as exc:
         raise ContextError("artifact_read_error", "artifact", str(exc), str(path)) from exc
 
@@ -843,7 +1033,16 @@ def _refresh_artifacts(
             current = _file_sha256(path) if path.is_file() else "missing"
             if current == reference.artifact_sha256:
                 continue
-            statuses[stage] = replace(status, status="stale")
+            if status.status == "applied" and current != "missing":
+                statuses[stage] = replace(
+                    status,
+                    refs=tuple(
+                        replace(item, artifact_sha256=current) if item is reference else item
+                        for item in status.refs
+                    ),
+                )
+            else:
+                statuses[stage] = replace(status, status="stale")
             changes.append(
                 DriftChange("artifact_changed", spec_id, rule.ref, reference.artifact_sha256, current, (stage,))
             )
@@ -910,15 +1109,21 @@ def _refresh_binding(
 
 
 def refresh_context(context: SpecContext, root: str, artifact_root: Optional[str] = None) -> DriftResult:
+    started = time.monotonic()
     specs = Path(root) / ".code-flow" / "specs"
     artifacts = Path(artifact_root) if artifact_root is not None else Path(root)
     bindings: list[SpecBinding] = []
     changes: list[DriftChange] = []
     for binding in context.bindings:
+        phase_started = time.monotonic()
         updated, binding_changes = _refresh_binding(binding, specs, artifacts)
+        phase_timing(f"context.refresh.{binding.spec_id}", phase_started)
         bindings.append(updated)
         changes.extend(binding_changes)
     refreshed = replace(context, updated_at=_now(), bindings=tuple(bindings))
+    phase_timing("context.refresh.total", started)
+    if refreshed.bindings == context.bindings:
+        return DriftResult(context, tuple(changes))
     return DriftResult(refreshed, tuple(changes))
 
 
@@ -993,7 +1198,10 @@ def apply_artifact_ref(
                 statuses = dict(rule.stage_status)
                 current = statuses[stage]
                 refs = _upsert_artifact_ref(current.refs, reference)
-                statuses[stage] = replace(current, status="applied", refs=refs)
+                if current.decision is not None:
+                    statuses[stage] = replace(current, refs=refs)
+                else:
+                    statuses[stage] = replace(current, status="applied", refs=refs)
                 rule = replace(rule, stage_status=statuses)
                 found = True
             rules.append(rule)
@@ -1089,6 +1297,7 @@ def _decision_command(args: argparse.Namespace, payload: Mapping[str, object]) -
         payload.get("batch") is True,
     )
     save_context(str(context_path), context)
+    _resync_after_save(args, context_path)
     return {"ok": True, "status": context.bindings[0].rules[0].stage_status[_string(payload.get("stage"), "stage", "")].status}
 
 
@@ -1117,6 +1326,7 @@ def _bind_command(args: argparse.Namespace, payload: Mapping[str, object]) -> di
     context = bind_specs(context, selections)
     context = _apply_payload(context, args.task_dir, payload)
     save_context(str(context_path), context)
+    _resync_after_save(args, context_path)
     applied = sum(
         status.status == "applied"
         for binding in context.bindings
@@ -1146,12 +1356,132 @@ def _active_command(args: argparse.Namespace, payload: Mapping[str, object]) ->
         active = complete_active_task(args.root, payload.get("gate_passed") is True)
     else:
         result = doctor_active_task(
-            args.root, args.context_sha256, payload.get("abandon") is True
+            args.root,
+            args.context_sha256,
+            payload.get("abandon") is True,
+            payload.get("resync") is True,
         )
         return {"ok": True, "action": result.action, "active": _active_data(result.active)}
     return {"ok": True, "active": _active_data(active)}
 
 
+def _start_command(args: argparse.Namespace, payload: Mapping[str, object]) -> dict[str, object]:
+    """Run refresh, activation and TASK projection in one guarded process."""
+    context_path = Path(args.task_dir) / "spec-context.yml"
+    refreshed = refresh_context(load_context(str(context_path)), args.root, artifact_root=args.task_dir)
+    save_context(str(context_path), refreshed.context)
+    _resync_after_save(args, context_path)
+    current_hash = context_sha256(refreshed.context)
+    owned = tuple(
+        _string(item, "owned_paths[]", "")
+        for item in _sequence(payload.get("owned_paths", []), "owned_paths", "")
+    )
+    task_file = Path(args.task_file).resolve()
+    task_dir = Path(args.task_dir).resolve()
+    if task_file.parent != task_dir or not task_file.is_file():
+        raise ContextError("invalid_task_file", "task_file", str(task_file), args.task_dir)
+    manifest_file = task_dir / ".acceptance-manifest.json"
+    if "## Acceptance Coverage" in task_file.read_text(encoding="utf-8") and not manifest_file.is_file():
+        raise ContextError(
+            "acceptance_manifest_missing",
+            "acceptance_manifest",
+            "run plan verification and lock the manifest",
+            str(manifest_file),
+        )
+    if manifest_file.is_file():
+        from cf_acceptance_manifest import validate_manifest
+
+        valid, reason = validate_manifest(str(task_file), str(manifest_file))
+        if not valid:
+            raise ContextError(reason, "acceptance_manifest", "run plan verification before coding", str(manifest_file))
+    from cf_spec_session import project_task_session
+
+    projection = project_task_session(refreshed.context, str(task_file), args.task)
+    if projection.truncated:
+        raise ContextError("task_projection_truncated", "task_file", "split the TASK before coding")
+    output = Path(args.session_output) if args.session_output else (
+        Path(args.root) / ".code-flow/specs/_session" / f"task-{task_file.stem}.md"
+    )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_text(output, projection.text)
+    active = start_active_task(args.root, args.task_dir, args.task, current_hash, owned)
+    return {
+        "ok": True,
+        "context_sha256": current_hash,
+        "refresh_changes": [item.__dict__ for item in refreshed.changes],
+        "active": _active_data(active),
+        "session_output": str(output),
+        "acceptance_manifest": str(manifest_file) if manifest_file.is_file() else None,
+    }
+
+
+def _status_command(args: argparse.Namespace) -> dict[str, object]:
+    """Human-readable Spec Context status: task, marker health, gate, rules."""
+    from cf_spec_gate import result_to_data, validate_stage  # local import avoids module cycle
+
+    context_path = Path(args.task_dir) / "spec-context.yml"
+    context = load_context(str(context_path))
+    gate = validate_stage(context, "code")
+    root = getattr(args, "root", "") or _find_root(args.task_dir) or ""
+    marker: dict[str, object] = {"exists": False}
+    if root:
+        marker_path = Path(root) / ".code-flow" / ".active-task.json"
+        if marker_path.exists():
+            active = load_active_task(root)
+            marker = {
+                "exists": True,
+                "task_id": active.task_id,
+                "status": active.status,
+                "hash_match": active.context_sha256 == context_sha256(context),
+                "baseline_head": active.baseline.head,
+            }
+    bindings = []
+    for binding in context.bindings:
+        rules = []
+        for rule in binding.rules:
+            status = rule.stage_status.get("code")
+            rules.append(
+                {
+                    "ref": f"{binding.spec_id}#{rule.ref}",
+                    "enforcement": rule.enforcement,
+                    "status": status.status if status else "missing",
+                    "verifier": rule.verifier_ref,
+                }
+            )
+        bindings.append({"spec_id": binding.spec_id, "path": binding.path, "status": binding.status, "rules": rules})
+    return {
+        "task": context.task,
+        "context_sha256": context_sha256(context),
+        "gate": result_to_data(gate),
+        "marker": marker,
+        "bindings": bindings,
+    }
+
+
+def _status_text(data: dict[str, object]) -> str:
+    lines = [f"# {data['task']} — Spec Context 状态"]
+    marker = data["marker"]
+    if marker["exists"]:
+        match = "✓ 一致" if marker["hash_match"] else "✗ 漂移"
+        lines.append(f"- TASK {marker['task_id']}（{marker['status']}），marker hash {match}")
+        if not marker["hash_match"]:
+            lines.append("  下一步: 运行 cf-spec doctor（resync 可自动重同步）")
+    else:
+        lines.append("- 无 active TASK（path/catalog 路由模式）")
+    gate = data["gate"]
+    if gate["decision"] == "pass":
+        lines.append("- code Gate: ✓ pass")
+    else:
+        lines.append(f"- code Gate: ✗ block（{len(gate['errors'])} 项）")
+        for issue in gate["errors"]:
+            lines.append(f"  ✗ {issue['message']}")
+    for binding in data["bindings"]:
+        lines.append(f"- {binding['spec_id']}（{binding['path']}）— {binding['status']}")
+        for rule in binding["rules"]:
+            lines.append(f"  {rule['status']:<12} {rule['ref']}（{rule['verifier']}）")
+    return "\n".join(lines)
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="cf_spec_context.py")
     commands = parser.add_subparsers(dest="command", required=True)
@@ -1171,6 +1501,10 @@ def _parser() -> argparse.ArgumentParser:
     validate = commands.add_parser("validate")
     validate.add_argument("--task-dir", required=True)
     validate.add_argument("--json", action="store_true")
+    status = commands.add_parser("status")
+    status.add_argument("--task-dir", required=True)
+    status.add_argument("--root", default="")
+    status.add_argument("--json", action="store_true")
     for name in ("refresh", "refresh-missing"):
         refresh = commands.add_parser(name)
         refresh.add_argument("--task-dir", required=True)
@@ -1185,6 +1519,13 @@ def _parser() -> argparse.ArgumentParser:
         command.add_argument("--task", required=True)
         command.add_argument("--context-sha256", required=True)
         command.add_argument("--json", action="store_true")
+    start = commands.add_parser("start")
+    start.add_argument("--task-dir", required=True)
+    start.add_argument("--root", required=True)
+    start.add_argument("--task", required=True)
+    start.add_argument("--task-file", required=True)
+    start.add_argument("--session-output", default="")
+    start.add_argument("--json", action="store_true")
     return parser
 
 
@@ -1193,6 +1534,8 @@ def _execute(args: argparse.Namespace, stdin: IO[str]) -> dict[str, object]:
         return _catalog_command(args)
     if args.command == "active":
         return _active_command(args, _json_payload(stdin))
+    if args.command == "start":
+        return _start_command(args, _json_payload(stdin))
     context_path = Path(args.task_dir) / "spec-context.yml"
     if args.command == "decision":
         return _decision_command(args, _json_payload(stdin))
@@ -1208,6 +1551,7 @@ def _execute(args: argparse.Namespace, stdin: IO[str]) -> dict[str, object]:
         result = refresh_context(load_context(str(context_path)), args.root, artifact_root=args.task_dir)
         context, changes = result.context, result.changes
     save_context(str(context_path), context)
+    _resync_after_save(args, context_path)
     return {
         "ok": True,
         "missing": sum(item.status == "missing" for item in context.bindings),
@@ -1217,7 +1561,15 @@ def _execute(args: argparse.Namespace, stdin: IO[str]) -> dict[str, object]:
 
 def main(argv: Optional[Sequence[str]] = None, stdin: IO[str] = sys.stdin, stdout: IO[str] = sys.stdout) -> int:
     try:
-        result = _execute(_parser().parse_args(argv), stdin)
+        args = _parser().parse_args(argv)
+        if args.command == "status":
+            data = _status_command(args)
+            if args.json:
+                stdout.write(json.dumps(data, ensure_ascii=False))
+            else:
+                stdout.write(_status_text(data) + "\n")
+            return 0
+        result = _execute(args, stdin)
         stdout.write(json.dumps(result, ensure_ascii=False))
         return 0
     except ContextError as exc: