@giamme/forge 0.9.0 → 0.10.0

package/scripts/forge-runs.py

@@ -7,6 +7,10 @@ run dir under it, so you can see what happened without a browser and get the dir
 or open with `forge ui open`. The repo is the Git top level of the current directory unless
 `--repo` names one; `--all` lists the runs of every repo. It reads the same run summaries as
 forge-ui and never writes anything.
+
+`forge runs rm <run-dir> [--dry-run] [--yes] [--no-archive] [--worktrees] [--branches] [--json]`
+is the one thing here that changes anything: it deletes a run, after its traces are in the dataset
+and an archive exists (scripts/forge-runs-rm.py).
 """
 from __future__ import annotations
 
@@ -86,8 +90,22 @@ def line(run: dict, now: float, with_repo: bool = False) -> str:
     return f"{run['run_id'] or run['key']}  {run['kind']}{repo}  {age(run['updated'], now)}  {counts}{checks}  {goal}\n    {run['path']}"
 
 
+def remove(argv) -> int:
+    """`forge runs rm`: loaded on demand, so listing never pays for the dataset package."""
+    import importlib.util
+    spec = importlib.util.spec_from_file_location('forge_runs_rm', Path(__file__).resolve().with_name('forge-runs-rm.py'))
+    module = importlib.util.module_from_spec(spec)
+    sys.modules['forge_runs_rm'] = module
+    spec.loader.exec_module(module)
+    return module.main(argv)
+
+
 def main(argv=None) -> int:
-    parser = argparse.ArgumentParser(prog='forge runs', description="This repo's recent forge runs, newest first. Read-only.")
+    argv = sys.argv[1:] if argv is None else list(argv)
+    if argv[:1] == ['rm']:
+        return remove(argv[1:])
+    parser = argparse.ArgumentParser(prog='forge runs', description="This repo's recent forge runs, newest first. Listing is read-only.",
+                                     epilog='Delete a run, keeping its traces: forge runs rm <run-dir> (forge runs rm --help)')
     which = parser.add_mutually_exclusive_group()
     which.add_argument('--repo', type=Path, metavar='DIR', help='the repo whose runs to list (default: the Git top level of the current directory)')
     which.add_argument('--all', action='store_true', help='list the runs of every repo')

package/scripts/forge-schedule.py

@@ -10,17 +10,26 @@ Two opt-in behaviours live here, both off by default so a plain `run` is unchang
   network, empty output) up to M times instead of stopping. Without it the scheduler
   stops dispatching, lets running tasks drain and exits 8: nothing was the task's fault
   and no attempt was spent, so the next `run` simply resumes.
+
+Both numbers are per invocation, but while the scheduler runs they are mirrored into the
+plan dir (retry_budget, infra_budget, tasks/<id>/retry_budget) and re-read at every
+decision, so `forge control` can change them mid-run. See "live control files" below.
 """
 from __future__ import annotations
 
 import argparse
+import contextlib
+import errno
 import fcntl
+import json
 import os
 from pathlib import Path
 import posixpath
 import signal
+import stat
 import subprocess
 import sys
+import tempfile
 import time
 
 
@@ -80,6 +89,157 @@ def infra_wait(info: dict, cycle: int) -> float:
     return min(base * (2 ** cycle), max(base, 1800.0))
 
 
