roar-cli 0.2.7__tar.gz → 0.2.9__tar.gz

{roar_cli-0.2.7 → roar_cli-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roar-cli
-Version: 0.2.7
+Version: 0.2.9
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research

{roar_cli-0.2.7 → roar_cli-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "roar-cli"
-version = "0.2.7"
+version = "0.2.9"
 description = "Reproducibility and provenance tracker for ML training pipelines"
 authors = [
     { name="TReqs Team", email="info@treqs.ai" }
@@ -81,6 +81,7 @@ include = [
     { path = "LICENSE", format = "wheel" },
     { path = "roar/bin/*", format = "sdist" },
     { path = "roar/bin/*", format = "wheel" },
+    { path = "roar_inject.pth", format = "wheel" },
 ]
 
 [tool.pytest.ini_options]
@@ -97,6 +98,8 @@ markers = [
     "cloud: Tests for cloud storage operations",
     "happy_path: Happy path tests for core functionality",
     "ray_e2e: Ray end-to-end tests requiring a running Docker cluster",
+    "ray_contract: User-facing Ray contract tests using `roar run ray job submit ...`",
+    "ray_diagnostic: Diagnostic Ray tests that intentionally inspect internal runtime details",
 ]
 addopts = "-v --strict-markers -n auto --dist loadfile --ignore=tests/ebpf --ignore=tests/live_glaas --ignore=tests/benchmarks --ignore=tests/integration --ignore=tests/e2e"
 timeout = 60

{roar_cli-0.2.7 → roar_cli-0.2.9}/roar/cli/commands/_execution.py

@@ -10,6 +10,7 @@ Usage:
     from ._execution import validate_git_clean, get_quiet_setting, execute_and_report
 """
 
+import os
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -35,6 +36,8 @@ def validate_git_clean() -> str:
     """
     import subprocess
 
+    cwd = os.getcwd()
+
     # Find repo root (no bootstrap needed)
     try:
         repo_root = subprocess.check_output(
@@ -43,6 +46,10 @@ def validate_git_clean() -> str:
             text=True,
         ).strip()
     except (subprocess.CalledProcessError, FileNotFoundError):
+        # Ray jobs run from extracted working dirs that are not git repos.
+        # Allow execution there while preserving git checks everywhere else.
+        if "RAY_JOB_ID" in os.environ:
+            return cwd
         raise click.ClickException(
             "roar requires the working directory to be inside a git repository."
         ) from None
@@ -79,6 +86,10 @@ def get_quiet_setting(quiet_flag: bool | None, repo_root: str | Path) -> bool:
     The CLI flag takes precedence. If not provided, checks the config
     for `output.quiet` setting.
 
+    Fast path: reads TOML directly — avoids loading Pydantic/settings for
+    this single key.  Falls back to the full settings stack only if the
+    direct read fails.
+
     Args:
         quiet_flag: Explicit quiet flag from command line (None if not specified)
         repo_root: Repository root for config lookup
@@ -89,6 +100,26 @@ def get_quiet_setting(quiet_flag: bool | None, repo_root: str | Path) -> bool:
     if quiet_flag is not None:
         return quiet_flag
 
+    # Fast path: read config TOML directly without loading Pydantic.
+    # This is the hot path — called before the child process starts.
+    from pathlib import Path as _Path
+
+    try:
+        try:
+            import tomllib as _tomllib
+        except ImportError:
+            import tomli as _tomllib  # type: ignore[no-redef]
+
+        config_toml = _Path(repo_root) / ".roar" / "config.toml" if repo_root else None
+        if config_toml is not None and config_toml.exists():
+            data = _tomllib.loads(config_toml.read_text())
+            return bool(data.get("output", {}).get("quiet", False))
+        # No config file found — use default.
+        return False
+    except Exception:
+        pass
+
+    # Fallback: full settings stack (covers edge cases like custom config paths).
     from ...config import load_config
 
     config = load_config(start_dir=str(repo_root) if repo_root else None)

roar_cli-0.2.9/roar/cli/commands/_ray_job_submit.py

@@ -0,0 +1,298 @@
+"""Rewrites for `ray job(s) submit` launched through `roar run`."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from ...glaas_client import GlaasClient
+from ...ray.fragment_key import generate_fragment_key, save_key
+
+_ROAR_WORKER_PY_EXECUTABLE = "roar-worker"
+_ROAR_WORKER_SETUP_HOOK = "roar.ray.roar_worker._startup"
+_ROAR_DRIVER_ENTRYPOINT_MODULE = "roar.ray.driver_entrypoint"
+_ROAR_JOB_INSTRUMENTED_ENV_VAR = "ROAR_JOB_INSTRUMENTED"
+_ROAR_CLUSTER_GLAAS_URL_ENV = "ROAR_CLUSTER_GLAAS_URL"
+_ROAR_CLUSTER_AWS_ENDPOINT_URL_ENV = "ROAR_CLUSTER_AWS_ENDPOINT_URL"
+
+
+@dataclass(frozen=True)
+class RayJobSubmitRewrite:
+    command: list[str]
+    session_id: str | None = None
+
+
+def maybe_rewrite_ray_job_submit(command: list[str]) -> RayJobSubmitRewrite:
+    """Rewrite ray jobs submit commands for roar instrumentation."""
+    if not _is_ray_job_submit(command):
+        return RayJobSubmitRewrite(command=command)
+
+    if "--" not in command:
+        return RayJobSubmitRewrite(command=command)
+
+    separator_index = command.index("--")
+    before_separator = list(command[:separator_index])
+    entrypoint = list(command[separator_index + 1 :])
+    if not entrypoint:
+        return RayJobSubmitRewrite(command=command)
+    entrypoint = _wrap_entrypoint_for_driver_proxy(entrypoint)
+
+    runtime_env_json_arg = _find_runtime_env_json(before_separator)
+    runtime_env = _load_runtime_env(before_separator, runtime_env_json_arg)
+    if runtime_env is None:
+        # Invalid user-provided JSON - leave command untouched.
+        return RayJobSubmitRewrite(command=command)
+
+    merged_pip = _merge_roar_runtime_env_pip(runtime_env.get("pip"))
+    if merged_pip:
+        runtime_env["pip"] = merged_pip
+    else:
+        runtime_env.pop("pip", None)
+
+    # py_executable is intentionally NOT set at job level — it would apply to the
+    # JobSupervisor/driver process which doesn't have roar installed yet (pip runs after
+    # the supervisor starts). worker_process_setup_hook is sufficient: it runs inside
+    # each worker process after the runtime env (and pip) is ready.
+    runtime_env["worker_process_setup_hook"] = _ROAR_WORKER_SETUP_HOOK
+
+    env_vars = dict(runtime_env.get("env_vars", {}) or {})
+    env_vars[_ROAR_JOB_INSTRUMENTED_ENV_VAR] = "1"
+    env_vars["ROAR_WRAP"] = "1"
+    env_vars["ROAR_RAY_NODE_AGENTS"] = "1"
+    # Stable job_id shared by driver + workers for node agent name resolution.
+    import uuid as _uuid
+
+    env_vars["ROAR_JOB_ID"] = _uuid.uuid4().hex[:8]
+
+    # Tell the job driver where roar.db lives (CWD inside the Ray job is the
+    # extracted working_dir, not the original project directory).
+    roar_dir = os.environ.get("ROAR_PROJECT_DIR", "")
+    if not roar_dir:
+        # Use CWD — `roar run` is invoked from the project root.
+        roar_dir = os.getcwd()
+    if roar_dir and os.path.isfile(os.path.join(roar_dir, ".roar", "roar.db")):
+        env_vars["ROAR_PROJECT_DIR"] = roar_dir
+
+    # Route S3 traffic through the per-node proxy (port 19191) for I/O capture.
+    # Save the REAL upstream endpoint (not the roar-run local proxy) so the
+    # cluster-side proxy can forward to the actual S3 service.
+    original_endpoint = (
+        os.environ.get("ROAR_UPSTREAM_S3_ENDPOINT") or os.environ.get("AWS_ENDPOINT_URL") or ""
+    )
+    cluster_upstream_endpoint = _resolve_cluster_upstream_s3_endpoint(original_endpoint)
+    if cluster_upstream_endpoint:
+        env_vars["ROAR_UPSTREAM_S3_ENDPOINT"] = cluster_upstream_endpoint
+    env_vars["ROAR_PROXY_PORT"] = "19191"
+    env_vars["AWS_ENDPOINT_URL"] = "http://127.0.0.1:19191"
+
+    fragment_session_id: str | None = None
+
+    glaas_url = _resolve_glaas_url()
+    if glaas_url:
+        cluster_glaas_url = _resolve_cluster_glaas_url(glaas_url)
+        if cluster_glaas_url:
+            env_vars["GLAAS_URL"] = cluster_glaas_url
+
+        key = generate_fragment_key()
+        try:
+            _register_fragment_session(glaas_url, key["session_id"], key["token_hash"])
+        except Exception:
+            # Keep existing behavior when fragment preregistration is unavailable.
+            pass
+        else:
+            save_key(Path(os.getcwd()) / ".roar", key)
+            env_vars["ROAR_SESSION_ID"] = key["session_id"]
+            env_vars["ROAR_FRAGMENT_TOKEN"] = key["token"]
+            fragment_session_id = str(key["session_id"])
+
+    if env_vars:
+        runtime_env["env_vars"] = env_vars
+    else:
+        runtime_env.pop("env_vars", None)
+
+    before_separator = _store_runtime_env(before_separator, runtime_env, runtime_env_json_arg)
+    return RayJobSubmitRewrite(
+        command=[*before_separator, "--", *entrypoint],
+        session_id=fragment_session_id,
+    )
+
+
+def _is_ray_job_submit(command: list[str]) -> bool:
+    if len(command) < 3:
+        return False
+
+    binary = Path(command[0]).name.lower()
+    noun = command[1].lower()
+    verb = command[2].lower()
+    return binary == "ray" and noun in {"job", "jobs"} and verb == "submit"
+
+
+def _wrap_entrypoint_for_driver_proxy(entrypoint: list[str]) -> list[str]:
+    if (
+        len(entrypoint) >= 3
+        and entrypoint[1] == "-m"
+        and entrypoint[2] == _ROAR_DRIVER_ENTRYPOINT_MODULE
+    ):
+        return entrypoint
+
+    return ["python", "-m", _ROAR_DRIVER_ENTRYPOINT_MODULE, "--", *entrypoint]
+
+
+def _find_runtime_env_json(command: list[str]) -> tuple[int, int | None] | None:
+    for index, arg in enumerate(command):
+        if arg == "--runtime-env-json":
+            if index + 1 < len(command):
+                return index, index + 1
+            return index, None
+        if arg.startswith("--runtime-env-json="):
+            return index, None
+    return None
+
+
+def _load_runtime_env(
+    command_before_separator: list[str], runtime_env_json_arg: tuple[int, int | None] | None
+) -> dict | None:
+    if runtime_env_json_arg is None:
+        return {}
+
+    flag_index, value_index = runtime_env_json_arg
+    if value_index is not None:
+        payload = command_before_separator[value_index]
+    else:
+        payload = command_before_separator[flag_index].split("=", 1)[1]
+
+    try:
+        parsed = json.loads(payload)
+    except json.JSONDecodeError:
+        return None
+
+    if isinstance(parsed, dict):
+        return parsed
+    return {}
+
+
+def _store_runtime_env(
+    command_before_separator: list[str],
+    runtime_env: dict,
+    runtime_env_json_arg: tuple[int, int | None] | None,
+) -> list[str]:
+    serialized = json.dumps(runtime_env, separators=(",", ":"))
+    command_out = list(command_before_separator)
+
+    if runtime_env_json_arg is None:
+        command_out.extend(["--runtime-env-json", serialized])
+        return command_out
+
+    flag_index, value_index = runtime_env_json_arg
+    if value_index is not None:
+        command_out[value_index] = serialized
+    else:
+        command_out[flag_index] = f"--runtime-env-json={serialized}"
+    return command_out
+
+
+def _merge_roar_runtime_env_pip(existing_pip: object) -> list[str] | None:
+    roar_req = _resolve_roar_requirement()
+    dependencies = _coerce_runtime_env_pip(existing_pip)
+    dependencies = [
+        dependency
+        for dependency in dependencies
+        if _requirement_name(dependency) not in {"roar-cli", "roar"}
+        # Also deduplicate URL-based requirements (e.g. presigned S3 URLs).
+        # _requirement_name() returns the full URL for these, so the name-based
+        # filter above never matches them — without this check the URL would
+        # survive the filter and get appended again, producing duplicates.
+        and dependency.strip() != roar_req.strip()
+    ]
+    # "skip" means roar is already installed on workers (e.g. Docker image with editable install).
+    if roar_req != "skip":
+        dependencies.append(roar_req)
+    return dependencies if dependencies else None
+
+
+def _coerce_runtime_env_pip(value: object) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, (list, tuple, set)):
+        return [str(item) for item in value if item]
+    return []
+
+
+def _requirement_name(requirement: str) -> str:
+    text = requirement.strip()
+    if not text:
+        return ""
+
+    for delimiter in ("@", "==", ">=", "<=", "~=", "!=", ">", "<", ";", "["):
+        position = text.find(delimiter)
+        if position > 0:
+            text = text[:position]
+            break
+    return text.strip().lower()
+
+
+def _resolve_roar_requirement() -> str:
+    import importlib.metadata as importlib_metadata
+
+    # Allow overriding the pip requirement — useful for testing unreleased wheels via S3 URL
+    # without a PyPI publish. Set ROAR_CLUSTER_PIP_REQ=https://... in the environment.
+    override = os.environ.get("ROAR_CLUSTER_PIP_REQ", "").strip()
+    if override:
+        return override
+
+    try:
+        version = importlib_metadata.version("roar-cli")
+        return f"roar-cli=={version}"
+    except importlib_metadata.PackageNotFoundError:
+        pass
+    except Exception:
+        pass
+
+    return "roar-cli"
+
+
+def _resolve_glaas_url() -> str | None:
+    from ...glaas_client import get_glaas_url
+
+    url = get_glaas_url()
+    if not url:
+        return "https://api.glaas.ai"
+    return str(url)
+
+
+def _resolve_cluster_glaas_url(host_glaas_url: str | None) -> str | None:
+    override = os.environ.get(_ROAR_CLUSTER_GLAAS_URL_ENV, "").strip()
+    if override:
+        return override
+    if not host_glaas_url:
+        return None
+    return str(host_glaas_url)
+
+
+def _resolve_cluster_upstream_s3_endpoint(host_endpoint: str | None) -> str | None:
+    override = os.environ.get(_ROAR_CLUSTER_AWS_ENDPOINT_URL_ENV, "").strip()
+    if override:
+        return override
+    if not host_endpoint:
+        return None
+    return str(host_endpoint)
+
+
+def _register_fragment_session(
+    glaas_url: str,
+    session_id: str,
+    token_hash: str,
+    ttl: int = 86400,
+) -> None:
+    client = GlaasClient(base_url=glaas_url)
+    _result, error = client.register_fragment_session(
+        session_id=session_id,
+        token_hash=token_hash,
+        ttl_seconds=ttl,
+    )
+    if error:
+        raise RuntimeError(f"failed to pre-register fragment session {session_id}: {error}")

{roar_cli-0.2.7 → roar_cli-0.2.9}/roar/cli/commands/init.py

@@ -119,8 +119,6 @@ fallback_enabled = true
 enabled = true
 # Inject roar-cli into runtime_env.pip for remote workers
 pip_install = true
-# Shared log directory for Ray worker I/O capture
-log_dir = "/shared/.roar-logs"
 # Actor attribution mode for Ray actor methods (per_call | per_actor)
 actor_attribution = "per_call"
 
@@ -156,6 +154,33 @@ def _add_to_gitignore(gitignore_path: Path, gitignore_content: str) -> None:
         f.write(".roar/\n")
 
 
+def init_project(cwd: Path) -> Path:
+    """Create the minimal local roar project structure in ``cwd``."""
+    roar_dir = cwd / ".roar"
+    if roar_dir.exists():
+        return roar_dir
+
+    roar_dir.mkdir()
+
+    db_path = roar_dir / "roar.db"
+    engine = create_roar_engine(db_path)
+    init_database(engine)
+    engine.dispose()
+
+    raw_conn = _sqlite3.connect(str(db_path))
+    raw_conn.row_factory = _sqlite3.Row
+    try:
+        run_migrations(raw_conn)
+        raw_conn.commit()
+    finally:
+        raw_conn.close()
+
+    config_path = roar_dir / "config.toml"
+    config_path.write_text(DEFAULT_CONFIG_TEMPLATE)
+
+    return roar_dir
+
+
 @click.command("init")
 @click.option(
     "--yes",
@@ -204,23 +229,10 @@ def init(ctx: RoarContext, yes: bool, no: bool, init_path: Path | None) -> None:
         click.echo(f".roar directory already exists at {roar_dir}")
         return
 
-    # Create .roar directory
-    roar_dir.mkdir()
-    click.echo(f"Created {roar_dir}")
+    init_project(cwd)
 
-    # Initialize the SQLite database and schema
-    db_path = roar_dir / "roar.db"
-    engine = create_roar_engine(db_path)
-    init_database(engine)
-    engine.dispose()
-    raw_conn = _sqlite3.connect(str(db_path))
-    raw_conn.row_factory = _sqlite3.Row
-    try:
-        run_migrations(raw_conn)
-        raw_conn.commit()
-    finally:
-        raw_conn.close()
-    click.echo(f"Initialized database at {db_path}")
+    click.echo(f"Created {roar_dir}")
+    click.echo(f"Initialized database at {roar_dir / 'roar.db'}")
 
     # Add privacy/data collection notice
     click.echo("")
@@ -228,10 +240,7 @@ def init(ctx: RoarContext, yes: bool, no: bool, init_path: Path | None) -> None:
     click.echo("It does not upload file contents to GLaaS.")
     click.echo("")
 
-    # Create default config.toml
-    config_path = roar_dir / "config.toml"
-    config_path.write_text(DEFAULT_CONFIG_TEMPLATE)
-    click.echo(f"Created {config_path}")
+    click.echo(f"Created {roar_dir / 'config.toml'}")
 
     # Check if we're in a git repo
     if ctx.repo_root is None:

{roar_cli-0.2.7 → roar_cli-0.2.9}/roar/cli/commands/register.py

@@ -1,9 +1,9 @@
 """
 Native Click implementation of the register command.
 
-Usage: roar register [options] <artifact_path>
+Usage: roar register [options] <target>
 
-Registers an artifact and its complete lineage with GLaaS.
+Registers artifact, step, or session lineage with GLaaS.
 """
 
 import click
@@ -25,7 +25,7 @@ def _confirm_secrets(detected_secrets: list[str]) -> bool:
 
 
 @click.command("register")
-@click.argument("artifact_path", type=click.STRING)
+@click.argument("target", type=click.STRING)
 @click.option(
     "--dry-run",
     is_flag=True,
@@ -44,15 +44,15 @@ def _confirm_secrets(detected_secrets: list[str]) -> bool:
 )
 @click.pass_obj
 @require_init
-def register(
-    ctx: RoarContext, artifact_path: str, dry_run: bool, yes: bool, as_blake3: bool
-) -> None:
-    """Register artifact lineage with GLaaS.
+def register(ctx: RoarContext, target: str, dry_run: bool, yes: bool, as_blake3: bool) -> None:
+    """Register lineage with GLaaS.
 
-    Submits the complete lineage of an artifact to the GLaaS server,
-    including all jobs and artifacts in the dependency chain.
+    Submits lineage to the GLaaS server, starting from one of:
+    - an artifact path
+    - a DAG step reference like ``@4``
+    - a local session hash/prefix previously shown by roar
 
-    The ARTIFACT_PATH must be a file that has been tracked by roar run.
+    Artifact paths must refer to files tracked by roar.
 
     If secrets are detected in the data (API keys, tokens, passwords, etc.),
     you will be prompted to confirm. Use --yes to skip the prompt and
@@ -67,6 +67,10 @@ def register(
 
         roar register -y model.pt           # Skip confirmation prompt
 
+        roar register @4                    # Register the lineage for DAG step 4
+
+        roar register 8d7a1f2c...           # Register a whole local session
+
         roar register --as-blake3 model.pt  # Upgrade S3 etag hashes
 
         roar register outputs/metrics.json  # Register from subdirectory
@@ -74,9 +78,9 @@ def register(
     # Create service
     service = RegisterService()
 
-    # Register the artifact lineage
-    result = service.register_artifact_lineage(
-        artifact_path=artifact_path,
+    # Register the requested lineage target
+    result = service.register_lineage_target(
+        target=target,
         roar_dir=ctx.roar_dir,
         cwd=ctx.cwd,
         dry_run=dry_run,
@@ -105,9 +109,10 @@ def register(
         click.echo("")
         click.echo("View on GLaaS:")
         click.echo(f"  Session:  {web_url}/dag/{result.session_hash}")
-        click.echo(f"  Artifact: {web_url}/artifact/{result.artifact_hash}")
+        if result.artifact_hash:
+            click.echo(f"  Artifact: {web_url}/artifact/{result.artifact_hash}")
     else:
-        click.echo(f"Registered lineage for: {artifact_path}")
+        click.echo(f"Registered lineage for: {target}")
         click.echo(f"  Session: {result.session_hash[:12]}...")
         click.echo(f"  Jobs: {result.jobs_registered}")
         click.echo(f"  Artifacts: {result.artifacts_registered}")
@@ -122,12 +127,13 @@ def register(
             for error in result.error.split("; "):
                 click.echo(f"  - {error}", err=True)
 
-        # Print reproduce command
-        click.echo("")
-        click.echo("To reproduce this artifact:")
-        click.echo(f"  roar reproduce {result.artifact_hash}")
+        if result.artifact_hash:
+            click.echo("")
+            click.echo("To reproduce this artifact:")
+            click.echo(f"  roar reproduce {result.artifact_hash}")
 
         click.echo("")
         click.echo("View on GLaaS:")
         click.echo(f"  Session:  {web_url}/dag/{result.session_hash}")
-        click.echo(f"  Artifact: {web_url}/artifact/{result.artifact_hash}")
+        if result.artifact_hash:
+            click.echo(f"  Artifact: {web_url}/artifact/{result.artifact_hash}")

{roar_cli-0.2.7 → roar_cli-0.2.9}/roar/cli/commands/run.py

@@ -6,10 +6,14 @@ Usage: roar run [options] <command>
 """
 
 import shlex
+from pathlib import Path
 
 import click
 
 from ...core.tracer_modes import TRACER_MODE_VALUES
+from ...glaas_client import get_glaas_url
+from ...ray.fragment_key import load_key
+from ...ray.fragment_reconstituter import FragmentReconstituter
 from ..context import RoarContext
 from ..decorators import require_init
 from ._execution import (
@@ -18,6 +22,7 @@ from ._execution import (
     get_quiet_setting,
     validate_git_clean,
 )
+from ._ray_job_submit import maybe_rewrite_ray_job_submit
 
 
 @click.command(
@@ -126,6 +131,18 @@ def run(
             raise click.ClickException("No command specified")
         job_type = None
 
+    if (
+        len(command) >= 3
+        and Path(command[0]).name.lower() == "ray"
+        and command[1].lower() in {"job", "jobs"}
+        and command[2].lower() == "submit"
+    ):
+        rewritten = maybe_rewrite_ray_job_submit(command)
+        command = rewritten.command
+        session_id = rewritten.session_id
+    else:
+        session_id = None
+
     # Execute and report
     exit_code = execute_and_report(
         ctx=ctx,
@@ -139,6 +156,9 @@ def run(
         tracer_fallback=tracer_fallback,
     )
 
+    if session_id:
+        _maybe_reconstitute_lineage(ctx, session_id)
+
     if exit_code != 0:
         raise SystemExit(exit_code)
 
@@ -214,3 +234,39 @@ Hash algorithms: blake3 (default), sha256, sha512, md5
 Examples:
   roar run python train.py
   roar run @2 --epochs=10    # Re-run step 2 with parameter override"""
+
+
+def _maybe_reconstitute_lineage(ctx: RoarContext, session_id: str) -> None:
+    glaas_url = get_glaas_url()
+    if not glaas_url:
+        return
+
+    try:
+        key_payload = load_key(ctx.roar_dir, session_id)
+        token = key_payload.get("token")
+        if not isinstance(token, str) or not token:
+            raise ValueError("missing token in key payload")
+    except Exception as exc:
+        click.echo(
+            f"[roar] warning: failed to load fragment key for session {session_id}: {exc}",
+            err=True,
+        )
+        return
+
+    try:
+        result = FragmentReconstituter(
+            session_id=session_id,
+            token=token,
+            glaas_url=str(glaas_url),
+            roar_db_path=ctx.roar_dir / "roar.db",
+        ).reconstitute()
+    except Exception as exc:
+        click.echo(
+            f"[roar] warning: lineage reconstitution failed for session {session_id}: {exc}",
+            err=True,
+        )
+        return
+
+    click.echo(
+        f"[roar] lineage reconstituted: {result.jobs_merged} jobs, {result.artifacts_merged} artifacts"
+    )