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

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

@@ -6,17 +6,22 @@ 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,
+    NO_SESSION_MARK,
     SESSION_ID,
     VERSION,
     WORKER_DEADLINE_S,
@@ -25,7 +30,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 +47,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 +105,64 @@ 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)
+
+
+#: fabric-mcp --rejoin-only's exit status when no Fabric session holds the runtime id (Fabric 0.3.9, TR-11).
+NO_SESSION_EXIT = 3
+
+
+class NoSessionError(TimeoutError):
+    """fabric-mcp --rejoin-only ended with NO_SESSION_EXIT: Fabric holds no session for this id. A TimeoutError, so a
+    caller that knows only "no answer" (watch-mail) keeps treating it as one."""
+
+
 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.tools: List[Dict[str, Any]] = []  # the last tools/list answer, for the tools' input schemas
+        self.reader = threading.Thread(target=self._read, daemon=True)
+        self.reader.start()
 
     def _read(self) -> None:
         assert self.proc.stdout is not None
@@ -116,10 +180,23 @@ class McpStdio:
         with self.cond:
             self.cond.notify_all()
 
+    def _ended(self) -> None:
+        """The server is gone: raise what its exit status says."""
+        if self.proc.returncode == NO_SESSION_EXIT:
+            raise NoSessionError("fabric-mcp found no session for this id")
+        raise TimeoutError("fabric-mcp ended")
+
     def _send(self, message: Dict[str, Any]) -> None:
         assert self.proc.stdin is not None
-        self.proc.stdin.write((json.dumps(message) + "\n").encode("utf-8"))
-        self.proc.stdin.flush()
+        try:
+            self.proc.stdin.write((json.dumps(message) + "\n").encode("utf-8"))
+            self.proc.stdin.flush()
+        except OSError:  # a server that exited closed its stdin: say why it exited, never a broken pipe
+            try:
+                self.proc.wait(timeout=max(0.0, min(1.0, self.deadline - time.monotonic())))
+            except subprocess.TimeoutExpired:
+                pass
+            self._ended()
 
     def notify(self, method: str, params: Optional[Dict[str, Any]] = None) -> None:
         self._send({"jsonrpc": "2.0", "method": method, **({"params": params} if params else {})})
@@ -134,10 +211,13 @@ 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:
+                if self.proc.poll() is not None:
+                    self._ended()
+                if left <= 0:
                     raise TimeoutError("no answer to %s" % method)
                 self.cond.wait(min(left, 0.25))
 
@@ -148,18 +228,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
+            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
-            self.proc.kill()
+            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 +279,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 +294,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 +377,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 +418,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"))
+        entries = _drop_stale_ends(sorted(directory.glob("*-*.json")), note, session_id)
         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,38 +451,61 @@ 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": {
-                            "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)))
+                        release = {"claims": "session", "outcome": "let-go",
+                                   "reason": "the Claude Code session ended (%s)" % reason,
+                                   "idempotencyKey": key + ":release"}
+                        # Fabric 0.3.9 refuses an end observed before the session enrolled (`stale-end`, board thread
+                        # 02bf19c5): say when it was observed, where the tool takes the field.
+                        if isinstance(entry.get("observedAt"), str) and "observedAt" in _input_fields(client, RELEASE_TOOL):
+                            release["observedAt"] = entry["observedAt"]
+                        call(event, RELEASE_TOOL, 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()
-            entries = sorted(directory.glob("*-*.json"))  # turns spooled while this worker ran
+                if event == "end":
+                    ended = True  # only now: a call that timed out above left this entry for the next worker
+            entries = _drop_stale_ends(sorted(directory.glob("*-*.json")), note, session_id)  # spooled meanwhile
         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))
+    except NoSessionError:
+        # Recorded once (02bf19c5, ask 4): nothing in the spool can reach a session Fabric does not hold.
+        note("session=%s outcome=no-session reason=%r" % (session_id[:8], "Fabric holds no session for this id"))
+        for path in directory.glob("*-*.json"):
+            ended = ended or path.name.endswith("-end.json")  # the session's last hook: its folder goes now
+            try:
+                path.unlink()
+            except OSError:
+                pass
+        try:
+            _write_private(directory / NO_SESSION_MARK, "")
+        except OSError as exc:  # the worker never raises: without the mark, the next turn tries once more
+            note("session=%s outcome=no-session reason=%r" % (session_id[:8], "the mark was not written (%s)" % type(exc).__name__))
     except TimeoutError as exc:
         note("session=%s outcome=unknown reason=%r" % (session_id[:8], str(exc)))
     except Exception as exc:  # noqa: BLE001 — the worker never raises
@@ -323,10 +522,39 @@ def deliver(directory: Path, env: Optional[Dict[str, str]] = None, deadline_s: f
     return said
 
 
+def _drop_stale_ends(entries: List[Path], note: Callable[[str], None], session_id: str) -> List[Path]:
+    """The entries left once every end followed by a later turn of the same id is dropped (FAA-83; board thread
+    02bf19c5, ask 3): `claude --resume` keeps the id, so such an end belongs to an earlier process of the session, and
+    delivering it would release the live session's claims. An end that is the newest entry keeps its retry. Entries
+    are named by `time_ns`, so the sorted order is the spooling order."""
+    kept: List[Path] = []
+    for index, path in enumerate(entries):
+        if path.name.endswith("-end.json") and any(p.name.endswith("-turn.json") for p in entries[index + 1:]):
+            note("session=%s event=end outcome=dropped reason=%r" % (session_id[:8], "a later turn of the same session"))
+            try:
+                path.unlink()
+            except OSError:
+                pass
+            continue
+        kept.append(path)
+    return kept
+
+
+def _input_fields(client: McpStdio, tool: str) -> List[str]:
+    """The property names a listed tool's input schema declares; [] when it declares none."""
+    for listed in client.tools:
+        if listed.get("name") == tool:
+            schema = listed.get("inputSchema")
+            props = schema.get("properties") if isinstance(schema, dict) else None
+            return [k for k in props if isinstance(k, str)] if isinstance(props, dict) else []
+    return []
+
+
 def _wait_for_session_tools(client: McpStdio, deadline: float) -> List[str]:
     """fabric-mcp lists only fabric_whoami until it holds a session; then it says its tools changed."""
     while True:
         tools = client.request("tools/list", {}).get("tools") or []
+        client.tools = [t for t in tools if isinstance(t, dict)]
         names = [t.get("name") for t in tools if isinstance(t, dict) and isinstance(t.get("name"), str)]
         if [n for n in names if n != WAITING_TOOL]:
             return names

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;