painapple-code 1.0.2__tar.gz → 1.0.4__tar.gz

{painapple_code-1.0.2/src/painapple_code.egg-info → painapple_code-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: painapple-code
-Version: 1.0.2
+Version: 1.0.4
 Summary: Self-hosted remote UI for Claude Code that journals every turn - background AI summaries become shadow-git commits and a queryable DuckDB history
 Author-email: Michał Booth-Wrotkowski <michal@boothw.com>
 License-Expression: AGPL-3.0-or-later

{painapple_code-1.0.2 → painapple_code-1.0.4}/docs-site/getting-started/install-docker.md

@@ -35,6 +35,9 @@ Docker and Podman are auto-detected (pick one — or a custom binary path — in
 ## Option B — raw `docker run` (one-liner, no clone needed)
 
 ```bash
+# Podman won't create a missing bind-mount source (Docker will) — make it first:
+mkdir -p "$HOME/.painapple-code/.claude"
+
 docker run -d --name painapple-code \
     -p 127.0.0.1:8765:8765 \
     -v "$PWD:/workspace" \
@@ -44,10 +47,27 @@ docker run -d --name painapple-code \
 # Bootstrap URL — the container hides credentials from its own logs, so
 # read the derived API token from its config instead (?tkn= links never
 # carry the password):
-echo "http://localhost:8765/?tkn=$(docker exec painapple-code \
+echo "https://localhost:8765/?tkn=$(docker exec painapple-code \
     awk '/^api_token:/ {print $2}' /home/app/.config/painapple-code/config.yaml)"
 ```
 
+!!! note "Why `https://` here, but `http://` with `painapple --in-docker`"
+
+    The server inside the container always binds `0.0.0.0` — it has to, or
+    the published port would have nothing to forward to. So it cannot tell
+    whether you published on loopback or on the LAN, and `--tls auto`
+    resolves to **on**: you get HTTPS with a self-signed certificate and a
+    one-time browser warning. That is the safe default for a command whose
+    reachability is unknown.
+
+    `painapple --in-docker` knows the publish interface, so it resolves TLS
+    on the host side and turns it off for a loopback-only run.
+
+    You *can* append `--tls off` to the `docker run` command for plain HTTP
+    on a loopback publish — but then remember to remove it if you ever widen
+    `-p 127.0.0.1:…` to another interface, or the token and chat traffic go
+    out unencrypted.
+
 **Image tags:**
 
 | Tag | Meaning |
@@ -84,7 +104,7 @@ To layer your own tooling on top of the base image:
 ./painapple-docker.sh build --dockerfile ~/my-project/Dockerfile
 ```
 
-Open `http://localhost:8765/` in a browser. The first run generates an auth password — the container keeps it out of `docker logs` (they persist), so reveal the bootstrap URL with `painapple password` (pip CLI) or the `docker exec … awk` one-liner above, and open it once; the cookie keeps you logged in. See [First run & login](first-run.md).
+Open `https://localhost:8765/` in a browser (self-signed certificate — accept the one-time warning). The first run generates an auth password — the container keeps it out of `docker logs` (they persist), so reveal the bootstrap URL with `painapple password` (pip CLI) or the `docker exec … awk` one-liner above, and open it once; the cookie keeps you logged in. See [First run & login](first-run.md).
 
 ## Manual Compose / Podman (no wrapper)
 

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.2'
-__version_tuple__ = version_tuple = (1, 0, 2)
+__version__ = version = '1.0.4'
+__version_tuple__ = version_tuple = (1, 0, 4)
 
-__commit_id__ = commit_id = 'ge157c77'
+__commit_id__ = commit_id = 'g682c211'

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/cli/deploy/container.py

@@ -14,6 +14,7 @@ import threading
 import time
 from pathlib import Path
 
+from painapple_code import __version__
 from painapple_code.cli.netinfo import detect_local_ips
 from painapple_code.cli.ui import (
     BOLD, DIM, GREEN, RESET, die, err, info, ok, print_credentials, say, warn,
@@ -136,6 +137,70 @@ def print_bootstrap_url(cfg, pw, profile=None, raw_tty=False, token=None):
     sys.stdout.flush()
 
 
+def suggest_profile_name(workspace):
+    """A profile name suggestion derived from the workspace dir, or ''.
+
+    Sanitized to profiles.valid_name()'s alphabet so the printed command
+    actually runs, and skipped when the name is already taken (a hint
+    that would reconfigure someone's existing deployment is worse than
+    no hint) or reserved ('default').
+    """
+    import re
+    from painapple_code.cli import profiles
+
+    base = Path(workspace or "").name.lower()
+    # Strip separators from BOTH ends, and again after truncation — a cut
+    # at 32 chars can leave a trailing dash of its own.
+    name = re.sub(r"[^a-z0-9._-]", "-", base).strip("-._")[:32].strip("-._")
+    if not name or not profiles.valid_name(name):
+        return ""
+    return "" if name in profiles.list_profiles() else name
+
+
+# ──── image version ──────────────────────────────────────────────────────
+
+def _release_tuple(version):
+    """(major, minor, patch) from a version string, pre/dev/local suffixes
+    dropped — "1.0.0rc1" → (1, 0, 0). None when it can't be parsed."""
+    if not version:
+        return None
+    parts = []
+    for chunk in version.lstrip("vV").split("+")[0].split(".")[:3]:
+        digits = ""
+        for ch in chunk:
+            if not ch.isdigit():
+                break
+            digits += ch
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts) if len(parts) == 3 else None
+
+
+def _is_prerelease(version):
+    core = (version or "").lstrip("vV").split("+")[0]
+    return any(marker in core for marker in ("rc", "a", "b", "dev"))
+
+
+def _image_is_stale(img_version, cli=None):
+    """Is the local image an older build than this CLI?
+
+    Only a CONFIDENT comparison warns — an unparseable or unlabeled
+    version stays quiet rather than crying wolf on every start. Equal
+    releases still count as stale when the image is a pre-release and
+    the CLI is not (an rc image under a released CLI). ``cli`` overrides
+    the running version (tests).
+    """
+    cli_version = cli or __version__
+    img, cli_rel = _release_tuple(img_version), _release_tuple(cli_version)
+    if img is None or cli_rel is None:
+        return False
+    if img < cli_rel:
+        return True
+    return (img == cli_rel and _is_prerelease(img_version)
+            and not _is_prerelease(cli_version))
+
+
 # ──── pull ────────────────────────────────────────────────────────────────
 
 def pull_image(cfg, rt, tag="latest", source=None):
@@ -400,6 +465,13 @@ def build_run_argv(cfg, rt, detach, profile=None, ident=None):
     argv += [cfg.image, "python", "-m", "painapple_code",
              "--host", "0.0.0.0", "--port", "8765",
              "--workspace", "/workspace"]
+    # Parent mode mounts the dir AT /workspace. If it's a git checkout
+    # (forced --no-project, or a hand-edited profile), the container's own
+    # serve auto-detect would see /workspace/.git and flip to single-project
+    # mode — pin it to wrapper. Only appended when needed: older images
+    # don't know the flag and would crash-loop on it.
+    if cfg.workspace_mode == "parent" and (Path(cfg.workspace) / ".git").exists():
+        argv += ["--no-project"]
     if cfg.instance_name:
         argv += ["--instance-name", cfg.instance_name]
     if cfg.accent:
@@ -530,13 +602,46 @@ def run_container(cfg, detach, profile=None):
     # inside the runtime with a message that never mentions painapple
     # ("pasta failed with exit code 1…") — and, being on stderr, it lands
     # out of order among our own lines. Check it ourselves, first.
-    from painapple_code.cli.netinfo import port_holder, port_taken
+    from painapple_code.cli.netinfo import first_free_port, port_holder, port_taken
     reason = port_taken(cfg.listen_host, cfg.port)
     if reason:
+        if getattr(reason, "bad_host", False):
+            err(f"Cannot bind {cfg.listen_host}:{cfg.port} — {reason}")
+            say(f"  {DIM}Fix the bind host:  {hint('setup', profile)}{RESET}")
+            return 1
         holder = port_holder(cfg.port)
         err(f"Port {cfg.port} on {cfg.listen_host} is already in use — {reason}"
             + (f" (held by {holder})" if holder else ""))
-        say(f"  {DIM}Pick another port:  {hint('setup', profile)}{RESET}")
+        # Lead with the one-off retry, not the wizard: the user wants THIS
+        # launch to go, and `setup` rewrites global/profile defaults for
+        # every future start. A concrete free port beats "pick another".
+        #
+        # A named profile gets the whole command (self-contained). The
+        # ad-hoc sandbox gets the FLAG to append instead — printing
+        # `painapple --in-docker --port N` would quietly drop the rest of
+        # what the user typed (--project, --workspace, --accent …), and a
+        # copied hint that changes behavior is worse than no hint.
+        free = first_free_port(cfg.listen_host, cfg.port + 1)
+        port_arg = f"--port {free}" if free else "--port N"
+        if profile:
+            say(f"  {DIM}Retry on another port:  "
+                f"{hint('start', profile)} {port_arg}{RESET}")
+            say(f"  {DIM}Or change the saved default:  "
+                f"{hint('setup', profile)}{RESET}")
+        else:
+            say(f"  {DIM}Retry on another port:  add {port_arg} to your "
+                f"command{RESET}")
+            # A named profile is the right PERMANENT answer for a
+            # repeat launch that collides: it gets its own port,
+            # container, volumes and config. Unnamed `setup` would
+            # instead move the GLOBAL default under every future
+            # launch — rarely what someone juggling two instances wants,
+            # so it goes last.
+            suggested = suggest_profile_name(cfg.workspace)
+            say(f"  {DIM}Or save it as its own deployment:  "
+                f"painapple setup {suggested or 'NAME'}{RESET}")
+            say(f"  {DIM}Or change the global default:  "
+                f"{hint('setup', profile)}{RESET}")
         return 1
 
     # Bind-mount dirs must exist so docker doesn't create them as root.
@@ -563,6 +668,20 @@ def run_container(cfg, detach, profile=None):
     say(f"  Config    : {DIM}{cfg.config_volume}{RESET} ({'bind' if cfg.config_is_bind() else 'volume'}) → /home/app/.config/painapple-code")
     say(f"  Listen on : {DIM}{cfg.listen_host}:{cfg.port}{RESET} → container :8765 "
         f"{DIM}(host bind — {listen_scope(cfg)}){RESET}")
+    # Name the image's version, always — the same reason `pull` does it.
+    # `run` uses whatever image is already local and never re-pulls, so a
+    # box that pulled once during the rc series keeps booting that build
+    # forever while the host CLI reports a current version. Unlabeled
+    # (pre-label) images say so rather than printing nothing.
+    img_version = rt.label(cfg.image, "org.opencontainers.image.version")
+    say(f"  Image     : {DIM}{cfg.image}{RESET}"
+        + (f"  {DIM}(version {img_version}){RESET}" if img_version
+           else f"  {DIM}(version unknown — predates the label){RESET}"))
+    if _image_is_stale(img_version):
+        warn(f"The local image is {img_version or 'older than this CLI'} but "
+             f"this CLI is {__version__} — flags and endpoints added since "
+             f"then will be missing inside the container. Refresh it with: "
+             f"{hint('pull', profile)}")
     if cfg.instance_name:
         say(f"  Instance  : {DIM}{cfg.instance_name}{RESET}")
     if cfg.accent:

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/cli/deploy/launch.py

@@ -58,13 +58,36 @@ def _apply_serve_flags(cfg, argv):
     return False
 
 
-def _auto_workspace_mode(cfg):
-    """Zero-config mode pick: a git checkout → 'project', anything else
+def _forced_project_flag(argv):
+    """--project / --no-project from raw argv: True / False / None (auto).
+    Last occurrence wins, matching argparse BooleanOptionalAction."""
+    forced = None
+    for tok in argv:
+        if tok == "--project":
+            forced = True
+        elif tok == "--no-project":
+            forced = False
+    return forced
+
+
+def _auto_workspace_mode(cfg, argv=()):
+    """Mode pick for the mount layer. --project/--no-project force it;
+    otherwise zero-config: a git checkout → 'project', anything else
     → 'parent' — matching "I'm in a repo" vs "I opened a folder of
-    repos" without asking. (.git can be a dir or a worktree file.)"""
+    repos" without asking. (.git can be a dir or a worktree file.)
+    The serve flag itself is NOT forwarded into the container — project
+    mode is realized by the one-level-down mount (container_mount());
+    build_run_argv adds --no-project only where the container's own
+    auto-detect would wrongly flip a parent-mode git mount."""
     ws = Path(cfg.workspace or ".")
-    mode = "project" if (ws / ".git").exists() else "parent"
-    reason = "found .git" if mode == "project" else "no .git"
+    forced = _forced_project_flag(argv)
+    if forced is True:
+        mode, reason = "project", "forced by --project"
+    elif forced is False:
+        mode, reason = "parent", "forced by --no-project"
+    else:
+        mode = "project" if (ws / ".git").exists() else "parent"
+        reason = "found .git" if mode == "project" else "no .git"
     cfg.workspace_mode = mode
     info(f"{ws} → {mode} mode {DIM}({reason}){RESET}")
 
@@ -100,7 +123,7 @@ def adhoc_settings(argv):
     explicit_ws = _apply_serve_flags(cfg, argv)
     if not explicit_ws:
         cfg.workspace = str(Path.cwd())
-    _auto_workspace_mode(cfg)
+    _auto_workspace_mode(cfg, argv)
     return cfg
 
 
@@ -146,9 +169,9 @@ def profile_settings(prof, argv=()):
     explicit_ws = _apply_serve_flags(cfg, list(argv))
     if not cfg.workspace and cfg.workspace_mode != "multi":
         cfg.workspace = str(Path.cwd())
-        _auto_workspace_mode(cfg)
+        _auto_workspace_mode(cfg, argv)
     elif explicit_ws and prof.is_docker is False:
-        _auto_workspace_mode(cfg)
+        _auto_workspace_mode(cfg, argv)
     return cfg
 
 

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/cli/lifecycle_cmd.py

@@ -280,12 +280,25 @@ def _start(target, extra):
     # Bind test, not a scan of our own process table — a port held by
     # ANYTHING (another painapple, a stray dev server) must fail here,
     # loudly, rather than inside a detached child nobody is watching.
-    from painapple_code.cli.netinfo import port_holder, port_taken
+    from painapple_code.cli.netinfo import first_free_port, port_holder, port_taken
     reason = port_taken(host, port)
     if reason:
+        if getattr(reason, "bad_host", False):
+            err(f"Cannot bind {host}:{port} — {reason}. Check the host address.")
+            return 1
         holder = port_holder(port)
         err(f"Port {port} on {host} is already in use — {reason}"
             + (f" (held by {holder})" if holder else ""))
+        # Same actionable exit as the container path: a concrete free port
+        # to retry on, then the wizard for a permanent change.
+        free = first_free_port(host, port + 1)
+        port_arg = f"--port {free}" if free else "--port N"
+        label = target.get("label") or ""
+        name = label if label and label != "default" else ""
+        say(f"  {DIM}Retry on another port:  "
+            f"painapple start{f' {name}' if name else ''} {port_arg}{RESET}")
+        say(f"  {DIM}Or change the saved default:  "
+            f"painapple setup{f' {name}' if name else ''}{RESET}")
         return 1
 
     return _spawn_and_wait(

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/cli/netinfo.py

@@ -37,18 +37,36 @@ def detect_local_ips():
     return results
 
 
+class BindFailure(str):
+    """Reason string from port_taken(). `bad_host` is True when the HOST is
+    the problem (unresolvable, or not an address on this machine —
+    EADDRNOTAVAIL) rather than the port being held by another process, so
+    callers can skip the "already in use" framing and the holder lookup."""
+    bad_host = False
+
+
+def _bind_failure(reason, bad_host=False):
+    out = BindFailure(reason)
+    out.bad_host = bad_host
+    return out
+
+
 def port_taken(host, port):
     """Reason string when `host:port` can't be bound, '' when it's free.
 
     A plain bind test — catches ANY holder, unlike a scan of painapple's
     own process table. Used by the server's own pre-flight and by
     `painapple start` so the failure is reported before a detached child
-    inherits it. Unresolvable host counts as taken (with the reason)."""
+    inherits it. Non-empty returns are BindFailure: `bad_host` marks a
+    wrong bind address (unresolvable / not local) as opposed to a port
+    genuinely held by another process."""
+    import errno
     import socket
     try:
         infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
     except socket.gaierror as e:
-        return f"cannot resolve host {host!r} ({e})"
+        return _bind_failure(f"cannot resolve host {host!r} ({e})",
+                             bad_host=True)
     family, socktype, proto, _canon, sockaddr = infos[0]
     with socket.socket(family, socktype, proto) as sock:
         # SO_REUSEADDR means opposite things on the two platforms. On POSIX
@@ -65,10 +83,33 @@ def port_taken(host, port):
         try:
             sock.bind(sockaddr)
         except OSError as e:
-            return e.strerror or str(e)
+            msg = e.strerror or str(e)
+            # EADDRNOTAVAIL ("Cannot assign requested address") is not a
+            # port conflict — the IP isn't assigned to any interface here.
+            # Framing it as "already in use" sent users hunting for a
+            # holder that doesn't exist (winsock code on Windows differs).
+            if e.errno in (errno.EADDRNOTAVAIL,
+                           getattr(errno, "WSAEADDRNOTAVAIL", None)):
+                return _bind_failure(
+                    f"{msg} — {host!r} is not an address on this machine",
+                    bad_host=True)
+            return _bind_failure(msg)
     return ""
 
 
+def first_free_port(host, start, span=40):
+    """First bindable port at or above ``start``, or None if the whole
+    span is taken. Used to turn "port busy" into an actionable
+    "--port N" suggestion instead of sending the user to a wizard."""
+    for candidate in range(start, min(start + span, 65536)):
+        reason = port_taken(host, candidate)
+        if getattr(reason, "bad_host", False):
+            return None          # host is the problem — no port helps
+        if not reason:
+            return candidate
+    return None
+
+
 def _listener_pid(port):
     """PID of whatever holds the listening socket on `port`, or None.
     Never raises — every caller is decoration."""

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/cli/serve_args.py

@@ -85,6 +85,12 @@ def build_parser():
                            "its own directory. This anchors the file explorer and "
                            "the welcome screen's project suggestions. Mapped to "
                            "/workspace inside Docker. (--cwd is an alias)")
+    core.add_argument("--project", dest="project",
+                      action=argparse.BooleanOptionalAction, default=None,
+                      help="Treat the workspace as ONE project (the welcome screen "
+                           "offers it as a single entry) instead of a folder of "
+                           "projects. Default: auto-detect by a top-level .git; "
+                           "--no-project disables the auto-detect.")
     core.add_argument("--instance-name", default=None,
                       help="Instance label for PWA icon and UI (e.g., DEV, STABLE)")
     core.add_argument("--accent", default=None,

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/cli/setup_cmd.py

@@ -74,8 +74,16 @@ def step_network(cfg, back, n=1):
         warn(f"Server will be reachable on {cfg['host']} — anyone with the "
              "password can connect.")
 
-    port = ui.int_input("Port to bind", default=cfg.get("port") or 8765,
-                        lo=1, hi=65535)
+    # A profile the user has already configured keeps its own port. A NEW
+    # one defaults to the first FREE port at/above 8765 rather than 8765
+    # flat: the common reason to create a second deployment is that
+    # something already holds the default, and offering the taken port
+    # walks straight back into the collision that sent them here.
+    default_port = cfg.get("port")
+    if not default_port:
+        from painapple_code.cli.netinfo import first_free_port
+        default_port = first_free_port(cfg.get("host") or "127.0.0.1", 8765) or 8765
+    port = ui.int_input("Port to bind", default=default_port, lo=1, hi=65535)
     if port is BACK:
         return step_network(cfg, back, n)
     cfg["port"] = port
@@ -568,7 +576,11 @@ def _profile_setup(name):
         docker_only(lambda back: step_storage(cfg, back)),
     ]
 
-    # Warn about port collisions with other profiles (advisory only).
+    # Warn about port collisions (advisory only) — against other
+    # profiles AND against whatever is listening right now. The
+    # profile-only check missed the case that actually bites: the root
+    # deployment (or any unmanaged process) already holding the port,
+    # which is configured nowhere this loop can see.
     def _port_clash():
         for other in profiles.list_profiles():
             if other == name:
@@ -578,6 +590,14 @@ def _profile_setup(name):
                 warn(f"Port {cfg.get('port')} is also configured on profile "
                      f"'{other}' — they can't run at the same time.")
                 return
+        from painapple_code.cli.netinfo import port_holder, port_taken
+        host = cfg.get("host") or "127.0.0.1"
+        reason = port_taken(host, cfg.get("port"))
+        if reason and not getattr(reason, "bad_host", False):
+            holder = port_holder(cfg.get("port"))
+            warn(f"Port {cfg.get('port')} on {host} is in use right now"
+                 + (f" (held by {holder})" if holder else "")
+                 + " — this profile won't start until that frees up.")
 
     try:
         i = 0

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/paths.py

@@ -494,6 +494,30 @@ def _looks_like_project(child: Path) -> bool:
     return False
 
 
+def resolve_workspace_is_project(workspace: str, flag: Optional[bool]) -> tuple[bool, str]:
+    """Decide whether the workspace IS one project (vs a wrapper dir of projects).
+
+    flag: True/False = forced by --project/--no-project, None = auto-detect.
+    Auto-detect keys on a top-level ``.git`` ONLY (dir for a normal repo,
+    file for a git worktree) — the same zero-config pick the Docker launch
+    path uses (cli/deploy/launch.py), deliberately NOT the broader
+    ``_looks_like_project`` manifest list: a wrapper dir with a stray
+    requirements.txt must not silently flip modes.
+
+    Returns:
+        (is_project, reason) — reason is human-readable for the startup log.
+    """
+    if flag is True:
+        return True, "forced by --project"
+    if flag is False:
+        return False, "forced by --no-project"
+    try:
+        has_git = (Path(workspace).expanduser() / ".git").exists()
+    except OSError:
+        has_git = False
+    return (True, "found .git") if has_git else (False, "no .git")
+
+
 def list_workspace_dirs(root: str, exclude_paths: Optional[list[str]] = None,
                         limit: int = 100) -> list[dict]:
     """List immediate sub-directories of a workspace root, excluding ones

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/routes/api_session_welcome.py

@@ -93,18 +93,50 @@ async def get_welcome_projects(request: Request):
     enriched.sort(key=lambda x: x["name"].lower())
 
     workspace_root = getattr(request.app.state, "workspace_root", None)
+    is_project = bool(getattr(request.app.state, "workspace_is_project", False))
     workspace_dirs: list[dict] = []
-    if workspace_root:
+    if workspace_root and is_project:
+        # The workspace IS one project — never list its internals
+        # (src/, node_modules/, …). Offer the root itself as the single
+        # "unvisited" chip until the first session tracks it as a project.
+        workspace_dirs = _root_as_workspace_entry(workspace_root, projects)
+    elif workspace_root:
         exclude = [p["path"] for p in projects]
         workspace_dirs = list_workspace_dirs(workspace_root, exclude_paths=exclude)
 
     return {
         "projects": enriched,
         "workspace_root": workspace_root,
+        "workspace_is_project": is_project,
         "workspace_dirs": workspace_dirs,
     }
 
 
+def _root_as_workspace_entry(workspace_root: str, projects: list[dict]) -> list[dict]:
+    """Project-mode chip list: the workspace root itself, in the same shape
+    `list_workspace_dirs` emits — or [] once it's already a tracked project
+    (it then appears in `projects` instead)."""
+    root = Path(workspace_root)
+    tracked = set()
+    for p in projects:
+        try:
+            tracked.add(str(Path(p["path"]).expanduser().resolve()))
+        except (OSError, RuntimeError):
+            continue
+    if str(root) in tracked:
+        return []
+    try:
+        mtime = root.stat().st_mtime
+    except OSError:
+        return []
+    return [{
+        "path": str(root),
+        "name": root.name,
+        "mtime": mtime,
+        "looks_like_project": True,
+    }]
+
+
 @router.get("/api/welcome/projects/sessions")
 async def get_project_sessions(path: str, limit: int = 15):
     """Recent sessions for a specific project — drives the quick-switcher drill-in.

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/server.py

@@ -1794,6 +1794,24 @@ def _preflight_port(host: str, port: int) -> None:
     if not reason:
         return
 
+    if getattr(reason, "bad_host", False):
+        # The HOST is wrong (unresolvable / not a local address), not the
+        # port — the "already in use" box below would send the user cycling
+        # through ports that were never the problem.
+        print(f"""
+╔══════════════════════════════════════════════════════════════╗
+║           pAInapple Code Server — cannot start
+╠══════════════════════════════════════════════════════════════╣
+║  Cannot bind {host}:{port} — the bind host is wrong.
+║  {reason}
+║
+║  Try:  {'painapple --host 0.0.0.0':<27} (listen on all interfaces)
+║        {'painapple --host 127.0.0.1':<27} (this machine only)
+╚══════════════════════════════════════════════════════════════╝
+""", file=sys.__stderr__ or sys.stdout)
+        logger.error(f"Cannot bind {host}:{port} — {reason}; not starting")
+        sys.exit(1)
+
     holder = port_holder(port)
     port_flag = f"painapple --port {port + 1}"
     print(f"""
@@ -2039,16 +2057,23 @@ def main(argv=None):
     app.state.agents = agents
     app.state.workspace = args.workspace
 
-    # --workspace IS the root: the dir that holds the project subdirs, not
-    # one project. Sessions pick their own cwd from the welcome screen and
-    # files/git/terminal follow THAT, so this only anchors discovery (the
-    # welcome "Unvisited" chips, the file-explorer browse root) and supplies
-    # a fallback cwd for sessions created without one. Stored as absolute
-    # string (or None) for route modules to read.
+    # --workspace anchors discovery (the welcome "Unvisited" chips, the
+    # file-explorer browse root) and supplies a fallback cwd for sessions
+    # created without one — sessions pick their own cwd from the welcome
+    # screen and files/git/terminal follow THAT. Two modes: a WRAPPER dir
+    # holding project subdirs (welcome lists them), or ONE project
+    # (welcome offers just the workspace itself — never its internals like
+    # src/ or node_modules/). Mode from --project/--no-project, else
+    # auto-detected by a top-level .git (same pick as Docker's launch
+    # path, which sidesteps this via the one-level-down mount). Stored as
+    # absolute string (or None) for route modules to read.
     try:
         app.state.workspace_root = str(Path(args.workspace).expanduser().resolve())
     except (OSError, RuntimeError):
         app.state.workspace_root = None
+    is_project, project_reason = paths.resolve_workspace_is_project(
+        args.workspace, args.project)
+    app.state.workspace_is_project = is_project
 
     # Load config file and populate auth state (fails open if the directory
     # can't be written — intentional: we want a noisy permissions error).
@@ -2116,6 +2141,13 @@ def main(argv=None):
                 "Use --tls=auto (default) unless you have a reason."
             )
 
+    # Project-mode annotation on the Workspace banner line; a fuller notice
+    # prints below the box ONLY when the mode was auto-detected (explicit
+    # --project/--no-project users already know what they asked for).
+    workspace_mode = ""
+    if app.state.workspace_is_project:
+        workspace_mode = f"  (single project: {project_reason})"
+
     instance_line = ""
     if instance_config.get("name"):
         instance_line = f"\n║  Instance:       {instance_config['name']} (accent: {instance_config.get('accent', 'default')})"
@@ -2164,11 +2196,16 @@ def main(argv=None):
 ╠══════════════════════════════════════════════════════════════╣
 ║  WebSocket:      {ws_scheme}://{args.host}:{args.port}/chat
 ║  Files API:      {scheme}://{args.host}:{args.port}/api/files
-║  Workspace:      {args.workspace}{instance_line}{shadow_db_line}{log_dir_line}{state_suffix_line}
+║  Workspace:      {args.workspace}{workspace_mode}{instance_line}{shadow_db_line}{log_dir_line}{state_suffix_line}
 ║  Auth File:      {app.state.auth_config_file}{tls_line}{auth_lines}
 ╚══════════════════════════════════════════════════════════════╝
     """)
 
+    if args.project is None and app.state.workspace_is_project:
+        print(f"{DIM}Workspace looks like a project (found .git) — the welcome "
+              f"screen shows it as one project, not its subfolders. Pass "
+              f"--no-project to treat it as a folder of projects.{_ANSI_RESET}")
+
     # Trust X-Forwarded-* only from loopback by default (a reverse proxy on
     # the same host). A remote proxy sets FORWARDED_ALLOW_IPS explicitly. The
     # old "*" let ANY direct client spoof X-Forwarded-Proto and flip the

{painapple_code-1.0.2 → painapple_code-1.0.4}/src/painapple_code/static/css/67-file-preview-widget.css

@@ -1031,6 +1031,23 @@
     transition: all 0.15s;
 }
 
+/* Icon buttons in the panzoom toolbar (e.g. annotate): the inline SVG ships
+   only a viewBox, so without explicit sizing it renders at the 300×150
+   replaced-element default and the icon clips out of the button entirely. */
+.panzoom-annotate-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--layout-btn-sm);
+    padding: 0;
+    flex-shrink: 0;
+}
+
+.panzoom-annotate-btn svg {
+    width: 14px;
+    height: 14px;
+}
+
 .panzoom-ctrl-btn:hover, .panzoom-ctrl-btn:active {
     background: var(--surface-hover, #30363d);
     color: var(--text-primary, #e6edf3);