froid-loop 0.11.1__py3-none-any.whl

froid_loop/data/froid_loop_hook.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Coding-CLI hook relay for froid-loop. Stdlib only.
+
+Each CLI's hook config registers this script under its native event names
+(Claude/Codex: SessionStart/Stop/..., Gemini: AfterAgent for Stop, Copilot:
+agentStop for Stop) but always passes the CANONICAL event name as argv[1] — the
+orchestrator only ever sees canonical events. Payload keys vary too: snake_case
+(claude/codex), conversation_id (cursor), or camelCase (copilot's sessionId/
+transcriptPath, agy's conversationId/transcriptPath — protojson encoding); the
+field extraction below tries each. agy alone carries no cwd, sending the
+workspacePaths list instead. Reads the hook payload
+from stdin and writes one event file
+into the orchestrator's events directory. No-ops (exit 0) unless the session was
+spawned by froid-loop (detected via env vars set on the tmux window), so
+normal interactive sessions are unaffected.
+
+Where that directory is: $FROID_LOOP_EVENTS_DIR when the orchestrator names one,
+else the legacy $FROID_LOOP_RUN_DIR/events. The channel moved out of the project
+tree in #494 so a branch switch or a worktree mount cannot take a live run's
+control plane away, and this script is COPIED into the target project at init
+time — so an upgraded orchestrator regularly drives sessions whose installed
+copy is this file's older self, which knows only the legacy path. That pairing
+is what the orchestrator's own dual poll (signals.SignalWatcher) covers.
+
+$FROID_LOOP_EVENTS_DIR is deliberately NOT part of the no-op detector above: the
+mirror-image skew — an older orchestrator that sets only RUN_DIR/TASK_ID driving
+a session whose installed relay is this newer file — must still write its
+events, and requiring the new variable would silently stall every one of those
+runs instead.
+"""
+
+import json
+import os
+import stat
+import sys
+import time
+
+# Windows reparse tags that make a directory entry REDIRECT somewhere else,
+# compared against os.lstat().st_reparse_tag (Windows, 3.8+). Deliberately not
+# os.path.isjunction(), which is 3.12+ — this relay runs under whatever
+# interpreter the host has, not under the orchestrator's. Deliberately not "any
+# reparse tag" either: cloud placeholders (OneDrive) and dedup stubs are reparse
+# points too, and refusing those would stall a legitimate run. Empty on POSIX.
+_LINK_REPARSE_TAGS = tuple(
+    tag
+    for tag in (
+        getattr(stat, "IO_REPARSE_TAG_SYMLINK", None),
+        getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", None),
+    )
+    if tag is not None
+)
+
+
+def _first_workspace(payload):
+    paths = payload.get("workspacePaths")
+    if isinstance(paths, list) and paths and isinstance(paths[0], str):
+        return paths[0]
+    return None
+
+
+def _is_link_like(path):
+    """True when `path` redirects elsewhere: a POSIX symlink, or a Windows
+    symlink OR DIRECTORY JUNCTION.
+
+    `os.path.islink()` is False for a junction — junctions are a distinct
+    reparse kind, which is why `os.path.isjunction()` exists at all. On Windows
+    the junction is the arm that matters: `mklink /J` needs no elevation, while
+    a directory symlink needs SeCreateSymbolicLinkPrivilege or Developer Mode —
+    so the unprivileged attack is exactly the one `islink()` misses.
+    """
+    if os.path.islink(path):
+        return True
+    try:
+        return getattr(os.lstat(path), "st_reparse_tag", 0) in _LINK_REPARSE_TAGS
+    except OSError:
+        return False
+
+
+def _write_all(fd, data):
+    """Write every byte of `data` to `fd`.
+
+    `os.write()` may write FEWER bytes than asked and simply return the count. A
+    truncated event file is not merely retried, it is lost: `SignalWatcher.poll`
+    adds a filename to its consumed set BEFORE parsing it (signals.py), so
+    malformed JSON is skipped and never re-read — the session's Stop signal is
+    gone for good and the run waits out `session_timeout_min`. The buffered
+    `open()` this replaced looped internally; the raw fd needed for
+    O_NOFOLLOW/dir_fd does not, so loop here.
+    """
+    view = memoryview(data)
+    while view:
+        written = os.write(fd, view)
+        if written <= 0:  # not observed in practice; a spinning hook is worse
+            raise OSError("short write to the event file")
+        view = view[written:]
+
+
+def _write_event(events_dir, name, event):
+    """Write one event file into `events_dir`, refusing to follow a redirect.
+
+    The events dir is the orchestrator's control plane. A driven session has
+    write access to the project, so it could plant `<run_dir>/events` as a
+    symlink (or, on Windows, a junction) and redirect — or swallow — the
+    completion signal, stalling the run to `session_timeout_min` instead of
+    completing. `os.makedirs(exist_ok=True)` `isdir()`-checks THROUGH such a
+    link, so the refusal has to come before it. That refusal works on every
+    platform.
+
+    Where the platform has them, the create+replace is anchored to a dir_fd
+    opened O_NOFOLLOW: every later operation goes through that fd, so a swap
+    after the check cannot reach the write. Windows has neither
+    O_NOFOLLOW/O_DIRECTORY nor a handle-relative open (`os.supports_dir_fd` is
+    empty — dir_fd is implemented with the POSIX `*at` calls), so its fallback
+    re-resolves the path and the check-to-write window stays open there. It is
+    NARROWED, not closed: the redirect check runs again after the payload is
+    written and before it is published, so a swap still in place is refused and
+    the temp file removed. Two windows stay open on that path (#494), both
+    measured: a swap-and-restore around the create is undetectable from stdlib
+    Python, and a swap landing after the second check leaves the path-based
+    publish unable to find the temp file it wrote — it either raises or renames
+    a file the attacker planted inside the attacker's own directory. Neither
+    redirects the payload, and both end where a refusal ends: no event, so the
+    run waits out session_timeout_min. That is the same outcome an attacker gets
+    for free by leaving a redirect in place, which is refused without any race —
+    winning the race buys no capability, which is why the residual is accepted
+    rather than chased into ctypes/NtCreateFile inside a stdlib-only relay.
+
+    Mode is 0o600 (narrowed from the umask-derived mode an ordinary `open()`
+    produced): only the operator running the loop reads these.
+
+    Raises OSError on any refusal or failure; the caller degrades to a no-op.
+    """
+    if _is_link_like(events_dir):
+        raise OSError(f"refusing to write events into a redirected directory: {events_dir}")
+    os.makedirs(events_dir, exist_ok=True)
+    data = json.dumps(event).encode("utf-8")
+    tmp = name + ".tmp"
+    o_nofollow = getattr(os, "O_NOFOLLOW", 0)
+    o_directory = getattr(os, "O_DIRECTORY", 0)
+    # O_BINARY is a no-op flag on POSIX; on Windows it stops the fd from
+    # newline-translating what os.write() puts through it.
+    create = os.O_WRONLY | os.O_CREAT | os.O_EXCL | o_nofollow | getattr(os, "O_BINARY", 0)
+    # Probe os.rename, not os.replace: CPython omits os.replace from
+    # supports_dir_fd on Linux even though it accepts src_dir_fd/dst_dir_fd, so
+    # probing it would leave this whole branch dead everywhere. This branch is
+    # POSIX-only by construction, and there rename(2) IS the atomic-replace
+    # primitive os.replace wraps — probe the function actually called.
+    if o_nofollow and o_directory and {os.open, os.rename} <= os.supports_dir_fd:
+        dir_fd = os.open(events_dir, os.O_RDONLY | o_directory | o_nofollow)
+        try:
+            fd = os.open(tmp, create, 0o600, dir_fd=dir_fd)
+            try:
+                _write_all(fd, data)
+            finally:
+                os.close(fd)
+            os.rename(tmp, name, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+        finally:
+            os.close(dir_fd)
+        return
+    # Fallback (Windows): no dir_fd to anchor to, so the create below re-resolves
+    # events_dir by path. A swap into a junction between the check above and this
+    # create would have put the temp file inside the attacker's directory. Check
+    # again before publishing, so a swap that is still in place is refused rather
+    # than followed — the realistic shape, since a junction has to persist to
+    # capture the events the attacker is after.
+    tmp_path = os.path.join(events_dir, tmp)
+    fd = os.open(tmp_path, create, 0o600)
+    try:
+        _write_all(fd, data)
+    finally:
+        os.close(fd)
+    if _is_link_like(events_dir):
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise OSError(f"events directory was redirected mid-write: {events_dir}")
+    os.replace(tmp_path, os.path.join(events_dir, name))
+
+
+def main() -> int:
+    run_dir = os.environ.get("FROID_LOOP_RUN_DIR")
+    task_id = os.environ.get("FROID_LOOP_TASK_ID")
+    if not run_dir or not task_id:
+        return 0
+    event_name = sys.argv[1] if len(sys.argv) > 1 else "Unknown"
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        payload = {}
+    if not isinstance(payload, dict):
+        payload = {}
+
+    ts = time.time_ns()
+    event = {
+        "ts": ts,
+        "event": event_name,
+        "task_id": task_id,
+        # Payload keys vary by CLI: snake_case (claude/codex), conversation_id
+        # (cursor), or camelCase (copilot's sessionId/transcriptPath, agy's
+        # conversationId). Try each.
+        "session_id": (
+            payload.get("session_id")
+            or payload.get("conversation_id")
+            or payload.get("sessionId")
+            or payload.get("conversationId")
+        ),
+        "transcript_path": payload.get("transcript_path") or payload.get("transcriptPath"),
+        # agy sends no cwd — it sends workspacePaths, a list of workspace roots.
+        "cwd": payload.get("cwd") or _first_workspace(payload),
+    }
+    # The orchestrator's own events dir when it named one, else the legacy
+    # in-tree location this file's older selves are still installed at (see the
+    # module docstring). `or`, not a presence test: an exported-but-empty value
+    # names the launch cwd, which is not a control plane.
+    events_dir = os.environ.get("FROID_LOOP_EVENTS_DIR") or os.path.join(run_dir, "events")
+    try:
+        _write_event(events_dir, f"{ts}-{task_id}-{event_name}.json", event)
+    except OSError:
+        # A hostile or broken events dir must degrade to the orchestrator's
+        # normal session_timeout_min path, never surface as a hook failure that
+        # fails the CLI window (mirrors froid_loop_probe_hook.py's write wrap).
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

froid_loop/data/froid_loop_probe_hook.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Full-payload capture hook for `froid-loop probe-adapter --probe`. Stdlib only.
+
+A throwaway sibling of froid_loop_hook.py used ONLY during an opt-in live probe.
+It no-ops (exit 0) unless FROID_LOOP_PROBE_CAPTURE_DIR is set — a DISTINCT env var
+from the real relay's FROID_LOOP_RUN_DIR, so the capture hook and the signal relay
+can never fire in each other's context (a normal interactive session sees neither).
+
+For every event it writes two files atomically into the capture dir:
+
+  <ts>-<event>.signal.json   SignalWatcher-shaped {ts,event,task_id,session_id,
+                             transcript_path,cwd} so the probe's completion poll
+                             (a plain SignalWatcher over the capture dir) works
+                             with no change to the watcher.
+  <ts>-<event>.payload.json  the ENTIRE raw stdin payload plus an injected
+                             "argv_event" (the native event name from argv, for
+                             native->canonical pairing) so a maintainer can read
+                             the CLI's exact field names and casing. The probe
+                             command sanitizes this before it is ever shown;
+                             nothing written here is displayed raw.
+
+Tolerant of empty/garbage stdin and of write errors — it must never crash the
+CLI window it is hooked into.
+"""
+
+import json
+import os
+import sys
+import time
+
+
+def _first_workspace(payload):
+    paths = payload.get("workspacePaths")
+    if isinstance(paths, list) and paths and isinstance(paths[0], str):
+        return paths[0]
+    return None
+
+
+def _atomic_write(path: str, obj) -> None:
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(obj, f)
+    os.replace(tmp, path)
+
+
+def main() -> int:
+    capture_dir = os.environ.get("FROID_LOOP_PROBE_CAPTURE_DIR")
+    if not capture_dir:
+        return 0
+    task_id = os.environ.get("FROID_LOOP_TASK_ID", "probe")
+    event_name = sys.argv[1] if len(sys.argv) > 1 else "Unknown"
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        payload = {}
+    if not isinstance(payload, dict):
+        payload = {}
+
+    ts = time.time_ns()
+    try:
+        os.makedirs(capture_dir, exist_ok=True)
+        signal = {
+            "ts": ts,
+            "event": event_name,
+            "task_id": task_id,
+            # Casing varies by CLI, exactly as in froid_loop_hook.py: snake_case
+            # (claude/codex), conversation_id (cursor), camelCase (copilot,
+            # agy). agy sends workspacePaths rather than a cwd.
+            "session_id": (
+                payload.get("session_id")
+                or payload.get("conversation_id")
+                or payload.get("sessionId")
+                or payload.get("conversationId")
+            ),
+            "transcript_path": payload.get("transcript_path") or payload.get("transcriptPath"),
+            "cwd": payload.get("cwd") or _first_workspace(payload),
+        }
+        _atomic_write(os.path.join(capture_dir, f"{ts}-{event_name}.signal.json"), signal)
+        captured = dict(payload)
+        captured["argv_event"] = event_name
+        _atomic_write(os.path.join(capture_dir, f"{ts}-{event_name}.payload.json"), captured)
+    except OSError:
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

froid_loop/data/plugins/example/plugin.toml

@@ -0,0 +1,21 @@
+# A data-only example plugin: the smallest thing the plugin system can load.
+#
+# It declares metadata and one setting, but no [hooks] and no [python] — so it
+# carries zero executable behavior and is byte-identical to "no plugin" at run
+# time. It exists as the canonical reference for the manifest format and as the
+# fixture proving froid_loop/data/plugins/ ships in an installed wheel. A real
+# plugin authoring walkthrough builds on this shape in the docs phase.
+
+[plugin]
+name = "example"
+version = "1.0.0"
+api_version = 1
+description = "Data-only example plugin (settings only; no hooks, no code)."
+author = "froid-loop"
+
+[[settings]]
+key = "greeting"
+type = "str"
+default = "hello"
+label = "Greeting"
+help = "Demonstration setting; a data-only plugin is always active, so this renders in the settings UI."

froid_loop/data/plugins/tea/plugin.toml

@@ -0,0 +1,184 @@
+# Bundled Test Architect Enterprise (TEA) plugin for froid-loop.
+#
+# Wires the FROID "Test Architect Enterprise" module (the "Murat" agent + its
+# `froid-testarch-*` workflows) into every run and sweep as advisory-by-default
+# quality steps. It assumes TEA is already installed in the project
+# (`npx froid-plane install` -> Test Architect), and orchestrates by injecting
+# natural-language sessions that invoke the relevant TEA workflow at two
+# stages that have a live worktree:
+#
+#   post_dev_phase     test-design (TD) + atdd (AT) + automate (TA)   [role=dev]
+#   pre_commit_gate    trace (TR) + nfr (NR) + test-review (RV)       [role=review]
+#
+# The gate steps bind to pre_commit_gate — the injection point that fires
+# unconditionally just before every commit — NOT post_review_result, which fires
+# only when the orchestrator review loop runs (review.trigger="recommended"
+# skips it whenever the dev session doesn't recommend a follow-up). Gates
+# therefore evaluate the exact tree about to commit, and the `*_blocking` flags
+# enforce on every path.
+#
+# Because sweep bundles run the same inherited dev/review pipeline, these
+# workflows fire for runs AND sweep bundles with no sweep-specific code.
+#
+# Opt in from .froid-loop/policy.toml:
+#   [plugins]
+#   enabled = ["tea"]            # [python] readiness gate loads only when enabled
+#
+#   [plugins.tea]
+#   # every step is on + advisory by default; flip what you need:
+#   nfr_blocking = true          # escalate (don't commit) when the NFR gate fails
+#   atdd_enabled = false         # skip the ATDD generation step
+#
+# The per-step `<name>_enabled` / `<name>_blocking` settings use the generic
+# plugin-system workflow-overlay convention (see docs/plugin-authoring-guide.md,
+# "Making a workflow configurable"). Generation steps (td/atdd/automate) ship
+# advisory; the gate steps operators are likely to enforce (trace/nfr/review)
+# expose a `*_blocking` flag — when true, a FAIL/CONCERNS gate verdict escalates
+# the unit at commit time (enforcement: `TeaPlugin.on_pre_commit`).
+
+[plugin]
+name = "tea"
+version = "1.0.0"
+api_version = 1
+description = "Inject the FROID Test Architect Enterprise (TEA) workflows as advisory-by-default quality steps across runs and sweeps."
+author = "froid-loop"
+# TEA's runtime + its compiled per-CLI skills are gitignored / not guaranteed in
+# a fresh checkout, so prime them into an isolated per-worktree checkout. No-ops
+# under today's in-place (isolation = none) mode; needed once worktrees are used.
+seed_globs = [
+  "_froid/**",               # TEA runtime: config.yaml + testarch workflows + knowledge base
+  ".claude/skills/froid-t*", # compiled TEA skills for claude-code (froid-tea + froid-testarch-*)
+  ".agents/skills/froid-t*", # codex/cursor compiled skill home
+  ".gemini/skills/froid-t*", # gemini compiled skill home
+  ".agent/skills/froid-t*",  # generic agent compiled skill home
+]
+
+# In-process module. Trust-gated: never imported unless "tea" is in
+# [plugins] enabled. Owns the readiness gate (validate) and the blocking-gate
+# enforcement at pre_commit (on_pre_commit).
+[python]
+module = "tea_plugin.py"
+class = "TeaPlugin"
+
+# ----------------------------------------------------------------- settings
+
+# Readiness gate. With this on (default), a run fails fast at startup if TEA is
+# not installed in the project; turn it off to let the workflows degrade to
+# advisory prompts even when TEA is absent.
+[[settings]]
+key = "require_tea"
+type = "bool"
+default = true
+label = "Require TEA installed"
+help = "Fail fast at startup if the project has no _froid/tea/config.yaml (TEA not installed). false = run anyway."
+
+# Per-step enable flags (workflow-overlay convention: <name>_enabled). Every
+# step ships on; set one false to drop just that workflow.
+[[settings]]
+key = "td_enabled"
+type = "bool"
+default = true
+label = "Enable test-design (TD)"
+help = "post_dev_phase: risk assessment + coverage strategy for the changes (froid-testarch-test-design)."
+
+[[settings]]
+key = "atdd_enabled"
+type = "bool"
+default = true
+label = "Enable ATDD (AT)"
+help = "post_dev_phase: failing acceptance tests + implementation checklist (froid-testarch-atdd)."
+
+[[settings]]
+key = "automate_enabled"
+type = "bool"
+default = true
+label = "Enable automate (TA)"
+help = "post_dev_phase: prioritized API/E2E tests, fixtures, DoD summary (froid-testarch-automate)."
+
+[[settings]]
+key = "trace_enabled"
+type = "bool"
+default = true
+label = "Enable trace (TR)"
+help = "pre_commit_gate: map requirements to tests + record the quality-gate decision (froid-testarch-trace)."
+
+[[settings]]
+key = "nfr_enabled"
+type = "bool"
+default = true
+label = "Enable NFR (NR)"
+help = "pre_commit_gate: assess non-functional requirements + record the gate decision (froid-testarch-nfr)."
+
+[[settings]]
+key = "review_enabled"
+type = "bool"
+default = true
+label = "Enable test-review (RV)"
+help = "pre_commit_gate: quality check against the written tests (froid-testarch-test-review)."
+
+# Per-gate blocking flags (workflow-overlay convention: <name>_blocking). The
+# gate steps ship advisory; flip one true so a FAIL/CONCERNS verdict escalates
+# the unit at commit instead of landing (enforcement: TeaPlugin.on_pre_commit).
+# Generation steps stay advisory by design, so they expose no flag.
+[[settings]]
+key = "trace_blocking"
+type = "bool"
+default = false
+label = "Block on trace gate"
+help = "true = a failing trace (requirements-traceability) gate escalates the unit at commit instead of committing."
+
+[[settings]]
+key = "nfr_blocking"
+type = "bool"
+default = false
+label = "Block on NFR gate"
+help = "true = a failing NFR gate escalates the unit at commit instead of committing."
+
+[[settings]]
+key = "review_blocking"
+type = "bool"
+default = false
+label = "Block on test-review gate"
+help = "true = a failing test-review gate escalates the unit at commit instead of committing."
+
+# ---------------------------------------------------------------- workflows
+
+# Prompts are CLI-agnostic: a natural-language intent plus the explicit TEA
+# workflow/skill name, phrased around the changes in the working tree for
+# {story_key} so they work for a single story AND a sweep bundle.
+
+[workflows.td]
+stage = "post_dev_phase"
+role = "dev"
+prompt = "Run the TEA Test Design workflow (skill `froid-testarch-test-design`) for `{story_key}`. Produce a risk assessment and a risk-based coverage strategy for the changes currently in the working tree, and write the artifacts under TEA's configured test_artifacts directory. Do not modify production code."
+blocking = false
+
+[workflows.atdd]
+stage = "post_dev_phase"
+role = "dev"
+prompt = "Run the TEA ATDD workflow (skill `froid-testarch-atdd`) for `{story_key}`. Generate failing acceptance tests plus an implementation checklist covering the changes currently in the working tree, written under TEA's configured test_artifacts directory."
+blocking = false
+
+[workflows.automate]
+stage = "post_dev_phase"
+role = "dev"
+prompt = "Run the TEA Test Automation workflow (skill `froid-testarch-automate`) for `{story_key}`. Generate prioritized API/E2E tests and fixtures for the changes currently in the working tree, plus a Definition-of-Done summary, under TEA's configured test_artifacts directory."
+blocking = false
+
+[workflows.trace]
+stage = "pre_commit_gate"
+role = "review"
+prompt = "Run the TEA Trace Requirements workflow (skill `froid-testarch-trace`) for `{story_key}`. Map the requirements to the tests covering the changes currently in the working tree and record the quality-gate decision under TEA's configured test_artifacts directory."
+blocking = false
+
+[workflows.nfr]
+stage = "pre_commit_gate"
+role = "review"
+prompt = "Run the TEA Non-Functional Requirements workflow (skill `froid-testarch-nfr`) for `{story_key}`. Assess the NFRs of the changes currently in the working tree and record the gate decision under TEA's configured test_artifacts directory."
+blocking = false
+
+[workflows.review]
+stage = "pre_commit_gate"
+role = "review"
+prompt = "Run the TEA Test Review workflow (skill `froid-testarch-test-review`) for `{story_key}`. Perform a quality check against the tests covering the changes currently in the working tree, using TEA's knowledge base and best practices, and record findings under TEA's configured test_artifacts directory."
+blocking = false