@passioncode-ai/fabric-agent-adapter 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # Changelog
 
+## 0.19.0 - 2026-10-12
+
+Settings backups, every spending limit and the feed client's token header in both kits. These are the
+service-side surfaces the pinned contract already carries: DEC-0025 and DEC-0027 (FAA-13).
+
+### Added
+
+- **Settings backups (`fabric-settings-backup/1`, FAC-SEM-035).** Each function exists in both kits.
+  - **Location.** Snapshots live under `<root>/settings-backups/<id>/<instance>/`, outside the data directory.
+    `<root>` is per system: `~/Library/Application Support/PassionCode`, `%APPDATA%\PassionCode` or
+    `$XDG_CONFIG_HOME/PassionCode`.
+  - **Writing.** `make_settings_backup` builds a snapshot from allow-listed tables of JSON scalars. It refuses
+    secret tables, credential columns and fractions.
+  - `write_settings_backup` writes atomically, 0600 in a 0700 folder.
+    - It does not rewrite an unchanged snapshot.
+    - It removes a temporary file an interrupted write left behind.
+    - It keeps the 14 newest snapshots.
+  - `backup_due` decides when the next snapshot is due.
+  - **Reading.** `read_settings_backup` refuses a damaged file and names why.
+  - `newest_intact_backup` skips damaged files and empty snapshots.
+  - `restore_plan` adds rows and never overwrites them. It names what it drops, leaves to defaults or refuses.
+  - **The checksum** uses the settings canonical form: `settings_canonical_json` and `settings_backup_digest`.
+    They are checked against the contract's vectors.
+  - **Parity.** Both kits write byte-identical files.
+- **Every spending limit (DEC-0027, FAC-SEM-031).**
+  - `usage_report` and `usageReport` take a `budgets` list.
+  - A machine day or month limit is counted from the receipts, so it always agrees with `budget`.
+  - A per-order limit gets `spentUsd: null`.
+  - The report is refused when its limits break FAC-SEM-031.
+  - `usage_limit_problems` and `usageLimitProblems` check a report.
+- **The feed client (FAC-SEM-036).** `token_header` and `tokenHeader` give the one header the descriptor
+  declares. `check_service.py` now sends its token through it.
+- **An independent review found 20 moderate defects; all are fixed with tests.**
+  - **The readers follow the schema exactly**, and the two kits accept the same files:
+    - a trailing newline is refused (Python matches a whole string now);
+    - a timestamp is any RFC 3339 date-time with a real calendar date, including an offset;
+    - a string holds at most 1 MiB and a row at most 512 values;
+    - every `extensions` key is a URI;
+    - NaN is refused;
+    - in Node, invalid UTF-8 and a `1.0` integer are refused the way Python refuses them.
+  - **A damaged file never stops anything.** The scan skips it, the digest does not crash, a damaged newest file
+    does not suppress a good snapshot, and an impossible file name makes a snapshot due.
+  - **Safer writes:**
+    - only a temporary file older than an hour is removed;
+    - the snapshot just written is never pruned, even after the clock steps back.
+  - **The restore preview** refuses a key the snapshot holds twice.
+  - **Limits:**
+    - a machine limit over a rolling window is counted from the receipts;
+    - a limit that is not an object is refused.
+  - **Both descriptor validators** check `auth.header` and `auth.scheme` the way the schema does.
+- **Tests.**
+  - The contract's fixtures at the pin are copied to `test/fixtures/contract/dec-0025-0027/`.
+  - The Windows CI job runs both kits' new cases.
+  - Mutation testing: 79 planted defects, all caught.
+- **Docs.**
+  - `references/settings-backups.md` is new.
+  - `usage.md` covers every limit.
+  - `events-and-notifications.md` covers reading a feed.
+  - Updated: `SKILL.md` step 5 and the lifecycle reference's directory table.
+  - The scenario eval `settings-backups-and-every-limit` and two triggers came first.
+
+## 0.18.0 - 2026-10-12
+
+Services on Linux and Windows in both kits (contract DEC-0032, DEC-0033; FAA-21): the supervisor files the
+contract names, and the Node kit on Windows.
+
+### Added
+
+- **The supervisor writers, in both kits.** They write byte-identical files, and a test holds them to that.
+  - **Linux — a systemd user unit.** `systemd_unit` / `systemdUnit` writes `Restart=always`, `RestartSec=10`,
+    `TimeoutStopSec` above the drain, `WantedBy=default.target` and `FABRIC_SERVICE_SUPERVISOR=systemd`.
+    `systemd_install` / `systemdInstall` runs `daemon-reload` and `enable --now`. `systemd_uninstall` /
+    `systemdUninstall` runs `disable --now`, removes the unit, then runs `daemon-reload`.
+  - **Windows — a per-user Scheduled Task.** `task_xml` / `taskXml` writes a logon trigger, least privilege,
+    restart every minute on failure, no time limit and `IgnoreNew`. `task_install` / `taskInstall` runs
+    `schtasks /Create` from a UTF-16 file it then removes, then `/Run`. `task_uninstall` / `taskUninstall` runs
+    `/End`, then `/Delete`.
+  - **No secret in a supervisor file.** The writers refuse a credential-shaped argument, environment name or
+    value, and any control character.
+  - **An upgrade restarts what runs; the operator's off stays off (LC-14).** A unit that `is-enabled` reports
+    disabled, or a task whose settings say `Enabled false`, is rewritten and left off unless `force_enable`.
+  - **Checked by the real readers:** `systemd-analyze verify` on the Linux job (a quoted `WorkingDirectory=` is
+    refused there, so it is written unquoted), and `schtasks /Create` of a throwaway task on the Windows job.
+- **The Node kit on Windows and Linux:**
+  - `servicesDir` and `serviceDirs` use `%LOCALAPPDATA%`.
+  - `expand` and `validateDescriptor` match the Python kit: all four managers, `unit` and `task` paired with
+    their manager, Windows paths, never a network share.
+  - The token file gets a protected ACL: written with `icacls`, read with Windows PowerShell 5.1. A refusal
+    names the SID.
+  - The instance lock is a named pipe on Windows (an abstract socket on Linux, as before).
+- **One copy across the kits.** The Python kit holds the Node kit's lock name (`lock_name` / `lockName`)
+  beside its file lock, so the two kits exclude each other on every system. `check_service.py` now reports the
+  lock as held when a Node service holds it. Before this release it failed every Node service on Linux.
+- **A copy under systemd backs off on a held lock** as one under launchd does (`supervised()`).
+- **The Windows CI job** runs the Node kit's platform, supervisor and service tests and the Python supervisor
+  tests.
+- **Docs:**
+  - `references/lifecycle.md`, *Linux and Windows*: the verbs per system and the Windows directories.
+  - `SKILL.md` step 4.
+  - `protocol.md`.
+
+  The scenario eval `linux-and-windows-supervision` and two triggers came first.
+- **The probe only looks** (`/proc/net/unix`, `WaitNamedPipeW`) and never takes the lock's name.
+- **An independent review** found 2 critical and 9 moderate defects before release; each is fixed with a test, except
+  that a Scheduled Task still cannot tell the service it is supervised (a task sets no environment; documented).
+- **Mutation testing:** 14 planted defects in the Python writers, 23 in the Node port, 7 in the lock name
+  and probe and a quoted `WorkingDirectory=` against `systemd-analyze` were all caught.
+
 ## 0.17.0 - 2026-10-12
 
 The organisation's lifecycle rules LC-19 and LC-21 apply to what the adapter ships and checks (FAA-22, FAA-23):