+# --- live control files ------------------------------------------------------------------
+# Created at start and removed at exit, so a later `run` never inherits a budget it did not
+# ask for. Writers replace files atomically, so readers need no lock; the control lock only
+# orders a lifecycle write against `forge control`'s liveness check. It is never held across
+# a model dispatch and never taken together with schedule.lock.
+CONTROL_LOCK_WAIT = 5.0   # seconds; a busy lock must never fail a run
+SWEEP_EVERY = 1.0         # seconds between looks at tasks that already ended FAIL/UNKNOWN
+
+
+def _warn(message: str) -> None:
+    print('forge: ' + message, file=sys.stderr, flush=True)
+
+
+def _task_id_ok(name: str) -> bool:
+    return bool(name) and name not in ('.', '..') and '/' not in name and '\0' not in name
+
+
+def _resolve(plan: object, *parts: str) -> str:
+    """plan/<parts> if every directory on the way is a real one (no symlink) inside the
+    canonical plan dir and an existing target is a regular file. OSError otherwise."""
+    if not all(_task_id_ok(part) for part in parts):
+        raise OSError(errno.EINVAL, 'invalid path component', '/'.join(parts))
+    path = os.path.realpath(plan)
+    for part in parts[:-1]:
+        path = os.path.join(path, part)
+        if not stat.S_ISDIR(os.lstat(path).st_mode):
+            raise OSError(errno.ENOTDIR, 'not a real directory', path)
+    path = os.path.join(path, parts[-1])
+    try:
+        if not stat.S_ISREG(os.lstat(path).st_mode):
+            raise OSError(errno.EPERM, 'not a regular file', path)
+    except FileNotFoundError:
+        pass
+    return path
+
+
+def _write_atomic(plan: object, text: str, *parts: str) -> bool:
+    """Temp file in the same directory, then rename. A failure warns and returns False."""
+    tmp = None
+    try:
+        path = _resolve(plan, *parts)
+        fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path), prefix='.' + parts[-1] + '.')
+        with os.fdopen(fd, 'w') as handle:
+            os.fchmod(handle.fileno(), 0o644)
+            handle.write(text)
+        os.replace(tmp, path)
+        return True
+    except OSError as error:
+        _warn('could not write ' + '/'.join(parts) + ': ' + str(error))
+        if tmp:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+        return False
+
+
+def _remove(plan: object, *parts: str) -> None:
+    try:
+        os.unlink(_resolve(plan, *parts))
+    except FileNotFoundError:
+        pass
+    except OSError as error:
+        _warn('could not remove ' + '/'.join(parts) + ': ' + str(error))
+
+
+def _read_budget(plan: object, *parts: str) -> int | None:
+    """A non-negative integer from a control file; None when it is missing, empty, a
+    symlink or anything else, so the caller falls through to its next source."""
+    try:
+        fd = os.open(_resolve(plan, *parts), os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        try:
+            data = os.read(fd, 65)
+        finally:
+            os.close(fd)
+        text = data.decode('ascii').strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+    return int(text) if len(data) <= 64 and text.isdigit() else None
+
+
+@contextlib.contextmanager
+def _control_lock(plan: object):
+    """flock on control.lock, retried for CONTROL_LOCK_WAIT seconds. On timeout or any
+    error: warn and proceed without it (yielding False), never fail the run."""
+    fd = None
+    try:
+        fd = os.open(_resolve(plan, 'control.lock'), os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o644)
+        deadline = time.monotonic() + CONTROL_LOCK_WAIT
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise OSError(errno.EWOULDBLOCK, 'busy for ' + ('%g' % CONTROL_LOCK_WAIT) + 's')
+                time.sleep(0.05)
+    except OSError as error:
+        _warn('control.lock not taken, continuing without it: ' + str(error))
+        if fd is not None:
+            os.close(fd)
+            fd = None
+    try:
+        yield fd is not None
+    finally:
+        if fd is not None:
+            os.close(fd)
+
+
+def _task_dirs(plan: object, names: object) -> list[str]:
+    """The planned tasks plus any other task dir, since `forge control` accepts an id
+    that is not in tasks.tsv and its file must not outlive the invocation either."""
+    found = set(names)
+    try:
+        with os.scandir(os.path.join(os.path.realpath(plan), 'tasks')) as entries:
+            found.update(e.name for e in entries if _task_id_ok(e.name) and e.is_dir(follow_symlinks=False))
+    except OSError:
+        pass
+    return sorted(found)
+
+
+def _pinned(plan: object, name: str) -> bool:
+    try:
+        return os.path.lexists(_resolve(plan, 'tasks', name, 'escalation.pin'))
+    except OSError:
+        return False
+
+
+def live_start(plan: object, names: object, retry_failed: int, infra_retries: int) -> None:
+    """Publish the flags and that this scheduler is live. Stale per-task overrides and
+    usage counters from an earlier invocation go first."""
+    with _control_lock(plan):
+        for name in _task_dirs(plan, names):
+            _remove(plan, 'tasks', name, 'retry_budget')
+            _remove(plan, 'tasks', name, 'retries.used')
+        _write_atomic(plan, str(retry_failed), 'retry_budget')
+        _write_atomic(plan, str(infra_retries), 'infra_budget')
+        _write_atomic(plan, json.dumps({'pid': os.getpid(), 'started': time.time()}), 'scheduler.live')
+
+
+def live_stop(plan: object, names: object) -> None:
+    """Withdraw liveness first, then every budget. retries.used stays for the UI."""
+    try:
+        with _control_lock(plan):
+            _remove(plan, 'scheduler.live')
+            _remove(plan, 'retry_budget')
+            _remove(plan, 'infra_budget')
+            for name in _task_dirs(plan, names):
+                _remove(plan, 'tasks', name, 'retry_budget')
+    except Exception as error:
+        _warn('could not withdraw the live control files: ' + str(error))
+
+
 def schedule(script: str, plan: str, capacity: int, retry_failed: int = 0,
              infra_retries: int = 0) -> int:
     if capacity <= 0:
@@ -97,16 +257,18 @@ def schedule(script: str, plan: str, capacity: int, retry_failed: int = 0,
     if len(tasks) != len(rows):
         raise ValueError('duplicate task IDs')
     for name in tasks:
-        if not name or name in ('.', '..') or '/' in name:
+        if not _task_id_ok(name):
             raise ValueError('invalid task ID: ' + name)
         (plan / 'tasks' / name).mkdir(parents=True, exist_ok=True)
     active = {}
     pending = list(tasks)
     interrupted = False
     retries = {}       # automatic reviewer-driven retries used per task, this run
+    refused = {}       # task -> budget at the time its retry could not be prepared
     retried = set()    # tasks whose next dispatch is a retry (FORGE_FRACTAL_RETRY=1)
     offsets = {}       # how much of each task.out was already echoed under --output full
     infra_seen = []    # tasks stopped by an infrastructure failure, awaiting resume
+    held = set()       # INFRA tasks not resumed: their pin could not be applied
     infra_cycles = 0   # how many times this run already waited out an infrastructure pause
     paused = False     # an infrastructure failure was seen: dispatch nothing new
     resume_at = 0.0
@@ -127,30 +289,61 @@ def schedule(script: str, plan: str, capacity: int, retry_failed: int = 0,
         if result.returncode and status(name) == 'PASS':
             mark(name, 'ERROR')
 
+    def budget(name: str) -> int:
+        """Automatic retries this task may use. Read at every decision, never cached: the
+        task's own file, then the run-wide file, then the flag."""
+        for parts in (('tasks', name, 'retry_budget'), ('retry_budget',)):
+            value = _read_budget(plan, *parts)
+            if value is not None:
+                return value
+        return retry_failed
+
+    def infra_budget() -> int:
+        value = _read_budget(plan, 'infra_budget')
+        return infra_retries if value is None else value
+
     def retryable(name: str) -> bool:
+        root = plan / 'tasks' / name
         return (
-            retry_failed > 0
-            and retries.get(name, 0) < retry_failed
-            and status(name) in ('FAIL', 'UNKNOWN')
+            status(name) in ('FAIL', 'UNKNOWN')
+            and retries.get(name, 0) < budget(name)
             # A task that produced no new work (empty diff, byte-identical retry) would
             # only repeat itself; its marker says so and it is left for a human.
-            and not (plan / 'tasks' / name / 'noretry').exists()
+            and not (root / 'noretry').exists()
             # The retry policy found no stronger model after repeated failures on one: a
-            # split, or an explicit `retry --dwarf`, is the human's call.
-            and not (plan / 'tasks' / name / 'escalation.stop').exists()
+            # split, or an explicit `retry --dwarf`, is the human's call. A pin is exactly
+            # that call, made ahead of time: the next full retry applies it.
+            and (not (root / 'escalation.stop').exists() or _pinned(plan, name))
         )
 
     def requeue(name: str) -> bool:
         """Prepare a retry exactly as `retry` does, then put the task at the queue head."""
         result = subprocess.run(['/bin/bash', script, '_prepare_retry', str(plan), name])
         if result.returncode:
+            refused[name] = budget(name)
             return False
+        refused.pop(name, None)
         retries[name] = retries.get(name, 0) + 1
+        _write_atomic(plan, str(retries[name]), 'tasks', name, 'retries.used')
         retried.add(name)
         if name not in pending:
             pending.insert(0, name)
         print('forge: retrying ' + name + ' (automatic retry ' + str(retries[name]) + '/'
-              + str(retry_failed) + ')', file=sys.stderr, flush=True)
+              + str(budget(name)) + ')', file=sys.stderr, flush=True)
+        return True
+
+    def resume(name: str) -> bool:
+        """Prepare an INFRA task's next entry. Not a retry, so nothing is counted, but a
+        pending pin applies when that entry is a full implementer attempt. False when a
+        claimed pin could not be put in place: the task then stays INFRA, as `retry` would."""
+        if not _pinned(plan, name):
+            return True
+        result = subprocess.run(['/bin/bash', script, '_prepare_retry', str(plan), name, '--resume'])
+        if result.returncode:
+            held.add(name)
+            print('forge: ' + name + ' is not resumed: its escalation pin could not be applied',
+                  file=sys.stderr, flush=True)
+            return False
         return True
 
     def echo_output(name: str) -> None:
@@ -171,6 +364,7 @@ def schedule(script: str, plan: str, capacity: int, retry_failed: int = 0,
     signal.signal(signal.SIGTERM, stop)
     signal.signal(signal.SIGINT, stop)
     try:
+        live_start(plan, tasks, retry_failed, infra_retries)
         # Failures require an explicit retry unless this run asked for automatic ones.
         # Saved PASS results use the same fingerprint checks without paying for
         # implementation or QA again; an INFRA stop is not a failure of the work, so it
@@ -183,13 +377,19 @@ def schedule(script: str, plan: str, capacity: int, retry_failed: int = 0,
                 mark(name, 'INTERRUPTED')
             if state in ('FAIL', 'UNKNOWN') and retryable(name):
                 requeue(name)
+            if state == 'INFRA' and not resume(name):
+                pending.remove(name)
+                continue
             if status(name) not in ('PENDING', 'BLOCKED', 'INFRA'):
                 pending.remove(name)
+        swept = time.monotonic()
         while pending or active:
             if interrupted:
                 break
+            ended = set()
             for name, (process, log) in list(active.items()):
                 if process.poll() is not None:
+                    ended.add(name)
                     log.close()
                     del active[name]
                     if os.environ.get('FORGE_OUTPUT') == 'full':
@@ -205,7 +405,18 @@ def schedule(script: str, plan: str, capacity: int, retry_failed: int = 0,
                             infra_seen.append(name)
                     elif state in ('FAIL', 'UNKNOWN') and retryable(name):
                         requeue(name)
-            if paused and not active and infra_seen and infra_cycles < infra_retries:
+            if time.monotonic() - swept >= SWEEP_EVERY:
+                # A human can raise a budget after a task already ended FAIL while others
+                # still run. The initial pass's predicate, for tasks nothing else will look
+                # at again; one whose retry could not be prepared waits for a new budget.
+                swept = time.monotonic()
+                for name in tasks:
+                    if name in pending or name in active or name in ended:
+                        continue
+                    if status(name) in ('FAIL', 'UNKNOWN') and retryable(name) \
+                            and refused.get(name) != budget(name):
+                        requeue(name)
+            if paused and not active and infra_seen and infra_cycles < infra_budget():
                 # Everything running has drained. Wait out the outage once for all the
                 # tasks it stopped, then dispatch them again.
                 wait = max(infra_wait(infra_info(plan / 'tasks' / n), infra_cycles) for n in infra_seen)
@@ -218,8 +429,10 @@ def schedule(script: str, plan: str, capacity: int, retry_failed: int = 0,
                     time.sleep(min(0.05, max(resume_at - time.time(), 0)))
                 if interrupted:
                     break
+                # A pin set before or during the wait applies to the entries that run the
+                # implementer again; a QA-stage stop keeps it for the next full retry.
                 for name in reversed(infra_seen):
-                    if name not in pending:
+                    if name not in pending and resume(name):
                         pending.insert(0, name)
                 infra_seen.clear()
                 paused = False
@@ -249,15 +462,18 @@ def schedule(script: str, plan: str, capacity: int, retry_failed: int = 0,
                 pending.remove(name)
                 print('forge: dispatched ' + name + ' -> ' + str(root), file=sys.stderr, flush=True)
             if not active:
-                if paused:
+                if paused or held:
                     # Infrastructure stop: leave everything not yet run PENDING. Marking it
                     # BLOCKED would turn "the provider was down" into a recorded failure.
+                    # A task held back by its pin is still an infrastructure stop.
                     break
                 for name in pending:
                     mark(name, 'BLOCKED')
                 break
             time.sleep(0.05)
     finally:
+        # Not live from here on: a late `forge control` must not edit budgets nobody reads.
+        live_stop(plan, tasks)
         for process, log in active.values():
             try:
                 os.killpg(process.pid, signal.SIGTERM)

package/scripts/forge-ui.py

@@ -5,6 +5,13 @@
 prints a link to the run; every later `open` reuses it. State lives in
 `${XDG_STATE_HOME:-~/.local/state}/forge/ui`: `server.json` (what we started), `server.log`
 and `lock` (serialises launchers). The server exits by itself after FORGE_UI_IDLE_S idle seconds.
+
+FORGE_UI_READONLY=1 starts (or insists on) a server that answers no write. The mode is recorded
+with the server, and a running server of the other mode is replaced like one running old code.
+
+The server runs without the shell's FORGE_* variables, but the CLIs its writes call need the forge
+configuration (control.CLI_ENV_NAMES): `open` writes those to `cli-env.json` (0600) for the server to
+load, records them in server.json, and refuses (exit 5) to reuse a server started with other values.
 """
 from __future__ import annotations
 
@@ -38,6 +45,7 @@ LOCK_WAIT_S = 10
 START_WAIT_S = 5
 STOP_WAIT_S = 2
 BROWSER_WAIT_S = 2  # a browser command that hangs must not hold `open` past its budget
+CLI_ENV_FILE = 'cli-env.json'
 
 
 def state_dir() -> Path:
@@ -123,13 +131,13 @@ def read_state(state):
     return data if isinstance(data, dict) else None
 
 
-def write_state(state, data):
-    handle, temp = tempfile.mkstemp(prefix='server.json.', dir=str(state))
+def write_state(state, data, name='server.json'):
+    handle, temp = tempfile.mkstemp(prefix=name + '.', dir=str(state))  # mkstemp makes it 0600
     try:
         with os.fdopen(handle, 'w') as out:
             json.dump(data, out, indent=1, sort_keys=True)
             out.write('\n')
-        os.replace(temp, state / 'server.json')
+        os.replace(temp, state / name)
     except BaseException:
         try:
             os.unlink(temp)
@@ -187,12 +195,25 @@ def terminate(pid) -> bool:
     return wait_dead(pid, STOP_WAIT_S)
 
 
-def _spawn(state, port, registry, idle):
+def read_only_wanted() -> bool:
+    return os.environ.get('FORGE_UI_READONLY', '').strip().lower() in ('1', 'true', 'yes', 'on')
+
+
+def is_read_only(answer) -> bool:
+    """Whether a live /api/health answer is a read-only server (a server too old to say is one)."""
+    return answer.get('controls') is not True
+
+
+def _spawn(state, port, registry, idle, read_only=False, cli_env=None):
     """Start the server; returns (process, port) or (None, error text)."""
     log = state / 'server.log'
     env = {k: v for k, v in os.environ.items() if not k.startswith('FORGE_')}
-    command = [sys.executable, '-I', str(Path(__file__).resolve()), '_serve', '--port', str(port),
-               '--quiet', '--registry-dir', registry, '--idle-exit', str(idle)]
+    # The forge configuration goes to the server's CLIs only, through a file: never into its own environment.
+    write_state(state, cli_env or {}, CLI_ENV_FILE)
+    command = [sys.executable, '-I', str(Path(__file__).resolve()), '_serve', '--cli-env', str(state / CLI_ENV_FILE),
+               '--port', str(port), '--quiet', '--registry-dir', registry, '--idle-exit', str(idle)]
+    if read_only:  # the server's environment has no FORGE_* variables, so the mode goes as a flag
+        command.append('--read-only')
     with os.fdopen(open_regular(log, os.O_WRONLY | os.O_CREAT | os.O_TRUNC), 'w') as out:
         proc = subprocess.Popen(command, cwd=str(state), stdin=subprocess.DEVNULL, stdout=out, stderr=out,
                                 start_new_session=True, close_fds=True, env=env)
@@ -211,11 +232,11 @@ def _spawn(state, port, registry, idle):
     return None, None
 
 
-def start_server(state, port, registry, idle):
+def start_server(state, port, registry, idle, read_only=False, cli_env=None):
     """Spawn a server, falling back once to a free port when the preferred one is taken."""
-    proc, result = _spawn(state, port, registry, idle)
+    proc, result = _spawn(state, port, registry, idle, read_only, cli_env)
     if proc is None and result == 2 and port != 0:
-        proc, result = _spawn(state, 0, registry, idle)
+        proc, result = _spawn(state, 0, registry, idle, read_only, cli_env)
     if proc is None:
         return None
     return {'pid': proc.pid, 'port': result}
@@ -258,6 +279,14 @@ def browse(url):
     return 0
 
 
+def config_change(recorded, current):
+    """How the running server's forge configuration differs from this shell's, as text; '' when it does not."""
+    recorded = recorded if isinstance(recorded, dict) else {}  # a record without one has none
+    names = sorted(name for name in set(recorded) | set(current) if recorded.get(name) != current.get(name))
+    return '; '.join(f'{name} is {current.get(name, "unset")} here, {recorded.get(name, "unset")} in the server'
+                     for name in names)
+
+
 def run_info(directory):
     """(repo, None) for a run dir, or (None, why not). Never raises and never blocks."""
     marker = directory / 'repo'
@@ -269,7 +298,10 @@ def run_info(directory):
         # a FIFO or a device named `repo` would block the read: only a regular file is read
         if not stat.S_ISREG(os.stat(marker).st_mode):
             return None, f'{marker} is not a regular file'
-        repo = marker.read_text().strip()
+        # only the first line names the repo, as in forge_registry._repo_of (the runners register
+        # the same run dir under that line; anything after it must not change where it lands)
+        lines = marker.read_text().splitlines()
+        repo = lines[0].strip() if lines else ''
     except (OSError, ValueError) as exc:  # ValueError: not decodable text
         return None, f'cannot read {marker}: {getattr(exc, "strerror", None) or exc}'
     if not repo:
@@ -282,6 +314,7 @@ def run_info(directory):
 def cmd_open(args):
     import forge_registry
     from forge_ui import __version__, build_id
+    from forge_ui.control import cli_env_from
     from forge_ui.reader import run_key
 
     try:
@@ -307,6 +340,8 @@ def cmd_open(args):
     state = state_dir()
     log = state / 'server.log'
     registry = str(forge_registry.registry_dir())
+    read_only = read_only_wanted()
+    cli_env = cli_env_from(os.environ)
     spawned = None
     # Any OSError below is state we cannot use (state dir, lock, server.log, server.json) or a
     # spawn that failed: exit 4. An unreadable or invalid server.json is not one: it means no server.
@@ -317,26 +352,35 @@ def cmd_open(args):
             server = read_state(state)
             answer = confirmed(server) if server else None
             if answer:
-                # the record and the live answer must both name this code
-                if server.get('build') == build and answer.get('build') == build and server.get('registry') == registry:
-                    pass  # reuse
+                # the record and the live answer must both name this code and the mode asked for
+                if (server.get('build') == build and answer.get('build') == build and server.get('registry') == registry
+                        and bool(server.get('read_only')) == read_only and is_read_only(answer) == read_only):
+                    # Reused, it would run this shell's writes with another registry and dataset, and a
+                    # restart could cut off a write in flight: say so instead, and how to restart it.
+                    change = config_change(server.get('cli_env'), cli_env)
+                    if change:
+                        _say(f'error: the running forge-ui (pid {server["pid"]}) has another forge configuration '
+                             f'for its writes: {change}. Run `forge ui stop`, then open again.')
+                        return 5
                 else:
                     terminate(server['pid'])
                     server = None
             else:
                 server = None  # dead, or a pid that is not our forge-ui: never signal it
             if server is None:
-                spawned = start_server(state, port, registry, idle)
+                spawned = start_server(state, port, registry, idle, read_only, cli_env)
                 if spawned is None:
                     _say(f'error: the server did not start; see {log}')
                     return 4
-                server = dict(spawned, version=__version__, build=build, registry=registry, log=str(log),
-                              started=datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'), opened=[])
+                server = dict(spawned, version=__version__, build=build, registry=registry, log=str(log), read_only=read_only,
+                              cli_env=cli_env, started=datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'), opened=[])
             opened = server.get('opened')
             opened = opened if isinstance(opened, list) else []
             mark = key or ''
             # a key counts as opened only when a browser is really launched for it
-            first = mark not in opened and browser_wanted(args)
+            wanted = browser_wanted(args)
+            first = mark not in opened and wanted
+            again = mark in opened and wanted  # say so, or a repeated `open` looks like it did nothing
             if first:
                 opened.append(mark)
             server['opened'] = opened
@@ -354,6 +398,8 @@ def cmd_open(args):
     print(f'forge-ui: {url}')
     if first:
         launch_browser(url)
+    elif again:
+        _say('a browser tab was already opened for this link, so no new one was opened; use the link above')
     return 0
 
 
@@ -368,11 +414,13 @@ def cmd_status(args):
         return 1
     info = {'running': True, 'pid': server['pid'], 'port': server['port'],
             'url': f'http://{HOST}:{server["port"]}/', 'version': answer.get('version'),
-            'build': answer.get('build'), 'started': server.get('started'), 'log': server.get('log')}
+            'build': answer.get('build'), 'started': server.get('started'), 'log': server.get('log'),
+            'read_only': is_read_only(answer)}
     if args.json:
         print(json.dumps(info, sort_keys=True))
     else:
-        print(f'forge-ui: running at {info["url"]} (pid {info["pid"]}, started {info["started"]})')
+        mode = 'read-only' if info['read_only'] else 'read-write'
+        print(f'forge-ui: running at {info["url"]} (pid {info["pid"]}, started {info["started"]}, {mode})')
     return 0
 
 
@@ -403,8 +451,26 @@ def cmd_stop(args):
     return 0
 
 
+def load_cli_env(path):
+    """The forge configuration `_spawn` wrote for the server's CLIs; OSError or ValueError otherwise."""
+    from forge_ui import control
+    with os.fdopen(open_regular(path, os.O_RDONLY), 'rb') as handle:
+        return control.check_cli_env(json.loads(handle.read()))
+
+
 def serve(argv):
+    from forge_ui import control
     from forge_ui.__main__ import main
+    if argv[:1] == ['--cli-env']:
+        if len(argv) < 2:
+            _say('error: --cli-env needs a file')
+            return 1  # not 2: start_server reads 2 as a taken port
+        try:
+            control.cli_env = load_cli_env(argv[1])
+        except (OSError, ValueError, RecursionError) as exc:
+            _say(f'error: cannot load the CLI configuration {argv[1]}: {getattr(exc, "strerror", None) or exc}')
+            return 1
+        argv = argv[2:]
     return main(argv)