@passioncode-ai/fabric-agent-adapter 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## 0.28.0 - 2026-10-13
+
+A service answers a Project's requests on Fabric's project board (`fabric-project-comms/0.1`; FAA-12b, contract
+DEC-0022, DEC-0073, DEC-0078; Fabric ADR-0149), and checks a directory page before it looks a Project up (FAA-40,
+DEC-0077, `FAC-SEM-107`). Repinned to contract `f00a768` (DEC-0078: a replacement's receipt carries the attempt of
+each request it transferred); `a046f57` stays supported.
+
+### Added
+
+- **The hub door client.**
+  - `fabric_hub.py` / `fabric-hub.mjs` re-read `hub.json` before every call, the way Fabric's `locateHub` does: a small
+    regular file, protocol `fabric-hub/0.1`, the origin exactly `http://127.0.0.1:<port>`, a door token inside the
+    registry root, and a live pid. A binding credential is sent only after that check.
+  - `request_board_access` asks the operator for the `board.respond` grant. `poll_access` writes the credential, shown
+    once, to a 0600 file and leaves it out of the answer. `join_board` answers a board session.
+  - Typed `HubError`s: a missing grant carries the arguments to ask with. `Backoff` waits 2 s, doubling up to 5 minutes,
+    with jitter, so a loop never spins.
+  - A `hubKey` in a later `hub.json` is checked with `hub_key_certified` (DEC-0060) when the caller passes an estate
+    record. `fabric-hub/0.1` publishes no key today.
+- **The responder.** `fabric_board.Responder` / `Responder` runs inside the service, one request at a time:
+  - Each tick (15 s ± 5 s) enrolls, claims, reads the message and accepts it with the claim's exact fence. The digest
+    must match the claim's, and the request must name this Project and capability.
+  - `com.effect_begin` is sent only when the handler calls `ctx.begin_effect()`. Renewal is about every 20 s. Progress
+    notes, a fenced `com.reply`, and `com.complete` with an observed outcome and at most 8 sha256 artifacts follow.
+  - A checkpoint (0600, fsync) is written before each step. If it cannot be written, nothing is sent.
+  - It stops acting on `fenced`, `lease_expired` and `authority_changed`.
+  - On restart it reconciles unknown outcomes from what `observe` reads. It takes accepted work back only through
+    `com.responder_replace`'s `transferred` (DEC-0078). On a Fabric that does not answer `transferred`, the work stays
+    held and is never claimed back.
+  - A board session never sends `com.submit`, `com.cancel`, `com.read_ack` or `com.directory`.
+  - With no idempotency epoch in `com.status`, it fails closed.
+  - The body is data: `admit`, the service's own input gate, is required. A refusal completes the request
+    `failed_known` with the gate's sentence.
+- **The directory page check (FAA-40).** `directory_findings`, `directory_problems` and `find_project` / `findProject`
+  apply `FAC-SEM-107`: each Project once, each capability once per Project, compared exactly as written. A page that
+  fails is refused rather than read.
+- **Closed shapes:** `receipt_problems` (with `transferred` for `com.responder_replace` only, each request once),
+  `refusal_problems`, `evidence_problems` (one artifact never twice, DEC-0076), `outcome_problems`, and
+  `comms_digest`, which matches the contract's `commsDigest` vectors.
+- **`check_service.py`** gains the rule `board.responder`:
+  - `NOT_RUN` when the well-known `protocols` lists no `fabric-project-comms` revision.
+  - Otherwise it runs the kit's fixture conversation: `self_check()` / `selfCheck()` covers the whole conversation, a
+    fenced accept and a session without an epoch. `--board-kit` names the service's own copy.
+- **`sample_service.py serve --board-project <uuid>`** opts in to answering `sample.echo` on the board, with a gate
+  and a reply. It is off by default.
+- `references/board.md`, linked from SKILL.md. working-with-fabric's `project-board.md`:
+  - The project directory is decided (DEC-0073).
+  - Answering as a responder needs `board.respond`.
+
+### Evidence
+
+- 20 hub tests and 49 board tests in Python, and 16 Node tests, run against one fake Fabric hub
+  (`test/fake_fabric_hub.py`), which models migration 87's fence order. The Python and Node kits read each other's
+  checkpoint.
+- The contract's 77 comms fixtures, 8 responder-argument digests and 12 `FAC-SEM-107` pages are vendored by
+  `vendor_vectors.mjs` at `f00a768`.
+- 22 planted defects across both kits, all caught (`docs/reports/2026-10-13-faa-12b-board-responders/raw/plants.log`).
+- Red before: the new tests at `origin/main` `65c1751` fail on the missing modules.
+- The live Claude→Codex board smoke is `NOT_RUN`: no disposable Fabric fits this machine. The commands are in
+  `references/board.md`.
+
+## 0.27.0 - 2026-10-13
+
+The usage report's window and spend by project, and OpenRouter attribution for a product's own traffic (contract
+DEC-0065, FAA-33). Pin unchanged at `a046f57`.
+
+### Added
+
+- **Spend by project.** `make_usage_receipt` / `makeUsageReceipt` take `project_id` / `projectId`, a URI kept in its
+  normal form (DEC-0076), and `task_run_id` / `taskRunId`. `usage_report` / `usageReport` then write `byProject`: each
+  project once, each task run once within it, with calls, unpriced calls and cost. It names no caller, session or
+  person.
+- **FAC-SEM-025 whole:** `usage_findings` / `usageFindings` check the arithmetic, the window (every day exists, is not
+  after `generatedAt`'s UTC date and is at most 30 days before it) and the projects. The projects' calls, priced calls
+  and known costs are bounded by the days' (CT-40).
+- **OpenRouter attribution, off by default:** `attribution_headers` / `attributionHeaders` and
+  `attribution_setting_findings` / `attributionSettingFindings` (FAC-SEM-098). The answer adds `HTTP-Referer`,
+  `X-OpenRouter-Title` and `X-OpenRouter-Categories` only with a valid setting, only to `https://openrouter.ai` (read as
+  a browser reads the URL), only for traffic the product originates, and never over a user's own attribution.
+- **`check_service.py`** `usage.report` reads each row's route (`platform-metered` included), the window and
+  `byProject`.
+
+### Evidence
+
+- Both kits pass the contract's 34 attribution cases.
+- Both kits give the contract's `usageRules` answer on 21 reports: its six positive usage fixtures and 15 edits of the
+  by-project one.
+- 23 planted defects, all caught.
+- The scenario eval `usage-by-project-and-attribution` was written before the prose.
+
 ## 0.26.0 - 2026-10-13
 
 Feed events carry machine-readable `data` (contract DEC-0070, FAA-35), and a service says which protocol revisions it

package/README.md

@@ -52,7 +52,11 @@ or dashboard — an `https` origin on a platform — a Fabric service (the remot
 four routes behind the token, a `__Host-` session cookie, and one descriptor on the operator's computer;
 `scripts/sample-remote-service.mjs` is the complete example. It ships Python and
 Node reference kits (`scripts/fabric_service.py`, `scripts/fabric-service.mjs`), a
-complete `scripts/sample_service.py`, and `scripts/check_service.py`, a live probe:
+complete `scripts/sample_service.py`, and `scripts/check_service.py`, a live probe. A service that answers
+requests other Projects post to its Project on Fabric's project board uses the board responder
+(`scripts/fabric_hub.py` and `scripts/fabric_board.py`, Node `fabric-hub.mjs` and `fabric-board.mjs`): the
+`board.respond` grant, enroll, claim, accept the exact digest, complete, a checkpoint before every step, and restarts
+that reconcile or take accepted work back by a transfer (the [board reference](plugins/fabric-agent-adapter/skills/building-fabric-services/references/board.md)):
 
 ```bash
 python3 plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py example-agent
@@ -235,7 +239,7 @@ Scaffolding is non-destructive by default. It writes only the paths declared in
 The default pin for new bundles is [`fabric-contract.lock.json`](fabric-contract.lock.json):
 
 - version: `0.1.0`
-- commit: `a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b`
+- commit: `f00a7685e3861c27f7899c033fb850a145a1708f`
 
 Every other mention of the default contract revision — this section, the skills' metadata, the
 skill card, `adapt_project.py` — must equal it; `python3 test/validate.py` fails a tree

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/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.
 metadata:
   author: PassionCode.ai
-  version: "0.26.0"
+  version: "0.28.0"
   contract-version: "0.1.0"
-  contract-commit: "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b"
+  contract-commit: "f00a7685e3861c27f7899c033fb850a145a1708f"
 ---
 
 # Adapting projects to Fabric
@@ -70,7 +70,7 @@ Use exactly:
 
 - contract version `0.1.0`;
 - repository `https://github.com/passioncode-ai/fabric-agent-contract`;
-- commit `a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b`.
+- commit `f00a7685e3861c27f7899c033fb850a145a1708f`.
 
 This is the default for new bundles. When checking an issued legacy bundle, preserve its
 explicit supported lock and use that exact clean checkout. Never silently upgrade or

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

@@ -21,10 +21,10 @@ import fabric_secrets as _secrets  # noqa: E402 - the contract's credential dete
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
-CONTRACT_COMMIT = "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b"
+CONTRACT_COMMIT = "f00a7685e3861c27f7899c033fb850a145a1708f"
 # #region supported-contract-revisions — docs: README.md#contract-pin
 # Only this declaration may name a legacy revision in live files.
-SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0", "b291bf09e0a9f9fd3c16cf540832cd021203b7d1", "0cacd08b0e95b6abf131eae1206b60792138bc3c", "2eb91c00e852d9c31d804310d38fad91589fcbac", "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5", "a83bec6b47776af688402c18efec507143061f68", "52da526d7cc1e063d74c5b520dbc03d0ace15246", "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5", "623bf61358c339cb10297807b3f024b5d9f1f327", "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
+SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b", "fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0", "b291bf09e0a9f9fd3c16cf540832cd021203b7d1", "0cacd08b0e95b6abf131eae1206b60792138bc3c", "2eb91c00e852d9c31d804310d38fad91589fcbac", "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5", "a83bec6b47776af688402c18efec507143061f68", "52da526d7cc1e063d74c5b520dbc03d0ace15246", "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5", "623bf61358c339cb10297807b3f024b5d9f1f327", "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
 # #endregion supported-contract-revisions
 INTEROP_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1"
 MCP_REVISION = "2026-07-28"

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

@@ -2,24 +2,25 @@
 name: building-fabric-services
 description: >-
   Use when handing out or opening a Fabric service dashboard, building a local agent service on a
-  macOS machine, or making an ONLINE agent or dashboard (https origin, the remote placement) a
-  Fabric service — «сделай агенту дашборд», «локальный сервис агента», «онлайн-дашборд в Fabric»,
-  «подключи агента к Fabric Dashboards», "make this agent a local service", "make an online
-  dashboard a Fabric service", "fabric-service protocol", "add the well-known endpoint", «расходы агента
-  на модели». Covers
-  fabric-service/0.1: surfaces, token and one-time login, state, one copy, launchd, descriptor,
-  well-known document, events, the usage report (spend per model); online: the https guard, the token-gated well-known document, the
-  __Host- cookie, registering it on the operator's computer; Python, Node and dashboard
-  kits, a TLS sample, live and layout probes. NOT for a one-off script or cron job, a hosted product with no agent
-  behind it, the provider manifest (adapting-projects-to-fabric), or building Fabric Dashboards.
+  macOS machine, making an ONLINE agent or dashboard (https origin, the remote placement) a
+  Fabric service, or letting a service answer a Project's board requests — «сделай агенту дашборд»,
+  «локальный сервис агента», «подключи агента к Fabric Dashboards», «отвечать на запросы с доски проекта»,
+  "make this agent a local service", "make an online dashboard a Fabric service", "add the
+  well-known endpoint", «расходы агента на модели». Covers fabric-service/0.1:
+  surfaces, token and one-time login, state, one copy, launchd, descriptor, well-known document,
+  events, the usage report; online: the https guard, the token-gated well-known document, the
+  __Host- cookie; the board responder (fenced claims); Python, Node and dashboard kits, probes.
+  NOT for a one-off script or cron job, a hosted product
+  with no agent behind it, the provider manifest (adapting-projects-to-fabric), or building Fabric
+  Dashboards.
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; 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.26.0"
+  version: "0.28.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b"
+  extension-commit: "f00a7685e3861c27f7899c033fb850a145a1708f"
 ---
 
 # Building Fabric services
@@ -89,6 +90,13 @@ applies the estate record (DEC-0055) verifies each revision first and trusts onl
 (DEC-0046), or a project routes its work through an ordered list of runners (DEC-0026: the doctor's closed probe
 results, the route checks FAC-SEM-028…034), read [the profiles reference](references/profiles.md).
 
+When the service answers requests other Projects post to its Project on Fabric's project board
+(`fabric-project-comms/0.1`), it holds a responder slot under the operator's `board.respond` grant and runs the kits'
+responder in its own process: [`scripts/fabric_hub.py`](scripts/fabric_hub.py) finds the hub and joins,
+[`scripts/fabric_board.py`](scripts/fabric_board.py) enrolls, claims, accepts the exact digest, checkpoints before
+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. Read [the board reference](references/board.md).
+
 ## Step 2 — the non-negotiables
 
 1. **Loopback only.** Bind `127.0.0.1`. Refuse any `Host` other than
@@ -252,7 +260,8 @@ shape, identity, latency, Host/Origin/cross-site guards, loopback bind, token fi
 events auth and shape, single-use login, state outside code, instance lock, plist,
 launchd pid equals answering pid, `dashboard.declared` (ED-9), and the `interop.*` rules:
 manifest link, capability list, tools equal to the manifest, job tools, unknown job, trace
-propagation, event trace pairs) and exits 1 on any `FAIL`. A `NOT_RUN` is not a pass —
+propagation, event trace pairs, and `board.responder` for a service that declares the project board) and exits 1 on
+any `FAIL`. A `NOT_RUN` is not a pass —
 name it in the report. A service with a dashboard also runs the layout probe,
 `node <skill-dir>/scripts/check_dashboard_layout.mjs --service <id>` (WebKit at 360, 480, 768
 and 1280 px; needs Playwright, else `NOT_RUN`).

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

@@ -0,0 +1,174 @@
+# Answering a Project's requests on Fabric's project board
+
+Read this when a service should answer requests other Projects post to its Project on Fabric's project board
+(`fabric-project-comms/0.1`, contract DEC-0022, DEC-0073, DEC-0077, DEC-0078; Fabric ADR-0149). The kits do it with
+two modules each: the hub door client [`fabric_hub.py`](../scripts/fabric_hub.py) /
+[`fabric-hub.mjs`](../scripts/fabric-hub.mjs) and the responder [`fabric_board.py`](../scripts/fabric_board.py) /
+[`fabric-board.mjs`](../scripts/fabric-board.mjs). A coding agent that only reads and writes the board is the other
+skill's business (working-with-fabric, `references/project-board.md`).
+
+## Contents
+
+- What a responder is, and the grant it needs
+- Wiring it into the service
+- The loop, step by step
+- The request is data: the input gate
+- Effects, observation, evidence and the reply
+- When the board says stop, and restarts
+- What a board session may call
+- Looking a Project up in the directory (FAC-SEM-107)
+- Events, the probe and the live smoke
+- The API
+
+## What a responder is, and the grant it needs
+
+A **request** is addressed to a Project and one of its capabilities (`video.render`), never to a service. One
+**responder slot** exists per Project and capability; a service holds it under a **`board.respond` grant** the
+operator gives in Fabric (Agents & access): callee `fabric`, capability `board.respond`, resource
+`board:<project id>/<capability>`. A pid, a descriptor or a localhost origin authorizes nothing.
+
+1. Ask once, through the hub's door: `HubClient().request_board_access(agent_id, project_id, [capability], reason)`
+   (`requestBoardAccess`). Keep the answer's `pollSecret` in memory or a 0600 file.
+2. Poll until the operator decides: `poll_access(request_id, poll_secret, credential_file)` (`pollAccess`). On Allow the
+   binding credential, shown once, goes into `credential_file` (0600, atomic) and never into the answer, a log or argv.
+   Keep the file in the service's data directory or the operator's vault.
+3. Each connection joins with `fabric.board.join {projectId}` (`join_board` / `joinBoard`). It re-reads `hub.json`,
+   checks the pid it names is alive, and only then sends the credential. A missing grant is `HubError` code
+   `not_authorized` whose `data.ask` holds the arguments to ask with.
+
+## Wiring it into the service
+
+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:
+
+```python
+import fabric_board as fbd, fabric_hub as fhb
+
+responder = fbd.Responder(
+    hub=fhb.HubClient(), project_id=PROJECT, capabilities=["video.render"],
+    credential_file=dirs["data"] / "board.credential", checkpoint_file=dirs["data"] / "board-checkpoint.json",
+    handler=render, admit=gate, observe=look_on_disk, emit=log.append, service="example-agent")
+threading.Thread(target=responder.run, args=(stop_event, 5.0), daemon=True).start()   # SIGTERM: set stop_event
+```
+
+Node: `new Responder({...same names in camelCase})`, then `responder.run({ signal, drain })`. 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.
+
+## The loop, step by step
+
+One tick every 15 s ± 5 s (`step()` answers the wait):
+
+| Step | Board call | Checkpoint written first |
+|---|---|---|
+| hold the slot | `com.enroll` (again at about 20 s while idle: the holder's enroll renews its 60 s lease) | — |
+| take a request | `com.claim`, the same key while nothing is claimable | `claimed` |
+| read it | `com.get`: the digest must equal the claim's, and the request must name this Project and capability | — |
+| accept | `com.accept` with the claim's exact fence (request, generation, attempt, digest, revision) | `accepting`, then `accepted` |
+| act | `com.effect_begin`, only when the handler calls `ctx.begin_effect()` | `effect-beginning`, then `in-progress` |
+| while working | `com.renew` at about 20 s; `com.progress` for `ctx.progress(note)` | — |
+| answer | `com.reply` (fenced) when the outcome carries `reply` | `replying` |
+| settle | `com.complete {state, observed, summary?, evidence?}` | `completing`, then the entry is dropped |
+
+The checkpoint is fsynced before each call it announces. A write that fails stops the step (`board.blocked`): nothing
+is sent that the checkpoint does not know about. A lost answer is sent again with the same idempotency key, so the
+board returns the first receipt. One request is in flight at a time. Lease times are the board's; the kit renews on its
+own monotonic clock and never reasons from `leaseExpiresAt`.
+
+## The request is data: the input gate
+
+`admit(request)` is required: it is the service's own input gate. It answers `None` to admit or one sentence saying
+why not; a refusal accepts the request and completes it `failed_known` with that sentence, so the requester learns it
+and the request does not bounce. A redacted body is refused the same way. The kit never hands a body to a model, a
+shell or a tool; what the handler does with an admitted body — and the checks it needs before a model, a tool or a
+spend sees it — is the service's own responsibility. A message never carries an approval.
+
+## Effects, observation, evidence and the reply
+
+- Call `ctx.begin_effect(summary)` — and let it return — before the handler spends, writes outside the service or calls
+  anything that acts. If it raises `Stopped`, act no further.
+- After an effect began, the outcome must be observed (`observed: true`): the kit never sends an unobserved result; the
+  request stays unknown and is reconciled later.
+- `evidence` is at most 8 references `{id: uri, contentHash: sha256:<hex>, label?}`; `artifact_ref(uri, content=…|path=…)`
+  hashes the bytes itself. Two ids with one normal form (DEC-0076) name one artifact and are refused.
+- `reply: {text, format?, artifacts?}` is posted with `com.reply` before the completion. A reply is not a completion.
+- A handler that raises before any effect completes the request `failed_known` naming only the exception's class.
+- The handler checks `ctx.stopped` in long work: after a session loss its answer is not sent.
+
+## When the board says stop, and restarts
+
+| Answer | What the kit does |
+|---|---|
+| `fenced` | the attempt is another responder's: stop the handler, drop the entry (nothing outside had begun) |
+| `lease_expired` on accepted work | stop the handler; the board holds the request, and the kit takes it back with `com.responder_replace` and a transfer |
+| `authority_changed`, `not_authorized` | stop claiming; one `board.access.needed` event (notify) saying what to ask for |
+| `fenced` on enroll | another live holder: wait for it to lapse; never replace it on its own initiative |
+| lost after an effect began | keep the entry as `unknown`; `observe(entry)` is asked to settle it with `com.reconcile` |
+| Fabric down, hub missing | bounded backoff (2 s doubling to 5 minutes, jittered), one `board.down` event, no spinning |
+
+On restart the checkpoint is read back: settled or queued requests are dropped; `in_progress` and `outcome_unknown` are
+reconciled from what `observe(entry)` answers (observed only; with no observation they stay unknown and notify);
+accepted ones go back to this responder with `com.responder_replace {expectedGeneration, transfer}`, whose receipt's
+`transferred` (DEC-0078: `{request, revision, attempt}`) carries the new fence. **A Fabric that does not answer
+`transferred` yet leaves the request held** (`board.request.held`, notify): the kit never claims it back, because the
+contract has no `com.claim` read-back and `com.claim` never moves an accepted request. A known outcome is sent after the
+transfer without running the handler again. `shutdown()` drains, then leaves the session (its DELETE releases the slot).
+
+## What a board session may call
+
+A board session (`fabric.board.join`) is served the respond scope only: `com.status`, `com.list`, `com.get`,
+`com.reply` (the fenced form), `com.enroll`, `com.claim`, `com.renew`, `com.accept`, `com.progress`,
+`com.effect_begin`, `com.complete`, `com.reconcile`, `com.responder_replace`. `BoardSession.call` refuses anything else
+locally (`not-in-scope`) — never `com.submit`, `com.cancel`, `com.read_ack` or `com.directory`.
+
+The idempotency epoch comes from `com.status`. A Fabric built before its board-session fix tells a board session none:
+the kit fails closed (`no-epoch`, `board.blocked`) instead of guessing one.
+
+## Looking a Project up in the directory (FAC-SEM-107)
+
+The directory belongs to a Project session (a coding agent's, or a launched one). Before looking a Project up in a
+`com.directory` page, `find_project(page, project_id, capability=None)` / `findProject` checks the page: closed shapes
+(no count, holder or generation) and FAC-SEM-107 — each Project once, each capability once per Project. Project ids and
+capability names compare **exactly as written** (DEC-0077; they are not URIs, so not by normal form). A page that fails
+raises `directory-invalid` rather than answering; an unlisted Project may still be addressed by an id already held.
+
+## Events, the probe and the live smoke
+
+Events go to `emit(kind, level, text, notify=…, data=…)` — `JsonlEventLog.append` fits — 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.access.needed`, `board.blocked`, `board.down`, each
+notifying episode said once.
+
+`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
+not read or a fixture conversation that goes wrong; `PASS` when the kit's `self_check()` / `selfCheck()` passes (the
+whole conversation, a fenced accept, a session without an epoch — no Fabric touched).
+
+The live smoke runs only against a disposable Fabric (built app and its own stack), never an operator's estate: Fabric's
+COM-03 packet (`docs/evidence/plans/2026-10-04-project-communications.md`) has the exact commands — register
+`fabric-mcp` for Claude Code and Codex, the operator allows `session.enroll` and `board.respond`
+(`board:<example-agent project>/<capability>`), Claude submits a request, the responder enrolls, claims, accepts and
+completes, then is killed mid-claim and replaced. Without that Fabric, report it `NOT_RUN`.
+
+## The API
+
+Python (`fabric_hub`): `fabric_root(platform, env)`, `locate_hub(root=None, alive=pid_alive, estate=None, now=None)`,
+`read_door_token(location)`, `read_credential(path)`, `HubClient(root=None, *, alive, timeout, estate, post)` with
+`request_board_access(agent_id, project_id, capabilities, reason)`, `poll_access(request_id, poll_secret,
+credential_file)`, `join_board(project_id, credential_file) -> BoardGrant`, `call_door(tool, args)`,
+`call_binding(tool, args, credential_file)`; `Backoff(first=2, cap=300, jitter=0.2, floor=1)`; `HubError(code,
+message, retryable, data)`.
+
+Python (`fabric_board`): `Responder(*, hub, project_id, capabilities, credential_file, checkpoint_file, handler,
+admit, observe=None, emit=None, service, now, rand, spawn, session_factory)` with `step()`, `run(stop, drain)`,
+`shutdown(drain)`; `WorkContext.progress(note)`, `.begin_effect(summary)`, `.stopped`; `BoardSession(grant)`;
+`Checkpoint(path)`; `comms_canonical(value)`, `comms_digest(operation, value)`, `receipt_problems(value, op)`,
+`refusal_problems(value)`, `directory_findings(page)`, `directory_problems(page)`, `find_project(page, project_id,
+capability)`, `artifact_ref(uri, content|path, label)`, `evidence_problems(list)`, `outcome_problems(outcome,
+effect_began)`, `self_check()`; `BoardError`, `Stopped`.
+
+Node: the same names in camelCase (`locateHub(root, {alive, estate, now})`, `new HubClient(root, {alive, timeout,
+estate, post})`, `new Responder({...})` with async `step()`, `run({signal, drain})`, `shutdown(drain)`; `await
+ctx.progress(note)`, `await ctx.beginEffect(summary)`; `selfCheck()`). Both kits read and write the same checkpoint file.

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 `a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b`
+Pinned to `fabric-agent-contract` commit `f00a7685e3861c27f7899c033fb850a145a1708f`
 (`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;
@@ -8,7 +8,7 @@ canonical forms DEC-0043; `degraded[].setup` and `run.mcp.stdio.scope` DEC-0044;
 DEC-0045; runner and model profiles DEC-0046; the estate record DEC-0055; one copy under any supervisor and its marker,
 the Windows token-file reader DEC-0057; the hub key the estate certifies DEC-0060; signing credentials DEC-0063; the
 estate record's 60 s skew DEC-0066; an app's own descriptor DEC-0069; the descriptor for listings DEC-0061; identifier equality
-by normal form DEC-0076). The contract's schemas are normative;
+by normal form DEC-0076; the project board's directory page DEC-0077 and a replacement's transferred attempts DEC-0078). The contract's schemas are normative;
 this page is the working summary. Extension key:
 `https://fabric.passioncode.ai/agent-contract/extensions/service/0.1`.
 

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

@@ -5,6 +5,14 @@ Fabric Agent Contract DEC-0021, `docs/specification/service.md` → *Usage repor
 offer it, so Fabric Dashboards (Spend, MCP `spend`) and Fabric can show each agent's spend beside
 its health without knowing any provider.
 
+## Contents
+
+- What to record
+- What to answer
+- By project (DEC-0065)
+- OpenRouter attribution (DEC-0065)
+- Verify
+
 ## What to record
 
 One **receipt per model call**, built from the numbers the provider returned:
@@ -78,9 +86,36 @@ Call `ledger.prune()` at start (or daily) to keep the file at the reported windo
 `JsonlUsageLedger` appends 0600 JSON lines. A line torn by a killed writer is skipped, and the
 next receipt never glues onto it.
 
+## By project (DEC-0065)
+
+Pass `project_id` / `projectId` (the URI of the project the service ran the call for) and, optionally, `task_run_id` /
+`taskRunId` (the service's own run id) to `make_usage_receipt` / `makeUsageReceipt`. The report then carries `byProject`:
+each project once, by the normal form of its id (DEC-0076, so `URN:PROJECT:a` and `urn:project:a` are one row), with
+its calls, unpriced calls, cost and `taskRuns`. A call for no project is in no row. It is the service's own run
+attribution and names no caller, session or person. `usage_findings` / `usageFindings` port FAC-SEM-025 whole:
+- the arithmetic;
+- the window: every day exists, is not after `generatedAt`'s UTC date, and is at most 30 days before it;
+- the projects: each project and task run once, and their calls, priced calls and known costs within the days' (CT-40).
+
+A row's `route` may be `platform-metered`: the hosting platform's own metered models under the deployment's account.
+
+## OpenRouter attribution (DEC-0065)
+
+A product credits its own OpenRouter traffic with `attribution_headers(setting, request)` / `attributionHeaders`. The
+setting is `{product, title, categories?}`: a lower-case slug (the app is `https://passioncode.ai/<product>/`), a printable
+title, and at most two of OpenRouter's recognized categories (FAC-SEM-098, `attribution_setting_findings`). Attribution
+is off by default: without a setting nothing is sent. The answer adds `HTTP-Referer`, `X-OpenRouter-Title` and
+`X-OpenRouter-Categories` only when all of these hold:
+- the request goes to `https://openrouter.ai` (read as a browser reads a URL);
+- the product itself originated the traffic;
+- the request carries no attribution header of the user's own.
+
+Otherwise it answers why not. It never reads, moves or returns a key.
+
 ## Verify
 
 `check_service.py <id>` reads a declared report: `usage.requires-token` (401 without the token)
-and `usage.report` (identity, USD, dates forward, null for all-unpriced rows, sums). The
+and `usage.report` (identity, USD, dates forward, null for all-unpriced rows, sums, each row's route, the window and
+`byProject`). The
 `sample_service.py` serves one. Fabric Dashboards → **Spend** shows it within a minute of opening
 the page.

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

@@ -5,6 +5,7 @@
   check_service.py --descriptor PATH
   options: --services-dir DIR  --json  --skip-login
            --ca-file PEM  --connect HOST:PORT     (remote placement: trust a test CA; dial another address)
+           --board-kit PATH                       (board.responder: the service's own fabric_board.py or fabric-board.mjs)
 
 A remote placement (DEC-0019 — an online agent or dashboard at an https origin) is probed over
 TLS with the certificate verified: the well-known document must refuse a request without the
@@ -19,6 +20,12 @@ that it redeems one login code it asked for itself (that creates one session).
 The interop.* rules (fabric-interop/0.1) read the manifest the descriptor names and
 the service's MCP surface: tools/list, and fabric.job.get for an id that does not
 exist. They never call a capability.
+
+board.responder (fabric-project-comms/0.1, FAA-12b): a service that lists a fabric-project-comms revision in its
+well-known `protocols` declares that it answers board requests. The rule checks that this kit reads that revision and
+runs the kit's fixture conversation (`fabric_board.self_check`, or `selfCheck` of a Node copy given with --board-kit):
+the whole conversation, a fenced accept and a board session without an epoch, with no Fabric. A live board is never
+touched; that smoke needs a disposable Fabric and is reported separately.
 """
 
 from __future__ import annotations
@@ -112,7 +119,8 @@ class _PinnedHTTPS(http.client.HTTPSConnection):
 
 class Probe:
     def __init__(self, descriptor_path: Path, descriptor: Dict[str, Any], services_dir: Path, skip_login: bool,
-                 ca_file: Optional[str] = None, connect: Optional[str] = None):
+                 ca_file: Optional[str] = None, connect: Optional[str] = None, board_kit: Optional[str] = None):
+        self.board_kit = board_kit
         self.remote = fs.placement_of(descriptor) == "remote"
         self.ca_file = ca_file
         self.connect = connect
@@ -799,10 +807,49 @@ class Probe:
             self.dashboard_rules()
             self.login_rules()
             self.interop_rules()
+            verdict, evidence = board_responder_verdict(self.wk, self.board_kit)
+            self.add("board.responder", verdict, evidence)
         self.lifecycle_rules()
         return self.results
 
 
+def board_responder_verdict(wk: Any, kit: Optional[str] = None) -> Tuple[str, str]:
+    """board.responder: NOT_RUN when the well-known document declares no fabric-project-comms revision; FAIL when it
+    declares one this kit does not read or the kit's fixture conversation finds a problem; PASS otherwise. `kit` is the
+    service's own copy (a .py or .mjs path); by default the kit beside this probe."""
+    protocols = wk.get("protocols") if isinstance(wk, dict) else None
+    declared = [p for p in protocols if isinstance(p, str) and p.startswith("fabric-project-comms/")] if isinstance(protocols, list) else []
+    if not declared:
+        return "NOT_RUN", "the service declares no board participation (no fabric-project-comms revision in protocols)"
+    accepted = fs.accepted_revisions("fabric-project-comms")
+    unread = [p for p in declared if "error" in fs.negotiate_revision(p, accepted)]
+    if unread:
+        return "FAIL", "declares %s, which this kit does not read (it reads %s)" % (", ".join(unread), ", ".join(accepted))
+    try:
+        if kit and kit.endswith(".mjs"):
+            if not shutil.which("node"):
+                return "NOT_RUN", "node is not installed to run %s's fixture conversation" % kit
+            url = Path(kit).resolve().as_uri()
+            out = subprocess.run(["node", "--input-type=module", "-e",
+                                  "import(process.env.FABRIC_BOARD_KIT).then(async (m) => console.log(JSON.stringify(await m.selfCheck())))"],
+                                 env=dict(os.environ, FABRIC_BOARD_KIT=url), capture_output=True, text=True, timeout=60)
+            problems = json.loads(out.stdout.strip().splitlines()[-1]) if out.returncode == 0 and out.stdout.strip() else ["the Node kit did not run: %s" % out.stderr.strip()[:200]]
+        else:
+            import importlib.util
+            path = Path(kit) if kit else Path(__file__).resolve().parent / "fabric_board.py"
+            spec = importlib.util.spec_from_file_location("fabric_board_under_test", str(path))
+            module = importlib.util.module_from_spec(spec)
+            sys.path.insert(0, str(path.resolve().parent))
+            spec.loader.exec_module(module)  # type: ignore[union-attr]
+            problems = module.self_check()
+    except Exception as exc:  # noqa: BLE001 - a kit that cannot run its conversation fails the rule
+        return "FAIL", "the kit's fixture conversation did not run: %s" % exc.__class__.__name__
+    if problems:
+        return "FAIL", "; ".join(problems)
+    return "PASS", "declares %s; the kit%s answers the fixture conversation (whole, fenced, no epoch)" % (
+        ", ".join(declared), " at %s" % kit if kit else " beside this probe")
+
+
 def session_lifetime_problem(set_cookie: str, now: Optional[float] = None) -> Optional[str]:
     """DEC-0039: a session cookie set at sign-in lives at most 7 days. Max-Age wins over Expires (RFC 6265
     §5.3); a cookie with neither ends with the browser session. None when it is within the bound."""
@@ -880,6 +927,16 @@ def usage_problems(report: Any, service_id: str, instance: str) -> List[str]:
         known = sum(m["costUsd"] for m in models if isinstance(m.get("costUsd"), (int, float)))
         if isinstance(day.get("costUsd"), (int, float)) and abs(day["costUsd"] - known) > 1e-6:
             out.append("%s: costUsd is not the sum of its models' known costs" % at)
+        for j, m in enumerate(models):
+            # DEC-0046, DEC-0061: a row's route is a login in its vendor's runner, an issued key, or the platform's
+            # own metered models (a listing in the cloud).
+            if "route" in m and m["route"] not in fs.USAGE_ROUTES:
+                out.append("%s.byModel[%d]: route %r is not subscription, key or platform-metered" % (at, j, m["route"]))
+    # DEC-0065: the window and the project attribution, as the contract's usageRules reads them (FAC-SEM-025).
+    for finding in fs.usage_findings(report):
+        path, message = finding["instancePath"], finding["message"]
+        if path.startswith(("/byProject", "/generatedAt")) or "generatedAt" in message or "exists in its month" in message:
+            out.append("%s: %s" % (path or "/", message))
     return out
 
 
@@ -912,6 +969,7 @@ def main(argv: Optional[List[str]] = None) -> int:
     parser.add_argument("--skip-login", action="store_true")
     parser.add_argument("--ca-file", help="remote placement: trust this CA bundle instead of the system store (tests)")
     parser.add_argument("--connect", help="remote placement: dial HOST:PORT while speaking TLS to the origin's name (tests)")
+    parser.add_argument("--board-kit", help="board.responder: the service's own fabric_board.py or fabric-board.mjs")
     args = parser.parse_args(argv)
     if not args.target and not args.descriptor:
         parser.print_usage(sys.stderr)
@@ -923,7 +981,7 @@ def main(argv: Optional[List[str]] = None) -> int:
     except (OSError, ValueError) as exc:
         print("No readable descriptor at %s: %s" % (path, exc), file=sys.stderr)
         return 1
-    results = Probe(path, descriptor, services_dir, args.skip_login, args.ca_file, args.connect).run()
+    results = Probe(path, descriptor, services_dir, args.skip_login, args.ca_file, args.connect, args.board_kit).run()
     failed = sum(r["verdict"] == "FAIL" for r in results)
     if args.json:
         print(json.dumps({"descriptor": str(path), "results": results, "failed": failed}, indent=2))