package/README.md

@@ -230,8 +230,8 @@ FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/curren
 ```
 
 Without both environment variables, those tests explicitly skip as `NOT_RUN`.
-This source checkout is 0.17.0. 0.16.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
-were never released); 0.17.0 is published by its `v0.17.0` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.19.0. 0.18.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
+were never released); 0.19.0 is published by its `v0.19.0` tag. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.17.0",
+  "version": "0.19.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.17.0",
+  "version": "0.19.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ 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.17.0"
+  version: "0.19.0"
   contract-version: "0.1.0"
   contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
 ---

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

@@ -13,10 +13,10 @@ description: >-
   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.
 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.
+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.17.0"
+  version: "0.19.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
@@ -190,10 +190,14 @@ The installer, not the service, owns the plist and the descriptor. Sequence:
 4. After an upgrade, `prune_releases(releases_dir, current=…)` keeps the running release
    and the one before it.
 
+On Linux the supervisor is a systemd user unit (`systemd_unit` + `systemd_install`), on
+Windows a per-user Scheduled Task (`task_xml` + `task_install`); the Node kit has the same
+writers (`systemdUnit`, `taskXml`, …) and both kits write identical files.
+
 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)
 for the plist fields, the release layout, log rotation, behaving under a host lifecycle broker
-and the Linux case.
+and the Linux and Windows supervisors.
 
 ## Step 5 — the dashboard and the events
 
@@ -224,8 +228,12 @@ 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.
+report. An unknown cost is null, never 0. It lists **every** spending limit the service applies
+in `budgets`, enforced or not. Read [the usage reference](references/usage.md) before wiring it.
+
+A service whose store holds what the operator decided keeps **settings backups** outside its data
+directory, restores only on a fresh database and never overwrites. Read
+[the settings backups reference](references/settings-backups.md).
 
 ## Step 6 — verify
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/events-and-notifications.md

@@ -11,6 +11,15 @@
 
 The feed is a view: never copy rows into a second store that can drift from the first.
 
+## Reading a feed (FAC-SEM-036)
+
+A client of `GET /fabric/v1/events` — or of any token-protected route — sends the token in the
+header the descriptor's `auth.header` names, in the form `auth.scheme` names: the raw token for
+`none`, `Bearer <token>` for `Bearer`. Never assume `Authorization: Bearer`: a client that did
+was refused on every poll and silently dropped every notify event. `token_header(auth, token)` /
+`tokenHeader(auth, token)` gives the one header; the token never travels in another header or
+in the URL.
+
 ## Writing an event
 
 - `kind`: dotted, stable, past tense or state (`job.failed`, `job.awaiting_choice`,

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

@@ -8,23 +8,23 @@ 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-03 a job is bounded and exclusive | [one copy under a supervisor](#one-copy-under-a-supervisor) | `hold_single_instance` / `holdSingleInstance` |
+| LC-09 the footprint is declared | the descriptor and the plist, unit or task; the service's own `AGENTS.md` names its label (unit, task) and port | `write_descriptor`, `launchd_plist`, `systemd_unit` / `systemdUnit`, `task_xml` / `taskXml` |
 | 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-14 operator intent wins; uninstall is symmetric | [Install, upgrade, uninstall](#install-upgrade-uninstall), [Linux and Windows](#linux-and-windows) | `launchd_install`, `launchd_uninstall` (Python); `systemd_install` / `systemdInstall`, `task_install` / `taskInstall` and their uninstalls |
 | 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)
+- [One copy under a supervisor](#one-copy-under-a-supervisor)
 - [Directories](#directories)
 - [Logs](#logs)
 - [Shutdown](#shutdown)
 - [Being managed by a host lifecycle broker](#being-managed-by-a-host-lifecycle-broker)
-- [Linux](#linux)
+- [Linux and Windows](#linux-and-windows)
 
 ## launchd plist (generate it with `launchd_plist`)
 
@@ -70,24 +70,25 @@ that deletes an override, and a leftover `disabled` would make a later fresh ins
 off. Tests use a throwaway label or a fake `launchctl` first on `PATH` — never the
 operator's real jobs.
 
-## One copy under launchd
+## One copy under a supervisor
 
 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,
+(10 s), forever, and under systemd one every `RestartSec`. So a copy whose plist or unit
+carries `FABRIC_SERVICE_SUPERVISOR=launchd` (or `systemd`) 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 |
-|---|---|---|
-| data + config | `~/Library/Application Support/<id>/` | `${XDG_DATA_HOME:-~/.local/share}/<id>/` |
-| logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` |
-| cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` |
-| code | `~/.local/share/<id>/releases/…` | same |
+| What | macOS | Linux | Windows (DEC-0032) |
+|---|---|---|---|
+| data + config | `~/Library/Application Support/<id>/` | `${XDG_DATA_HOME:-~/.local/share}/<id>/` | `%LOCALAPPDATA%\<id>\` |
+| logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` | `%LOCALAPPDATA%\<id>\Logs\` |
+| cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` | `%LOCALAPPDATA%\<id>\Cache\` |
+| code | `~/.local/share/<id>/releases/…` | same | under `%LOCALAPPDATA%` too, never a network share |
+| settings backups ([DEC-0025](settings-backups.md)) | `~/Library/Application Support/PassionCode/settings-backups/<id>/<instance>/` | `${XDG_CONFIG_HOME:-~/.config}/PassionCode/settings-backups/…` | `%APPDATA%\PassionCode\settings-backups\…` |
 
 A repository that versions the data itself (a registry, a plan) may hold the data; the
 service's own code checkout and its releases may not. Directories 0700, secret files 0600. A store carries a schema version and the service
@@ -140,8 +141,58 @@ has to survive being driven from outside:
   well-known document for a service, a process-level answer for a plain app — and keep it honest
   while the app is still starting.
 
-## Linux
-
-Until a systemd adapter exists, declare `lifecycle.manager: "none"`. A `systemd --user`
-unit with `Restart=always` gives the same guarantees; the host will control it once the
-adapter ships. Everything else in this skill applies unchanged.
+## Linux and Windows
+
+Both kits write and install the supervisor file the contract names (DEC-0032, service.md
+*Supervisor*); the two kits write byte-identical files. A supervisor file never carries a
+secret: the writers refuse a credential-shaped argument, environment name or value, and any
+control character (a line break would end a unit line early).
+
+**Linux — a systemd user unit.** `systemd_unit(unit, argv, working_directory=…)` /
+`systemdUnit(unit, argv, {workingDirectory})` writes `Restart=always`, `RestartSec=10`,
+`TimeoutStopSec` above the drain (15 s default), `KillMode=mixed`, `WantedBy=default.target`
+and `FABRIC_SERVICE_SUPERVISOR=systemd`, quoting every argument (`%` → `%%`, `$` → `$$`).
+`WorkingDirectory=` is written unquoted: systemd reads it as the rest of the line, so quotes would
+become part of the path and the unit would be refused (`systemd-analyze verify` checks it in CI). The
+descriptor says `"lifecycle": {"manager": "systemd", "unit": "<id>.<instance>.service"}`.
+
+| Verb | Command |
+|---|---|
+| install, upgrade | `systemd_install` / `systemdInstall`: write `~/.config/systemd/user/<unit>`, `daemon-reload`, `enable`, `restart` (so the new unit is what runs). A unit already installed that `is-enabled` reports `disabled` stays off: the file is rewritten and nothing starts (LC-14), unless `force_enable` |
+| stop, keep off | `systemctl --user disable --now <unit>` |
+| uninstall | `systemd_uninstall` / `systemdUninstall`: `disable --now`, remove the unit, `daemon-reload` |
+
+A user unit runs while the person is logged in; one that must run without a session needs
+`loginctl enable-linger <user>`, which is the operator's decision, not the installer's.
+
+**Windows — a per-user Scheduled Task.** `task_xml(task, argv, working_directory=…)` /
+`taskXml(task, argv, {workingDirectory})` writes a task with a logon trigger for the current
+user, `InteractiveToken` and `LeastPrivilege` (no administrator rights), restart on failure
+every minute, no execution time limit and `MultipleInstancesPolicy` `IgnoreNew`, its settings in the
+order `schtasks` exports them; the arguments are quoted the way the C runtime parses them. The Windows
+CI job has the real `schtasks` create, read back and delete such a task. The descriptor says
+`"lifecycle": {"manager": "task-scheduler", "task": "\\PassionCode\\<id>.<instance>"}`.
+
+| Verb | Command |
+|---|---|
+| install, upgrade | `task_install` / `taskInstall`: `schtasks /Create /TN <task> /XML <file> /F` from a UTF-16 file it then removes, then `/End` (when it existed) and `/Run`. A task already installed and disabled stays off: it is recreated and disabled again (LC-14), unless `force_enable` |
+| stop, keep off | `schtasks /End /TN <task>`, then `schtasks /Change /TN <task> /DISABLE` |
+| uninstall | `task_uninstall` / `taskUninstall`: `/End`, then `/Delete /F` |
+
+A task cannot set an environment variable, so a copy Task Scheduler restarts does not back off
+in-process; `IgnoreNew` keeps the scheduler from starting a second copy, and a hand-started copy
+holding the lock makes the scheduled one exit 75 once a minute until it leaves.
+
+**One copy on each system.** The Python kit takes `flock` (Linux) or a locked byte
+(Windows); the Node kit cannot, so it holds a name instead — an abstract unix socket on Linux,
+a named pipe on Windows (`lock_name` / `lockName`), each gone with the process. The Python kit
+holds the same name beside its file lock, so the two kits exclude each other everywhere, and
+`check_service.py` reports the lock held when either is. The probe only looks (`/proc/net/unix`,
+`WaitNamedPipeW`); it never takes the name, so it cannot make a service that is starting fail.
+
+**Token files on Windows.** The privacy of `service.token` is its ACL (service.md *Windows
+token files*): the kits write a protected list — the user, SYSTEM and Administrators, set before the
+token's bytes go in, any entry already there dropped — and refuse
+on read a link, a file outside the profile, another owner, or any other granted SID, naming the
+SID. The Node kit reads the list with Windows PowerShell 5.1 (.NET, no modules) and writes it
+with `icacls`; the path goes through the environment, never a command line.

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

@@ -31,7 +31,7 @@ File `<id>.<instance>.json`, mode 0600 (on Windows a protected ACL), atomic.
 | `name`, `summary` | ≤ 80 and ≤ 200 characters |
 | `origin` | `http://127.0.0.1:<port>`; the port is a machine-wide claim |
 | `auth` | `tokenFile` (0600; on Windows a protected ACL — owner and every granting entry the current user, SYSTEM or Administrators: service.md *Windows token files*, DEC-0032, DEC-0033); `header` default `Authorization` with `scheme` `Bearer`; any other header carries the raw token with `scheme: "none"` |
-| `lifecycle` | `manager` `launchd` (then `label` and `plist`), `systemd` (then `unit`, a `systemctl --user` unit), `task-scheduler` (then `task`, a per-user Scheduled Task) or `none`; `unit` and `task` are refused beside any other manager (DEC-0032). The Python kit and the probe accept all four; the Node kit still accepts only `launchd` and `none` (FAA-16) |
+| `lifecycle` | `manager` `launchd` (then `label` and `plist`), `systemd` (then `unit`, a `systemctl --user` unit), `task-scheduler` (then `task`, a per-user Scheduled Task) or `none`; `unit` and `task` are refused beside any other manager (DEC-0032). Both kits and the probe accept all four; both kits write the unit and the task (`systemd_unit`, `task_xml` / `systemdUnit`, `taskXml`) |
 | `paths` | `data` (required), `logs[]`, optional `config`, `cache` |
 | `commands` | only `doctor` and `update`, argument arrays whose first item is an absolute or `~/` path (Windows: also `C:\…`, `C:/…` or `~\…`, never a network share — DEC-0032) |
 | `source.repository`, `fabricManifest` | optional |

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

@@ -0,0 +1,67 @@
+# Settings backups — what the operator decided survives the data directory (DEC-0025)
+
+Fabric Agent Contract DEC-0025, `docs/specification/service.md` → *Settings backup*, schema
+`schemas/settings-backup.schema.json`, rule `FAC-SEM-035`. A service whose store holds what the operator
+decided — which projects it serves, how each is bound, which secret slot each binding uses, their overrides —
+SHOULD keep settings backups, so a lost, purged or wrongly migrated data directory costs the operator nothing.
+
+## Where
+
+`<root>/settings-backups/<id>/<instance>/settings-<UTC %Y%m%dT%H%M%S%fZ>.json`, outside the data directory:
+
+| System | `<root>` (`settings_backup_root` / `settingsBackupRoot`) |
+|---|---|
+| macOS | `~/Library/Application Support/PassionCode` |
+| Windows | `%APPDATA%\PassionCode` |
+| Linux | `$XDG_CONFIG_HOME/PassionCode`, default `~/.config/PassionCode` |
+
+`settings_backup_dir(id, instance)` / `settingsBackupDir(id, instance)` names the folder. Directories are 0700
+(on Windows a protected ACL), files 0600, writes atomic.
+
+## Take a snapshot
+
+```python
+dirs = fs.settings_backup_dir(ID, INSTANCE)
+if fs.backup_due(dirs):                                   # none yet, or the newest is older than 24 hours
+    doc = fs.make_settings_backup(service_id=ID, instance=INSTANCE, version=VERSION, schema=SCHEMA_VERSION,
+                                  tables=allow_listed_tables(db), reason="start")      # or daily, uninstall, manual
+    fs.write_settings_backup(doc, dirs)                   # None when unchanged; keeps the 14 newest
+```
+
+```js
+const dir = k.settingsBackupDir(ID, INSTANCE);
+if (k.backupDue(dir)) k.writeSettingsBackup(k.makeSettingsBackup({ id: ID, instance: INSTANCE, version, schema, tables, reason: 'daily' }), dir);
+```
+
+- **Tables on an allow-list**, each `{"columns": [...], "rows": [[...], ...]}` of JSON scalars. A fraction is its
+  decimal string (`"0.25"`), binary data is never stored, and an integer stays within ±(2^53 − 1).
+- **Secrets by name only.** `make_settings_backup` refuses a table that can only hold connections, tokens,
+  secrets, credentials, passwords, login codes or sessions, and a column whose name says it holds a credential
+  value (`access_token`, `client_secret`); `secret_name` and `token_slot` pass. The names cannot see values, so
+  back up what is on the allow-list, never everything except a deny-list.
+- **When:** at start when `backup_due`, then daily; on uninstall a last one, read-only (open the store without
+  migrating or writing). An unchanged snapshot is not rewritten; a temporary file an interrupted write left is
+  removed first. A fresh, empty database writes none: it would hide the good snapshot before it is restored.
+- Both kits write byte-identical files (`test/fabric-service-backups.test.mjs`, last case).
+
+## Read and restore
+
+`read_settings_backup` / `readSettingsBackup` refuses a file whose checksum, counts or row widths disagree with
+its tables, that carries a value with no canonical form, or whose `format` it does not know, naming why
+(`FAC-SEM-035`). The checksum is SHA-256 of the settings canonical form of `tables`
+(`settings_canonical_json` / `settingsCanonicalJson`: Python's `json.dumps(sort_keys=True,
+ensure_ascii=False)`).
+
+Restore **adds and never overwrites**:
+
+```python
+path, doc, skipped = fs.newest_intact_backup(dirs)        # the newest intact snapshot with content; damaged ones named
+plan = fs.restore_plan(doc, {"projects": {"columns": [...], "key": ["id"], "required": ["id", "name"],
+                                          "existing": existing_keys("projects")}})
+# plan["tables"]["projects"]: insert, present, droppedColumns, defaultedColumns, missingRequired, refused
+```
+
+- **Automatic restore** only on a *fresh* database — no domain records **and** the service has never started —
+  so a restart never undoes a deletion. Insert `plan[...]["insert"]` and add every row the database refuses to
+  `refused` with its key and reason.
+- **Manual restore** shows the plan first; applying it is the operator's act, never an agent's.

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

@@ -50,6 +50,29 @@ left out.
 **Budget.** Pass `budget` only if the service **enforces** that limit itself. The report states
 it, and the host only shows it.
 
+**Every limit (DEC-0027).** Pass `budgets` to list every spending limit the service applies,
+enforced or not, so the spend view shows all of them — the operator asked for that on 2026-10-07:
+
+```python
+ledger.report(service_id=ID, budget={"period": "month", "limitUsd": 100}, budgets=[
+    {"id": "machine.monthly", "scope": "machine", "kind": "monthly", "period": "month", "limitUsd": 100, "enforced": True},
+    {"id": "project.demo.daily", "scope": "project", "subject": "demo", "kind": "daily", "windowSeconds": 86400,
+     "limitUsd": 5, "spentUsd": 0.31, "enforced": True},
+    {"id": "job.cap", "scope": "job", "kind": "per_job", "limitUsd": 2, "enforced": True},
+])
+```
+
+- A machine limit with a `period` and no `spentUsd` is counted by the kit from the receipts, the
+  way `budget` is, so `budget` and its twin in `budgets` never disagree. A per-order limit
+  (`per_job`, `approval`) gets `spentUsd: null`. Every other limit states its own spend.
+- `scope` is `machine`, `project`, `pool` or `job`; a `project` or `pool` limit names its
+  `subject`. A limit has at most one window — `period`, `windowSeconds` or `since` — and it agrees
+  with the kind (`daily`: the day or 86400 s; `monthly`: the month or 28–31 days; `velocity`: a
+  rolling window). `tripped: true` (work stopped by it now) needs `enforced: true`. An unknown
+  kind is shown generically, never refused.
+- The kits refuse a report that breaks these (`usage_limit_problems` / `usageLimitProblems`,
+  `FAC-SEM-031`). A breach is not refused: the report shows it, and the host shows it first.
+
 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

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

@@ -162,10 +162,9 @@ class Probe:
             conn.close()
 
     def auth_headers(self) -> Dict[str, str]:
-        auth = self.d.get("auth", {})
-        header = auth.get("header", "Authorization")
-        value = self.token or ""
-        return {header: ("Bearer " + value) if auth.get("scheme", "Bearer") == "Bearer" else value}
+        # The header and form the descriptor declares, never an assumed `Authorization: Bearer` (FAC-SEM-036).
+        name, value = fs.token_header(self.d.get("auth"), self.token or "")
+        return {name: value}
 
     # descriptor ------------------------------------------------------------
     def descriptor_rules(self) -> None:
@@ -730,7 +729,7 @@ class Probe:
                     self.add("lifecycle.instance-lock", "PASS", "held by the running service")
                 else:
                     msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
-                    self.add("lifecycle.instance-lock", "FAIL", "%s exists but nobody holds it" % lock)
+                    self.lock_free(lock)
             finally:
                 os.close(fd)
             return
@@ -747,10 +746,17 @@ class Probe:
             self.add("lifecycle.instance-lock", "PASS" if held else "FAIL", "held by the running service" if held else str(exc))
         else:
             fcntl.flock(fd, fcntl.LOCK_UN)
-            self.add("lifecycle.instance-lock", "FAIL", "%s exists but nobody holds it" % lock)
+            self.lock_free(lock)
         finally:
             os.close(fd)
 
+    def lock_free(self, lock: Path) -> None:
+        """The file lock is free; a Node kit service holds the lock's name instead (fs.lock_name)."""
+        if fs.lock_name_held(lock):
+            self.add("lifecycle.instance-lock", "PASS", "held by the running service (the lock's name, %s)" % ("a named pipe" if fs.WINDOWS else "an abstract socket"))
+        else:
+            self.add("lifecycle.instance-lock", "FAIL", "%s exists but nobody holds it" % lock)
+
     def run(self) -> List[Result]:
         self.descriptor_rules()
         if not self.port: