@passioncode-ai/passioncode 0.1.28 → 0.1.30

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.1.30 - 2026-10-07
+
+### Changed
+
+- **Fabric Agent Adapter is pinned at `v0.8.0`** (it was `v0.6.3`). Its service kit meets the
+  organization's lifecycle contract (0.7.0: a launchd install respects an operator's disable, an
+  `ExitTimeOut` default), agents can report what they spend (`make_usage_receipt`, `usage_report`,
+  Fabric Agent Contract DEC-0021), and a service may keep its MCP credential apart from the host's
+  token (DEC-0024). Bundles issued under the earlier contract revisions stay valid.
+- **Observatory Log is pinned at `v0.18.0`** (plugin 0.18.0; it was `v0.17.3`), the Project
+  Observatory 0.18.0 skills. That release installs only updates whose `SHA256SUMS` is signed by
+  the organization's release key, so the hook's daily update of an older engine now refuses an
+  unsigned or foreign-signed release instead of installing it.
+
+## 0.1.29 - 2026-10-05
+
+### Changed
+
+- **Observatory Log is pinned at `v0.17.3`** (plugin 0.17.3; it was `v0.16.0`). Its
+  SessionStart hook keeps Project Observatory current:
+  - for an engine at 0.17.0 or later, it schedules the engine's hourly maintenance job where
+    it is missing;
+  - for an engine from 0.7.0 to 0.16.0, which has no updater of its own, it installs the newer
+    release once a day with that engine's `full update --apply`, unless the person turned
+    automatic updates off.
+
+  Both run detached, at most every six hours or once a day, and never hold up a session.
+
 ## 0.1.28 - 2026-10-05
 
 The launcher meets the organization's

package/COMMERCIAL-LICENSE.md

@@ -5,7 +5,7 @@ This repository is open source under the [GNU Affero General Public License v3.0
 meet the AGPL's terms — for example inside a closed-source product, or as a modified hosted
 service whose source is not published.
 
-To obtain a commercial license, write to **contact@passioncode.ai**.
+To obtain a commercial license, tell us about your use at **https://passioncode.ai/business/**, or write to **commercial@passioncode.ai**.
 
 SPDX: `AGPL-3.0-only OR LicenseRef-PassionCode-Commercial`. Copyright (c) 2026 Siarhei Sheleh.
 Contributions are accepted under [CLA.md](CLA.md), which allows this dual licence.

package/README.md

@@ -115,7 +115,7 @@ reads a member from `<dir>/<repository name>`, and `PASSIONCODE_CHECKOUT_<MEMBER
 ## License
 
 Open source under the [GNU AGPL-3.0](LICENSE). A [commercial license](COMMERCIAL-LICENSE.md) is
-available for use that does not meet the AGPL's terms — contact@passioncode.ai.
+available for use that does not meet the AGPL's terms — [passioncode.ai/business](https://passioncode.ai/business/).
 Versions before 0.1.12 were released under PolyForm Noncommercial or Internal Use (v0.1.5 to
 v0.1.11) and MIT (v0.1.4 and earlier); each keeps the licence it was released under.
 Contributions are accepted under [CLA.md](CLA.md) ([CONTRIBUTING.md](CONTRIBUTING.md)).

package/family.json

@@ -8,7 +8,7 @@
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "repo": "passioncode-ai/fabric-agent-adapter",
-      "ref": "v0.6.3",
+      "ref": "v0.8.0",
       "kind": "plugin",
       "path": "plugins/fabric-agent-adapter",
       "legacyPluginIds": [
@@ -22,7 +22,7 @@
       "name": "observatory-log",
       "displayName": "Observatory Log",
       "repo": "passioncode-ai/project-observatory-dashboard",
-      "ref": "v0.16.0",
+      "ref": "v0.18.0",
       "kind": "plugin",
       "path": "observatory/engine/skill/plugins/observatory-log",
       "legacyPluginIds": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/passioncode",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "The PassionCode.ai agent skill set \u2014 Fabric Agent Adapter, Observatory Log and the organisation's working rules \u2014 for Claude Code and every other agent on the machine, updated as one set.",
   "bin": {
     "passioncode": "bin/passioncode.js"

package/payload/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "source": "./plugins/fabric-agent-adapter",
-      "version": "0.6.3",
+      "version": "0.8.0",
       "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.",
       "author": {
         "name": "PassionCode.ai",
@@ -23,7 +23,7 @@
       "name": "observatory-log",
       "displayName": "Observatory Log",
       "source": "./plugins/observatory-log",
-      "version": "0.16.0",
+      "version": "0.18.0",
       "description": "Records what changed in a watched project at the end of every turn, and asks for the one thing a diff cannot contain: why.",
       "author": {
         "name": "PassionCode.ai",
@@ -35,7 +35,7 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "source": "./plugins/passioncode",
-      "version": "0.1.28",
+      "version": "0.1.30",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/manifest.json

@@ -1,15 +1,15 @@
 {
   "family": "passioncode",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "release": true,
   "members": [
     {
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "repo": "passioncode-ai/fabric-agent-adapter",
-      "ref": "v0.6.3",
-      "commit": "30a1148ba77fe9ed56ea98c218d10ccf2fadf084",
-      "version": "0.6.3",
+      "ref": "v0.8.0",
+      "commit": "726646da8b8d2ec51ae5f911e1b3058d563d5cdc",
+      "version": "0.8.0",
       "via": "clone of https://***@github.com/passioncode-ai/fabric-agent-adapter.git",
       "skills": [
         "adapting-projects-to-fabric",
@@ -22,7 +22,7 @@
       "legacyMarketplaces": [
         "fabric-agent-adapter"
       ],
-      "contentHash": "sha256:264191fab8632a4f720185c68f79ca74c8fba1a14e50fd2d68957a35303c9c4b",
+      "contentHash": "sha256:8bf9584283471da6dcb4c2dbcb6be26a9ff3a042634a84976d5bb7ff479feba7",
       "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.",
       "author": {
         "name": "PassionCode.ai",
@@ -34,9 +34,9 @@
       "name": "observatory-log",
       "displayName": "Observatory Log",
       "repo": "passioncode-ai/project-observatory-dashboard",
-      "ref": "v0.16.0",
-      "commit": "aa6788d51e248de54c3f7184b17206af43e0b28e",
-      "version": "0.16.0",
+      "ref": "v0.18.0",
+      "commit": "4c68decefd213ccbb808a6f0ed5dfe72c1760d58",
+      "version": "0.18.0",
       "via": "clone of https://***@github.com/passioncode-ai/project-observatory-dashboard.git",
       "skills": [
         "explaining-changes",
@@ -49,7 +49,7 @@
       "legacyMarketplaces": [
         "observatory-log"
       ],
-      "contentHash": "sha256:f0bfd0f79ee99d25e6c82ad5f84337de2ce09f406fb4f5036cb45e3aa20d490a",
+      "contentHash": "sha256:3e93bbc01672e5595f5ba95412b4cc7eed633f559a121ec3f9908efe12cf4f59",
       "description": "Records what changed in a watched project at the end of every turn, and asks for the one thing a diff cannot contain: why.",
       "author": {
         "name": "PassionCode.ai",
@@ -61,16 +61,16 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "repo": "passioncode-ai/passioncode",
-      "ref": "v0.1.28",
+      "ref": "v0.1.30",
       "commit": null,
-      "version": "0.1.28",
+      "version": "0.1.30",
       "via": "this repository",
       "skills": [
         "working-in-passioncode"
       ],
       "legacyPluginIds": [],
       "legacyMarketplaces": [],
-      "contentHash": "sha256:c071f7a058bd6a8b8135ca7dd498f0b72ecd31cff1086ebbd3567611d66dbc98",
+      "contentHash": "sha256:f9ed14b545885bea0bdb2967253eeb53850aeb1e8880a2e9aaf8c840faae4b05",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/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.",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/payload/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.6.3"
+  version: "0.8.0"
   contract-version: "0.1.0"
-  contract-commit: "2ce392291c6668598d12cd38327e24696b5ca15c"
+  contract-commit: "23f9fda4c05f8a3852246ee98d4f2adf74ed0875"
 ---
 
 # Adapting projects to Fabric
@@ -70,7 +70,13 @@ Use exactly:
 
 - contract version `0.1.0`;
 - repository `https://github.com/passioncode-ai/fabric-agent-contract`;
-- commit `2ce392291c6668598d12cd38327e24696b5ca15c`.
+- commit `23f9fda4c05f8a3852246ee98d4f2adf74ed0875`.
+
+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
+downgrade it. Unknown repository/version/SHA locks and mismatched checkouts fail; missing
+dependencies remain `NOT_RUN`. Capability names may contain underscores at this default
+revision; declaring a COM name does not confer a grant, admission or wider authority.
 
 Read the pinned contract's guide
 `docs/guides/connecting-compatible-agents.md`, the selected profile specification, and

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

@@ -16,7 +16,11 @@ from urllib.parse import urlparse
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
-CONTRACT_COMMIT = "2ce392291c6668598d12cd38327e24696b5ca15c"
+CONTRACT_COMMIT = "23f9fda4c05f8a3852246ee98d4f2adf74ed0875"
+# #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, "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
+# #endregion supported-contract-revisions
 INTEROP_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1"
 MCP_REVISION = "2026-07-28"
 A2A_VERSION = "1.0"
@@ -357,7 +361,9 @@ def _walk_keys(value: Any, prefix: str = "") -> Iterable[Tuple[str, Any]]:
             yield from _walk_keys(item, "%s[%d]" % (prefix, index))
 
 
-def _contract_shape(manifest: Path, contract: Path) -> Tuple[str, List[str]]:
+def _contract_shape(manifest: Path, contract: Path, selected_commit: str) -> Tuple[str, List[str]]:
+    if selected_commit not in SUPPORTED_CONTRACT_COMMITS:
+        return "FAIL", ["unsupported selected contract revision"]
     if not contract.is_dir():
         return "NOT_RUN", ["contract checkout is not a directory: %s" % contract]
     try:
@@ -367,8 +373,19 @@ def _contract_shape(manifest: Path, contract: Path) -> Tuple[str, List[str]]:
         ).stdout.strip()
     except (OSError, subprocess.CalledProcessError) as exc:
         return "NOT_RUN", ["cannot read contract commit: %s" % exc]
-    if head != CONTRACT_COMMIT:
-        return "NOT_RUN", ["contract checkout is %s; expected %s" % (head, CONTRACT_COMMIT)]
+    if head != selected_commit:
+        return "FAIL", ["contract checkout is %s; selected lock requires %s" % (head, selected_commit)]
+    try:
+        dirty = subprocess.run(
+            ["git", "status", "--porcelain", "--untracked-files=normal"], cwd=str(contract), check=True,
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+        ).stdout.strip()
+    except (OSError, subprocess.CalledProcessError) as exc:
+        return "NOT_RUN", ["cannot verify clean contract checkout: %s" % exc]
+    if dirty:
+        return "FAIL", ["contract checkout has modifications; exact selected schema is required"]
+    if not (contract / "node_modules/.bin/tsx").is_file():
+        return "NOT_RUN", ["pinned contract dependencies are missing; run pnpm install --frozen-lockfile"]
 
     code = """import {readFile} from 'node:fs/promises';
 import {createValidator,validateDocument} from './src/validator.ts';
@@ -391,8 +408,10 @@ import {SCHEMA_PREFIX} from './src/contract.ts';
         return "NOT_RUN", ["contract shape validation timed out"]
     if run.returncode != 0:
         detail = (run.stdout + "\n" + run.stderr).strip()
+        if run.returncode != 3:
+            return "NOT_RUN", [detail[-4000:] or "contract validator could not run"]
         return "FAIL", [detail[-4000:] or "contract validator failed"]
-    return "PASS", ["manifest validated by pinned contract schema"]
+    return "PASS", ["manifest validated by selected contract schema at %s" % selected_commit]
 
 
 def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
@@ -406,11 +425,19 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
     manifest = _load_json(manifest_path, errors)
     lock = _load_json(root / "fabric-contract.lock.json", errors)
     profile_kind = None
+    lock_errors: List[str] = []
     if isinstance(lock, dict):
+        if lock.get("contract") != "fabric-agent-contract":
+            lock_errors.append("contract lock contract must be fabric-agent-contract")
+        if lock.get("repository") != CONTRACT_REPOSITORY:
+            lock_errors.append("contract lock repository must be %s" % CONTRACT_REPOSITORY)
         if lock.get("version") != CONTRACT_VERSION:
-            errors.append("contract lock version must be %s" % CONTRACT_VERSION)
-        if lock.get("commit") != CONTRACT_COMMIT:
-            errors.append("contract lock commit must be %s" % CONTRACT_COMMIT)
+            lock_errors.append("contract lock version must be %s" % CONTRACT_VERSION)
+        if lock.get("commit") not in SUPPORTED_CONTRACT_COMMITS:
+            lock_errors.append("contract lock commit must be an explicitly supported immutable revision")
+    else:
+        lock_errors.append("contract lock must be an object")
+    errors.extend(lock_errors)
 
     if isinstance(manifest, dict):
         if manifest.get("contractVersion") != CONTRACT_VERSION:
@@ -462,8 +489,10 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
 
     shape_status = "NOT_RUN"
     shape_receipts = ["pass --contract PATH pointing at the pinned checkout"]
-    if contract is not None and manifest_path.is_file():
-        shape_status, shape_receipts = _contract_shape(manifest_path, contract)
+    if lock_errors:
+        shape_status, shape_receipts = "FAIL", lock_errors
+    elif contract is not None and manifest_path.is_file():
+        shape_status, shape_receipts = _contract_shape(manifest_path, contract, lock["commit"])
 
     local_status = "PASS" if not errors else "FAIL"
     ready = local_status == "PASS" and shape_status == "PASS" and not warnings

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

@@ -5,9 +5,10 @@ description: >-
   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
+  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; online: the https guard, the token-gated well-known document, the
+  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; ships Python and Node kits, a TLS
   sample and a live probe. 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.
@@ -15,10 +16,10 @@ 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 use lifecycle manager none until a systemd adapter exists). 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.6.3"
+  version: "0.8.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "2ce392291c6668598d12cd38327e24696b5ca15c"
+  extension-commit: "23f9fda4c05f8a3852246ee98d4f2adf74ed0875"
 ---
 
 # Building Fabric services
@@ -90,7 +91,9 @@ are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
 2. **One copy, locked before any side effect.** Take the exclusive lock on
    `<data>/service.lock` first — before resuming jobs, starting a scheduler, migrating
    a store or even creating a token. Held → print one sentence naming the holder's pid
-   and exit **75**. Binding the port is not a lock. *(A second copy re-queued the first
+   and exit **75**. Binding the port is not a lock. Under launchd the kit backs off
+   in-process first (up to 300 s), so a duplicate is a few starts an hour, not a
+   `KeepAlive` respawn every 10 s. *(A second copy re-queued the first
    copy's running jobs in its startup hook, before its bind failed.)*
 3. **launchd is the only supervisor.** `RunAtLoad` true, `KeepAlive` true,
    `ThrottleInterval` 10, `ExitTimeOut` above your drain time. Never start yourself
@@ -133,7 +136,7 @@ Startup order is the part that goes wrong; keep it exactly:
 import fabric_service as fs
 
 dirs = fs.service_dirs("example-agent")
-lock = fs.hold_single_instance(dirs["data"])        # 1. lock — exits 75 if held
+lock = fs.hold_single_instance(dirs["data"])        # 1. lock — exits 75 if held (backs off first under launchd)
 token = fs.ensure_token(dirs["data"] / "service.token")  # 2. only now touch state
 log = fs.JsonlEventLog(dirs["data"] / "events.jsonl")    #    (or a view over your own log)
 codes = fs.LoginCodes(dirs["data"] / "auth")
@@ -153,8 +156,10 @@ On every request call `check_request(port, host, origin, sec_fetch_site)` and an
 | `POST /fabric/v1/login-code` | service token | `LoginCodes.issue()` |
 | `GET /fabric/v1/login?code=` | the code | `LoginCodes.redeem(code)` → `Set-Cookie: session_cookie_header(...)`, 302 to the dashboard |
 
-`SIGTERM` drains in-flight work within `ExitTimeOut`, then exits; interrupted work
-resumes on the next start.
+`SIGTERM` drains in-flight work, then exits — 10 s at most, inside `ExitTimeOut`
+(`fs.Drain` / `new Drain()`: `with drain.work():` refuses new work once a stop began);
+interrupted work resumes on the next start. Log through `RotatingLog` (5 × 5 MB, 0600)
+and call `cap_stdout_log` once at start.
 
 The MCP surface (`POST /mcp`, service token) is `fabric_interop.McpToolServer.handle`
 in Python; jobs live in `fabric_interop.JobStore(dirs["data"] / "jobs")`, created after
@@ -175,8 +180,11 @@ The installer, not the service, owns the plist and the descriptor. Sequence:
 2. `launchd_plist(...)` then `launchd_install(...)` — writes and lints the plist,
    `bootout` and waits for the unload, `bootstrap` with retries on the transient I/O
    error, then polls the well-known document until it answers with **this** identity.
-3. Uninstall: `launchd_uninstall`, `remove_descriptor`; keep data unless the operator
-   asks to purge.
+   A label the operator disabled stays disabled: only a first install enables.
+3. Uninstall: `launchd_uninstall` (waits for the unload, removes the plist, resets the
+   override; `purge=True` removes data only when the operator asks), `remove_descriptor`.
+4. After an upgrade, `prune_releases(releases_dir, current=…)` keeps the running release
+   and the one before it.
 
 Code runs from an immutable release directory; an upgrade writes a new release,
 rewrites the plist and restarts. Read [the lifecycle reference](references/lifecycle.md)
@@ -199,6 +207,11 @@ raises no banners of its own: the host is the one channel. Read
 [the events reference](references/events-and-notifications.md) for mapping an existing
 log, retention and notification policy.
 
+An agent that calls paid models reports **what it spent**: one receipt per call from the
+provider's own usage numbers, served behind the token at `surfaces.usage` as the DEC-0021 usage
+report. An unknown cost is null, never 0. Read [the usage reference](references/usage.md)
+before wiring it.
+
 ## Step 6 — verify
 
 Run the probe against the live service — it reads the descriptor, then checks every

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

@@ -1,5 +1,31 @@
 # Lifecycle — supervisor, install, release layout, state
 
+This page implements the organization's
+[product lifecycle contract](https://github.com/passioncode-ai/fabric-workspace/blob/main/knowledge/lifecycle.md)
+(rules LC-01…LC-15) for `fabric-service/0.1` services. Where the two differ, the contract
+wins and this page is the defect. The rule each section serves:
+
+| Contract rule | Here | Kit (Python / Node) |
+|---|---|---|
+| LC-01 quit reaches exit within a deadline | [Shutdown](#shutdown) | `Drain` / `Drain` |
+| LC-03 a job is bounded and exclusive | [one copy under launchd](#one-copy-under-launchd) | `hold_single_instance` / `holdSingleInstance` |
+| LC-09 the footprint is declared | the descriptor and the plist; the service's own `AGENTS.md` names its label and port | `write_descriptor`, `launchd_plist` |
+| LC-11 previous release kept, older pruned | [Install, upgrade, uninstall](#install-upgrade-uninstall) | `prune_releases` / `pruneReleases` |
+| LC-12 every file is bounded | [Logs](#logs) | `RotatingLog`, `cap_stdout_log` / `RotatingLog`, `capStdoutLog` |
+| LC-14 operator intent wins; uninstall is symmetric | [Install, upgrade, uninstall](#install-upgrade-uninstall) | `launchd_install`, `launchd_uninstall` (Python) |
+| LC-15 builds clean up after themselves | release pruning runs inside the installer, not later | `prune_releases` / `pruneReleases` |
+
+## Contents
+
+- [launchd plist](#launchd-plist-generate-it-with-launchd_plist)
+- [Install, upgrade, uninstall](#install-upgrade-uninstall)
+- [One copy under launchd](#one-copy-under-launchd)
+- [Directories](#directories)
+- [Logs](#logs)
+- [Shutdown](#shutdown)
+- [Being managed by a host lifecycle broker](#being-managed-by-a-host-lifecycle-broker)
+- [Linux](#linux)
+
 ## launchd plist (generate it with `launchd_plist`)
 
 | Key | Value | Why |
@@ -9,9 +35,9 @@
 | `RunAtLoad` | `true` | back at every login |
 | `KeepAlive` | `true` | `{SuccessfulExit:false}` leaves a cleanly exited service down |
 | `ThrottleInterval` | `10` | bounds a crash loop |
-| `ExitTimeOut` | drain time + margin (40 s default) | SIGKILL arrives after it |
+| `ExitTimeOut` | above the drain and its hard exit (15 s default; `Drain` ends by 10 s) | SIGKILL arrives after it, so it must never come first |
 | `ProcessType` | `Standard` — never `Background`, and no `Nice` > 0 or `LowPriorityIO` | a host probes the service and agents call it while the Mac is busy; a background job is starved for tens of seconds under load and every host reports an outage that never happened (the probe's `lifecycle.priority` rule fails it) |
-| `EnvironmentVariables` | `PATH` set explicitly; `*_FILE` paths to secrets | never a secret value — the plist is world-readable in backups |
+| `EnvironmentVariables` | `PATH` set explicitly; `*_FILE` paths to secrets; `FABRIC_SERVICE_SUPERVISOR=launchd` | never a secret value — the plist is world-readable in backups; the supervisor marker is how the lock knows to back off |
 | `StandardOutPath`/`StandardErrorPath` | `~/Library/Logs/<id>/service.log` | one place the host tails |
 
 ## Install, upgrade, uninstall
@@ -19,17 +45,41 @@
 1. Build or unpack the release into `~/.local/share/<id>/releases/<version>-<sha12>/`
    (a venv or `node_modules` inside it). Never edit a release after it is written.
 2. `write_descriptor` (port and id claims are checked here).
-3. `launchd_install`: write + `plutil -lint`, `enable`, `bootout` and wait until
-   `launchctl print gui/<uid>/<label>` fails, `bootstrap` with up to five retries,
+3. `launchd_install`: write + `plutil -lint`, read `launchctl print-disabled gui/<uid>`,
+   `enable` **only when no override is recorded** (a first install), `bootout` and wait
+   until `launchctl print gui/<uid>/<label>` fails, `bootstrap` with up to five retries,
    then poll the well-known document until it answers with this `id.instance`.
 4. Upgrade = new release, rewrite the plist with the new path, `launchd_install`
-   again. Keep the previous release for rollback; prune older ones by count.
-5. Uninstall = `launchd_uninstall` + `remove_descriptor`. Data stays.
-
-A host stops a service with `bootout` **and** `disable` (off survives a login) and
-starts it with `enable` + `bootstrap`; restart is `kickstart -k`. The service never
+   again, then `prune_releases(releases_dir, current=<new release>)`: the running release
+   and the one before it stay for rollback, older ones go (LC-11, LC-15).
+5. Uninstall = `launchd_uninstall` + `remove_descriptor`. Data stays; `purge=True`
+   (with `service_id`) removes data, logs and cache when the operator asks.
+
+**The operator's intent wins (LC-14).** A host stops a service with `bootout` **and**
+`disable` (off survives a login) and starts it with `enable` + `bootstrap`; restart is
+`kickstart -k`. An install or upgrade never re-enables a label the operator disabled: it
+rewrites the plist, so the new release is what starts once they turn it back on, and
+answers `{"disabled": true, ...}` instead of the well-known document. `force_enable=True`
+is for an operator who asked for the service to be switched on. The service never
 implements these verbs itself — its CLI calls launchctl the same way.
 
+**Uninstall is symmetric.** `launchd_uninstall` boots the job out and **waits** until
+launchd reports it gone (it raises, removing nothing, if the job is still loaded at the
+timeout), removes the plist, and resets the override to `enabled`. launchctl has no verb
+that deletes an override, and a leftover `disabled` would make a later fresh install stay
+off. Tests use a throwaway label or a fake `launchctl` first on `PATH` — never the
+operator's real jobs.
+
+## One copy under launchd
+
+Started by hand, a copy that finds `service.lock` held prints one sentence naming the
+holder and exits 75 at once. Under launchd that exit is a respawn every `ThrottleInterval`
+(10 s), forever. So a copy whose plist carries `FABRIC_SERVICE_SUPERVISOR=launchd` backs
+off in-process — 0.5 s doubling to 30 s, 300 s in all — takes over if the holder leaves,
+and exits 75 only when the wait runs out: a few starts an hour instead of 360. It touches
+nothing while it waits. Two installs sharing one data directory are still the defect to
+remove; the back-off only stops the loop from costing the machine.
+
 ## Directories
 
 | What | macOS | Linux |
@@ -46,15 +96,28 @@ anything the operator would miss belongs in data.
 
 ## Logs
 
-One structured log (JSON lines) rotated by size (5 × 5 MB is a sane default) plus the
-launchd stdout file, truncated at start. Configure logging once, in the entry point.
-Never log a token, a cookie, a login code or a request body that may carry one.
+One structured log (JSON lines) rotated by size — `RotatingLog(dirs["logs"] / "service.jsonl")`,
+5 × 5 MB by default, files 0600 in a 0700 directory — plus the launchd stdout file, which
+`cap_stdout_log` copies to `.1` and truncates at start once it passes 5 MB (launchd holds it
+open for append, so it is truncated in place, never renamed). Configure logging once, in the
+entry point. Never log a token, a cookie, a login code or a request body that may carry one.
 
 ## Shutdown
 
 On `SIGTERM`: stop accepting new work, append a `service.stopping` event, drain
-in-flight work until `ExitTimeOut` minus a margin, persist what was interrupted so the
-next start resumes it, release the lock, exit 0.
+in-flight work, persist what was interrupted so the next start resumes it, release the
+lock, exit 0 — within 10 s with work in flight (LC-01). `Drain` does the timing:
+
+```python
+drain = fs.Drain()                       # drain 8 s, hard exit 2 s later (EXIT_HARD_STOP, 70)
+drain.install(lambda drained: server.shutdown(),
+              on_stopping=lambda: log.append("service.stopping", "info", "Stopping."))
+with drain.work():                       # raises fs.Stopping once a stop has begun -> answer 503
+    handle(request)
+```
+
+Work longer than the drain is journalled before it starts and resumes on the next start;
+it is never a reason to raise the deadline.
 
 ## Being managed by a host lifecycle broker
 

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

@@ -1,7 +1,7 @@
 # fabric-service/0.1 — wire reference
 
-Pinned to `fabric-agent-contract` commit `2ce392291c6668598d12cd38327e24696b5ca15c`
-(`docs/specification/service.md`, DEC-0015). The contract's schemas are normative;
+Pinned to `fabric-agent-contract` commit `23f9fda4c05f8a3852246ee98d4f2adf74ed0875`
+(`docs/specification/service.md`, DEC-0015; the usage report DEC-0021). The contract's schemas are normative;
 this page is the working summary. Extension key:
 `https://fabric.passioncode.ai/agent-contract/extensions/service/0.1`.
 
@@ -47,7 +47,8 @@ No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
 - `status`: `starting | ready | degraded | stopping`. No answer means `down`.
 - `build` needs `commit` or `digest` (`sha256:<64 hex>`).
 - `summary`: at most six tiles; `attention: true` counts toward the host's badge.
-- `surfaces.events` is required; `dashboard` and `mcp` when the service has them.
+- `surfaces.events` is required; `dashboard` and `mcp` when the service has them; `usage`
+  (DEC-0021) when the service reports its spend — see [the usage reference](usage.md).
 
 ## Events page — `GET /fabric/v1/events?after=<cursor>&limit=<n>`
 
@@ -81,3 +82,4 @@ single use, at most 120 s, recorded as used before it is honoured. `GET` that UR
 | `FAC-SEM-010` | no two descriptors claim one port or one `id.instance` |
 | `FAC-SEM-011` | `ready` carries no degraded source |
 | `FAC-SEM-012` | commands start with an absolute or `~/` executable |
+| `FAC-SEM-025` | a usage report adds up; an all-unpriced row costs `null`, not `0` (DEC-0021) |

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/surfaces-and-auth.md

@@ -6,6 +6,12 @@
   origin, stateless JSON responses unless the tools stream.
 - Authenticate with the service token in the declared header. OAuth is for remote
   multi-user servers, not for a loopback service.
+- **Or keep the two roles apart (DEC-0024).** The descriptor's token is the host's: it reads
+  events and the usage report, and it mints operator login codes. An MCP token sits in every
+  client's `~/.claude.json`. When that matters, give agents their own token (`service.token`
+  for agents, `host.token` named by the descriptor), declare `surfaces.mcp.auth: "own"`, and
+  make `/mcp` refuse the host's token. `check_service.py` then checks only that refusal
+  (`interop.mcp-own-auth`) and leaves the caller rules NOT_RUN.
 - Register it into a client config with the service's own command
   (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
   atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token

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

@@ -0,0 +1,63 @@
+# Usage report — what the agent spent (DEC-0021)
+
+Fabric Agent Contract DEC-0021, `docs/specification/service.md` → *Usage report*, schema
+`schemas/service-usage.schema.json`. Optional. A service that calls paid models or tools should
+offer it, so Fabric Dashboards (Spend, MCP `spend`) and Fabric can show each agent's spend beside
+its health without knowing any provider.
+
+## What to record
+
+One **receipt per model call**, built from the numbers the provider returned:
+
+```python
+receipt = fs.make_usage_receipt("anthropic", "claude-sonnet-5-5",
+                                input_tokens=u.input_tokens, output_tokens=u.output_tokens,
+                                cache_read_tokens=u.cache_read_input_tokens or 0,
+                                cost_usd=charged, cost_basis="provider")   # or "price-list"
+ledger.record(receipt)                     # fs.JsonlUsageLedger(data / "usage.jsonl")
+```
+
+```js
+ledger.record(k.makeUsageReceipt('openrouter', model, { inputTokens, outputTokens, costUsd: usage.cost ?? null }));
+```
+
+- **The provider's own numbers.** Take tokens from the response's usage block, not from a local
+  estimate. The cost is `provider` when the provider reported the charge (OpenRouter `usage.cost`,
+  a billing API) and `price-list` when you computed it from a published price list.
+- **Unknown is `None`/`null`, never `0`.** A local model, or a provider that reports no price,
+  records `cost_usd=None`. The report counts it in `unpricedCalls`, and a host shows a lower bound
+  («≥ $x») or «unknown». A call that is really free (a template, a cached answer) records
+  `cost_usd=0.0` with `price-list`.
+- **No content.** A receipt carries no prompt, output, caller or user id. The kits accept only the
+  fields above.
+- If the service already keeps a ledger (a jobs table with token counts), build the receipts from
+  it and pass them to `usage_report(...)`. That avoids a second store.
+
+## What to answer
+
+Declare the surface in the well-known document and serve the report behind the service token:
+
+```python
+surfaces={..., "usage": {"path": fs.USAGE_PATH}}          # "/fabric/v1/usage"
+# GET /fabric/v1/usage, token required:
+return send(200, ledger.report(service_id=ID, instance=INSTANCE, budget={"period": "month", "limitUsd": 100}))
+```
+
+`usage_report` / `usageReport` give the last 31 UTC days, oldest first, per provider and model,
+with day totals that are the sums of the model rows (`FAC-SEM-025`). Days without calls are
+left out.
+
+**Budget.** Pass `budget` only if the service **enforces** that limit itself. The report states
+it, and the host only shows it.
+
+Call `ledger.prune()` at start (or daily) to keep the file at the reported window (LC-12).
+
+`JsonlUsageLedger` appends 0600 JSON lines. A line torn by a killed writer is skipped, and the
+next receipt never glues onto it.
+
+## 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
+`sample_service.py` serves one. Fabric Dashboards → **Spend** shows it within a minute of opening
+the page.