agent-apprenticeship 0.1.0 → 0.1.2

package/src/agent_apprenticeship_trace/cli.py

@@ -2,11 +2,16 @@ from __future__ import annotations
 import base64
 import hashlib
 import os
+import re
+import select
 import shlex
 import sys
 import subprocess
 import shutil, json
 import zipfile
+import urllib.error
+import urllib.parse
+import urllib.request
 from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path
@@ -32,6 +37,7 @@ from .config import (
     configured_model_provider_ready,
     apprentice_agent_readiness_status,
     mentor_model_provider_readiness,
+    mentor_mode_display,
     normalize_mentor_mode,
     normalize_ecosystem_auto_share,
     normalize_sensitive_info_masking,
@@ -61,9 +67,9 @@ from .learning import (
     update_pack_status,
     write_before_after_result,
 )
-from .public_run import apprentice_agent_readiness, continue_session, finish_session, run_prompt_task, run_root_for
-from .progress import format_progress_event, format_run_status, read_run_status, watch_progress
-from .recipes import MODEL_PROVIDER_RECIPES, REMOVED_V0_MODEL_PROVIDER_IDS, WORKER_AGENT_RECIPES
+from .public_run import RunInterrupted, apprentice_agent_readiness, continue_session, finish_session, run_prompt_task, run_root_for
+from .progress import append_progress_event, format_progress_event, format_run_status, read_run_status, watch_progress
+from .recipes import MODEL_PROVIDER_RECIPES, WORKER_AGENT_RECIPES
 app=typer.Typer(add_completion=False)
 configure_app=typer.Typer(add_completion=False, help='Configure Apprentice Agents and Mentor Model Providers.')
 ecosystem_app=typer.Typer(add_completion=False, help='Explore and contribute Agent Apprenticeship ecosystem bundles.')
@@ -76,6 +82,11 @@ app.add_typer(learn_app, name='learn')
 
 SLACK_LINK='https://join.slack.com/t/fsycommunity/shared_invite/zt-37417grrb-jFD6BQIYgC5wEMrW2bHssw'
 
+FIRST_RUN_BANNER = """╭────────────────────────────────────────────╮
+│        Agent Apprenticeship                │
+│  Real-world work -> reusable agent signals │
+╰────────────────────────────────────────────╯"""
+
 MODEL_KEY_CANDIDATES = {
     "openai": ["OPENAI_API_KEY"],
     "anthropic": ["ANTHROPIC_API_KEY"],
@@ -102,6 +113,11 @@ def _print_public_ecosystem_contribution_help(bundle: str | Path) -> None:
     typer.echo('Public ecosystem:')
     typer.echo(_ecosystem_repo_url())
 
+
+def _print_first_run_banner() -> None:
+    typer.echo(FIRST_RUN_BANNER)
+    typer.echo("")
+
 def _print_task_result(
     status: dict,
     *,
@@ -202,6 +218,24 @@ def _env_next_step(env_var: str | None) -> str:
     return f"Next: export {env}=... or add {env}=... to ~/.agent-apprenticeship/.env.local"
 
 
+def _stdin_allows_prompt() -> bool:
+    if sys.stdin.isatty():
+        return True
+    try:
+        ready, _, _ = select.select([sys.stdin], [], [], 0)
+        if not ready:
+            return False
+    except Exception:
+        pass
+    try:
+        pos = sys.stdin.tell()
+        char = sys.stdin.read(1)
+        sys.stdin.seek(pos)
+        return bool(char)
+    except Exception:
+        return False
+
+
 def _detect_apprentice_agents() -> list[dict]:
     detected = []
     for agent_id, commands in AGENT_COMMAND_CANDIDATES.items():
@@ -289,7 +323,7 @@ def _configure_detected_model_provider(row: dict) -> None:
     )
 
 
-def _first_run_setup(*, interactive: bool) -> None:
+def _first_run_setup(*, interactive: bool, defaults: bool=False) -> None:
     detected_agents = _detect_apprentice_agents()
     typer.echo("")
     if detected_agents:
@@ -298,7 +332,10 @@ def _first_run_setup(*, interactive: bool) -> None:
             typer.echo(f"{idx}. {row['display_name']} - command found ({row['command']})")
         custom_index = len(detected_agents) + 1
         typer.echo(f"{custom_index}. Custom - use a custom command template")
-        if interactive:
+        if defaults:
+            _configure_detected_apprentice_agent(detected_agents[0])
+            typer.echo(f"Configured Apprentice Agent: {detected_agents[0]['display_name']}")
+        elif interactive:
             choice = _choose_detected_index(custom_index, default=1)
             if choice and choice <= len(detected_agents):
                 _configure_detected_apprentice_agent(detected_agents[choice - 1])
@@ -318,7 +355,10 @@ def _first_run_setup(*, interactive: bool) -> None:
         typer.echo("Detected Mentor Model Provider keys:")
         for idx, row in enumerate(detected_providers, 1):
             typer.echo(f"{idx}. {row['display_name']} - {row['api_key_env_var']} visible")
-        if interactive:
+        if defaults:
+            _configure_detected_model_provider(detected_providers[0])
+            typer.echo(f"Configured Mentor Model Provider: {detected_providers[0]['display_name']}")
+        elif interactive:
             choice = _choose_detected_index(len(detected_providers), default=1)
             if choice:
                 _configure_detected_model_provider(detected_providers[choice - 1])
@@ -342,7 +382,7 @@ def _progress_callback(quiet: bool=False, verbose: bool=False, json_progress: bo
             typer.echo('')
             typer.echo(f'Run: {status.get("run_id")}')
             typer.echo(f'Apprentice Agent: {status.get("apprentice_agent") or status.get("worker_agent")}')
-            typer.echo(f'Mentor Mode: {status.get("mentor_mode")}')
+            typer.echo(f'Mentor Mode: {mentor_mode_display(status.get("mentor_mode"))}')
             typer.echo(f'Maximum Improvement Loops: {status.get("maximum_improvement_loops")}')
             typer.echo(f'Task workspace: {status.get("task_workspace_path")}')
             typer.echo(f'Artifacts: {status.get("artifacts_path")}')
@@ -568,6 +608,13 @@ def _ensure_evaluation_ready(settings, interactive: bool=True):
         return settings
     if not interactive:
         raise typer.BadParameter('model-assisted/hybrid Mentor Mode requires a ready Mentor Model Provider; use configure model or --mentor-mode expert-led')
+    if not _stdin_allows_prompt():
+        readiness = mentor_model_provider_readiness(settings)
+        reason = readiness.get("reason") or "Mentor Model Provider is not ready."
+        raise typer.BadParameter(
+            f"model-assisted/hybrid Mentor Mode requires a ready Mentor Model Provider. {reason} "
+            "Run `apprentice doctor --live`, `apprentice configure model`, or use `--mentor-mode expert-led`."
+        )
     typer.echo('Model-assisted Mentor Mode needs a ready Mentor Model Provider.')
     readiness=mentor_model_provider_readiness(settings)
     if readiness.get("provider"):
@@ -578,7 +625,14 @@ def _ensure_evaluation_ready(settings, interactive: bool=True):
     typer.echo('2. Run this session in expert-led mode')
     typer.echo('3. Cancel')
     typer.echo('')
-    choice=typer.prompt('Default', default='expert-led').strip().lower()
+    try:
+        choice=typer.prompt('Default', default='expert-led').strip().lower()
+    except typer.Abort:
+        reason = readiness.get("reason") or "Mentor Model Provider is not ready."
+        raise typer.BadParameter(
+            f"model-assisted/hybrid Mentor Mode requires a ready Mentor Model Provider. {reason} "
+            "Run `apprentice doctor --live`, `apprentice configure model`, or use `--mentor-mode expert-led`."
+        ) from None
     if choice in {'1','setup','set up','configure','configure mentor model provider','set up model provider now'}:
         configured=_configure_model_impl(None, None, None, test_connection=False)
         return configured
@@ -596,6 +650,14 @@ def _ensure_apprentice_agent_ready(settings, runner: str | None=None, interactiv
     reason = status.get("reason")
     if not interactive:
         raise typer.BadParameter(reason or 'Apprentice Agent is not ready.')
+    if not _stdin_allows_prompt():
+        if status.get("command_found"):
+            typer.echo("Apprentice Agent readiness is untested; command was found, continuing without an interactive prompt.")
+            return
+        raise typer.BadParameter(
+            f"Apprentice Agent is not ready. {reason or 'Command was not found.'} "
+            "Run `apprentice configure agent` or install/authenticate a selected Apprentice Agent CLI."
+        )
     if status.get("status") == "untested":
         typer.echo('Apprentice Agent Status: Untested')
         if reason:
@@ -607,7 +669,16 @@ def _ensure_apprentice_agent_ready(settings, runner: str | None=None, interactiv
         typer.echo('3. Configure Apprentice Agent')
         typer.echo('4. Cancel')
         typer.echo('')
-        choice=typer.prompt('Default', default='run anyway').strip().lower()
+        try:
+            choice=typer.prompt('Default', default='run anyway').strip().lower()
+        except typer.Abort:
+            if status.get("command_found"):
+                typer.echo("Apprentice Agent readiness is untested; command was found, continuing without an interactive prompt.")
+                return
+            raise typer.BadParameter(
+                f"Apprentice Agent is not ready. {reason or 'Command was not found.'} "
+                "Run `apprentice configure agent` or install/authenticate a selected Apprentice Agent CLI."
+            ) from None
         if choice in {'1','run check','check'}:
             if status.get("command_found"):
                 update_settings(apprentice_agent_readiness_status="ready", apprentice_agent_readiness_reason="Command availability check passed.")
@@ -629,7 +700,16 @@ def _ensure_apprentice_agent_ready(settings, runner: str | None=None, interactiv
     typer.echo('2. Continue anyway')
     typer.echo('3. Cancel')
     typer.echo('')
-    choice=typer.prompt('Default', default='cancel').strip().lower()
+    try:
+        choice=typer.prompt('Default', default='cancel').strip().lower()
+    except typer.Abort:
+        if status.get("command_found"):
+            typer.echo("Apprentice Agent is not ready; command was found, continuing without an interactive prompt.")
+            return
+        raise typer.BadParameter(
+            f"Apprentice Agent is not ready. {reason or 'Command was not found.'} "
+            "Run `apprentice configure agent` or install/authenticate a selected Apprentice Agent CLI."
+        ) from None
     if choice in {'1','configure','configure apprentice agent','configure agent'}:
         typer.echo('Run: agent-apprenticeship configure agent')
         raise typer.Exit(1)
@@ -641,10 +721,14 @@ def _ensure_apprentice_agent_ready(settings, runner: str | None=None, interactiv
 def init(
     overwrite: bool=typer.Option(False, help='Replace existing settings.json with defaults.'),
     setup: bool=typer.Option(False, '--setup', help='Detect installed Apprentice Agents and Mentor Model Provider keys.'),
+    defaults: bool=typer.Option(False, '--defaults', '--non-interactive', help='Initialize with deterministic defaults and never prompt.'),
 ):
+    _print_first_run_banner()
     path=init_settings(overwrite=overwrite)
     typer.echo(f'initialized Agent Apprenticeship settings at {path}')
-    if setup or sys.stdin.isatty():
+    if defaults:
+        _first_run_setup(interactive=False, defaults=True)
+    elif setup or sys.stdin.isatty():
         _first_run_setup(interactive=bool(setup or sys.stdin.isatty()))
 
 @app.command('settings')
@@ -688,7 +772,7 @@ def doctor(
     typer.echo(f'Apprentice Agent command: {agent.get("command") or "Not configured"}')
     typer.echo(f'Apprentice Agent command found: {_yes_no(bool(agent.get("command_found")))}')
     typer.echo(_status_line('Apprentice Agent readiness', agent.get('status'), agent.get('reason')))
-    typer.echo(f'Mentor Mode: {settings.mentor_mode}')
+    typer.echo(f'Mentor Mode: {mentor_mode_display(settings.mentor_mode)}')
     typer.echo(f'Mentor Model Provider: {provider.get("provider_display")}')
     typer.echo(f'Mentor model: {provider.get("model") or "Not configured"}')
     typer.echo(f'API key env var: {provider.get("api_key_env_var") or "Not configured"}')
@@ -917,11 +1001,6 @@ def _print_integration_groups(report: dict) -> None:
             typer.echo(f"- {item}")
     else:
         typer.echo("- none")
-    if REMOVED_V0_MODEL_PROVIDER_IDS:
-        typer.echo("")
-        typer.echo("Removed From V0")
-        for provider_id in REMOVED_V0_MODEL_PROVIDER_IDS:
-            typer.echo(f"- {provider_id}")
 
 
 @app.command('integrations')
@@ -990,8 +1069,6 @@ def _print_certification_groups(report: dict) -> None:
             typer.echo(f"  - {item}")
     else:
         typer.echo("  - none")
-    if REMOVED_V0_MODEL_PROVIDER_IDS:
-        typer.echo(f"- Removed from v0: {', '.join(REMOVED_V0_MODEL_PROVIDER_IDS)}")
 
 
 @app.command('certify-integrations')
@@ -1196,7 +1273,15 @@ def start(
         hybrid_auto_approve=hybrid_auto_approve,
         mentor_interactive_checkpoints=interactive_checkpoints,
     ):
-        run_root,bundle=run_prompt_task(instruction, assets=assets, settings=settings, runner=runner, progress_callback=_progress_callback(quiet, verbose, json_progress))
+        try:
+            run_root,bundle=run_prompt_task(instruction, assets=assets, settings=settings, runner=runner, progress_callback=_progress_callback(quiet, verbose, json_progress))
+        except RunInterrupted as exc:
+            if not quiet and not json_progress:
+                typer.echo("")
+                typer.echo("Run interrupted.")
+                typer.echo("Run directory:")
+                typer.echo(str(exc.run_root))
+            raise typer.Exit(130)
     status = read_run_status(run_root)
     if quiet:
         _print_task_result(status, include_contribution_help=False)
@@ -1254,15 +1339,23 @@ def run_prompt(
         hybrid_auto_approve=hybrid_auto_approve,
         mentor_interactive_checkpoints=interactive_checkpoints,
     ):
-        run_root,bundle=run_prompt_task(
-            effective_instruction,
-            assets=asset,
-            run_id=run_id,
-            settings=settings,
-            runner=runner,
-            progress_callback=_progress_callback(quiet, verbose, json_progress),
-            experience_pack_refs=experience_refs,
-        )
+        try:
+            run_root,bundle=run_prompt_task(
+                effective_instruction,
+                assets=asset,
+                run_id=run_id,
+                settings=settings,
+                runner=runner,
+                progress_callback=_progress_callback(quiet, verbose, json_progress),
+                experience_pack_refs=experience_refs,
+            )
+        except RunInterrupted as exc:
+            if not quiet and not json_progress:
+                typer.echo("")
+                typer.echo("Run interrupted.")
+                typer.echo("Run directory:")
+                typer.echo(str(exc.run_root))
+            raise typer.Exit(130)
     status = read_run_status(run_root)
     if quiet:
         _print_task_result(status, include_contribution_help=False)
@@ -1315,7 +1408,28 @@ def continue_run(
         hybrid_auto_approve=hybrid_auto_approve,
         mentor_interactive_checkpoints=interactive_checkpoints,
     ):
-        run_root,bundle=continue_session(run_id, followup_instruction, assets=asset, run_loop=run_loop, settings=settings, runner=runner, progress_callback=_progress_callback(quiet, verbose, json_progress))
+        try:
+            run_root,bundle=continue_session(run_id, followup_instruction, assets=asset, run_loop=run_loop, settings=settings, runner=runner, progress_callback=_progress_callback(quiet, verbose, json_progress))
+        except KeyboardInterrupt:
+            previous_status = read_run_status(run_root)
+            append_progress_event(
+                run_root,
+                "followup_interrupted",
+                run_id=run_root.name,
+                message="Follow-up interrupted by user.",
+                phase="interrupted",
+                run_status="partial",
+                task_status="partial",
+                contribution_bundle_path=previous_status.get("contribution_bundle_path"),
+                operational_error="Follow-up interrupted by user.",
+            )
+            if not quiet and not json_progress:
+                typer.echo("")
+                typer.echo("Follow-up interrupted.")
+                if previous_status.get("contribution_bundle_path"):
+                    typer.echo("Previous Contribution Bundle:")
+                    typer.echo(str(previous_status.get("contribution_bundle_path")))
+            raise typer.Exit(130)
     status = read_run_status(run_root)
     if quiet:
         _print_task_result(status, followup=True, record_only=not run_loop, include_contribution_help=False)
@@ -1540,6 +1654,150 @@ def _index_from_gh(repo: str) -> list[dict]:
     )
 
 
+def _read_public_url_text(url: str, *, timeout: int = 20) -> str:
+    req = urllib.request.Request(
+        url,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "agent-apprenticeship-cli",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as response:
+        return response.read().decode("utf-8")
+
+
+def _github_raw_url(repo: str, path: str, ref: str = "main") -> str:
+    quoted = urllib.parse.quote(path.strip("/"), safe="/")
+    return f"https://raw.githubusercontent.com/{repo}/{ref}/{quoted}"
+
+
+def _github_contents_url(repo: str, path: str, ref: str = "main") -> str:
+    quoted = urllib.parse.quote(path.strip("/"), safe="/")
+    suffix = f"/{quoted}" if quoted else ""
+    return f"https://api.github.com/repos/{repo}/contents{suffix}?ref={urllib.parse.quote(ref)}"
+
+
+def _public_index_cache_path(repo: str) -> Path:
+    slug = re.sub(r"[^A-Za-z0-9_.-]+", "_", repo)
+    return get_settings().app_home / "ecosystem" / "public_index_cache" / f"{slug}.json"
+
+
+def _load_public_index_cache(repo: str) -> list[dict] | None:
+    path = _public_index_cache_path(repo)
+    if not path.exists():
+        return None
+    try:
+        data = read_json(path)
+    except Exception:
+        return None
+    rows = data.get("rows") if isinstance(data, dict) else None
+    if not isinstance(rows, list):
+        return None
+    return [row for row in rows if isinstance(row, dict)]
+
+
+def _write_public_index_cache(repo: str, rows: list[dict]) -> None:
+    path = _public_index_cache_path(repo)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_json(
+        path,
+        {
+            "kind": "public_ecosystem_index_cache",
+            "repo": repo,
+            "repo_url": _ecosystem_repo_url(repo),
+            "cached_at": datetime.now(timezone.utc).isoformat(),
+            "rows": rows,
+        },
+    )
+
+
+def _rows_from_index_text(text: str, *, suffix: str) -> list[dict]:
+    if suffix == ".jsonl":
+        return [json.loads(line) for line in text.splitlines() if line.strip()]
+    data = json.loads(text or "{}")
+    if isinstance(data, list):
+        return [row for row in data if isinstance(row, dict)]
+    if isinstance(data, dict):
+        rows = (
+            data.get("bundles")
+            or data.get("items")
+            or data.get("entries")
+            or data.get("contributions")
+            or []
+        )
+        return [row for row in rows if isinstance(row, dict)]
+    return []
+
+
+def _index_from_public_repo_url(repo: str) -> list[dict]:
+    rows: list[dict] = []
+    errors: list[str] = []
+    for path in [
+        "seed_dataset/ecosystem_registry.jsonl",
+        "seed_dataset/ecosystem_registry.json",
+        "ecosystem/contributions/index.json",
+        "ecosystem/contributions/index.jsonl",
+    ]:
+        try:
+            text = _read_public_url_text(_github_raw_url(repo, path), timeout=20)
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            errors.append(f"{path}: {exc}")
+            continue
+        for row in _rows_from_index_text(text, suffix=Path(path).suffix):
+            out = dict(row)
+            out.setdefault("public_repo_slug", repo)
+            out.setdefault("public_repo_url", _ecosystem_repo_url(repo))
+            if path.startswith("seed_dataset/"):
+                out.setdefault("kind", "seed_task")
+                out.setdefault("experience_source_type", "seed_task")
+            else:
+                out.setdefault("kind", "contribution_bundle")
+                out.setdefault("experience_source_type", "contribution_bundle")
+            rows.append(out)
+    if not rows:
+        detail = "; ".join(errors[:3])
+        raise FileNotFoundError(
+            f"Could not read public ecosystem index from https://github.com/{repo}. {detail}".strip()
+        )
+    deduped: list[dict] = []
+    seen: set[str] = set()
+    for row in rows:
+        key = str(row.get("bundle_id") or row.get("seed_task_id") or row.get("task_id") or "")
+        if key and key in seen:
+            continue
+        if key:
+            seen.add(key)
+        deduped.append(row)
+    _write_public_index_cache(repo, deduped)
+    return deduped
+
+
+def _download_public_repo_path(repo: str, rel_path: str, dest: Path) -> None:
+    data = json.loads(_read_public_url_text(_github_contents_url(repo, rel_path), timeout=20))
+    if isinstance(data, list):
+        dest.mkdir(parents=True, exist_ok=True)
+        for item in data:
+            item_type = item.get("type")
+            item_path = item.get("path")
+            item_name = item.get("name")
+            if not item_path or not item_name:
+                continue
+            if item_type == "dir":
+                _download_public_repo_path(repo, item_path, dest / item_name)
+            elif item_type == "file":
+                download_url = item.get("download_url") or _github_raw_url(repo, item_path)
+                target = dest / item_name
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(_read_public_url_text(download_url, timeout=20))
+        return
+    if isinstance(data, dict) and data.get("type") == "file":
+        download_url = data.get("download_url") or _github_raw_url(repo, data.get("path") or rel_path)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(_read_public_url_text(download_url, timeout=20))
+        return
+    raise FileNotFoundError(f"Could not download public ecosystem path: {rel_path}")
+
+
 def _load_json_rows(path: Path) -> list[dict]:
     if not path.exists():
         return []
@@ -1648,15 +1906,21 @@ def _load_registry(registry: Path | None=None) -> list[dict]:
             return _index_from_public_repo_path(repo_path)
         repo = _configured_ecosystem_repo()
         if repo:
+            cached = _load_public_index_cache(repo)
+            if cached:
+                return cached
             try:
-                return _index_from_gh(repo)
+                return _index_from_public_repo_url(repo)
             except FileNotFoundError as exc:
-                seed_rows = search_learning_sources(None)
-                if repo == DEFAULT_PUBLIC_ECOSYSTEM_REPO and seed_rows:
-                    return seed_rows
-                raise FileNotFoundError(
-                    f"Public ecosystem repo is configured as {repo}, but the index could not be read. {exc}"
-                )
+                try:
+                    return _index_from_gh(repo)
+                except FileNotFoundError as gh_exc:
+                    seed_rows = search_learning_sources(None)
+                    if repo == DEFAULT_PUBLIC_ECOSYSTEM_REPO and seed_rows:
+                        return seed_rows
+                    raise FileNotFoundError(
+                        f"Public ecosystem repo is configured as {repo}, but the index could not be read. {exc} {gh_exc}"
+                    )
         path=_default_registry_path()
         if not path.exists():
             seed_rows = search_learning_sources(None)
@@ -1769,7 +2033,7 @@ def _format_registry_row(row: dict) -> str:
         str(row.get("task_status") or row.get("run_status") or "status_unknown"),
     ]
     if row.get("mentor_mode"):
-        details.append(f"mentor_mode={row.get('mentor_mode')}")
+        details.append(f"mentor_mode={mentor_mode_display(row.get('mentor_mode'))}")
     traces = row.get("traced_steps")
     if traces is not None:
         details.append(f"traces: {_format_count(traces)}")
@@ -1884,7 +2148,7 @@ def _submission_summary(metadata: dict, bundle: Path, package_zip: Path | None =
         f"Task Status: {metadata.get('task_status')}",
         f"Run Status: {metadata.get('run_status')}",
         f"Apprentice Agent: {metadata.get('apprentice_agent') or 'unknown'}",
-        f"Mentor Mode: {metadata.get('mentor_mode')}",
+        f"Mentor Mode: {mentor_mode_display(metadata.get('mentor_mode'))}",
         f"Mentor Model Provider: {metadata.get('mentor_model_provider') or 'none'}",
         f"Attempts: {metadata.get('attempts')}",
         f"Traced Steps: {metadata.get('traced_steps')}",
@@ -2045,7 +2309,7 @@ def _print_auto_share_summary(metadata: dict) -> None:
     typer.echo(f"title: {metadata.get('title')}")
     typer.echo(f"task_status: {metadata.get('task_status')}")
     typer.echo(f"Apprentice Agent: {metadata.get('apprentice_agent') or 'unknown'}")
-    typer.echo(f"Mentor Mode: {metadata.get('mentor_mode')}")
+    typer.echo(f"Mentor Mode: {mentor_mode_display(metadata.get('mentor_mode'))}")
     typer.echo(f"Mentor Model Provider: {metadata.get('mentor_model_provider') or 'none'}")
     typer.echo(f"artifact_count: {metadata.get('artifact_count')}")
 
@@ -2605,6 +2869,7 @@ def ecosystem_pull(
         row = {**row, "experience_source_type": row.get("experience_source_type") or "seed_task", "pulled_item_type": "seed_task"}
         try:
             write_json(dest / "ecosystem_item.json", row)
+            public_repo = row.get("public_repo_slug")
 
             def resolve_seed_path(raw: str | None) -> Path | None:
                 if not raw:
@@ -2613,15 +2878,17 @@ def ecosystem_pull(
                 return path if path.is_absolute() else Path.cwd() / path
 
             def copy_seed_path(raw: str | None, target_rel: str) -> None:
-                source_path = resolve_seed_path(raw)
-                if not source_path or not source_path.exists():
+                if not raw:
                     return
+                source_path = resolve_seed_path(raw)
                 target = dest / target_rel
                 target.parent.mkdir(parents=True, exist_ok=True)
-                if source_path.is_dir():
+                if source_path and source_path.exists() and source_path.is_dir():
                     shutil.copytree(source_path, target, dirs_exist_ok=True)
-                else:
+                elif source_path and source_path.exists():
                     shutil.copy2(source_path, target)
+                elif public_repo:
+                    _download_public_repo_path(str(public_repo), str(raw), target)
 
             copy_seed_path(row.get("task_path") or row.get("task_packet_path"), "task")
             copy_seed_path(row.get("rubric_path"), "rubric/rubric.json")
@@ -2632,8 +2899,8 @@ def ecosystem_pull(
             copy_seed_path(row.get("learning_signals_path"), "learning_signals")
             for idx, trace_path in enumerate(row.get("trace_paths") or [], 1):
                 trace_source = resolve_seed_path(str(trace_path))
-                if trace_source and trace_source.exists():
-                    target_name = Path(trace_path).parent.name or f"trace_{idx}"
+                target_name = Path(trace_path).parent.name or f"trace_{idx}"
+                if (trace_source and trace_source.exists()) or public_repo:
                     copy_seed_path(str(trace_path), f"traces/{target_name}/{Path(trace_path).name}")
         except OSError as exc:
             typer.echo('Could not pull ecosystem seed task.')
@@ -2668,7 +2935,13 @@ def _summarize_bundle_manifest(manifest: dict) -> str:
         'agent_apprentice_role','expected_economic_value',
         'expected_economic_value_for_agent_apprentice','mentor_mode','task_status','run_status'
     ]
-    return '\n'.join(f'{key}: {manifest.get(key)}' for key in keys if key in manifest)
+    lines = []
+    for key in keys:
+        if key not in manifest:
+            continue
+        value = mentor_mode_display(manifest.get(key)) if key == "mentor_mode" else manifest.get(key)
+        lines.append(f"{key}: {value}")
+    return "\n".join(lines)
 
 
 def _summarize_seed_registry_row(row: dict) -> str:
@@ -2718,7 +2991,8 @@ def _summarize_contribution_registry_row(row: dict) -> str:
         "expected_economic_value_for_agent_apprentice",
     ]:
         if row.get(key) is not None:
-            lines.append(f"{key}: {row.get(key)}")
+            value = mentor_mode_display(row.get(key)) if key == "mentor_mode" else row.get(key)
+            lines.append(f"{key}: {value}")
     if row.get("domains"):
         lines.append(f"domains: {row.get('domains')}")
     if row.get("subdomains"):
@@ -2775,6 +3049,60 @@ def bundle_inspect(path: Path=typer.Argument(..., help='Contribution Bundle fold
     typer.echo(f"Next: apprentice ecosystem contribute {path}")
 
 
+@bundle_app.command('check')
+def bundle_check(path: Path=typer.Argument(..., help='Contribution Bundle folder.')):
+    issues: list[str] = []
+    bundle = Path(path).expanduser()
+    manifest_path = bundle / "contribution_manifest.json"
+    if not bundle.exists():
+        issues.append(f"Bundle path does not exist: {bundle}")
+    elif not manifest_path.exists():
+        issues.append(f"Contribution Bundle manifest not found: {manifest_path}")
+    manifest_data = {}
+    if manifest_path.exists():
+        try:
+            manifest_data = read_json(manifest_path)
+        except Exception as exc:
+            issues.append(f"contribution_manifest.json could not be parsed: {exc}")
+    artifact_index_path = bundle / "outputs" / "artifacts_index.json"
+    artifacts: list[dict] = []
+    if artifact_index_path.exists():
+        try:
+            raw_artifacts = read_json(artifact_index_path)
+            if isinstance(raw_artifacts, list):
+                artifacts = raw_artifacts
+            else:
+                issues.append("outputs/artifacts_index.json must contain a JSON list.")
+        except Exception as exc:
+            issues.append(f"outputs/artifacts_index.json could not be parsed: {exc}")
+    for row in artifacts:
+        ref = row.get("package_relative_path") or row.get("artifact_ref")
+        if ref and not (bundle / str(ref)).exists():
+            issues.append(f"Referenced artifact is missing: {ref}")
+    for optional in ["session_events.jsonl", "progress_events.jsonl"]:
+        file_path = bundle / optional
+        if file_path.exists():
+            try:
+                read_jsonl(file_path)
+            except Exception as exc:
+                issues.append(f"{optional} could not be parsed: {exc}")
+    secret_hits = _bundle_secret_hits(bundle) if bundle.exists() else []
+    if secret_hits:
+        issues.append("Obvious secret-like values were found: " + ", ".join(secret_hits[:10]))
+    if issues:
+        typer.echo("Bundle check: needs attention")
+        typer.echo(f"Bundle: {bundle}")
+        for issue in issues:
+            typer.echo(f"Reason: {redact_secrets(issue)}")
+        typer.echo("Next action: fix the packaging issue, then rerun `apprentice bundle check`.")
+        raise typer.Exit(1)
+    status = manifest_data.get("task_status") or manifest_data.get("run_status") or "unknown"
+    typer.echo("Bundle check: passed")
+    typer.echo(f"Bundle: {bundle}")
+    typer.echo(f"Task status: {status}")
+    typer.echo("This bundle is ready to add to the public ecosystem.")
+
+
 @bundle_app.command('contribute')
 def bundle_contribute(path: Path=typer.Argument(..., help='Contribution Bundle folder.')):
     manifest=path/'contribution_manifest.json'
@@ -2782,11 +3110,10 @@ def bundle_contribute(path: Path=typer.Argument(..., help='Contribution Bundle f
         typer.echo(f'Contribution Bundle manifest not found: {manifest}')
         raise typer.Exit(1)
     try:
-        result = _ecosystem_contribute_impl(path, auto_share_mode="manual")
+        submission_dir, package_zip, metadata = _create_ecosystem_submission(path)
     except Exception as exc:
         typer.echo(f"Could not prepare public ecosystem contribution: {redact_secrets(str(exc))}")
         raise typer.Exit(1)
-    metadata = result["metadata"]
     typer.echo('Contribution Bundle ready.')
     typer.echo('')
     typer.echo(f"Bundle ID: {metadata.get('bundle_id')}")
@@ -2794,14 +3121,9 @@ def bundle_contribute(path: Path=typer.Argument(..., help='Contribution Bundle f
     typer.echo('Bundle:')
     typer.echo(str(path))
     typer.echo('')
-    if result["contribution_created"]:
-        typer.echo(f"Public contribution URL: {result['contribution_url']}")
-        typer.echo("No bundle files were uploaded automatically. Attach or submit the generated package according to the repo instructions.")
-        return
     typer.echo('No upload was performed by this command.')
-    reason = result.get("skipped_reason")
-    if reason:
-        typer.echo(f"Reason: {reason}")
+    typer.echo(f"Submission package: {package_zip}")
+    typer.echo(f"Submission metadata: {submission_dir / 'ecosystem_submission.json'}")
     typer.echo('')
     typer.echo('Contribute to public ecosystem:')
     typer.echo(f'apprentice ecosystem contribute {path}')
@@ -2812,27 +3134,27 @@ def bundle_contribute(path: Path=typer.Argument(..., help='Contribution Bundle f
     typer.echo('View files:')
     typer.echo(f'open {path}')
 
-@app.command('init-env')
+@app.command('init-env', hidden=True)
 def init_env():
     dst=Path('.env.local')
     if not dst.exists(): shutil.copyfile('.env.example', dst); typer.echo('created .env.local from .env.example')
     else: typer.echo('.env.local already exists')
 
-@app.command('run-task')
+@app.command('run-task', hidden=True)
 def run_task(input: Path=typer.Option(Path('data/seed_tasks/hard_finance_reconciliation.jsonl')), output_root: Path=Path('outputs'), runner: str='deterministic'):
     raw=RawTaskRecord.model_validate(read_jsonl(input)[0])
     run_root=output_root/'runs'/'single'
     pkg=run_one(raw, run_root, runner=runner); typer.echo(str(pkg))
 
-@app.command('run-batch')
+@app.command('run-batch', hidden=True)
 def run_batch(input: Path=typer.Option(...), limit: int|None=None, resume: bool=False, max_parallel: int=1, retry_limit: int=0, task_timeout_seconds: int=900, runner: str='deterministic', release_id: str|None=None, output_root: Path=Path('outputs'), max_iterations: int|None=None):
     typer.echo(str(run_batch_impl(input, output_root, limit, resume, max_parallel, retry_limit, task_timeout_seconds, runner, release_id, max_iterations=max_iterations)))
 
-@app.command('run-many')
+@app.command('run-many', hidden=True)
 def run_many(input: Path=typer.Option(...), limit: int|None=None, resume: bool=False, max_parallel: int=1, retry_limit: int=0, task_timeout_seconds: int=900, runner: str='deterministic', release_id: str|None=None, output_root: Path=Path('outputs'), max_iterations: int|None=None):
     typer.echo(str(run_batch_impl(input, output_root, limit, resume, max_parallel, retry_limit, task_timeout_seconds, runner, release_id, max_iterations=max_iterations)))
 
-@app.command('create-bundle')
+@app.command('create-bundle', hidden=True)
 def create_bundle(
     run_root: Path=typer.Option(...),
     bundle_root: Path|None=typer.Option(None),
@@ -2841,15 +3163,15 @@ def create_bundle(
 ):
     typer.echo(str(create_contribution_bundle(run_root, bundle_root, include_debug=include_debug, release_style=release_style)))
 
-@app.command('create-release')
+@app.command('create-release', hidden=True)
 def create_release(run_root: Path=typer.Option(Path('outputs/runs/single')), release_root: Path=typer.Option(Path('outputs/releases/manual'))):
     typer.echo(str(create_release_impl(run_root, release_root)))
 
-@app.command('validate-release')
+@app.command('validate-release', hidden=True)
 def validate_release(release_root: Path=typer.Option(...)):
     c=validate_release_impl(release_root); typer.echo(format_counters(c)); raise typer.Exit(0 if c['release_valid'] else 1)
 
-@app.command('validate-public-release')
+@app.command('validate-public-release', hidden=True)
 def validate_public_release(release_root: Path=typer.Option(...)):
     public=release_root/'public' if (release_root/'public').exists() else release_root
     c=validate_release_impl(release_root if (release_root/'public').exists() else release_root.parent) if public.name == 'public' else validate_release_impl(release_root)
@@ -2857,7 +3179,7 @@ def validate_public_release(release_root: Path=typer.Option(...)):
     raise typer.Exit(0 if c.get('public_release_valid') else 1)
 
 
-@app.command('repair-roles')
+@app.command('repair-roles', hidden=True)
 def repair_roles(run_root: Path=typer.Option(...), task_id: str=typer.Option(...), roles: str=typer.Option('evaluator_agent,grader_agent,verifier_agent'), attempts: str=typer.Option('baseline,revised'), rebuild_release: Path|None=typer.Option(None)):
     """Re-run model evaluation roles from existing task package artifacts/traces."""
     from .schemas import RubricSpec, ActualOutputs, AgentTrace, GraderResult, VerifierResult
@@ -2916,7 +3238,7 @@ def repair_roles(run_root: Path=typer.Option(...), task_id: str=typer.Option(...
         typer.echo(f'rebuilt release={rebuild_release}')
 
 
-@app.command('summarize-releases')
+@app.command('summarize-releases', hidden=True)
 def summarize_releases(release_root: Path=typer.Option(Path('outputs/releases')), pattern: str=typer.Option('tasks-*')):
     """Summarize release readiness across a release directory."""
     from .validation import validate_release
@@ -2952,17 +3274,17 @@ def summarize_releases(release_root: Path=typer.Option(Path('outputs/releases'))
     typer.echo('task_ids_publishable_with_warnings=' + ','.join(warnings))
     typer.echo('task_ids_clean_publishable=' + ','.join(clean))
 
-@app.command('inspect-trace')
+@app.command('inspect-trace', hidden=True)
 def inspect_trace(trace_path: Path):
     t=AgentTrace.model_validate_json(trace_path.read_text()); typer.echo(f'trace_id={t.trace_id}\ntask_id={t.task_id}\nsteps={len(t.steps)}')
 
-@app.command('codex-smoke')
+@app.command('codex-smoke', hidden=True)
 def codex_smoke():
     if not shutil.which('codex'):
         typer.echo('codex_available=false'); raise typer.Exit(1)
     typer.echo('codex_available=true')
 
-@app.command('llm-smoke')
+@app.command('llm-smoke', hidden=True)
 def llm_smoke(
     output_dir: Path=Path('outputs/llm_smoke'),
     provider: str | None=typer.Option(None, '--provider', help='Mentor Model Provider id to test. Defaults to configured provider.'),