@maudecode/talaria-web 1.18.0 → 1.20.0

package/sidecar/talaria_sidecar/methods/kanban.py

@@ -7,17 +7,20 @@ server; the sidecar receives typed params.
 
 from __future__ import annotations
 
+import functools
 import json
 import secrets
 import time
 from dataclasses import asdict, is_dataclass
-from typing import Any
+from typing import Any, NamedTuple
 
 from ..errors import InvalidParams, RpcError
 from ..home import profile_home_param, scoped_home
 from ..rpc import CallContext
 
-BOARD_COLUMNS = ["triage", "todo", "ready", "running", "blocked", "done"]
+# Agent 2026.9.24 predates ``kanban_workflow``; its ``VALID_STATUSES`` set holds these columns, in this board order.
+# Delete with that release's entry in ``agent_support.json``.
+_LEGACY_COLUMNS = ("triage", "todo", "scheduled", "ready", "running", "blocked", "review", "done")
 
 
 class NotFound(RpcError):
@@ -38,6 +41,27 @@ def _kb():
     return kb
 
 
+class _Workflow(NamedTuple):
+    columns: tuple[tuple[str, str], ...]  # (key, label) in board order
+    manual: dict | None  # src -> [dst]; None on an Agent without a move table
+
+
+@functools.cache
+def _workflow() -> _Workflow:
+    """The Agent's board columns and manual move table from ``kanban_workflow.DEFAULT_WORKFLOW`` (Agent 0.21.6+, TAL-796)."""
+    try:
+        from hermes_cli.kanban_workflow import DEFAULT_WORKFLOW
+    except ImportError:
+        statuses = getattr(_kb(), "VALID_STATUSES", _LEGACY_COLUMNS)
+        return _Workflow(tuple((key, key.title()) for key in _LEGACY_COLUMNS if key in statuses), None)
+    workflow = DEFAULT_WORKFLOW.to_dict()
+    return _Workflow(tuple((c["key"], c["label"]) for c in workflow["columns"]), workflow["manual"])
+
+
+def _columns() -> list[str]:
+    return [key for key, _ in _workflow().columns]
+
+
 def _board(params: dict):
     raw = params.get("board")
     if raw is None or (isinstance(raw, str) and raw.strip() == ""):
@@ -49,9 +73,16 @@ def _board(params: dict):
         raise InvalidParams(f"invalid board slug: {raw!r}") from exc
     if not normed:
         return None
-    default_slug = getattr(kb, "DEFAULT_BOARD", "default")
-    if normed != default_slug and not kb.board_exists(normed):
-        raise NotFound(f"board {normed!r} does not exist")
+    if normed == getattr(kb, "DEFAULT_BOARD", "default"):
+        return normed
+    return _live_board(kb, normed, normed)
+
+
+def _live_board(kb, normed: str, shown, *, archived_ok: bool = False) -> str:
+    """``normed`` when it names a live board. Agent 0.21.6 leaves an ``archived`` ``board.json`` tombstone at an
+    archived board's slug, so ``board_exists`` alone would let a stale link reach it (TAL-795)."""
+    if not kb.board_exists(normed) or (not archived_ok and kb.read_board_metadata(normed).get("archived")):
+        raise NotFound(f"board {shown!r} does not exist")
     return normed
 
 
@@ -66,8 +97,6 @@ def _connect_module():
 
 
 def _conn(board=None):
-    kb = _kb()
-    kb.init_db(board=board)
     module = _connect_module()
     closing = getattr(module, "connect_closing", None)
     return closing(board=board) if closing is not None else module.connect(board=board)
@@ -197,6 +226,8 @@ def _task_dict(task, conn):
     # stored or supplied evidence, and refuses to release a live worker's claim.
     data["claim_live"] = data.get("status") == "running" and _claim_live(conn, data.get("id"))
     data["has_completion_evidence"] = bool(str(data.get("result") or "").strip())
+    manual = _workflow().manual
+    data["agent_move_targets"] = None if manual is None else list(manual.get(data.get("status"), []))
     try:
         age = _kb().task_age(task)
     except Exception:  # noqa: BLE001
