@passioncode-ai/fabric-agent-adapter 0.40.0 → 0.41.0

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session_mail.py

@@ -15,10 +15,13 @@ from fabric_session_env import (  # noqa: E402 - the kit (FAA-65)
     UNREAD_LINE,
     VERSION,
     WORKER_DEADLINE_S,
+    _write_private,
     claude_registration,
     fabric_launched,
     fabric_root,
     locate_hub,
+    rejoin_wait,
+    session_dir,
 )
 from fabric_session_mcp import (  # noqa: E402 - the kit (FAA-65)
     McpStdio,
@@ -36,9 +39,15 @@ WATCH_MAX_BACKOFF_S = 900
 def poll_unread(session_id: str, cwd: Path, env: Optional[Dict[str, str]] = None,
                 deadline_s: float = WORKER_DEADLINE_S) -> Tuple[str, Any]:
     """One look at the board through `fabric-mcp --rejoin-only`: ("ok", count), ("unavailable", why) when Fabric
-    answers but the board cannot be read, ("down", why) when Fabric cannot be reached. No fabric-mcp starts unless
-    the running Fabric advertises session-hooks/1 (the rejoin)."""
+    answers but the board cannot be read, ("down", why) when Fabric cannot be reached, ("wait", seconds) when the
+    session rejoined within the last minute (the Stop worker's mark, or this one's): the rejoin budget is shared, so
+    no fabric-mcp starts then (FAA-68). No fabric-mcp starts unless the running Fabric advertises session-hooks/1
+    (the rejoin). A successful rejoin renews the mark in the session's folder when the hooks made one."""
     env = dict(os.environ if env is None else env)
+    directory = session_dir(session_id, env)
+    left = rejoin_wait(directory)
+    if left > 0:
+        return "wait", left
     hub = locate_hub(fabric_root(env=env))
     if hub["state"] != "running":
         return "down", "Fabric is not running (%s)" % hub["reason"]
@@ -56,6 +65,11 @@ def poll_unread(session_id: str, cwd: Path, env: Optional[Dict[str, str]] = None
                                       "clientInfo": {"name": "fabric-agent-adapter-watch-mail", "version": VERSION}})
         client.notify("notifications/initialized")
         names = _wait_for_session_tools(client, deadline)
+        if directory.is_dir():  # the hooks made it, after their launch check; never made here
+            try:
+                _write_private(directory / "rejoined", "")
+            except OSError:
+                pass
         if BOARD_STATUS_TOOL not in names:
             return "unavailable", "this Fabric serves no %s" % BOARD_STATUS_TOOL
         unread, said = board_unread(client.request("tools/call", {"name": BOARD_STATUS_TOOL, "arguments": {}}))
@@ -72,15 +86,18 @@ def poll_unread(session_id: str, cwd: Path, env: Optional[Dict[str, str]] = None
 def watch_mail(session_id: str, cwd: Path, env: Optional[Dict[str, str]] = None, interval: float = 60, *,
                poll: Optional[Callable[[], Tuple[str, Any]]] = None, out: Callable[[str], None] = print,
                wait: Callable[[float], bool], stop: Callable[[], bool], rng: Callable[[], float]) -> int:
-    """Poll the board every `interval` seconds (±20 % jitter, never under WATCH_MIN_INTERVAL_S) and print ONE line each
-    time the unread count rises. While Fabric is down or the board unreadable, say so once and back off, doubling up
-    to WATCH_MAX_BACKOFF_S. `wait(seconds)` returns True when it was told to stop."""
+    """Poll the board every `interval` seconds (±20 % jitter; the delay after jitter stays within WATCH_MIN_INTERVAL_S
+    and WATCH_MAX_BACKOFF_S) and print ONE line each time the unread count rises. While Fabric is down or the board
+    unreadable, say so once and back off, doubling up to WATCH_MAX_BACKOFF_S. A look the shared rejoin mark holds back
+    ("wait") changes nothing and waits it out. `wait(seconds)` returns True when it was told to stop."""
     interval = max(float(WATCH_MIN_INTERVAL_S), float(interval))
     poll = poll or (lambda: poll_unread(session_id, cwd, env))
     last, trouble, backoff = 0, None, interval
     while not stop():
         kind, value = poll()
-        if kind == "ok":
+        if kind == "wait":
+            delay = float(value)
+        elif kind == "ok":
             if value > last:
                 out(UNREAD_LINE % value)
             last, trouble, backoff = value, None, interval
@@ -91,7 +108,8 @@ def watch_mail(session_id: str, cwd: Path, env: Optional[Dict[str, str]] = None,
                 out("watch-mail: %s; trying again, backing off up to %d minutes" % (value, WATCH_MAX_BACKOFF_S // 60))
                 trouble = kind
             delay = backoff
-        if wait(delay * (0.8 + 0.4 * rng())):
+        jittered = delay if kind == "wait" else delay * (0.8 + 0.4 * rng())
+        if wait(min(max(jittered, float(WATCH_MIN_INTERVAL_S)), float(WATCH_MAX_BACKOFF_S))):
             break
     return 0
 

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session_mcp.py

@@ -6,17 +6,21 @@ import json
 import os
 import re
 import subprocess
+import sys
 import time
 from pathlib import Path
 from typing import Any
+from typing import Callable
 from typing import Dict
 from typing import List
 from typing import Optional
+from typing import Tuple
 
 from fabric_session_env import (  # noqa: E402 - the kit (FAA-65)
     BOARD_STATUS_TOOL,
     GIT_TIMEOUT_S,
     HOOK_FEATURE,
+    LOCK_STALE_S,
     SESSION_ID,
     VERSION,
     WORKER_DEADLINE_S,
@@ -25,7 +29,6 @@ from fabric_session_env import (  # noqa: E402 - the kit (FAA-65)
     claude_registration,
     fabric_root,
     locate_hub,
-    lock_held,
     log,
     read_small,
 )
@@ -43,21 +46,36 @@ RELEASE_TOOL = "fabric_work_release"
 WAITING_TOOL = "fabric_whoami"
 
 
-def git_facts(cwd: Path) -> Dict[str, Optional[int]]:
-    """HEAD, files that differ from it (untracked included) and lines added/removed. No path, no text."""
+#: The Stop and SessionEnd hooks measure the turn's facts inside this total, so the hook stays far under its 5 s.
+FACTS_BUDGET_S = 1.5
+
+
+FACT_KEYS = ("head", "filesChanged", "linesAdded", "linesRemoved")
+
+
+HEAD = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")
+
+
+def git_facts(cwd: Path, budget_s: Optional[float] = None) -> Dict[str, Optional[int]]:
+    """HEAD, files that differ from it (untracked included) and lines added/removed. No path, no text. With
+    `budget_s`, every git call shares that total; a fact git could not give in time is None."""
     facts: Dict[str, Any] = {"head": None, "filesChanged": None, "linesAdded": None, "linesRemoved": None}
+    until = None if budget_s is None else time.monotonic() + budget_s
 
     def git(*args: str) -> Optional[str]:
+        timeout = GIT_TIMEOUT_S if until is None else min(GIT_TIMEOUT_S, until - time.monotonic())
+        if timeout <= 0:
+            return None
         try:
             done = subprocess.run(["git", "--no-optional-locks", "-C", str(cwd)] + list(args),
                                   stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
-                                  timeout=GIT_TIMEOUT_S, check=False)
+                                  timeout=timeout, check=False)
         except (OSError, subprocess.SubprocessError):
             return None
         return done.stdout.decode("utf-8", "replace") if done.returncode == 0 else None
 
     head = (git("rev-parse", "--verify", "-q", "HEAD") or "").strip()
-    facts["head"] = head if re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", head) else None
+    facts["head"] = head if HEAD.fullmatch(head) else None
     status = git("status", "--porcelain=v1", "-z", "--untracked-files=normal")
     if status is not None:
         facts["filesChanged"] = _count_status(status)
@@ -86,19 +104,54 @@ def _count_status(z: str) -> int:
     return count
 
 
+def stored_facts(entry: Dict[str, Any]) -> Dict[str, Any]:
+    """The facts a spool entry carries, as the hook measured them when its turn ended (FAA-68): a head of 40 or 64
+    hex digits and non-negative counts, each else None. Nothing is measured at delivery."""
+    facts = entry.get("facts") if isinstance(entry.get("facts"), dict) else {}
+    head = facts.get("head")
+    out: Dict[str, Any] = {"head": head if isinstance(head, str) and HEAD.fullmatch(head) else None}
+    for key in FACT_KEYS[1:]:
+        value = facts.get(key)
+        out[key] = value if isinstance(value, int) and not isinstance(value, bool) and 0 <= value < 2 ** 53 else None
+    return out
+
+
+class JsonRpcError(RuntimeError):
+    """An `error` answer to one request: that request failed, the connection did not."""
+
+    def __init__(self, code: Any):
+        self.code = code if isinstance(code, int) and not isinstance(code, bool) else None
+        super().__init__("json-rpc error %s" % self.code)
+
+    def said(self) -> str:
+        return "error:%s" % ("unnamed" if self.code is None else self.code)
+
+
 class McpStdio:
     """A minimal MCP client over stdio (newline-delimited JSON-RPC) with a hard deadline."""
 
     def __init__(self, argv: List[str], cwd: str, env: Dict[str, str], deadline: float):
         import threading  # only the worker needs it; the hooks' path stays light
         self.deadline = deadline
+        # Its own process group (FAA-68): a wrapper (npx, a shell script, fabric-mcp.cmd) keeps the server as a
+        # grandchild, and only a group kill reaches it.
+        options: Dict[str, Any] = {}
+        if sys.platform == "win32":
+            options["creationflags"] = 0x00000200  # CREATE_NEW_PROCESS_GROUP
+            # CreateProcess applies no PATHEXT: a registration naming `fabric-mcp` means `fabric-mcp.cmd` on PATH.
+            import shutil
+            found = shutil.which(argv[0], path=env.get("PATH"))
+            argv = [found or argv[0]] + list(argv[1:])
+        else:
+            options["start_new_session"] = True
         self.proc = subprocess.Popen(argv, cwd=cwd, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
-                                     stderr=subprocess.DEVNULL)
+                                     stderr=subprocess.DEVNULL, **options)
         self.messages: List[Dict[str, Any]] = []
         self.cond = threading.Condition()
         self.next_id = 0
         self.tools_changed = False
-        threading.Thread(target=self._read, daemon=True).start()
+        self.reader = threading.Thread(target=self._read, daemon=True)
+        self.reader.start()
 
     def _read(self) -> None:
         assert self.proc.stdout is not None
@@ -134,7 +187,8 @@ class McpStdio:
                     if message.get("id") == ident:
                         self.messages.remove(message)
                         if "error" in message:
-                            raise RuntimeError("json-rpc error %s" % (message["error"] or {}).get("code"))
+                            error = message["error"]
+                            raise JsonRpcError(error.get("code") if isinstance(error, dict) else None)
                         return message.get("result") or {}
                 left = self.deadline - time.monotonic()
                 if left <= 0 or self.proc.poll() is not None:
@@ -148,18 +202,42 @@ class McpStdio:
             self.tools_changed = False
 
     def close(self) -> None:
+        """End the server: its stdin's end first (fabric-mcp exits on it), then its whole process group, so nothing a
+        wrapper started keeps the pipe open. Never blocks on stdout while the reader thread holds it (FAA-68)."""
+        grace = max(0.2, min(1.5, self.deadline - time.monotonic()))
         try:
             if self.proc.stdin:
-                self.proc.stdin.close()  # fabric-mcp ends on stdin's end
-            self.proc.wait(timeout=1.5)
+                self.proc.stdin.close()
         except Exception:  # noqa: BLE001
-            self.proc.kill()
+            pass
+        try:
+            self.proc.wait(timeout=grace)
+        except Exception:  # noqa: BLE001
+            pass
+        self._kill_group()  # the wrapper may have exited and left its child behind: always
+        try:
+            self.proc.wait(timeout=1.0)
+        except Exception:  # noqa: BLE001
+            pass
+        self.reader.join(timeout=1.0)
+        if self.proc.stdout and not self.reader.is_alive():
+            self.proc.stdout.close()  # a reader still blocked keeps it; the process's end closes it
+
+    def _kill_group(self) -> None:
+        if sys.platform == "win32":
             try:
-                self.proc.wait(timeout=1.0)
-            except Exception:  # noqa: BLE001
+                subprocess.run(["taskkill", "/F", "/T", "/PID", str(self.proc.pid)], stdin=subprocess.DEVNULL,
+                               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=2.0, check=False)
+            except (OSError, subprocess.SubprocessError):
                 pass
-        if self.proc.stdout:
-            self.proc.stdout.close()
+            if self.proc.poll() is None:
+                self.proc.kill()
+            return
+        import signal
+        try:
+            os.killpg(self.proc.pid, signal.SIGKILL)  # the group the server leads (start_new_session)
+        except OSError:
+            pass
 
 
 def _take_lock(directory: Path, wait_s: float = 0.0) -> bool:
@@ -175,7 +253,14 @@ def _take_lock(directory: Path, wait_s: float = 0.0) -> bool:
         time.sleep(0.2)
 
 
-def _try_lock(lock: Path, directory: Path) -> bool:
+def _identity(st: os.stat_result) -> Tuple[int, int, int, int]:
+    return (st.st_dev, st.st_ino, st.st_mtime_ns, st.st_size)  # not ctime: the rename itself moves it
+
+
+def _try_lock(lock: Path, directory: Path, _between: Optional[Callable[[], None]] = None) -> bool:
+    """Create the lock; take a stale one (older than LOCK_STALE_S) by renaming it to a name of this worker's own and
+    checking that the file renamed is the very one judged stale. A lock another worker made in between is put back
+    (FAA-68: no check-then-act). `_between` runs after the judgement and before the rename, for the tests."""
     for _ in range(2):
         try:
             fd = os.open(str(lock), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
@@ -183,14 +268,46 @@ def _try_lock(lock: Path, directory: Path) -> bool:
             os.close(fd)
             return True
         except FileExistsError:
-            if lock_held(directory):
-                return False
+            pass
+        except OSError:
+            return False
+        try:
+            seen = os.lstat(str(lock))
+        except FileNotFoundError:
+            continue
+        except OSError:
+            return False
+        if time.time() - seen.st_mtime < LOCK_STALE_S:
+            return False
+        if _between is not None:
+            _between()
+        taken = directory / (".worker.lock.%d.%s" % (os.getpid(), os.urandom(4).hex()))
+        try:
+            os.rename(str(lock), str(taken))
+        except FileNotFoundError:
+            continue  # another worker took it first; try to create ours
+        except OSError:
+            return False
+        try:
+            got = os.lstat(str(taken))
+        except OSError:
+            return False
+        # An inode number alone is not identity: Linux hands a freed one straight to the next file, so the lock another
+        # worker just made can carry the stale lock's number. Its write time and size are its own.
+        if _identity(got) != _identity(seen):
             try:
-                lock.unlink()
+                os.link(str(taken), str(lock))  # put the live lock back, unless a newer one is there already
             except OSError:
-                return False
-        except OSError:
+                pass
+            try:
+                os.unlink(str(taken))
+            except OSError:
+                pass
             return False
+        try:
+            os.unlink(str(taken))
+        except OSError:
+            pass
     return False
 
 
@@ -234,8 +351,33 @@ def board_unread(result: Dict[str, Any]) -> Tuple[Optional[int], str]:
     return unread, "answer=ok unread=%d%s" % (unread, " board=degraded" if state == "degraded" else "")
 
 
+def _read_entry(path: Path) -> Optional[Dict[str, Any]]:
+    """One spool entry, or None when it cannot be read as one: not a small regular file, not UTF-8 JSON, not an
+    object, or an event other than `turn` and `end`."""
+    try:
+        entry = json.loads(read_small(path) or "")
+    except ValueError:
+        return None
+    if not isinstance(entry, dict) or entry.get("event") not in ("turn", "end"):
+        return None
+    return entry
+
+
+def _entry_cwd(entries: List[Path]) -> Path:
+    """The folder the session worked in, from the first entry that names an existing one."""
+    for path in entries:
+        entry = _read_entry(path)
+        cwd = entry.get("cwd") if entry else None
+        if isinstance(cwd, str) and cwd and "\0" not in cwd and Path(cwd).is_dir():
+            return Path(cwd)
+    return Path(os.getcwd())
+
+
 def deliver(directory: Path, env: Optional[Dict[str, str]] = None, deadline_s: float = WORKER_DEADLINE_S) -> List[str]:
-    """Drain one session's spool through fabric-mcp --rejoin-only. Returns the log lines it wrote."""
+    """Drain one session's spool through fabric-mcp --rejoin-only. Returns the log lines it wrote. An entry that
+    cannot be read, or a call answered with a JSON-RPC error, is logged and dropped; the rest still goes out (FAA-68).
+    Only an answer that never came leaves the spool for the next worker: the session's folder goes only once its end
+    entry's calls (the claim release and the end observation) were answered, refused or error-coded."""
     env = dict(os.environ if env is None else env)
     said: List[str] = []
 
@@ -250,12 +392,20 @@ def deliver(directory: Path, env: Optional[Dict[str, str]] = None, deadline_s: f
         return said
     client: Optional[McpStdio] = None
     ended = False
+
+    def call(event: str, tool: str, arguments: Dict[str, Any]) -> None:
+        assert client is not None
+        try:
+            answer = _answer_said(client.request("tools/call", {"name": tool, "arguments": arguments}))
+        except JsonRpcError as exc:
+            answer = exc.said()
+        note("session=%s event=%s tool=%s answer=%s" % (session_id[:8], event, tool, answer))
+
     try:
         entries = sorted(directory.glob("*-*.json"))
         if not entries:
             return said
-        first = json.loads(read_small(entries[0]) or "{}")
-        cwd = Path(first.get("cwd") or os.getcwd())
+        cwd = _entry_cwd(entries)
         registration = claude_registration(cwd, env)
         hub = locate_hub(fabric_root(env=env))
         if not registration or hub["state"] != "running" or HOOK_FEATURE not in hub.get("features", []):
@@ -275,35 +425,41 @@ def deliver(directory: Path, env: Optional[Dict[str, str]] = None, deadline_s: f
         _write_private(directory / "rejoined", "")
         while entries:
             for path in entries:
-                entry = json.loads(read_small(path) or "{}")
-                event = entry.get("event")
+                entry = _read_entry(path)
+                if entry is None:
+                    note("session=%s outcome=dropped reason=%r" % (session_id[:8], "unreadable entry"))
+                    path.unlink()
+                    continue
+                event = entry["event"]
                 key = "%s:%s" % (session_id, path.name.split("-", 1)[0])
+                reason = entry.get("reason") if isinstance(entry.get("reason"), str) else "other"
                 if event == "end":
-                    ended = True
                     if RELEASE_TOOL in names:
-                        result = client.request("tools/call", {"name": RELEASE_TOOL, "arguments": {
+                        call(event, RELEASE_TOOL, {
                             "claims": "session", "outcome": "let-go",
-                            "reason": "the Claude Code session ended (%s)" % entry.get("reason", "other"),
-                            "idempotencyKey": key + ":release"}})
-                        note("session=%s event=end tool=%s answer=%s" % (session_id[:8], RELEASE_TOOL, _answer_said(result)))
+                            "reason": "the Claude Code session ended (%s)" % reason,
+                            "idempotencyKey": key + ":release"})
                     else:
                         note("session=%s event=end outcome=degraded reason=%r" % (session_id[:8], "no %s" % RELEASE_TOOL))
-                if event in ("turn", "end"):
-                    if OBSERVE_TOOL in names:
-                        arguments = dict(git_facts(cwd), event=event, runtime=RUNNER, runtimeSessionId=session_id,
-                                         observedAt=entry.get("observedAt"), idempotencyKey=key)
-                        if event == "end":
-                            arguments["reason"] = entry.get("reason", "other")
-                        result = client.request("tools/call", {"name": OBSERVE_TOOL, "arguments": arguments})
-                        note("session=%s event=%s tool=%s answer=%s" % (session_id[:8], event, OBSERVE_TOOL, _answer_said(result)))
-                    elif not (directory / "observe.degraded").exists():
-                        note("session=%s event=%s outcome=degraded reason=%r" % (session_id[:8], event, "no %s" % OBSERVE_TOOL))
-                        (directory / "observe.degraded").touch()
+                if OBSERVE_TOOL in names:
+                    arguments = dict(stored_facts(entry), event=event, runtime=RUNNER, runtimeSessionId=session_id,
+                                     observedAt=entry.get("observedAt"), idempotencyKey=key)
+                    if event == "end":
+                        arguments["reason"] = reason
+                    call(event, OBSERVE_TOOL, arguments)
+                elif not (directory / "observe.degraded").exists():
+                    note("session=%s event=%s outcome=degraded reason=%r" % (session_id[:8], event, "no %s" % OBSERVE_TOOL))
+                    (directory / "observe.degraded").touch()
                 path.unlink()
+                if event == "end":
+                    ended = True  # only now: a call that timed out above left this entry for the next worker
             entries = sorted(directory.glob("*-*.json"))  # turns spooled while this worker ran
         if not ended and BOARD_STATUS_TOOL in names:
             # The board's unread count for the prompt hook (FAA-12a). A count, never a message.
-            unread, said_board = board_unread(client.request("tools/call", {"name": BOARD_STATUS_TOOL, "arguments": {}}))
+            try:
+                unread, said_board = board_unread(client.request("tools/call", {"name": BOARD_STATUS_TOOL, "arguments": {}}))
+            except JsonRpcError as exc:
+                unread, said_board = None, "answer=" + exc.said()
             _write_private(directory / "board.json", json.dumps({
                 "unread": unread, "observedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}))
             note("session=%s event=board tool=%s %s" % (session_id[:8], BOARD_STATUS_TOOL, said_board))

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/host_hooks.py

@@ -105,6 +105,10 @@ def plan(host, path, script, remove):
         return [(path, old, openclaw_edit(old, script, remove))]
     if host == 'hermes':
         if path.is_symlink(): raise fs.Refused('plugin directory is a symlink; nothing was changed')
+        if remove:
+            # Removal reads nothing from the source skill: its hosts/ folder may be gone (FAA-69).
+            desired = dict.fromkeys((path/'__init__.py', path/'plugin.yaml'), '')
+            return _changes(desired, remove)
         module = str(script.parent / 'hosts/hermes/__init__.py')
         loader = ('# ' + MARKER + '\nimport importlib.util\n'
                   '_spec = importlib.util.spec_from_file_location("_fabric_native_hermes", ' + repr(module) + ')\n'
@@ -114,6 +118,10 @@ def plan(host, path, script, remove):
     else:
         module = (script.parent / ('hosts/' + host + '/fabric.mjs')).as_uri()
         desired = {path: '// ' + MARKER + '\nexport { default } from ' + json.dumps(module) + ';\n'}
+    return _changes(desired, remove)
+
+
+def _changes(desired, remove):
     changes = []
     for target, text in desired.items():
         old = fs._read_bytes(target)
@@ -137,7 +145,8 @@ def main(argv=None, env=None, out=print, err=print):
     args=parser.parse_args(argv)
     try:
         script=Path(args.script).expanduser().absolute() if args.script else BASE/'fabric_session.py'
-        if not script.is_file(): raise fs.Refused('shared helper is missing')
+        # Removal needs no helper: the skill it was installed from may be gone (FAA-69).
+        if not args.remove and not script.is_file(): raise fs.Refused('shared helper is missing')
         if not args.remove:
             required = {'hermes':['hosts/hermes/__init__.py','hosts/hermes/plugin.yaml'],
                         'opencode':['hosts/context.mjs','hosts/opencode/fabric.mjs'],

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/context.mjs

@@ -7,6 +7,9 @@ const scriptPath = fileURLToPath(new URL('../fabric_session.py', import.meta.url
 const hosts = new Set(['opencode', 'pi', 'openclaw']);
 const cap = 64 * 1024;
 
+// Resolves the helper's context, '' when it answered none (or nothing usable), and null when the run failed: an error,
+// a nonzero exit, a timeout, output over the cap, a missing python3 or script. A caller treats null as no context;
+// onceEach keeps no null, so the next request runs the helper again.
 export async function readContext(host, cwd, options = {}) {
   if (!hosts.has(host) || typeof cwd !== 'string' || !cwd || cwd.includes('\0')) return '';
   const payload = {cwd};
@@ -21,13 +24,33 @@ export async function readContext(host, cwd, options = {}) {
         ['-S', options.script || scriptPath, 'hook', 'session-start', '--host', host],
         {timeout, killSignal:'SIGKILL', maxBuffer:cap, encoding:'utf8', windowsHide:true},
         (error, stdout) => {
-          if (error || typeof stdout !== 'string' || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(stdout)) return resolve('');
+          if (error || typeof stdout !== 'string') return resolve(null);
+          if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(stdout)) return resolve('');
           resolve(stdout.trim());
         });
       // A missing executable or early exit may close stdin before it is written.
       child.stdin?.on('error', () => {});
       child.stdin?.end(input);
-    } catch { resolve(''); }
+    } catch { resolve(null); }
   });
 }
+
+// One helper run per host, workspace and registration in this process (FAA-69): OpenCode and OpenClaw ask on every
+// request, and the answer does not change within a process. A failed run (a rejection, or null from readContext) is
+// not kept, so the next request asks again.
+const cacheCap = 64;
+export function onceEach(reader = readContext) {
+  const answers = new Map();
+  return (host, cwd, options = {}) => {
+    const key = JSON.stringify([host, cwd, options.fabricRegistered === true]);
+    if (!answers.has(key)) {
+      if (answers.size >= cacheCap) answers.delete(answers.keys().next().value);
+      const pending = Promise.resolve().then(() => reader(host, cwd, options));
+      answers.set(key, pending);
+      const forget = () => { if (answers.get(key) === pending) answers.delete(key); };
+      pending.then((value) => { if (value === null || value === undefined) forget(); }, forget);
+    }
+    return answers.get(key);
+  };
+}
 // #endregion native-host-context

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/openclaw/index.mjs

@@ -1,6 +1,6 @@
 // #region native-host-context — docs: plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md
 // Native OpenClaw prompt hook. Never observes conversation content or sends messages.
-import { readContext } from '../context.mjs';
+import { onceEach, readContext } from '../context.mjs';
 
 function fabricRegistered(config) {
   const servers = config?.mcp?.servers;
@@ -14,6 +14,8 @@ function fabricRegistered(config) {
 }
 
 export function createPlugin(contextReader = readContext) {
+  // The helper runs once per workspace and registration in this process, not per prompt (FAA-69).
+  const read = onceEach(contextReader);
   return {
     id: 'fabric-agent-adapter',
     name: 'Fabric Agent Adapter',
@@ -27,7 +29,7 @@ export function createPlugin(contextReader = readContext) {
           // Configured is not connected/admitted. Forward only the boolean,
           // never server configuration, headers, environment or credentials.
           const options = fabricRegistered(api.config) ? { fabricRegistered: true } : {};
-          const context = await contextReader('openclaw', ctx.workspaceDir, options);
+          const context = await read('openclaw', ctx.workspaceDir, options);
           ctx.hookInvocation?.assertActive();
           if (typeof context !== 'string' || !context.trim()) return;
           return { prependContext: context };

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/opencode/fabric.mjs

@@ -1,11 +1,12 @@
 // #region native-host-context — docs: plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md
-import { readContext } from '../context.mjs';
+import { onceEach } from '../context.mjs';
 
 const marker = '[fabric-agent-adapter]';
 
 // OpenCode's legacy loader treats every export as a plugin factory.
 export default async function fabricPlugin({directory} = {}) {
   let fabricRegistered = false;
+  const readContext = onceEach();  // Python once per workspace and registration, not per request (FAA-69)
   return {
     config: async config => {
       const entry = config?.mcp?.fabric;