fix(ssh): bootstrap-aware first-run wait + strict --ssh value classification

First run: the host gave up after a flat 20s while the container was still
bootstrapping (config clone, volume chown, provider setup all run before
sshd starts in start.sh) — a false 'SSH server not ready' that a retry
'solved'. Now lpb detects first run (no <state>/.initialized, the
container's /home/lpb/.pi/.initialized marker), waits up to 300s with
progress notes (30s warm), and on exhaustion hints at 'lpb --logs'
(sshd starts automatically once the bootstrap completes) or a restart.

--ssh value: argparse consumed the next arg as PUBKEY, so
'lpb --dev --ssh /path/to/project' silently used the path as an inline key
(no error, no key prompt, project dir lost). Values are now classified:
inline key (ssh-*/ecdsa-*/sk-* + base64) | existing .pub file (content
validated, ~ expanded) | existing directory (becomes the project dir and
the profile-key menu still shows) | anything else is an explicit error.
An explicit positional project still wins.

Docs (README, doc/lpb-cli.md, usage text) + 6 new ssh tests; 93/93 pass.

Author: localpibox

README.md

@@ -126,7 +126,7 @@ CI tags images per pipeline: `:0.0.x-lpb[-dev]-cli/web` (versioned),
 | `lpb /path` | Pi CLI session (foreground); no path → last project or `~` |
 | `lpb --web /path` | VSCodium (background); `--port 8080` to change the port |
 | `lpb --shell /path` | Interactive bash inside the container |
-| `lpb --ssh [pubkey\|path] /path` | sshd server in the container for remote login (key auto-detected from `~/.ssh` when omitted) |
+| `lpb --ssh [pubkey\|path] [project]` | sshd server in the container for remote login (key auto-detected from `~/.ssh` when omitted) |
 | `lpb --ssh --ssh-password [pw]` | SSH password login (random if omitted, shown once; can combine with a key) |
 | `lpb --stop` / `--remove` / `--logs` | Stop / stop+remove+state cleanup / stream logs |
 | `lpb --update` | Self-update launcher + pull latest image for the selected pipeline |

doc/lpb-cli.md

@@ -28,7 +28,7 @@ Installs (no sudo required) into `~/.local/bin`:
 | `lpb [/path/to/project]` | Start a **Pi CLI session** (foreground). No path → last project, or `~` if none yet |
 | `lpb --web [/path]` | Start **VSCodium** (background), prints the connection URL |
 | `lpb --shell [/path]` | Interactive bash shell inside the container |
-| `lpb --ssh [pubkey\|path] [/path]` | Start an sshd server in the container for remote login (key auto-detected from `~/.ssh` when omitted) |
+| `lpb --ssh [pubkey\|path] [project]` | Start an sshd server in the container for remote login (key auto-detected from `~/.ssh` when omitted) |
 | `lpb --ssh --ssh-password [pw]` | SSH password login (random if omitted, shown once; can combine with key auth) |
 | `lpb --stop` | Stop the container |
 | `lpb --remove` | Stop + remove container + state dirs |
@@ -69,7 +69,18 @@ lpb /myproject -- --thinking high            # pass any pi flag
   profile (`~/.ssh/*.pub`). One key → used (confirmed on a TTY); several →
   numbered menu; none → error with a hint. Non-interactive: one key is used
   automatically, several → explicit selection required.
-- **Explicit key still wins**: `lpb --ssh <pubkey|path>` (literal key or file).
+- **Explicit key still wins**: `lpb --ssh <pubkey|path>` — a literal inline
+  key or a path to a `.pub` file (tilde expanded). A value that is an
+  existing *directory* is treated as the project dir (the key menu still
+  appears); anything else is an error — a nonexistent path is never silently
+  accepted as a key.
+- **First-run wait**: on the first boot the container bootstraps (config-repo
+  clone, volume chown, provider setup) *before* sshd starts, which can take a
+  few minutes. `lpb` detects first run (no `.initialized` in the state dir),
+  waits up to 5 minutes with progress notes (30 s on warm starts), and only
+  then reports a failure — with the last container log lines and a
+  first-run-aware hint (`lpb --logs` shows the bootstrap finishing; sshd
+  starts automatically once it completes).
 - **Password login**: `lpb --ssh --ssh-password` (random, printed once) or
   `lpb --ssh --ssh-password <pw>` (user-chosen). The container user's password
   is set at start (`chpasswd`) and `PasswordAuthentication` is enabled in the

scripts/lpb.py

@@ -5,8 +5,9 @@
     lpb [/path/to/project]              Start Pi CLI session at project (foreground)
     lpb /path -- <pi-args...>           Pass args through to pi (e.g. -p, --session)
     lpb --shell [/path/to/project]      Start interactive bash shell in container
-    lpb --ssh [pubkey|path] [/path]     Start sshd server (background) for remote login
-                                        (key auto-detected from ~/.ssh when omitted)
+    lpb --ssh [pubkey|path] [project]   Start sshd server (background) for remote login
+                                        (key auto-detected from ~/.ssh when omitted;
+                                         a project dir in place of a key is also accepted)
     lpb --ssh --ssh-password [pw]       SSH password login (no pw: random, shown once)
     lpb --web [/path/to/project]        Start VSCodium at project (background)
     lpb --stop                          Stop the container
@@ -410,6 +411,35 @@ def _discover_ssh_pubkeys(ssh_dir: Path | None = None) -> list[Path]:
     return sorted(p for p in d.glob("*.pub") if p.is_file())
 
 
+_SSH_KEY_PREFIXES = ("ssh-rsa", "ssh-dss", "ssh-ed25519", "ecdsa-sha2-",
+                     "sk-ecdsa-", "sk-ssh-")
+
+
+def _looks_like_pubkey(value: str) -> bool:
+    """A public key is '<type> <base64> [comment]'; type starts with a known prefix."""
+    parts = value.split()
+    return len(parts) >= 2 and parts[0].startswith(_SSH_KEY_PREFIXES)
+
+
+def _classify_ssh_key_arg(value: str) -> tuple[str, object]:
+    """Classify the optional --ssh value:
+
+      ("key", str)      inline public key
+      ("file", Path)    existing file (to read as a public key)
+      ("project", str)  existing directory — a project path was passed
+      ("invalid", str)  none of the above
+    """
+    raw = value.strip()
+    p = Path(raw).expanduser()
+    if p.is_file():
+        return "file", p
+    if _looks_like_pubkey(raw):
+        return "key", raw
+    if p.is_dir():
+        return "project", str(p)
+    return "invalid", raw
+
+
 # ── Output helpers (stdout) ───────────────────────────────────────────────────
 
 # Engine file path — resolved from __file__, NOT sys.argv[0]: the bash wrapper
@@ -858,7 +888,7 @@ def apply_overrides(project_dir: str | None = None, project_name: str | None = N
     "  lpb [/path/to/project]           Start Pi CLI session at project\n"
     "  lpb /path -- <pi-args...>        Pass flags through to pi (-p, --session, etc.)\n"
     "  lpb --shell [/path/to/project]   Interactive bash shell in container\n"
-    "  lpb --ssh [pubkey|path]          Start sshd server in background (key auto-detected from ~/.ssh)\n"
+    "  lpb --ssh [pubkey|path] [project] Start sshd server in background (key auto-detected from ~/.ssh)\n"
     "  lpb --ssh --ssh-password [pw]    SSH password login (no pw: random, shown once)\n"
     "  lpb --web [/path/to/project]     Start VSCodium (background)\n"
     "  lpb --stop                       Stop the container\n"
@@ -1030,9 +1060,31 @@ def parse_cli(args: list[str]) -> None:
     if known.ssh is not None or known.ssh_password is not None:
         cfg.ssh_mode = cfg.shell_mode = True
         if known.ssh:
-            p = Path(known.ssh)
-            cfg.ssh_pubkey = p.read_text(encoding="utf-8").strip() if p.is_file() else known.ssh.strip()
-        elif known.ssh_password is None:
+            kind, value = _classify_ssh_key_arg(known.ssh)
+            if kind == "file":
+                key_text = value.read_text(encoding="utf-8").strip()
+                if not _looks_like_pubkey(key_text):
+                    err(f"{value} does not contain a valid public key",
+                        "Pass a .pub file, an inline key (lpb --ssh <key>), or run 'lpb --ssh' to pick from ~/.ssh")
+                    raise DevstackError
+                cfg.ssh_pubkey = key_text
+            elif kind == "key":
+                cfg.ssh_pubkey = value
+            elif kind == "project":
+                # `lpb --ssh /path/to/project`: a directory where a key was
+                # expected — use it as the project dir and fall through to
+                # the profile-key discovery below (the selection prompt shows).
+                # An explicit positional project (parsed later) still wins.
+                if not cfg.project_dir:
+                    cfg.project_dir = value
+                    info(f"Project directory from --ssh argument: {value}")
+                known.ssh = ""
+            else:
+                err(f"'{known.ssh}' is not a valid pub key, a pub key file, or a project directory",
+                    "Key:     lpb --ssh <pubkey|path-to-pub-file> — or 'lpb --ssh' alone to pick from ~/.ssh\n"
+                    "Project: pass it as a positional: lpb --dev --ssh <key> <project>")
+                raise DevstackError
+        if not cfg.ssh_pubkey and known.ssh == "" and known.ssh_password is None:
             # No explicit key — fall back to the user's profile keys.
             keys = _discover_ssh_pubkeys()
             if not keys:
@@ -1942,16 +1994,19 @@ def _port_in_use(port) -> bool:
         s.close()
 
 
-def _wait_ssh_port(port, timeout: int = 20) -> bool:
+def _wait_ssh_port(port, timeout: int = 30) -> bool:
     """Wait until the sshd port accepts TCP connections.
 
     start.sh launches sshd asynchronously after the container starts, so
     connecting right after 'run' returns is too early. The SSH banner is
     verified — a bare connect cannot tell sshd apart from whatever else
     holds the host port, and claiming 'ready' for a non-sshd holder would
-    repeat the silent-failure bug."""
+    repeat the silent-failure bug. Prints a progress note every 30s so a
+    long first-run wait is not mistaken for a hang."""
     port = int(port)
-    deadline = time.time() + timeout
+    start = time.time()
+    deadline = start + timeout
+    next_note = 30
     while time.time() < deadline:
         try:
             s = socket.create_connection(("127.0.0.1", port), timeout=2)
@@ -1967,6 +2022,9 @@ def _wait_ssh_port(port, timeout: int = 20) -> bool:
             s.close()
         if banner.startswith(b"SSH-"):
             return True
+        if time.time() - start >= next_note:
+            info(f"  ... still waiting for sshd ({int(time.time() - start)}s elapsed)")
+            next_note += 30
         time.sleep(1)
     return False
 
@@ -2008,15 +2066,32 @@ def _run_ssh(c: ContainerClient, project_dir: str, env_vars: list[str],
     port = cfg.ssh_port
     user = "lpb"  # container user (uid 1000) is lpb
 
+    # First-run detection: the host state dir IS the container's /home/lpb/.pi
+    # mount, and start.sh creates <state>/.initialized when the bootstrap
+    # finishes. On the first boot the bootstrap (config-repo clone, volume
+    # chown, provider setup) runs BEFORE sshd starts and can take several
+    # minutes — a short wait here produced a false 'SSH server not ready'
+    # failure while the container was simply still bootstrapping.
+    first_run = not (Path(resolve_path(cfg.state_dir)) / ".initialized").exists()
+    if first_run:
+        info("First run — container is bootstrapping (config clone, provider setup)...")
+        info("  sshd starts automatically after the bootstrap; this can take a few minutes.")
+    wait_timeout = 300 if first_run else 30
+
     # Wait for sshd to actually listen before claiming success — the SSH
     # banner probe is the only ground truth (the host cannot see start.sh's
     # log in detached mode).
-    if not _wait_ssh_port(port):
+    if not _wait_ssh_port(port, wait_timeout):
         warn(f"Container started but SSH port {port} is NOT accepting the SSH protocol.")
         warn("  sshd failed to start inside the container — last container log lines:")
         _show_log_tail(c, 15)
-        err("SSH server not ready (container is still running)",
-            "Fix the cause above, then:  lpb --stop && lpb --ssh  (or --ssh-port <port>)")
+        if first_run:
+            err("SSH server not ready — the first-run bootstrap may still be running (container is still alive)",
+                "Watch it finish:  lpb --logs   (sshd starts once 'First run bootstrap complete' appears)\n"
+                "Start over:       lpb --stop && lpb --ssh  (or --ssh-port <port>)")
+        else:
+            err("SSH server not ready (container is still running)",
+                "Fix the cause above, then:  lpb --stop && lpb --ssh  (or --ssh-port <port>)")
         raise DevstackError
 
     done(f"\u2713 SSH server ready (background) — listening on port {port}")

scripts/test_lpb_ssh.py

@@ -54,6 +54,68 @@ def test_ssh_explicit_key_path():
     print("  PASS\n")
 
 
+def test_ssh_explicit_key_tilde_path():
+    print("TEST: --ssh ~/.ssh/<pub> → tilde expanded, file read")
+    reset_mock()
+    _clear_ssh()
+    mod = make_module()
+    _write_key("id_ed25519.pub")
+    mod.parse_cli(["--ssh", "~/.ssh/id_ed25519.pub"])
+    mod.apply_overrides()
+    assert mod.cfg.ssh_pubkey == "ssh-ed25519 AAAAC3-id_ed25519.pub id_ed25519.pub@host"
+    assert "~" not in mod.cfg.ssh_pubkey
+    print("  PASS\n")
+
+
+def test_ssh_project_dir_as_value():
+    print("TEST: --ssh <project dir> → project dir + profile key selection")
+    reset_mock()
+    _clear_ssh()
+    mod = make_module()
+    _write_key("id_ed25519.pub")
+    proj = os.path.join(os.environ["HOME"], "myproject")
+    os.makedirs(proj, exist_ok=True)
+    mod.parse_cli(["--ssh", proj])
+    mod.apply_overrides()
+    assert mod.cfg.ssh_mode
+    assert mod.cfg.project_dir == proj, "dir passed to --ssh must become the project dir"
+    # non-TTY + single profile key → auto-used (the prompt shows on a TTY)
+    assert mod.cfg.ssh_pubkey == "ssh-ed25519 AAAAC3-id_ed25519.pub id_ed25519.pub@host"
+    shutil.rmtree(proj, ignore_errors=True)
+    print("  PASS\n")
+
+
+def test_ssh_invalid_value_errors():
+    print("TEST: --ssh <nonexistent path> → error (not silently a key)")
+    reset_mock()
+    _clear_ssh()
+    mod = make_module()
+    try:
+        mod.parse_cli(["--ssh", os.path.join(os.environ["HOME"], "nowhere", "missing.pub")])
+        raise AssertionError("expected DevstackError")
+    except mod.DevstackError:
+        pass
+    print("  PASS\n")
+
+
+def test_ssh_file_without_key_content_errors():
+    print("TEST: --ssh <file that is not a pub key> → error")
+    reset_mock()
+    _clear_ssh()
+    mod = make_module()
+    bad = os.path.join(os.environ["HOME"], "not-a-key.pub")
+    with open(bad, "w") as f:
+        f.write("just some text\n")
+    try:
+        mod.parse_cli(["--ssh", bad])
+        raise AssertionError("expected DevstackError")
+    except mod.DevstackError:
+        pass
+    finally:
+        os.unlink(bad)
+    print("  PASS\n")
+
+
 def test_ssh_no_key_no_profile_keys():
     print("TEST: --ssh with no key and empty ~/.ssh → error")
     reset_mock()
@@ -239,9 +301,99 @@ def test_ssh_ready_only_after_port_opens():
     print("  PASS\n")
 
 
+def _first_run_marker():
+    """Host-side first-run marker: <state dir>/.initialized (start.sh creates it
+    when the in-container bootstrap finishes)."""
+    return os.path.join(os.environ["HOME"], ".lpb-stack", "state", ".initialized")
+
+
+def _run_ssh_flow_timeout(wait_ok: bool, first_run: bool) -> int:
+    """Run the --ssh flow and return the timeout _wait_ssh_port got."""
+    from testharness import _OutputCapture
+    mod = make_module()  # redirects HOME to the isolated test home
+    mod.lpb_setup = _FakeSetupOk()
+    mod._port_in_use = lambda port: False
+    marker = _first_run_marker()
+    try:
+        if first_run:
+            if os.path.exists(marker):
+                os.unlink(marker)
+        else:
+            os.makedirs(os.path.dirname(marker), exist_ok=True)
+            open(marker, "w").close()
+        captured = {}
+
+        def fake_wait(port, timeout=30):
+            captured["timeout"] = timeout
+            return wait_ok
+
+        mod._wait_ssh_port = fake_wait
+        out = _OutputCapture()
+        out.__enter__()
+        try:
+            mod.parse_cli(["--ssh", "ssh-ed25519 AAAA k@h"])
+            mod.apply_overrides()
+            mod.cmd_run()
+        finally:
+            out.__exit__(None, None, None)
+        assert captured.get("timeout") is not None, "_wait_ssh_port was not called"
+        return captured["timeout"]
+    finally:
+        if os.path.exists(marker):
+            os.unlink(marker)
+
+
+def test_ssh_first_run_waits_for_bootstrap():
+    print("TEST: first run (no .initialized) → long sshd wait (bootstrap)")
+    reset_mock()
+    t_first = _run_ssh_flow_timeout(wait_ok=True, first_run=True)
+    t_warm = _run_ssh_flow_timeout(wait_ok=True, first_run=False)
+    assert t_first >= 120, f"first-run wait too short: {t_first}s"
+    assert t_warm < t_first, f"warm wait ({t_warm}s) should be shorter than first-run ({t_first}s)"
+    print("  PASS\n")
+
+
+def test_ssh_first_run_failure_hint():
+    print("TEST: first-run wait exhausted → hint says the bootstrap may still be running")
+    from testharness import _OutputCapture
+    reset_mock()
+    mod = make_module()  # redirects HOME to the isolated test home
+    mod.lpb_setup = _FakeSetupOk()
+    mod._port_in_use = lambda port: False
+    mod._wait_ssh_port = lambda port, timeout=30: False
+    marker = _first_run_marker()
+    try:
+        if os.path.exists(marker):
+            os.unlink(marker)
+        out = _OutputCapture()
+        out.__enter__()
+        raised = None
+        try:
+            mod.parse_cli(["--ssh", "ssh-ed25519 AAAA k@h"])
+            mod.apply_overrides()
+            mod.cmd_run()
+        except mod.DevstackError:
+            raised = "DevstackError"
+        finally:
+            out.__exit__(None, None, None)
+        out_text = "".join(out.out)
+        assert raised == "DevstackError", "must fail when the port never opens"
+        assert "SSH server ready" not in out_text
+        assert "bootstrap" in out_text, "first-run failure must mention the bootstrap"
+        assert "lpb --logs" in out_text, "first-run failure must point at the live log"
+    finally:
+        if os.path.exists(marker):
+            os.unlink(marker)
+    print("  PASS\n")
+
+
 TESTS = [
     test_ssh_explicit_key_literal,
     test_ssh_explicit_key_path,
+    test_ssh_explicit_key_tilde_path,
+    test_ssh_project_dir_as_value,
+    test_ssh_invalid_value_errors,
+    test_ssh_file_without_key_content_errors,
     test_ssh_no_key_no_profile_keys,
     test_ssh_auto_single_key,
     test_ssh_auto_multiple_keys_noninteractive,
@@ -254,6 +406,8 @@ def test_ssh_ready_only_after_port_opens():
     test_ssh_port_in_use_fails_fast,
     test_ssh_no_false_success_when_port_never_opens,
     test_ssh_ready_only_after_port_opens,
+    test_ssh_first_run_waits_for_bootstrap,
+    test_ssh_first_run_failure_hint,
 ]