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

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/fabric_secrets.py

@@ -2,12 +2,15 @@
 """The contract's one credential detector (Fabric Agent Contract DEC-0044, `src/secret-shape.ts` at the pin): a name
 that can only carry a credential, a value shaped like one, a launch argument that carries one, and a URL that does
 (LC-21). A port held to the contract's own answers by test/fixtures/contract/profile-vectors.json. Standard library
-only. The dashboard kit's fabric-button.js carries its own copy of the name and value checks (FL-4)."""
+only. The dashboard kit's fabric-button.js carries its own copy of the name and value checks (FL-4).
+
+It reads as the contract's ECMAScript does (FAA-136): ECMAScript's whitespace (Python's `\\s` also takes U+0085 and
+U+001C to U+001F, and not U+FEFF), `.` stopping at every line terminator, ASCII case folding, an ASCII word boundary."""
 
 from __future__ import annotations
 
 import re
-from typing import Dict, List
+from typing import Dict, List, Tuple
 import urllib.parse
 
 CREDENTIAL_WORDS = (
@@ -22,20 +25,28 @@ CREDENTIAL_PAIRS: Dict[str, tuple] = {
     "session": ("token", "id"),
     "code": ("login", "auth", "access", "session"),
 }
+#: ECMAScript's \s, as a character class body.
+JS_SPACE = "\t\n\x0b\x0c\r \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
+_NOT_LINE_END = "[^\n\r\u2028\u2029]"  # ECMAScript's `.` without the s flag
 JWT_SHAPE = re.compile(r"eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*")
-SECRET_VALUE = re.compile(r"(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})",
-                          re.IGNORECASE | re.DOTALL)
+SECRET_VALUE = re.compile(r"(^bearer[%s]%s+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}"
+                          r"|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})" % (JS_SPACE, _NOT_LINE_END), re.IGNORECASE | re.ASCII)
 _LONG_RUN = re.compile(r"[A-Za-z0-9+/=_-]{40,}")
-_BEARER_INSIDE = re.compile(r"\bbearer\s+(?=[A-Za-z0-9._~+/-]*\d)[A-Za-z0-9._~+/-]{12,}=*", re.IGNORECASE)
-_PATH_LIKE = re.compile(r"^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*://)", re.IGNORECASE)
+_BEARER_INSIDE = re.compile(r"(?<![A-Za-z0-9_])bearer[%s]+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{12,}=*" % JS_SPACE,
+                            re.IGNORECASE | re.ASCII)
+_PATH_LIKE = re.compile(r"^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*://)", re.IGNORECASE | re.ASCII)
+_WORD_SPLIT = re.compile("[%s._-]+" % JS_SPACE)
+_ARGUMENT_SPLIT = re.compile("[%s=]" % JS_SPACE)
 _SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+#: WHATWG's special schemes that carry an authority with user information (file has none).
+_SPECIAL = ("ftp", "http", "https", "ws", "wss")
 
 
 def name_words(name: str) -> List[str]:
     """A name's words: split at `.`, `_`, `-` and camelCase humps, lowercased (`APIKey` is `api key`)."""
     spaced = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", name)
     spaced = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1 \2", spaced)
-    return [w.lower() for w in re.split(r"[\s._-]+", spaced) if w]
+    return [w.lower() for w in _WORD_SPLIT.split(spaced) if w]
 
 
 def _with_singulars(words: List[str]) -> List[str]:
@@ -73,7 +84,7 @@ def secret_argument(value: str) -> bool:
     so a folder path holding a session id is not taken for a key."""
     if JWT_SHAPE.search(value) or SECRET_VALUE.search(value) or _BEARER_INSIDE.search(value):
         return True
-    for piece in re.split(r"[\s=]", value):
+    for piece in _ARGUMENT_SPLIT.split(value):
         if _path_like(piece):
             if any(_long_secret(part) for part in re.split(r"[\\/]", piece)):
                 return True
@@ -93,7 +104,8 @@ def _decode_keeping_plus(raw: str) -> str:
 
 
 def _form_name(text: str) -> str:
-    pairs = urllib.parse.parse_qsl(text, keep_blank_values=True)
+    # URLSearchParams drops one leading `?` from the text it is given (0.56.0 unit r7).
+    pairs = urllib.parse.parse_qsl(text[1:] if text.startswith("?") else text, keep_blank_values=True)
     return pairs[0][0] if pairs else ""
 
 
@@ -109,23 +121,66 @@ def raw_values(query: str) -> Dict[str, List[str]]:
     return values
 
 
+#: The C0 controls and space, U+0000 to U+0020: what WHATWG URL parsing trims from a URL's ends.
+_C0_OR_SPACE = "".join(map(chr, range(0x21)))
+
+
+_LONE_SURROGATE = re.compile("[\ud800-\udfff]")
+
+
+def _percent_encode(text: str, also: str) -> str:
+    """WHATWG's percent-encoding of a query or a fragment: every C0 control, space, `"`, `<`, `>`, every code point
+    above U+007E and the characters in `also`, as UTF-8 %XX (a lone surrogate as U+FFFD, as a USVString reads it).
+    `new URL` hands the contract's secretUrl the text in this form, so a malformed escape left in it is read the same
+    way by both ports (0.56.0 unit r8)."""
+    out = []
+    for char in _LONE_SURROGATE.sub("\ufffd", text):
+        if ord(char) <= 0x20 or ord(char) > 0x7E or char in '"<>' or char in also:
+            out.append("".join("%%%02X" % byte for byte in char.encode("utf-8")))
+        else:
+            out.append(char)
+    return "".join(out)
+
+
+def _url_parts(value: str) -> Tuple[str, str, str]:
+    """The password, query and fragment of an absolute URL as WHATWG URL parsing splits them, read by hand: urlsplit
+    refuses a `[` or `]` outside an IPv6 host (`https://u:p[w@h/`), where `new URL` reads the password (0.56.0 unit
+    r7). The fragment starts at the first `#`, the query at the first `?` before it. A special scheme's authority starts
+    after every slash or backslash that follows `scheme:` (the special authority ignore slashes state) and ends at the
+    next slash, backslash, `?` or `#`, so `https:u:p@h` and `https:\\u:p@h` carry the password p; any other scheme
+    has an authority only after `//`, and `file` has no user information. The user information ends at the authority's
+    last `@`, and the password follows its first `:`. A host `new URL` would refuse is not checked: such a URL is read
+    for its password and parameters all the same, the safe direction for a detector."""
+    scheme, _, rest = value.partition(":")
+    rest, _, fragment = rest.partition("#")
+    rest, _, query = rest.partition("?")
+    lowered = scheme.lower()
+    if lowered in _SPECIAL:
+        authority = rest.replace("\\", "/").lstrip("/").partition("/")[0]
+    elif lowered != "file" and rest.startswith("//"):
+        authority = rest[2:].partition("/")[0]
+    else:
+        authority = ""
+    userinfo, at, _ = authority.rpartition("@")
+    return ((userinfo.partition(":")[2] if at else ""), _percent_encode(query, "'" if lowered in _SPECIAL or lowered == "file" else ""),  # file is special too
+            _percent_encode(fragment, "`"))
+
+
 def secret_url(value: str) -> bool:
     """Whether a URL an MCP entry or a launch names carries a credential (LC-21): anything secret_argument finds, a
     password in its user information, or a query or fragment parameter whose name can only carry a credential and has
     a value, or whose value is shaped like one. A string that is not an absolute URL is checked as an argument only."""
     if secret_argument(value):
         return True
-    if not _SCHEME.match(value.strip()):
+    # What WHATWG URL parsing does first: trim C0 controls and space from the ends (never other Unicode spaces, which it
+    # refuses), then remove every tab, CR and LF.
+    value = re.sub(r"[\t\n\r]", "", value.strip(_C0_OR_SPACE))
+    if not _SCHEME.match(value):
         return False  # not an absolute URL (WHATWG URL parsing refuses it)
-    try:
-        parts = urllib.parse.urlsplit(value.strip())
-    except ValueError:
-        return False
-    if not parts.scheme:
-        return False
-    if parts.password:
+    password, query, fragment = _url_parts(value)
+    if password:
         return True
-    for part in (parts.query, parts.fragment):
+    for part in (query, fragment):
         for name, raws in raw_values(part).items():
             if any((raw != "" and credential_name(name)) or secret_value(raw) for raw in raws):
                 return True

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -14,10 +14,10 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits (Node.js 22+ for a Linux service's instance lock); the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.55.0"
+  version: "0.57.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "00e050ba7429c0c60261cec871779e0fd6aeeb28"
+  extension-commit: "3830a3353923e20f826d466610e1c479f120bec0"
 ---
 
 # Building Fabric services
@@ -104,8 +104,8 @@ responder in its own process: [`scripts/fabric_hub.py`](scripts/fabric_hub.py) f
 every step and stops on `fenced`, `lease_expired` or `authority_changed` (Node: `fabric-hub.mjs`, `fabric-board.mjs`).
 The request body is data behind the service's own input gate. From 0.53.0 a slot the operator moved to another
 session stays moved until `take_back` (`takeBack`): give it an operator action with its tool and gate `relayed`, or it
-stays moved for good (until Fabric's hub forwards decisions, CT-125, the operator reaches it through the service's page
-or its elicitation). Read [the board reference](references/board.md).
+stays moved for good (the operator reaches it through an agent that relays their decision in `_meta`, the service's
+page or its elicitation; Claude Code and Codex wait for CT-125's forwarding). Read [the board reference](references/board.md).
 
 ## Step 2: the non-negotiables
 
@@ -260,8 +260,9 @@ or `human` with its `humanStep`) and declared with `build_well_known(actions=ser
 `extensions/actions/0.1`. A `relayed` action called by the operator's own agent with their decision in
 `_meta.decision` is the operator's act: never answer it "operator session required" or send them to the page.
 A service adopts the relayed gate once Fabric's hub forwards decisions (CT-125), as the contract says; until then its tools
-answer as today, except the board responder's take-back action, declared `relayed` now and reached through the
-page or elicitation until CT-125 ([board.md](references/board.md)). Read the interop reference's *Actions* section for when to adopt, the gate, its hooks and its
+answer as today, except the board responder's take-back action, declared `relayed` now: an agent whose client sets
+`_meta` calls it with the operator's decision; Claude Code and Codex reach it through the page until CT-125
+([board.md](references/board.md); the reference service's `board.take-back`). Read the interop reference's *Actions* section for when to adopt, the gate, its hooks and its
 refusals.
 
 **Say what the agent uses** (`fabric-connections/0.1`, DEC-0096) so Fabric Dashboards draws its chain: the other

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/board.md

@@ -42,7 +42,9 @@ operator gives in Fabric (Agents & access): callee `fabric`, capability `board.r
 
 The responder runs inside the service process, started after the instance lock like every other piece of state
 (SKILL.md, Step 3). [`sample_service.py`](../scripts/sample_service.py) does it behind `serve --board-project <uuid>`,
-off by default:
+off by default (register it with the same `--board-project`, so its manifest lists the take-back tool below; a serve
+whose board mode differs from the registered manifest at its start logs `service.manifest.mismatch` and leaves the
+manifest as it is):
 
 ```python
 import fabric_board as fbd, fabric_hub as fhb
@@ -53,12 +55,13 @@ responder = fbd.Responder(
     handler=render, admit=gate, observe=look_on_disk, emit=log.append, service="example-agent")
 board = threading.Thread(target=responder.run, args=(stop_event, 5.0), daemon=True)  # SIGTERM: set stop_event
 board.start()
-# ... at stop, after stop_event is set: wait for it to leave its board session (a clean leave forgets its slot
-# records, FAA-155), bounded inside the kit's hard exit, as scripts/sample_service.py does
+# ... at stop, after stop_event is set: wait for it to leave its board session (a clean leave forgets the slot
+# records it confirmed, FAA-155), bounded inside the kit's hard exit, as scripts/sample_service.py does
 board.join(timeout)
 ```
 
-Node: `new Responder({...same names in camelCase})`, then `responder.run({ signal, drain })`. A service that lists
+Node: `new Responder({...same names in camelCase})`, then `const running = responder.run({ signal, drain })`; at stop,
+abort the signal and `await running`, bounded inside the hard exit (the run leaves its board session before it settles). A service that lists
 `fabric-project-comms/0.1` in its well-known `protocols` (DEC-0067: only once its hosts are pinned at or after it)
 declares that it answers board requests; the probe checks that declaration.
 
@@ -144,6 +147,28 @@ answers `not_available` or `capacity_exceeded`, which do not say whether the rep
 in line and the next tick asks again, and a restart asks with the same old fence. A request leaves the resume queue only
 once it has resumed: when the `com.complete` that sends a known outcome loses its answer, the next tick sends the same
 key again in the same session (FAA-86). `shutdown()` drains, then leaves the session (its DELETE releases the slot).
+An idle responder waits 3 s at most for that DELETE (`IDLE_LEAVE_SECONDS`), so an idle stop ends within the org's 5 s
+(LC-01, FAA-173); one with work waits up to the session's 15 s client timeout. A board call already in flight when the
+stop comes (a poll against a slow hub) runs first; when the service's bounded join ends before the DELETE is sent, the
+slot lapses on the board's clock as before. The slot records are forgotten only after
+a DELETE Fabric answered with a 2xx (a 404, the session already gone, keeps them: a move made before it ended is read at the next `com.status`), also when a session is dropped on a live board (FAA-163): an unanswered one keeps
+them, and the slot lapses in 60 s.
+
+**One capability at a time (FAA-163).** At connect (and every reconnect) the responder starts with no slot. Each
+capability's enroll or replace is settled on its own: a refusal of that capability (`capacity_exceeded`,
+`invalid_arguments`, any code that is not about the board session) leaves it `retry`, asked again alone after 15 s,
+30 s, doubling to 15 minutes, with one `board.slot.refused` event (warning; said again if it is refused again after
+the slot was held); its accepted work waits `lapsed` and goes back
+by a transfer once the slot is held. The capabilities after it are recovered as before. A refusal of the board session
+(`unreachable`, `session-ended`, `not_available`, `not_authorized` and the other codes in `SESSION_CODES`) leaves the
+rest `retry` too, says no `board.slot.refused`, and goes to the responder's fault, which says it by code:
+`board.access.needed` for `not_authorized`, `authority_changed` and `credential` (the session is left),
+`board.blocked` for a defect (`no-epoch`, `schema-unsupported`, `checkpoint`, `receipt-shape`,
+`idempotency_conflict`), and `board.down` for the rest: `unreachable` keeps the session while a held slot's lease runs
+(so a lost enroll of one capability is asked again at its next retry), `not_available` keeps it except at connect or recovery with no slot held,
+and `session-ended`, `not-running` and the other hub codes drop it (as a fault during connect or recovery does) and
+reconnect. A slot whose lease lapsed (`lease_expired`) holds
+no lease for that decision.
 
 ## When the operator holds work (DEC-0079)
 
@@ -178,9 +203,16 @@ held and not transferred). The responder keeps that move instead of undoing it:
   {project, generation, moved?, asking?}}`). The record is written when a receipt's generation changes and before an
   enroll or a replace that can change it; a live holder's renew (about every 20 s) cannot, and writes nothing. At a
   clean leave (the service stopped; the session's DELETE released its slots) the record of a slot with no request left
-  in the checkpoint and not moved is forgotten (a moved slot's record stays, so a clean stop never undoes a move): the slot is free, and whoever takes it next is no move. A file without the record
-  reads as before; a kit before 0.53.0 reads the file, ignores the record and drops it at its first checkpoint write. So a service stopped cleanly with no request left in its checkpoint, rolled back to 0.52 and up again starts as on a first
-  start. After a crash the record stays: if 0.52 then ran, enrolled the slot and
+  in the checkpoint and not moved is forgotten when this session confirmed its generation (held it, paused under the
+  operator's hold included, or read it unmoved in `com.status`) and no fenced call has put in doubt since: the slot is
+  free, and whoever takes it next is no move. An unconfirmed record stays, since the slot may have moved while the
+  service was down, and a move this session saw keeps its record, so a clean stop never undoes it. A paused or
+  retrying slot reads `com.status` before each new ask. A move made after the slot's last renew or check and before
+  the stop, with no call since, is not seen at the leave: its record is forgotten, and the next start reads the slot
+  as free and may enroll it once the other holder lets it go (FAA-187). A file without the record
+  reads as before; a kit before 0.53.0 reads the file, ignores the record and drops it at its first checkpoint write. So a service stopped cleanly with no request left in its checkpoint, its DELETE answered 2xx and every slot confirmed
+  in that session, rolled back to 0.52 and up again starts as on a first start. Otherwise (a 404, the idle wait running
+  out, a slot this session never confirmed, one left retrying before `com.status` answered for it included) its records stay, and the case is the crash case below. After a crash the record stays: if 0.52 then ran, enrolled the slot and
   wrote nothing to the checkpoint, the next 0.53 start reads that enroll as a move; bring it back with the service's take-back action (below).
 - An enroll or a replace is written into that record with its key before it is sent (`asking`). When its answer is
   lost, the next connect (or the next enroll) sends the same call again under the same key; the board answers the
@@ -205,8 +237,8 @@ held and not transferred). The responder keeps that move instead of undoing it:
   holder, or the estate owner, reconciles it now). No `com.claim`, `com.renew`, `com.complete`, `com.enroll` or
   `com.responder_replace` is sent for that capability again: not at recovery after a restart, and not when the new
   holder's lease lapses, nor when com.status later names no generation for the slot (a recorded move stays until
-  take-back). Accepted requests stay held on the board, unanswered, until the slot is taken back (CT-175
-  will hand them to the new holder). One `board.slot.moved` event (warn, notify) says so, once, also across restarts
+  take-back). Accepted requests stay `accepted` on the board, unanswered, until the slot is taken back (CT-175
+  will hand them to the new holder). One `board.slot.moved` event (warning, notify) says so, once, also across restarts
   (the record keeps `moved`).
 - A responder that never held the slot (a first start: no record, or a record of another Project), or whose record
   equals the current generation, behaves as before: it enrolls, recovers and replaces its own lapsed work. A recorded or
@@ -216,18 +248,28 @@ held and not transferred). The responder keeps that move instead of undoing it:
   records its own generation. Only a replay the board refuses, or one that ran for the first time (`repeated: false`)
   after the slot had moved past the record, reads as a move: the safe side; a slot such a replay took is left to lapse
   unused. A generation written `2.0` is `2`.
-- Only the operator brings the slot back: `take_back(capability)` (`takeBack`) forgets the record; never edit the
+- Only the operator brings the slot back: `take_back(capability)` (`takeBack`) forgets the record, and wins over a move
+  being read at the same time: the move is written under the responder's lock (Node: on the fence queue, after any fenced
+  call in flight) and only while the record is unchanged (FAA-158). Never edit the
   checkpoint's `slots` record by hand to undo a move. In the same board
   session the next tick enrolls once the other session lets the slot go (a live holder is waited for) and takes the work
-  left `lapsed` back with a transfer. A restart or reconnect before that, with accepted work held for the slot, takes it
+  left `lapsed` back with a transfer. A restart or reconnect before that, with accepted work waiting for the slot, takes it
   back at once by `com.responder_replace`, as a restart did before 0.53.0: the operator asked for the slot back, so the
   other session is replaced. In recovery, a refusal that leaves no slot held reconnects; one that leaves some held keeps
-  the session and serves them. The kit gives it no route of its own (the reference service has none yet,
-  FAA-157): a service built on the kit declares it as an operator action, a button with its tool ([Every button has a
-  tool](../SKILL.md), `fabric-actions/0.1`) with gate `relayed` (the operator's decision), never `none`, so no other
-  agent can call it on its own; on a server that reads mandates (`agent_id`) it also names its effect class, for example
-  `change-policy` (DEC-0125); until Fabric's hub forwards decisions (CT-125) the operator reaches it through the
-  service's page or its elicitation, and names it in its docs; otherwise a moved slot stays moved. A move back to this service's own session is not
+  the session and serves them. The kit gives it no route of its own. The reference service (`sample_service.py`) offers
+  it on its dashboard (FAA-157): a moved slot shows a Take back button that posts `POST /api/board/take-back` from the
+  operator's signed-in session with the `X-Fabric-Request` header; the service token alone is refused. Since 0.56.0 the
+  button has its tool, `board.take-back` with `{capability}`, declared under `extensions/actions/0.1` with gate
+  `relayed` and target `capability`, and a capability of the manifest like every tool the well-known lists
+  (`interop.well-known-capabilities`): an agent whose MCP client sets `_meta` calls it over `/mcp` with the operator's
+  decision in `_meta.decision` (a call without one is `operator-decision-required`); Claude Code and Codex send
+  arguments only, so until CT-125 they hand the operator the page as Fabric Dashboards' `open_link`. Either door records
+  the take-back as a `board.slot.returned` event (info, the capability as its subject) whose sentence says the route in
+  words and whose `data` holds `by`, `via` and the `caller` (none when the feed refuses the caller), never the decision's words; a repeat after a lost answer is answered `{capability, moved: false}`. A service built on the kit declares it as an operator action, a button with its tool ([Every button has a
+  tool](../SKILL.md), `fabric-actions/0.1`) with gate `relayed` (the operator's decision), never `none`, so a call
+  without the operator's relayed decision is refused; on a server that reads mandates (`agent_id`) it also names its effect class, for example
+  `change-policy` (DEC-0125); the operator reaches it through an agent that relays their decision in `_meta`, the
+  service's page or its elicitation (Claude Code and Codex, which cannot set `_meta`, wait for CT-125's forwarding), and the service names it in its docs; otherwise a moved slot stays moved. A move back to this service's own session is not
   detected yet: the receiving side and the hand-over of accepted requests (contract CT-175) wait for Fabric's session
   surface.
 
@@ -251,11 +293,19 @@ raises `directory-invalid` rather than answering; an unlisted Project may still
 
 ## Events, the probe and the live smoke
 
-Events go to `emit(kind, level, text, notify=…, data=…)` (`JsonlEventLog.append` fits) with `data {schema, value}`
+Events go to `emit(kind, level, text, notify=…, subject=…, data=…)` (`JsonlEventLog.append` fits: every level is one
+of its `info`, `notice`, `warning`, `error`; `subject` is `{type, id}`, the notice's request, else its capability, else
+its episode (such as a block's cause), else the Project; in Python it goes only to an `emit` whose signature names a `subject`
+parameter with no value bound, as `JsonlEventLog.append` does, and any other `emit`, one with only `**kwargs`, one with
+a subject bound by `functools.partial` (which then stands) or one whose signature cannot be read, is called once, without
+one, as before 0.56.0; the Node responder always passes it in its options, which an `emit` that does not read it ignores) with
+`data {schema, value}`
 checked by FAC-SEM-101 (no credential in data): `board.request.completed`, `board.request.refused`,
 `board.request.skipped`, `board.request.reconciled`, `board.request.held`, `board.attempt.lost`,
-`board.reconcile.needed`, `board.slot.contested`, `board.slot.moved`, `board.access.needed`, `board.blocked`,
-`board.down`, each notifying episode said once.
+`board.reconcile.needed`, `board.slot.contested`, `board.slot.moved`, `board.slot.refused`, `board.access.needed`, `board.blocked`,
+`board.down`, each notifying episode said once, and `board.outcome.invalid` (warning) when a handler's outcome fails
+its checks and is not sent. The operator's hold (below) adds `board.held`, `board.slot.held`,
+`board.slot.released` and `board.request.waiting`. The reference service adds `board.slot.returned` at a take-back.
 
 `check_service.py <id> [--board-kit <the service's fabric_board.py or fabric-board.mjs>]` rule **board.responder**:
 `NOT_RUN` when the well-known `protocols` names no `fabric-project-comms` revision; `FAIL` for a revision this kit does

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/connectors.md

@@ -45,7 +45,12 @@ const answer = await request('GET', 'https://api.example/v1/items', { headers, d
 
 Every answer comes back as a `Response`, whatever its status; `HttpError` means no usable answer came, with `kind`
 `connection`, `timeout`, `too-large` or `refused`, the status when there was one, and the URL redacted to scheme,
-host, port and path (`redact_url`). An error never carries a request header or body.
+host, port and path (`redact_url`); a URL that is not http or https keeps only its scheme (`htps:<redacted>`), and
+one that does not parse as a URL is `<unparseable url>`. The path is not redacted (Node writes it as `new URL`
+normalises it, Python as given), so a key never belongs in it. Python's `check_url` refuses a host
+with a backslash, space, control character (C0, DEL or C1) or `%`, a URL with a space or ASCII control character before its
+first `#` (the default transport sends a URL up to there, as Node's does; a transport you pass receives the URL as given), or a character outside ASCII in its path or query (ASCII whitespace at its ends is trimmed, as urllib and `new URL` trim it; a Unicode space ending the part before the first `#` is refused, where Node keeps it percent-encoded), a bracketed host that is not an IPv6 address with no zone, and a port that is not
+ASCII digits, all as kind `refused` before sending; it checks a host's shape, not its name. `redact_url` on Python reads a host holding `%` as `<unparseable url>`; Node writes it decoded. An error never carries a request header or body.
 
 ## fabric_openrouter
 
@@ -77,6 +82,7 @@ const answer = await client.chat(messages, { model, fallback, maxTokens: 800 });
 | The fallback | required, of another vendor (the part before `/` differs) |
 | Content | text only: a string, null, or parts that are all `{"type": "text"}`; an image, audio or file part is refused (`config`), because what it is billed cannot be bounded from its bytes |
 | What the ceiling does not cover | the `provider` routing param can send a call to a provider priced above the catalog; two `Client` objects sharing one ledger each hold only their own calls in flight, so give an agent one client per key |
+| The base URL | `base_url` (`baseUrl`), by default `https://openrouter.ai/api/v1`: checked by `check_url` when the client is built; ASCII whitespace and trailing `/` at its ends are trimmed (Node also trims every C0 control at the ends and removes a tab or line break anywhere, as `new URL` reads them); a base that is not a string is refused as `check_url` refuses it (`HttpError` kind `refused`, both twins); a query or a fragment is refused (kind `config`, both twins, before `check_url`). Python also refuses a space, a control or a non-ASCII character in the path (`check_url`'s `HttpError` kind `refused`); Node sends it percent-encoded, as `new URL` writes it (FAA-187 (18)) |
 | Attribution | off unless an `attribution` setting is given (FAC-SEM-098, `fabric_usage.attribution_headers`) |
 | Request body | `model`, `messages`, `max_tokens`, `usage: {include: true}` and your params (temperature, reasoning, response_format, tools); `stream`, `model`, `messages`, `max_tokens` and `usage` as params are refused |
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/delegation.md

@@ -110,7 +110,9 @@ issuer's fault, `issuer-unavailable` (DEC-0045); a gate without a trusted issuer
 DEC-0121 adds three codes to the one set, each 403: `operator-decision-required` (a `relayed` action called without the
 operator's decision), `decision-invalid` (a decision for another action or object, outside its 24 hours, or malformed)
 and `human-step-required`, which carries `data.humanStep` (`sign-in`, `consent`, `payment`, `secret`,
-`spend-above-limit`, `passkey`) and `data.url` (an https URL or a path on the service's origin) beside `detail`.
+`spend-above-limit`, `passkey`, and since DEC-0142 `comparison`: a comparison of codes between two people or the choice
+to share without one; a reader pinned before DEC-0142 refuses a whole declaration that names it, and a caller that validates the refusal
+against a `delegation-refusal.schema.json` pinned before DEC-0142 refuses that refusal) and `data.url` (an https URL or a path on the service's origin) beside `detail`.
 `refusal_from_action` / `refusalFromAction` turn an action decision into that refusal; a service's own fault never
 reaches the caller and reads as `unknown-state`, but for `mandate-capability-missing` (DEC-0141 MJ-1): the caller
 reads `operator-decision-required` with that `data.detail`, since no mandate covers the step and only a decision does. Since 0.51.0 the `operator-decision-required` message (free text in
@@ -124,6 +126,15 @@ page as Fabric Dashboards' `open_link`; both kits carry the same sentence. The g
 `JwksCache` holds the estate's key set at most 10 minutes and, on a `kid` it does not hold, re-reads at most once
 a minute (DL-15), and waits 10 s after a failed read before trying again; after 10 minutes without a successful read it answers nothing, and the verifier says
 `issuer-unavailable`. It reads https, http on loopback only, or a file; a URL with credentials is refused. The
+Python kit also refuses, https included, a URL holding a space or ASCII control character before its first `#` (it
+reads the URL up to there, as Node does), or a character outside ASCII in its path or query (urllib would send it
+and every read fail; a trailing ASCII space or line break is trimmed as urllib reads it; a Unicode space ending the
+part before the first `#` is refused, as `check_url` refuses it, because Node keeps it percent-encoded (urllib would
+trim it and read the keys when it ends the URL); a leading space is refused as not a URL), a host holding `%`, a backslash, a Unicode space or a control character (urllib
+would decode or dial it as another host), a bracketed host that is no IPv6 address, a port that is not ASCII digits or is above
+65535, no host, and an empty userinfo. The Node kit accepts several of these as `new URL` reads them, among them a `%`
+host decoded, a backslash as `/`, a tab or line break removed, an empty userinfo dropped and an extra slash before the
+host skipped. The
 Python kit verifies Ed25519 itself (RFC 8032, standard library only, strict as OpenSSL: `S` below the group order,
 canonical points, no small-order key); it follows no redirect when it reads the key set; the Node kit uses `node:crypto` and refuses small-order keys
 itself (`isSmallOrderKey`), because Node before 26 lets OpenSSL accept a signature under one.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/interop.md

@@ -149,7 +149,8 @@ operator's own coding agents: Claude Code and Codex cannot set `_meta`, so until
 a `relayed` gate turns "approve it" in chat into `operator-decision-required` with the page as the only route.
 Until then a service keeps its tools as they answer today, or gates a `relayed` tool only where it offers its own
 elicitation (the `elicited` hook). The one exception is the board responder's take-back action: it is declared
-`relayed` now and reached through the page or elicitation until CT-125 (`board.md`). This is D8's reason, which keeps `input_actions` off, applied to tools.
+`relayed` now (the reference service's `board.take-back`); an agent whose MCP client sets `_meta` calls it with the
+operator's decision, and Claude Code and Codex reach it through the page until CT-125 (`board.md`). This is D8's reason, which keeps `input_actions` off, applied to tools.
 
 **Parity (AP-1).** Every action the dashboard, app or page lets a person take (approve, reject, choose, edit, pause,
 resume, cancel, retry, send, publish, restore, set a policy, any other) has a tool on the MCP surface with the same
@@ -160,7 +161,11 @@ dialog is one of those checks; an instruction that names the action satisfies it
 |---|---|---|
 | `none` | an act on the caller's own account: refresh, read, retry or cancel its own job | the caller's own act |
 | `relayed` | a decision on another party's proposal or draft, a send, a publish, a deletion, a spend within a limit, a restore, a policy change | the operator's act when a T0 or T1 caller carries a valid decision; else a refusal below |
-| `human` with `humanStep` | `sign-in`, `consent`, `payment`, `secret`, `spend-above-limit`, `passkey` (AP-4): they stay the person's | `human-step-required` with `data.humanStep` and `data.url`, the direct link to that step |
+| `human` with `humanStep` | `sign-in`, `consent`, `payment`, `secret`, `spend-above-limit`, `passkey`, `comparison` (a comparison of codes between two people or the choice to share without one, DEC-0142) (AP-4): they stay the person's | `human-step-required` with `data.humanStep` and `data.url`, the direct link to that step |
+
+Declare `comparison` only to readers at or after DEC-0142: a reader pinned before it (a 0.56.0 or older kit, Fabric
+Dashboards before 0.8.9) refuses the whole declaration, every action in it, and FAC-SEM-142 then reads it as not declared. Fabric's hub reads no declaration and forwards the step unchanged
+(CT-186).
 
 ```python
 server = fi.McpToolServer("example-agent", "1.0.0", jobs=jobs, authorize=gate,
@@ -201,8 +206,11 @@ well_known = fs.build_well_known(..., surfaces=surfaces, actions=server.action_t
   `caller-missing`: an action-gated server must pass `tier`, `identify` or `authorize`,
   since `handle` defaults to T2 and a T2 call names nobody without them). One fault reaches the caller by name:
   `mandate-capability-missing` (DEC-0141 MJ-1), read as `operator-decision-required` with that `data.detail`.
-  `on_fault` hears it from `ctx.approval_step` at a job's start under the job's tool, and at the answer under
-  `fabric.job.get`; at the start it hears any fault `job_step` answers (also `now-unreadable` from the server's clock).
+  `on_fault` hears it under the job's capability (the name the job was created under) both from `ctx.approval_step`
+  at a job's start, where the caller sees no refusal: the job waits `input_required`, its message naming the fault,
+  and at an answer through `fabric.job.get`, where the call is refused; at the start it hears any fault `job_step`
+  answers (also `now-unreadable` from the server's clock). A capability name is what `^[a-z][a-z0-9._-]{1,127}$`
+  matches (`reviews.approve`, never `reviewsApprove`); a job created under another name is read under that name.
 - **Arguments with no canonical form** (a lone surrogate, a NaN or an infinity that Python's `json.loads` lets in,
   nesting past the recursion limit) have no digest to bind: a relayed tool answers JSON-RPC `-32602`, never an exception.
 - **The handler** reads `ctx.record` (`"caller"`, or `{by, via, caller}`) and writes it into the service's audit
@@ -305,7 +313,10 @@ server.add_tool(approve_tool, approve_reply, action=reply_action, target="reply_
   step is kept in the job's private part (`request_input(..., steps=)`). An answer's `_meta.mandate` that covers that
   step is then read when `input_actions=True`, beside a decision for the key. The rule alone is `job_step(mandate, ...)`
   / `jobStep({mandate, tier, now, self, capability, key, effect, callerAgent, spendUsd, project})`; Node's
-  `requestInput(jobId, inputRequests, statusMessage, {steps})` keeps the same private part. Each `request_input`
+  `requestInput(jobId, inputRequests, statusMessage, {steps})` keeps the same private part. Node has no
+  `approvalStep`, so a Node service calls `jobStep` itself and passes `{}` when the start call's `_meta` carried
+  `mandate: null` (`Object.hasOwn(meta, 'mandate') && meta.mandate === null ? {} : meta.mandate`): `null` is no mandate
+  to `jobStep`, while the answer reads it as an unreadable one (FAA-178). Each `request_input`
   replaces the kept steps, and an answer clears them: pass `steps=` again on every question whose answer a mandate may
   cover. The answer's mandate is read under the job's own capability, as at the start (`action_gate(...,
   mandate_capability=)` / `actionGate({mandateCapability})`), so the start and the answer agree whatever the tool is
@@ -328,7 +339,9 @@ lead, at, expiresAt})` (a day unless told, at most seven), hands it to the agent
 `hand_on(mandate, callee, at, narrower=None)` / `handOn(mandate, callee, at, narrower)` (the chain gains the callee; a
 wider scope, a fifth agent, an agent already in it or a time at the expiry is refused; `source` travels unchanged), and
 sends it with `request_meta(traceparent, mandate=...)` / `requestMeta(traceparent, {mandate})`, which refuse one
-`FAC-SEM-144` refuses. `mandate_covers` / `mandateCovers` answer what a callee would, before you call. Never write a
+`FAC-SEM-144` refuses. `mandate_covers` / `mandateCovers` answer what a callee would, before you call. To cover a
+job's approval steps, name the job's capability in `capabilities` (or leave `capabilities` out) and the steps' keys in
+`actions`; never `fabric.job.get`, which covers no step of another capability (DEC-0141 MJ-1). Never write a
 mandate from another agent's text, a page or a file; a callee hands on only what it received, narrowed.
 
 A relay the operator's rule accepts (DEC-0126 OA-2, OA-3: one of his own Projects on his board, provenance `trusted`,

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/kit-modules.md

@@ -87,6 +87,7 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | L4 | `fabric_hub` | the Fabric hub's door (`fabric-hub/0.1`) |
 | L4 | `fabric_board_shapes` | the project board's wire: constants, refusal codes, shapes |
 | L4 | `fabric_board_link` | the board's link: the MCP session over the hub, the fsynced checkpoint, a claimed request as data |
+| L4 | `fabric_board_slots` | the responder's slot records: the generation held, a move and its take-back, one capability's refusal retried alone (FAA-163) |
 | L4 | `fabric_board_session` | the board responder: the work context, the fenced request, transfer and recovery |
 | L4 | `fabric_board_fixture` | the scripted board the probe runs a responder against |
 | L4 | `fabric_board` | the facade of the board connector ([board](board.md)) |

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/lifecycle.md

@@ -55,7 +55,7 @@ that document until `service.id` matches (at most 40 s) before it calls the serv
 
 | Id | Rule | Here | Kit (Python / Node) |
 |---|---|---|---|
-| LC-01 | **Quit reaches exit within a deadline.** Every trigger (`SIGTERM`, `SIGINT`, logout, the app's own quit) ends the process: within 5 s idle, within 10 s with work in flight, then a hard exit (a board responder leaving its session can take an idle stop up to that hard exit). Nothing starts after quit begins | [Shutdown](#shutdown) | `Drain` / `Drain` |
+| LC-01 | **Quit reaches exit within a deadline.** Every trigger (`SIGTERM`, `SIGINT`, logout, the app's own quit) ends the process: within 5 s idle, within 10 s with work in flight, then a hard exit (an idle board responder waits 3 s at most for its session's DELETE, FAA-173; one with work can take up to that hard exit). Nothing starts after quit begins | [Shutdown](#shutdown) | `Drain` / `Drain` |
 | LC-02 | **Every child has an owner, a deadline and a process group.** No subprocess without a timeout; on timeout or the parent's exit the whole group goes; no orphan survives. Locks and shared resources are released in `finally` | your own code | none |
 | LC-03 | **A job is bounded and exclusive.** One copy holds `service.lock`; a scheduled job has a watchdog shorter than its interval, shares its lock with every manual entry point, bounds every network call and records each run's outcome. Long work is journalled before it starts | [One copy under a supervisor](#one-copy-under-a-supervisor) | `hold_single_instance` / `holdSingleInstance` |
 | LC-04 | **Credentials are silent after setup.** No background prompt; a credential read that is denied or absent is cached and backs off until a person acts | [Directories](#directories) (secret files 0600) | none |

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -1,6 +1,6 @@
 # fabric-service/0.1: wire reference
 
-Pinned to `fabric-agent-contract` commit `00e050ba7429c0c60261cec871779e0fd6aeeb28`
+Pinned to `fabric-agent-contract` commit `3830a3353923e20f826d466610e1c479f120bec0`
 (`docs/specification/service.md`, DEC-0015; the usage report DEC-0021; Windows and Linux supervision
 DEC-0032 and DEC-0033; the operator channel DEC-0034 and DEC-0035; the embedded dashboard DEC-0036;
 delegation and the operator session's lifetime DEC-0039; the meter's call window DEC-0041; session handoff DEC-0042;
@@ -23,8 +23,10 @@ DEC-0124; the operator's mandate `mandate/1`, handed on narrowed with a task DEC
 operator's agents, its `source` on a mandate and a decision DEC-0126; context hub keys and the organizations an estate
 record pins DEC-0127 and DEC-0128; the family and the agent network named DEC-0130 and DEC-0137; a reply delivered to
 the sender it answers, or to whom it names DEC-0135; a hand-over adds no naming list the scope in force leaves out
-DEC-0136; a job's step under the mandate read under the job's own capability DEC-0141. The organization's member list, draft exchange, relay and the machines' report, DEC-0129, DEC-0131 to DEC-0134,
-reach the kit only as protocol register entries). The contract's schemas are normative;
+DEC-0136; a job's step under the mandate read under the job's own capability DEC-0141; a person's comparison of codes as a human
+step DEC-0142. The organization's member list, draft exchange, relay and the machines' report, DEC-0129, DEC-0131 to
+DEC-0134 and DEC-0139, an organization's adaptation DEC-0138 and the peer share DEC-0142, reach the kit only as
+protocol register entries). The contract's schemas are normative;
 this page is the working summary. Extension key:
 `https://fabric.passioncode.ai/agent-contract/extensions/service/0.1`.
 
@@ -162,7 +164,10 @@ path on the service origin, never an absolute URL. Optional SSE stream at
 **Machine-readable `data` (DEC-0070).** An event may carry `data {schema, value}` beside its sentence: `schema` is the
 absolute URI of a payload schema the service publishes; `value` is an object of at most 32 members, each a scalar (a
 string of at most 500 characters, a number, a boolean, null), a list of at most 32 scalars, or an object of at most 32
-scalar members. `text` stays the event: a host that ignores `data` loses nothing, and one that does not know the schema
+scalar members: two levels at most, so `value.cited` may be a list of ids or an object of counts, never a list of
+objects (FAA-122). Flatten a nested record into members of its own, `{"citedIds": ["a1", "b2"], "citedCoverage":
+[0.8, 0.4]}` in place of `{"cited": [{"id": "a1", "coverage": 0.8}, ...]}`; the refusal names the first place that
+nests too deep (`data.value.cited[0] is an object`). `text` stays the event: a host that ignores `data` loses nothing, and one that does not know the schema
 treats `value` as opaque. No string in `value` sits under a credential's name or has a credential's shape
 (`FAC-SEM-101`); personal data is the service's own duty. `make_event` / `makeEvent` (and `JsonlEventLog.append`) take
 `data=` and refuse one that breaks either rule, naming the place, never the value; `check_service.py` checks the feed it

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-actions.mjs

@@ -37,7 +37,8 @@ export const DECISION_INVALID = 'decision-invalid';
 export const HUMAN_STEP_REQUIRED = 'human-step-required';
 export const APPROVAL_REQUIRED = 'approval-required';
 export const GATES = Object.freeze(['none', 'relayed', 'human']);
-export const HUMAN_STEPS = Object.freeze(['sign-in', 'consent', 'payment', 'secret', 'spend-above-limit', 'passkey']);
+/** AP-4's steps a person takes; `comparison` (DEC-0142) is a comparison of codes between two people. */
+export const HUMAN_STEPS = Object.freeze(['sign-in', 'consent', 'payment', 'secret', 'spend-above-limit', 'passkey', 'comparison']);
 export const MAX_ACTIONS = 128;
 /** How far ahead of the service's clock a decision's `at` may be (the contract's CLOCK_SKEW_SECONDS). */
 export const CLOCK_SKEW_SECONDS = 60;

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-board-link.mjs

@@ -10,7 +10,7 @@ import { BoardError, RESPOND_TOOLS, isObj, refusalProblems } from './fabric-boar
 /** MCP over HTTP with a board session's one-session bearer; calls are serialised; close() sends the session's DELETE. */
 export class BoardSession {
   constructor(grant, { timeout = 15000, post = postMcp } = {}) {
-    Object.assign(this, { grant, timeout, post });
+    Object.assign(this, { grant, timeout: timeout > 0 ? timeout : 15000, post }); // not above 0 is the default
     this.mcpSession = null;
     this.protocolVersion = MCP_PROTOCOL_VERSION;
     this.rpc = 0;
@@ -23,9 +23,9 @@ export class BoardSession {
     return run;
   }
 
-  async #send(body, method = 'POST') {
+  async #send(body, method = 'POST', timeout = null) {
     try {
-      return await this.post(this.grant.origin, body, this.grant.bearer(), { session: this.mcpSession, timeout: this.timeout, method, protocolVersion: this.mcpSession ? this.protocolVersion : undefined });
+      return await this.post(this.grant.origin, body, this.grant.bearer(), { session: this.mcpSession, timeout: timeout > 0 ? timeout : this.timeout, method, protocolVersion: this.mcpSession ? this.protocolVersion : undefined });
     } catch (e) {
       if (e instanceof HubError) throw new BoardError('unreachable', 'Fabric\'s hub did not answer; a write may have been stored, so send it again with the same idempotency key.', true);
       throw e;
@@ -66,15 +66,19 @@ export class BoardSession {
     });
   }
 
-  close() {
+  /** Sends the DELETE (waiting `timeout` ms at most); true when Fabric answered it with a 2xx, so the slots are free now (FAA-163). A 404 (already gone) is false: a move made before it ended is read at the next com.status, so the slot records stay. */
+  close(timeout = null) {
     return this.#serial(async () => {
-      if (!this.mcpSession) return;
+      if (!this.mcpSession) return false;
+      let status = 0;
       try {
-        await this.#send({}, 'DELETE');
+        const answer = await this.#send({}, 'DELETE', timeout);
+        status = Number.isInteger(answer?.status) ? answer.status : 0; // an answer it cannot read is no release, as in Python
       } catch {
         // best effort: the lease lapses in 60 s anyway
       }
       this.mcpSession = null;
+      return status >= 200 && status < 300;
     });
   }
 }
@@ -135,14 +139,17 @@ export class Checkpoint {
     this.slots = slots;
   }
   /**
-   * At a clean leave (the session's DELETE released the slots): forget the record of each slot this service held for
-   * `project` with no request left and not moved away, so a later generation is another session taking a free slot, and
+   * At a clean leave (the session's DELETE released the slots): forget the record of each slot this session confirmed
+   * (`held`, required: capability to the generation it held, or com.status showed unmoved) at that generation or below, for `project`, with no request left and not moved away, so a later generation is another session taking a free slot, and
    * a kit rolled back to before 0.53.0 leaves nothing that reads as a move. A record that cannot be written stays.
    */
-  leave(project) {
+  leave(project, held) {
     const busy = new Set(Object.values(this.entries).map((e) => e.capability));
     for (const [capability, record] of Object.entries(this.slots)) {
       if (!isObj(record) || record.project !== project || 'moved' in record || busy.has(capability)) continue;
+      // Only a slot this session confirmed, at or below that generation: an unconfirmed record may be a move (0.56.0 seam r2, r3).
+      const confirmed = Object.hasOwn(held, capability) ? held[capability] : null;
+      if (!Number.isInteger(record.generation) || record.generation < 1 || !Number.isInteger(confirmed) || record.generation > confirmed) continue;
       try {
         this.slot(capability, null);
       } catch {