@passioncode-ai/fabric-agent-adapter 0.6.3 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## 0.8.0 - 2026-10-04
+
+Agents report what they spend (Fabric Agent Contract DEC-0021), and a service may keep its MCP
+credential apart from the host's token (DEC-0024). The contract pin moves to the DEC-0024 merge;
+bundles issued under the DEC-0021, DEC-0020 and DEC-0019 revisions stay valid.
+
+### Added
+
+- **Usage report in both kits.** `make_usage_receipt` / `makeUsageReceipt` record one model call
+  from the provider's own numbers (no prompt, output or caller). `usage_report` / `usageReport`
+  build the `service-usage.schema.json` answer: 31 UTC days per provider and model, day totals
+  that are the sums of the rows (FAC-SEM-025), and an unknown cost as `null`, never `0`.
+  `JsonlUsageLedger` keeps receipts as 0600 JSON lines pruned to the window. A line torn by a
+  killed writer is skipped and never glued to the next receipt. The Python and Node twins
+  produce the same report from the same receipts (`test/fixtures/usage/receipts.json`).
+- `sample_service.py` declares `surfaces.usage` and serves the report behind the token.
+- `check_service.py` adds `usage.requires-token` and `usage.report` when a service declares the
+  surface.
+- `references/usage.md`; SKILL.md Step 5 and the protocol reference name the surface; trigger
+  and scenario evals `agent-reports-its-own-spend`.
+
+### Added (DEC-0024)
+
+- **A service may keep its MCP credential apart from the host's token.** When the well-known
+  document says `surfaces.mcp.auth: "own"`, `check_service.py` no longer calls MCP with the
+  descriptor's token as a caller. It checks that the surface refuses that token
+  (`interop.mcp-own-auth`) and leaves the caller rules NOT_RUN with the reason. Before this, two
+  services that separate the roles on purpose were reported as `interop.tools-match` FAIL
+  (401/403). `references/surfaces-and-auth.md` explains when to do it. The contract pin moves to
+  `23f9fda4c05f8a3852246ee98d4f2adf74ed0875`; `9091d3d` joins the supported earlier revisions.
+
+### Fixed
+
+- **MCP 2026-07-28 standard headers.** The probe's MCP calls now send `Mcp-Method`, and `Mcp-Name`
+  for `tools/call`. Without them a server on the official 2026-07-28 SDK answers HTTP 400 (seen live
+  against a local agent on 2026-10-04: `tools/list failed: HTTP 400 from /mcp`).
+  `fabric_interop.McpToolServer.handle(message, headers)` checks them the way the specification
+  requires: a mismatch is refused with `-32020` whatever the revision, and a request that declares
+  2026-07-28 must carry them. Callers that pass no headers keep the old behaviour.
+  `mcp_header_problem` / `mcp_request_headers` are in both kits (Node: `mcpHeaderProblem`,
+  `mcpRequestHeaders`). The sample service answers a mismatch with HTTP 400.
+
+### Changed
+
+- Contract pin `df55c8c` → `9091d3d` (lock, scaffolder default, metadata). The supported earlier
+  revisions are now a reviewed list of two, `test/validate.py` checks it, and
+  `test_contract_revisions` runs against real checkouts of `2ce3922` and `9091d3d`.
+
+## 0.7.0 - 2026-10-04
+
+The service kit meets the organization's
+[product lifecycle contract](https://github.com/passioncode-ai/fabric-workspace/blob/main/knowledge/lifecycle.md)
+(LC-01…LC-15). Findings F7, F8, F9, F16 of the 2026-10-03 lifecycle audit.
+
+### Fixed
+
+- **An upgrade no longer switches back on a service the operator switched off (LC-14, F7).**
+  `launchd_install` called `launchctl enable` on every run. It now reads `launchctl
+  print-disabled` and enables only on a first install (no override recorded); a disabled label
+  stays disabled and unloaded, its plist is still rewritten, and the answer is
+  `{"disabled": true, ...}`. `force_enable=True` is the operator's explicit switch-on.
+  Tests: `test_fabric_service_lifecycle.LaunchdInstallTests` (fake `launchctl`, throwaway labels).
+- **A duplicate copy under `KeepAlive` no longer respawns every 10 s (LC-03, F8).** A
+  launchd-supervised copy (`FABRIC_SERVICE_SUPERVISOR=launchd`, now written by `launchd_plist`)
+  backs off in-process on a held lock — 0.5 s doubling to 30 s, 300 s in all — takes over if the
+  holder leaves, and exits 75 only then. Started by hand it still exits 75 at once (the contract's
+  one-copy rule). Python and Node. Tests: `SupervisedLockTests`, `fabric-service-lifecycle.test.mjs`.
+- **Uninstall is symmetric with install (LC-14, F9).** `launchd_uninstall` waits until launchd
+  reports the job gone (raises, removing nothing, at its timeout), removes the plist, resets the
+  override to `enabled`, and with `purge=True` removes the service's data, logs and cache. It now
+  returns a summary dict instead of `None`. Tests: `LaunchdUninstallTests`.
+- **The installers leave launcher-managed hub links alone (F16).** `install.sh` and
+  `npx @passioncode-ai/fabric-agent-adapter` (even with `--force`) skip a `~/.agents/skills/<name>`
+  that is a symlink, naming `npx @passioncode-ai/passioncode@latest update` when it points into
+  `~/.passioncode`. Tests: `test_installer.InstallerTests.test_launcher_managed_hub_links_survive_force`,
+  `test_install_sh_leaves_launcher_links_alone`.
+
+### Added
+
+- **`Drain` (Python and Node, LC-01, F9):** SIGTERM/SIGINT stops new work (`work()` raises
+  `Stopping`), drains in-flight work for 8 s, hands over, and hard-exits (`EXIT_HARD_STOP`, 70)
+  2 s later if the hand-over hangs. `sample_service.py` uses it and answers `503` while stopping.
+- **`RotatingLog` and `cap_stdout_log` / `capStdoutLog` (LC-12, F9):** JSON-lines log rotated by
+  size, 5 × 5 MB, files 0600 in a 0700 directory; the launchd stdout file is capped at start.
+- **`prune_releases` / `pruneReleases` (LC-11, LC-15):** keeps the running release and the one
+  before it, removes older ones, never removes `current` after a rollback.
+
+### Changed
+
+- **CO-193 contract adoption (source, pending release):** new bundles use the shared
+  capability-name schema and accept underscore names. Complete previously issued bundles
+  remain checkable at their explicitly supported legacy revision. The checker rejects
+  forged locks, revision mismatches and modified checkouts; unavailable dependencies remain
+  `NOT_RUN`. This adds no COM runtime, grant or admission authority.
+- Align validation triggers with the operator's 2026-09-25 CI policy: replace automatic
+  push/PR runs with manual dispatch, retaining the reusable release-validation workflow.
+  Existing test jobs and commands are unchanged; no new nightly schedule is asserted.
+
+- `launchd_plist`'s default `ExitTimeOut` is 15 s (was 40): above the drain and its hard exit, so
+  launchd's SIGKILL never comes first, and inside LC-01's 10 s quit bound for the service itself.
+- `references/lifecycle.md` links the org contract and maps each LC rule to the kit.
+- Three scenario evals: `operator-off-survives-upgrade`, `duplicate-under-keepalive`,
+  `stop-drains-and-uninstall-is-symmetric`.
+
 ## 0.6.3 - 2026-10-04
 
 ### Changed
@@ -348,4 +452,3 @@ Fabric Agent Contract DEC-0017. **Contract pin** moves from `a22dea3` to `9cd778
 - Add a standard-library project inspector, non-destructive scaffolder, and checker.
 - Add contract pinning and independent conformance gate reporting.
 - Add trigger/scenario evals, unit tests, repository validator, and plugin packaging.
-

package/README.md

@@ -188,15 +188,38 @@ Scaffolding is non-destructive by default. It writes only the paths declared in
 
 ## Contract pin
 
-The one pin is [`fabric-contract.lock.json`](fabric-contract.lock.json):
+The default pin for new bundles is [`fabric-contract.lock.json`](fabric-contract.lock.json):
 
 - version: `0.1.0`
-- commit: `2ce392291c6668598d12cd38327e24696b5ca15c`
+- commit: `23f9fda4c05f8a3852246ee98d4f2adf74ed0875`
 
-Every other mention of the contract revision — this section, the skills' metadata, the
+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
-where one does not. The contract repository is normative. Updating the pin requires a
-new adapter release, fixture review, and a complete validation run.
+where one does not. The sole live legacy exception is the immutable
+`SUPPORTED_CONTRACT_COMMITS` declaration in the scaffolder: previously issued bundles
+keep their selected legacy lock and require that exact clean contract checkout. The
+checker validates the lock's contract, repository, version and supported full SHA before
+running its selected schema. Unknown locks, modified checkouts and revision mismatches fail.
+Missing checkouts or dependencies are `NOT_RUN`, never admission.
+
+There is no automatic upgrade or downgrade. An intentional migration requires review of
+the whole bundle and validation against the new selected schema; editing a lock alone
+does not prove runtime compatibility. Underscore names such as `receive_project_message`
+are declarations only: they confer no COM grant or authority. Legacy revisions cannot
+validate those names. The contract repository is normative. Updating the default pin
+requires fixture review, complete validation and a new adapter release before propagation.
+
+To run both compiled-schema integration arms, install the frozen dependencies in separate
+clean checkouts at the supported revisions, then run:
+
+```bash
+FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/current-contract \
+  python3 -m unittest discover -s test -p test_contract_revisions.py -v
+```
+
+Without both environment variables, those tests explicitly skip as `NOT_RUN`.
+This source checkout is 0.8.0 pending release (0.7.0 was never released); the verified published GitHub/npm version
+on 2026-10-04 is 0.6.3. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/bin/fabric-agent-adapter.js

@@ -48,6 +48,15 @@ function copyDir(src, dest) {
   }
 }
 
+// A link in the hub belongs to whoever made it: 'launcher' for the PassionCode launcher's
+// ~/.passioncode/... links, 'other' for any other link, null for a directory or nothing.
+function linkOwner(dest) {
+  let info;
+  try { info = fs.lstatSync(dest); } catch { return null; }
+  if (!info.isSymbolicLink()) return null;
+  return fs.readlinkSync(dest).split(path.sep).includes('.passioncode') ? 'launcher' : 'other';
+}
+
 function pluginInstalled(home) {
   try {
     const data = JSON.parse(fs.readFileSync(path.join(home, '.claude/plugins/installed_plugins.json'), 'utf8'));
@@ -129,6 +138,15 @@ function main(argv) {
   const destRoot = target === 'claude' ? path.join(home, '.claude', 'skills') : path.join(home, '.agents', 'skills');
   for (const name of names) {
     const dest = path.join(destRoot, name);
+    const owner = linkOwner(dest);
+    if (owner) {
+      // One owner per artefact on disk: a plain copy over someone else's link freezes the skill
+      // at this version, and its owner stops updating it. --force does not override this.
+      console.log(owner === 'launcher'
+        ? `skip: ${name} at ${dest} is managed by the PassionCode launcher — update it with: npx @passioncode-ai/passioncode@latest update`
+        : `skip: ${name} at ${dest} is a link managed elsewhere — remove the link first to install a copy here`);
+      continue;
+    }
     if (fs.existsSync(dest) && !force) {
       console.log(`skip: ${name} already installed at ${dest} (rerun with --force to overwrite)`);
       continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.6.3",
+  "version": "0.8.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.",
-  "version": "0.6.3",
+  "version": "0.8.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.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/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/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/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/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/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