insightfactory-cli 1.0.1.dev9__tar.gz → 1.0.1.dev10__tar.gz

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: insightfactory-cli
-Version: 1.0.1.dev9
+Version: 1.0.1.dev10
 Summary: Profile-based authentication CLI for the InsightFactory Interfaces API
 Project-URL: Homepage, https://github.com/insightfactory-ai/insightfactory-cli
 Project-URL: Repository, https://github.com/insightfactory-ai/insightfactory-cli
@@ -78,6 +78,10 @@ if-cli token -p example-dev --env-name INSIGHTFACTORY_ACCESS_TOKEN_DEV
 if-cli api -p example-dev /api/agent-projects
 if-cli api -p example-dev -X POST -d '{"name":"example"}' /api/example
 
+# Wait longer than the 30-second default for a long-running endpoint.
+if-cli api -p example-dev --timeout 300 -X PUT -d '{"productionLineCodes":["PL001"]}' \
+  /api/orchestration/run
+
 # Discover API routes from the factory's OpenAPI document.
 if-cli api routes -p example-dev
 if-cli api routes -p example-dev agent-projects
@@ -99,6 +103,23 @@ factory origin so a profile token cannot be forwarded to another host. Profile
 hosts must be bare origins rather than URLs containing application path
 prefixes.
 
+Requests time out after 30 seconds by default. Raise the deadline per
+invocation with `--timeout <seconds>`, or for a whole session with
+`INSIGHTFACTORY_REQUEST_TIMEOUT`; the flag wins over the environment variable,
+and both are validated before the command touches the network. There is no
+upper bound, because the right ceiling depends on the endpoint.
+
+Both apply to the API request itself. The OAuth discovery and token-refresh
+round trips keep the 30-second default, so `if-cli token` and in-process callers
+of `if_cli.oauth.get_valid_token` always have a bounded wait that no ambient
+environment value can redefine.
+
+A timeout is a client-side deadline, not a rejection: the factory may have
+accepted and completed the request after `if-cli` gave up. Re-issuing a
+non-idempotent call (`POST`, `PUT`, `PATCH`, `DELETE`) can therefore apply it
+twice, so the timeout message for those methods says to confirm the current
+state before retrying rather than repeating the call.
+
 Override the config directory with `INSIGHTFACTORY_CONFIG_DIR` (useful in tests
 and CI). The default is `~/.insightfactory`.
 

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/README.md

@@ -62,6 +62,10 @@ if-cli token -p example-dev --env-name INSIGHTFACTORY_ACCESS_TOKEN_DEV
 if-cli api -p example-dev /api/agent-projects
 if-cli api -p example-dev -X POST -d '{"name":"example"}' /api/example
 
+# Wait longer than the 30-second default for a long-running endpoint.
+if-cli api -p example-dev --timeout 300 -X PUT -d '{"productionLineCodes":["PL001"]}' \
+  /api/orchestration/run
+
 # Discover API routes from the factory's OpenAPI document.
 if-cli api routes -p example-dev
 if-cli api routes -p example-dev agent-projects
@@ -83,6 +87,23 @@ factory origin so a profile token cannot be forwarded to another host. Profile
 hosts must be bare origins rather than URLs containing application path
 prefixes.
 
+Requests time out after 30 seconds by default. Raise the deadline per
+invocation with `--timeout <seconds>`, or for a whole session with
+`INSIGHTFACTORY_REQUEST_TIMEOUT`; the flag wins over the environment variable,
+and both are validated before the command touches the network. There is no
+upper bound, because the right ceiling depends on the endpoint.
+
+Both apply to the API request itself. The OAuth discovery and token-refresh
+round trips keep the 30-second default, so `if-cli token` and in-process callers
+of `if_cli.oauth.get_valid_token` always have a bounded wait that no ambient
+environment value can redefine.
+
+A timeout is a client-side deadline, not a rejection: the factory may have
+accepted and completed the request after `if-cli` gave up. Re-issuing a
+non-idempotent call (`POST`, `PUT`, `PATCH`, `DELETE`) can therefore apply it
+twice, so the timeout message for those methods says to confirm the current
+state before retrying rather than repeating the call.
+
 Override the config directory with `INSIGHTFACTORY_CONFIG_DIR` (useful in tests
 and CI). The default is `~/.insightfactory`.
 

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "insightfactory-cli"
-version = "1.0.1.dev9"
+version = "1.0.1.dev10"
 description = "Profile-based authentication CLI for the InsightFactory Interfaces API"
 readme = "README.md"
 requires-python = ">=3.10"

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/src/if_cli/commands/api.py

