@passioncode-ai/fabric-agent-adapter 0.55.0 → 0.57.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/sample_service.py

@@ -13,7 +13,10 @@ once, and `sample.draft` is a job that stops for a titled choice before it compl
 Opt-in, off by default: `serve --board-project <Project uuid>` also answers that Project's `sample.echo` requests on
 Fabric's project board (fabric-project-comms/0.1, FAA-12b) with fabric_board.Responder, from a board.respond grant whose
 credential is in `<data>/board.credential` (0600; `--board-credential` names another file). The request body is data:
-the gate admits plain text of at most 2,000 characters, and the answer is a reply carrying the same text.
+the gate admits plain text of at most 2,000 characters, and the answer is a reply carrying the same text. Its
+dashboard's Take back has the tool `board.take-back`, which the manifest lists when registered with the same
+`--board-project`; a serve whose board mode differs from the registered manifest at its start logs
+`service.manifest.mismatch`.
 """
 
 from __future__ import annotations
@@ -52,8 +55,29 @@ PAGE = """<!doctype html><html lang="en"><head><meta charset="utf-8">
 <nav class="fd-nav" aria-label="Sections"><ul class="fd-nav-list"><li><a href="#events" aria-current="page">Events</a></li>
 <li><a href="#about">About</a></li></ul></nav></div>
 <main class="fd-page"><section id="events"><h2>Events</h2><ul>{rows}</ul></section>
-<section id="about"><h2>About</h2><p class="fd-hint">A sample fabric-service/0.1 service built on the kit.</p></section></main>
+{board}<section id="about"><h2>About</h2><p class="fd-hint">A sample fabric-service/0.1 service built on the kit.</p></section></main>
 </body></html>"""
+# FAA-157: a moved board slot comes back only by the operator's act, a button on this page. The button posts from the
+# operator's signed-in dashboard session with the request header; a service token alone cannot reach it.
+BOARD_SECTION = """<section id="board"><h2>Project board</h2><p class="fd-hint">These slots were moved to another
+session; this service no longer answers them there. Take back asks for one again: the service enrolls once the other
+session lets it go, or at once when it restarts with accepted work for the slot.</p><ul>{items}</ul>
+<script src="/board.js" defer></script></section>"""
+#: The dashboard's Take back button and its tool (FAA-157, DEC-0121): the operator's decision, relayed in `_meta`.
+TAKE_BACK = {"id": "board.take-back", "title": "Take back", "tool": "board.take-back", "gate": "relayed"}
+TAKE_BACK_INPUT = {"type": "object", "properties": {"capability": {"type": "string"}}, "required": ["capability"],
+                   "additionalProperties": False}
+BOARD_ITEM = '<li>{capability} <button type="button" data-take-back="{capability}">Take back</button></li>'
+BOARD_JS = """document.addEventListener('click', function (e) {
+  var cap = e.target && e.target.getAttribute && e.target.getAttribute('data-take-back');
+  if (!cap) return;
+  e.target.disabled = true;
+  fetch('/api/board/take-back', {method: 'POST', credentials: 'same-origin',
+    headers: {'Content-Type': 'application/json', 'X-Fabric-Request': '1'}, body: JSON.stringify({capability: cap})})
+    .then(function (r) { e.target.textContent = r.ok ? 'Asked back: waiting for the other session' : 'Refused (' + r.status + ')'; })
+    .catch(function () { e.target.disabled = false; e.target.textContent = 'Failed: try again'; });
+});
+"""
 
 
 def _schema(name: str, body: Dict[str, Any]) -> Dict[str, Any]:
@@ -72,10 +96,26 @@ CAPABILITIES = [
      "output": _schema("sample.draft-output", {"type": "object", "additionalProperties": False,
                                                  "properties": {"title": {"type": "string"}, "body": {"type": "string"}}, "required": ["title", "body"]})},
 ]
+#: The take-back tool as a manifest capability (0.56.0 product r28): every tool the well-known lists is in the
+#: manifest, so `register --board-project` writes it there.
+TAKE_BACK_CAPABILITY: Dict[str, Any] = {
+    "name": TAKE_BACK["tool"], "effect": "change-policy", "idempotency": "required", "job": False,
+    "description": "Take back a board slot the operator moved away.",
+    # A relayed action: a probe call carries no operator decision, so it is refused and changes nothing (unit r28).
+    "probeAssertion": "is refused as operator-decision-required without the operator's decision in _meta",
+    "input": _schema("board.take-back-input", TAKE_BACK_INPUT),
+    "output": _schema("board.take-back-output", {"type": "object", "additionalProperties": False,
+                                                  "properties": {"capability": {"type": "string"}, "moved": {"const": False}},
+                                                  "required": ["capability", "moved"]})}
+
+
+def served_capabilities(board: bool) -> list:
+    return CAPABILITIES + ([TAKE_BACK_CAPABILITY] if board else [])
 
 
 class Service:
     def __init__(self, args: argparse.Namespace):
+        self.args = args
         self.id = args.id
         self.instance = args.instance
         self.name = args.name
@@ -110,9 +150,73 @@ class Service:
             self.board = fbd.Responder(hub=fhb.HubClient(), project_id=self.board_project, capabilities=[self.board_capability],
                                        credential_file=self.board_credential, checkpoint_file=self.data / "board-checkpoint.json",
                                        handler=self.board_answer, admit=self.board_admit, emit=self.log.append, service=self.id)
+            # Every button has a tool (DEC-0121): the page's Take back is this relayed action, the operator's decision.
+            cap = TAKE_BACK_CAPABILITY
+            self.mcp.add_tool(fi.tool_for_capability(cap, cap["input"], cap["output"]), self.board_take_back_tool,
+                              action=TAKE_BACK, target="capability")
         self.log.append("service.started", "info", "%s started on build %s." % (self.name, self.build["commit"]))
+        self.check_manifest()
+
+    def check_manifest(self) -> None:
+        """The registered manifest is register's to write, never serve's (0.56.0 seam r28): a serve whose board mode
+        differs from it at its start says so, and the probe fails until it is registered again (interop.tools-match when
+        the manifest lists a take-back this run does not serve, interop.well-known-capabilities when it lacks one this run
+        lists)."""
+        try:
+            listed = {c.get("name") for c in json.loads((self.data / "fabric-agent.json").read_text(encoding="utf-8"))["capabilities"]
+                      if isinstance(c, dict)}
+        except (OSError, ValueError, KeyError, TypeError, AttributeError):
+            return  # not registered here, or not a manifest of this shape: nothing to compare
+        if (TAKE_BACK["tool"] in listed) != (self.board is not None):
+            self.log.append("service.manifest.mismatch", "warning",
+                            "The registered manifest %s the take-back tool, which this run %s: register again %s --board-project."
+                            % ("lists" if TAKE_BACK["tool"] in listed else "lacks",
+                               "does not serve" if self.board is None else "serves", "without" if self.board is None else "with"))
 
     # --- the project board (opt-in): the input gate and the answer -------------------
+    def board_moved(self) -> list:
+        """The capabilities whose slot the operator moved to another session (FAA-155): the page offers their take-back.
+        The live slot or the checkpoint's record says so: before a restart has reconnected (or while Fabric is down) the
+        record alone knows the move (0.56.0 seam r3)."""
+        if not self.board:
+            return []
+        live = {c for c, slot in dict(self.board.slots).items() if slot.get("state") == "moved"}
+        kept = {c for c, record in dict(self.board.checkpoint.slots).items()
+                if isinstance(record, dict) and record.get("project") == self.board_project and "moved" in record}
+        return sorted((live | kept) & set(self.board.capabilities))
+
+    def board_take_back(self, capability: Any, record: Any = None) -> Dict[str, Any]:
+        """The operator's take-back (FAA-157): the next tick enrolls once the other session lets the slot go. `record` is
+        the act the action gate recorded (by, via, caller), kept in the event; never the decision's words. A repeat for a
+        capability of this service that is no longer moved (its first answer lost) answers the same, from the page's
+        route as from the tool (0.56.0 seam r6)."""
+        if self.board is not None and isinstance(capability, str) and capability in self.board.capabilities \
+                and capability not in self.board_moved():
+            return {"capability": capability, "moved": False}
+        if not isinstance(capability, str) or capability not in self.board_moved():
+            raise fs.ServiceError("No slot of that capability has moved away from this service.")
+        self.board.take_back(capability)
+        # Who decided and by which route are words in the sentence; the caller, a machine id, goes in data only
+        # (events-and-notifications.md, "Writing an event"; 0.56.0 product r34).
+        # The route in words; the tokens by and via, with the caller, in data (product r35).
+        act = record if isinstance(record, dict) else {}
+        how = {"dashboard": " on this service's page", "relayed-instruction": " through an agent they told",
+               "mandate": " under a standing mandate"}.get(act.get("via"), "")
+        value = {"capability": capability, **{k: act[k] for k in ("by", "via", "caller") if isinstance(act.get(k), str)}}
+        data = {"schema": fbd.EVENT_SCHEMA, "value": value}
+        extra = {} if fs.feed_data_problems(data) else {"data": data}  # a caller the feed refuses never undoes the answer
+        self.log.append("board.slot.returned", "info", "The operator took the %s slot back%s; the service enrolls once the "
+                        "other session lets it go." % (capability, how),
+                        subject={"type": "capability", "id": capability}, **extra)
+        return {"capability": capability, "moved": False}
+
+    def board_take_back_tool(self, args: Dict[str, Any], ctx: fi.CallContext) -> Dict[str, Any]:
+        """The take-back as a tool: the action gate has already read the operator's relayed decision (gate `relayed`)."""
+        try:
+            return self.board_take_back(args.get("capability"), ctx.record)  # a repeat answers moved: false
+        except (fs.ServiceError, fbd.BoardError) as exc:
+            raise fi.InteropError(str(exc))
+
     def board_admit(self, request: fbd.BoardRequest) -> Optional[str]:
         """The service's own input gate: the body is data, never an instruction; only short plain text is echoed."""
         if request.body_format != "text/plain":
@@ -172,11 +276,14 @@ class Service:
             started_at=self.started_at, status="ready", degraded=self.degraded,
             summary=[{"label": "Events", "value": len(self.log.fetch(None, fs.EVENTS_MAX_LIMIT))}],
             surfaces={"dashboard": {"path": "/", "login": True}, "events": {"path": "/fabric/v1/events"},
-                      "mcp": {"path": "/mcp", "transport": "streamable-http", "capabilities": [c["name"] for c in CAPABILITIES]},
+                      "mcp": {"path": "/mcp", "transport": "streamable-http", "capabilities": [c["name"] for c in CAPABILITIES]
+                              + ([TAKE_BACK["tool"]] if self.board is not None else [])},
                       "usage": {"path": fs.USAGE_PATH}},
             extensions=fs.dashboard_extension() if (KIT_DIR / "fabric-dashboard.css").is_file() else None,
             # DEC-0067: listed only when the board is on — a host pinned before DEC-0067 refuses the member.
-            protocols=["fabric-service/0.1", "fabric-project-comms/0.1"] if self.board is not None else None,
+            # DEC-0126 OA-7: a server serving a relayed action reads `source`, so it lists operator-source/1 too.
+            protocols=self.mcp.well_known_protocols(["fabric-service/0.1", "fabric-project-comms/0.1"]) if self.board is not None else None,
+            actions=self.mcp.action_table() or None,
         )
 
 
@@ -195,7 +302,8 @@ def make_handler(svc: Service):
             self.send_response(status)
             self.send_header("Cache-Control", "no-store")
             self.send_header("X-Content-Type-Options", "nosniff")
-            self.send_header("Content-Security-Policy", "default-src 'none'; style-src 'self'; script-src 'self'; frame-ancestors 'self'")
+            self.send_header("Content-Security-Policy", "default-src 'none'; style-src 'self'; script-src 'self'; connect-src 'self'; "
+                             "frame-ancestors 'self'")
             if body is not None:
                 self.send_header("Content-Type", content_type)
                 self.send_header("Content-Length", str(len(payload)))
@@ -261,8 +369,12 @@ def make_handler(svc: Service):
                     return self._send(401, "Open this dashboard from Fabric Dashboards.", content_type="text/plain")
                 rows = "".join("<li>%s: %s</li>" % (html.escape(e["at"]), html.escape(e["text"]))
                                for e in reversed(svc.log.fetch(None, 20)))
-                return self._send(200, PAGE.format(name=html.escape(svc.name), agent=html.escape("%s.%s" % (svc.id, svc.instance)), status="ready", rows=rows),
+                moved = "".join(BOARD_ITEM.format(capability=html.escape(c)) for c in svc.board_moved())
+                return self._send(200, PAGE.format(name=html.escape(svc.name), agent=html.escape("%s.%s" % (svc.id, svc.instance)), status="ready", rows=rows,
+                                                   board=BOARD_SECTION.format(items=moved) if moved else ""),
                                   content_type="text/html; charset=utf-8")
+            if url.path == "/board.js" and svc.board is not None:
+                return self._send(200, BOARD_JS, content_type="text/javascript; charset=utf-8")
             self._send(404, {"error": "Not found."})
 
         def _length(self, cap: int) -> "int | None":
@@ -290,7 +402,8 @@ def make_handler(svc: Service):
                     return self._send(400, {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error."}})
                 try:
                     with svc.drain.work():
-                        response = svc.mcp.handle(message, self.headers)
+                        # T0 (DL-25): a loopback call the service token authenticated is the local floor's caller.
+                        response = svc.mcp.handle(message, self.headers, tier="T0")
                 except fs.Stopping as exc:
                     return self._send(503, {"jsonrpc": "2.0", "id": None, "error": {"code": -32000, "message": str(exc)}},
                                       {"Retry-After": "5"})
@@ -307,6 +420,21 @@ def make_handler(svc: Service):
                     return self._send(403, {"error": "Missing request header."})
                 svc.codes.logout(fs.cookie_value(self.headers.get("Cookie")))
                 return self._send(204, None, {"Set-Cookie": fs.expired_session_cookie_header()})
+            if url.path == "/api/board/take-back" and svc.board is not None:
+                if not self._session_ok():  # the operator's dashboard session only: never the service token (FAA-157)
+                    return self._send(401, {"error": "Sign in from Fabric Dashboards first."})
+                if self.headers.get("X-Fabric-Request") != "1":
+                    return self._send(403, {"error": "Missing request header."})
+                length = self._length(4096)
+                if length is None:
+                    return
+                try:
+                    body = json.loads(self.rfile.read(length) or b"{}")
+                    # The event names who decided, as the tool's does: the operator, at the dashboard (0.56.0 seam r7).
+                    return self._send(200, svc.board_take_back(body.get("capability") if isinstance(body, dict) else None,
+                                                               {"by": "operator", "via": "dashboard", "caller": "the signed-in page"}))
+                except (ValueError, RecursionError, fs.ServiceError, fbd.BoardError) as exc:
+                    return self._send(400, {"error": str(exc)})
             if url.path == "/api/emit":
                 if not (self._session_ok() or fs.token_matches(self.headers.get("Authorization"), svc.token)):
                     return self._send(401, {"error": "Sign in first."})
@@ -343,11 +471,6 @@ def serve(args: argparse.Namespace) -> int:
     # hand-over that hangs is cut by the kit's hard exit, inside launchd's ExitTimeOut.
     import threading
     board_stop = threading.Event()
-    board_thread = None
-    if svc.board is not None:
-        board_thread = threading.Thread(target=svc.board.run, args=(board_stop, 5.0), name="board-responder", daemon=True)
-        board_thread.start()
-
     stop_asked: list = []
 
     def stopping() -> None:
@@ -355,30 +478,39 @@ def serve(args: argparse.Namespace) -> int:
         board_stop.set()  # stop claiming; the responder drains its request and leaves its board session
         svc.log.append("service.stopping", "info", "%s is stopping." % svc.name)
     svc.drain.install(lambda drained: server.shutdown(), on_stopping=stopping)
+    # The board thread starts only once the stop handler is installed: a SIGTERM in between would end the process with
+    # no drain and no DELETE, and the slot would stay held until its lease lapses (0.56.0 seam r6).
+    board_thread = None
+    if svc.board is not None:
+        board_thread = threading.Thread(target=svc.board.run, args=(board_stop, 5.0), name="board-responder", daemon=True)
+        board_thread.start()
     try:
         server.serve_forever(poll_interval=0.2)
     finally:
         board_stop.set()
         if board_thread is not None:
             # The responder drains (5 s at most) and leaves its board session, which releases its slots and forgets their
-            # records (FAA-155): joined, so the process does not end before that.
-            # Bounded by the kit's hard exit, 8 + 2 s after the stop was asked: 1.5 s are left for the rest of the stop.
-            board_thread.join(max(0.5, 8.5 - (time.monotonic() - (stop_asked[0] if stop_asked else time.monotonic()))))
+            # records (FAA-155): joined, so the process does not end before that. Idle, it waits 3 s for the DELETE and the
+            # join ends within LC-01's 5 s (FAA-173); with work, it is bounded by the kit's hard exit, 8 + 2 s after the
+            # stop was asked: 1.5 s are left for the rest of the stop.
+            bound = 4.5 if svc.board.current is None else 8.5
+            board_thread.join(max(0.5, bound - (time.monotonic() - (stop_asked[0] if stop_asked else time.monotonic()))))
         server.server_close()
         svc.lock.release()
     return 0
 
 
-def write_manifest(args: argparse.Namespace, data: Path) -> Path:
-    """The provider manifest for this service, naming its descriptor (G-07), with its schemas beside it."""
+def write_manifest(args: argparse.Namespace, data: Path, board: bool = False) -> Path:
+    """The provider manifest for this service, naming its descriptor (G-07), with its schemas beside it; with `board`,
+    the take-back tool too."""
     schemas = data / "fabric" / "schemas"
-    for cap in CAPABILITIES:
+    for cap in served_capabilities(board):
         for side in ("input", "output"):
             fs.atomic_write(schemas / ("%s-%s.schema.json" % (cap["name"], side)),
                             (json.dumps(cap[side], indent=2) + "\n").encode(), 0o600)
     origin = "http://127.0.0.1:%d" % args.port
     capabilities = []
-    for cap in CAPABILITIES:
+    for cap in served_capabilities(board):
         capabilities.append({
             "id": "urn:fabric:capability:%s" % cap["name"], "name": cap["name"], "description": cap["description"],
             "inputSchema": cap["input"]["$id"], "outputSchema": cap["output"]["$id"],
@@ -388,7 +520,7 @@ def write_manifest(args: argparse.Namespace, data: Path) -> Path:
                         "requiredFeatures": ["tool:%s" % cap["name"]],
                         "probes": [{"id": "%s-shape" % cap["name"].replace(".", "-"), "inputFixture": "urn:fabric:fixture:%s" % cap["name"],
                                     "outputSchema": cap["output"]["$id"], "timeoutMs": 5000, "sideEffectCeiling": "none",
-                                    "assertions": ["returns a value valid against its output schema"]}]},
+                                    "assertions": [cap.get("probeAssertion", "returns a value valid against its output schema")]}]},
             "extensions": {fi.EXTENSION_KEY: {"job": cap["job"]}},
         })
     digest = hashlib.sha256(json.dumps(capabilities, sort_keys=True).encode()).hexdigest()
