sift-stack-py 0.17.0.dev3__tar.gz → 0.18.0__tar.gz

{sift_stack_py-0.17.0.dev3 → sift_stack_py-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sift_stack_py
-Version: 0.17.0.dev3
+Version: 0.18.0
 Summary: Python client library for the Sift API
 Maintainer-email: Sift Software Engineers <engineering@siftstack.com>
 License: Copyright (c) 2024 Azimuth Industries Inc.
@@ -55,7 +55,7 @@ Requires-Dist: polars~=1.8; extra == "all"
 Requires-Dist: pyOpenSSL<24.0.0; extra == "all"
 Requires-Dist: pyarrow>=17.0.0; extra == "all"
 Requires-Dist: rosbags~=0.0; python_full_version >= "3.8.2" and extra == "all"
-Requires-Dist: sift-stream-bindings==0.3.0; extra == "all"
+Requires-Dist: sift-stream-bindings==0.4.1; extra == "all"
 Requires-Dist: types-pyOpenSSL<24.0.0; extra == "all"
 Provides-Extra: build
 Requires-Dist: build==1.2.1; extra == "build"
@@ -94,7 +94,7 @@ Requires-Dist: pytest-randomly==3.15.0; extra == "dev-all"
 Requires-Dist: pytest==8.2.2; extra == "dev-all"
 Requires-Dist: rosbags~=0.0; python_full_version >= "3.8.2" and extra == "dev-all"
 Requires-Dist: ruff~=0.12.10; extra == "dev-all"
-Requires-Dist: sift-stream-bindings==0.3.0; extra == "dev-all"
+Requires-Dist: sift-stream-bindings==0.4.1; extra == "dev-all"
 Requires-Dist: tomlkit~=0.13.3; extra == "dev-all"
 Requires-Dist: types-pyOpenSSL<24.0.0; extra == "dev-all"
 Provides-Extra: development
@@ -146,7 +146,7 @@ Requires-Dist: pytest-randomly==3.15.0; extra == "docs-build"
 Requires-Dist: pytest==8.2.2; extra == "docs-build"
 Requires-Dist: rosbags~=0.0; python_full_version >= "3.8.2" and extra == "docs-build"
 Requires-Dist: ruff~=0.12.10; extra == "docs-build"
-Requires-Dist: sift-stream-bindings==0.3.0; extra == "docs-build"
+Requires-Dist: sift-stream-bindings==0.4.1; extra == "docs-build"
 Requires-Dist: tomlkit~=0.13.3; extra == "docs-build"
 Requires-Dist: types-pyOpenSSL<24.0.0; extra == "docs-build"
 Provides-Extra: file-imports
@@ -164,9 +164,9 @@ Requires-Dist: types-pyOpenSSL<24.0.0; extra == "openssl"
 Provides-Extra: rosbags
 Requires-Dist: rosbags~=0.0; python_full_version >= "3.8.2" and extra == "rosbags"
 Provides-Extra: sift-stream
-Requires-Dist: sift-stream-bindings==0.3.0; extra == "sift-stream"
+Requires-Dist: sift-stream-bindings==0.4.1; extra == "sift-stream"
 Provides-Extra: sift-stream-bindings
-Requires-Dist: sift-stream-bindings==0.3.0; extra == "sift-stream-bindings"
+Requires-Dist: sift-stream-bindings==0.4.1; extra == "sift-stream-bindings"
 Provides-Extra: tdms
 Requires-Dist: npTDMS~=1.9; extra == "tdms"
 

{sift_stack_py-0.17.0.dev3 → sift_stack_py-0.18.0}/lib/sift_client/_internal/low_level_wrappers/_test_results_log.py

@@ -32,8 +32,8 @@ versa), which is acceptable because writes are tiny and we only have one reader.
 
 Waiting for the lock is cooperative: ``AsyncFileLock`` retries a non-blocking
 acquire and sleeps on the event loop between attempts, so a contended or stale
