lcode-cli 0.19.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

lcode/__init__.py

@@ -3,7 +3,7 @@
 From a program: `from lcode import Session` (see lcode.api).
 """
 
-__version__ = "0.19.0"
+__version__ = "0.21.0"
 
 API = ("Session", "Result", "Options", "SetupError")
 

lcode/acp.py

@@ -46,7 +46,7 @@ KINDS = {
     "read_file": "read", "view_image": "read", "list_dir": "search", "glob": "search", "grep": "search",
     "repo_map": "search", "search_code": "search", "lsp": "search", "edit_file": "edit", "write_file": "edit",
     "bash": "execute", "web_search": "fetch", "web_fetch": "fetch", "agent": "think", "todo_write": "think",
-    "present_plan": "switch_mode",
+    "present_plan": "switch_mode", "bash_output": "read", "bash_stop": "execute",
 }  # fmt: skip
 STOP = {"success": "end_turn", "max_steps": "max_turn_requests", "interrupted": "cancelled"}
 MAX_INLINE = 200_000  # bytes of a file the editor attaches that go into the prompt

lcode/agent.py

@@ -22,11 +22,12 @@ from rich.markup import escape
 from rich.panel import Panel
 from rich.text import Text
 
-from lcode import catalog, codesearch, extensions, limits, planning, repomap, sessions, subagents, vision, web
+from lcode import catalog, codesearch, extensions, limits, notify, planning, repomap, sessions, subagents, vision, web
 from lcode import context as context_tools
 from lcode import memory as memory_notes
 from lcode.checkpoints import Checkpoints
 from lcode.config import format_tokens
+from lcode.jobs import Jobs
 from lcode.mcp import McpManager
 from lcode.ollama import Ollama, OllamaError
 from lcode.permissions import Permissions
@@ -212,6 +213,8 @@ class Settings:
     lsp: str = "off"  # auto: use the installed language servers (lcode.lsp)
     repo_map: bool = False  # the repository map (lcode.repomap)
     embed_model: str = "off"  # semantic code search (lcode.codesearch): auto, off or a model
+    notify: bool = False  # desktop notifications after long requests (lcode.notify)
+    notify_after: int = 30  # seconds: a request this long notifies when it's done or waits for an answer
     max_parallel_agents: int = 1
 
 
@@ -256,6 +259,8 @@ class Agent:
         self.no_changes = ""  # set during a review: why nothing may change (read-only tools only)
         self.cancel: threading.Event | None = None  # set from another thread to stop
         self.on_tool = None  # called with (name, arguments) before each tool runs
+        self.jobs = Jobs()  # background commands (shared with subagents)
+        self.turn_started = 0.0  # when the running request started (time.monotonic)
         self.on_event: Callable[[dict], None] | None = None  # each step and tool result, for --output stream-json
         self.on_delta: Callable[[str, str], None] | None = None  # ("text" or "thinking", piece) as it streams
         self.current_call = ""  # id of the tool call that's running, so a permission request can name it
@@ -746,6 +751,7 @@ class Agent:
         return name
 
     def run_turn(self, user_text: str) -> None:
+        self.turn_started = time.monotonic()
         self.checkpoints.begin_turn(self.session_id, user_text, len(self.messages))
         try:
             self._run_turn(user_text)
@@ -760,6 +766,27 @@ class Agent:
                             Text(f"  ⎿ after_request hook ({outcome.code}): {outcome.output[:500]}", style=style)
                         )
 
+    def waiting(self, title: str) -> None:
+        """lcode waits for the user's answer: tell them, if they've likely walked away (lcode.notify)."""
+        if self.hooks.for_event("notification"):
+            self.hooks.notify(f"lcode needs you: {title}", self.cwd)
+        if (
+            self.settings.notify
+            and self.interactive
+            and time.monotonic() - self.turn_started >= self.settings.notify_after
+        ):
+            notify.desktop("lcode needs you", title)
+
+    def finished(self, request: str, seconds: float) -> None:
+        """A request is done: after a long one, tell the user."""
+        if seconds < self.settings.notify_after:
+            return
+        title = sessions.title_from([{"role": "user", "content": request}])
+        if self.hooks.for_event("notification"):
+            self.hooks.notify(f"lcode finished: {title}", self.cwd)
+        if self.settings.notify and self.interactive:
+            notify.desktop("lcode is done", f"{title} ({seconds:.0f}s)")
+
     def sandbox_root(self) -> Path | None:
         """The folder the model is limited to while the sandbox is on (None when it's off)."""
         if not self.sandbox:

lcode/api.py

@@ -192,6 +192,8 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
         prune=cfg["prune"],
         repo_map=cfg["repo_map"],
         embed_model=cfg["embed_model"],
+        notify=cfg["notify"],
+        notify_after=cfg["notify_after"],
     )
     agent = Agent(ollama, settings, cwd, console=console)
     agent.interactive = options.interactive
@@ -206,8 +208,7 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
     agent.hooks, agent.perms.rules = hooks.load(cwd, trust_project)
     for problem in agent.hooks.problems:
         console.print(f"[yellow]Settings: {problem}[/]")
-    if agent.hooks.for_event("notification"):
-        agent.perms.on_prompt = lambda title: agent.hooks.notify(f"lcode needs you: {title}", agent.cwd)
+    agent.perms.on_prompt = agent.waiting  # notification hooks and desktop notifications
     if cfg["lsp"] == "auto":
         from lcode import lsp
         from lcode.checkpoints import work_tree_for
@@ -233,6 +234,9 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
 
 
 def close_agent(agent: Agent) -> None:
+    stopped = agent.jobs.stop_all()
+    if stopped:
+        agent.console.print(f"[dim]Stopped {stopped} background job(s).[/]")
     if agent.lsp is not None:
         agent.lsp.close()
     if agent.mcp:

lcode/cli.py

@@ -678,7 +678,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="lcode",
         description="A local-first terminal coding agent powered by open-weight models via Ollama.",
-        epilog="Subcommands: lcode setup | models | doctor | config | bench | mcp | index "
+        epilog="Subcommands: lcode setup | models | doctor | config | bench | mcp | index | update "
         "(lcode <subcommand> --help). "
         "Docs: https://nasser1941.github.io/lcode/",
     )
@@ -774,6 +774,15 @@ def build_subparsers() -> dict[str, argparse.ArgumentParser]:
     from lcode.mcp.commands import build_parser as mcp_parser
 
     subs["mcp"] = mcp_parser()
