froid-loop 0.11.1__py3-none-any.whl

froid_loop/journal.py

@@ -0,0 +1,178 @@
+"""Append-only run journal and atomic run-state persistence."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from .model import RunState
+from .platform_util import (
+    DIR_FD_ANCHORED_WRITES,
+    atomic_replace,
+    atomic_write_text,
+    atomic_write_text_at,
+    is_link_like,
+    open_dir_confined,
+)
+
+STATE_FILE = "state.json"
+JOURNAL_FILE = "journal.jsonl"
+LOGS_DIR = "logs"
+# Verifier subprocess streams, deliberately NOT under LOGS_DIR — see
+# Journal.write_verify_stream for why sharing that directory is a TUI bug.
+VERIFY_DIR = "verify"
+
+
+class Journal:
+    def __init__(self, run_dir: Path):
+        self.run_dir = run_dir
+        self.path = run_dir / JOURNAL_FILE
+        self._log_task: str | None = None
+        self._log_path: Path | None = None
+        run_dir.mkdir(parents=True, exist_ok=True)
+
+    def set_active_log(self, task_id: str) -> None:
+        """Entries from now on carry log_task/log_pos: the pane log of this
+        task and its byte size at append time. Deliberately not cleared on
+        session end — post-session entries (decisions, story-done) point at
+        the end of the log they are about; the next session replaces it."""
+        self._log_task = task_id
+        self._log_path = self.run_dir / LOGS_DIR / f"{task_id}.log"
+
+    def append(self, kind: str, **fields: Any) -> None:
+        entry = {"ts": time.time(), "kind": kind, **fields}
+        if self._log_path is not None:
+            try:
+                size = self._log_path.stat().st_size
+            except OSError:
+                size = 0  # pipe-pane has not created the file yet
+            entry.setdefault("log_task", self._log_task)
+            entry.setdefault("log_pos", size)
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, default=str) + "\n")
+
+    def write_verify_stream(self, name: str, content: str) -> str:
+        """Atomically retain one verifier subprocess stream under ``verify/`` and
+        return its run-relative pointer.  The journal records the pointer and byte
+        counts, never unbounded subprocess output inline.
+
+        Its own directory, not ``logs/``: every other inhabitant of ``logs/`` is a
+        coding-CLI pane capture named after a session task id.  The adapters own
+        that namespace (they write ``{task_id}.log``) and the TUI reads the whole
+        directory as one — with no session open, ``tui.data.active_task_id`` falls
+        back to the newest ``logs/*.log`` and returns its stem as the live task,
+        which the dashboard then reopens as ``logs/{stem}.log``.  Verifier streams
+        land in exactly that window: session-end is journalled when the session
+        ends, before its result reaches verification, so at the moment these files
+        are newest no session is open and the fallback fires.  Under ``logs/`` that
+        rendered verifier stderr in the agent log pane.  Keeping the store in a
+        separate directory makes that unrepresentable, rather than a name filter
+        every future reader of ``logs/`` would have to remember to apply.
+
+        ``name`` is engine-generated (not plugin or command supplied), so it is
+        safe to join below.  ``content`` arrives already bounded — the cap is
+        ``verify.stream_capture_kb``, applied by the caller, which is also where
+        the full-size and truncation bookkeeping lives; this method is journal
+        storage only and never decides how much to keep.  Callers retain the
+        original stream separately in a hook context.
+
+        :func:`atomic_write_text`, never ``write_text`` (#379) — the rule
+        ``install.py`` states flatly.  The fixed ``.tmp`` sibling this replaces is
+        the collision that helper's own docstring exists to prevent, and its
+        fsync-before-replace is what keeps a pointer from ever naming blocks that
+        were never written.  ``follow_symlinks=False`` because these are
+        machine-minted records under a run directory a coding-CLI session can
+        reach: honouring a planted link would aim the write at a path of that
+        session's choosing, and there is no operator-curated target here to
+        preserve (contrast the ledgers the default was built for).
+
+        Text mode is deliberate, and it is why the record's byte counts are
+        defined over the *stream*, not the file: ``\\n`` is translated on Windows,
+        so the file can be larger there than the count.  ``read_text`` normalizes
+        it back, so the content round-trips either way.
+
+        The write is **anchored at a directory descriptor** where the platform has
+        one, because ``follow_symlinks=False`` covers the final component and
+        nothing above it.  Sessions are handed this run directory outright
+        (``FROID_LOOP_RUN_DIR``, which is where they write ``result.json``), so a
+        session that plants a symlink at ``verify/`` before verification redirects
+        every record: ``mkdir(exist_ok=True)`` ACCEPTS a symlink-to-directory —
+        it re-raises only when ``is_dir()`` is false, and that follows links — and
+        the replace then lands wherever the link points, outside the run dir
+        entirely.  Measured, not theorised.
+
+        ``open_dir_confined`` is the fix the repo already keeps for exactly this
+        (``tui/launch.py`` writes its control-window record the same way): it walks
+        each component below the run dir ``O_NOFOLLOW`` and hands back a descriptor
+        for the directory it actually reached, and :func:`atomic_write_text_at`
+        never names a path again.  A path check would be answered *about a path*
+        and stale the moment it returned — the session can re-plant the link
+        between check and write — so this closes the window rather than narrowing
+        it.  The ``mkdir`` above may still be fooled; that is harmless, because the
+        confinement walk that follows is not, and refusal is what the fooled case
+        produces.
+
+        win32 has no ``*at()`` family to anchor against, so it keeps a
+        check-then-write, and the check is :func:`is_link_like` rather than
+        ``is_symlink()`` — on Windows the redirect that matters is a DIRECTORY
+        JUNCTION, which ``is_symlink()`` reports False for and which ``mklink /J``
+        creates with no elevation at all, while a directory symlink needs
+        SeCreateSymbolicLinkPrivilege or Developer Mode.  Checking only for
+        symlinks there would leave the unprivileged half of the same escape open,
+        and with no race to win.  The residual is the platform's: a path check is
+        stale the moment it returns, but the planting session runs as the same uid
+        as this writer and the names here are engine-minted, so the exposure is a
+        redirected diagnostic rather than a foothold.
+
+        Raises ``OSError`` — including when confinement cannot be established, so
+        an unconfined ``verify/`` REFUSES rather than writing through the link.
+        The caller degrades (this is observation), it does not swallow it here:
+        the record still lands, with a null pointer and ``capture_error``.
+        """
+        verify_dir = self.run_dir / VERIFY_DIR
+        verify_dir.mkdir(parents=True, exist_ok=True)
+        if DIR_FD_ANCHORED_WRITES:
+            dir_fd = open_dir_confined(self.run_dir, verify_dir)
+            if dir_fd is None:
+                raise OSError(
+                    f"refusing to write into an unconfined verify directory: {verify_dir}"
+                )
+            try:
+                atomic_write_text_at(dir_fd, name, content)
+            finally:
+                os.close(dir_fd)
+        else:
+            if is_link_like(verify_dir):
+                raise OSError(f"refusing to write into a redirected verify directory: {verify_dir}")
+            atomic_write_text(verify_dir / name, content, follow_symlinks=False)
+        return (verify_dir / name).relative_to(self.run_dir).as_posix()
+
+    def entries(self) -> list[dict[str, Any]]:
+        if not self.path.is_file():
+            return []
+        out = []
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return out
+
+
+def save_state(run_dir: Path, state: RunState) -> None:
+    run_dir.mkdir(parents=True, exist_ok=True)
+    target = run_dir / STATE_FILE
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(state.to_dict(), indent=2), encoding="utf-8")
+    atomic_replace(tmp, target)
+
+
+def load_state(run_dir: Path) -> RunState:
+    target = run_dir / STATE_FILE
+    return RunState.from_dict(json.loads(target.read_text(encoding="utf-8")))

froid_loop/machine.py

@@ -0,0 +1,148 @@
+"""The machine-readable output contract for CLI ``--json`` modes.
+
+``--json`` in its pure-document form means exactly one JSON object on stdout
+and nothing else — no trailers, no fenced blocks, no log lines. Every document
+carries an inline integer ``schema_version``; each command owns its own version
+constant (e.g. ``cli.STATUS_SCHEMA_VERSION``) so the documents evolve
+independently, the same convention as ``diagnostics.SCHEMA_VERSION``. Evolution
+is additive-only: new fields may appear, but anything breaking — removing or
+renaming a field, changing a type or the meaning of a value — bumps that
+command's version.
+
+Errors never produce a partial or error document: the message goes to stderr,
+stdout stays empty, and the exit code is nonzero. Consumers may rely on
+"stdout is either one complete valid document or empty".
+
+An **error** is a command that could not do its job — no runs to dump, an
+unresolvable run ref, a policy that will not parse. A command whose job is to
+report a *verdict* is a different thing: it did its job, and it exits nonzero to
+carry the answer. ``validate --json`` is the case — a failing check is the
+finding it was asked for, and the document is still owed. So the rule for
+consumers is positive rather than inferred from the exit code: **parse non-empty
+stdout whatever the exit code, and take the verdict from the document's own
+field** (``ok`` on ``validate``). That field, unlike rc, separates "the checks
+failed" from "the command broke": rc 1 is both, ``ok: false`` is only the first,
+and a command that broke leaves nothing on stdout to read the field from. Note
+that every gate in ``cmd_validate`` runs inside a ``try``, so the command has no
+error path of its own — its rc ∈ {0, 1} is purely the verdict.
+
+**Success does not imply a document on stdout.** ``diagnose`` and
+``probe-adapter`` also take ``--out FILE``; with both flags the document goes to
+the file and stdout is legitimately empty at exit 0, with only a confirmation on
+stderr. So empty stdout means "no document *here*" — check the exit code to tell
+a redirect from a failure, and do not treat rc 0 as a promise of bytes to parse.
+That file is held to the same standard as the stream: :func:`write_document` is
+the only way it is written, and validates exactly as :func:`emit_document` does.
+
+Every command that takes ``--json`` shares this contract; there is no exception
+(#195 removed the last two, ``diagnose`` and ``probe-adapter``, which used to
+append a fenced JSON block to a markdown/text report). A command adopting the
+flag adopts the whole of it — the contract is the flag's meaning, not a style
+the earlier commands happen to follow.
+
+Two ways in, by what the caller already holds:
+
+- :func:`emit` takes a ``dict`` and serializes it — ``status`` and ``list``.
+- :func:`emit_document` takes an already-serialized ``str`` — ``diagnose`` and
+  ``probe-adapter``, whose renderers return text. For both this is a hard
+  constraint: each serializes *before* running the shared leak self-check
+  (``sanitize.guard``), making those exact bytes the ones the check verified —
+  re-encoding them here would emit bytes nothing verified.
+
+:func:`write_document` is the ``--out`` sibling of :func:`emit_document`, taking
+the same already-serialized string to a file instead of stdout.
+
+The serializer flags differ by family on purpose and are not to be unified: the
+renderers behind :func:`emit_document` sort their keys (a diff-stable dump is
+worth more than field order there) while :func:`emit`'s dicts are built in the
+order they are meant to be read, and the two guarded renderers pass
+``ensure_ascii=False`` because the leak guard has to scan the values unescaped.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def emit(doc: dict[str, object]) -> None:
+    """The single stdout write in JSON mode."""
+    emit_document(json.dumps(doc, indent=2))
+
+
+def _validated(rendered: str) -> str:
+    """Return ``rendered`` unchanged, or raise if it is not a whole JSON document.
+
+    Parse to assert, never to re-serialize: the caller's exact bytes are what gets
+    written. The ``diagnose``/``probe-adapter`` renderers run their leak self-check
+    *before* handing the string over, so re-encoding here would ship bytes nothing
+    checked.
+    """
+    try:
+        json.loads(rendered)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"refusing to emit a malformed JSON document: {e}") from e
+    return rendered
+
+
+def emit_document(rendered: str) -> None:
+    """The single stdout write, for a document that is *already* serialized.
+
+    Verifies well-formedness before writing, then writes the ORIGINAL string —
+    never a re-serialization of the parsed result. Half the commands reach stdout
+    through here rather than through :func:`emit`, so without this the contract
+    would hold for them by convention only; but the guarded renderers validated
+    these exact bytes with their leak self-check, so emitting anything re-derived
+    would ship bytes nothing checked. Parse to assert, print verbatim.
+
+    Raises :class:`ValueError` on a malformed document — a bug in the caller's
+    renderer, and far better surfaced as a crash with empty stdout (which the
+    contract permits) than as a half-parsable stream a consumer has to diagnose.
+
+    stdout is switched to UTF-8 first, because a document is not necessarily
+    ASCII — the guarded renderers dump with ``ensure_ascii=False`` so the
+    leak guard can scan the values unescaped, which lets a non-sensitive
+    non-ASCII field (a localized ``platform.release()``, say) through to here
+    verbatim. Encoding it for a legacy non-UTF-8 console then raised
+    :class:`UnicodeEncodeError` before a byte was written (#200). Escaping the
+    output instead would have been the smaller change and the wrong one: it
+    breaks the invariant this function exists for, since the guard verified the
+    unescaped bytes. So the stream is made able to carry the document rather
+    than the document cut down to fit the stream.
+    """
+    document = _validated(rendered)
+    # Guarded: a substituted stdout (pytest capture, an exotic stream) may not be
+    # a TextIOWrapper at all. Falling through leaves the pre-#200 behaviour, which
+    # is a crash with stdout still empty — permitted by the contract above.
+    if hasattr(sys.stdout, "reconfigure"):
+        # hasattr-guarded: reconfigure exists on TextIOWrapper, not the TextIO base.
+        sys.stdout.reconfigure(  # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType]
+            encoding="utf-8"
+        )
+    print(document)
+
+
+def write_document(path: Path, rendered: str) -> None:
+    """The single file write in JSON mode — the bytes :func:`emit_document` prints.
+
+    ``--out FILE`` is the other half of the same contract, so it gets the same
+    validation and the same trailing newline: ``--json --out FILE`` and
+    ``--json > FILE`` produce byte-identical files. Without the parse the file was
+    the weaker half — stdout refused a malformed document while the file accepted
+    it, which is backwards, since a document written to a file is the one nobody
+    eyeballs before feeding it to a parser.
+
+    Raises :class:`ValueError` on a malformed document, before the file is created.
+    """
+    path.write_text(_validated(rendered) + "\n", encoding="utf-8")
+
+
+def add_json_flag(parser: argparse.ArgumentParser, what: str) -> None:
+    """Register ``--json`` with the standard help text."""
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help=f"emit a stable machine-readable JSON document ({what}) instead of text",
+    )