@@ -8,7 +8,14 @@ from urllib.parse import ParseResult
 
 from if_cli.cli import Options, parse_args
 from if_cli.config import get_profile, load_config, resolve_profile_name
-from if_cli.http import fetch_with_timeout, parse_url, url_href, url_origin
+from if_cli.http import (
+    fetch_with_timeout,
+    parse_timeout_seconds,
+    parse_url,
+    resolve_request_timeout,
+    url_href,
+    url_origin,
+)
 from if_cli.oauth import get_valid_token
 from if_cli.runtime import die, is_record, set_exit_code
 
@@ -21,12 +28,13 @@ API_OPTIONS: Options = {
     "profile": {"type": "string", "short": "p"},
     "method": {"type": "string", "short": "X"},
     "data": {"type": "string", "short": "d"},
+    "timeout": {"type": "string"},
 }
 
 API_USAGE = (
-    "usage: if-cli api [-p profile] [-X METHOD] [-d DATA] /api/path\n"
-    "       if-cli api routes [-p profile] [filter]\n"
-    "       if-cli api describe [-p profile] METHOD /api/path"
+    "usage: if-cli api [-p profile] [-X METHOD] [-d DATA] [--timeout SECONDS] /api/path\n"
+    "       if-cli api routes [-p profile] [--timeout SECONDS] [filter]\n"
+    "       if-cli api describe [-p profile] [--timeout SECONDS] METHOD /api/path"
 )
 
 
@@ -109,9 +117,9 @@ def resolve_api_url(host: str, api_path: str) -> ParseResult:
     return url
 
 
-def _fetch_openapi(host: str) -> dict[str, Any]:
+def _fetch_openapi(host: str, timeout: float) -> dict[str, Any]:
     url = f"{host}/swagger/v1/swagger.json"
-    response = fetch_with_timeout(url)
+    response = fetch_with_timeout(url, timeout=timeout)
     if not response.ok:
         die(f"API discovery failed for {host} (HTTP {response.status})")
     try:
@@ -125,16 +133,16 @@ def _fetch_openapi(host: str) -> dict[str, Any]:
     return body
 
 
-def _routes_command(positionals: list[str], profile_name: str | None) -> None:
+def _routes_command(positionals: list[str], profile_name: str | None, timeout: float) -> None:
     profile = get_profile(load_config(), resolve_profile_name(profile_name))
     filter_text = positionals[1] if len(positionals) > 1 else None
-    routes = discover_routes(_fetch_openapi(profile["host"]), filter_text)
+    routes = discover_routes(_fetch_openapi(profile["host"], timeout), filter_text)
     if not routes:
         die(f"no API routes matched '{filter_text or ''}'")
     sys.stdout.write(f"{chr(10).join(routes)}\n")
 
 
-def _describe_command(positionals: list[str], profile_name: str | None) -> None:
+def _describe_command(positionals: list[str], profile_name: str | None, timeout: float) -> None:
     method = positionals[1].upper() if len(positionals) > 1 and positionals[1] else None
     path = positionals[2] if len(positionals) > 2 else None
     if not method or not path:
@@ -143,7 +151,7 @@ def _describe_command(positionals: list[str], profile_name: str | None) -> None:
         _die_on_msys_mangled_path(path)
         die(f"API path must begin with '/'; '{path}' is not a discovery document path")
     profile = get_profile(load_config(), resolve_profile_name(profile_name))