+    p = argparse.ArgumentParser(
+        prog="lcode update",
+        description="Update lcode, and Ollama when it runs in Docker (to the newest version on Docker Hub, pinned "
+        "to its version tag).",
+    )
+    p.add_argument("what", nargs="?", choices=["lcode", "ollama"], help="only this one (default: both)")
+    p.add_argument("--check", action="store_true", help="only show which versions are out")
+    p.add_argument("-y", "--yes", action="store_true", help="don't ask before updating")
+    subs["update"] = p
     subs["acp"] = argparse.ArgumentParser(
         prog="lcode acp",
         description="Run as the agent inside an editor, over the Agent Client Protocol on stdin and stdout "
@@ -787,6 +796,12 @@ def build_subparsers() -> dict[str, argparse.ArgumentParser]:
     return subs
 
 
+def cmd_update(args) -> None:
+    from lcode import update
+
+    sys.exit(update.command(console, args.what or "", check=args.check, yes=args.yes))
+
+
 def cmd_acp(args) -> None:
     from lcode import acp
 
@@ -863,6 +878,7 @@ COMMANDS = {
     "index": cmd_index,
     "action": cmd_action,
     "acp": cmd_acp,
+    "update": cmd_update,
 }
 
 

lcode/config.py

@@ -57,6 +57,8 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "lsp": ("auto", str, "language servers for code navigation and errors after edits: auto | off"),
     "prune": (True, bool, "before summarizing a full conversation, first remove old tool output from it"),
     "subagents": (True, bool, "let the model hand tasks to subagents that have their own context"),
+    "notify": (True, bool, "desktop notification when a long request is done or waits for you"),
+    "notify_after": (30, int, "seconds a request runs before it notifies (with notify on)"),
     "max_parallel_agents": (1, int, "subagents that may run at the same time (more needs OLLAMA_NUM_PARALLEL)"),
 }
 ENV_OVERRIDES = {

lcode/jobs.py

@@ -0,0 +1,165 @@
+"""Background commands: dev servers, watchers and other processes that keep running.
+
+The model starts one with `bash(command, background=true)` and gets an id back, reads what it
+printed since last time with `bash_output(id)` and stops it with `bash_stop(id)`. `/jobs` lists
+them. They're all stopped when the session ends.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import signal
+import subprocess
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+KEEP = 1_000_000  # characters of a job's output kept in memory
+STARTUP_WAIT = 3.0  # seconds to wait for a new job's first output (and quick failures)
+
+
+class JobError(Exception):
+    pass
+
+
+@dataclass
+class Job:
+    id: str
+    command: str
+    proc: subprocess.Popen
+    kill: Callable[[], None] | None = None  # extra cleanup, e.g. the process in the sandbox
+    started: float = field(default_factory=time.monotonic)
+    output: str = ""
+    read: int = 0  # how much of `output` the model has seen
+    dropped: int = 0  # characters dropped from the front to stay under KEEP
+    stopped: bool = False
+    ended: float = 0.0
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def pump(self) -> None:
+        assert self.proc.stdout is not None
+        for line in self.proc.stdout:
+            with self.lock:
+                self.output += line
+                if len(self.output) > KEEP:
+                    cut = len(self.output) - KEEP
+                    self.output = self.output[cut:]
+                    self.dropped += cut
+                    self.read = max(0, self.read - cut)
+        self.proc.wait()
+        self.ended = time.monotonic()
+
+    @property
+    def running(self) -> bool:
+        return self.proc.poll() is None
+
+    def status(self) -> str:
+        if self.running:
+            return "running"
+        if self.stopped:
+            return "stopped"
+        return f"exited with code {self.proc.returncode}"
+
+    def runtime(self) -> float:
+        return (self.ended or time.monotonic()) - self.started
+
+    def new_output(self, limit: int) -> str:
+        with self.lock:
+            text, self.read = self.output[self.read :], len(self.output)
+        if len(text) > limit:
+            text = f"[… {len(text) - limit:,} earlier characters not shown]\n" + text[-limit:]
+        return text
+
+
+class Jobs:
+    """The session's background commands (shared with its subagents)."""
+
+    def __init__(self) -> None:
+        self.items: dict[str, Job] = {}
+        self.counter = 0
+
+    def start(self, argv: list[str], cwd: Path, command: str, kill: Callable[[], None] | None = None) -> Job:
+        proc = subprocess.Popen(
+            argv,
+            cwd=cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.DEVNULL,
+            text=True,
+            errors="replace",
+            start_new_session=True,  # its own process group, so stopping it stops its children too
+            bufsize=1,
+        )
+        self.counter += 1
+        job = Job(str(self.counter), command, proc, kill)
+        self.items[job.id] = job
+        threading.Thread(target=job.pump, daemon=True).start()
+        deadline = time.monotonic() + STARTUP_WAIT
+        while time.monotonic() < deadline and job.running and not job.output:
+            time.sleep(0.05)
+        if job.running:
+            time.sleep(min(0.5, max(0.0, deadline - time.monotonic())))  # a little more of its first output
+        else:
+            time.sleep(0.1)  # let the pump read the rest
+        return job
+
+    def get(self, job_id: str) -> Job:
+        job = self.items.get(str(job_id).strip().lstrip("#"))
+        if job is None:
+            known = ", ".join(self.items) or "none"
+            raise JobError(f"there's no background job {job_id} (jobs: {known})")
+        return job
+
+    def stop(self, job_id: str) -> Job:
+        job = self.get(job_id)
+        if job.running:
+            job.stopped = True
+            terminate(job)
+        return job
+
+    def stop_all(self) -> int:
+        running = [j for j in self.items.values() if j.running]
+        for job in running:
+            job.stopped = True
+            terminate(job)
+        return len(running)
+
+    def running(self) -> list[Job]:
+        return [j for j in self.items.values() if j.running]
+
+
+def stop_leftovers(group: int) -> bool:
+    """Stop what a finished command left running in its process group; whether there was anything."""
+    try:
+        os.killpg(group, 0)  # raises when nothing is left
+    except (ProcessLookupError, PermissionError):
+        return False
+    for sig in (signal.SIGTERM, signal.SIGKILL):
+        with contextlib.suppress(ProcessLookupError, PermissionError):
+            os.killpg(group, sig)
+            time.sleep(0.3)
+    return True
+
+
+def terminate(job: Job, grace: float = 3.0) -> None:
+    """SIGTERM the job's process group, then SIGKILL whatever is left."""
+    if job.kill is not None:
+        with contextlib.suppress(Exception):
+            job.kill()
+    for sig in (signal.SIGTERM, signal.SIGKILL):
+        with contextlib.suppress(ProcessLookupError, PermissionError):
+            os.killpg(job.proc.pid, sig)
+        try:
+            job.proc.wait(timeout=grace)
+            return
+        except subprocess.TimeoutExpired:
+            continue
+
+
+def describe(job: Job) -> str:
+    minutes, seconds = divmod(int(job.runtime()), 60)
+    took = f"{minutes}m {seconds:02d}s" if minutes else f"{seconds}s"
+    return f"job {job.id} ({job.status()}, {took}): {job.command}"

lcode/notify.py

@@ -0,0 +1,43 @@
+"""Desktop notifications: when a long request is done, or lcode waits for an answer during one.
+
+Local models are slow, so people switch to something else while a request runs. lcode shows a
+notification with `notify-send` on Linux and `osascript` on macOS, and rings the terminal bell
+where neither is available.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import sys
+import threading
+
+
+def command(title: str, message: str) -> list[str] | None:
+    """The command that shows a notification on this machine, or None."""
+    if platform.system() == "Darwin" and shutil.which("osascript"):
+        quoted = message.replace("\\", "\\\\").replace('"', '\\"')
+        heading = title.replace("\\", "\\\\").replace('"', '\\"')
+        return ["osascript", "-e", f'display notification "{quoted}" with title "{heading}"']
+    if shutil.which("notify-send"):
+        return ["notify-send", "--app-name=lcode", title, message]
+    return None
+
+
+def desktop(title: str, message: str) -> None:
+    """Show the notification without waiting for it; the terminal bell if there's no way to."""
+    argv = command(title, message[:200])
+    if argv is None:
+        sys.stderr.write("\a")
+        sys.stderr.flush()
+        return
+
+    def run() -> None:
+        try:
+            subprocess.run(argv, capture_output=True, timeout=10)
+        except (OSError, subprocess.SubprocessError):
+            sys.stderr.write("\a")
+            sys.stderr.flush()
+
+    threading.Thread(target=run, daemon=True).start()

lcode/planning.py

@@ -32,7 +32,7 @@ if TYPE_CHECKING:
 PLAN_MODE_TOOLS = frozenset(
     {
         "read_file", "list_dir", "glob", "grep", "bash", "web_search", "web_fetch", "view_image", "todo_write",
-        "agent", "memory", "present_plan", "mcp_find_tools", "skill", "lsp", "repo_map", "search_code",
+        "agent", "memory", "present_plan", "mcp_find_tools", "skill", "lsp", "repo_map", "search_code", "bash_output",
     }
 )  # fmt: skip
 
@@ -103,6 +103,8 @@ def present(agent: Agent, title: str, plan: str) -> str:
         if not agent.interactive:
             return "The plan was shown to the user, who will review it later. Stop here and don't change anything."
         c.print(CHOICES)
+        if agent.perms.on_prompt:
+            agent.perms.on_prompt(f"Plan: {title}")
         try:
             answer = input("  > ").strip()
         except EOFError:

lcode/repl.py

@@ -62,6 +62,7 @@ COMMANDS = {
     "/mode": "Permission mode: ask | plan | auto-edit | yolo (Shift+Tab cycles)",
     "/cd": "Change the working directory",
     "/todos": "Show the current todo list",
+    "/jobs": "Background commands the model started: /jobs, /jobs stop <id>",
     "/commit": "Commit the changes with a message in the repository's style, after you approve it",
     "/review": "Review the uncommitted changes, or the branch against a base: /review [base]",
     "/pr": "Push the branch and open a GitHub pull request, after you approve it: /pr [base] [notes]",
@@ -776,7 +777,28 @@ def web_status(agent: Agent) -> str:
     return f"{agent.settings.web} · {search}"
 
 
-LONG_REQUEST = 30  # seconds: a request this long sends a notification when it's done (notification hooks)
+def jobs_command(agent: Agent, arg: str) -> None:
+    """List the background commands, or stop one: /jobs stop <id>."""
+    from lcode.jobs import JobError, describe
+
+    c = agent.console
+    word, _, job_id = arg.partition(" ")
+    if word == "stop":
+        try:
+            job = agent.jobs.stop(job_id or "?")
+        except JobError as e:
+            c.print(f"[red]{escape(str(e))}[/]")
+            return
+        c.print(f"Stopped {escape(describe(job))}")
+        return
+    if not agent.jobs.items:
+        c.print("No background commands. The model starts them with bash(background=true), e.g. a dev server.")
+        return
+    for job in agent.jobs.items.values():
+        style = "green" if job.running else "dim"
+        c.print(f"[{style}]{escape(describe(job))}[/]")
+    if agent.jobs.running():
+        c.print("[dim]/jobs stop <id> stops one; they all stop when the session ends.[/]")
 
 
 def git_command(agent: Agent, cmd: str, arg: str) -> None:
@@ -810,8 +832,7 @@ def run_safely(agent: Agent, text: str) -> None:
         agent.console.print(f"[red]{e}[/]")
     finally:
         agent.save()
-        if time.monotonic() - started > LONG_REQUEST:
-            agent.hooks.notify(f"lcode finished: {sessions.title_from([{'role': 'user', 'content': text}])}", agent.cwd)
+        agent.finished(text, time.monotonic() - started)
 
 
 def session_start(agent: Agent) -> None:
@@ -931,6 +952,8 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
             c.print(f"[red]Not a directory: {p}[/]")
     elif cmd == "/todos":
         agent.tools.show_todos()
+    elif cmd == "/jobs":
+        jobs_command(agent, arg)
     elif cmd == "/init":
         run_safely(agent, INIT_PROMPT)
     elif cmd in REPLACEABLE and cmd[1:] not in agent.extensions().commands:

lcode/subagents.py

@@ -463,6 +463,7 @@ class Run:
         child = Agent(parent.ollama, settings, cwd, console=Console(file=io.StringIO(), width=120))
         child.perms = self.relay  # type: ignore[assignment]
         child.sandbox = parent.sandbox
+        child.jobs = parent.jobs  # its background commands belong to the session
         if not self.worktree:
             child.checkpoints = parent.checkpoints  # changes in the shared tree are part of the running request
         child.mcp = None

lcode/tools.py

@@ -25,6 +25,7 @@ from rich.text import Text
 
 from lcode import web
 from lcode.context import shorten
+from lcode.jobs import JobError, describe, stop_leftovers
 from lcode.permissions import bash_key, is_read_only
 from lcode.planning import BLOCKED, PLAN_MODE_TOOLS
 from lcode.sandbox import SandboxError
@@ -38,6 +39,7 @@ NO_NETWORK = re.compile(
     r"EAI_AGAIN|Name or service not known|network is unreachable|No route to host"
 )
 MAX_TOOL_OUTPUT = 30_000  # characters returned to the model per tool call
+LEFTOVER_GRACE = 0.5  # seconds to wait for output after a command ends, before stopping what it left running
 IGNORE_DIRS = {
     ".git", "node_modules", "__pycache__", ".venv", "venv", "env", ".mypy_cache", ".pytest_cache",
     ".ruff_cache", ".tox", ".idea", ".vscode", "dist", "build", ".next", "target", ".cache", ".gradle",
@@ -119,13 +121,28 @@ SCHEMAS = [
         "bash",
         "Run a shell command with bash in the working directory and return its output and exit code. The "
         "working directory persists between calls (cd works). Use it to run scripts and tests, use git, install "
-        "packages, etc. Avoid interactive commands.",
+        "packages, etc. Avoid interactive commands. For a process that keeps running (a dev server, a watcher), "
+        "set background=true and give the plain command, without & or redirecting its output: lcode keeps it "
+        "running and keeps its output, you get a job id back and can carry on.",
         {
             "command": {"type": "string"},
             "timeout": {"type": "integer", "description": "Seconds before the command is killed (default 180)"},
+            "background": {
+                "type": "boolean",
+                "description": "Keep it running in the background; read its output with bash_output and stop it "
+                "with bash_stop (not with kill)",
+            },
         },
         ["command"],
     ),
+    _fn(
+        "bash_output",
+        "Read what a background command (bash with background=true) printed since you last read it, and whether "
+        "it's still running.",
+        {"id": {"type": "string", "description": "The job id bash returned"}},
+        ["id"],
+    ),
+    _fn("bash_stop", "Stop a background command.", {"id": {"type": "string"}}, ["id"]),
     _fn(
         "todo_write",
         "Create or update your task list for multi-step work. Pass the full list every time. Keep exactly one "
@@ -792,7 +809,7 @@ class Toolbox:
         return f"Edited {self.rel(p)} ({count} replacement(s)). Result:\n{snippet}" + problems
 
     # -- shell
-    def t_bash(self, command: str, timeout: int = 180) -> str:
+    def t_bash(self, command: str, timeout: int = 180, background: bool = False) -> str:
         sandbox = self.agent.sandbox
         if self.agent.planning() and not is_read_only(command):
             raise ToolError(f"{BLOCKED} Until then, only read-only commands run (ls, cat, grep, git log, …).")
@@ -814,7 +831,9 @@ class Toolbox:
                 return feedback
         if not is_read_only(command):
             self.agent.checkpoint()
-        self.console.print(Text(f"  $ {command}", style="bold cyan"))
+        self.console.print(Text(f"  $ {command}" + ("  (in the background)" if background else ""), style="bold cyan"))
+        if background is True or str(background).lower() == "true":
+            return self._background(command)
         marker = f"__lcode_cwd_{secrets.token_hex(8)}__"
         script = f"{command}\n__lcode_ec=$?\nprintf '\\n{marker}%s\\n' \"$(pwd -P)\"\nexit $__lcode_ec\n"
         token = ""
@@ -855,6 +874,8 @@ class Toolbox:
         out: list[str] = []
         shown, status, recorded = 0, "", ""
         deadline = time.time() + int(timeout or 180)
+        finished = 0.0  # when the command itself ended (its marker arrived)
+        held_open = False  # something it started still holds the output open
         try:
             while True:
                 if self.agent.cancel is not None and self.agent.cancel.is_set():
@@ -862,6 +883,9 @@ class Toolbox:
                 try:
                     line = lines.get(timeout=0.2)
                 except queue.Empty:
+                    if finished and time.time() - finished > LEFTOVER_GRACE:
+                        held_open = True
+                        break
                     if time.time() > deadline:
                         stop()
                         status = f"\n[Command timed out after {timeout}s and was killed]"
@@ -871,6 +895,7 @@ class Toolbox:
                     break
                 if line.startswith(marker):
                     recorded = line[len(marker) :].strip()
+                    finished = time.time()
                     continue
                 out.append(line)
                 if shown <= 40:
@@ -881,6 +906,13 @@ class Toolbox:
             stop()
             raise
         code = proc.wait()
+        if held_open and sandbox and token:
+            sandbox.kill(token)  # what it left running in the container
+        if (not sandbox and stop_leftovers(proc.pid)) or held_open:
+            status += (
+                "\n[lcode stopped what this command left running (started with &). To keep a process running, "
+                "start it with background=true: then bash_output reads its output and bash_stop stops it]"
+            )
         if out and out[-1] == "\n":
             out.pop()  # the blank line printed before the marker
         if recorded and Path(recorded).is_dir() and Path(recorded).resolve() != self.agent.cwd:
@@ -933,6 +965,51 @@ class Toolbox:
             raise ToolError(str(e)) from e
         return web.format_page(url, title, text, max(1000, min(int(max_chars or 20000), MAX_TOOL_OUTPUT)))
 
+    def _background(self, command: str) -> str:
+        sandbox, kill = self.agent.sandbox, None
+        if sandbox:
+            try:
+                with self.console.status("Starting the sandbox…"):
+                    sandbox.ensure(self.agent.cwd)
+            except SandboxError as e:
+                return f"Error: the sandbox can't start, so the command didn't run: {e}"
+            argv, token = sandbox.exec_argv(self.agent.cwd, command)
+            kill = lambda: sandbox.kill(token)  # noqa: E731
+        else:
+            argv = ["bash", "-c", command]
+        job = self.agent.jobs.start(argv, self.agent.cwd, command, kill)
+        first = job.new_output(MAX_TOOL_OUTPUT // 3).rstrip()
+        for line in first.splitlines()[:10]:
+            self.console.print(Text("    " + line[:300], style="dim"))
+        if not job.running:
+            return (
+                f"The command ended right away ({job.status()}), so it isn't running in the background:\n"
+                f"{first or '(no output)'}"
+            )
+        self.console.print(Text(f"  ⎿ background job {job.id}, /jobs to see it", style="dim"))
+        return (
+            f"Started background job {job.id}: it keeps running while you work. Read its new output with "
+            f'bash_output(id="{job.id}") and stop it with bash_stop(id="{job.id}") when it\'s no longer needed.\n'
+            f"Output so far:\n{first or '(none yet)'}"
+        )
+
+    def t_bash_output(self, id: str) -> str:
+        try:
+            job = self.agent.jobs.get(id)
+        except JobError as e:
+            raise ToolError(str(e)) from e
+        text = job.new_output(MAX_TOOL_OUTPUT).rstrip()
+        return f"[{describe(job)}]\n{text or '(no new output)'}"
+
+    def t_bash_stop(self, id: str) -> str:
+        try:
+            job = self.agent.jobs.stop(id)
+        except JobError as e:
+            raise ToolError(str(e)) from e
+        self.console.print(Text(f"  ⎿ {describe(job)}", style="dim"))
+        last = job.new_output(4000).rstrip()
+        return f"[{describe(job)}]" + (f"\nIts last output:\n{last}" if last else "")
+
     # -- planning
     def t_todo_write(self, todos: list | str) -> str:
         if isinstance(todos, str):

lcode/update.py

@@ -0,0 +1,557 @@
+"""`lcode update`: update lcode, and Ollama when it runs in Docker.
+
+lcode updates itself the way it was installed: uv tool, pipx, Homebrew, pip, or `git pull` for a
+checkout (an editable install).
+
+For Ollama in Docker, the newest version is looked up on Docker Hub, never taken from a local
+`latest` tag (which can be months old), and pulled by its version tag (`ollama/ollama:0.35.1`), so
+`docker ps` shows which version runs. Release candidates are skipped, and a ROCm image stays ROCm.
+- A container from Docker Compose gets the new tag in its compose file and is recreated with
+  `docker compose up`, so Compose keeps managing it.
+- Any other container is recreated with the same name, ports, volumes, environment, GPUs, network
+  and restart policy. The old one is kept until the new one answers with the new version, and is
+  put back if it doesn't.
+Ollama installed without Docker gets the command to update it, which lcode doesn't run itself.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import json
+import re
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import requests
+
+from lcode import __version__
+
+IMAGE = "ollama/ollama"
+HUB_TAGS = "https://hub.docker.com/v2/namespaces/ollama/repositories/ollama/tags"
+PYPI = "https://pypi.org/pypi/lcode-cli/json"
+SEMVER = re.compile(r"\d+\.\d+\.\d+")
+START_TIMEOUT = 120  # seconds for a recreated container to answer
+NATIVE = {
+    "linux": "curl -fsSL https://ollama.com/install.sh | sh",
+    "darwin": "brew upgrade ollama   (or let the Ollama app update itself)",
+}
+
+
+class UpdateError(Exception):
+    pass
+
+
+def version_key(version: str) -> tuple[int, ...]:
+    return tuple(int(p) for p in re.findall(r"\d+", version)[:3])
+
+
+def run(argv: list[str], cwd: Path | None = None, timeout: float = 120) -> subprocess.CompletedProcess:
+    """A command whose output lcode reads (and tests replace)."""
+    try:
+        return subprocess.run(argv, cwd=cwd, capture_output=True, text=True, timeout=timeout)
+    except (OSError, subprocess.SubprocessError) as e:
+        raise UpdateError(f"{argv[0]} failed: {e}") from e
+
+
+def stream(argv: list[str], cwd: Path | None = None) -> int:
+    """A command the user watches (pulls, installs); returns its exit code."""
+    try:
+        return subprocess.call(argv, cwd=cwd)
+    except OSError as e:
+        raise UpdateError(f"{argv[0]} failed: {e}") from e
+
+
+def get_json(url: str, **params) -> dict:
+    try:
+        r = requests.get(url, params=params or None, timeout=20)
+        r.raise_for_status()
+        return r.json()
+    except (requests.RequestException, ValueError) as e:
+        raise UpdateError(f"couldn't read {url.split('?')[0]}: {e}") from e
+
+
+# ----------------------------------------------------------------------------- the newest versions
+
+
+def latest_lcode() -> str:
+    return str(get_json(PYPI)["info"]["version"])
+
+
+def latest_ollama(flavor: str = "") -> str:
+    """The newest released Ollama image tag on Docker Hub: "0.35.1", or "0.35.1-rocm" for flavor "rocm"."""
+    names: list[str] = []
+    url, params = HUB_TAGS, {"page_size": 100, "ordering": "last_updated"}
+    for _ in range(3):  # the newest tags come first; three pages reach well past them
+        page = get_json(url, **params)
+        names += [str(t.get("name", "")) for t in page.get("results") or []]
+        url, params = page.get("next"), {}
+        if not url:
+            break
+    suffix = f"-{flavor}" if flavor else ""
+    versions = [
+        n.removesuffix(suffix) for n in names if n.endswith(suffix) and SEMVER.fullmatch(n.removesuffix(suffix))
+    ]
+    if not versions:
+        raise UpdateError(f"Docker Hub lists no released {IMAGE} versions{f' for {flavor}' if flavor else ''}")
+    return max(versions, key=version_key) + suffix
+
+
+def image_flavor(image: str) -> str:
+    """The image variant to stay on: "rocm" for ollama/ollama:rocm or :0.35.1-rocm, else ""."""
+    tag = image.rsplit(":", 1)[1] if ":" in image.rsplit("/", 1)[-1] else "latest"
+    return "rocm" if tag == "rocm" or tag.endswith("-rocm") else ""
+
+
+# ----------------------------------------------------------------------------- lcode itself
+
+
+@dataclass
+class Install:
+    kind: str  # checkout, uv, pipx, brew, uvx, pip
+    command: list[str] | None = None  # what updates it
+    path: Path | None = None  # the checkout, for kind checkout
+
+    def describe(self) -> str:
+        return {
+            "checkout": f"a git checkout at {self.path}",
+            "uv": "uv tool",
+            "pipx": "pipx",
+            "brew": "Homebrew",
+            "uvx": "uvx",
+            "pip": "pip",
+        }[self.kind]
+
+
+def lcode_install(prefix: Path | None = None, direct_url: str | None = None) -> Install:
+    """How this lcode was installed."""
+    prefix = (prefix or Path(sys.prefix)).resolve()
+    if direct_url is None:
+        try:
+            direct_url = importlib.metadata.distribution("lcode-cli").read_text("direct_url.json") or ""
+        except importlib.metadata.PackageNotFoundError:
+            direct_url = ""
+    try:
+        origin = json.loads(direct_url) if direct_url else {}
+    except ValueError:
+        origin = {}
+    if (origin.get("dir_info") or {}).get("editable") and str(origin.get("url", "")).startswith("file://"):
+        return Install("checkout", path=Path(urlsplit(origin["url"]).path))
+    text = str(prefix)
+    if (prefix / "uv-receipt.toml").exists():
+        return Install("uv", ["uv", "tool", "upgrade", "lcode-cli"])
+    if "/Cellar/lcode/" in text:
+        return Install("brew", ["brew", "upgrade", "nasser1941/tap/lcode"])
+    if "pipx" in prefix.parts:
+        return Install("pipx", ["pipx", "upgrade", "lcode-cli"])
+    if "/uv/" in text and ("archive-v" in text or "/cache/" in text or "/.cache/" in text):
+        return Install("uvx")
+    return Install("pip", [sys.executable, "-m", "pip", "install", "--upgrade", "lcode-cli"])
+
+
+@dataclass
+class CheckoutState:
+    branch: str
+    dirty: bool
+    behind: int
+    upstream: str
+
+
+def checkout_state(path: Path) -> CheckoutState:
+    def git(*args: str) -> str:
+        r = run(["git", "-C", str(path), *args], timeout=120)
+        if r.returncode != 0:
+            raise UpdateError(f"git {args[0]} failed in {path}: {(r.stderr or r.stdout).strip()[:200]}")
+        return r.stdout.strip()
+
+    branch = git("rev-parse", "--abbrev-ref", "HEAD")
+    dirty = bool(git("status", "--porcelain", "--untracked-files=no"))
+    upstream = run(["git", "-C", str(path), "rev-parse", "--abbrev-ref", "@{upstream}"]).stdout.strip()
+    behind = 0
+    if upstream:
+        git("fetch", "-q")
+        behind = int(git("rev-list", "--count", "HEAD..@{upstream}") or 0)
+    return CheckoutState(branch, dirty, behind, upstream)
+
+
+def update_checkout(path: Path, install_receipt: bool) -> str:
+    """git pull a checkout lcode runs from; reinstall its environment when its dependencies changed."""
+    before = run(["git", "-C", str(path), "rev-parse", "HEAD"]).stdout.strip()
+    if stream(["git", "-C", str(path), "pull", "--ff-only"]) != 0:
+        raise UpdateError(f"git pull failed in {path}")
+    changed = run(["git", "-C", str(path), "diff", "--name-only", before, "HEAD"]).stdout.split()
+    reinstall = ["uv", "tool", "install", "--force", "--editable", str(path)]
+    if "pyproject.toml" in changed and install_receipt and stream(reinstall) != 0:
+        raise UpdateError("reinstalling lcode's environment failed: run  uv tool install --force --editable .")
+    count = run(["git", "-C", str(path), "rev-list", "--count", f"{before}..HEAD"]).stdout.strip() or "0"
+    return f"{count} new commit(s)"
+
+
+# ----------------------------------------------------------------------------- Ollama in Docker
+
+
+@dataclass
+class Container:
+    id: str
+    name: str
+    image: str  # as configured, e.g. ollama/ollama:latest
+    info: dict = field(repr=False)
+
+    @property
+    def compose(self) -> dict | None:
+        labels = (self.info.get("Config") or {}).get("Labels") or {}
+        project, service = labels.get("com.docker.compose.project"), labels.get("com.docker.compose.service")
+        if not project or not service:
+            return None
+        files = [f for f in str(labels.get("com.docker.compose.project.config_files", "")).split(",") if f]
+        return {"project": project, "service": service, "files": files,
+                "workdir": labels.get("com.docker.compose.project.working_dir", "")}  # fmt: skip
+
+
+def docker_available() -> bool:
+    return shutil.which("docker") is not None and run(["docker", "info", "--format", "{{.ID}}"]).returncode == 0
+
+
+def find_container(host: str) -> Container | None:
+    """The Ollama container that serves `host` (a local address), if Ollama runs in Docker."""
+    parts = urlsplit(host)
+    if parts.hostname not in ("localhost", "127.0.0.1", "::1", "0.0.0.0", None):
+        return None
+    port = str(parts.port or 11434)
+    ids = run(["docker", "ps", "-q"]).stdout.split()
+    if not ids:
+        return None
+    infos = json.loads(run(["docker", "inspect", *ids]).stdout or "[]")
+    found = []
+    for info in infos:
+        image = (info.get("Config") or {}).get("Image", "")
+        if not image.startswith(IMAGE):
+            continue
+        bindings = ((info.get("HostConfig") or {}).get("PortBindings") or {}).get("11434/tcp") or []
+        if any(str(b.get("HostPort")) == port for b in bindings):
+            found.append(Container(info["Id"][:12], info["Name"].lstrip("/"), image, info))
+    return found[0] if len(found) == 1 else None
+
+
+def set_compose_image(text: str, service: str, image: str) -> tuple[str, str]:
+    """The compose file with the service's image changed, and the image it had."""
+    lines = text.splitlines(keepends=True)
+    services = next((i for i, line in enumerate(lines) if re.match(r"services:\s*(#.*)?$", line)), None)
+    if services is None:
+        raise UpdateError("no services: section")
+    start = indent = None
+    for i in range(services + 1, len(lines)):
+        m = re.match(rf"(\s+)['\"]?{re.escape(service)}['\"]?:\s*(#.*)?$", lines[i])
+        if m:
+            start, indent = i, len(m.group(1))
+            break
+        if lines[i].strip() and not lines[i][0].isspace() and not lines[i].lstrip().startswith("#"):
+            break  # the next top-level key: services ended
+    if start is None or indent is None:
+        raise UpdateError(f"no service {service} in it")
+    for i in range(start + 1, len(lines)):
+        line = lines[i]
+        if line.strip() and not line.lstrip().startswith("#") and len(line) - len(line.lstrip()) <= indent:
+            break  # the next service
+        m = re.match(r"(\s+image:\s*)(['\"]?)([^'\"#\s]+)\2(\s*(#.*)?)$", line.rstrip("\n"))
+        if m:
+            if "${" in line:
+                raise UpdateError(f"the image comes from a variable ({m.group(3)}): set it to {image}")
+            newline = "\n" if line.endswith("\n") else ""
+            lines[i] = f"{m.group(1)}{m.group(2)}{image}{m.group(2)}{m.group(4)}{newline}"
+            return "".join(lines), m.group(3)
+    raise UpdateError(f"service {service} has no image: line (it may be built from a Dockerfile)")
+
+
+def run_args(info: dict, image_info: dict, image: str) -> list[str]:
+    """`docker run` arguments that recreate a container with another image and the same settings."""
+    config, host = info.get("Config") or {}, info.get("HostConfig") or {}
+    base = image_info.get("Config") or {}
+    args = ["docker", "run", "-d", "--name", info["Name"].lstrip("/")]
+    restart = host.get("RestartPolicy") or {}
+    if restart.get("Name") not in (None, "", "no"):
+        retries = restart.get("MaximumRetryCount") or 0
+        args += ["--restart", restart["Name"] + (f":{retries}" if restart["Name"] == "on-failure" and retries else "")]
+    for port, bindings in (host.get("PortBindings") or {}).items():
+        target = port.removesuffix("/tcp")
+        for b in bindings or []:
+            ip = b.get("HostIp") or ""
+            args += ["-p", f"{ip + ':' if ip else ''}{b.get('HostPort', '')}:{target}"]
+    for m in info.get("Mounts") or []:
+        source = m.get("Name") if m.get("Type") == "volume" else m.get("Source")
+        if source and m.get("Type") in ("volume", "bind"):
+            args += ["-v", f"{source}:{m['Destination']}" + ("" if m.get("RW", True) else ":ro")]
+    default_env = set(base.get("Env") or [])
+    for entry in config.get("Env") or []:
+        if entry not in default_env:  # only what was set for this container; the new image brings its own PATH
+            args += ["-e", entry]
+    for request in host.get("DeviceRequests") or []:
+        if ["gpu"] in (request.get("Capabilities") or []):
+            ids = request.get("DeviceIDs") or []
+            count = request.get("Count") or 0
+            args += ["--gpus", f"device={','.join(ids)}" if ids else ("all" if count == -1 else str(count))]
+    for device in host.get("Devices") or []:
+        args += ["--device", f"{device['PathOnHost']}:{device['PathInContainer']}"]
+    if host.get("Runtime") not in (None, "", "runc"):
+        args += ["--runtime", host["Runtime"]]
+    network = host.get("NetworkMode") or "default"
+    if network not in ("default", "bridge") and not network.startswith("container:"):
+        args += ["--network", network]
+        endpoint = ((info.get("NetworkSettings") or {}).get("Networks") or {}).get(network) or {}
+        name, short_id = info["Name"].lstrip("/"), info["Id"][:12]
+        for alias in endpoint.get("Aliases") or []:
+            if alias not in (name, short_id):
+                args += ["--network-alias", alias]
+    for host_entry in host.get("ExtraHosts") or []:
+        args += ["--add-host", host_entry]
+    base_labels = base.get("Labels") or {}
+    for key, value in (config.get("Labels") or {}).items():
+        if base_labels.get(key) != value:
+            args += ["--label", f"{key}={value}"]
+    entrypoint, cmd = config.get("Entrypoint") or [], config.get("Cmd") or []
+    if entrypoint and entrypoint != (base.get("Entrypoint") or []):
+        args += ["--entrypoint", entrypoint[0]]
+        cmd = [*entrypoint[1:], *cmd]
+    elif cmd == (base.get("Cmd") or []):
+        cmd = []
+    return [*args, image, *cmd]
+
+
+def wait_for_version(host: str, wanted: str, timeout: float = START_TIMEOUT) -> bool:
+    from lcode.ollama import Ollama, OllamaError
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            if Ollama(host).version() == wanted.removesuffix("-rocm"):
+                return True
+        except OllamaError:
+            pass
+        time.sleep(2)
+    return False
+
+
+def recreate(container: Container, image: str, host: str, say: Callable[[str], None]) -> None:
+    """Replace a plain container with one on `image`; put the old one back if that fails."""
+    image_info = json.loads(run(["docker", "image", "inspect", container.info["Image"]]).stdout or "[{}]")[0]
+    args = run_args(container.info, image_info, image)
+    backup = f"{container.name}-before-lcode-update"
+    for step in (["docker", "stop", container.name], ["docker", "rename", container.name, backup]):
+        r = run(step)
+        if r.returncode != 0:
+            raise UpdateError(f"{' '.join(step[:2])} failed: {(r.stderr or r.stdout).strip()}")
+    say(f"$ {' '.join(args)}")
+    started = run(args)
+    if started.returncode == 0 and wait_for_version(host, image.rsplit(":", 1)[1]):
+        run(["docker", "rm", backup])
+        return
+    problem = (started.stderr or started.stdout).strip() or "it didn't answer with the new version"
+    run(["docker", "rm", "-f", container.name])
+    run(["docker", "rename", backup, container.name])
+    run(["docker", "start", container.name])
+    raise UpdateError(f"the new container didn't start ({problem[:300]}); the old one is running again")
+
+
+def recreate_with_compose(container: Container, image: str, host: str, say: Callable[[str], None]) -> None:
+    command, project_dir = compose_up(container.compose or {})
+    say(f"$ {' '.join(command)}")
+    if stream(command, cwd=project_dir) != 0:
+        raise UpdateError("docker compose up failed")
+    if not wait_for_version(host, image.rsplit(":", 1)[1]):
+        raise UpdateError(f"Ollama didn't answer with version {image.rsplit(':', 1)[1]} after the restart")
+
+
+def compose_up(compose: dict) -> tuple[list[str], Path]:
+    """`docker compose up` for just the Ollama service of its project, and where to run it."""
+    files = [Path(f) for f in compose["files"]]
+    project_dir = Path(compose["workdir"]) if compose.get("workdir") else files[0].parent
+    command = ["docker", "compose", "-p", compose["project"], "--project-directory", str(project_dir)]
+    for f in files:
+        command += ["-f", str(f)]
+    return [*command, "up", "-d", "--no-deps", compose["service"]], project_dir
+
+
+def compose_change(container: Container, image: str) -> tuple[Path, str, str]:
+    """Which compose file defines the service's image, and its new text."""
+    compose = container.compose or {}
+    problems = []
+    for path in reversed([Path(f) for f in compose.get("files") or []]):  # later files override earlier ones
+        try:
+            text, old = set_compose_image(path.read_text(), compose["service"], image)
+            return path, text, old
+        except (OSError, UpdateError) as e:
+            problems.append(f"{path}: {e}")
+    raise UpdateError("couldn't find the image to change: " + "; ".join(problems))
+
+
+# ----------------------------------------------------------------------------- lcode update
+
+
+def command(console, what: str = "", check: bool = False, yes: bool = False) -> int:
+    """Update lcode and Ollama (or `what`: "lcode" or "ollama"). Returns the exit code."""
+    from rich.prompt import Confirm
+
+    def ask(question: str) -> bool:
+        if yes:
+            return True
+        if not sys.stdin.isatty():
+            console.print("[dim]Not asking without a terminal: run lcode update -y to go ahead.[/]")
+            return False
+        return Confirm.ask(question, default=True, console=console)
+
+    failed = False
+    for part, step in (("lcode", update_lcode), ("ollama", update_ollama)):
+        if what and what != part:
+            continue
+        try:
+            step(console, check, ask)
+        except UpdateError as e:
+            console.print(f"[red]✗ {escape(str(e))}[/]")
+            failed = True
+        console.print()
+    return 1 if failed else 0
+
+
+def escape(text: str) -> str:
+    from rich.markup import escape as rich_escape
+
+    return rich_escape(text)
+
+
+def update_lcode(console, check: bool, ask: Callable[[str], bool]) -> None:
+    install = lcode_install()
+    if install.kind == "checkout" and install.path is not None:
+        state = checkout_state(install.path)
+        where = f"lcode {__version__} · {install.describe()}, branch {state.branch}"
+        if not state.upstream:
+            console.print(f"{where}: no upstream branch to update from.")
+        elif not state.behind:
+            console.print(f"[green]✓[/] {where}: up to date with {state.upstream}.")
+        elif check:
+            console.print(f"{where}: {state.behind} new commit(s) on {state.upstream}.")
+        elif state.dirty or state.branch not in ("main", "master"):
+            why = "has uncommitted changes" if state.dirty else f"is on branch {state.branch}"
+            console.print(
+                f"{where}: {state.behind} new commit(s) on {state.upstream}, but the checkout {why}. Update it yourself with git pull."
+            )
+        elif ask(f"Pull {state.behind} new commit(s) into {install.path}?"):
+            receipt = (Path(sys.prefix) / "uv-receipt.toml").exists()
+            console.print(f"[green]✓[/] lcode updated: {update_checkout(install.path, receipt)}.")
+        return
+    latest = latest_lcode()
+    if version_key(latest) <= version_key(__version__):
+        console.print(f"[green]✓[/] lcode {__version__} is the newest version ({install.describe()}).")
+        return
+    if install.command is None:
+        console.print(
+            f"lcode {__version__} → {latest} is out. You run lcode with uvx: use  uvx --refresh --from lcode-cli lcode"
+        )
+        return
+    shown = " ".join(install.command)
+    if check:
+        console.print(f"lcode {__version__} → {latest} is out ({install.describe()}): {shown}")
+        return
+    if not ask(f"Update lcode {__version__} → {latest} with `{shown}`?"):
+        return
+    if stream(install.command) != 0:
+        raise UpdateError(f"{shown} failed")
+    console.print("[green]✓[/] lcode updated; the new version runs from the next `lcode`.")
+    if install.kind == "brew":
+        console.print(
+            "[dim]Homebrew's formula follows a release by up to a day: if it's still the old version, try again later.[/]"
+        )
+
+
+def update_ollama(console, check: bool, ask: Callable[[str], bool]) -> None:
+    from lcode import config
+    from lcode.hardware import detect
+    from lcode.ollama import Ollama, OllamaError
+
+    cfg = config.load()
+    if cfg["backend"] != "ollama":
+        console.print(f"lcode uses another model server (backend = {cfg['backend']}): update it there.")
+        return
+    host = cfg["ollama_host"]
+    try:
+        current = Ollama(host).version()
+    except OllamaError:
+        current = ""
+    container = find_container(host) if docker_available() else None
+    if container is None:
+        if not current:
+            raise UpdateError(f"Ollama doesn't answer at {host}: start it, then run lcode update again")
+        latest = latest_ollama()
+        local = urlsplit(host).hostname in ("localhost", "127.0.0.1", "::1", "0.0.0.0", None)
+        if version_key(latest) <= version_key(current):
+            console.print(f"[green]✓[/] Ollama {current} is the newest version.")
+        elif not local:
+            console.print(f"Ollama {current} → {latest} is out. It runs on {host}: update it on that machine.")
+        else:
+            hint = NATIVE.get(detect().os, NATIVE["linux"])
+            console.print(
+                f"Ollama {current} → {latest} is out. Ollama isn't in a Docker container here, so update it with:\n  {hint}"
+            )
+        return
+    latest = latest_ollama(image_flavor(container.image))
+    image = f"{IMAGE}:{latest}"
+    compose = container.compose
+    where = f"container {container.name}, image {container.image}" + (
+        f", Docker Compose project {compose['project']}" if compose else ""
+    )
+    console.print(f"Ollama {current or '?'} · {where}. Newest on Docker Hub: {latest}.")
+    if container.image == image and current == latest.removesuffix("-rocm"):
+        console.print(f"[green]✓[/] Ollama is up to date, on {image}.")
+        return
+    if current == latest.removesuffix("-rocm"):
+        console.print(
+            f"[dim]It already runs {current}, but as {container.image}: pinning it to {image} shows the version in docker ps.[/]"
+        )
+    change = compose_change(container, image) if compose else None
+    plan = [f"docker pull {image}"]
+    if change:
+        path, _, old = change
+        plan.append(f"in {path}, service {compose['service']}: image {old} → {image}")  # type: ignore[index]
+        plan.append(f"docker compose up -d --no-deps {compose['service']}")  # type: ignore[index]
+    else:
+        plan.append(
+            f"recreate container {container.name} on {image}, with the same name, ports, volumes, environment, GPUs, network and restart policy (the old one is kept until the new one answers)"
+        )
+    console.print("\n".join(f"  {i}. {escape(step)}" for i, step in enumerate(plan, 1)))
+    if check:
+        return
+    console.print("[dim]Ollama restarts: requests running now stop, and models load again on their next request.[/]")
+    if not ask("Update Ollama?"):
+        return
+    if stream(["docker", "pull", image]) != 0:
+        raise UpdateError(f"docker pull {image} failed")
+
+    def say(text: str) -> None:
+        console.print(f"[dim]{escape(text)}[/]")
+
+    if change:
+        path, text, _ = change
+        original = path.read_text()
+        path.write_text(text)
+        try:
+            recreate_with_compose(container, image, host, say)
+        except UpdateError:
+            path.write_text(original)
+            say(f"put {path} back the way it was")
+            command, workdir = compose_up(compose)  # type: ignore[arg-type]
+            stream(command, cwd=workdir)
+            raise
+    else:
+        recreate(container, image, host, say)
+    console.print(f"[green]✓[/] Ollama {current or '?'} → {latest.removesuffix('-rocm')}, running as {image}.")
+    old_image = container.info.get("Image", "")
+    if old_image and not run(["docker", "ps", "-aq", "--filter", f"ancestor={old_image}"]).stdout.strip():
+        size = run(["docker", "image", "inspect", old_image, "--format", "{{.Size}}"]).stdout.strip()
+        gb = f" ({int(size) / 1e9:.1f} GB)" if size.isdigit() else ""
+        console.print(
+            f"[dim]The previous image is still on disk{gb}. To remove it: docker image rm {old_image[7:19]}[/]"
+        )

{lcode_cli-0.19.0.dist-info → lcode_cli-0.21.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.19.0
+Version: 0.21.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/
@@ -216,7 +216,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [Long-running work: finish notifications and background commands](https://github.com/nasser1941/lcode/issues/51)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))
 
 ## Contributing

{lcode_cli-0.19.0.dist-info → lcode_cli-0.21.0.dist-info}/RECORD

@@ -1,37 +1,40 @@
-lcode/__init__.py,sha256=7yjbvkgWF_Vh6y72kETMa3SVkh4RP81rLJzvo11gIV8,473
+lcode/__init__.py,sha256=CcNLwxNc-qPLNMDrdZMe5h6rRYH_9ISij5uyXwc5PBA,473
 lcode/__main__.py,sha256=s5N5pryX2FAu93GGZ3FxUrIXHWGzxz66lKUoaV_h8Ws,35
-lcode/acp.py,sha256=M_CdTVqRSmLn33QD56Le4238Vz1ZxffnHCfjmajSv34,28940
+lcode/acp.py,sha256=kRD_uuDDdGXt7xwvXZ8OqePK1HprEV76wWAWkV_gcak,28987
 lcode/action.py,sha256=1r3abjheYFYQ-EUArvotls8pLmE3YjNMGHAy_iF0Z70,16198
-lcode/agent.py,sha256=pB7rDZIbWiRrc8Ye4rA_LzHVqJ36yoTUN6nFsUeg428,49664
-lcode/api.py,sha256=kXlzXhGwkNdW9sWpxgOvL9h5pPzhzKRLXKrL1-eN3XY,15110
+lcode/agent.py,sha256=FgZJpGD1a46qaa1nixZYXS3rPaFaJgnGpfoUi7ikhGY,51106
+lcode/api.py,sha256=rOpcA2-axzUj_DppH3EelanVnwd-2O4MgN91OXGJePY,15250
 lcode/backends.py,sha256=dtJHrC6ys73bRDg64z0tQz1PavmeAkiODZu1fOO9ExQ,20635
 lcode/bench.py,sha256=XVdk0hDxmRcjgROOCgwwOsExcUhIxgh0B2vnxtGnA3o,40742
 lcode/bench_backend.py,sha256=X2fo-zRX92Xp3KMxSsFlWioc2vRupBTtowj5kLME8mw,14287
 lcode/catalog.py,sha256=pZ1azX9OH2r4JE2c6E5OfwywpgS39-W2oXzoCHJhmtM,4141
 lcode/checkpoints.py,sha256=eqPtmPe44-aweWqc2H21ROogwzIt3NpvcUobsaCHoGY,18354
-lcode/cli.py,sha256=zo2QTHrdxVaJwIjCEOsfR99byPqeCkKHE5p_Xh8kfb8,39471
+lcode/cli.py,sha256=ue5wsoFxraXXVu7X32S4tbKPLKYhgeI6zpK2i5nXXlU,40180
 lcode/codesearch.py,sha256=Io8leN1nb_Y-Dvlm9xaGtwUWYXX-ooswuznJV6dGU1s,10766
-lcode/config.py,sha256=nFljzjHTFaCTTbagycagbh2X_PpLtsUs-yRODiy4QcU,10065
+lcode/config.py,sha256=eDEvOAA1plsSjvihzHEwGjNVgvcz3Pb-AR5DY5JmXnM,10255
 lcode/context.py,sha256=qJymLE3eYeaF6qVOzlUwDURqlky__8cskl_6vXeU3AA,10701
 lcode/extensions.py,sha256=W0HFDl0BvROzr7i_qtabHdIbacBgP5o5qIJLzoM2oNE,16806
 lcode/frontmatter.py,sha256=Bx0n4vLPhp7ZCWx-g7xqzqNy5VoKBxyeeikh5UFB_gA,2441
 lcode/gitflow.py,sha256=y78dqqh80is-MiDTnSHnK9vjx0vFovor_SZ8hW1NJaU,27167
 lcode/hardware.py,sha256=2VbknZCxTZJwJUD8YWdQ7ryEQo_LcjtoOBOHOU9Y0fw,3085
 lcode/hooks.py,sha256=K0itOiAuH4rxndJ9gne_uCrqby6oWAzFPRrfB3tCq-E,9324
+lcode/jobs.py,sha256=P1P3FqI6EqL4LgdMX9YGZwCW0Bh5BRXFA_FnQxpHNjE,5618
 lcode/limits.py,sha256=oJzVQoMyTZ0_Fkpu5t3qxrf9v7Hv9S8U8BRQR5M1aKA,1237
 lcode/lsp.py,sha256=NtSW7xapv7fg2HAQLuYK1nwIqT7nG0LK1hiTpOmla_4,26086
 lcode/memory.py,sha256=WZEHTp-lVxAwS-yyLQR2xB3TMZ9sejmX2Ivg7T-tl3w,21949
 lcode/models.toml,sha256=lt2G64zzo_Ryxv2ISRSNZoVD_JqCqYqsM01n8WoXGs8,4098
+lcode/notify.py,sha256=uieDeXe7XwuVHjOk4tqVyZEW_85XWkoWQmFOWEf77oc,1538
 lcode/ollama.py,sha256=u5tnvL28cfaFS4GhmiEsHhTQe6w3Ng_Tej05UUzLQTQ,7715
 lcode/permissions.py,sha256=i04YLtqYCxwApgawomPp4d35uk9HAJtpKY__gfw8j9s,6347
-lcode/planning.py,sha256=mGXMU-khHyGHE8IHxxrsQc-FFOzbdRa4MWHMU19UR7o,6439
+lcode/planning.py,sha256=Q2upaoZPnXDMQT2F-ETxX1lk_wDntTzhSKNVYIQSoQA,6540
 lcode/render.py,sha256=gMvf4W3qkLUJ4Vot3az_hP_zRDAItJC9pP-68dHFkfA,1375
-lcode/repl.py,sha256=zJ2hj1c-tx35Sms8V-1W4XsyfFZ9omu9bZgGpEgBYi8,47655
+lcode/repl.py,sha256=pQAPePNsBxJfcuif2Cvyxr0FSeO_DVGv_T5cL9BrWu4,48470
 lcode/repomap.py,sha256=1GRJgEUjBl9XHSXsF7tSGXBCEgsY-3CzwMohaTudZ_M,13969
 lcode/sandbox.py,sha256=u_pkrVRXhCGhh-wFDPwuZ3jGG7UeXxXRAeBNsm37ZvE,8608
 lcode/sessions.py,sha256=wOR-J0EHgJxLSPboKPHnvBcp5VTUYTj3tZWgpsa6-K4,4013
-lcode/subagents.py,sha256=S_ZBpqnKFxRKhe-lE-I8SHc3yMOhe0zW-SD2K-Gwn28,28832
-lcode/tools.py,sha256=Y4XmQsoLIA32S255DnCwOwebGPgQay1k7H_A9R5DINA,43145
+lcode/subagents.py,sha256=rD7lnIioodirh8eVnXvRWdZx79J_rscPLssD2Gt7KIo,28914
+lcode/tools.py,sha256=pOdA4ihQHSs8yWUzfxhiLw3GajF5Dr1edxVX0Akr6CU,47257
+lcode/update.py,sha256=i92bnW252VneYh0vD6djxmXsDOa5MXP20bjlLZUue_c,25236
 lcode/vision.py,sha256=w33QPmdGwP33wM4mvmAH4amFDZ1xzeXhEsSLJ-STSHY,4243
 lcode/web.py,sha256=vyxKbSRJTl1Lj3hj7Yd_NwTgbv0Xi6dup2YfUXjqp-Y,14579
 lcode/mcp/__init__.py,sha256=XujtAmRoXW9S0uq1XPf_CAeCkHh_UvA8FCmoAKP9j1Y,171
@@ -49,8 +52,8 @@ lcode/mcp/stdio.py,sha256=kC6KHwzMMDjBr-yCZLmyVKS7PZXU299WpZdYRoX5eRQ,6292
 lcode/servers/__init__.py,sha256=qrIhxEodEB8cjKEQ4Cicc0GsQhE2OH-9qlVHzr3-tq8,77
 lcode/servers/encord.py,sha256=WSauawL1UKYZCUAG1oalcKL_An3DVof-JM6xIgFyQSE,12769
 lcode/servers/valohai.py,sha256=e5xZGIoa4cja4f5i85q1GpL9c7cglUjV8jN2co1CFMY,14430
-lcode_cli-0.19.0.dist-info/METADATA,sha256=cUJGqerCzNU65yzxUbn48STtIOP3fjvVbItArdo1vJ4,12642
-lcode_cli-0.19.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-lcode_cli-0.19.0.dist-info/entry_points.txt,sha256=pMz2Byj2QRyt-ZZQYZvmWUtmKPCeE7f8iCvu-sjZPIo,133
-lcode_cli-0.19.0.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
-lcode_cli-0.19.0.dist-info/RECORD,,
+lcode_cli-0.21.0.dist-info/METADATA,sha256=5G93iKQq-92dbzpKJxamXKr9giXtXiVm0AsqhcJf4NU,12527
+lcode_cli-0.21.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lcode_cli-0.21.0.dist-info/entry_points.txt,sha256=pMz2Byj2QRyt-ZZQYZvmWUtmKPCeE7f8iCvu-sjZPIo,133
+lcode_cli-0.21.0.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
+lcode_cli-0.21.0.dist-info/RECORD,,