kanibako-cli 1.5.0.dev14__py3-none-any.whl

kanibako/commands/start.py

@@ -0,0 +1,1600 @@
+"""kanibako start / shell: container launch with credential flow."""
+
+from __future__ import annotations
+
+import argparse
+import fcntl
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from kanibako.crabs import load_crab_config, write_crab_config
+from kanibako.config import config_file_path, load_config, load_merged_config
+from kanibako.container import ContainerRuntime
+from kanibako.errors import ContainerError
+from kanibako.log import get_logger
+from kanibako.rig_registry import load_registry, registry_path
+from kanibako.rig_resolve import resolve_rig
+from kanibako.paths import (
+    _upgrade_shell,
+    xdg,
+    load_std_paths,
+    resolve_any_project,
+)
+from kanibako.targets import resolve_target
+from kanibako.utils import container_name_for, short_hash
+
+
+def add_start_parser(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(
+        "start",
+        help="Start or continue an agent session (default)",
+        description="Start or continue an agent session in a container.",
+    )
+
+    # Start mode: -N/-C/-R mutually exclusive
+    mode_group = p.add_mutually_exclusive_group()
+    mode_group.add_argument(
+        "-N", "--new", action="store_true", dest="new_session",
+        help="Start a new conversation (skip default --continue)",
+    )
+    mode_group.add_argument(
+        "-C", "--continue", action="store_true", dest="continue_session",
+        help="Continue the most recent conversation (default for existing projects)",
+    )
+    mode_group.add_argument(
+        "-R", "--resume", action="store_true", dest="resume_session",
+        help="Resume with conversation picker",
+    )
+
+    # Agent mode: -A/-S mutually exclusive
+    agent_group = p.add_mutually_exclusive_group()
+    agent_group.add_argument(
+        "-A", "--autonomous", action="store_true",
+        help="Run with full permissions (--dangerously-skip-permissions)",
+    )
+    agent_group.add_argument(
+        "-S", "--secure", action="store_true",
+        help="Run without --dangerously-skip-permissions",
+    )
+
+    p.add_argument(
+        "-M", "--model", default=None,
+        help="Override the agent model for this run",
+    )
+    p.add_argument(
+        "-e", "--env", action="append", default=None, metavar="KEY=VALUE",
+        help="Set per-run environment variable (repeatable)",
+    )
+    p.add_argument(
+        "--image", default=None,
+        help="Use IMAGE as the container image for this run (--rig is the preferred spelling)",
+    )
+    p.add_argument(
+        "--rig", dest="image", default=None,
+        help="Rig (image) to use; synonym for --image",
+    )
+    p.add_argument(
+        "--entrypoint", default=None,
+        help="Use CMD as the container entrypoint",
+    )
+
+    # Session persistence mode
+    persist_group = p.add_mutually_exclusive_group()
+    persist_group.add_argument(
+        "--persistent", action="store_true",
+        help="Run in a persistent tmux session (reattach on subsequent start)",
+    )
+    persist_group.add_argument(
+        "--ephemeral", action="store_true",
+        help="Run in foreground without tmux (single-use session)",
+    )
+
+    p.add_argument(
+        "--no-helpers", action="store_true",
+        help="Disable helper spawning (no hub socket mounted)",
+    )
+    p.add_argument(
+        "--no-auto-auth", action="store_true",
+        help="Disable automated browser-based OAuth refresh",
+    )
+    p.add_argument(
+        "--browser", action="store_true",
+        help="Launch a headless browser sidecar (BROWSER_WS_ENDPOINT injected)",
+    )
+    p.add_argument(
+        "--share-images", action="store_true",
+        help="Share host container image storage with child (read-only, experimental)",
+    )
+    p.add_argument(
+        "project", nargs="?", default=None,
+        help="Project directory or registered name (omit for current dir)",
+    )
+    p.set_defaults(func=run_start)
+
+
+def add_shell_parser(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(
+        "shell",
+        help="Open a bash shell in the container",
+        description="Open a bash shell in the container (no agent).",
+    )
+    p.add_argument(
+        "-e", "--env", action="append", default=None, metavar="KEY=VALUE",
+        help="Set per-run environment variable (repeatable)",
+    )
+    p.add_argument(
+        "--image", default=None,
+        help="Use IMAGE as the container image for this run (--rig is the preferred spelling)",
+    )
+    p.add_argument(
+        "--rig", dest="image", default=None,
+        help="Rig (image) to use; synonym for --image",
+    )
+    p.add_argument(
+        "--entrypoint", default=None,
+        help="Use CMD as the container entrypoint",
+    )
+
+    # Session persistence mode
+    persist_group = p.add_mutually_exclusive_group()
+    persist_group.add_argument(
+        "--persistent", action="store_true",
+        help="Run in a persistent tmux session (reattach on subsequent start)",
+    )
+    persist_group.add_argument(
+        "--ephemeral", action="store_true",
+        help="Run in foreground without tmux (single-use session)",
+    )
+
+    p.add_argument(
+        "--no-helpers", action="store_true",
+        help="Disable helper spawning (no hub socket mounted)",
+    )
+    p.add_argument(
+        "--share-images", action="store_true",
+        help="Share host container image storage with child (read-only, experimental)",
+    )
+    p.add_argument(
+        "project", nargs="?", default=None,
+        help="Project directory or registered name (omit for current dir)",
+    )
+    p.set_defaults(func=run_shell)
+
+
+def run_start(args: argparse.Namespace) -> int:
+    entrypoint = getattr(args, "entrypoint", None)
+    image_override = getattr(args, "image", None)
+    new_session = getattr(args, "new_session", False)
+    resume_session = getattr(args, "resume_session", False)
+    secure = getattr(args, "secure", False)
+    model_override = getattr(args, "model", None)
+    no_helpers = getattr(args, "no_helpers", False)
+    no_auto_auth = getattr(args, "no_auto_auth", False)
+    browser = getattr(args, "browser", False)
+    share_images = getattr(args, "share_images", False)
+    explicit_persistent = getattr(args, "persistent", False)
+    explicit_ephemeral = getattr(args, "ephemeral", False)
+    if explicit_persistent:
+        persistent = True
+    elif explicit_ephemeral:
+        persistent = False
+    else:
+        # Default: persistent when tmux is available
+        persistent = _tmux_available()
+    env_vars = getattr(args, "env", None) or []
+    project_dir = getattr(args, "project", None)
+    agent_args = getattr(args, "agent_args", [])
+
+    # Map -A/-S to safe_mode: -A means autonomous (safe_mode=False),
+    # -S means secure (safe_mode=True). Neither means autonomous (default).
+    safe_mode = secure
+
+    # Check for agent before launching container.
+    # If no agent is detected, show a helpful message instead of silently
+    # launching a plain shell.  run_shell() is not affected.
+    from kanibako.targets.no_agent import NoAgentTarget
+    target = resolve_target()
+    if isinstance(target, NoAgentTarget):
+        print()
+        print("No agents detected.")
+        print()
+        print("  Install a plugin:  pip install kanibako-agent-claude")
+        print("  Run setup wizard:  kanibako setup")
+        print("  Health check:      kanibako system diagnose")
+        print("  Plain sandbox:     kanibako shell")
+        print()
+        return 0
+
+    return _run_container(
+        project_dir=project_dir,
+        entrypoint=entrypoint,
+        image_override=image_override,
+        new_session=new_session,
+        safe_mode=safe_mode,
+        resume_mode=resume_session,
+        extra_args=agent_args,
+        no_helpers=no_helpers,
+        no_auto_auth=no_auto_auth,
+        browser=browser,
+        share_images=share_images,
+        persistent=persistent,
+        model_override=model_override,
+        cli_env=env_vars,
+    )
+
+
+def run_shell(args: argparse.Namespace) -> int:
+    project_dir = getattr(args, "project", None)
+    shell_args = getattr(args, "shell_args", [])
+
+    entrypoint = getattr(args, "entrypoint", None)
+    if not entrypoint:
+        entrypoint = "/bin/sh" if shell_args else "/bin/bash"
+    # Wrap shell_args as -c "cmd" so /bin/sh executes them as a command
+    if shell_args and not getattr(args, "entrypoint", None):
+        shell_args = ["-c", " ".join(shell_args)]
+
+    image_override = getattr(args, "image", None)
+    no_helpers = getattr(args, "no_helpers", False)
+    share_images = getattr(args, "share_images", False)
+    env_vars = getattr(args, "env", None) or []
+
+    explicit_persistent = getattr(args, "persistent", False)
+    explicit_ephemeral = getattr(args, "ephemeral", False)
+    if explicit_persistent:
+        persistent = True
+    elif explicit_ephemeral:
+        persistent = False
+    else:
+        persistent = False  # shell defaults to ephemeral
+
+    return _run_container(
+        project_dir=project_dir,
+        entrypoint=entrypoint,
+        image_override=image_override,
+        new_session=False,
+        safe_mode=False,
+        resume_mode=False,
+        extra_args=shell_args,
+        no_helpers=no_helpers,
+        share_images=share_images,
+        persistent=persistent,
+        cli_env=env_vars,
+    )
+
+
+def _tmux_available() -> bool:
+    """Check if tmux is installed."""
+    return shutil.which("tmux") is not None
+
+
+def _tmux_session_name(project_name: str) -> str:
+    """Generate a deterministic tmux session name for host-side reattach."""
+    return f"kanibako-{project_name}"
+
+
+def _tmux_has_session(session_name: str) -> bool:
+    """Check if a tmux session exists on the host."""
+    return subprocess.run(
+        ["tmux", "has-session", "-t", session_name],
+        capture_output=True,
+    ).returncode == 0
+
+
+def _apply_tweakcc(install, crab_cfg, cache_path, image, runtime_cmd, logger):
+    """Apply tweakcc patching if enabled in crab config.
+
+    Patching runs inside a throwaway container (``podman run --rm``) using
+    the same image that will be used for the agent.  The patched binary is
+    cached on disk with flock-based reference counting.
+
+    Returns ``(patched_install, cache_entry, cache)`` on success, or
+    *None* if tweakcc is disabled or patching fails (graceful fallback).
+    """
+    from kanibako.bun_sea import BunSEAError, cli_js_hash
+    from kanibako.targets.base import AgentInstall
+    from kanibako.tweakcc import build_merged_config, resolve_tweakcc_config, write_merged_config
+    from kanibako.tweakcc_cache import TweakccCache, TweakccCacheError, config_hash
+
+    tweakcc_cfg = resolve_tweakcc_config(crab_cfg.tweakcc)
+    if not tweakcc_cfg.enabled:
+        return None
+
+    try:
+        merged_config = build_merged_config(tweakcc_cfg)
+        bin_hash = cli_js_hash(install.binary)
+        cfg_hash = config_hash(merged_config)
+
+        cache_dir = cache_path / "tweakcc"
+        cache = TweakccCache(cache_dir)
+        key = cache.cache_key(bin_hash, cfg_hash)
+
+        entry = cache.get(key)
+        if entry is None:
+            # Write merged config to cache dir (will be mounted into container)
+            config_file = cache_dir / f".config-{key}.json"
+            write_merged_config(merged_config, config_file)
+
+            def patch_fn(staging_dir, staging_binary):
+                """Run tweakcc --apply inside a throwaway container."""
+                cmd = [
+                    runtime_cmd, "run", "--rm", "--network=none",
+                    "-v", f"{staging_dir}:/work:rw",
+                    "-v", f"{config_file}:/root/.tweakcc/config.json:ro",
+                    "-e", f"TWEAKCC_CC_INSTALLATION_PATH=/work/{staging_binary.name}",
+                    image,
+                    "tweakcc", "--apply",
+                ]
+                logger.debug("Running tweakcc via container: %s", cmd)
+                result = subprocess.run(
+                    cmd, capture_output=True, text=True, check=False,
+                )
+                if result.returncode != 0:
+                    raise TweakccCacheError(
+                        f"tweakcc container failed (exit {result.returncode}): "
+                        f"{result.stderr.strip()}"
+                    )
+
+            entry = cache.put(key, install.binary, patch_fn)
+            logger.info("Patched binary cached: %s", key)
+        else:
+            logger.info("Using cached patched binary: %s", key)
+
+        patched_install = AgentInstall(
+            name=install.name,
+            binary=entry.path,
+            install_dir=install.install_dir,
+        )
+        return patched_install, entry, cache
+
+    except (BunSEAError, TweakccCacheError) as exc:
+        logger.warning(
+            "tweakcc patching failed, using unpatched binary: %s", exc,
+        )
+        return None
+
+
+def _parse_cli_env(cli_env: list[str] | None) -> dict[str, str]:
+    """Parse ``-e/--env KEY=VALUE`` items into a dict (ignores malformed ones)."""
+    env: dict[str, str] = {}
+    for item in cli_env or []:
+        if "=" in item:
+            k, v = item.split("=", 1)
+            env[k] = v
+    return env
+
+
+def _run_container(
+    *,
+    project_dir: str | None,
+    entrypoint: str | None,
+    image_override: str | None,
+    new_session: bool,
+    safe_mode: bool,
+    resume_mode: bool,
+    extra_args: list[str],
+    no_helpers: bool = False,
+    no_auto_auth: bool = False,
+    browser: bool = False,
+    share_images: bool = False,
+    persistent: bool = False,
+    model_override: str | None = None,
+    cli_env: list[str] | None = None,
+    _is_retry: bool = False,
+) -> int:
+    config_file = config_file_path(xdg("XDG_CONFIG_HOME", ".config"))
+    config = load_config(config_file)
+
+    std = load_std_paths(config)
+
+    proj = resolve_any_project(std, config, project_dir, initialize=True)
+
+    # Hint about orphaned project data when initializing a new project
+    if proj.is_new and proj.group is not None and proj.group.is_default:
+        from kanibako.paths import iter_projects
+        for _settings, _ppath in iter_projects(std, config):
+            if _ppath is not None and not _ppath.is_dir():
+                print(
+                    "hint: orphaned project data detected — "
+                    "run 'kanibako box list' or use 'kanibako box migrate' "
+                    "if you moved a project.",
+                    file=sys.stderr,
+                )
+                break
+
+    # Load merged config (global + workset + project)
+    project_toml = proj.metadata_path / "project.yaml"
+    workset_path = (proj.group.root / "config.yaml") if proj.group is not None else None
+    merged = load_merged_config(
+        config_file,
+        project_toml,
+        workset_path=workset_path,
+        cli_overrides={"box_image": image_override} if image_override else None,
+    )
+
+    image = merged.box_image
+
+    # Persist image override for new projects so it becomes the default
+    if proj.is_new and image_override:
+        from kanibako.config import write_project_config
+        write_project_config(project_toml, image_override)
+
+    # Detect container runtime and ensure image is available
+    try:
+        runtime = ContainerRuntime()
+    except ContainerError:
+        print(
+            "Error: No container runtime found.\n"
+            "Install podman (https://podman.io/) or Docker, then try again.",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Resolve the rig name to a kind + prep action, then materialize it.
+    # Templates BUILD their Containerfile; prefabs keep the existing
+    # inspect->pull->build behavior via ensure_image (non-regression).
+    containers_dir = std.data_path / "containers"
+    registry = load_registry(registry_path(std))
+    res = resolve_rig(image, runtime, std, merged, registry=registry)
+    try:
+        if (
+            res.kind == "template"
+            and res.containerfile is not None
+            and not runtime.image_exists(res.image)
+        ):
+            print(
+                f"Rig '{image}' isn't prepped — building...",
+                file=sys.stderr,
+            )
+            rc = runtime.rebuild(
+                res.image,
+                res.containerfile,
+                res.containerfile.parent,
+                build_args=None,
+            )
+            if rc != 0:
+                print(
+                    f"Error: failed to build rig '{image}' "
+                    f"(exit code {rc}).",
+                    file=sys.stderr,
+                )
+                return 1
+        else:
+            # Prefab (or already-local template/extended): preserve the
+            # existing inspect->pull->build-fallback behavior exactly.
+            runtime.ensure_image(res.image, containers_dir)
+    except ContainerError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    image = res.image
+
+    from kanibako.freshness import check_image_freshness
+    check_image_freshness(runtime, image, std.cache_path)
+
+    # Resolve target (agent plugin) and detect installation
+    logger = get_logger("start")
+    is_agent_mode = entrypoint is None
+    target = None
+    install = None
+    if is_agent_mode:
+        try:
+            target = resolve_target(merged.box_crab or None)
+        except KeyError as e:
+            print(
+                f"Error: {e}\n"
+                f"Run 'kanibako crab list' to see available agents, or\n"
+                f"'kanibako system diagnose' for a full health check.",
+                file=sys.stderr,
+            )
+            return 1
+        logger.debug("Resolved target: %s", target.display_name)
+        install = target.detect()
+        if install:
+            print(
+                f"Using host {target.display_name}: {install.binary}",
+                file=sys.stderr,
+            )
+        elif target.has_binary:
+            print(
+                f"Warning: {target.display_name} binary not found on host. "
+                f"Launching without agent.",
+                file=sys.stderr,
+            )
+            logger.debug("target.detect() returned None for %s", target.name)
+
+    # Load agent config
+    agent_id = target.name if target else "general"
+    crab_cfg_path = std.crabs / f"{agent_id}.yaml"
+    if target and not crab_cfg_path.exists():
+        # First-use: generate default crab config from target plugin
+        crab_cfg = target.generate_crab_config()
+        write_crab_config(crab_cfg_path, crab_cfg)
+    else:
+        crab_cfg = load_crab_config(crab_cfg_path)
+
+    # Deterministic container name for stop/cleanup
+    container_name = container_name_for(proj)
+
+    logger.debug("Project: %s (mode=%s)", proj.project_path, proj.mode)
+    logger.debug("Image: %s", image)
+    logger.debug("Container: %s", container_name)
+
+    # Persistent mode: reattach if already running, clean up stale containers
+    if persistent:
+        if runtime.is_running(container_name):
+            # Refresh credentials before reattaching
+            if target and proj.group_auth:
+                target.refresh_credentials(proj.shell_path)
+            return runtime.exec(
+                container_name, ["tmux", "attach", "-t", "kanibako"]
+            )
+        # Stale stopped container: remove before recreating
+        if runtime.container_exists(container_name):
+            runtime.rm(container_name)
+        # Persistent mode forces no helpers
+        no_helpers = True
+    else:
+        # Interactive (shell/ephemeral) mode: if a container is already
+        # running for this project AND we're in shell mode (entrypoint set,
+        # no agent), exec into it instead of erroring — matches the natural
+        # UX of `kanibako shell <name> -- cmd` against a live container.
+        if runtime.is_running(container_name) and entrypoint is not None:
+            exec_cmd = [entrypoint] + (extra_args or [])
+            # Apply per-run -e/--env vars to the exec'd process. The container's
+            # baseline env (env files, crab_cfg.env, KANIBAKO_NAME) was set at
+            # launch and is inherited by exec; without this, per-run -e vars
+            # would be silently dropped when the box is already running.
+            return runtime.exec(
+                container_name, exec_cmd, env=_parse_cli_env(cli_env)
+            )
+        if runtime.container_exists(container_name):
+            print(
+                "Error: A container already exists for this project.\n"
+                "  Reattach:  kanibako start\n"
+                "  Stop it:   kanibako stop",
+                file=sys.stderr,
+            )
+            return 1
+
+    # Concurrency lock (skip for persistent — container existence is the lock)
+    lock_fd = None
+    if not persistent:
+        lock_file = proj.metadata_path / ".kanibako.lock"
+        lock_file.parent.mkdir(parents=True, exist_ok=True)
+        lock_fd = open(lock_file, "w")
+        try:
+            fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            print(
+                "Error: Another Kanibako session is already running for this project.\n"
+                "  Stop it first:  kanibako stop\n"
+                "  Or use a shell: kanibako shell",
+                file=sys.stderr,
+            )
+            lock_fd.close()
+            return 1
+
+        # Record container name so `kanibako stop` can find it
+        lock_fd.write(container_name + "\n")
+        lock_fd.flush()
+
+    try:
+        # Auto-snapshot vault share-rw before launch.
+        if proj.enable_vault and proj.vault_rw_path.is_dir():
+            from kanibako.snapshots import auto_snapshot, detect_snapshot_strategy
+            strategy = detect_snapshot_strategy(proj.vault_rw_path)
+            snap = auto_snapshot(proj.vault_rw_path, strategy=strategy)
+            if snap:
+                print(f"Vault snapshot: {snap.name}", file=sys.stderr)
+
+        # Upgrade shell (add shell.d support to existing shells).
+        _upgrade_shell(proj.shell_path)
+
+        # Shell directory hygiene: remove waste files, compress old logs.
+        from kanibako.hygiene import cleanup_shell_dir
+        hygiene_actions = cleanup_shell_dir(proj.shell_path)
+        if hygiene_actions:
+            for action in hygiene_actions:
+                logger.info(action)
+
+        # Template application + agent init for new projects.
+        if proj.is_new and target:
+            from kanibako.templates import apply_shell_template
+            templates_base = std.templates
+            # Ensure the agent-specific template variant directory exists.
+            (templates_base / target.name / crab_cfg.shell).mkdir(parents=True, exist_ok=True)
+            apply_shell_template(proj.shell_path, templates_base, target.name, crab_cfg.shell)
+            target.init_home(proj.shell_path, group_auth=proj.group_auth)
+
+            # Merge layered instruction files (base + template + user).
+            instr_files = target.instruction_files()
+            if instr_files:
+                from kanibako.instructions import merge_instruction_files
+                merge_instruction_files(
+                    shell_path=proj.shell_path,
+                    config_dir_name=target.config_dir_name,
+                    instruction_files=instr_files,
+                    templates_base=templates_base,
+                    agent_name=target.name,
+                    template_name=crab_cfg.shell,
+                )
+
+        # Copy-once-at-init seeds (additive; overlays templates). target may be
+        # None (no agent) — seeds can still come from config levels.
+        if proj.is_new:
+            _apply_init_seeds(
+                std=std, proj=proj, crab_name=agent_id, target=target,
+                global_config_path=config_file, project_toml=project_toml,
+                workset_config_path=workset_path, crab_config_path=crab_cfg_path,
+                logger=logger,
+            )
+
+        # Automated OAuth refresh (before interactive check_auth)
+        if (
+            target
+            and install
+            and proj.group_auth
+            and not no_auto_auth
+            and target.name == "claude"
+        ):
+            try:
+                from kanibako.auth_browser import auto_refresh_auth
+
+                auto_result = auto_refresh_auth(
+                    str(install.binary), std.data_path
+                )
+                if auto_result.success:
+                    logger.info("Auto-auth succeeded")
+                else:
+                    logger.debug("Auto-auth skipped: %s", auto_result.error)
+            except Exception as exc:
+                logger.debug("Auto-auth failed: %s", exc)
+
+        # Pre-launch auth check (skip for distinct auth — creds live in project)
+        if target and install and proj.group_auth:
+            if not target.check_auth():
+                print(
+                    "Error: Authentication failed.\n"
+                    "  Re-authenticate:  kanibako crab reauth\n"
+                    "  Skip agent:       kanibako shell",
+                    file=sys.stderr,
+                )
+                return 1
+
+        # Credential refresh via target (skip for distinct auth)
+        if target and proj.group_auth:
+            target.refresh_credentials(proj.shell_path)
+
+        # tweakcc: patch agent binary if enabled
+        tweakcc_entry = None
+        tweakcc_cache_obj = None
+        if target and install and crab_cfg.tweakcc:
+            result = _apply_tweakcc(
+                install, crab_cfg, std.cache_path, image, runtime.cmd, logger,
+            )
+            if result:
+                install, tweakcc_entry, tweakcc_cache_obj = result
+
+        # Build CLI args via target, merging crab run_args and state
+        if target:
+            effective_state = _build_effective_state(
+                target,
+                crab_cfg,
+                project_toml,
+                global_config_path=config_file,
+                workset_config_path=workset_path,
+            )
+            # Apply model override from -M/--model flag
+            if model_override:
+                effective_state["model"] = model_override
+            state_args, state_env = target.apply_state(effective_state)
+            all_extra = list(crab_cfg.run_args) + list(extra_args)
+            cli_args = target.build_cli_args(
+                safe_mode=safe_mode,
+                resume_mode=resume_mode,
+                new_session=new_session,
+                is_new_project=proj.is_new,
+                extra_args=all_extra,
+            )
+            cli_args.extend(state_args)
+        else:
+            state_env = {}
+            cli_args = list(extra_args)
+
+        # Build extra mounts from target binary detection
+        extra_mounts = []
+        if target and install:
+            binary_mnts = target.binary_mounts(install)
+            if not binary_mnts:
+                print(
+                    f"Error: {target.display_name} binary detected at "
+                    f"{install.binary} but mount sources are missing.\n"
+                    f"  binary:      {install.binary} "
+                    f"({'exists' if install.binary.exists() else 'MISSING'})\n"
+                    f"  install_dir: {install.install_dir} "
+                    f"({'exists' if install.install_dir.exists() else 'MISSING'})\n"
+                    f"The container would launch without the agent binary.",
+                    file=sys.stderr,
+                )
+                return 1
+            _sync_binary_symlink(proj.shell_path, install, binary_mnts, logger)
+            extra_mounts.extend(binary_mnts)
+
+        # kanibako CLI bind-mount (package + entry script)
+        kanibako_mnts = _kanibako_mounts()
+        extra_mounts.extend(kanibako_mnts)
+
+        # Shared cache mounts (global, lazy — only mount if dir exists)
+        if proj.global_shared_path:
+            from kanibako.targets.base import Mount
+            for cache_name, container_rel in merged.shared_caches.items():
+                host_dir = proj.global_shared_path / cache_name
+                if host_dir.is_dir():
+                    extra_mounts.append(Mount(
+                        source=host_dir,
+                        destination=f"/home/agent/{container_rel}",
+                        options="Z,U",
+                    ))
+
+        # Agent-level shared cache mounts (lazy — only mount if dir exists)
+        if proj.local_shared_path and crab_cfg.shared_caches:
+            from kanibako.targets.base import Mount as _Mount
+            for cache_name, container_rel in crab_cfg.shared_caches.items():
+                host_dir = proj.local_shared_path / agent_id / cache_name
+                if host_dir.is_dir():
+                    extra_mounts.append(_Mount(
+                        source=host_dir,
+                        destination=f"/home/agent/{container_rel}",
+                        options="Z,U",
+                    ))
+
+        # Resource scope mounts (SHARED / SEEDED from target.resource_mappings())
+        if target and proj.global_shared_path:
+            resource_mounts = _build_resource_mounts(proj, target, agent_id)
+            extra_mounts.extend(resource_mounts)
+
+        # Scoped shares (settings-framework {scope}.path.share_{ro,rw}.*).
+        # Additive: empty config → no mounts → no behavior change.
+        share_mounts = _build_share_mounts(
+            std=std,
+            proj=proj,
+            crab_name=agent_id,
+            global_config_path=config_file,
+            project_toml=project_toml,
+            workset_config_path=workset_path,
+            crab_config_path=crab_cfg_path,
+            target=target,
+        )
+        extra_mounts.extend(share_mounts)
+
+        # Image sharing: mount host image storage read-only into child.
+        if share_images or merged.box_share_images:
+            from kanibako.image_sharing import build_image_sharing_mounts
+            staging = proj.metadata_path / ".image-sharing"
+            img_mounts = build_image_sharing_mounts(
+                runtime.cmd, staging,
+            )
+            if img_mounts:
+                extra_mounts.extend(img_mounts)
+                logger.info("Image sharing enabled: %d mounts added", len(img_mounts))
+            else:
+                print(
+                    "Warning: --share-images enabled but host image storage "
+                    "could not be detected. Continuing without image sharing.",
+                    file=sys.stderr,
+                )
+
+        # Peer communication: mount shared comms directory.
+        from kanibako.targets.base import Mount as _CMount
+        comms_path = std.comms
+        comms_path.mkdir(parents=True, exist_ok=True)
+        if proj.name:
+            mailbox = comms_path / "mailbox" / proj.name
+            mailbox.mkdir(parents=True, exist_ok=True)
+        broadcast = comms_path / "broadcast.log"
+        if not broadcast.exists():
+            broadcast.touch()
+        _rotate_file(broadcast)
+        extra_mounts.append(
+            _CMount(comms_path, "/home/agent/comms", "Z,U"),
+        )
+
+        # Read environment variables, accumulating across config levels with
+        # the settings-framework precedence (low->high): system < crab <
+        # workset < box.  Target-derived state env and per-run CLI -e env stay
+        # above all config levels.
+        global_env_path = std.data_path / "env"
+        project_env_path = proj.metadata_path / "env"
+        # Workset-level env applies only for a named (non-default) workset
+        # group; the default group's tier is already the system env.
+        workset_env_path = (
+            proj.group.root / "env"
+            if (proj.group is not None and not proj.group.is_default)
+            else None
+        )
+        container_env = _build_config_env(
+            global_env_path, crab_cfg.env, workset_env_path, project_env_path,
+        )
+        container_env.update(state_env)                        # target-derived state env
+
+        # Merge per-run -e/--env KEY=VALUE vars (highest priority).
+        container_env.update(_parse_cli_env(cli_env))
+
+        # Disable Claude Code telemetry inside containers.
+        if target and target.name == "claude":
+            container_env.setdefault(
+                "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1",
+            )
+
+        # Inject instance identity for peer communication.
+        if proj.name:
+            container_env["KANIBAKO_NAME"] = proj.name
+
+        # Helper hub: start listener before director, mount socket
+        hub = None
+        helpers_enabled = not no_helpers and merged.allow_helpers
+        if helpers_enabled:
+            from kanibako.helper_listener import HelperContext, HelperHub, MessageLog
+            from kanibako.targets.base import Mount as _HMount
+
+            # Socket must live in a short path to stay under the 108-byte
+            # AF_UNIX limit.  /run/user/$UID is the XDG runtime dir.
+            _uid = os.getuid()
+            _run_base = Path(os.environ.get("XDG_RUNTIME_DIR", f"/run/user/{_uid}"))
+            _run_dir = _run_base / "kanibako"
+            try:
+                _run_dir.mkdir(parents=True, exist_ok=True)
+            except OSError:
+                # Fallback if /run/user/$UID is not writable
+                _run_dir = Path(f"/tmp/kanibako-{_uid}")
+                _run_dir.mkdir(parents=True, exist_ok=True)
+            _sock_id = proj.name if proj.name else short_hash(proj.project_hash)
+            socket_path = _run_dir / f"{_sock_id}.sock"
+            validate_socket_path(socket_path)
+            _log_id = proj.name if proj.name else short_hash(proj.project_hash)
+            log_dir = std.data_path / "logs" / _log_id
+            log_dir.mkdir(parents=True, exist_ok=True)
+            log_path = log_dir / "helper-messages.jsonl"
+
+            # Ensure helpers/ dir exists in shell_path
+            helpers_dir = proj.shell_path / "helpers"
+            helpers_dir.mkdir(exist_ok=True)
+
+            # Build context for helper container launches
+            binary_mounts = list(kanibako_mnts)
+            if target and install:
+                binary_mounts.extend(target.binary_mounts(install))
+
+            # Share tweakcc cache with helpers so they reuse patched binaries
+            if tweakcc_entry is not None:
+                _tweakcc_cache_dir = std.cache_path / "tweakcc"
+                if _tweakcc_cache_dir.is_dir():
+                    binary_mounts.append(_HMount(
+                        source=_tweakcc_cache_dir,
+                        destination=str(_tweakcc_cache_dir),
+                        options="ro",
+                    ))
+
+            helper_ctx = HelperContext(
+                runtime=runtime,
+                image=image,
+                container_name_prefix=container_name,
+                shell_path=proj.shell_path,
+                helpers_dir=helpers_dir,
+                socket_path=socket_path,
+                binary_mounts=binary_mounts,
+                env=container_env,
+                entrypoint=entrypoint,
+                default_entrypoint=target.default_entrypoint if target else None,
+                project_path=proj.project_path,
+                data_path=std.data_path,
+                boxes=std.boxes,
+            )
+
+            msg_log = MessageLog(log_path)
+            hub = HelperHub()
+            hub.start(socket_path, helper_ctx, log=msg_log)
+
+            # Mount the socket into the container (only if hub started)
+            kanibako_dir = proj.shell_path / ".local" / "state" / "kanibako"
+            kanibako_dir.mkdir(parents=True, exist_ok=True)
+            if socket_path.exists():
+                extra_mounts.append(_HMount(
+                    source=socket_path,
+                    destination="/home/agent/.local/state/kanibako/helper.sock",
+                    options="",
+                ))
+
+            # Mount helper-messages.jsonl for log command inside container
+            if log_path.exists():
+                extra_mounts.append(_HMount(
+                    source=log_path,
+                    destination="/home/agent/.local/state/kanibako/helper-messages.jsonl",
+                    options="ro",
+                ))
+
+        # Pre-launch validation: warn about missing mount sources.
+        _validate_mounts(extra_mounts, logger)
+
+        # Browser sidecar: on-demand headless Chrome for agent web access
+        browser_sidecar = None
+        if browser:
+            try:
+                from kanibako.browser_sidecar import (
+                    BrowserSidecar,
+                    ws_endpoint_for_container,
+                )
+
+                sidecar_name = f"{container_name}-browser"
+                browser_sidecar = BrowserSidecar(
+                    runtime=runtime,
+                    container_name=sidecar_name,
+                )
+                ws_url = browser_sidecar.start()
+                container_ws = ws_endpoint_for_container(ws_url)
+                container_env["BROWSER_WS_ENDPOINT"] = container_ws
+                logger.info("Browser sidecar started: %s", container_ws)
+            except Exception as exc:
+                logger.warning("Browser sidecar failed to start: %s", exc)
+                browser_sidecar = None
+
+        # Set agent entrypoint if not explicitly overridden.
+        if not entrypoint and target:
+            entrypoint = target.default_entrypoint
+
+        # Persistent mode: wrap command with tmux
+        if persistent:
+            inner_cmd = entrypoint or "/bin/bash"
+            tmux_args = ["new-session", "-s", "kanibako", "--", inner_cmd]
+            if cli_args:
+                tmux_args.extend(cli_args)
+            entrypoint = "tmux"
+            cli_args = tmux_args
+
+        try:
+            # Run the container
+            rc = runtime.run(
+                image,
+                shell_path=proj.shell_path,
+                project_path=proj.project_path,
+                vault_ro_path=proj.vault_ro_path,
+                vault_rw_path=proj.vault_rw_path,
+                extra_mounts=extra_mounts or None,
+                vault_tmpfs=(proj.group is not None and proj.group.is_default),
+                enable_vault=proj.enable_vault,
+                env=container_env,
+                name=container_name,
+                entrypoint=entrypoint,
+                cli_args=cli_args or None,
+                detach=persistent,
+            )
+        finally:
+            # Stop helper hub after director exits
+            if hub is not None:
+                hub.stop()
+            # Release tweakcc cache entry (shared lock)
+            if tweakcc_entry is not None and tweakcc_cache_obj is not None:
+                tweakcc_cache_obj.release(tweakcc_entry)
+            # Stop browser sidecar
+            if browser_sidecar is not None:
+                try:
+                    browser_sidecar.stop()
+                except Exception as exc:
+                    logger.debug("Browser sidecar cleanup: %s", exc)
+
+        if persistent:
+            # Wait briefly for the detached container to start, then verify
+            # it's actually running before trying to exec into it.
+            import time
+            for _attempt in range(10):
+                if runtime.is_running(container_name):
+                    break
+                time.sleep(0.3)
+            else:
+                # Container never started or exited immediately. If the
+                # target says this is recoverable (e.g. "no conversation
+                # to continue"), retry with a fresh session before bailing.
+                logs = _container_logs(runtime, container_name)
+                if logs:
+                    print(logs, file=sys.stderr)
+                if (
+                    target
+                    and not new_session
+                    and not _is_retry
+                    and logs
+                    and target.should_retry_new_session(logs)
+                ):
+                    print(
+                        "Restarting with a new session.",
+                        file=sys.stderr,
+                    )
+                    runtime.rm(container_name)
+                    return _run_container(
+                        project_dir=project_dir,
+                        entrypoint=None,
+                        image_override=image_override,
+                        new_session=True,
+                        safe_mode=safe_mode,
+                        resume_mode=False,
+                        extra_args=extra_args,
+                        no_helpers=no_helpers,
+                        no_auto_auth=no_auto_auth,
+                        browser=browser,
+                        share_images=share_images,
+                        persistent=persistent,
+                        model_override=model_override,
+                        cli_env=cli_env,
+                        _is_retry=True,
+                    )
+                print(
+                    "Error: Container exited before session could attach.\n"
+                    "Check the logs above, or run 'kanibako system diagnose'.",
+                    file=sys.stderr,
+                )
+                return 1
+
+            # Attach to the new tmux session.  The container may not be
+            # fully ready for exec even though is_running() returned True
+            # (podman race: "container state improper").  Retry a few times.
+            _max_exec_attempts = 5
+            for _exec_attempt in range(1, _max_exec_attempts + 1):
+                rc = runtime.exec(
+                    container_name, ["tmux", "attach", "-t", "kanibako"]
+                )
+                if rc == 0:
+                    break
+                # Non-zero exit — check if the container is still alive.
+                if not runtime.is_running(container_name):
+                    # Container died; fall through to the log-showing code.
+                    break
+                # Container still running but exec failed (transient race).
+                if _exec_attempt < _max_exec_attempts:
+                    print(
+                        f"Warning: container not ready for exec "
+                        f"(attempt {_exec_attempt}/{_max_exec_attempts}), "
+                        f"retrying...",
+                        file=sys.stderr,
+                    )
+                    time.sleep(0.5)
+            # If agent exited, show container logs so the user can
+            # see why (tmux swallows output on exit).
+            if not runtime.is_running(container_name):
+                logs = _container_logs(runtime, container_name)
+                if logs:
+                    print(logs, file=sys.stderr)
+                    # Auto-retry as new session if the target says so
+                    # (once only — _is_retry prevents loops).
+                    if (
+                        target
+                        and not new_session
+                        and not _is_retry
+                        and target.should_retry_new_session(logs)
+                    ):
+                        print(
+                            "Restarting with a new session.",
+                            file=sys.stderr,
+                        )
+                        runtime.rm(container_name)
+                        return _run_container(
+                            project_dir=project_dir,
+                            entrypoint=None,
+                            image_override=image_override,
+                            new_session=True,
+                            safe_mode=safe_mode,
+                            resume_mode=False,
+                            extra_args=extra_args,
+                            no_helpers=no_helpers,
+                            no_auto_auth=no_auto_auth,
+                            browser=browser,
+                            share_images=share_images,
+                            persistent=persistent,
+                            model_override=model_override,
+                            cli_env=cli_env,
+                            _is_retry=True,
+                        )
+        else:
+            # Write back refreshed credentials via target (skip for distinct auth)
+            if target and proj.group_auth:
+                target.writeback_credentials(proj.shell_path)
+
+            # Hint when agent exits non-zero and --continue/--resume was used
+            if rc != 0 and is_agent_mode and not new_session:
+                print(
+                    "hint: if the agent exited because there was no conversation "
+                    "to continue, use 'kanibako start -N' to start fresh.",
+                    file=sys.stderr,
+                )
+
+        return rc
+
+    finally:
+        if lock_fd is not None:
+            fcntl.flock(lock_fd, fcntl.LOCK_UN)
+            lock_fd.close()
+
+
+def _build_config_env(
+    global_env_path,
+    crab_env: dict[str, str],
+    workset_env_path,
+    project_env_path,
+) -> dict[str, str]:
+    """Layer config-level env vars, low->high: system < crab < workset < box.
+
+    Shared between container launch (start) and ``box config --effective`` so
+    the resolved config-env matches exactly. Runtime-only layers (target state
+    env, per-run ``-e``) are applied by the caller ON TOP of this and are NOT
+    config, so they are excluded here.
+    """
+    from kanibako.shellenv import read_env_file
+    env: dict[str, str] = {}
+    env.update(read_env_file(global_env_path))   # system
+    env.update(crab_env)                         # crab
+    if workset_env_path is not None:
+        env.update(read_env_file(workset_env_path))  # workset
+    env.update(read_env_file(project_env_path))  # box (highest config level)
+    return env
+
+
+def _build_effective_state(
+    target,
+    crab_cfg,
+    project_toml,
+    *,
+    global_config_path,
+    workset_config_path=None,
+) -> dict[str, str]:
+    """Resolve effective crab-state via the settings precedence walk.
+
+    Walks four levels MOST-SPECIFIC-FIRST — box > workset > crab > system —
+    with the target's declared defaults as a FLOOR (the system level's declared
+    defaults).  Sources for each level's ``[crab]`` table:
+
+      * **box**     — ``[crab]`` in project.yaml
+      * **workset** — ``[crab]`` in the workset's config.yaml (if any)
+      * **crab**    — the crab config's own state dict
+      * **system**  — ``[crab]`` in the global kanibako.yaml
+      * **floor**   — target ``setting_descriptors()`` defaults
+
+    Explicit set values beat all declared defaults; the most-specific level
+    wins; an explicit ``""`` is terminal (no fall-through to the floor).
+    Undeclared keys set anywhere (e.g. ``start_mode``) are passed through.
+
+    Values are used verbatim — no ``@``-ref / ``$var`` / ``~`` expansion.
+
+    With no system/workset ``[crab]`` config (the common case) the walk reduces
+    to box > crab > floor, i.e. project override > crab state > target default —
+    identical to the prior two-source merge.
+    """
+    from kanibako.config import read_crab_settings
+    from kanibako.settings_resolve import (
+        LevelView,
+        ResolveCtx,
+        SettingsError,
+        _Unset,
+        resolve_value,
+    )
+
+    descriptors = target.setting_descriptors()
+    if not descriptors:
+        return dict(crab_cfg.state)
+
+    def _read(path) -> dict[str, str]:
+        if not path:
+            return {}
+        try:
+            if not path.exists():
+                return {}
+            return read_crab_settings(path)
+        except Exception:
+            return {}
+
+    # Gather per-level [crab] leaf values.
+    box_vals = _read(project_toml)
+    ws_vals = _read(workset_config_path)
+    crab_vals = dict(crab_cfg.state)
+    sys_vals = _read(global_config_path)
+    floor = {d.key: d.default for d in descriptors}
+
+    # Most-specific first; the floor is the system level's declared defaults.
+    levels = [
+        LevelView("box", box_vals),
+        LevelView("workset", ws_vals),
+        LevelView("crab", crab_vals),
+        LevelView("system", sys_vals, defaults=floor),
+    ]
+
+    keys = (
+        set(floor)
+        | set(box_vals)
+        | set(ws_vals)
+        | set(crab_vals)
+        | set(sys_vals)
+    )
+
+    ctx = ResolveCtx(
+        crab_name=target.name,
+        workset_name=None,
+        host_home=str(Path.home()),
+        xdg={},
+    )
+
+    def _no_lookup(ref, chain):
+        raise SettingsError(f"@-refs not supported in crab settings: {ref}")
+
+    effective: dict[str, str] = {}
+    for key in keys:
+        rv = resolve_value(key, levels=levels, ctx=ctx, lookup=_no_lookup)
+        if not isinstance(rv, _Unset):
+            effective[key] = rv.value
+
+    return effective
+
+
+def _apply_init_seeds(
+    *,
+    std,
+    proj,
+    crab_name: str,
+    target=None,
+    global_config_path,
+    project_toml,
+    workset_config_path,
+    crab_config_path,
+    logger,
+) -> None:
+    """Copy configured copy-once-at-init seeds into the new project's shell dir.
+
+    ADDITIVE: with no seed config and no target default seeds, copies nothing.
+    Resolves {scope}.path.seeded.* across the 4 levels (target.default_seeds()
+    as the crab level's declared defaults), translates each SeedPair's
+    guest_dest (/home/agent/X) to a host path under proj.shell_path, and copies
+    host_src -> that path once (dir -> copytree dirs_exist_ok; file -> copy2).
+    """
+    import shutil
+
+    from kanibako.config import read_seeds
+    from kanibako.settings_resolve import (
+        GUEST_HOME,
+        LevelView,
+        ResolveCtx,
+        SettingsError,
+    )
+    from kanibako.settings_seeds import resolve_seeds
+
+    default_seeds = target.default_seeds() if target is not None else {}
+
+    # Four precedence levels, most-specific first; crab carries the defaults.
+    levels = [
+        LevelView("box", read_seeds(project_toml)),
+        LevelView("workset", read_seeds(workset_config_path)),
+        LevelView("crab", read_seeds(crab_config_path), defaults=default_seeds),
+        LevelView("system", read_seeds(global_config_path)),
+    ]
+
+    workset_name = (
+        proj.group.name
+        if (proj.group is not None and not proj.group.is_default)
+        else None
+    )
+    ctx = ResolveCtx(
+        crab_name=crab_name,
+        workset_name=workset_name,
+        host_home=str(Path.home()),
+        xdg={"XDG_DATA_HOME": str(std.data_home)},
+    )
+
+    resolved_sys = {
+        "system.path.data": str(std.data_path),
+        "system.path.boxes": str(std.boxes),
+        "system.path.crabs": str(std.crabs),
+        "system.path.comms": str(std.comms),
+        "system.path.templates": str(std.templates),
+        "system.path.ws_hints": str(std.ws_hints),
+        "system.path.share_ro": str(std.share_ro),
+        "system.path.share_rw": str(std.share_rw),
+    }
+
+    def _lookup(ref, chain):
+        if ref in resolved_sys:
+            return resolved_sys[ref]
+        raise SettingsError(f"Unresolvable @-reference in seed value: {ref}")
+
+    seeds = resolve_seeds(levels=levels, ctx=ctx, lookup=_lookup)
+
+    for seed in seeds:
+        gd = seed.guest_dest.rstrip("/")
+        if gd == GUEST_HOME:
+            dest = proj.shell_path
+        elif gd.startswith(GUEST_HOME + "/"):
+            rel = gd[len(GUEST_HOME) + 1:]
+            dest = proj.shell_path / rel
+        else:
+            logger.warning(
+                "seed %s: guest_dest %r is outside %s; skipping",
+                seed.name, seed.guest_dest, GUEST_HOME,
+            )
+            continue
+        src = Path(seed.host_src)
+        if not src.exists():
+            logger.warning(
+                "seed %s: host_src %r does not exist; skipping",
+                seed.name, seed.host_src,
+            )
+            continue
+        if src.is_dir():
+            dest.mkdir(parents=True, exist_ok=True)
+            shutil.copytree(str(src), str(dest), dirs_exist_ok=True)
+        else:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(str(src), str(dest))
+
+
+def _build_share_mounts(
+    *,
+    std,
+    proj,
+    crab_name: str,
+    global_config_path,
+    project_toml,
+    workset_config_path,
+    crab_config_path,
+    target=None,
+) -> list:
+    """Resolve scoped-share config ({scope}.path.share_{ro,rw}.*) into Mounts.
+
+    ADDITIVE: with no share keys configured (and no target default shares),
+    returns []. Reads each level's set share keys from its config file; the
+    KEY's scope sets the source root + mode, the LEVEL where set decides
+    precedence (a box can suppress an inherited system share with a terminal "").
+
+    *target*'s ``default_shares()`` (if a target is given) are injected as the
+    CRAB level's *declared defaults*: they mount unless overridden/suppressed at
+    a more-specific level. After resolution, host source directories for any
+    read-write share are created best-effort (mirrors the old SHARED-mount
+    behavior) so podman does not stub them; a bad source never crashes launch.
+    """
+    from kanibako.config import read_shares
+    from kanibako.settings_resolve import LevelView, ResolveCtx, SettingsError
+    from kanibako.settings_shares import resolve_shares
+
+    default_shares = target.default_shares() if target is not None else {}
+
+    # Four precedence levels, most-specific first.
+    levels = [
+        LevelView("box", read_shares(project_toml)),
+        LevelView("workset", read_shares(workset_config_path)),
+        LevelView("crab", read_shares(crab_config_path), defaults=default_shares),
+        LevelView("system", read_shares(global_config_path)),
+    ]
+
+    # Source roots per scope group (concrete host paths → expand_expr verbatim).
+    crab_share_root = str(std.crabs / crab_name / "share")
+    scope_roots = {
+        "system.path.share_ro": str(std.share_ro),
+        "system.path.share_rw": str(std.share_rw),
+        "crab.path.share_ro": crab_share_root,
+        "crab.path.share_rw": crab_share_root,
+    }
+    if proj.group is not None and not proj.group.is_default:
+        ws_root = str(proj.group.root)
+        scope_roots["workset.path.share_ro"] = ws_root
+        scope_roots["workset.path.share_rw"] = ws_root
+    # box scope: arbitrary host path, NO root → omit (host_src used as-is).
+
+    workset_name = (
+        proj.group.name
+        if (proj.group is not None and not proj.group.is_default)
+        else None
+    )
+    ctx = ResolveCtx(
+        crab_name=crab_name,
+        workset_name=workset_name,
+        host_home=str(Path.home()),
+        xdg={"XDG_DATA_HOME": str(std.data_home)},
+    )
+
+    # Share VALUES may reference the resolved system path tier via @-refs.
+    resolved_sys = {
+        "system.path.data": str(std.data_path),
+        "system.path.boxes": str(std.boxes),
+        "system.path.crabs": str(std.crabs),
+        "system.path.comms": str(std.comms),
+        "system.path.templates": str(std.templates),
+        "system.path.ws_hints": str(std.ws_hints),
+        "system.path.share_ro": str(std.share_ro),
+        "system.path.share_rw": str(std.share_rw),
+    }
+
+    def _lookup(ref, chain):
+        if ref in resolved_sys:
+            return resolved_sys[ref]
+        raise SettingsError(f"Unresolvable @-reference in share value: {ref}")
+
+    mounts = resolve_shares(
+        levels=levels, ctx=ctx, lookup=_lookup, scope_roots=scope_roots
+    )
+    for m in mounts:
+        if m.options != "ro":  # rw share: create the host source dir if absent
+            try:
+                m.source.mkdir(parents=True, exist_ok=True)
+            except OSError:
+                pass  # best-effort; podman will surface a genuinely bad source
+    return mounts
+
+
+def _kanibako_mounts():
+    """Build bind mounts for the kanibako CLI inside containers.
+
+    Returns two mounts:
+      1. Package dir → /opt/kanibako/kanibako/ (ro)
+      2. Entry script → /home/agent/.local/bin/kanibako (ro)
+    """
+    import importlib.resources
+
+    import kanibako
+    from kanibako.targets.base import Mount
+
+    pkg_dir = Path(kanibako.__file__).parent
+
+    entry_ref = importlib.resources.files("kanibako.scripts").joinpath("kanibako-entry")
+    entry_path = Path(str(entry_ref))
+
+    return [
+        Mount(pkg_dir, "/opt/kanibako/kanibako", "ro"),
+        Mount(entry_path, "/home/agent/.local/bin/kanibako", "ro"),
+    ]
+
+
+def _build_resource_mounts(proj, target, agent_id: str):
+    """Build bind mounts from target resource_mappings() and per-project overrides.
+
+    - SHARED: mount shared dir over ``/home/agent/{config_dir}/{path}`` (read-write).
+    - SEEDED: on first init, copy from shared to project-local; then no extra mount.
+    - PROJECT: no extra mount (already in shell_path).
+    """
+    import shutil
+
+    from kanibako.config import read_resource_overrides
+    from kanibako.targets.base import Mount, ResourceScope
+
+    mappings = target.resource_mappings()
+    if not mappings:
+        return []
+
+    shared_base = proj.global_shared_path
+    if not shared_base:
+        return []
+
+    config_dir = target.config_dir_name
+
+    project_toml = proj.metadata_path / "project.yaml"
+    try:
+        overrides = read_resource_overrides(project_toml)
+    except Exception:
+        overrides = {}
+
+    mounts = []
+    for mapping in mappings:
+        # Apply per-project override if present.
+        scope_str = overrides.get(mapping.path)
+        scope = ResourceScope(scope_str) if scope_str else mapping.scope
+
+        if scope == ResourceScope.SHARED:
+            shared_path = shared_base / agent_id / mapping.path
+            if mapping.path.endswith("/"):
+                shared_path.mkdir(parents=True, exist_ok=True)
+            else:
+                # File resource: create parent dir and touch the file.
+                shared_path.parent.mkdir(parents=True, exist_ok=True)
+                if not shared_path.exists():
+                    shared_path.touch()
+            mounts.append(Mount(
+                source=shared_path,
+                destination=f"/home/agent/{config_dir}/{mapping.path}",
+                options="Z,U",
+            ))
+        elif scope == ResourceScope.SEEDED:
+            local = proj.shell_path / config_dir / mapping.path
+            if not local.exists():
+                src = shared_base / agent_id / mapping.path
+                if src.exists():
+                    if src.is_dir():
+                        shutil.copytree(str(src), str(local))
+                    else:
+                        local.parent.mkdir(parents=True, exist_ok=True)
+                        shutil.copy2(str(src), str(local))
+        # PROJECT scope: no extra mount needed.
+
+    return mounts
+
+
+# AF_UNIX sun_path limit (108 on Linux, 104 on macOS).
+_UNIX_SOCKET_PATH_LIMIT = 104
+
+
+def _container_logs(runtime: ContainerRuntime, name: str) -> str:
+    """Return recent container logs, or empty string on failure."""
+    result = subprocess.run(
+        [runtime.cmd, "logs", "--tail", "50", name],
+        capture_output=True, text=True,
+    )
+    return (result.stdout + result.stderr).strip() if result.returncode == 0 else ""
+
+
+def _sync_binary_symlink(shell_path, install, mounts, log) -> None:
+    """Update a stale binary symlink in the shell dir to match the detected version.
+
+    When ``binary_mounts()`` returns both an install-dir mount and a binary
+    mount, podman follows the destination symlink, landing the binary mount
+    inside the install-dir subtree where the directory mount shadows it.
+    Keeping the symlink current ensures the install-dir mount serves the
+    correct binary version.
+    """
+    link = shell_path / ".local" / "bin" / install.name
+    if not link.is_symlink():
+        return
+    # Find the install-dir mount destination (e.g. /home/agent/.local/share/claude).
+    install_dir_dest = None
+    for m in mounts:
+        if m.source == install.install_dir:
+            install_dir_dest = m.destination
+            break
+    if not install_dir_dest:
+        return  # No install-dir mount; no shadowing risk.
+    try:
+        relative = install.binary.relative_to(install.install_dir)
+    except ValueError:
+        return
+    expected = str(Path(install_dir_dest) / relative)
+    current = os.readlink(str(link))
+    if current == expected:
+        return
+    link.unlink()
+    link.symlink_to(expected)
+    log.info("Updated %s symlink: %s → %s", install.name, current, expected)
+
+
+def _validate_mounts(mounts: list, logger) -> None:
+    """Warn about mount sources that don't exist on the host.
+
+    Called before ``runtime.run()`` to catch issues early with a clear
+    message instead of a cryptic Podman error.
+    """
+    for mount in mounts:
+        src = mount.source
+        if not src.exists():
+            logger.warning("Mount source missing: %s → %s", src, mount.destination)
+            print(
+                f"Warning: mount source does not exist: {src}",
+                file=sys.stderr,
+            )
+
+
+_ROTATE_MAX_BYTES = 1_048_576  # 1 MiB
+
+
+def _rotate_file(path: Path) -> None:
+    """Rotate *path* if it exceeds the size threshold."""
+    try:
+        size = path.stat().st_size
+        if not isinstance(size, int) or size < _ROTATE_MAX_BYTES:
+            return
+    except (OSError, TypeError):
+        return
+    backup = path.with_suffix(path.suffix + ".1")
+    path.rename(backup)
+    path.touch()
+
+
+def validate_socket_path(socket_path: Path) -> None:
+    """Raise ValueError if *socket_path* exceeds the AF_UNIX length limit."""
+    path_len = len(str(socket_path))
+    if path_len >= _UNIX_SOCKET_PATH_LIMIT:
+        raise ValueError(
+            f"Socket path too long ({path_len} >= {_UNIX_SOCKET_PATH_LIMIT}): "
+            f"{socket_path}"
+        )