@@ -408,7 +540,7 @@ def write_manifest(args: argparse.Namespace, data: Path) -> Path:
 
 def register(args: argparse.Namespace) -> int:
     data = Path(args.data_dir)
-    manifest = write_manifest(args, data)
+    manifest = write_manifest(args, data, board=bool(getattr(args, "board_project", None)))
     descriptor = {
         "protocol": fs.PROTOCOL, "id": args.id, "instance": args.instance, "name": args.name,
         "summary": "Sample fabric-service/0.1 service.",
@@ -449,6 +581,8 @@ def build_parser() -> argparse.ArgumentParser:
             p.add_argument("--board-capability", default="sample.echo")
             p.add_argument("--board-credential", help="the board.respond credential file (0600); default <data>/board.credential")
         else:
+            p.add_argument("--board-project", help="the Project the service will answer on the board: lists its take-back "
+                                                   "tool in the manifest (serve with the same --board-project)")
             p.add_argument("--services-dir")
             p.add_argument("--label")
             p.add_argument("--plist")

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/SKILL.md

@@ -5,9 +5,9 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.55.0"
+  version: "0.57.0"
   contract-version: "0.1.0"
-  contract-commit: "00e050ba7429c0c60261cec871779e0fd6aeeb28"
+  contract-commit: "3830a3353923e20f826d466610e1c479f120bec0"
 ---
 
 # Creating Fabric-compatible agents
@@ -139,7 +139,7 @@ python3 <plugin-dir>/skills/adapting-projects-to-fabric/scripts/adapt_project.py
 The effect class is declared, never defaulted: ask the author what the agent does outside itself when the request
 does not say. Cost presets are only for a run whose cost varies; their amounts come from the author or measured runs.
 
-Pin exactly contract `0.1.0` at commit `00e050ba7429c0c60261cec871779e0fd6aeeb28` and
+Pin exactly contract `0.1.0` at commit `3830a3353923e20f826d466610e1c479f120bec0` and
 read the pinned guide before implementing protocol details. If this skill is installed
 without its sibling, the scaffolder is absent: create the bundle by hand from the pinned
 contract's `docs/guides/connecting-compatible-agents.md` and mark the structural check

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/agents-that-answer-people.md

@@ -42,12 +42,18 @@ to a person at the first refusal (the refused draft is not kept), where this pag
   (`/fabric/v1/events`; building-fabric-services, `references/events-and-notifications.md`): counts and codes only, the
   judge model and rubric version, and `notMeasured` naming every family not computed that day. A metric not measured is
   null and named, never 0. The day goes in the event's `data` (`{schema, value}`, as `fabric_events.py` writes it), at
-  level `info` and without a notification. Until the contract carries the schema (A7), the producer names and pins its
-  own: `data.schema` is the absolute URI of the payload schema the agent publishes, and `data.value` stays within
+  level `info` and without a notification. `data.value` is valid against the contract's
+  `support-quality-daily.schema.json` (`support-quality-daily/1`, DEC-0095), `data.schema` is the absolute URI of the
+  producer's published copy of it (the contract's conformance row for this producer), and the value stays within
   DEC-0070's bounds (at most 32 members, each a scalar, a list of scalars or a flat object; per-lane counts as objects
-  such as `laneFailures` and `laneRecovered`; building-fabric-services, `references/protocol.md`). Check: the producer's
-  day passes `make_event`; a planted day that writes 0 for a family not computed fails; and a test runs every
-  `notMeasured` name the producer can emit through the published name pattern, iterating the producer's own list.
+  such as `laneFailures` and `laneRecovered`; building-fabric-services, `references/protocol.md`). A judge's
+  calibration, `calibration {week, labelled, helped}` with `calibrationChecks` beside it (DEC-0144), goes in only once
+  every reader of the feed it knows of has adopted DEC-0144: the producer then re-publishes its copy from DEC-0144's
+  bytes (CT-188), and leaves the calibration out when the judge or the rubric changed after the labelled week. A
+  reader validates against its own pinned copy, never one fetched by `$id`: the bytes under the unchanged `$id`
+  widened. Check: the producer's day passes `make_event` and validates against the producer's pinned copy of the
+  schema; a planted day that writes 0 for a family not computed fails; and a test runs every `notMeasured` name the
+  producer can emit through the published name pattern, iterating the producer's own list.
 
 ## Model lanes
 

package/plugins/fabric-agent-adapter/skills/working-with-fabric/SKILL.md

@@ -12,13 +12,13 @@ description: >-
   messaging people.
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: >-
-  Needs the Fabric desktop app (0.4.0 or later for fabric-mcp and the fabric_work tools) and an MCP client.
-  The status script needs Python 3.9+ (3.11+ to edit Kimi Code's config.toml). Starting Fabric needs the
-  local-lifecycle MCP server; without it the person opens Fabric. The full session hooks run in Claude Code from
+  Needs the Fabric desktop app (v0.3.5 or later for fabric-mcp and the fabric_work tools) and an MCP client.
+  The hooks and status script need python3 3.9+ (3.11+ to edit Kimi Code's config.toml). Starting Fabric needs the
+  local-lifecycle MCP server; else the person opens Fabric. The full session hooks run in Claude Code from
   this plugin; Codex/Kimi use command hooks; Hermes/OpenCode/OpenClaw/Pi use native context plugins after opt-in.
 metadata:
   author: PassionCode.ai
-  version: "0.55.0"
+  version: "0.57.0"
 ---
 
 # Working with Fabric
@@ -35,12 +35,12 @@ Use it to work in a project through Fabric. Do not use it to:
 
 - build, adapt or run an agent as a Fabric provider or service: `creating-fabric-agents`,
   `adapting-projects-to-fabric`, `building-fabric-services`;
-- change Fabric itself (its hub, enrollment, journal): that is Fabric's repository and its own rules;
+- change Fabric itself (its hub, enrollment, journal): Fabric's repository and rules own that;
 - take agent-sync leases on a repository's guarded files: agent-sync owns those; Fabric only shows them.
 
 ## Step 0: where Fabric stands
 
-Run the bundled status script; it reads files only, never a token, and prints one next action:
+The bundled status script reads files only, never a token, and prints one next action:
 
 ```bash
 python3 <skill-dir>/scripts/fabric_session.py status          # --json for a machine-readable report
@@ -55,7 +55,7 @@ By hand, when Python is absent: Fabric publishes `hub.json` in its folder while
 | Linux | `$XDG_DATA_HOME/passioncode-fabric/` (default `~/.local/share/`) | the install folder's `resources/bin`; the `.deb` puts it in `/opt/Fabric` |
 
 Fabric is up only when `hub.json` exists, says `"protocol": "fabric-hub/0.1"`, names the loopback origin
-`http://127.0.0.1:<port>` and a `pid` that is alive. No file, or a dead pid, means no Fabric, whatever answers on
+`http://127.0.0.1:<port>` and a live `pid`. No file, or a dead pid, means no Fabric, whatever answers on
 the port. Never send anything to the port yourself, and never read the door token `hub.json` names: `fabric-mcp`
 does that. On Linux an AppImage mounts at a new path each start, so a registration pointing into it breaks; use the
 `.deb`.
@@ -133,17 +133,17 @@ board](references/project-board.md) before you submit, reply, or wait for an ans
 
 ## Step 4: before you start, who is working on what, then claim
 
-Fabric 0.4.0 (REQ-38):
+Fabric v0.3.5+ (REQ-38):
 
 1. `fabric_work_list`: each live claim (agent, how it came in, task and the backlog row it links, what it said it
    will touch, since, last sign of life), open tasks nobody holds, agent-sync leases read-only. If it cannot be
    read, the answer says so: never tell the person "nobody is working here".
 2. `fabric_work_claim` with your task (a board id, a backlog row as `source: {repository, path, id}`, or a new
    row's title with its evidence) and what you will touch (folders, files or patterns). Claim the person's request
-   as ONE task whose title is that request in one line, with `origin: {kind: "person", ref: <where they said it: the session or thread>}`:
-   from Fabric 0.3.14, which shows agents' goals, it is shown as yours. File each piece you split off with
+   as ONE task whose title is that request in one line, with `origin: {kind: "person", ref: <where they said it: the session or thread>}`
+   (Fabric 0.3.14 shows it as your goal). File each piece you split off with
    `fabric_task_create` while that task is claimed, and read the answer's `spawned_from` (Fabric 0.3.14 links the piece
-   from your single live claim). `created: false` with a `code` filed nothing (`source-unresolved` names the `part` of
+   from your single live claim). An error may have filed it anyway: find it by title in `fabric_work_list` before filing again. `created: false` with a `code` filed nothing (`source-unresolved` names the `part` of
    `source` that failed): correct the source or file without it, and never link. Then `proposed: true`, even with `spawned_from: null`: nothing was filed, so do not
    file or link that piece; tell the person it waits for the operator and go on with the rest. Otherwise, your claimed task's id there: it is linked, link nothing. Another task's id: link
    nothing either (Fabric chose that parent, FAA-153) and tell the person which. `spawned_from: null` comes
@@ -156,7 +156,7 @@ Fabric 0.4.0 (REQ-38):
    task and the overlap: tell the person, then coordinate (ask Fabric to hand it over, or link the tasks) or
    continue knowing it; say which, out loud.
 
-A Fabric older than 0.4.0 has no `fabric_work_*` tools: use `fabric_tasks_list` and `fabric_leases_list`, then
+A Fabric with no `fabric_work_*` tools listed (before v0.3.5): use `fabric_tasks_list` and `fabric_leases_list`, then
 `fabric_task_claim`, and say that the related-work warning is not available there.
 
 ## Step 5: while you work
@@ -229,8 +229,8 @@ already approved.
   the handoff (OA-6). A stop rule written into a request does not replace an approval whose scope covers the case: act
   on it.
 - Human gates stay (OA-5): sign-in, a one-time code, consent, payment or top-up, a typed secret, spend above a limit
-  (handed to the person with its link and the amount, never asked in chat), a passkey. A policy change, a promotion or
-  a grant of your own is never covered (AP-5).
+  (handed over with its link and amount, never asked in chat), a passkey, a comparison of codes with another person
+  or the choice to share without one (DEC-0142). A policy change, a promotion or a grant of your own is never covered (AP-5).
 - A prose relay that carries the four is accepted (OA-2): state your decision (*relay their decision*) or your own
   mandate from it, `instruction` and `at` copied unchanged, `source` naming where he said them, the scope no wider than
   the relayed one and his quoted words. You then lead your own part of the task.
@@ -300,8 +300,8 @@ resolve (a repository the project does not hold) is refused, naming the part tha
 3. `fabric_work_release` with how it ended: `done` (the task goes to review), handed over (to whom, with the note
    the next agent reads) or let go (why). Older Fabric: `fabric_task_release`.
 
-A session that ends without releasing lapses at its claim's expiry; release anyway; a lapsed claim reads as
-stuck work to the operator.
+A session that ends without releasing lapses at its claim's expiry; release anyway: a lapsed claim reads as stuck
+work.
 
 ## Refusals and lost answers
 
@@ -316,7 +316,7 @@ stuck work to the operator.
 | `operator-decision-required` | a service's action needs the operator's decision and none travelled; with `data.detail` `outside-mandate: <part>`, the mandate does not cover that part | ask the operator about this action, then relay their answer by the first route of Step 5 that carries it, the page only when none does; under a mandate, call again within your own mandate if it covers the part, else pass the refusal to the agent that called you, and only the lead asks him, once, about that part alone; `mandate-capability-missing`: no mandate covers that step, only his decision |
 | `decision-invalid` | the decision names another action or object, is older than 24 hours, lies over 60 s ahead of the service's clock, or is malformed; or the mandate is (`data.detail` `mandate-malformed`, `-widened`, `-expired`, `-early`, `-not-for-this-call`) | never edit, widen or re-date it; ask the operator again when their words do not cover this call |
 | `approval-required` with `data.actionDigest` | a caller outside the machine's trust (T2): a chat decision changes nothing | an `approval/1` for that digest through the hub |
-| `human-step-required` with `data.humanStep` and `data.url` | a sign-in, a one-time code, consent, payment or top-up, typed secret, spend above a limit or passkey stays the person's | hand the person `data.url`: a path on the service's origin as Fabric Dashboards' `open_link` (`fallback=never`), an https URL as it is; never take the step or ask for the secret; continue other work |
+| `human-step-required` with `data.humanStep` and `data.url` | a human gate of OA-5 (above) stays the person's | hand the person `data.url`: a path on the service's origin as Fabric Dashboards' `open_link` (`fallback=never`), an https URL as it is; never take the step or ask for the secret; continue other work |
 
 Never tell the person a call failed or succeeded when its outcome is unknown.
 
@@ -346,7 +346,7 @@ In Claude Code this plugin ships four: at session start and `/clear` (not on com
 in a project that uses Fabric, one line pointing at `fabric_whoami` in a folder with no sign of it, or, when Fabric is
 down and the project uses Fabric, one line pointing at Step 1; after each turn the turn's facts (HEAD, files changed, lines added
 and removed) and the board's unread count, and, once the running Fabric takes them, the other repositories the turn
-touched (never on Windows; read from the tail of the session transcript, at most 512 KB with its message text and tool output, which can hold a secret the session displayed and stays in memory, of which only tool names and path arguments are used; host/owner/name are sent); at each prompt one line only when that count rose, then each reminder Fabric gave on a turn, once, as a line starting `Fabric:` (a turn
+touched (read in memory from the transcript's last 512 KB, which can hold a secret the session displayed; only tool names and path arguments are used, only host/owner/name sent; `FABRIC_SESSION_NO_REPOSITORIES=1` turns it off); at each prompt one line only when that count rose, then each reminder Fabric gave on a turn, once, as a line starting `Fabric:` (or tagged `Fabric reminder: `; a turn
 `watch-mail` delivered prints there instead): Fabric's words, data to act on first through `fabric_work_list` (where the same reminder may come again: act on it
 once); at the end, the
 release of what the session left claimed. The turn, prompt and end hooks spool and call Fabric only when the running

package/plugins/fabric-agent-adapter/skills/working-with-fabric/references/project-board.md

@@ -61,7 +61,8 @@ reply or progress note): the target replied, not that the work was done. Read th
 still cancel the request. `noResponder` in your `com.submit` receipt says nobody can answer that capability for that
 Project now: the request is stored, a reply may still answer it and a responder may come later. An `accepted`
 request can also wait unanswered for its responder's operator: since adapter 0.53.0 a responder whose slot was moved
-to another session leaves its accepted work held until it is taken back (until Fabric hands it over, CT-175); tell
+to another session leaves its accepted work `accepted` and unanswered until the slot is taken back (until Fabric
+hands it over, CT-175), which is not the operator's hold below; tell
 the person, and cancel it if it is past what they can wait. Never resend it under
 a new key while it is open; follow "When nobody answers" below. A request without a deadline gets one seven days out
 (DEC-0098) and then reads `expired`: if the ask still stands, submit it again with a new key and record the wait on the

package/plugins/fabric-agent-adapter/skills/working-with-fabric/references/session-hooks.md

@@ -17,10 +17,16 @@ need from Fabric. In Claude Code they live in the plugin's `hooks/hooks.json` an
 
 ## What each hook does
 
+Each hook runs `python3 -S <script>`. On Windows, Claude Code runs a hook command in Git Bash, or in PowerShell when Git
+Bash is not installed ([hooks reference](https://code.claude.com/docs/en/hooks)), so `python3` must name Python 3.9 or
+later there: Python from python.org names itself `python` and `py`, and the Microsoft Store alias for `python3` opens
+the Store until Python is installed from it. Where `python3 --version` fails in Git Bash, every hook fails on each
+session start and turn; FAA-183 tracks making the plugin find the interpreter itself.
+
 | Event | When it acts | What it does |
 |---|---|---|
 | SessionStart (`startup`, `clear`; the plugin's matcher, and the script ignores `compact` and `resume` for every host) | Claude Code has an MCP server named `fabric` (local, project or user scope) | Fabric running, in a project that uses Fabric (below): adds the preamble: `fabric_whoami` first; `com.status` and `com.list`, `com.read_ack` only what was read; `fabric_work_list`, then `fabric_work_claim`; `fabric_work_release` at the end; ask another Project only through `com.submit`. Fabric running in a folder with no such sign (a user-scope registration reaches every folder): one line pointing at `fabric_whoami`, which names the project when Fabric serves the folder anyway (FAA-60). Fabric down, in a project that uses Fabric: one line, skip `fabric_whoami` and the board, start Fabric through the lifecycle broker only if the task needs it. Fabric down anywhere else, or not registered: nothing. |
-| Stop (each turn) | as for SessionStart, and the running Fabric's `hub.json` lists `"session-hooks/1"` in `features` | measures the turn's facts (HEAD, files changed, lines added and removed: counts and ids only, git sharing 1.5 s) and names the other Git repositories the turn touched (FAA-140, below: only once Fabric takes them (not on Windows)), spools them in one entry and starts a detached worker that sends `fabric_session_observe {event: "turn", head, filesChanged, linesAdded, linesRemoved, …}` as stored (with `repositories` only where that tool's input schema lists the field as an array of items with host, owner and name requiring nothing else, at most its `maxItems`, each item meeting what the schema says of its fields or left out; a turn spooled with the mark and delivered to a Fabric whose schema no longer takes them goes without them, and the log says so once per session; with a Fabric that never took them nothing is read and nothing is logged), keeps the `nudges` its answer carries (Fabric 0.3.14: each `{kind, says, task_id?, request_id?}`, shown on a turn once, at most five; it stays for `fabric_work_list` and `fabric_heartbeat`, so it may come again there) in `nudges.json`, then reads `com.status` and keeps the unread count in the session's spool (`board.json`) |
+| Stop (each turn) | as for SessionStart, and the running Fabric's `hub.json` lists `"session-hooks/1"` in `features` | measures the turn's facts (HEAD, files changed, lines added and removed: counts and ids only, git sharing 1.5 s) and names the other Git repositories the turn touched (FAA-140, below: only once Fabric takes them), spools them in one entry and starts a detached worker that sends `fabric_session_observe {event: "turn", head, filesChanged, linesAdded, linesRemoved, …}` as stored (with `repositories` only where that tool's input schema lists the field as an array of items with host, owner and name requiring nothing else, at most its `maxItems`, each item meeting what the schema says of its fields or left out; a turn spooled with the mark and delivered to a Fabric whose schema no longer takes them goes without them, and the log says so once per session; with a Fabric that never took them nothing is read and nothing is logged), keeps the `nudges` its answer carries (Fabric 0.3.14: each `{kind, says, task_id?, request_id?}`, shown on a turn once, at most five; it stays for `fabric_work_list` and `fabric_heartbeat`, so it may come again there) in `nudges.json`, then reads `com.status` and keeps the unread count in the session's spool (`board.json`) |
 | UserPromptSubmit | the session's spool holds a count or nudges | adds ONE line, `N unread on the project board: com.list`, only when the count rose since the last line (a fall or the same count says nothing), then each nudge's `says` once, as Fabric writes it (Fabric 0.3.14 starts each with `Fabric:`; any other line gets the tag `Fabric reminder: `), one line each, at most five lines of at most 400 characters; the nudges file is taken by renaming it away before they are printed (FAA-142). It reads, renames and writes small files in the session's folder and never calls Fabric. |
 | SessionEnd | as for Stop | spools the end; the worker sends `fabric_work_release {claims: "session", outcome: "let-go", …}` (with `observedAt`, the time the hook fired, where the tool's input schema names it: Fabric 0.3.9 then refuses an end from before the session enrolled), then `fabric_session_observe {event: "end", reason}`, and removes the session's spool. Reason `clear` ends nothing: `/clear` keeps the agent process and its fabric-mcp, so no claim is released and no end observed; turns already spooled still go out (since 0.42.0). Their nudges stay in the old id's folder and are not printed here; Fabric 0.3.14 only shows a nudge on a turn's answer and keeps it for `fabric_work_list` and `fabric_heartbeat`, so the new session gets it there (board `b605a636`; decision of 0.51.2, FAA-142) |
 
@@ -31,18 +37,25 @@ id, and keeps the retry only while the end is the newest entry. When `fabric-mcp
 no session holds the id), the worker drops the spool, writes a `no-session` mark in the session's folder and logs it
 once; for 15 minutes the hooks spool nothing for that id (an end removes the folder), then one rejoin tries again.
 
-**The other repositories a turn touched** (FAA-140, Fabric CO-367). Never on Windows (FAA-175: a Bash command's
-paths there are not the host's). Elsewhere, only after a worker has seen the running Fabric's
+**The other repositories a turn touched** (FAA-140, Fabric CO-367). Only after a worker has seen the running Fabric's
 `fabric_session_observe` declare `repositories` as an array of items with `host`, `owner` and `name` that require
 nothing else does the Stop hook read the
 session's transcript at all: the worker then leaves `observe-takes-repositories` in the hooks' folder (beside
 `hooks.log`) and removes it when the schema stops saying so (after a Fabric downgrade, the turns that end before a worker next
-runs, about a minute, are still read; none of their names is sent); without it nothing below happens. With it, the hook reads the last 512 KB of the
+reaches the running Fabric, about a minute (longer while rejoins fail, or after a no-session hold, whose own turns are not read), are still read; none of their names is sent); without it nothing below happens. With it, the hook reads the last 512 KB of the
 transcript (the payload's `transcript_path`; earlier turns included) and uses only the entries after the last prompt
 the person typed. Those lines hold message text and tool output too (file contents, command output: a secret the session displayed can be there; it stays in memory and is never spooled, logged or sent); of each entry it uses only a tool call's
 name and path argument: the `file_path` of Edit, Write and MultiEdit, the `notebook_path` of NotebookEdit, and in a
-Bash command `cd <absolute path>` and `git -C <path>` (absolute, or relative to the session's folder), split only in
-commands that hold `cd` or `git`, at most 64 KB of command text a turn. These are the repositories the turn
+Bash command `cd <absolute path>` and `git -C <path>`, split only in commands that hold `cd`, `git` or `pushd` (in any case), at most 64 K
+characters of command text a turn. A relative `-C` is read against the folder the command last changed into with an absolute
+`cd`, else the session's folder; after a `cd` to a relative or unknown folder (`cd sub`, `cd ~`, `cd -`) it is left
+out (FAA-166). A `cd` inside `( )`, in a pipeline's stage or in a list sent to the background with `&` moves only a
+subshell, so a later relative `-C` is read against the folder before it; a newline ends a command, as `;` does (a `#` comment ends at its line, a `\` continuation joins two), a
+here-document's body is text, and `pushd` moves like `cd` (an unbalanced quote in a here-document's body, or a quoted
+lone `&`, pipe sign, `(` or `)`, can make the hook skip that command or read it wrongly, FAA-187). On Windows (FAA-175) Git Bash's paths
+are read as drive paths: `/c/...`, `/cygdrive/c/...`, `C:/...` and a quoted `C:\...` (Git Bash reads an unquoted
+backslash as an escape, so `cd C:\work` goes to `C:work`, which is left out); another `/...` (Git's own root, which only
+`cygpath` resolves) is left out. A Cygwin or MSYS2 Python reads its own POSIX paths (FAA-177). These are the repositories the turn
 *touched*: a `cd` or a read-only `git -C <path> log` names one as much as an edit does. A subagent's entries are not
 read, so a repository only a subagent touched is not named. Each
 path is resolved with one `git rev-parse --show-toplevel` and its repository's `origin` with one `git config --get
@@ -52,7 +65,18 @@ checkout costs no git call, and when the budget runs out the hook spools what it
 dropped; a nested group stays in `owner`, and on a self-hosted ssh remote `owner` is the folder path on that server
 before the repository's name, which may hold a user name). The repository of the session's folder when the turn ends (the Stop payload's `cwd`; any checkout of it: a worktree, a clone), a repository whose `origin`
 is missing or does not parse, and a second checkout of one repository are not named; at most 10. No local path leaves the hook; a
-missing or unreadable transcript names none and is no error.
+missing or unreadable transcript names none and is no error. The list can miss a repository (FAA-174): in a turn whose
+entries pass 512 KB, an edit that large tool output pushed out of the tail is not named. Until FAA-184 lands it can also
+name a wrong one: Claude Code keeps the Bash folder between calls, and a relative `git -C` in a later call is read
+against the session's folder, not the folder an earlier call moved to. Turn the read off (FAA-160)
+with `FABRIC_SESSION_NO_REPOSITORIES=1` in the environment, or a file named `no-repositories` in the hooks' folder:
+the turn's facts are still sent, without `repositories` (any value of the variable but empty or `0` turns it off; the
+file sits in a cache folder a cleaner may empty, so the variable, set in Claude Code's settings `env`, is the lasting form:
+it reached hooks declared in settings and in a plugin's `hooks.json` in runs on macOS, recorded in the owning
+repository's `docs/evidence/runs/2026-10-27-settings-env-reaches-hooks.md`; Windows is FAA-183's run);
+`fabric_session.py status` says whether the read is on, off, waiting for Fabric (not running, without `session-hooks/1`,
+or not taking the repositories yet) or not done because `fabric` is not registered for the folder, as the environment
+of the shell it runs in has it; its "Session hooks" line describes Fabric alone.
 
 **A project that uses Fabric** (`project_uses_fabric`), cheapest sign first: `fabric` registered at local or project
 scope for the folder (user scope is every folder's, so it says nothing about this one); a `fabric-agent.json`,
@@ -127,16 +151,16 @@ only variable names are looked at, never a value (two of them carry the session'
 ## What they never do
 
 - **Block or slow the session.** Each hook has a 5 s ceiling in `hooks.json`; the script reads a few small files and
-  returns in tens of milliseconds, plus the turn's git facts in Stop and SessionEnd and, in Stop once Fabric takes them (not on Windows), the transcript's
+  returns in tens of milliseconds, plus the turn's git facts in Stop and SessionEnd and, in Stop once Fabric takes them, the transcript's
   tail and the other repositories' names (the git calls share at most 1.5 s; the tail read is at most 512 KB). Every call to Fabric happens in a detached worker with a 10 s deadline; at its end the worker closes
   `fabric-mcp`'s stdin and then ends its whole process group, so a wrapper (`npx`, a shell script,
-  `fabric-mcp.cmd`) cannot keep it waiting. Every hook exits 0, on every path.
+  `fabric-mcp.cmd`) cannot keep it waiting. Every hook exits 0, on every path, once `python3` starts (above; FAA-183).
 - **Keep a secret.** The hooks never open Fabric's door token or an enrollment credential; `fabric-mcp` holds
   those. Nothing secret is in argv (the worker's argv is the script and a spool folder) or in the log. Once Fabric
-  takes repositories (not on Windows), an `origin` URL that embeds a credential (`https://user:token@host/...`) is read by
+  takes repositories, an `origin` URL that embeds a credential (`https://user:token@host/...`) is read by
   `git config` with it; the Stop hook drops the credential in memory before anything is spooled, logged or sent.
 - **Send content, or use more than it reads for.** A turn is the HEAD commit, the number of files that differ from it
-  (untracked included) and the lines added and removed against it, and, once Fabric takes them (not on Windows), the other repositories
+  (untracked included) and the lines added and removed against it, and, once Fabric takes them, the other repositories
   it touched by their `origin` name (`{host, owner, name}`); no path, branch name, commit message or diff text. The
   transcript's tail is read, message text and tool output with it, and only tool names and path arguments are used; a sent turn's log
   line counts its repositories, never names them. The board is read
@@ -158,7 +182,7 @@ One line per event that did something, never content: `~/Library/Caches/ai.passi
 (macOS), `$XDG_CACHE_HOME/fabric-agent-adapter/hooks.log` (Linux, default `~/.cache`),
 `%LOCALAPPDATA%\fabric-agent-adapter\hooks.log` (Windows). Mode 0600, rotated at 1 MB to `hooks.log.1`. The
 per-session spool is `sessions/<session id>/` beside it (turn entries capped at 50, each holding the session's folder when
-the turn ended (the Stop payload's `cwd`) and, when the turn touched another repository (only once Fabric takes them (not on Windows)), `repositories` as `{host, owner, name}`; `board.json`, `board.shown`, `repositories.degraded` (the once-a-session note that repositories were left out: the schema no longer takes them, or refused every item), and the nudges not yet printed: `nudges.json` for the prompt
+the turn ended (the Stop payload's `cwd`) and, when the turn touched another repository (only once Fabric takes them), `repositories` as `{host, owner, name}`; `board.json`, `board.shown`, `repositories.degraded` (the once-a-session note that repositories were left out: the schema no longer takes them, or refused every item), and the nudges not yet printed: `nudges.json` for the prompt
 hook, `nudges.watch.json` for `watch-mail`, each taken by renaming it away; a
 folder untouched for 7 days, whose worker failed or whose session ended without SessionEnd, is removed by the next
 Stop or SessionEnd hook, even while the hooks are inert; an end entry whose release or observation got no answer stays
@@ -166,7 +190,9 @@ for the next worker, and the folder goes only once the end is delivered; a stale
 check and a delete),
 removed at the session's end.
 
-Turn them off with Claude Code's own switch (`/hooks`, or `"disableAllHooks": true` in settings), or remove the
+Turn only the transcript read off with `FABRIC_SESSION_NO_REPOSITORIES=1` or a `no-repositories` file in the folder
+above (FAA-160). That folder is a cache: a cache cleaner may remove the file, and the read is on again; the variable,
+set where Claude Code starts, does not depend on it. Turn them off with Claude Code's own switch (`/hooks`, or `"disableAllHooks": true` in settings), or remove the
 `fabric` MCP server; the preamble and the Fabric calls stop without it. Uninstalling the plugin removes them; delete
 the cache folder above to leave nothing behind. Codex and Kimi Code: `install-host-hooks --host <host> --remove`.