@@ -237,8 +268,13 @@ def _comment_counts(conn):
 
 def _validate_status(status: str) -> str:
     value = str(status or "").strip().lower()
-    if value not in set(BOARD_COLUMNS) | {"archived"}:
+    if value not in {*_columns(), "archived"}:
         raise InvalidParams(f"invalid status: {value}")
+    if value == "running":
+        raise InvalidParams("Cannot set status to 'running' directly; use the dispatcher/claim path")
+    if value in ("scheduled", "review"):
+        # The Agent reaches these through verbs with extra input (a wake time, a reviewer), which Talaria does not offer.
+        raise InvalidParams(f"Cannot set status to {value!r} directly")
     return value
 
 
@@ -327,19 +363,21 @@ def _patch_task(conn, task_id: str, body: dict) -> None:
     elif status == "archived":
         if not _fenced(conn, task_id, lambda: kb.archive_task(conn, task_id), confirm_running_exit=confirm, releases_claim=False):
             raise NotFound("task not found")
-    elif status == "running":
-        raise InvalidParams("Cannot set status to 'running' directly; use the dispatcher/claim path")
-    elif status == "ready":
+    else:
         current = kb.get_task(conn, task_id)
         if not current:
             raise NotFound("task not found")
-        if current.status == "blocked":
-            if not kb.unblock_task(conn, task_id):
-                raise NotFound("task not found")
-        elif not _set_status_direct(conn, task_id, "ready", confirm_running_exit=confirm):
-            raise NotFound("task not found")
-    elif status in ("triage", "todo"):
-        if not _set_status_direct(conn, task_id, status, confirm_running_exit=confirm):
+        # Like the Agent's dashboard: leaving review reopens it, and blocked/scheduled -> ready unblocks; both re-gate on
+        # parents. Triage is a direct write there too. The reopen lands in ready whatever the target, so todo is refused.
+        if current.status == "review" and status == "todo":
+            raise Conflict("A task in review reopens to ready")
+        if current.status == "review" and status == "ready":
+            ok = kb.reopen_review_task(conn, task_id)
+        elif status == "ready" and current.status in ("blocked", "scheduled"):
+            ok = kb.unblock_task(conn, task_id)
+        else:
+            ok = _set_status_direct(conn, task_id, status, confirm_running_exit=confirm)
+        if not ok:
             raise NotFound("task not found")
 
 
@@ -373,15 +411,15 @@ def _board_counts(slug):
             pass
 
 
-def _normalize_existing_slug(slug) -> str:
+def _normalize_existing_slug(slug, *, archived_ok: bool = False) -> str:
     kb = _kb()
     try:
         normed = kb._normalize_board_slug(slug)
     except (ValueError, AttributeError) as exc:
         raise InvalidParams(f"invalid board slug: {slug!r}") from exc
-    if not normed or not kb.board_exists(normed):
+    if not normed:
         raise NotFound(f"board {slug!r} does not exist")
-    return normed
+    return _live_board(kb, normed, slug, archived_ok=archived_ok)
 
 
 def _current_board() -> str:
@@ -449,9 +487,9 @@ def board_payload(params: dict) -> dict:
             data["comment_count"] = comment_counts.get(task.id, 0)
             return data
 
-        columns = [{"name": name, "tasks": [row(t) for t in tasks if t.status == name]} for name in BOARD_COLUMNS]
+        columns = [{"name": key, "label": label, "tasks": [row(t) for t in tasks if t.status == key]} for key, label in _workflow().columns]
         if include_archived:
-            columns.append({"name": "archived", "tasks": [row(t) for t in tasks if t.status == "archived"]})
+            columns.append({"name": "archived", "label": "Archived", "tasks": [row(t) for t in tasks if t.status == "archived"]})
         return {
             "columns": columns,
             "tenants": sorted({t.tenant for t in tasks if getattr(t, "tenant", None)}),
@@ -472,6 +510,8 @@ def create_task_payload(params: dict) -> dict:
         priority = int(body.get("priority") or 0)
     except (TypeError, ValueError):
         raise InvalidParams("priority must be an integer")
+    # Checked before the insert, so a refused status leaves no task behind.
+    status = _validate_status(body.get("status")) if body.get("status") else None
     kb = _kb()
     with _conn(board=_board(params)) as conn:
         task_id = kb.create_task(
@@ -480,8 +520,8 @@ def create_task_payload(params: dict) -> dict:
             workspace_kind=body.get("workspace_kind") or "scratch", workspace_path=body.get("workspace_path") or None,
             idempotency_key=body.get("idempotency_key") or None, max_runtime_seconds=body.get("max_runtime_seconds") or None, skills=body.get("skills") or None,
         )
-        if body.get("status"):
-            _patch_task(conn, task_id, {"status": body.get("status")})
+        if status:
+            _patch_task(conn, task_id, {"status": status})
         return {"task": _task_dict(kb.get_task(conn, task_id), conn), "read_only": False}
 
 
@@ -534,11 +574,17 @@ def task_detail_payload(params: dict) -> dict:
         task = kb.get_task(conn, task_id)
         if not task:
             raise NotFound("task not found")
+        data = _task_dict(task, conn)
+        # ``started_at`` is the first-ever start; a retried task's run clock counts from its current run (TAL-809).
+        data["current_run_started_at"] = kb.current_run_started_ats(conn, [task_id]).get(task_id)
+        links = {"parents": kb.parent_ids(conn, task_id), "children": kb.child_ids(conn, task_id)}
+        linked = (kb.get_task(conn, link_id) for link_id in dict.fromkeys([*links["parents"], *links["children"]]))
         return {
-            "task": _task_dict(task, conn),
+            "task": data,
             "comments": [_obj_dict(c) for c in kb.list_comments(conn, task_id)],
             "events": [_obj_dict(e) for e in kb.list_events(conn, task_id)],
-            "links": {"parents": kb.parent_ids(conn, task_id), "children": kb.child_ids(conn, task_id)},
+            "links": links,
+            "link_tasks": [{"id": t.id, "title": t.title, "status": t.status} for t in linked if t],
             "runs": [_obj_dict(r) for r in kb.list_runs(conn, task_id)],
             "read_only": False,
         }
@@ -547,6 +593,7 @@ def task_detail_payload(params: dict) -> dict:
 def events_payload(params: dict) -> dict:
     since = _int(params, "since", 0, minimum=0)
     limit = _int(params, "limit", 200, minimum=1, maximum=200)
+    kb = _kb()
     with _conn(board=_board(params)) as conn:
         rows = conn.execute(
             "SELECT id, task_id, run_id, kind, payload, created_at FROM task_events WHERE id > ? ORDER BY id ASC LIMIT ?", (since, limit)
@@ -557,7 +604,7 @@ def events_payload(params: dict) -> dict:
                 payload = json.loads(row["payload"]) if row["payload"] else None
             except Exception:  # noqa: BLE001
                 payload = None
-            events.append({"id": row["id"], "task_id": row["task_id"], "run_id": row["run_id"], "kind": row["kind"], "payload": payload, "created_at": row["created_at"]})
+            events.append({"id": row["id"], "task_id": row["task_id"], "run_id": row["run_id"], "kind": row["kind"], "payload": payload, "created_at": kb._to_epoch(row["created_at"])})
             cursor = int(row["id"])
         latest = _latest_event_id(conn)
         if not events:
@@ -583,13 +630,17 @@ def config_payload(params: dict) -> dict:
         cfg = {}
     k = ((cfg.get("dashboard") or {}).get("kanban") or {})
     return {
-        "columns": BOARD_COLUMNS, "assignees": assignees, "default_tenant": k.get("default_tenant") or "",
+        "columns": _columns(), "assignees": assignees, "default_tenant": k.get("default_tenant") or "",
         "lane_by_profile": bool(k.get("lane_by_profile", True)), "include_archived_by_default": bool(k.get("include_archived_by_default", False)),
         "render_markdown": bool(k.get("render_markdown", True)), "read_only": False,
     }
 
 
 def stats_payload(params: dict) -> dict:
+    return {**_stats(params), "column_order": _columns()}
+
+
+def _stats(params: dict) -> dict:
     kb = _kb()
     with _conn(board=_board(params)) as conn:
         if hasattr(kb, "board_stats"):
@@ -761,7 +812,8 @@ def create_board_payload(params: dict) -> dict:
 def update_board_payload(params: dict) -> dict:
     kb = _kb()
     body = params.get("board_spec") or {}
-    normed = _normalize_existing_slug(params.get("slug"))
+    # Metadata edits stay open on an archived board: clearing ``archived`` is how one archived in place comes back.
+    normed = _normalize_existing_slug(params.get("slug"), archived_ok=True)
     kwargs = {}
     if "default_workdir" in body:
         kwargs["default_workdir"] = str(body.get("default_workdir") or "")

package/sidecar/talaria_sidecar/methods/memory.py

@@ -0,0 +1,84 @@
+"""``memory.*``: the Agent's ``MemoryStore`` reading of a memory page save (TAL-886) and its compare-and-write (TAL-784)."""
+
+from __future__ import annotations
+
+import errno
+import hashlib
+import os
+import stat
+import threading
+from pathlib import Path
+
+from ..errors import InvalidParams, RpcError
+from ..home import profile_home_param, scoped_home
+from ..rpc import CallContext
+
+# Agents without the per-file lock helper: this sidecar's saves still run one at a time.
+_SAVE_LOCK = threading.Lock()
+
+
+def check(target: str, content: str) -> dict:
+    """``content``'s char count as the Agent's memory tool parses it, and the profile's limit for ``target``."""
+    from hermes_cli.config import load_config
+    from tools.memory_tool_store import ENTRY_DELIMITER, MemoryStore
+
+    mem = (load_config() or {}).get("memory") or {}
+    store = MemoryStore(**{key: int(mem[key]) for key in ("memory_char_limit", "user_char_limit") if mem.get(key) is not None})
+    # The store keeps each entry once (first occurrence wins), as its load and write paths do.
+    entries = list(dict.fromkeys(MemoryStore._parse_entries(content)))
+    return {"count": len(ENTRY_DELIMITER.join(entries)), "limit": store._char_limit(target)}
+
+
+def _digest(path: Path) -> str | None:
+    """SHA-256 hex of the regular file at ``path`` (of no bytes when there is none), never following a link; None otherwise."""
+    try:
+        fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
+    except FileNotFoundError:
+        return hashlib.sha256(b"").hexdigest()
+    except OSError as exc:
+        if exc.errno == errno.ELOOP:
+            return None
+        raise
+    with os.fdopen(fd, "rb") as handle:
+        if not stat.S_ISREG(os.fstat(handle.fileno()).st_mode):
+            return None
+        return hashlib.sha256(handle.read()).hexdigest()
+
+
+def write(home: Path, section: str, base: str, content: str) -> dict:
+    """Replace ``section``'s file with ``content`` only while its bytes still hash to ``base``, the server's read.
+
+    Each file is checked and written under the Agent's own per-file lock (``<file>.lock``), so neither a memory tool
+    call nor a concurrent save can land between the two; an Agent without the lock helper gets this sidecar's lock.
+    """
+    from tools.memory_tool_store import MemoryStore
+    from utils import atomic_write_text
+
+    if section not in ("memory", "user", "soul"):
+        raise InvalidParams("section must be memory, user, or soul")
+    # The files the server read: SOUL.md in the profile home, MEMORY.md / USER.md in its memories folder.
+    path = home / "SOUL.md" if section == "soul" else home / "memories" / ("USER.md" if section == "user" else "MEMORY.md")
+    file_lock = getattr(MemoryStore, "_file_lock", None)
+    try:
+        with file_lock(path) if file_lock else _SAVE_LOCK:
+            if _digest(path) != base:
+                return {"written": False}
+            atomic_write_text(path, content, tmp_prefix=".mem_", preserve_mode=True)
+    except OSError as exc:
+        if exc.errno not in (errno.EACCES, errno.EPERM, errno.EROFS):
+            raise
+        raise RpcError(f"{path.name} is not writable: {exc.strerror}", condition="memory_not_writable") from exc
+    return {"written": True}
+
+
+def register(registry) -> None:
+    @registry.method("memory.check")
+    def check_(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return check(str(params["target"]), str(params["content"]))
+
+    @registry.method("memory.write")
+    def write_(ctx: CallContext, params: dict) -> dict:
+        home = profile_home_param(params)
+        with scoped_home(home):
+            return write(home, str(params["section"]), str(params["base"]), str(params["content"]))

package/sidecar/talaria_sidecar/methods/oauth.py

@@ -1,4 +1,5 @@
-"""``oauth.*``: the Agent's device-code sign-ins for Nous Portal, OpenAI Codex, xAI and MiniMax (TAL-398).
+"""``oauth.*``: the Agent's device-code sign-ins for Nous Portal, OpenAI Codex, xAI and MiniMax (TAL-398), and the
+browser sign-in of a plugin-declared OAuth client (``plugin:<key>:<id>``, TAL-1276, in ``plugin_oauth``).
 
 ``oauth.start`` asks the provider for a code and answers what the user has to see; a daemon thread then waits for the
 approval and saves the credential with the Agent's own auth-store helpers under the flow's profile home, the steps its
@@ -9,9 +10,12 @@ Flows live in this process only.
 
 from __future__ import annotations
 
+import contextlib
+import inspect
 import logging
 import os
 import secrets
+import ssl
 import threading
 import time
 from dataclasses import dataclass, field
@@ -22,6 +26,7 @@ from typing import Any, Callable
 from ..errors import InvalidParams, RpcError
 from ..home import profile_home_param, scoped_home
 from ..rpc import CallContext
+from . import plugin_oauth
 
 log = logging.getLogger("talaria_sidecar.oauth")
 
@@ -31,6 +36,8 @@ _CODEX_EXPIRES_IN = 15 * 60  # OpenAI's device-code lifetime, as the Agent dashb
 _ENDED_TTL = 10 * 60
 # A pending flow past its code's expiry by this much ends expired even if its provider call has not returned yet.
 _EXPIRY_GRACE = 60
+# How long a start waits for the flows it replaces to close their loopback listeners.
+_RELEASE_WAIT = 5.0
 
 _DENIED = "Sign-in was declined."
 _EXPIRED = "The sign-in code expired before it was approved."
@@ -55,6 +62,17 @@ class Flow:
     cancelled: threading.Event = field(default_factory=threading.Event)
     # Serialises the cancel check with the credential save: a cancel cannot land between them.
     lock: threading.Lock = field(default_factory=threading.Lock)
+    # The credential is saved but the sign-in has not finished (a guest sign-in still settles the account): a cancel or
+    # an expiry can no longer undo it, and the flow stays pending until its own ending.
+    committed: bool = False
+    # A browser sign-in also finishes from the redirect address the user pastes (``oauth.submit_redirect``).
+    submit: Callable[[str], None] | None = None
+    # Set once a browser sign-in's loopback listener is closed, so a replacing start can bind the same fixed port.
+    closed: threading.Event | None = None
+
+    @property
+    def stoppable(self) -> bool:
+        return self.status == "pending" and not self.committed
 
     def end(self, status: str, error: str | None = None) -> None:
         self.status, self.error, self.ended_at = status, error, time.time()
@@ -107,9 +125,24 @@ def _now_z() -> str:
 
 
 def _client(timeout: float, **kwargs: Any) -> Any:
+    """Every flow's HTTP client, verifying TLS as the Agent's own sign-in does: the OS trust store, and (v0.22.3+) a
+    certifi bundle an install-environment rotation deleted under this process, re-derived process-wide."""
     import httpx
 
-    return httpx.Client(timeout=httpx.Timeout(timeout), headers={"Accept": "application/json"}, **kwargs)
+    return httpx.Client(timeout=httpx.Timeout(timeout), headers={"Accept": "application/json"}, verify=_verify(), **kwargs)
+
+
+def _verify() -> Any:
+    try:
+        from agent.ssl_verify import resolve_httpx_verify
+    except ImportError:  # an Agent without it keeps httpx's default
+        return True
+    verify = resolve_httpx_verify()
+    # The resolver hands over the platform store alone when SSL_CERT_FILE/SSL_CERT_DIR is set; httpx's default trusted
+    # that bundle, so keep it, on top of the platform store the resolver installed (as ``platform_ssl_context`` does).
+    cafile, capath = os.environ.get("SSL_CERT_FILE", "").strip(), os.environ.get("SSL_CERT_DIR", "").strip()
+    cafile, capath = (cafile if os.path.isfile(cafile) else None), (capath if os.path.isdir(capath) else None)
+    return ssl.create_default_context(cafile=cafile, capath=capath) if cafile or capath else verify
 
 
 # ── providers: (begin, wait, save) over the Agent's own steps ──────────
@@ -121,10 +154,14 @@ def _nous_begin() -> tuple[dict, dict]:
     from hermes_cli import anon_auth
     from hermes_cli.auth import PROVIDER_REGISTRY, _request_device_code
 
-    if anon_auth.guest_enabled() and anon_auth.has_guest():
-        # The free tier's sign-in moves its connectors to the account (``anon_auth.run_sign_in``); a plain device-code
-        # sign-in here would orphan them.
-        raise RpcError("This profile uses the Nous free tier. Sign in from Hermes with `hermes portal`.", condition="oauth_unsupported")
+    # v0.22.0 replaced ``guest_enabled`` with ``guest_allowed``; 0.21.x releases only have the former.
+    guest_gate = getattr(anon_auth, "guest_allowed", None) or getattr(anon_auth, "guest_enabled")
+    if guest_gate() and anon_auth.has_guest():
+        # The native sign-in owns the guest's connector handoff for its installed protocol.
+        if hasattr(anon_auth, "run_sign_in"):
+            return _nous_sign_in(anon_auth)
+        hint = getattr(anon_auth, "UPGRADE_HINT", None) or "Sign in from Hermes with `hermes auth upgrade`."
+        raise RpcError(f"This profile uses the Nous free tier. {hint}", condition="oauth_unsupported")
     pconfig = PROVIDER_REGISTRY["nous"]
     portal = (os.getenv("HERMES_PORTAL_BASE_URL") or os.getenv("NOUS_PORTAL_BASE_URL") or pconfig.portal_base_url).rstrip("/")
     with _client(15.0) as client:
@@ -133,7 +170,63 @@ def _nous_begin() -> tuple[dict, dict]:
     return display, {"portal": portal, "client_id": pconfig.client_id, "scope": pconfig.scope, "device_code": str(data["device_code"])}
 
 
+def _nous_sign_in(anon_auth: Any) -> tuple[dict, dict]:
+    """Over a guest, the Agent's own sign-in (``anon_auth.run_sign_in``, as its dashboard runs it): it moves the guest's
+    connected apps to the account, then persists and settles the account itself. Its cancel check, persist guard and
+    home scope read the flow ``_nous_wait`` binds into the state; before that only ``start``'s first step runs, already
+    under the flow's home."""
+    state: dict = {}
+
+    def cancelled() -> bool:
+        flow = state.get("flow")
+        return flow is not None and flow.cancelled.is_set()
+
+    @contextlib.contextmanager
+    def persist_guard():
+        # As ``_run`` does for a plain save, the final cancel check and the save share the flow's lock; the flow ends
+        # approved only when the Agent has also settled the account, through ``_run``.
+        flow = state["flow"]
+        with flow.lock:
+            may_persist = flow.status == "pending"
+            yield may_persist
+            if may_persist:
+                flow.committed = True
+
+    def scope():
+        flow = state.get("flow")
+        return scoped_home(flow.home) if flow is not None else contextlib.nullcontext()
+
+    # Older Agents use promotion; v0.22.5 removed its option in favor of plain device login and native handoff.
+    options = {"cancel_wins_after_promotion": True} if "cancel_wins_after_promotion" in inspect.signature(anon_auth.run_sign_in).parameters else {}
+    sign_in = anon_auth.run_sign_in(cancelled=cancelled, persist_guard=persist_guard, scope=scope, **options)
+    first = next(sign_in)
+    if first.kind != "code":
+        sign_in.close()
+        raise RpcError(first.copy_terminal, condition="oauth_unsupported" if first.precondition else "oauth_failed")
+    state["sign_in"] = sign_in
+    return {"user_code": first.code, "verification_url": first.link, "expires_in": first.expires_in, "interval": first.interval}, state
+
+
+class _SignInEnded(Exception):
+    """A guest sign-in that ended without an account; ``code`` lets ``_ending`` classify a decline and an expiry."""
+
+    def __init__(self, ended: Any):
+        super().__init__(ended.copy)
+        self.code = {"declined": "access_denied", "timed_out": "expired_token"}.get(ended.kind, ended.kind)
+
+
 def _nous_wait(flow: Flow, state: dict) -> dict:
+    sign_in = state.get("sign_in")
+    if sign_in is not None:
+        state["flow"] = flow
+        try:
+            for ended in sign_in:  # the generator always ends on one terminal state
+                pass
+        finally:
+            sign_in.close()
+        if not ended.ok:
+            raise _SignInEnded(ended)
+        return {}
     from hermes_cli.auth import _poll_for_token
 
     with _client(15.0) as client:
@@ -142,6 +235,8 @@ def _nous_wait(flow: Flow, state: dict) -> dict:
 
 
 def _nous_save(flow: Flow, state: dict, token_data: dict) -> None:
+    if "sign_in" in state:  # the guest sign-in persisted and settled the account itself
+        return
     from hermes_cli import anon_auth
     from hermes_cli.auth import persist_nous_credentials, refresh_nous_oauth_from_state
 
@@ -210,8 +305,10 @@ def _codex_save(flow: Flow, state: dict, tokens: dict) -> None:
 def _xai_begin() -> tuple[dict, dict]:
     from hermes_cli.auth import _xai_oauth_discovery, _xai_oauth_request_device_code
 
-    discovery = _xai_oauth_discovery(20.0)
     with _client(20.0) as client:
+        # The Agent's discovery is a bare ``httpx.get``: building the client first gives it the platform store and a
+        # certifi re-derived after a rotation.
+        discovery = _xai_oauth_discovery(20.0)
         data = _xai_oauth_request_device_code(client)
     display = {"user_code": str(data["user_code"]), "verification_url": str(data.get("verification_uri_complete") or data["verification_uri"]),
                "expires_in": int(data["expires_in"]), "interval": int(data["interval"])}
@@ -320,9 +417,16 @@ def _run(flow: Flow, wait: Callable[[Flow, dict], dict], save: Callable[[Flow, d
         log.info("oauth: %s sign-in ended %s (flow=%s)", flow.provider, flow.status, flow.flow_id[:6])
 
 
+def _discard(state: dict) -> None:
+    """Releases a begun sign-in that is never published: a guest sign-in's generator holds its HTTP client."""
+    if "sign_in" in state:
+        state["sign_in"].close()
+    plugin_oauth.discard(state)
+
+
 def _cancel(flow: Flow) -> None:
     with flow.lock:
-        if flow.status == "pending":
+        if flow.stoppable:
             flow.cancelled.set()
             flow.end("cancelled")
 
@@ -354,7 +458,7 @@ def _pending(home: Path, provider: str) -> list[Flow]:
 
 
 def start(home: Path, provider: str, *, providers: dict[str, Provider] | None = None) -> dict:
-    steps = (providers or PROVIDERS).get(provider)
+    steps = (providers or PROVIDERS).get(provider) or plugin_oauth.steps(provider)
     if steps is None:
         raise InvalidParams(f"{provider} has no device-code sign-in")
     begin, wait, save = steps
@@ -366,6 +470,11 @@ def start(home: Path, provider: str, *, providers: dict[str, Provider] | None =
     # old code that lands while the provider answers can no longer save.
     for old in _pending(home, provider):
         _cancel(old)
+    # A cancelled browser sign-in closes its listener from its own thread; a fixed redirect port is free only after that.
+    with _FLOWS_LOCK:
+        listening = [f for f in _FLOWS.values() if f.provider == provider and f.closed is not None and not f.closed.is_set() and _same_home(f.home, home)]
+    for old in listening:
+        old.closed.wait(_RELEASE_WAIT)
     try:
         with scoped_home(home):
             display, state = begin()
@@ -376,11 +485,13 @@ def start(home: Path, provider: str, *, providers: dict[str, Provider] | None =
         raise RpcError(_first_line(exc), condition="oauth_failed") from exc
     if not str(display["verification_url"]).lower().startswith(("https://", "http://")):
         # The browser opens this link: anything but a web address is refused before a flow exists.
+        _discard(state)
         raise RpcError("The provider answered an invalid sign-in link.", condition="oauth_failed")
-    flow = Flow(secrets.token_urlsafe(16), provider, home, time.time() + int(display["expires_in"]), max(1, int(display["interval"])))
+    flow = Flow(secrets.token_urlsafe(16), provider, home, time.time() + int(display["expires_in"]), max(1, int(display["interval"])), submit=state.get("submit"), closed=state.get("closed"))
     with _FLOWS_LOCK:
         if _GENERATIONS.get(key) != generation:
             # A newer start for this home and provider began while this one waited on the provider: it owns the sign-in.
+            _discard(state)
             raise RpcError("A newer sign-in for this provider replaced this one.", condition="oauth_superseded")
         superseded = [f for f in _FLOWS.values() if f.provider == provider and f.status == "pending" and _same_home(f.home, home)]
         _FLOWS[flow.flow_id] = flow
@@ -400,10 +511,10 @@ def _flow(home: Path, flow_id: str) -> Flow:
 
 def poll(home: Path, flow_id: str) -> dict:
     flow = _flow(home, flow_id)
-    if flow.status == "pending" and time.time() > flow.expires_at + _EXPIRY_GRACE:
+    if flow.stoppable and time.time() > flow.expires_at + _EXPIRY_GRACE:
         # The provider call outlived its code: end it now, and a late approval can no longer save.
         with flow.lock:
-            if flow.status == "pending":
+            if flow.stoppable:
                 flow.cancelled.set()
                 flow.end("expired", _EXPIRED)
     return flow.view()
@@ -415,6 +526,18 @@ def cancel(home: Path, flow_id: str) -> dict:
     return flow.view()
 
 
+def submit_redirect(home: Path, flow_id: str, url: str) -> dict:
+    """Finish a browser sign-in with the address its redirect reached, when the browser runs on another machine."""
+    flow = _flow(home, flow_id)
+    if flow.submit is None:
+        raise InvalidParams("This sign-in takes no redirect address.")
+    with flow.lock:
+        if not flow.stoppable or time.time() >= flow.expires_at:
+            raise RpcError("This sign-in already ended.", condition="oauth_flow_ended")
+    flow.submit(url)
+    return flow.view()
+
+
 def _flow_id(params: dict) -> str:
     flow_id = str(params.get("flow_id") or "").strip()
     if not flow_id:
@@ -425,7 +548,8 @@ def _flow_id(params: dict) -> str:
 def register(reg) -> None:
     @reg.method("oauth.start")
     def start_(ctx: CallContext, params: dict) -> dict:
-        provider = str(params.get("provider") or "").strip().lower()
+        provider = str(params.get("provider") or "").strip()
+        provider = provider if provider.startswith(plugin_oauth.PREFIX) else provider.lower()
         if not provider:
             raise InvalidParams("provider is required")
         return start(profile_home_param(params), provider)
@@ -437,3 +561,10 @@ def register(reg) -> None:
     @reg.method("oauth.cancel", requires_agent=False)
     def cancel_(ctx: CallContext, params: dict) -> dict:
         return cancel(profile_home_param(params), _flow_id(params))
+
+    @reg.method("oauth.submit_redirect", requires_agent=False)
+    def submit_(ctx: CallContext, params: dict) -> dict:
+        url = str(params.get("url") or "").strip()
+        if not url:
+            raise InvalidParams("url is required")
+        return submit_redirect(profile_home_param(params), _flow_id(params), url)