execsql2 2.23.1__py3-none-any.whl → 2.25.0__py3-none-any.whl

execsql/utils/fileio.py

@@ -7,7 +7,7 @@ Provides:
 
 - :class:`EncodedFile` — opens files with a specific encoding and error
   handler; supports the script-, output-, and import-encoding settings.
-- :class:`FileWriter` — asynchronous multiprocessing text-file writer
+- :class:`FileWriter` — asynchronous text-file writer thread, one per run,
   used for export output to avoid blocking the main execution loop.
 - :class:`Logger` — wraps a log file with timestamped write methods;
   mirrors output to stderr when ``tee_write_log`` is set.
@@ -24,18 +24,18 @@ import codecs
 import collections
 import errno
 import io
-import multiprocessing
 import os
 import queue
 import re
 from pathlib import Path
 import stat
-import sys
 import tempfile
+import threading
 import time
+import weakref
 from collections.abc import Callable
 from encodings.aliases import aliases as codec_dict
-from typing import Any, cast
+from typing import Any, NamedTuple, cast
 
 from execsql.exceptions import ErrInfo
 
@@ -43,6 +43,7 @@ __all__ = [
     "make_export_dirs",
     "check_dir",
     "FileWriter",
+    "LostOutput",
     "EncodedFile",
     "Logger",
     "TempFileMgr",
@@ -55,6 +56,8 @@ __all__ = [
     "filewriter_closeall",
     "filewriter_shutdown",
     "filewriter_end",
+    "redact",
+    "register_secret",
 ]
 
 
@@ -184,8 +187,21 @@ def safe_output_path(user_path: str, root: str | os.PathLike[str] | None) -> str
     return str(resolved)
 
 
-class FileWriter(multiprocessing.Process):
-    # An object of this class is intended to be used as a subprocess.
+class LostOutput(NamedTuple):
+    """Output a file never received, as the writer reports it."""
+
+    filename: str  # "" for an error not tied to one file
+    dropped: int  # writes discarded
+    error: str | None  # the OS error; None for an open that timed out
+    during: str  # "open", "write", "closed" (while still locked) or "writer"
+
+
+class FileWriter(threading.Thread):
+    # Each run owns one of these, held on its RuntimeContext and running as a
+    # daemon thread.  (Upstream used a subprocess; under the ``spawn`` start
+    # method that re-imported the caller's __main__, so a library caller's
+    # unguarded script ran a second time, and one writer was shared by every
+    # run in the process.)
     # All files that are to be written to are kept open until explicitly closed or the object is destroyed.
     # When writing to a file is requested, the file will be opened if it is not already open.  If the
     # file cannot be opened for writing, the content to be written will be queued up and opening will
@@ -201,10 +217,12 @@ class FileWriter(multiprocessing.Process):
         CMD_CLOSE_ALL_AFTER_WRITE,
         CMD_CLOSED_STATUS,
         CMD_PING,
-    ) = range(9)
+        CMD_OPEN_FAILURES,
+    ) = range(10)
 
     class FileControl:
-        STATUS_OPEN, STATUS_WAITING, STATUS_UNOPENED, STATUS_CLOSED, STATUS_OPENFAILURE = range(5)
+        STATUS_OPEN, STATUS_WAITING, STATUS_UNOPENED, STATUS_CLOSED, STATUS_OPENFAILURE, STATUS_WRITEFAILURE = range(6)
+        FAILED = (STATUS_OPENFAILURE, STATUS_WRITEFAILURE)
 
         def __init__(self, fn: str, open_timeout: int, encoding: str = "utf-8") -> None:
             self.filename = fn
@@ -214,9 +232,17 @@ class FileWriter(multiprocessing.Process):
             self.handle: io.TextIOWrapper | None = None
             self.status = self.STATUS_UNOPENED
             self.open_start_time: float | None = None
-            self.fail_message_written = False
             self.output_queue: collections.deque[str] = collections.deque()
             self.close_after_write = False