-    operation = describe_route(_fetch_openapi(profile["host"]), method, path)
+    operation = describe_route(_fetch_openapi(profile["host"], timeout), method, path)
     if not operation:
         die(f"{method} {path} was not found in the API discovery document")
     sys.stdout.write(f"{json.dumps({'method': method, 'path': path, **operation}, indent=2)}\n")
@@ -151,11 +159,15 @@ def _describe_command(positionals: list[str], profile_name: str | None) -> None:
 
 def api_command(argv: list[str]) -> None:
     values, positionals = parse_args(argv, options=API_OPTIONS, allow_positionals=True)
+    # Resolved up front so an unusable --timeout or environment value fails before
+    # the command reaches for a profile, a token, or the network.
+    flag = parse_timeout_seconds(values["timeout"], "--timeout") if values["timeout"] is not None else None
+    timeout = resolve_request_timeout(flag)
     if positionals and positionals[0] == "routes":
-        _routes_command(positionals, values["profile"])
+        _routes_command(positionals, values["profile"], timeout)
         return
     if positionals and positionals[0] == "describe":
-        _describe_command(positionals, values["profile"])
+        _describe_command(positionals, values["profile"], timeout)
         return
 
     api_path = positionals[0] if positionals else None
@@ -178,7 +190,14 @@ def api_command(argv: list[str]) -> None:
     headers = {"Authorization": f"Bearer {token}"}
     if values["data"] is not None:
         headers["Content-Type"] = "application/json"
-    response = fetch_with_timeout(url, method=method, headers=headers, body=values["data"])
+    response = fetch_with_timeout(
+        url,
+        method=method,
+        headers=headers,
+        body=values["data"],
+        timeout=timeout,
+        warn_unsafe_retry=True,
+    )
     sys.stderr.write(f"HTTP {response.status}\n")
     body = response.text()
     if body:

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/src/if_cli/constants.py

@@ -1,4 +1,5 @@
 ENV_PROFILE: str = "INSIGHTFACTORY_CONFIG_PROFILE"
+ENV_REQUEST_TIMEOUT: str = "INSIGHTFACTORY_REQUEST_TIMEOUT"
 DEFAULT_SCOPE: str = "openid profile email offline_access"
 LOOPBACK_HOST: str = "127.0.0.1"
 DEFAULT_CALLBACK_PORT: int = 53682

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/src/if_cli/http.py

@@ -1,15 +1,43 @@
 from __future__ import annotations
 
 import json
+import math
+import os
 import socket
 import urllib.error
 import urllib.request
 from email.message import Message
+from typing import NoReturn
 from urllib.parse import ParseResult, urljoin, urlparse
 
+from if_cli.constants import ENV_REQUEST_TIMEOUT
 from if_cli.runtime import die
 
-REQUEST_TIMEOUT_MS = 30_000
+DEFAULT_REQUEST_TIMEOUT_S = 30.0
+SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "TRACE"})
+
+
+def parse_timeout_seconds(value: str, label: str) -> float:
+    """Parse a request timeout in seconds. There is no upper bound: the right
+    ceiling depends on the endpoint, and a long factory call must be waitable."""
+    try:
+        timeout = float(value)
+    except ValueError:
+        die(f"{label} must be a positive number of seconds (received '{value}')")
+    if not math.isfinite(timeout) or timeout <= 0:
+        die(f"{label} must be a positive number of seconds (received '{value}')")
+    return timeout
+
+
+def resolve_request_timeout(explicit: float | None = None) -> float:
+    """Per-invocation timeout, in seconds: explicit argument, then the
+    environment variable, then the default."""
+    if explicit is not None:
+        return explicit
+    from_environment = os.environ.get(ENV_REQUEST_TIMEOUT)
+    if from_environment is not None and from_environment.strip():
+        return parse_timeout_seconds(from_environment.strip(), ENV_REQUEST_TIMEOUT)
+    return DEFAULT_REQUEST_TIMEOUT_S
 
 
 def _with_backslashes_as_slashes(value: str) -> str:
@@ -122,13 +150,34 @@ class HttpResponse:
         return str(value)
 
 
+def _die_on_timeout(url: str, method: str, timeout: float, *, warn_unsafe_retry: bool) -> NoReturn:
+    if not warn_unsafe_retry or method.upper() in SAFE_METHODS:
+        die(f"request timed out after {timeout}s: {url}")
+    die(
+        f"request timed out after {timeout}s: {url}\n"
+        f"        The timeout is a client-side deadline, not a rejection — the factory may still have\n"
+        f"        accepted and completed this {method.upper()}. Do not re-issue it: confirm the\n"
+        "        current state first, and retry only if the work did not happen. Raise the\n"
+        "        deadline with --timeout <seconds>."
+    )
+
+
 def fetch_with_timeout(
     url: str,
     *,
     method: str = "GET",
     headers: dict[str, str] | None = None,
     body: str | bytes | None = None,
+    timeout: float | None = None,
+    warn_unsafe_retry: bool = False,
 ) -> HttpResponse:
+    """Issue one request, dying on timeout.
+
+    `warn_unsafe_retry` opts into the confirm-don't-retry guidance, which only makes
+    sense for a request the caller issued on the user's behalf against the factory.
+    It is wrong advice for an OAuth round trip, where retrying is the correct response
+    and there is no factory-side state to confirm.
+    """
     data: bytes | None
     if body is None:
         data = None