-lock never blocks the loop thread (the hang in ENG-12003). The acquire is also
-bounded by ``LOG_LOCK_TIMEOUT_SECONDS``, surfacing a stuck lock as
+lock never blocks the loop thread. The acquire is also
+bounded by ``LOG_LOCK_TIMEOUT_SECONDS``, so a stuck lock surfaces as
 ``TimeoutError`` instead of waiting forever. The file read/write under the lock
 runs inline on the loop; it is a tiny local-file operation, the same class of
 brief synchronous work async methods do throughout this client.

{sift_stack_py-0.17.0.dev3 → sift_stack_py-0.18.0}/lib/sift_client/_internal/low_level_wrappers/ingestion.py

@@ -236,6 +236,86 @@ class IngestionLowLevelClient(LowLevelClientBase, WithGrpcClient):
         return _hash_flows(asset_name=asset_name, flows=flows)
 
 
+async def _build_sift_stream_instance(
+    api_key: str,
+    grpc_uri: str,
+    ingestion_config_form: IngestionConfigFormPy,
+    run_form: RunFormPy | None = None,
+    run_id: str | None = None,
+    asset_tags: list[str] | None = None,
+    asset_metadata: list[MetadataPy] | None = None,
+    streaming_mode: StreamingMode = ...,  # type: ignore[assignment]
+    retry_policy: RetryPolicyPy | None = None,
+    disk_backup_policy: DiskBackupPolicyPy | None = None,
+    checkpoint_interval_seconds: int | None = None,
+    enable_tls: bool = True,
+    tracing_config: TracingConfig | None = None,
+) -> SiftStreamPy:
+    """Build a raw `SiftStreamPy` without wrapping it in a client.
+
+    Shared by both `IngestionConfigStreamingLowLevelClient` and the auto-register path.
+    """
+    # Importing here to allow sift_stream_bindings to be an optional dependency for non-ingestion users
+    # TODO(nathan): Fix bindings to fix mypy issues with tracing functions
+    from sift_stream_bindings import (  # type: ignore[attr-defined]
+        DurationPy,
+        SiftStreamBuilderPy,
+        init_tracing,  # type: ignore[attr-defined]
+        init_tracing_with_file,  # type: ignore[attr-defined]
+        is_tracing_initialized,  # type: ignore[attr-defined]
+    )
+
+    from sift_client.resources.ingestion import StreamingMode, TracingConfig
+
+    _default_max_log_files = 7
+    _default_logfile_prefix = "sift_stream_bindings.log"
+
+    if streaming_mode is ...:  # type: ignore[comparison-overlap]
+        streaming_mode = StreamingMode.LIVE_WITH_BACKUPS
+
+    if not is_tracing_initialized():
+        if tracing_config is None:
+            tracing_config = TracingConfig.with_file()
+
+        if tracing_config.log_dir is not None:
+            init_tracing_with_file(
+                tracing_config.level,
+                tracing_config.log_dir,
+                tracing_config.filename_prefix or _default_logfile_prefix,
+                tracing_config.max_log_files or _default_max_log_files,
+            )
+        else:
+            init_tracing(tracing_config.level)
+
+    sift_builder = SiftStreamBuilderPy(uri=grpc_uri, apikey=api_key)
+    sift_builder.enable_tls = enable_tls
+
+    config_builder = sift_builder.ingestion_config(ingestion_config_form)
+    config_builder.run = run_form
+    config_builder.run_id = run_id
+    config_builder.asset_tags = asset_tags
+    config_builder.metadata = asset_metadata
+
+    if streaming_mode == StreamingMode.LIVE_ONLY:
+        return await config_builder.live_only().build()
+
+    elif streaming_mode == StreamingMode.FILE_BACKUP:
+        fb_builder = config_builder.file_backup()
+        if disk_backup_policy is not None:
+            fb_builder.disk_backup_policy = disk_backup_policy
+        return await fb_builder.build()
+
+    else:  # LIVE_WITH_BACKUPS (default)
+        lwb_builder = config_builder.live_with_backups()
+        if retry_policy is not None:
+            lwb_builder.retry_policy = retry_policy
+        if disk_backup_policy is not None:
+            lwb_builder.disk_backup_policy = disk_backup_policy
+        if checkpoint_interval_seconds is not None:
+            lwb_builder.checkpoint_interval = DurationPy(secs=checkpoint_interval_seconds, nanos=0)
+        return await lwb_builder.build()
+
+
 class IngestionConfigStreamingLowLevelClient(LowLevelClientBase):
     DEFAULT_MAX_LOG_FILES = 7  # Equal to 1 week of logs
     DEFAULT_LOGFILE_PREFIX = "sift_stream_bindings.log"
@@ -262,67 +342,21 @@ class IngestionConfigStreamingLowLevelClient(LowLevelClientBase):
         enable_tls: bool = True,
         tracing_config: TracingConfig | None = None,
     ) -> IngestionConfigStreamingLowLevelClient:
-        # Importing here to allow sift_stream_bindings to be an optional dependancy for non-ingestion users
-        # TODO(nathan): Fix bindings to fix mypy issues with tracing functions
-        from sift_stream_bindings import (  # type: ignore[attr-defined]
-            DurationPy,
-            SiftStreamBuilderPy,
-            init_tracing,  # type: ignore[attr-defined]
-            init_tracing_with_file,  # type: ignore[attr-defined]
-            is_tracing_initialized,  # type: ignore[attr-defined]
+        sift_stream_instance = await _build_sift_stream_instance(
+            api_key=api_key,
+            grpc_uri=grpc_uri,
+            ingestion_config_form=ingestion_config_form,
+            run_form=run_form,
+            run_id=run_id,
+            asset_tags=asset_tags,
+            asset_metadata=asset_metadata,
+            streaming_mode=streaming_mode,
+            retry_policy=retry_policy,
+            disk_backup_policy=disk_backup_policy,
+            checkpoint_interval_seconds=checkpoint_interval_seconds,
+            enable_tls=enable_tls,
+            tracing_config=tracing_config,
         )
-
-        from sift_client.resources.ingestion import StreamingMode, TracingConfig
-
-        if streaming_mode is ...:  # type: ignore[comparison-overlap]
-            streaming_mode = StreamingMode.LIVE_WITH_BACKUPS
-
-        if not is_tracing_initialized():
-            if tracing_config is None:
-                tracing_config = TracingConfig.with_file()
-
-            if tracing_config.log_dir is not None:
-                # Use file logging
-                init_tracing_with_file(
-                    tracing_config.level,
-                    tracing_config.log_dir,
-                    tracing_config.filename_prefix or cls.DEFAULT_LOGFILE_PREFIX,
-                    tracing_config.max_log_files or cls.DEFAULT_MAX_LOG_FILES,
-                )
-            else:
-                # Use stdout/stderr only
-                init_tracing(tracing_config.level)
-
-        sift_builder = SiftStreamBuilderPy(uri=grpc_uri, apikey=api_key)
-        sift_builder.enable_tls = enable_tls
-
-        config_builder = sift_builder.ingestion_config(ingestion_config_form)
-        config_builder.run = run_form
-        config_builder.run_id = run_id
-        config_builder.asset_tags = asset_tags
-        config_builder.metadata = asset_metadata
-
-        if streaming_mode == StreamingMode.LIVE_ONLY:
-            sift_stream_instance = await config_builder.live_only().build()
-
-        elif streaming_mode == StreamingMode.FILE_BACKUP:
-            fb_builder = config_builder.file_backup()
-            if disk_backup_policy is not None:
-                fb_builder.disk_backup_policy = disk_backup_policy
-            sift_stream_instance = await fb_builder.build()
-
-        else:  # LIVE_WITH_BACKUPS (default)
-            lwb_builder = config_builder.live_with_backups()
-            if retry_policy is not None:
-                lwb_builder.retry_policy = retry_policy
-            if disk_backup_policy is not None:
-                lwb_builder.disk_backup_policy = disk_backup_policy
-            if checkpoint_interval_seconds is not None:
-                lwb_builder.checkpoint_interval = DurationPy(
-                    secs=checkpoint_interval_seconds, nanos=0
-                )
-            sift_stream_instance = await lwb_builder.build()
-
         return cls(sift_stream_instance)
 
     async def send(self, flow: FlowPy):

{sift_stack_py-0.17.0.dev3 → sift_stack_py-0.18.0}/lib/sift_client/_internal/pyproject_config.py

@@ -3,7 +3,7 @@
 The pytest plugin consumes this loader to resolve report-content config (under
 ``[tool.sift.pytest.report]``) and SDK-level fallbacks (URIs under
 ``[tool.sift]``). A malformed or missing ``pyproject.toml`` returns ``{}`` so a
-bad config file never aborts the session — the plugin falls back to its
+bad config file never aborts the session. The plugin falls back to its
 built-in defaults and surfaces a single warning.
 """
 

{sift_stack_py-0.17.0.dev3 → sift_stack_py-0.18.0}/lib/sift_client/_internal/pytest_plugin/audit_log.py

@@ -2,15 +2,15 @@
 
 On by default: every session attaches two handlers to the ``sift_client`` root
 logger so plugin-behavior modules AND high-value SDK call sites land in one file
-(a temp file unless ``--sift-audit-log=<path>`` pins one), with warnings also
-echoed to stdout. Pass ``--sift-audit-log=false`` (or set ``sift_audit_log =
-"false"``) to turn it off. The replay subprocess gets its own sibling file via
+(in the run's ``--sift-output-dir``, or a temp dir), with warnings also echoed
+to stdout. Pass ``--no-sift-audit-log`` (or set ``sift_audit_log = false``) to
+turn it off. The replay subprocess gets its own sibling file via
 ``replay_audit_path``.
 
 Handlers are removed at session end (``pytest_unconfigure`` ->
-``detach_audit_handlers``) so a process that runs many pytest sessions — the
-plugin's own test suite drives nested in-process sessions — doesn't accumulate
-handlers or leak one session's file into the next.
+``detach_audit_handlers``) so a process that runs many pytest sessions does not
+accumulate handlers or leak one session's file into the next. This matters
+because the plugin's own test suite drives nested in-process sessions.
 
 TODO: levels are fixed (DEBUG file / WARNING stdout) and output is plain text.
 A configurable level, JSON lines, or rotation are follow-ups gated on real need.
@@ -29,7 +29,7 @@ if TYPE_CHECKING:
 
 ROOT_LOGGER = "sift_client"
 # Columnar line for easy parsing: fixed-width timestamp, level, and namespace
-# columns, then the message — which every plugin call starts with a
+# columns, then the message. Every plugin call starts the message with a
 # left-justified ``EVENT_WIDTH`` event token followed by space-separated
 # key=value fields (incl. the full test ``path=``). Fields never contain spaces
 # (lists are ``/``-joined, free text is quoted), so the line tokenizes cleanly
@@ -95,7 +95,7 @@ class ColumnFormatter(logging.Formatter):
 
     Adds a ``namespace`` field (the logger name with the redundant
     ``sift_client.`` prefix trimmed) as its own aligned column, without mutating
-    ``record.name`` — other handlers (e.g. pytest's log capture) see the record
+    ``record.name``, so other handlers (e.g. pytest's log capture) see the record
     unchanged.
     """
 
@@ -110,41 +110,17 @@ def replay_audit_path(main_path: Path) -> Path:
     return main_path.with_suffix(".replay" + main_path.suffix)
 
 
-def audit_disabled(value: object) -> bool:
-    """Whether audit logging is explicitly turned off.
+def _make_session_dir(base: Path | None = None) -> Path:
+    """Create and return ``<base>/<random>/`` for this run's artifacts.
 
-    Default on: only ``False`` / ``"false"`` / ``"none"`` disables. Anything
-    else — unset, ``"true"``, or a path — leaves it enabled.
+    ``base`` is the ``--sift-output-dir`` directory when set, else
+    ``<tmpdir>/sift_test_results``. Each run gets its own random subfolder (from
+    ``tempfile.mkdtemp``) so repeated or concurrent runs never collide, and all
+    of a run's artifacts (JSONL log, tracking sidecar, audit log, replay audit
+    log) land inside it together.
     """
-    if value is False:
-        return True
-    return isinstance(value, str) and value.strip().lower() in ("false", "none")
-
-
-def explicit_audit_path(value: object) -> Path | None:
-    """The file path the user pinned, or ``None`` to use a temp default.
-
-    ``"true"`` / ``"1"`` / unset all mean "enabled, no specific path", so the
-    caller falls back to :func:`default_audit_path`.
-    """
-    if not isinstance(value, str):
-        return None
-    text = value.strip()
-    if text.lower() in ("", "true", "1", "false", "none"):
-        return None
-    return Path(text)
-
-
-def _make_session_dir() -> Path:
-    """Create and return ``<tmpdir>/sift_test_results/<random>/``.
-
-    All per-session temp artifacts (JSONL log, tracking sidecar, audit log,
-    replay audit log) land inside this directory so they're easy to locate and
-    clean up together. The random component comes from ``tempfile.mkdtemp`` —
-    the same OS-backed source used by ``NamedTemporaryFile``.
-    """
-    parent = Path(tempfile.gettempdir()) / "sift_test_results"
-    parent.mkdir(exist_ok=True)
+    parent = base if base is not None else Path(tempfile.gettempdir()) / "sift_test_results"
+    parent.mkdir(parents=True, exist_ok=True)
     return Path(tempfile.mkdtemp(dir=parent, prefix=""))
 
 
@@ -198,10 +174,9 @@ def configure_audit_logging(
     """
     from sift_client._internal.pytest_plugin.options import AUDIT_LOG_OPTION
 
-    raw = AUDIT_LOG_OPTION.resolve(config)
-    if audit_disabled(raw):
+    if not AUDIT_LOG_OPTION.resolve(config):
         return None
-    path = explicit_audit_path(raw) or default_audit_path(session_dir=session_dir)
+    path = default_audit_path(session_dir=session_dir)
     attach_file_handler(path)
     logger = logging.getLogger(ROOT_LOGGER)
     if not any(
@@ -226,7 +201,7 @@ def detach_audit_handlers(*, root: str = ROOT_LOGGER) -> None:
     """Remove and close the audit handlers; reset the logger level.
 
     Called from ``pytest_unconfigure`` so handlers don't outlive the session
-    that created them — important when one process runs many sessions (the
+    that created them. This matters when one process runs many sessions (the
     plugin's own test suite drives nested in-process pytester runs).
     """
     logger = logging.getLogger(root)
@@ -239,15 +214,34 @@ def detach_audit_handlers(*, root: str = ROOT_LOGGER) -> None:
 
 # Width the status column is right-aligned to in the rendered tree.
 _TREE_WIDTH = 64
+# Width the status column is left-justified to, so the ``[start -> end]`` window
+# starts at the same column on every line. ``IN_PROGRESS`` (11) is the longest
+# status; a never-closed step that overflows just shifts its own window.
+_STATUS_WIDTH = 11
+
+
+def _fmt_clock(dt: Any) -> str:
+    """Wall-clock ``HH:MM:SS.mmm`` (UTC) for a step time, or a dashed placeholder.
+
+    Millisecond precision is enough to read execution order off the tree; the
+    full timestamp lives in the JSONL. ``None`` (a step that never stamped a
+    time) renders as ``--:--:--.---`` so the column still aligns.
+    """
+    if dt is None:
+        return "--:--:--.---"
+    return dt.strftime("%H:%M:%S.") + f"{dt.microsecond // 1000:03d}"
 
 
 def render_report_tree(created_steps: list[Any], *, mode: str) -> str:
-    """Render the final step tree with statuses — the end-state validation view.
+    """Render the final step tree with statuses, the end-state validation view.
 
     Reconstructs the parent/child structure from each step's dotted numeric
     ``step_path`` (``"1"`` -> ``"1.1"`` -> ``"1.1.2"``), preserving creation
-    order, and renders an ASCII tree with a dotted leader to the final status.
-    Failed/errored steps are annotated with the first line of their
+    order, and renders an ASCII tree with a dotted leader to the final status,
+    then each node's ``[start -> end]`` execution window (UTC, ms precision).
+    Because nodes render in creation order, not chronological order, a parent's
+    window can start before a sibling that ran earlier — the times make that
+    visible. Failed/errored steps are annotated with the first line of their
     ``error_info`` when present, so a reader sees what went wrong inline.
     """
     header = f"Sift report tree ({mode} mode):"
@@ -277,7 +271,8 @@ def render_report_tree(created_steps: list[Any], *, mode: str) -> str:
             head = f"{prefix}{connector}{step.name} "
             child_prefix = prefix + ("   " if is_last else "|  ")
         leader = "." * max(3, _TREE_WIDTH - len(head))
-        line = f"{head}{leader} {status}"
+        window = f"[{_fmt_clock(getattr(step, 'start_time', None))} -> {_fmt_clock(getattr(step, 'end_time', None))}]"
+        line = f"{head}{leader} {status:<{_STATUS_WIDTH}} {window}"
         error = getattr(step, "error_info", None)
         if status in ("FAILED", "ERROR") and error is not None and error.error_message:
             line += f"   <- {error.error_message.strip().splitlines()[0]}"

{sift_stack_py-0.17.0.dev3 → sift_stack_py-0.18.0}/lib/sift_client/_internal/pytest_plugin/options.py

@@ -217,22 +217,36 @@ def _walk_toml(data: dict[str, Any], path: tuple[str, ...]) -> Any:
 #     loads .env for local dev; CI sets the same names from its secret store).
 # ---------------------------------------------------------------------------
 
-# Pytest behavior. The CLI flag survives because the per-run override is real.
+# Pytest behavior. The CLI flags survive because the per-run override is real.
+OUTPUT_DIR_OPTION = Option(
+    name="output_dir",
+    category=CAT_BEHAVIOR,
+    help="Directory for this run's artifacts (JSONL log, audit trace). Each run gets "
+    "its own random subfolder. Defaults to a temp directory.",
+    cli="--sift-output-dir",
+    ini="sift_output_dir",
+)
 LOG_FILE_OPTION = Option(
     name="log_file",
     category=CAT_BEHAVIOR,
-    help="Path to the JSONL log of create/update calls (path | true | false | none).",
-    cli="--sift-log-file",
+    help="Write the JSONL log of create/update calls. On by default; "
+    "--no-sift-log-file disables it (incompatible with --sift-offline).",
+    cli="--no-sift-log-file",
+    cli_action="store_false",
     ini="sift_log_file",
+    ini_type="bool",
+    ini_default=True,
 )
 AUDIT_LOG_OPTION = Option(
     name="audit_log",
     category=CAT_BEHAVIOR,
-    help="DEBUG-level audit trace of plugin behavior (path | true | false). On by "
-    "default to a temp file, with warnings echoed to stdout; set a path to pin the "
-    "file, or false to disable.",
-    cli="--sift-audit-log",
+    help="Write the DEBUG audit trace of plugin behavior, with warnings echoed to "
+    "stdout. On by default; --no-sift-audit-log disables it.",
+    cli="--no-sift-audit-log",
+    cli_action="store_false",
     ini="sift_audit_log",
+    ini_type="bool",
+    ini_default=True,
 )
 GIT_METADATA_OPTION = Option(
     name="git_metadata",
@@ -406,6 +420,7 @@ METADATA_OPTION = Option(
 )
 
 PLUGIN_OPTIONS: tuple[Option, ...] = (
+    OUTPUT_DIR_OPTION,
     LOG_FILE_OPTION,
     AUDIT_LOG_OPTION,
     GIT_METADATA_OPTION,

{sift_stack_py-0.17.0.dev3 → sift_stack_py-0.18.0}/lib/sift_client/_internal/pytest_plugin/report.py

@@ -55,7 +55,7 @@ logger = logging.getLogger(__name__)
 def resolve_real_report_id(context: Any) -> str | None:
     """Resolve the real server-side report id for the online footer link.
 
-    In synchronous online mode (``--sift-log-file=false``) the report is created
+    In synchronous online mode (``--no-sift-log-file``) the report is created
     directly against the API, so ``report.id_`` is already the real id. In the
     default incremental mode the report is created through the simulate path
     (a client-side UUID) and the background worker maps it to the real id on
@@ -377,41 +377,20 @@ def format_template(
         return fallback
 
 
-def resolve_log_file(pytestconfig: pytest.Config | None) -> str | Path | bool | None:
-    """Determine log_file value from CLI flag or ini key.
+def log_file_enabled(pytestconfig: pytest.Config | None) -> bool:
+    """Whether the JSONL log of create/update calls is written.
 
-    Three signal types arrive here:
-
-    * ``None``: unset; nothing was passed on the CLI and the ini key is
-      absent. Treat as the default "use a temp file."
-    * Python ``False``: an explicit disable, typically set in a conftest via
-      ``config.option.sift_log_file = False``. Return ``None`` so
-      the rest of the pipeline knows to skip logging entirely.
-    * A string (from CLI or ini): interpret ``"true"`` / ``"1"`` as the temp
-      file default, ``"false"`` / ``"none"`` as disable, anything else as a
-      file path.
-
-    Rejects ``--sift-log-file=none`` combined with ``--sift-offline`` since
-    offline mode needs the log file as its sole sink.
+    On by default; ``--no-sift-log-file`` disables it. Offline mode routes every
+    create/update call through the log as its only sink, so disabling the log
+    while offline is a usage error.
     """
-    raw = LOG_FILE_OPTION.resolve(pytestconfig)
-    disabled = raw is False or (isinstance(raw, str) and raw.lower() in ("false", "none"))
-    if disabled and is_offline(pytestconfig):
+    enabled = bool(LOG_FILE_OPTION.resolve(pytestconfig))
+    if not enabled and is_offline(pytestconfig):
         raise pytest.UsageError(
-            "--sift-log-file=none is incompatible with --sift-offline; offline "
-            "mode requires a log file. Pin one with --sift-log-file=<path>, or "
-            "drop --sift-log-file=none to use a temp file."
+            "--no-sift-log-file is incompatible with --sift-offline; offline mode "
+            "requires the JSONL log as its only sink. Drop one of the two flags."
         )
-    if raw is False:
-        return None
-    if not raw:
-        return True
-    lower = str(raw).lower()
-    if lower in ("true", "1"):
-        return True
-    if lower in ("false", "none"):
-        return None
-    return Path(raw)
+    return enabled
 
 
 def report_context_impl(
@@ -458,15 +437,16 @@ def report_context_impl(
         "pytest_command": command,
     }
     # Mode → ReportContext flags:
-    #   online (default): log_file=<temp or user path>, replay_log_file=True
-    #   --sift-offline:   log_file=<temp or user path>, replay_log_file=False
-    #   --sift-disabled:  log_file=False,               replay_log_file=False
+    #   online (default): log_file=<path in session dir>, replay_log_file=True
+    #   --sift-offline:   log_file=<path in session dir>, replay_log_file=False
+    #   --sift-disabled / --no-sift-log-file: log_file=False, replay_log_file=False
     disabled = sift_client._simulate
     offline = False if disabled else is_offline(pytestconfig)
-    log_file: str | Path | bool | None = False if disabled else resolve_log_file(pytestconfig)
-    # When the log would use a default temp file and the plugin already created
-    # a session dir, pin the JSONL inside that dir so it lands alongside the
-    # audit log rather than having ReportContext mint a separate session dir.
+    log_file: str | Path | bool = False if disabled else log_file_enabled(pytestconfig)
+    # Place the JSONL inside the run's session dir so it lands alongside the
+    # audit log. pytest_configure created the dir whenever the log is enabled; if
+    # one isn't present (e.g. ReportContext used outside pytest), log_file stays
+    # True and ReportContext mints its own dir.
     if log_file is True and pytestconfig is not None:
         from sift_client.pytest_plugin import SIFT_SESSION_DIR_STASH_KEY