Add special instructions, auth modals, safer OAuth client registration, bump to 0.1.9

- Defer saving OAuth client_id until auth flow fully succeeds (prevents invalidating existing refresh tokens on failed re-auth)
- Add TUI auth-required modal with in-app re-authentication support
- Add special instructions modal for Ralph (per-project agent instructions, `i` key)
- Add --instructions flag to `mfbt ralph` CLI command
- Show project name in Ralph header
- Skip orchestration when all features are already completed
- Improve token expiry status messages (distinguish expired access vs refresh tokens)
- Remove auto-browser-open on 401 in CLI subcommands (just print re-auth instructions)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: shuveb

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mfbt-cli"
-version = "0.1.8"
+version = "0.1.9"
 description = "CLI tool for the mfbt platform — interactive TUI and subcommands for managing mfbt projects"
 readme = "README.md"
 requires-python = ">=3.10"

src/mfbt/auth_flow.py

@@ -41,6 +41,7 @@ def run_interactive_auth(
         TokenExchangeError,
         exchange_code_for_tokens,
         generate_pkce_params,
+        register_client,
         start_callback_server,
         wait_for_callback,
     )
@@ -55,10 +56,14 @@ def run_interactive_auth(
 
     redirect_uri = f"http://127.0.0.1:{port}/callback"
 
-    # Register OAuth client (RFC 7591 Dynamic Client Registration)
+    # Register OAuth client (RFC 7591 Dynamic Client Registration).
+    # Important: do NOT save the client_id yet — if the browser auth flow
+    # fails or times out, we must not overwrite the existing client_id
+    # (which the current refresh token is bound to).
     console.print("Registering OAuth client...")
     try:
-        client_id = token_manager.register_and_save_client([redirect_uri])
+        registered = register_client(base_url, [redirect_uri])
+        client_id = registered.client_id
     except ClientRegistrationError as exc:
         server.server_close()
         console.print(f"[red]Error:[/red] {exc}")
@@ -106,6 +111,8 @@ def run_interactive_auth(
         console.print(f"[red]Error:[/red] {exc}")
         return False
 
+    # Only save the client_id now that the full auth flow succeeded.
+    token_manager.save_client_id(client_id)
     token_manager.save_tokens(token_response)
     console.print("[green]Successfully authenticated![/green]\n")
     return True

src/mfbt/cli.py

@@ -157,10 +157,16 @@ def login(
 
     redirect_uri = f"http://127.0.0.1:{port}/callback"
 
-    # Register OAuth client (RFC 7591 Dynamic Client Registration)
+    # Register OAuth client (RFC 7591 Dynamic Client Registration).
+    # Important: do NOT save the client_id yet — if the auth flow fails,
+    # we must not overwrite the existing client_id that the current
+    # refresh token is bound to.
     console.print("Registering OAuth client...")
     try:
-        client_id = tm.register_and_save_client([redirect_uri])
+        from mfbt.auth import register_client
+
+        registered = register_client(effective_base_url, [redirect_uri])
+        client_id = registered.client_id
     except ClientRegistrationError as exc:
         server.server_close()
         console.print(f"[red]Error:[/red] {exc}")
@@ -222,7 +228,8 @@ def login(
         console.print(f"[red]Error:[/red] {exc}")
         raise typer.Exit(code=1) from exc
 
-    # Store tokens
+    # Only save client_id now that the full auth flow succeeded.
+    tm.save_client_id(client_id)
     tm.save_tokens(token_response)
     console.print("[green]Successfully authenticated![/green]")
 
@@ -269,11 +276,19 @@ def status() -> None:
         expiry = datetime.fromisoformat(expires_at)
         now = datetime.now(timezone.utc)
         if now >= expiry:
-            console.print("[red]Token expired.[/red]")
-            console.print(
-                "Run [bold]mfbt auth login[/bold] or "
-                "[bold]mfbt auth refresh[/bold]."
-            )
+            if tokens.get("refresh_token"):
+                console.print(
+                    "[yellow]Access token expired[/yellow] "
+                    "(refresh token still valid — will auto-refresh on next command)."
+                )
+                console.print(
+                    "Or run [bold]mfbt auth refresh[/bold] to refresh now."
+                )
+            else:
+                console.print("[red]Token expired (no refresh token).[/red]")
+                console.print(
+                    "Run [bold]mfbt auth login[/bold] to re-authenticate."
+                )
         else:
             remaining = expiry - now
             minutes = int(remaining.total_seconds() // 60)

src/mfbt/commands/projects.py

@@ -58,7 +58,6 @@
 def _get_api_client(ctx: typer.Context) -> Any:
     """Build an APIClient from ctx.obj."""
     from mfbt.api_client import APIClient
-    from mfbt.auth_flow import run_interactive_auth
     from mfbt.cache import ResponseCache
     from mfbt.config import get_mfbt_dir
     from mfbt.token_manager import TokenManager
@@ -71,8 +70,11 @@ def _get_api_client(ctx: typer.Context) -> Any:
     cache = ResponseCache(cache_dir)
 
     def _on_auth_required() -> bool:
-        console.print("\n[yellow]Session expired. Re-authenticating...[/yellow]")
-        return run_interactive_auth(base_url, tm, console)
+        console.print(
+            "\n[red]Authentication failed.[/red] "
+            "Run [bold]mfbt auth login[/bold] to re-authenticate."
+        )
+        return False
 
     return APIClient(base_url, tm, cache=cache, on_auth_required=_on_auth_required)
 

src/mfbt/commands/ralph/__init__.py

@@ -28,7 +28,6 @@
 def _get_api_client(ctx: typer.Context) -> Any:
     """Build an APIClient from ctx.obj."""
     from mfbt.api_client import APIClient
-    from mfbt.auth_flow import run_interactive_auth
     from mfbt.token_manager import TokenManager
 
     config = ctx.obj["config"]
@@ -37,8 +36,11 @@ def _get_api_client(ctx: typer.Context) -> Any:
     tm = TokenManager(base_url)
 
     def _on_auth_required() -> bool:
-        console.print("\n[yellow]Session expired. Re-authenticating...[/yellow]")
-        return run_interactive_auth(base_url, tm, console)
+        console.print(
+            "\n[red]Authentication failed.[/red] "
+            "Run [bold]mfbt auth login[/bold] to re-authenticate."
+        )
+        return False
 
     return APIClient(base_url, tm, cache=None, on_auth_required=_on_auth_required)
 
@@ -123,6 +125,12 @@ def ralph(
         "-y",
         help="Skip confirmation prompt and start immediately",
     ),
+    instructions: Optional[str] = typer.Option(
+        None,
+        "--instructions",
+        help="Special instructions for the coding agent (max 512 chars). "
+             "If not provided, loads saved instructions for this project.",
+    ),
     status: bool = typer.Option(
         False,
         "--status",
@@ -154,6 +162,21 @@ def ralph(
     # Resolve project identifier to UUID
     project_id = _resolve_project_identifier(ctx, project)
 
+    # Resolve special instructions
+    from mfbt.config import load_special_instructions, save_special_instructions
+
+    if instructions is not None:
+        if len(instructions) > 512:
+            console.print(
+                "[red]Error:[/red] Instructions must be 512 characters or fewer "
+                f"(got {len(instructions)})."
+            )
+            raise typer.Exit(code=1)
+        save_special_instructions(project_id, instructions)
+        resolved_instructions = instructions if instructions.strip() else None
+    else:
+        resolved_instructions = load_special_instructions(project_id)
+
     # Validate coding agent
     if coding_agent not in SUPPORTED_AGENTS:
         console.print(
@@ -201,6 +224,7 @@ def ralph(
                 max_turns=max_turns,
                 quiet=quiet,
                 base_url=base_url,
+                special_instructions=resolved_instructions,
             )
 
             # Fetch progress for each phase

src/mfbt/commands/ralph/agent.py

@@ -119,9 +119,11 @@ def __init__(
         self,
         agent_type: AgentType,
         max_turns: int | None = None,
+        special_instructions: str | None = None,
     ) -> None:
         self._agent_type = agent_type
         self._max_turns = max_turns
+        self._special_instructions = special_instructions
         self._process: subprocess.Popen | None = None
 
     def build_command(self, prompt: str) -> list[str]:
@@ -136,7 +138,13 @@ def build_command(self, prompt: str) -> list[str]:
             ]
             if self._max_turns is not None:
                 cmd.extend(["--max-turns", str(self._max_turns)])
-            cmd.extend(["--append-system-prompt", self._APPEND_SYSTEM_PROMPT])
+            append_prompt = self._APPEND_SYSTEM_PROMPT
+            if self._special_instructions:
+                append_prompt += (
+                    "\n\nAdditional instructions from the project owner:\n"
+                    + self._special_instructions
+                )
+            cmd.extend(["--append-system-prompt", append_prompt])
             return cmd
         msg = f"Unsupported agent type: {self._agent_type}"
         raise ValueError(msg)

src/mfbt/commands/ralph/orchestrator.py

@@ -50,7 +50,7 @@ def __init__(
         self._client = client
         self._display = display
         self._logger = logger
-        self._agent = AgentRunner(config.coding_agent, config.max_turns)
+        self._agent = AgentRunner(config.coding_agent, config.max_turns, config.special_instructions)
         self._results: list[FeatureResult] = []
         self._session_start: float = 0.0
         self._stop_event = threading.Event()

src/mfbt/commands/ralph/types.py

@@ -46,6 +46,7 @@ class RalphConfig:
     max_turns: int | None
     quiet: bool
     base_url: str
+    special_instructions: str | None = None
 
     @property
     def phase_ids(self) -> list[str]:

src/mfbt/config.py

@@ -442,6 +442,25 @@ def _load_json(path: Path, defaults: dict[str, Any]) -> dict[str, Any]:
         return dict(defaults)
 
 
+def load_special_instructions(project_id: str) -> str | None:
+    """Load special instructions for a project from ``~/.mfbt/special_instructions.json``."""
+    path = get_mfbt_dir() / "special_instructions.json"
+    data = _load_json(path, {})
+    text = data.get(project_id)
+    return text if isinstance(text, str) and text.strip() else None
+
+
+def save_special_instructions(project_id: str, text: str | None) -> None:
+    """Save special instructions for a project to ``~/.mfbt/special_instructions.json``."""
+    path = get_mfbt_dir() / "special_instructions.json"
+    data = _load_json(path, {})
+    if text and text.strip():
+        data[project_id] = text.strip()
+    else:
+        data.pop(project_id, None)
+    _atomic_write_json(path, data)
+
+
 def _atomic_write_json(path: Path, data: dict[str, Any]) -> None:
     """Write JSON atomically via temp file + rename."""
     path.parent.mkdir(parents=True, exist_ok=True)

src/mfbt/tui/__init__.py

@@ -51,11 +51,10 @@ def launch_tui(config: dict[str, Any]) -> None:
             return
 
     def _on_auth_required() -> bool:
-        from rich.console import Console
-
-        c = Console()
-        c.print("\n[yellow]Session expired. Re-authenticating...[/yellow]")
-        return run_interactive_auth(base_url, tm, c)
+        # Don't auto-open the browser — just signal failure so the
+        # API client surfaces an auth error.  The TUI's token monitor
+        # or notification will tell the user to run `mfbt auth login`.
+        return False
 
     mfbt_dir = get_mfbt_dir()
     cache = ResponseCache(mfbt_dir / "cache")