@@ -137,8 +186,9 @@ def fetch_with_timeout(
     else:
         data = body.encode("utf-8")
     request = urllib.request.Request(url, data=data, headers=headers or {}, method=method)
+    effective_timeout = resolve_request_timeout(timeout)
     try:
-        with urllib.request.urlopen(request, timeout=REQUEST_TIMEOUT_MS / 1000) as response:
+        with urllib.request.urlopen(request, timeout=effective_timeout) as response:
             return HttpResponse(response.status, response.headers, response.read())
     except urllib.error.HTTPError as error:
         return HttpResponse(error.code, error.headers, error.read())
@@ -147,7 +197,7 @@ def fetch_with_timeout(
         if isinstance(reason, (TimeoutError, socket.timeout)) or getattr(reason, "errno", None) == getattr(
             socket, "ETIMEDOUT", None
         ):
-            die(f"request timed out after {REQUEST_TIMEOUT_MS / 1000}s: {url}")
+            _die_on_timeout(url, method, effective_timeout, warn_unsafe_retry=warn_unsafe_retry)
         raise
     except TimeoutError:
-        die(f"request timed out after {REQUEST_TIMEOUT_MS / 1000}s: {url}")
+        _die_on_timeout(url, method, effective_timeout, warn_unsafe_retry=warn_unsafe_retry)

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/src/if_cli/main.py

@@ -10,7 +10,7 @@ from if_cli.commands.logout import logout_command
 from if_cli.commands.profiles import profiles_command
 from if_cli.commands.set_token import set_token_command
 from if_cli.commands.token import token_command
-from if_cli.constants import ENV_PROFILE
+from if_cli.constants import ENV_PROFILE, ENV_REQUEST_TIMEOUT
 from if_cli.runtime import die
 
 USAGE = f"""usage: if-cli <command> [options]
@@ -27,11 +27,12 @@ commands:
   config      print a non-secret profile value
               get <host|audience|callback_port|client_id|organization> [-p profile]
   api         call or discover factory API routes
-              [-p profile] [-X METHOD] [-d DATA] <path>
-              routes [-p profile] [filter]
-              describe [-p profile] METHOD <path>
+              [-p profile] [-X METHOD] [-d DATA] [--timeout SECONDS] <path>
+              routes [-p profile] [--timeout SECONDS] [filter]
+              describe [-p profile] [--timeout SECONDS] METHOD <path>
 
 profile selection: -p flag, then ${ENV_PROFILE}, then [DEFAULT].
+request timeout: --timeout flag, then ${ENV_REQUEST_TIMEOUT}, then 30 seconds.
 """
 
 

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/src/if_cli/oauth.py

@@ -20,7 +20,7 @@ from if_cli.cache import (
 )
 from if_cli.config import Profile, meaningful
 from if_cli.constants import DEFAULT_SCOPE, LOOPBACK_HOST
-from if_cli.http import fetch_with_timeout, validate_http_url
+from if_cli.http import DEFAULT_REQUEST_TIMEOUT_S, fetch_with_timeout, validate_http_url
 from if_cli.runtime import CliError, die, escape_html, is_record
 
 CALLBACK_TIMEOUT_SECONDS = 300
@@ -66,7 +66,10 @@ def build_callback_url(port: int) -> str:
 
 
 def _discover(host: str) -> dict[str, Any]:
-    response = fetch_with_timeout(f"{host}/.well-known/oauth-authorization-server")
+    response = fetch_with_timeout(
+        f"{host}/.well-known/oauth-authorization-server",
+        timeout=DEFAULT_REQUEST_TIMEOUT_S,
+    )
     if not response.ok:
         die(f"OAuth discovery failed for {host} (HTTP {response.status})")
     try:
@@ -114,11 +117,15 @@ def _parse_expires_in(value: object) -> float | None:
 
 
 def _token_request(token_endpoint: str, form: dict[str, str]) -> dict[str, object]:
+    # Pinned to the default rather than the caller's timeout: get_valid_token is a
+    # documented in-process surface that promises a bounded wait, and an OAuth round
+    # trip has no reason to inherit a ceiling chosen for a slow factory endpoint.
     response = fetch_with_timeout(
         token_endpoint,
         method="POST",
         headers={"Content-Type": "application/x-www-form-urlencoded"},
         body=urlencode(form),
+        timeout=DEFAULT_REQUEST_TIMEOUT_S,
     )
     if not response.ok:
         body = response.text()

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/tests/test_api.py

@@ -77,6 +77,19 @@ def test_api_suggests_a_placeholder_path_when_only_a_method_was_supplied():
     assert "did you mean: if-cli api -X POST /api/path ?" in result.stderr
 
 
+def test_api_rejects_a_timeout_that_is_not_a_positive_number_of_seconds():
+    for value in ["0", "-1", "abc", "nan", "inf", ""]:
+        result = run_cli(["api", f"--timeout={value}", "/api/health"])
+        assert result.returncode == 1, value
+        assert "--timeout must be a positive number of seconds" in result.stderr, value
+
+
+def test_api_rejects_an_invalid_request_timeout_from_the_environment():
+    result = run_cli(["api", "/api/health"], env={"INSIGHTFACTORY_REQUEST_TIMEOUT": "soon"})
+    assert result.returncode == 1
+    assert "INSIGHTFACTORY_REQUEST_TIMEOUT must be a positive number of seconds" in result.stderr
+
+
 def test_discovers_and_sorts_all_openapi_operations():
     assert discover_routes(OPENAPI) == [
         "DELETE  /api/agent-projects/{id}  Delete an agent project",

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/tests/test_api_command.py

@@ -6,9 +6,16 @@ import time
 from pathlib import Path
 from typing import Any
 
+import pytest
+
+from if_cli.http import fetch_with_timeout
+from if_cli.runtime import CliError
 from tests.helpers import create_config, run_cli
 from tests.servers import Request, Response, ThreadedServer
 
+SLOW_RESPONSE_S = 0.6
+SHORT_TIMEOUT_S = "0.1"
+
 
 def _api_server(mode: str = "valid") -> tuple[ThreadedServer, dict[str, Any]]:
     state: dict[str, Any] = {"return_null_swagger": False}
@@ -35,6 +42,9 @@ def _api_server(mode: str = "valid") -> tuple[ThreadedServer, dict[str, Any]]:
                     "contentType": request.headers.get("Content-Type") or request.headers.get("content-type"),
                 }
             )
+        if request.path == "/slow":
+            time.sleep(SLOW_RESPONSE_S)
+            return Response(body={"accepted": True})
         if request.path == "/invalid-json":
             return Response(body="not-json", headers={"Content-Type": "application/json"})
         if request.path == "/error":
@@ -322,3 +332,150 @@ def test_api_flushes_a_complete_error_body_before_exiting_unsuccessfully():
     finally:
         server.close()
         shutil.rmtree(config_dir, ignore_errors=True)
+
+
+def test_api_timeout_flag_raises_the_deadline_over_the_environment_default():
+    server, _state = _api_server("valid")
+    config_dir = create_config(f"[DEFAULT]\nhost = {server.origin}\n")
+    _write_token(config_dir, server.origin)
+    environment = {
+        "INSIGHTFACTORY_CONFIG_DIR": config_dir,
+        "INSIGHTFACTORY_REQUEST_TIMEOUT": SHORT_TIMEOUT_S,
+    }
+    try:
+        without_flag = run_cli(["api", "/slow"], env=environment)
+        assert without_flag.returncode == 1
+        assert f"request timed out after {float(SHORT_TIMEOUT_S)}s" in without_flag.stderr
+
+        with_flag = run_cli(["api", "--timeout", "30", "/slow"], env=environment)
+        assert with_flag.returncode == 0, with_flag.stderr
+        assert json.loads(with_flag.stdout) == {"accepted": True}
+    finally:
+        server.close()
+        shutil.rmtree(config_dir, ignore_errors=True)
+
+
+def test_api_timeout_on_a_non_idempotent_request_says_it_may_still_have_landed():
+    server, _state = _api_server("valid")
+    config_dir = create_config(f"[DEFAULT]\nhost = {server.origin}\n")
+    _write_token(config_dir, server.origin)
+    try:
+        result = run_cli(
+            ["api", "--timeout", SHORT_TIMEOUT_S, "-X", "PUT", "-d", '{"productionLineCodes":["PL001"]}', "/slow"],
+            env={"INSIGHTFACTORY_CONFIG_DIR": config_dir},
+        )
+        assert result.returncode == 1
+        assert f"request timed out after {float(SHORT_TIMEOUT_S)}s" in result.stderr
+        assert "the factory may still have" in result.stderr
+        assert "accepted and completed this PUT" in result.stderr
+        assert "Do not re-issue it" in result.stderr
+    finally:
+        server.close()
+        shutil.rmtree(config_dir, ignore_errors=True)
+
+
+def test_api_timeout_on_a_read_stays_a_plain_timeout():
+    server, _state = _api_server("valid")
+    config_dir = create_config(f"[DEFAULT]\nhost = {server.origin}\n")
+    _write_token(config_dir, server.origin)
+    try:
+        result = run_cli(
+            ["api", "--timeout", SHORT_TIMEOUT_S, "/slow"],
+            env={"INSIGHTFACTORY_CONFIG_DIR": config_dir},
+        )
+        assert result.returncode == 1
+        assert f"request timed out after {float(SHORT_TIMEOUT_S)}s" in result.stderr
+        assert "Do not re-issue it" not in result.stderr
+    finally:
+        server.close()
+        shutil.rmtree(config_dir, ignore_errors=True)
+
+
+def test_api_routes_honours_the_timeout_flag_during_discovery():
+    server, _state = _api_server("valid")
+    config_dir = create_config(f"[DEFAULT]\nhost = {server.origin}\n")
+    try:
+        result = run_cli(
+            ["api", "routes", "--timeout", "60"],
+            env={"INSIGHTFACTORY_CONFIG_DIR": config_dir},
+        )
+        assert result.returncode == 0, result.stderr
+        assert "GET     /api/health" in result.stdout
+    finally:
+        server.close()
+        shutil.rmtree(config_dir, ignore_errors=True)
+
+
+def test_token_refresh_ignores_a_short_ambient_request_timeout():
+    """`get_valid_token` promises a bounded wait, so the auth leg keeps the default.
+
+    Before the timeout override existed there was nothing to inherit; now an ambient
+    INSIGHTFACTORY_REQUEST_TIMEOUT must not shorten a token refresh out from under an
+    in-process caller.
+    """
+
+    def handler(request: Request) -> Response:
+        if request.path == "/token":
+            time.sleep(SLOW_RESPONSE_S)
+            return Response(body={"access_token": "refreshed", "expires_in": 3600})
+        return Response(body={"ok": True})
+
+    server = ThreadedServer(handler).start()
+    config_dir = create_config(f"[DEFAULT]\nhost = {server.origin}\nclient_id = test-client\n")
+    Path(config_dir, "token-cache.json").write_text(
+        json.dumps(
+            {
+                "version": 1,
+                "tokens": {
+                    server.origin: {
+                        "access_token": "stale",
+                        "refresh_token": "test-refresh",
+                        "expires_at": int(time.time()) - 10,
+                        "token_endpoint": f"{server.origin}/token",
+                        "client_id": "test-client",
+                    }
+                },
+            }
+        ),
+        encoding="utf-8",
+    )
+    try:
+        result = run_cli(
+            ["api", "--timeout", "30", "/api/health"],
+            env={
+                "INSIGHTFACTORY_CONFIG_DIR": config_dir,
+                "INSIGHTFACTORY_REQUEST_TIMEOUT": SHORT_TIMEOUT_S,
+            },
+        )
+        assert result.returncode == 0, result.stderr
+        assert "could not refresh token" not in result.stderr
+        assert json.loads(result.stdout) == {"ok": True}
+    finally:
+        server.close()
+        shutil.rmtree(config_dir, ignore_errors=True)
+
+
+def test_only_the_opted_in_caller_gets_the_confirm_dont_retry_guidance():
+    """A timed-out OAuth POST must not be told to confirm factory state first."""
+
+    def handler(request: Request) -> Response:
+        time.sleep(SLOW_RESPONSE_S)
+        return Response(body={"ok": True})
+
+    server = ThreadedServer(handler).start()
+    try:
+        with pytest.raises(CliError) as unopted:
+            fetch_with_timeout(f"{server.origin}/token", method="POST", timeout=float(SHORT_TIMEOUT_S))
+        assert "request timed out after" in str(unopted.value)
+        assert "Do not re-issue it" not in str(unopted.value)
+
+        with pytest.raises(CliError) as opted:
+            fetch_with_timeout(
+                f"{server.origin}/api/orchestration/run",
+                method="PUT",
+                timeout=float(SHORT_TIMEOUT_S),
+                warn_unsafe_retry=True,
+            )
+        assert "Do not re-issue it" in str(opted.value)
+    finally:
+        server.close()

{insightfactory_cli-1.0.1.dev9 → insightfactory_cli-1.0.1.dev10}/tests/test_cli.py

@@ -212,7 +212,7 @@ def test_parse_args_accepts_positionals_after_options():
         options=API_OPTIONS,
         allow_positionals=True,
     )
-    assert values_after == values_before == {"profile": "foundry-dev", "method": None, "data": None}
+    assert values_after == values_before == {"profile": "foundry-dev", "method": None, "data": None, "timeout": None}
     assert positionals_after == positionals_before == ["routes", "task"]
 
     describe_after, pos_after = parse_args(
@@ -225,7 +225,8 @@ def test_parse_args_accepts_positionals_after_options():
         options=API_OPTIONS,
         allow_positionals=True,
     )
-    assert describe_after == describe_before == {"profile": "foundry-dev", "method": None, "data": None}
+    expected = {"profile": "foundry-dev", "method": None, "data": None, "timeout": None}
+    assert describe_after == describe_before == expected
     assert pos_after == pos_before == ["describe", "GET", "/api/tasks"]
 
     config_after, config_pos_after = parse_args(
@@ -248,7 +249,7 @@ def test_parse_args_treats_tokens_after_double_dash_as_positionals():
         options=API_OPTIONS,
         allow_positionals=True,
     )
-    assert values == {"profile": "foundry-dev", "method": None, "data": None}
+    assert values == {"profile": "foundry-dev", "method": None, "data": None, "timeout": None}
     assert positionals == ["routes", "-X", "GET"]