froid-loop 0.11.1__py3-none-any.whl

froid_loop/data/plugins/unity/unity_teardown.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""per_worktree teardown for the froid-loop Unity engine plugin.
+
+Runs once per unit when the worktree is finished — on success, on a deferral, and
+on a pause/escalation — so the unit's managed Unity Editor never outlives its
+worktree. Best effort: the engine logs a non-zero exit but the unit's outcome
+stands (it does not re-defer a done/paused unit just because Editor-quit failed).
+
+  1. Gracefully quit the worktree's Editor (`unity-mcp-cli close`, then --force).
+  2. Fallback hard-kill: if an Editor *or its MCP server* whose argv references this
+     worktree is still alive afterwards, SIGTERM→SIGKILL it (Linux). ``close``
+     reports success even when it can't find the Editor — which happens precisely
+     when readiness failed and the Editor never registered with the MCP — so without
+     this a failed unit would leak a live Editor. The Unity plugin also spawns a
+     child ``gamedev-mcp-server`` (the local MCP HTTP server) that ``close`` does
+     NOT reap; a leaked server holds its port and poisons later runs (the plugin
+     declines to start a fresh server when a stale one lingers in the name-keyed
+     Library cache), so we sweep it up here too.
+  3. Reap this unit's detect-only dialog probe (``unity_dialog_probe.py``, launched
+     per-worktree at setup): terminate it via its pid-file handle, with a ``/proc``
+     argv-scan backstop (matched on the worktree path + the probe script name, since
+     its exe basename is ``python``). Best effort — a probe we cannot reap self-exits
+     when the engine pid dies, so it never fails the unit.
+  4. Drop the ``<worktree>/Library`` if setup left a *symlink* (the empty-cache
+     fallback), leaving the persistent cache it pointed at intact for the next run.
+     A real Library — the common case now that setup *primes* a warm reflink/CoW copy
+     in — is left untouched; it is removed cheaply when froid-loop deletes the worktree
+     (CoW-shared extents cost almost nothing to drop).
+
+Verified against unity-mcp-cli v0.81.1 (`close <path>` keys off the project path).
+Only the IvanMurzak MCP launches a managed per-worktree Editor, so only it is quit
+here; for CoplayDev (shared :8080 server) override engine.worktree_teardown_cmd.
+
+Env (injected by the engine):
+  FROID_LOOP_WORKTREE     the worktree whose Editor to quit
+  FROID_LOOP_RUN_DIR      run dir holding the dialog-probe pid-file handle
+  FROID_LOOP_ENGINE_MCP   ivanmurzak | coplaydev               (default ivanmurzak)
+  UNITY_MCP_CLI          IvanMurzak CLI binary                (default unity-mcp-cli)
+  FROID_LOOP_UNITY_CLOSE_TIMEOUT  polite-quit seconds before --force (default 30)
+
+Exit 0 = Editor quit + symlink dropped; non-zero = something failed (logged).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from froid_loop.process_host import get_process_host
+
+
+def _psutil():
+    """Lazily import psutil — a core dep on Windows, the ``non-linux`` extra on
+    macOS — used only for non-Linux process discovery (macOS and Windows). The
+    dep-free core never imports it; raise a clear, actionable error if it's missing
+    on a platform that needs it."""
+    try:
+        import psutil  # intentional lazy import — keeps the core dep-free
+    except ImportError as exc:  # pragma: no cover - exercised only off Linux
+        raise RuntimeError(
+            f"unity_teardown: process discovery on {sys.platform!r} needs psutil; "
+            "on Windows reinstall froid-loop (psutil is a required dependency there), "
+            "on macOS run `pip install 'froid-loop[non-linux]'`"
+        ) from exc
+    return psutil
+
+
+def _worktree() -> Path | None:
+    wt = os.environ.get("FROID_LOOP_WORKTREE")
+    return Path(wt) if wt else None
+
+
+def _run_dir() -> Path | None:
+    rd = os.environ.get("FROID_LOOP_RUN_DIR")
+    return Path(rd) if rd else None
+
+
+# Process basenames we reap when bound to the worktree path: the Unity Editor
+# binary and the local MCP HTTP server the plugin spawns as a child.
+_TARGET_BASENAMES = ("unity", "gamedev-mcp-server")
+
+# The detect-only dialog probe's pid-file handle + script basename. The probe's exe
+# basename is `python`, so it is INVISIBLE to the _TARGET_BASENAMES editor sweep (we
+# deliberately do not loosen those — a loosened editor match could kill the wrong
+# python); it gets its own argv-based matcher below.
+_DIALOG_PROBE_PID_FILE = "unity-dialog-probe.pid"
+_DIALOG_PROBE_SCRIPT_BASENAME = "unity_dialog_probe.py"
+
+
+def _exe_basename(entry: Path) -> str:
+    try:
+        return os.path.basename(os.readlink(entry / "exe")).lower()
+    except OSError:
+        return ""
+
+
+def _lingering_pids(worktree: Path) -> list[int]:
+    """PIDs of the Unity *Editor* or its *MCP server* bound to this worktree.
+
+    Tight on purpose: the process must (a) reference this exact worktree path in
+    argv — Unity gets ``-projectPath <path>`` and the server's binary lives under
+    ``<worktree>/Library/mcp-server/`` — and (b) have an executable basename of
+    exactly ``unity`` (the Editor) or ``gamedev-mcp-server`` (the MCP server). That
+    excludes the launcher shell, ``unity-mcp-cli``/node, python, greps, and the
+    operator's Editor/server on any other project, so we never kill the wrong one.
+
+    Linux uses the zero-dependency ``/proc`` fast path; other platforms (no /proc)
+    fall back to the same scan over psutil (the optional ``non-linux`` extra)."""
+    if sys.platform.startswith("linux"):
+        return _lingering_pids_proc(worktree)
+    return _lingering_pids_psutil(worktree)
+
+
+def _lingering_pids_proc(worktree: Path) -> list[int]:
+    """Linux fast path: scan ``/proc`` for the worktree-bound Editor/server."""
+    needle = str(worktree)
+    pids: list[int] = []
+    for entry in Path("/proc").iterdir():  # portability: Linux-only /proc scan, guarded above
+        if not entry.name.isdigit():
+            continue
+        try:
+            argv = (
+                (entry / "cmdline").read_bytes().replace(b"\x00", b" ").decode("utf-8", "replace")
+            )
+        except OSError:
+            continue  # process gone or unreadable
+        if needle not in argv:
+            continue
+        argv0 = os.path.basename(argv.split(" ", 1)[0]).lower() if argv.strip() else ""
+        if _exe_basename(entry) in _TARGET_BASENAMES or argv0 in _TARGET_BASENAMES:
+            pids.append(int(entry.name))
+    return pids
+
+
+def _lingering_pids_psutil(worktree: Path) -> list[int]:
+    """Non-Linux equivalent of the ``/proc`` scan via psutil (no /proc available).
+    Same tight match — argv references this worktree AND the process basename is a
+    target — with the basename's extension stripped so Windows' ``Unity.exe`` /
+    ``gamedev-mcp-server.exe`` match ``_TARGET_BASENAMES``. Not exercised on Linux."""
+    psutil = _psutil()
+    needle = str(worktree)
+    pids: list[int] = []
+    for proc in psutil.process_iter(["pid", "name", "exe", "cmdline"]):
+        try:
+            cmdline = proc.info.get("cmdline") or []
+            if needle not in " ".join(cmdline):
+                continue
+            exe = proc.info.get("exe") or ""
+            name = proc.info.get("name") or ""
+            argv0 = os.path.basename(cmdline[0]).lower() if cmdline else ""
+            exe_base = os.path.splitext(os.path.basename(exe))[0].lower() if exe else ""
+            name_base = os.path.splitext(name)[0].lower()
+            if (
+                exe_base in _TARGET_BASENAMES
+                or argv0 in _TARGET_BASENAMES
+                or name_base in _TARGET_BASENAMES
+            ):
+                pids.append(int(proc.info["pid"]))
+        except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+            continue  # process vanished or unreadable mid-scan
+    return pids
+
+
+def _terminate_identity_guarded(pids: list[int]) -> None:
+    """SIGTERM → grace → identity-checked SIGKILL a confirmed pid list. Snapshots
+    each pid's identity *before* signalling so the force-kill escalation can never
+    land on a pid the kernel recycled to an unrelated process (mirrors runs.stop_run's
+    guard; force_kill's own contract requires confirmed identity). Shared by the
+    Editor/MCP sweep and the dialog-probe reap."""
+    host = get_process_host()
+    ident = {pid: host.identity(pid) for pid in pids}
+    for pid in pids:
+        try:
+            host.terminate(pid)
+        except OSError:
+            pass
+    # give them a few seconds to exit politely, then hard-kill survivors
+    for _ in range(20):
+        if not any(host.is_alive(p) for p in pids):
+            break
+        time.sleep(0.5)
+    for pid in pids:
+        if not host.is_alive(pid):
+            continue
+        if ident[pid] is None or host.identity(pid) != ident[pid]:
+            print(
+                f"unity_teardown: pid {pid} survived terminate but its identity is "
+                "missing or changed since teardown began; skipping force-kill to "
+                "avoid hitting a reused pid",
+                file=sys.stderr,
+            )
+            continue
+        try:
+            host.force_kill(pid)
+        except OSError:
+            pass
+
+
+def _force_kill_lingering(worktree: Path) -> int:
+    """Best-effort SIGTERM→SIGKILL of any Editor or MCP server left running for this
+    worktree after ``close``. Returns the number of processes targeted."""
+    pids = _lingering_pids(worktree)
+    # exclude ourselves just in case (our own argv has the worktree path too)
+    pids = [p for p in pids if p != os.getpid()]
+    if not pids:
+        return 0
+    print(
+        f"unity_teardown: 'close' left {len(pids)} Unity process(es) for {worktree} "
+        f"running ({pids}); hard-killing",
+        file=sys.stderr,
+    )
+    _terminate_identity_guarded(pids)
+    return len(pids)
+
+
+def _probe_argv_matches(argv: str, worktree: Path) -> bool:
+    """True when ``argv`` is THIS worktree's detached dialog probe: it references both
+    the worktree path and the probe script basename. Scoped to the worktree so we
+    never touch another unit's probe, and keyed on the script name because the exe
+    basename is ``python`` (not a target editor binary)."""
+    return _DIALOG_PROBE_SCRIPT_BASENAME in argv and str(worktree) in argv
+
+
+def _lingering_probe_pids(worktree: Path) -> list[int]:
+    """``/proc`` scan for the worktree's detached dialog probe (python argv match).
+    Backstop for the pid-file reap handle. Linux-only — the probe is X11/Linux-only,
+    and off-Linux the pid file is the sole handle (returns [] here)."""
+    if not sys.platform.startswith("linux"):
+        return []
+    pids: list[int] = []
+    for entry in Path("/proc").iterdir():  # portability: Linux-only /proc scan, guarded above
+        if not entry.name.isdigit():
+            continue
+        try:
+            argv = (
+                (entry / "cmdline").read_bytes().replace(b"\x00", b" ").decode("utf-8", "replace")
+            )
+        except OSError:
+            continue  # process gone or unreadable
+        if _probe_argv_matches(argv, worktree):
+            pids.append(int(entry.name))
+    return pids
+
+
+def _probe_pidfile_pids(run_dir: Path | None) -> list[int]:
+    """The dialog probe recorded in ``<run_dir>/unity-dialog-probe.pid``, iff it is
+    still alive AND still our probe (identity-checked). The primary reap handle."""
+    if run_dir is None:
+        return []
+    from froid_loop.runs import read_named_pid_identity  # lazy import
+
+    pid, identity = read_named_pid_identity(run_dir / _DIALOG_PROBE_PID_FILE)
+    if pid is None:
+        return []
+    return [pid] if get_process_host().alive_and_ours(pid, identity) else []
+
+
+def _reap_dialog_probe(worktree: Path, run_dir: Path | None) -> int:
+    """Terminate this unit's detect-only dialog probe. Primary handle is the pid file
+    (``<run_dir>/unity-dialog-probe.pid``); the ``/proc`` argv scan is a backstop for a
+    probe whose pid file is missing/stale. Identity-guarded escalation, same as the
+    Editor sweep. Best effort — never changes the unit outcome (a survivor self-exits
+    when the engine pid dies). Returns the count targeted."""
+    pids = set(_probe_pidfile_pids(run_dir)) | set(_lingering_probe_pids(worktree))
+    pids.discard(os.getpid())
+    if not pids:
+        return 0
+    print(
+        f"unity_teardown: reaping {len(pids)} dialog-probe process(es) {sorted(pids)}",
+        file=sys.stderr,
+    )
+    _terminate_identity_guarded(sorted(pids))
+    if run_dir is not None:
+        try:
+            (run_dir / _DIALOG_PROBE_PID_FILE).unlink()
+        except OSError:
+            pass
+    return len(pids)
+
+
+def _cli() -> str:
+    return os.environ.get("UNITY_MCP_CLI", "unity-mcp-cli")
+
+
+def _drop_library_symlink(worktree: Path) -> None:
+    link = worktree / "Library"
+    if link.is_symlink():
+        try:
+            link.unlink()
+            print("unity_teardown: dropped Library symlink", file=sys.stderr)
+        except OSError as exc:  # best effort
+            print(f"unity_teardown: could not drop Library symlink: {exc}", file=sys.stderr)
+
+
+def _close_ivanmurzak(worktree: Path) -> int:
+    cli = _cli()
+    if shutil.which(cli) is None:
+        # nothing to quit against; not fatal — just drop the symlink below.
+        print(f"unity_teardown: {cli!r} not on PATH; skipping Editor quit", file=sys.stderr)
+        return 0
+    timeout = os.environ.get("FROID_LOOP_UNITY_CLOSE_TIMEOUT", "30")
+    proc = subprocess.run(
+        [cli, "close", str(worktree), "--timeout", timeout, "--force"],
+        capture_output=True,
+        text=True,
+    )
+    if proc.returncode != 0:
+        sys.stderr.write(proc.stdout + proc.stderr)
+        print(f"unity_teardown: 'close' exited {proc.returncode}", file=sys.stderr)
+    return proc.returncode
+
+
+def main() -> int:
+    worktree = _worktree()
+    if worktree is None:
+        print("unity_teardown: FROID_LOOP_WORKTREE is not set", file=sys.stderr)
+        return 2
+    mcp = (os.environ.get("FROID_LOOP_ENGINE_MCP") or "ivanmurzak").strip().lower()
+    rc = 0
+    if mcp == "ivanmurzak":
+        rc = _close_ivanmurzak(worktree)
+    elif mcp == "coplaydev":
+        print(
+            "unity_teardown: CoplayDev per_worktree teardown is not wired; override "
+            "engine.worktree_teardown_cmd if you launched a managed Editor for it.",
+            file=sys.stderr,
+        )
+    else:
+        print(
+            f"unity_teardown: unknown FROID_LOOP_ENGINE_MCP={mcp!r} (expected ivanmurzak|coplaydev)",
+            file=sys.stderr,
+        )
+        rc = 2
+    # close reports success even when it can't find the Editor (e.g. readiness
+    # failed so it never registered) and never reaps the plugin's child MCP server
+    # — sweep up any Editor or gamedev-mcp-server still bound to this worktree so a
+    # failed unit never leaks a live process (a leaked server poisons later runs).
+    # Only a SURVIVING process (couldn't be killed) is a teardown failure; a leak we
+    # successfully reaped is still a clean teardown.
+    if _force_kill_lingering(worktree):
+        survivors = _lingering_pids(worktree)
+        if survivors:
+            print(
+                f"unity_teardown: {len(survivors)} Editor/server process(es) survived kill: "
+                f"{survivors}",
+                file=sys.stderr,
+            )
+            rc = rc or 1
+    # Reap this unit's detect-only dialog probe (pid-file handle + argv backstop).
+    # Best effort — a probe we cannot reap self-exits when the engine pid dies, so it
+    # never fails the unit (unlike a surviving Editor/server, which poisons later runs).
+    _reap_dialog_probe(worktree, _run_dir())
+    _drop_library_symlink(worktree)
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

froid_loop/data/profiles/antigravity.toml

@@ -0,0 +1,52 @@
+# Google Antigravity CLI (`agy`). `-i` runs the slash command as the initial prompt
+# and stays interactive (a bare `-p` would run headless and exit). `Stop` is agy's
+# turn-complete event, mapped to canonical Stop — agy fires no SessionStart/SessionEnd
+# hooks, so only Stop is registered. Skills live in .agents/skills/, hooks in
+# .agents/hooks.json. Verified against agy 1.1.3.
+#
+# usage_parser is "none" DELIBERATELY AND PERMANENTLY — not a deferral. agy's
+# transcript (~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/
+# logs/transcript_full.jsonl, the path its Stop hook reports as `transcriptPath`)
+# carries only step_index/source/type/status/created_at/content/thinking. There is
+# no usage block anywhere in it — verified by capturing a live turn and scanning
+# every key recursively. agy does count tokens (the TUI shows them), but only
+# inside conversations/<conversationId>.db, a SQLite store whose gen_metadata is
+# an undocumented protobuf blob — unreadable through the JSONL-shaped
+# `(transcript_path) -> TokenUsage` parser contract, and fragile against an
+# internal schema. Runs work; the token columns stay empty. Revisit only if agy
+# starts emitting usage in the transcript.
+#
+# Hook payloads are protojson: keys are camelCase (conversationId, transcriptPath,
+# workspacePaths) — NOT the snake_case claude/codex use. agy sends no `cwd`; the
+# relay reads workspacePaths[0] instead. Hook `timeout` is in SECONDS (default 30);
+# handlers for Stop are a FLAT list with no matcher wrapper, and the file is keyed
+# by hook-GROUP name at the top level with no "hooks" wrapper (see install.py).
+# A hook's cwd is the dir holding hooks.json (.agents/), not the project root —
+# the relay is registered by absolute path, so this never matters.
+#
+# TRUST (verified empirically against 1.1.3, 3-run matrix): agy gates every
+# workspace on settings.json `trustedWorkspaces` and blocks on an interactive
+# "Do you trust the contents of this project?" dialog until answered.
+# `--dangerously-skip-permissions` does NOT bypass it — that flag covers tool
+# permissions only. Matching is EXACT-PATH: trusting /tmp does not cover
+# /tmp/foo. Consequences: `isolation = "none"` (the default) works once the
+# project root is trusted; `isolation = "worktree"` does NOT — each worktree is
+# a fresh path under .froid-loop/runs/, so every session would hang on the dialog.
+name = "antigravity"
+binary = "agy"
+prompt_template = "{prompt}"
+launch_args = ["-i"]
+bypass_args = ["--dangerously-skip-permissions"]
+model_flag = "--model"
+usage_parser = "none"
+first_run_note = "run `agy` once in the project and authenticate + answer 'Yes, I trust this folder' before `froid-loop run` — spawned sessions can't answer first-run dialogs, and a pending one reads as a session timeout. Requires Antigravity CLI (agy >= 1.1.3). Trust is exact-path (settings.json trustedWorkspaces): trusting a parent does NOT cover subdirectories, and --dangerously-skip-permissions does not bypass it — so antigravity requires isolation = \"none\" (the default); isolation = \"worktree\" will hang, as each worktree is an untrusted path."
+skill_tree = ".agents/skills"
+# .agents/hooks.json is agy's lifecycle-hook config. Seeded first, then the Stop
+# relay is merged in, so a worktree checkout keeps any user/plugin hook groups
+# already present instead of starting from an empty file.
+seed_files = [".agents/hooks.json"]
+
+[hooks]
+dialect = "antigravity-hooks-json"
+config_path = ".agents/hooks.json"
+events = { Stop = "Stop" }

froid_loop/data/profiles/claude.toml

@@ -0,0 +1,85 @@
+# Claude Code. Reference profile for the claude-settings-json hook dialect.
+name = "claude"
+binary = "claude"
+prompt_template = "{prompt}"
+bypass_args = ["--permission-mode", "bypassPermissions"]
+model_flag = "--model"
+usage_parser = "claude-jsonl"
+first_run_note = "run `claude` once in the project to accept workspace trust and hooks approval"
+skill_tree = ".claude/skills"
+# Gitignored configs a worktree checkout omits: project MCP servers (.mcp.json)
+# and Claude settings. .claude/settings.json is also the hook config_path — it is
+# seeded first, then the Stop hook is merged into it (see provision_worktree).
+seed_files = [
+  ".mcp.json",
+  ".claude/settings.json",
+  ".claude/settings.local.json",
+]
+
+# Transport-failure classification (#194, #507, #323): regexes matched
+# line-by-line against the ANSI-stripped 64 KiB tail of a non-completed
+# (timeout/stalled/crashed) session's pane log, once the verdict has settled. A
+# match reclassifies the session as an environment fault so the orchestrator can
+# PAUSE (and re-arm with a fresh budget) instead of charging a dev attempt for a
+# session that never got usable work out of the API.
+#
+# The scanned file is a tmux pane capture, so it carries THE MODEL'S OWN OUTPUT:
+# an assertion, an acceptance criterion or a doc bullet that merely writes ABOUT
+# a provider error lands in the scanned bytes. So every alternative below
+# reproduces one COMPLETE Claude Code error sentence rather than a framing token
+# plus a loose cause — a paraphrase cannot reach it. Every one is a captured line:
+#   * `API Error` … `Unable to connect to API` — #194's evidence, run
+#     20260718-191419-44e7 on this adapter.
+#   * `API Error` … `Connection closed mid-response`, and the 5xx pair
+#     (`529 Overloaded` / `500 Internal server error`) — Claude Code transcript
+#     entries structurally tagged "isApiErrorMessage": true.
+#
+# The 5xx statuses are ENUMERATED, not ranged. A `5[0-9][0-9]` range admits 100
+# codes against either reason phrase when exactly two pairings were ever
+# captured, so an unverified string — `API Error` … `503 Internal server error`,
+# which is what a story writing an HTTP error path prints — would pause the run.
+# Same evidentiary bar as the quota note below: seed the captured pairing, never
+# the plausible one.
+#
+# The single-character classes (`t[o]`, `respons[e]`, `5[2]9`, `5[0]0`) are
+# load-bearing, not typos: each makes its pattern fail to match its OWN line
+# here, so a session that prints or diffs this profile does not read its own
+# configuration as a provider outage (#507). Pinned by
+# test_shipped_patterns_do_not_match_their_own_profile_line.
+#
+# No usage-limit / quota cause is seeded: no captured Claude Code quota line
+# exists, and on a pane capture that vocabulary is what a story IMPLEMENTING
+# rate limiting prints all day. Seed one only from a captured line, citing the
+# run it came from — the bar test_unseeded_profiles_stay_inert states.
+#
+# To disable or extend, copy this profile into .froid-loop/profiles/ and edit.
+env_fault_patterns = [
+  "API Error: Unable to connect t[o] API",
+  "API Error: Connection closed mid-respons[e]",
+  "API Error: (5[2]9 Overloaded|5[0]0 Internal server error)",
+]
+
+# Force Claude Code's classic (inline/scrollback) renderer. The fullscreen TUI
+# (research preview, alt-screen ?1049h like vim/htop) repaints in place, so the
+# tmux pane capture only ever holds the final frame and the Log tab shows a single
+# page. The classic renderer keeps output in native scrollback, so the capture
+# scrolls normally and the Log tab reconstructs the whole session. This env var
+# overrides any `tui` setting (user/project/local/seeded) per Claude Code docs.
+#
+# Disable background tasks (issue #109): Claude Code can bias a session toward
+# backgrounding Agent/bash work (run_in_background) despite the froid-dev-auto
+# prompt ban on it. A session that ends its turn to await a background sub-agent
+# yields a result-less Stop — and if the CLI then exits, the in-process sub-agent
+# is stranded mid-implementation with the story stuck in-progress. The var forces
+# every subagent and bash call to run synchronously, which is the behavior the
+# skill contract already requires; froid-loop has no background-completion
+# re-invocation, so nothing sanctioned is lost. To opt out, copy this profile
+# into .froid-loop/profiles/ and drop the var.
+[env]
+CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN = "1"
+CLAUDE_CODE_DISABLE_BACKGROUND_TASKS = "1"
+
+[hooks]
+dialect = "claude-settings-json"
+config_path = ".claude/settings.json"
+events = { SessionStart = "SessionStart", Stop = "Stop", SessionEnd = "SessionEnd", PreCompact = "PreCompact" }

froid_loop/data/profiles/codex.toml

@@ -0,0 +1,22 @@
+# OpenAI Codex CLI (>= 0.139). Slash commands are NOT expanded when passed as
+# the initial prompt argument; the $skill-name mention syntax attaches the
+# skill instead (skills live in .agents/skills/) — live-verified 2026-06-11.
+# "use subagents as needed" is required or Codex runs the skill's parallel
+# phases (e.g. review layers) without spawning subagents. Codex has no
+# SessionEnd hook event — the adapter's window-death fallback covers crashes.
+name = "codex"
+binary = "codex"
+prompt_template = "Use the ${skill} skill now, and use subagents as needed: {args}"
+bypass_args = ["--dangerously-bypass-approvals-and-sandbox"]
+model_flag = "--model"
+usage_parser = "codex-rollout"
+first_run_note = "run `codex` once in the project and accept BOTH prompts: workspace trust, then 'Hooks need review' -> 'Trust all and continue' (untrusted hooks silently never fire); requires Codex >= 0.139"
+skill_tree = ".agents/skills"
+# Project-scoped Codex config (MCP servers under [mcp_servers]) — gitignored, so
+# a worktree checkout omits it and isolated sessions lose their MCP servers.
+seed_files = [".codex/config.toml"]
+
+[hooks]
+dialect = "codex-hooks-json"
+config_path = ".codex/hooks.json"
+events = { SessionStart = "SessionStart", Stop = "Stop" }

froid_loop/data/profiles/copilot.toml

@@ -0,0 +1,52 @@
+# GitHub Copilot CLI (GA since 2026-02). `-i "<prompt>"` starts an interactive
+# session and auto-runs the prompt (a bare `-p` prompt runs headless and exits).
+# Copilot has no native skill discovery, so the prompt tells it to read the
+# SKILL.md directly (skills live in .agents/skills/, shared with codex/gemini and
+# matching upstream Froid Plane's github-copilot installer). "use subagents as
+# needed" keeps parallel skill phases (e.g. review layers) actually spawning
+# subagents, same as codex.
+#
+# Hook events (verified against Copilot CLI 1.0.63 via `froid-loop probe-adapter
+# copilot --probe`): the turn-end event is `agentStop` — PascalCase `Stop` does
+# NOT fire on this build, so it must NOT be registered (it yields no completion
+# signal and every session reads as a timeout). `sessionStart`/`sessionEnd` cover
+# session lifecycle; Copilot has no PreCompact equivalent. Payload keys are
+# camelCase (sessionId, transcriptPath, cwd) regardless of event-name casing, and
+# the `agentStop` payload carries `transcriptPath` + `stopReason: end_turn` — the
+# shared relay reads both camelCase and snake_case, so the usage_parser gets the
+# transcript. CAVEAT: single build/OS (1.0.63, macOS); a future build may alias
+# `Stop`. NOTE: an enterprise policy permissions.disableBypassPermissionsMode =
+# 'disable' suppresses the --allow-all-* flags and will block unattended runs.
+name = "copilot"
+binary = "copilot"
+prompt_template = "LOAD the FULL .agents/skills/{skill}/SKILL.md, read its entire contents and follow its directions exactly, using subagents as needed: {args}"
+launch_args = ["-i"]
+bypass_args = ["--allow-all-tools", "--allow-all-paths"]
+model_flag = "--model"
+usage_parser = "copilot-events"
+# Copilot writes its token totals (modelMetrics) only in the trailing
+# `session.shutdown` events.jsonl line, ~1s AFTER the agentStop hook fires — so
+# read usage on a short grace poll, not the instant the turn ends, or it samples
+# the transcript before the totals land (reads as 0/None).
+usage_grace_s = 8.0
+# agentStop fires PER response turn, so a parallel-subagent review (e.g. the
+# froid-dev-auto step-04 hunter layers) ends several turns; the global default of
+# 1 nudge would declare it stalled on the 2nd Stop. 5 lets a multi-turn review finish.
+stop_without_result_nudges = 5
+# agentStop also fires for each SUBAGENT turn — with an empty transcriptPath and a
+# tool-use session id (toolu_…), not the main session's id. Those are not the main
+# turn-end: ignore a Stop with no transcript so a subagent's premature Stop is not
+# read as a (result-less) completion. Without this the dev stage (0 nudges) stalls
+# outright on the first subagent Stop, before froid-dev-auto writes its terminal spec.
+subagent_stop_without_transcript = true
+first_run_note = "run `copilot` once and authenticate (gh / Copilot subscription); requires Copilot CLI GA (>= 2026-02)"
+skill_tree = ".agents/skills"
+# .github/copilot/settings.json is the inline hook config (and can also hold MCP
+# servers) — gitignored in many projects, so a worktree checkout omits it and
+# isolated sessions lose it; seeded first, then the agentStop hook is merged in.
+seed_files = [".github/copilot/settings.json"]
+
+[hooks]
+dialect = "copilot-settings-json"
+config_path = ".github/copilot/settings.json"
+events = { agentStop = "Stop", sessionStart = "SessionStart", sessionEnd = "SessionEnd" }

froid_loop/data/profiles/gemini.toml

@@ -0,0 +1,26 @@
+# Google Gemini CLI (>= 0.46, hooks on by default). -i keeps the session
+# interactive with the slash command as the initial prompt (a positional
+# prompt would force headless mode). AfterAgent is the turn-complete event,
+# mapped to canonical Stop. Custom commands live in .gemini/commands/, skills
+# in .agents/skills/.
+name = "gemini"
+binary = "gemini"
+prompt_template = "{prompt}"
+launch_args = ["-i"]
+bypass_args = ["--approval-mode=yolo"]
+model_flag = "--model"
+usage_parser = "gemini-chat"
+first_run_note = "authenticate once (browser OAuth or GEMINI_API_KEY); requires Gemini CLI >= 0.46"
+skill_tree = ".agents/skills"
+# .gemini/settings.json holds project MCP servers (mcpServers) AND is the hook
+# config_path: it is seeded first, then the Stop hook is merged in, so a worktree
+# keeps the project's MCP servers instead of starting from an empty settings file.
+seed_files = [".gemini/settings.json"]
+
+[env]
+GEMINI_CLI_TRUST_WORKSPACE = "true"
+
+[hooks]
+dialect = "gemini-settings-json"
+config_path = ".gemini/settings.json"
+events = { SessionStart = "SessionStart", AfterAgent = "Stop", SessionEnd = "SessionEnd" }

froid_loop/data/profiles/opencode.toml

@@ -0,0 +1,54 @@
+# OpenCode (opencode.ai) driven over its local HTTP server (`opencode serve`) —
+# hookless: the adapter owns the server process and observes turn completion via
+# SSE + polling, so no hook scripts or config merges are ever written.
+# API facts pinned against opencode 1.18.2 (2026-07-16): see the adapters/opencode_http.py docstring.
+name = "opencode-http"
+binary = "opencode"
+# Driven by the bundled HTTP/SSE adapter class (adapters/registry.py), not the
+# tmux generic adapter — the selector for the coding-CLI adapter axis. Distinct
+# from `hooks.dialect = "none"` below, which says only that no hook config is
+# ever registered: the two axes are decoupled.
+adapter = "opencode-http"
+prompt_template = "Use the {skill} skill now: {args}"
+usage_parser = "none"
+skill_tree = ".claude/skills"
+first_run_note = "run `opencode auth login` once on this machine; headless servers reuse the stored credentials"
+
+# Transport/provider environment-fault classification (#194). Unlike the tmux
+# adapters, the file scanned for this adapter is logs/<task_id>.server.out — the
+# `opencode serve` process's own stdout/stderr, structured logfmt, which the model
+# never writes to. So the anchor can be the ai-sdk error class opencode reports in
+# the `error.error=` field of a `level=ERROR message="stream error"` line, which is
+# both precise and incapable of colliding with story output.
+#
+# NOT logs/<task_id>.log: that is the curated `[froid]` conversation transcript and
+# it carries the model's own words. These patterns are only safe against a
+# model-free log, so the file the classifier reads is part of their contract —
+# see EnvFaultMixin.ENV_FAULT_LOG_SUFFIX.
+#
+# Verified against a real 5-hour provider quota outage: 22 matching lines across
+# one run, in two forms — a clean refusal, and the socket drop providers fall
+# back to once they stop answering at all:
+#   ... message="stream error" ... error.error="AI_APICallError: Usage limit reached for 5 hour. Your limit will reset at 2026-07-26 22:49:46"
+#   ... message="stream error" ... error.error="AI_APICallError: Cannot connect to API: The socket connection was closed unexpectedly."
+# To disable or extend, copy this profile into .froid-loop/profiles/ and edit.
+# Anchored on the structured field name, not on the error class alone: the server
+# reports the failure as `error.error="AI_APICallError: …"` inside a logfmt line.
+# The bare class name would also match `const MSG = "AI_APICallError: Usage limit
+# reached";` — unreachable in THIS log, but a pattern is copied into project
+# overlays and read as an example, so it should not model a weaker rule than it
+# means. Deliberately content-anchored rather than position-anchored: this file is
+# a byte stream, and the tmux profiles' equivalent is a raw pipe-pane capture full
+# of cursor-addressed repaints, so no column or line offset in it is meaningful.
+# The gap is [^"], not `.`: it must stay INSIDE the quoted error value. With `.`
+# the lazy gap walks past the closing quote and finds a cause word in a later
+# logfmt field, so an unrelated `AI_APICallError: Invalid API key` on a line whose
+# trailing fields mention a quota path classifies as a quota outage. In every
+# captured line the cause is inside the quotes, so nothing real is lost.
+env_fault_patterns = [
+  'error[.]error="AI_APICallError: [^"]{0,400}?(?i:usage limit reached|429|too many requests|rate[ _-]?limit|quota|overloaded)',
+  'error[.]error="AI_APICallError: [^"]{0,400}?(?i:cannot connect to api|socket connection was closed|connection ?(error|refused|reset|timed ?out)|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN)',
+]
+
+[hooks]
+dialect = "none"