+            # Lines discarded because the file could not be opened within
+            # open_timeout, or could not be written; reported back to the
+            # caller, never silently lost.
+            self.dropped = 0
+            # The OS error that failed the file; None for an open that timed out.
+            self.error: str | None = None
+            # Lines discarded because the file was closed while still locked
+            # (a halt, or an exporter about to write the same path).
+            self.abandoned = 0
 
         def __del__(self) -> None:
             try:
@@ -224,11 +250,30 @@ class FileWriter(multiprocessing.Process):
             except Exception:
                 pass  # Best-effort cleanup at interpreter shutdown.
 
+        def fail(self, status: int, exc: BaseException) -> None:
+            """Give up on the file after *exc*: discard (and count) what is buffered, and buffer nothing more."""
+            self.status = status
+            self.error = str(exc)
+            self.dropped += len(self.output_queue)
+            self.output_queue.clear()
+            self.close_after_write = False
+            handle, self.handle = self.handle, None
+            if handle is not None:
+                try:
+                    handle.close()
+                except OSError:
+                    pass  # The file has already failed; its error is the one to report.
+
         def write_queue(self) -> None:
             assert self.handle is not None
             while len(self.output_queue) > 0:
                 m = self.output_queue.pop()
-                self.handle.write(m)
+                try:
+                    self.handle.write(m)
+                except OSError as exc:  # disk full, a share that dropped, ...
+                    self.dropped += 1
+                    self.fail(self.STATUS_WRITEFAILURE, exc)
+                    return
             if self.close_after_write:
                 self.close_after_write = False
                 self.close()
@@ -252,31 +297,41 @@ class FileWriter(multiprocessing.Process):
                                 errors="backslashreplace",
                             ),
                         )
-                    except Exception:
-                        self.status = self.STATUS_WAITING
+                    except Exception as exc:
+                        if _never_opens(self.filename, exc):
+                            self.fail(self.STATUS_OPENFAILURE, exc)
+                        else:
+                            self.status = self.STATUS_WAITING
                     else:
                         self.status = self.STATUS_OPEN
                         self.openmode = "a"  # Return to default for next open command.
                         self.open_start_time = None
-                        self.fail_message_written = False
                 else:
+                    # Give up: discard what was buffered (counting it so the
+                    # caller can report the loss) and stop buffering.
                     self.status = self.STATUS_OPENFAILURE
-                    if not self.fail_message_written:
-                        sys.stderr.write(
-                            f"Could not open {self.filename} for writing after retrying for {self.open_timeout} seconds",
-                        )
-                        self.fail_message_written = True
+                    self.dropped += len(self.output_queue)
+                    self.output_queue.clear()
+                    self.close_after_write = False
 
         def close(self) -> None:
             if self.status == self.STATUS_WAITING:
-                qlen = len(self.output_queue)
-                sys.stderr.write(
-                    f"Closing {self.filename} while still trying to open it (locked by another process?) -- {qlen} item(s) in queue to be written",
-                )
+                self.abandoned += len(self.output_queue)
+                self.output_queue.clear()
+                self.close_after_write = False
             if self.status == self.STATUS_OPEN and self.handle is not None:
                 self.write_queue()
-                self.handle.close()
+                if self.status == self.STATUS_WRITEFAILURE:
+                    return
+                try:
+                    self.handle.close()
+                except OSError as exc:  # the final flush failed
+                    self.handle = None
+                    self.fail(self.STATUS_WRITEFAILURE, exc)
+                    return
                 self.handle = None
+            if self.status in self.FAILED:
+                return  # Kept until the caller has been told about the loss.
             self.status = self.STATUS_CLOSED
             self.openmode = "a"  # Return this to the default in case it had been changed for the last open.
 
@@ -287,26 +342,28 @@ class FileWriter(multiprocessing.Process):
                 self.close()
 
         def write(self, content: str) -> None:
+            if self.status in self.FAILED:
+                self.dropped += 1
+                return
             self.output_queue.appendleft(content)
             self.try_open()
             if self.status == self.STATUS_OPEN:
                 self.write_queue()
 
-    def __init__(
-        self,
-        input_queue: multiprocessing.Queue,
-        return_msg_queue: multiprocessing.Queue,
-        file_encoding: str = "utf-8",
-        open_timeout: int = 600,
-    ) -> None:
+    def __init__(self, file_encoding: str = "utf-8", open_timeout: int = 600) -> None:
         # open_timeout is the maximum time, in seconds, that opening will be retried
         # if a file cannot be initially opened for writing.
-        super().__init__()
-        self.input_queue = input_queue
-        self.return_msg_queue = return_msg_queue
+        # Daemon, so a run that never reaches filewriter_end() cannot hold the
+        # interpreter open; the atexit handlers flush before daemons stop.
+        super().__init__(name="execsql-filewriter", daemon=True)
+        self.input_queue: queue.Queue[tuple[int, tuple[Any, ...]]] = queue.Queue()
+        self.return_msg_queue: queue.Queue[Any] = queue.Queue()
         self.file_encoding = file_encoding
         self.open_timeout = open_timeout
         self.files: dict[str, FileWriter.FileControl] = {}
+        # Commands that raised something other than a file's own OSError,
+        # reported with the failed files.
+        self.errors: list[LostOutput] = []
         self.active = True
         # Functions in execvec must be in the same order as the CMD enums.
         self.execvec: tuple[Callable[..., None], ...] = (
@@ -319,6 +376,7 @@ class FileWriter(multiprocessing.Process):
             self.close_all_after_write,
             self.closed_status,
             self.ping,
+            self.open_failures,
         )
 
     def __del__(self) -> None:
@@ -327,15 +385,23 @@ class FileWriter(multiprocessing.Process):
         except Exception:
             pass  # Best-effort cleanup at interpreter shutdown.
 
+    @staticmethod
+    def _on_file(fc: FileWriter.FileControl, action: Callable[[], None]) -> None:
+        """Run *action* on *fc*; anything it raises fails that file alone."""
+        try:
+            action()
+        except Exception as exc:
+            fc.fail(fc.STATUS_WRITEFAILURE, exc)
+
     def close_all(self) -> None:
         for fc in getattr(self, "files", {}).values():
-            fc.close()
+            self._on_file(fc, fc.close)
 
     def close_if_open(self, fn: str) -> None:
         filename = str(Path(fn).resolve())
         if filename in self.files:
             fc = self.files[filename]
-            fc.close()
+            self._on_file(fc, fc.close)
 
     def closed_status(self) -> None:
         # Return CLOSED for anything other than OPEN or WAITING
@@ -348,13 +414,54 @@ class FileWriter(multiprocessing.Process):
 
     def close_all_after_write(self) -> None:
         for fc in self.files.values():
-            if fc.status != self.FileControl.STATUS_CLOSED:
-                fc.clean_close()
+            if fc.status != self.FileControl.STATUS_CLOSED and fc.status not in fc.FAILED:
+                self._on_file(fc, fc.clean_close)
 
     def ping(self, token: object) -> None:
         """Echo *token* back on the return queue — used to synchronize callers."""
         self.return_msg_queue.put(token)
 
+    def retry_waiting(self) -> None:
+        """Re-attempt opening every file still waiting on a lock.
+
+        Called periodically from the writer loop, so a locked file is retried
+        (and its ``open_timeout`` honoured) even when the script writes nothing
+        more to it.  Without this a waiting file never reached
+        ``STATUS_OPENFAILURE`` and a flush waited on it forever.
+        """
+        for fc in self.files.values():
+            if fc.status == self.FileControl.STATUS_WAITING:
+                self._on_file(fc, fc.try_open)
+                if fc.status == self.FileControl.STATUS_OPEN:
+                    self._on_file(fc, fc.write_queue)
+
+    def open_failures(self) -> None:
+        """Report, and forget, every file whose output was lost.
+
+        Puts a list of :class:`LostOutput` on the return queue, then the
+        writer's own errors.  The failed entries are removed so a later
+        write to the same path starts afresh.
+        """
+        failed = [
+            LostOutput(
+                fn,
+                fc.dropped,
+                fc.error,
+                "open" if fc.status == fc.STATUS_OPENFAILURE else "write",
+            )
+            for fn, fc in self.files.items()
+            if fc.status in fc.FAILED
+        ]
+        for lost in failed:
+            del self.files[lost.filename]
+        for fn, fc in self.files.items():
+            if fc.abandoned:
+                failed.append(LostOutput(fn, fc.abandoned, None, "closed"))
+                fc.abandoned = 0
+        failed += self.errors
+        self.errors = []
+        self.return_msg_queue.put(failed)
+
     def open_as_new(self, fn: str) -> None:
         filename = str(Path(fn).resolve())
         if filename not in self.files:
@@ -364,7 +471,7 @@ class FileWriter(multiprocessing.Process):
                 encoding=self.file_encoding,
             )
         fc = self.files[filename]
-        fc.open_as_new()
+        self._on_file(fc, fc.open_as_new)
 
     def status(self, fn: str) -> None:
         filename = str(Path(fn).resolve())
@@ -382,57 +489,143 @@ class FileWriter(multiprocessing.Process):
                 encoding=self.file_encoding,
             )
         fc = self.files[filename]
-        fc.write(content)
+        self._on_file(fc, lambda: fc.write(content))
 
     def shutdown(self) -> None:
         self.active = False
         self.close_all()
 
-    def run(self) -> None:  # pragma: no cover – runs in a subprocess
-        # Ignore SIGINT in the child process — the parent owns Ctrl+C handling
-        # and will shut us down via CMD_SHUTDOWN on the queue.  Without this,
-        # KeyboardInterrupt races through queue.get() and close_all(), producing
-        # ugly tracebacks on stderr.
-        import signal
-
-        signal.signal(signal.SIGINT, signal.SIG_IGN)
-
+    def run(self) -> None:
         # Messages in the input queue consist of a 2-tuple, of which the first element
         # is a command and the second is a tuple of arguments for the function indicated
         # by that command.
+        # Waiting files are retried on a timer rather than only when the queue
+        # is idle: a caller polling CMD_CLOSED_STATUS keeps the queue busy.
+        last_retry = time.monotonic()
         while self.active:
             try:
                 command, argtuple = self.input_queue.get(timeout=0.1)
             except queue.Empty:
-                continue
-            self.execvec[command](*argtuple)
+                pass
+            else:
+                try:
+                    self.execvec[command](*argtuple)
+                except Exception as exc:
+                    self._command_failed(command, argtuple, exc)
+            if time.monotonic() - last_retry >= 0.1:
+                try:
+                    self.retry_waiting()
+                except Exception as exc:
+                    self.errors.append(LostOutput("", 0, str(exc), "writer"))
+                last_retry = time.monotonic()
+
+    def _command_failed(self, command: int, argtuple: tuple[Any, ...], exc: Exception) -> None:
+        """Record a command that raised, and still answer it if the caller waits for an answer.
+
+        A file's own OSErrors are handled by its FileControl; this catches
+        the rest, so one bad command cannot stop the thread (and with it
+        every later write, to any file).
+        """
+        filename = argtuple[0] if command != self.CMD_PING and argtuple and isinstance(argtuple[0], str) else ""
+        lost = LostOutput(filename, 0, str(exc), "writer")
+        if command == self.CMD_OPEN_FAILURES:
+            self.return_msg_queue.put([lost])
+            return
+        self.errors.append(lost)
+        replies: dict[int, Any] = {
+            self.CMD_GET_STATUS: self.FileControl.STATUS_CLOSED,
+            self.CMD_CLOSED_STATUS: self.FileControl.STATUS_CLOSED,
+            self.CMD_PING: argtuple[0] if argtuple else None,
+        }
+        if command in replies:
+            self.return_msg_queue.put(replies[command])
+
+
+def _never_opens(filename: str, exc: BaseException) -> bool:
+    """Whether an open that raised *exc* would fail however long it is retried.
+
+    Retrying exists for files another process holds for a moment (a backup
+    or sync tool's lock, which Windows reports as a PermissionError).  A
+    directory in the target's place, a parent that is a file, a read-only
+    filesystem or an over-long name will not change by waiting.  A missing
+    parent is still retried: on a network share it can be a dropped
+    connection that comes back.
+    """
+    if isinstance(exc, (IsADirectoryError, NotADirectoryError)):
+        return True
+    if isinstance(exc, OSError) and exc.errno in (errno.EROFS, errno.ENAMETOOLONG):
+        return True
+    return os.path.isdir(filename)  # Windows reports opening a directory as PermissionError
+
+
+def _writer_stopped(fw: FileWriter) -> bool:
+    """Whether *fw* was started and has ended without being shut down."""
+    return fw.ident is not None and fw.active and not fw.is_alive()
+
+
+def _writer_stopped_error() -> ErrInfo:
+    return ErrInfo(
+        "error",
+        other_msg="File output lost: the file writer stopped unexpectedly; output to files could not be written.",
+    )
 
 
-# Subprocess objects for asynchronous writing to text files.
-# filewriter is initialized in main(), so it can take configurable arguments.
-filewriter: FileWriter | None = None
-fw_input: multiprocessing.Queue = multiprocessing.Queue()
-fw_output: multiprocessing.Queue = multiprocessing.Queue()
+def _active_writer() -> FileWriter | None:
+    """The active run's writer if it is running, else ``None``.
 
+    Every entry point that puts a command on a writer's queue guards on this:
+    with no writer running (test contexts that bypass the CLI and
+    :func:`execsql.api.run`) a queued write would never be written, and a
+    wait for a reply would block forever.  A writer that was started and
+    stopped without being shut down raises :class:`ErrInfo`: its run's
+    output is being lost, which is an error, not "no writer configured".
+    """
+    import execsql.state as _state
+
+    fw = _state.filewriter
+    if fw is not None and _writer_stopped(fw):
+        raise _writer_stopped_error()
+    return fw if fw is not None and fw.is_alive() else None
+
+
+def _abspath(filename: str) -> str:
+    """*filename* made absolute against the working directory as it is now.
+
+    Resolved here, on the run's thread, rather than in the writer: a ``CD``
+    later in the script must not redirect output already queued.
+    """
+    return str(Path(filename).resolve())
+
+
+#: Sentinel returned by :func:`_writer_reply` when the writer died before
+#: answering.
+_NO_REPLY = object()
 
-def _writer_alive() -> bool:
-    """True if the FileWriter subprocess is running and consuming fw_input.
 
-    Every entry-point that puts a command on ``fw_input`` should guard on this:
-    if the subprocess isn't running (test contexts that bypass
-    ``_state.initialize()``, or a subprocess that crashed), unbounded ``put()``
-    calls eventually fill the OS pipe buffer (smaller on macOS than Linux) and
-    deadlock the caller. ``fw_output.get()`` calls would block forever on a
-    dead writer for the same reason.
+def _writer_reply(fw: FileWriter) -> Any:
+    """Wait for *fw*'s answer to the command just sent.
+
+    Polls with a short timeout and re-checks liveness between polls, so a
+    writer that dies mid-request cannot block the caller forever.  Returns
+    :data:`_NO_REPLY` if it died.
     """
-    return filewriter is not None and filewriter.is_alive()
+    while True:
+        try:
+            return fw.return_msg_queue.get(timeout=2.0)
+        except queue.Empty:
+            if not fw.is_alive():
+                return _NO_REPLY
 
 
 def filewriter_filestatus(filename: str) -> int:
-    if not _writer_alive():
+    fw = _active_writer()
+    if fw is None:
+        return FileWriter.FileControl.STATUS_CLOSED
+    fw.input_queue.put((FileWriter.CMD_GET_STATUS, (_abspath(filename),)))
+    reply = _writer_reply(fw)
+    if reply is _NO_REPLY:
         return FileWriter.FileControl.STATUS_CLOSED
-    fw_input.put((FileWriter.CMD_GET_STATUS, (filename,)))
-    return cast(int, fw_output.get())
+    return cast(int, reply)
 
 
 #: Set once the first dropped write has been reported, so a script writing
@@ -444,10 +637,9 @@ def _warn_write_dropped(filename: str) -> None:
     """Report, once per process, that file output is being discarded.
 
     Silently dropping a write is not a safe default: a script's logfile simply
-    comes back empty and the run still reports success.  The guard itself has
-    to stay — putting on a queue no subprocess is draining fills the OS pipe
-    buffer and deadlocks the caller — so the write is still dropped, but no
-    longer without saying so.
+    comes back empty and the run still reports success.  With no writer
+    running there is nothing to hand the write to, so it is still dropped,
+    but no longer without saying so.
     """
     global _drop_warned
     if _drop_warned:
@@ -458,8 +650,7 @@ def _warn_write_dropped(filename: str) -> None:
 
         write_warning(
             f'no file writer is running; output to "{filename}" and any later file '
-            "is discarded. Start one with execsql.utils.fileio.FileWriter, or run "
-            "the script through the CLI or execsql.api.run().",
+            "is discarded. Run the script through the CLI or execsql.api.run().",
             always=True,
         )
     except Exception:
@@ -467,78 +658,127 @@ def _warn_write_dropped(filename: str) -> None:
 
 
 def filewriter_write(filename: str, message: str) -> None:
-    if not _writer_alive():
+    fw = _active_writer()
+    if fw is None:
         _warn_write_dropped(filename)
         return
-    fw_input.put((FileWriter.CMD_WRITE, (filename, message)))
+    fw.input_queue.put((FileWriter.CMD_WRITE, (_abspath(filename), message)))
 
 
 def filewriter_open_as_new(filename: str) -> None:
     # FileWriter opens files in append mode ("a") by default.  This ensures that it
     # will be opened in write mode ("w") instead.  If the file is open, it will be closed.
-    if not _writer_alive():
+    fw = _active_writer()
+    if fw is None:
         _warn_write_dropped(filename)
         return
-    fw_input.put((FileWriter.CMD_OPEN_AS_NEW, (filename,)))
+    fw.input_queue.put((FileWriter.CMD_OPEN_AS_NEW, (_abspath(filename),)))
 
 
 def filewriter_close(filename: str) -> None:
-    # This is intended to be used by the main process to ensure that a file
-    # is closed before that process writes to it.
-    if not _writer_alive():
+    # This is intended to be used by the executing thread to ensure that a
+    # file is closed before it writes to that file itself.
+    fw = _active_writer()
+    if fw is None:
         return
-    fw_input.put((FileWriter.CMD_CLOSE_IF_OPEN, (filename,)))
+    filename = _abspath(filename)
+    fw.input_queue.put((FileWriter.CMD_CLOSE_IF_OPEN, (filename,)))
     while filewriter_filestatus(filename) == FileWriter.FileControl.STATUS_OPEN:
         time.sleep(0.05)
 
 
-def filewriter_close_all_after_write() -> None:
-    if not _writer_alive():
+def filewriter_close_all_after_write(max_wait: float | None = None) -> None:
+    """Flush and close every file the active run's writer holds, then report lost output.
+
+    Waits for files still locked by another process for up to the writer's
+    ``open_timeout`` (plus a small margin), or *max_wait* seconds if that is
+    shorter.  A file still locked then is closed and its output discarded,
+    and this raises :class:`ErrInfo` naming each file whose output was lost
+    and how much — a lost write is an error, not a silent success.
+    """
+    fw = _active_writer()
+    if fw is None:
         return
-    fw_input.put((FileWriter.CMD_CLOSE_ALL_AFTER_WRITE, ()))
-    all_closed = False
-    while not all_closed:
-        # Re-check liveness on every iteration: if the subprocess dies
-        # mid-loop, fw_output.get() would block forever otherwise.
-        if not _writer_alive():
-            return
-        fw_input.put((FileWriter.CMD_CLOSED_STATUS, ()))
-        try:
-            close_status = fw_output.get(timeout=2.0)
-        except queue.Empty:
-            # Either the writer is too slow or it died after the alive
-            # check above — recheck on the next iteration.
-            continue
-        all_closed = close_status == FileWriter.FileControl.STATUS_CLOSED
+    wait = fw.open_timeout + 5.0 if max_wait is None else min(fw.open_timeout + 5.0, max_wait)
+    deadline = time.monotonic() + wait
+    fw.input_queue.put((FileWriter.CMD_CLOSE_ALL_AFTER_WRITE, ()))
+    timed_out = False
+    while True:
+        if not fw.is_alive():
+            raise _writer_stopped_error()
+        fw.input_queue.put((FileWriter.CMD_CLOSED_STATUS, ()))
+        close_status = _writer_reply(fw)
+        if close_status is _NO_REPLY:
+            raise _writer_stopped_error()
+        if close_status == FileWriter.FileControl.STATUS_CLOSED:
+            break
+        if time.monotonic() > deadline:
+            timed_out = True
+            # Close what is still locked, so its discarded output is counted.
+            fw.input_queue.put((FileWriter.CMD_CLOSE_ALL, ()))
+            break
         time.sleep(0.05)
+    fw.input_queue.put((FileWriter.CMD_OPEN_FAILURES, ()))
+    failures = _writer_reply(fw)
+    if failures is _NO_REPLY:
+        raise _writer_stopped_error()
+    messages = [_lost_output_message(lost, fw.open_timeout) for lost in failures]
+    if timed_out and not messages:
+        messages.append(f"one or more output files were still locked after {wait:.0f} seconds")
+    if messages:
+        raise ErrInfo("error", other_msg="File output lost: " + "; ".join(messages) + ".")
+
+
+def _lost_output_message(lost: LostOutput, open_timeout: int) -> str:
+    if lost.during == "open" and lost.error is None:
+        cause = f"could not open {lost.filename} for writing within {open_timeout} seconds"
+    elif lost.during == "open":
+        cause = f"could not open {lost.filename} for writing ({lost.error})"
+    elif lost.during == "write":
+        cause = f"could not write {lost.filename} ({lost.error})"
+    elif lost.during == "closed":
+        cause = f"{lost.filename} was still locked by another process when it was closed"
+    elif lost.filename:
+        cause = f"file writer error on {lost.filename} ({lost.error})"
+    else:
+        cause = f"file writer error ({lost.error})"
+    return f"{cause}; {lost.dropped} line(s) of output to it were discarded" if lost.dropped else cause
 
 
 def filewriter_closeall() -> None:
-    if not _writer_alive():
+    fw = _active_writer()
+    if fw is None:
         return
-    fw_input.put((FileWriter.CMD_CLOSE_ALL, ()))
+    fw.input_queue.put((FileWriter.CMD_CLOSE_ALL, ()))
 
 
 def filewriter_shutdown() -> None:
-    if not _writer_alive():
+    fw = _active_writer()
+    if fw is None:
         return
-    fw_input.put((FileWriter.CMD_SHUTDOWN, ()))
+    fw.input_queue.put((FileWriter.CMD_SHUTDOWN, ()))
+
 
+def filewriter_end(writer: FileWriter | None = None) -> None:
+    """Close every file and stop *writer*, or the active run's writer if omitted.
+
+    Only that one writer is stopped: a run that halts leaves other runs'
+    output alone.  The join is capped so an ``atexit`` handler cannot wedge
+    interpreter shutdown on a writer stuck opening a file.
+    """
+    import execsql.state as _state
 
-def filewriter_end() -> None:
-    # join() with no timeout blocks forever if the subprocess is stuck;
-    # cap it so atexit handlers can't wedge Python shutdown.
-    if filewriter is None:
+    fw = writer if writer is not None else _state.filewriter
+    if fw is None:
         return
     try:
-        if filewriter.is_alive():
-            filewriter_shutdown()
-            filewriter.join(timeout=5.0)
-        if filewriter.is_alive():
-            filewriter.terminate()
-            filewriter.join(timeout=2.0)
+        if fw.is_alive():
+            fw.input_queue.put((FileWriter.CMD_SHUTDOWN, ()))
+            fw.join(timeout=5.0)
     except Exception:
         pass  # Best-effort cleanup at interpreter shutdown.
+    if _state.filewriter is fw:
+        _state.filewriter = None
 
 
 class EncodedFile:
@@ -714,7 +954,7 @@ class Logger:
             self.user,
             ", ".join([f"{k}: {cmdline_options[k]}" for k in cmdline_options]),
         )
-        self.writelog(msg)
+        self.writelog(self._redact(msg) or "")
         if server_name:
             msg = f"run_db_server\t{self.run_id}\t{server_name}\t{db_name}\n"
         else:
@@ -726,6 +966,7 @@ class Logger:
         self.exit_scriptfile: str | None = None
         self.exit_lno: int | None = None
         self.exit_description: str | None = None
+        self._exit_written = False
         atexit.register(self.log_exit)
 
     def _ts(self) -> str:
@@ -848,12 +1089,19 @@ class Logger:
         self.exit_lno = line_no
         self.exit_description = msg
 
-    def log_exit_exception(self, msg: str) -> None:
+    def log_exit_interrupted(self) -> None:
+        # Save values to be used by exit() function triggered on program exit
+        self.exit_type = "interrupted"
+        self.exit_scriptfile = None
+        self.exit_lno = None
+        self.exit_description = None
+
+    def log_exit_terminated(self) -> None:
         # Save values to be used by exit() function triggered on program exit
-        self.exit_type = "exception"
+        self.exit_type = "terminated"
         self.exit_scriptfile = None
         self.exit_lno = None
-        self.exit_description = self._redact(msg.replace("\n", ""))
+        self.exit_description = None
 
     def log_exit_error(self, msg: str | None) -> None:
         # Save values to be used by exit() function triggered on program exit
@@ -863,8 +1111,12 @@ class Logger:
         self.exit_description = self._redact(None if not msg else msg.replace("\n", ""))
 
     def log_exit(self) -> None:
+        """Write the run's ``exit`` record, once: ``exit_now`` writes it before closing the log, ``atexit`` otherwise."""
         import datetime as _datetime
 
+        if self._exit_written:
+            return
+        self._exit_written = True
         elapsed = (_datetime.datetime.now() - self.run_start).total_seconds()
         wmsg = "exit\t{}\t{}\t{}({})\t{}\t{:.1f}s\n".format(
             self.run_id,
@@ -877,6 +1129,29 @@ class Logger:
         self.writelog(wmsg)
 
 
+def register_secret(value: str | None) -> None:
+    """Keep *value* out of the active run's log from now on.
+
+    Called wherever a secret enters the run — a password typed at a prompt,
+    one read from a config file, DSN or keyring, a decrypted value — so a
+    later SQL statement, ``SYSTEM_CMD`` or error message that contains it is
+    logged with ``***`` instead.  A no-op when the run has no log.
+    """
+    import execsql.state as _state
+
+    add = getattr(_state.exec_log, "add_redaction_value", None)
+    if add is not None:
+        add(value)
+
+
+def redact(text: str) -> str:
+    """*text* with the active run's registered secrets and common secret shapes replaced by ``***``."""
+    import execsql.state as _state
+
+    redactor = getattr(_state.exec_log, "_redact", None)
+    return redactor(text) if redactor is not None else text
+
+
 class TempFileMgr:
     def __repr__(self) -> str:
         return "TempFileMgr()"
@@ -884,7 +1159,9 @@ class TempFileMgr:
     def __init__(self) -> None:
         # Initialize a list of temporary file names.
         self.temp_file_names: list = []
-        atexit.register(self.remove_all)
+        # One process-wide exit hook cleans every live manager; registering a
+        # hook per instance would add one for every execsql.run() call.
+        _live_tempfile_mgrs.add(self)
 
     def new_temp_fn(self) -> str:
         # Create a temp file securely via mkstemp (avoids TOCTOU race).
@@ -901,6 +1178,16 @@ class TempFileMgr:
                     os.unlink(fn)
                 except Exception:
                     pass
+        self.temp_file_names = []
+
+
+_live_tempfile_mgrs: weakref.WeakSet[TempFileMgr] = weakref.WeakSet()
+
+
+@atexit.register
+def _remove_all_temp_files() -> None:
+    for mgr in list(_live_tempfile_mgrs):
+        mgr.remove_all()
 
 
 def list_encodings() -> None: