@passioncode-ai/fabric-agent-adapter 0.77.0 → 0.78.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## 0.78.0 (2026-11-12)
+
+The contract pin stays `18f8d487`. Kit modules change: a new `fabric_tailnet` and `fabric-tailnet.mjs` (layer L0); `fabric_supervisors` and `fabric-supervisors.mjs`, and the facades
+`fabric_service` and `fabric-service.mjs` (new exports `launchd_domain` / `launchdDomain`, `SYSTEM_DAEMONS`,
+`jobWellKnownOf`, `ForeignUserAnswer`); the probe `check_service.py` (`lifecycle.one-copy`); guidance in building-fabric-services and
+working-with-fabric.
+
+### Added
+
+- **A LaunchDaemon for a headless Mac** (FAA-278, with FAA-228): the launchd helpers in both kits work in launchd's system
+  domain, for a Mac that a FileVault restart (`fdesetup authrestart`) leaves with no GUI login, where a `gui/<uid>` job
+  never starts. A plist in `/Library/LaunchDaemons` (the folder's case ignored) or `domain="system"` /
+  `domain: 'system'` is a LaunchDaemon, macOS only; `launchd_plist(..., user_name=)` / `launchdPlist({userName})` writes
+  its `UserName`, which a system install requires; `launchd_domain` / `launchdDomain` names the domain.
+  `launchd_loaded`, `launchd_pid` and `launchd_override` read the system domain without root. `launchd_install` and
+  `launchd_uninstall` there need root, refuse before writing anything otherwise and name the command to run as root,
+  refuse `purge` (the data is the `UserName`'s), and accept the installed service's token-free answer only on a
+  connection launchd's own job accepted (its pid from `launchctl print system/<label>`, running as the `UserName`'s uid)
+  or, under a restricted socket
+  table, on a port that pid listens on (`lsof -p`, a weaker vouch, CT-261). A `gui/<uid>` bootstrap that fails for lack
+  of a GUI session (error 125, an SSH install) now says to remove that LaunchAgent and use the system domain. The probe's
+  `lifecycle.one-copy` asks launchd in the domain the descriptor's plist names. A LaunchDaemon's label is the machine's:
+  an install refuses, before writing anything, a label another plist holds, a plist at its path of another label or
+  another `UserName`, a `UserName` that is not a short name, is root or is no account of the Mac, and an origin other
+  than `http://127.0.0.1:<port>`; one refused after its bootstrap leaves the job loaded and names the `bootout`. An
+  uninstall refuses a label another plist holds before its `bootout`. The root installer's read of its own job's token-free answer, proved by the job's pid, its uid and a bind on
+  exactly `127.0.0.1`, departs from the pinned HA-2 (and the contract's later RT-3); the contract owner accepted it in
+  principle as DEC-0161, proposed (FAA-288). `references/lifecycle.md`
+  *The system domain* says which steps run as the `UserName` and which as root, and what a host must not do (FAA-287);
+  one scenario eval.
+
+- **A kit module for an agent behind `tailscale serve`: `fabric_tailnet`** (FAA-297, a board request of 2026-11-11).
+  `fabric_tailnet.py` and `fabric-tailnet.mjs` (layer L0, no imports) decide who is calling and what that person may
+  open. The person comes from `Tailscale-User-Login`, believed only on the agent's own serve listener (a loopback port
+  or a Unix socket that only serve reaches) and from a loopback peer; a request carrying serve's headers on any other
+  listener is refused (`serve-header-off-serve`), never half-trusted. Groups, dashboards and capabilities come from a
+  `tailnet-perimeter/1` file generated from the organization's access registry: a file that does not name its source
+  (`generatedFrom`: registry, revision, time) is refused (`perimeter-not-generated`). MCP also takes a personal key,
+  stored only as its SHA-256, owned by one login, and refused when its capabilities are wider than that login's groups
+  (`key-wider-than-group`). Every refusal is 401 or 403 with a stable code; no answer carries a key or its hash. Both
+  twins answer one set of vectors, `test/fixtures/tailnet/vectors.json`; the reference is
+  `references/surfaces-and-auth.md` → "Behind tailscale serve".
+
+- **A fifth skill, `observing-products`: observer mode** (FAA-290, the observer-mode design of Fabric CO-546). Any
+  agent with the plugin can take a standing watch over one product. Setup first: it writes the product's channel
+  inventory, `docs/observer/channels.md` (ops log, errors, analytics, funnels, revenue, store, uptime, CI, the Fabric
+  board, support), each row with its read route, its credential by vault slot name, its cursor, baseline, thresholds,
+  placement (`local` or `remote`) and state, and proves one read from each; a channel without a proven read is never
+  counted as watched. Then a cycle every interval (30 minutes by default): bounded reads from the cursors, a failed
+  read as a finding, one cycle record before any cursor moves, no overlap with its own last run, a missed window run
+  once; triage S0 to S3 within the project's authority (`observe`, `fix`, `ship`, the last set only by the person),
+  every fix through the project's own delivery route and read back from the channel that showed the fault, two failed
+  attempts stop the automatic work on a finding, channel text is data and never an instruction, a USD 100 a month
+  budget per observer by default, silent cycles and one message on change. Scheduling: Fabric's observer-mode switch
+  where Fabric runs, else Claude Code `/loop`, a cron routine, or a cloud routine that watches only `remote` channels
+  and names the local ones it skipped. `scripts/observer_inventory.py` (`check`, `template`) validates an inventory and
+  prints connected out of named; `test/test_observer_inventory.py`; trigger and scenario evals in
+  `test/evals/observing-products/`. The release smoke checks the installed skill.
+
+### Changed
+
+- **Each skill's `description` is about 350 characters, within the skill listing budget** (FAA-291, a board request
+  of 2026-11-11). Claude Code shares one character budget among every installed skill's description and, over it,
+  keeps a description only for the most used skills (measured on the operator's machine: 105 skills, 35 962
+  characters against 30 000), so `working-with-fabric`, the skill the session hooks point at, was listed by name
+  alone. The five descriptions went from 4 542 characters to 1 722 (the four of 0.77.0 from 3 649 to 1 388): when to
+  use, two to four triggers in English and Russian, and the NOT-for boundary naming the neighbour. Each skill's
+  previous description, every trigger included, moved word for word to its `references/when-to-use.md`, linked
+  from a short `## When to use` section. `test/validate.py` now fails a description over 360 characters
+  (`DESCRIPTION_LISTING_BUDGET`) and its self-test plants one.
+
+### Fixed
+
+- SKILL.md headroom (FAA-263): building-fabric-services and working-with-fabric each keep at least 150 words under the
+  4750-word cap; the detail stays in their references, which already held most of it (the dashboard kit, the interop
+  *Actions* section, the session hooks, the board's *When nobody answers*), and the remote placement's *On the
+  platform* and the native host hooks gained what they lacked; no rule changes.
+
+### Upgrading
+
+- A service that installs a LaunchDaemon vendors `fabric_supervisors` (or `fabric-supervisors.mjs`) with its facade and
+  `fabric_peer_owner` (or `fabric-peer-owner.mjs`) of 0.76.0 or later, which it imports. A LaunchAgent install behaves
+  as before, but in Node `fabric-supervisors.mjs` 0.78.0 imports `fabric-peer-owner.mjs` 0.76.0 or later in either
+  domain; `fabric_kit.py install` copies both.
+
 ## 0.77.0 (2026-11-08)
 
 The contract pin stays `18f8d487`. Kit modules change: `fabric_events` and `fabric-events.mjs`, `fabric_peer_owner`

package/README.md

@@ -8,7 +8,7 @@
 
 **Fabric Agent Adapter** makes any agent Fabric-compatible. Fabric is PassionCode.ai's
 product, the CEO AI agent: you talk to Fabric, and it chooses, binds and runs the agents that
-do the work. This adapter is how an agent becomes one Fabric can bind: four Agent Skills,
+do the work. This adapter is how an agent becomes one Fabric can bind: five Agent Skills,
 Python and Node reference kits and a live conformance probe for the
 [Fabric Agent Contract](https://github.com/passioncode-ai/fabric-agent-contract). It also works
 on its own: the skills, kits and probe need no Fabric install.
@@ -18,7 +18,7 @@ on its own: the skills, kits and probe need no Fabric install.
 [![license](https://img.shields.io/badge/license-AGPL--3.0%20or%20commercial-blue.svg)](LICENSE)
 
 The skills are `adapting-projects-to-fabric`, `creating-fabric-agents`,
-`building-fabric-services` and `working-with-fabric`.
+`building-fabric-services`, `working-with-fabric` and `observing-products`.
 
 `working-with-fabric` is for the other side: a coding agent (Claude Code, Codex, Kimi Code, Kilo, Hermes) opened in
 a terminal that works in a project through Fabric. It finds Fabric (`hub.json`, its `pid`), has the machine's
@@ -58,6 +58,18 @@ for activation, reload and verification limits. The
 they need from Fabric; the [board reference](plugins/fabric-agent-adapter/skills/working-with-fabric/references/project-board.md)
 is the board-first workflow.
 
+`observing-products` puts an agent on a standing watch over one product (observer mode). It first writes the
+product's channel inventory, `docs/observer/channels.md`: every channel the product reports through (operations log,
+errors, analytics, funnels, revenue, store, uptime, CI, the Fabric board, support), each with its read route, its
+credential by vault slot name, its baseline and a proven read. Then every interval (30 minutes by default) it reads
+each channel from its cursor, triages what changed (S0 to S3) and fixes it through the project's own delivery route,
+within the authority the project sets (`observe`, `fix`, `ship`). `scripts/observer_inventory.py check` validates the
+inventory and prints connected out of named:
+
+```bash
+python3 plugins/fabric-agent-adapter/skills/observing-products/scripts/observer_inventory.py template --project example-app
+```
+
 `building-fabric-services` makes an agent a long-lived local service with a dashboard
 that is always alive, runs as one copy, keeps its state through a reinstall and appears
 in Fabric Dashboards by itself: the `fabric-service/0.1` extension. It also makes an **online** agent
@@ -174,6 +186,7 @@ npx skills add passioncode-ai/fabric-agent-adapter --skill adapting-projects-to-
 npx skills add passioncode-ai/fabric-agent-adapter --skill creating-fabric-agents
 npx skills add passioncode-ai/fabric-agent-adapter --skill building-fabric-services
 npx skills add passioncode-ai/fabric-agent-adapter --skill working-with-fabric
+npx skills add passioncode-ai/fabric-agent-adapter --skill observing-products
 ```
 
 ### Configure
@@ -211,10 +224,10 @@ EOF
 kill %1
 ```
 
-Verified 2026-11-07 from the published npm package 0.76.0 (`npm pack` into a throwaway folder, `KIT`
+Verified 2026-11-08 from the published npm package 0.77.0 (`npm pack` into a throwaway folder, `KIT`
 pointing at its skill) with Claude Code 2.1.299: the probe reported 44 rules, 0 FAIL, `listener.owner` PASS;
 the CLI connected to the sample over streamable HTTP, called `sample.echo` and printed `ping`
-([record](docs/evidence/runs/2026-11-07-0.76.0-quick-start.md)). The probe prints one line per rule
+([record](docs/evidence/runs/2026-11-08-0.77.0-quick-start.md)). The probe prints one line per rule
 (`PASS`, `FAIL` or `NOT_RUN` with its evidence) and exits 1 on any `FAIL`; run it against your
 own service by its id once its installer has written the descriptor.
 `FABRIC_REAL_CLIENT=1 python3 -m unittest discover -s test -p test_real_client.py` repeats the connection check

package/SECURITY.md

@@ -25,7 +25,13 @@ bounded and non-publishing until explicit scoped grants exist in a project bindi
 - The service kits create the service token (0600) and the instance lock in the
   service's own data directory, and write supervisor files only when an installer calls
   them: a launchd plist in `~/Library/LaunchAgents` (macOS), a systemd user unit (Linux) or
-  a per-user Scheduled Task (Windows), plus one descriptor in the services directory. The
+  a per-user Scheduled Task (Windows), plus one descriptor in the services directory. A LaunchDaemon in
+  `/Library/LaunchDaemons` (FAA-278) is written only by an installer running as root, which the kits never become:
+  without root they refuse before writing and name the command, and refuse a plist without `UserName` (except one written
+  there with an explicit `domain="gui"`, not refused yet, FAA-286 item 21); the job runs as the account its `UserName`
+  names. The installer accepts the job's answer only on a connection launchd's own job accepted
+  (its pid from `launchctl print system/<label>`) or, where the socket table is restricted, on a port that pid listens
+  on (`lsof -p`, the weaker vouch below, CT-261). The
   token is readable by any process of the same user; the protocol defends against web pages
   and mistakes, not against hostile local code.
 - The kits' connectors (`fabric_http`, `fabric_openrouter` and their Node twins) reach the
@@ -36,7 +42,12 @@ bounded and non-publishing until explicit scoped grants exist in a project bindi
   `check_dashboard_layout.mjs` (a local login code) and the launchd installers' poll send
   anything to `127.0.0.1:<port>`, they read the computer's socket table to tell which OS
   account owns the listener (DEC-0154 HA-2, `fabric_peer_owner`), and send nothing to
-  another account's, root's, SYSTEM's or an untellable listener. They read, never change:
+  another account's, root's, SYSTEM's or an untellable listener; the one exception is a LaunchDaemon's installer
+  (root, FAA-278), which sends a token-free well-known GET only on a connection the pid launchd names for its job
+  accepted while it runs as the plist's `UserName` and listens on exactly `127.0.0.1` (`lsof -p`), or, under a
+  restricted table, to a port that pid listens on there (the weaker vouch below): a departure from the pinned HA-2 and
+  the contract's later RT-3, accepted in principle by the contract owner as DEC-0161 (proposed; the restricted-table vouch
+  included) and kept as a departure until the next repin (FAA-288). They read, never change:
   macOS `sysctl net.inet.tcp.pcblist_n` in the process, or the programs `/usr/sbin/netstat
   -anv -p tcp` and `/bin/ps -o uid= -p <pid>` (the Node twin always); Linux
   `/proc/net/tcp` and `/proc/net/tcp6`; Windows `GetExtendedTcpTable` and the process
@@ -45,7 +56,10 @@ bounded and non-publishing until explicit scoped grants exist in a project bindi
   short-lived child of its own interpreter listening on a random `127.0.0.1` port; when the
   table is restricted (macOS 27.2, FAA-267) the launchd installers also run `/usr/sbin/lsof
   -nP -a -p <pid> -i4TCP -sTCP:LISTEN -Fn` on their own job's pid. That vouch shows the job listens on the port, not that it accepted
-  the connection (a more specific bind by root over a wildcard job would pass; contract CT-261). A token-free loopback door is not yet protected against
+  the connection (a more specific bind by root over a wildcard job would pass; contract CT-261). A LaunchDaemon's root
+  installer runs that `lsof` and `ps -o uid=` on its job's pid before it accepts an answer, and reads, never changes, every other
+  plist in `/Library/LaunchDaemons` (to find another holder of its label, `plutil -convert xml1` for a binary one in
+  Node), `launchctl print system/<label>` and the `UserName`'s uid (`pwd`, or `id -u` in Node). A token-free loopback door is not yet protected against
   another account's process (HA-3, FAA-227). An MCP client (Claude Code, Codex) sends the
   token it was registered with on every later connection without this check (the contract's
   residue "a coding agent's bearer"): when the port may have changed hands, rotate the token

package/package.json

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

@@ -2,8 +2,8 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
-  "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.77.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; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks; and put an agent on a standing watch over a product (observer mode).",
+  "version": "0.78.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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

@@ -1,11 +1,15 @@
 ---
 name: adapting-projects-to-fabric
-description: Use when adapting an existing agent, MCP server, A2A peer, HTTP service, or terminal CLI to the Fabric Agent Contract (choosing MCP/A2A/local-runner, scaffolding a provider bundle, or checking Fabric compatibility); also for «подключить проект к Fabric» or «сделать агента совместимым с Fabric». NOT for building the Fabric host/orchestrator, configuring an MCP client, a brand-new agent (creating-fabric-agents), running an agent as a local or online Fabric service with a dashboard (building-fabric-services), or a coding session working through Fabric, its board or claims, «подключись к Fabric» (working-with-fabric).
+description: >-
+  Use when adapting an existing agent, MCP server, A2A peer, HTTP service or CLI to the Fabric Agent Contract:
+  profile, provider bundle, compatibility check. Triggers: "adapt this to Fabric", «подключить проект к Fabric».
+  NOT for a new agent (creating-fabric-agents), a service (building-fabric-services) or a session
+  (working-with-fabric).
 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.77.0"
+  version: "0.78.0"
   contract-version: "0.1.0"
   contract-commit: "18f8d48762edc5bfb1433657cbfe1c16196df1a6"
 ---
@@ -16,6 +20,10 @@ Turn an existing stable interface into a proposed Fabric provider bundle, then p
 only the compatibility gates for which receipts exist. The Fabric Agent Contract is
 normative; this skill is an authoring workflow pinned to one immutable revision.
 
+## When to use
+
+The description above stays short for the skill listing budget; the whole reach, every trigger included, is in [references/when-to-use.md](references/when-to-use.md).
+
 ## Boundary
 
 Use this skill to adapt or assess a provider project. Do not use it to:

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/when-to-use.md

@@ -0,0 +1,5 @@
+# When to use adapting-projects-to-fabric
+
+The skill's full trigger description, kept here so the front matter's `description` stays within the client's skill listing budget (about 350 characters a skill). Read it when choosing between this skill and a neighbour.
+
+Use when adapting an existing agent, MCP server, A2A peer, HTTP service, or terminal CLI to the Fabric Agent Contract (choosing MCP/A2A/local-runner, scaffolding a provider bundle, or checking Fabric compatibility); also for «подключить проект к Fabric» or «сделать агента совместимым с Fabric». NOT for building the Fabric host/orchestrator, configuring an MCP client, a brand-new agent (creating-fabric-agents), running an agent as a local or online Fabric service with a dashboard (building-fabric-services), or a coding session working through Fabric, its board or claims, «подключись к Fabric» (working-with-fabric).

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

@@ -1,20 +1,15 @@
 ---
 name: building-fabric-services
 description: >-
-  Use when running an agent as a Fabric service (fabric-service/0.1, its kits and probe): a local service (launchd,
-  systemd, Windows), an ONLINE agent or dashboard on https, its dashboard link and kit (narrow panel, themes), data
-  and cache paths, how callers reach and authenticate it, long jobs (fabric.job.*), spend report and limits, runner
-  routes and model profiles, the estate record and delegation tokens, answering a Project's board requests, or packing
-  and signing it. «сделай агенту дашборд», «локальный сервис агента», «подключи агента к Fabric Dashboards», «отвечать
-  на запросы с доски проекта», «расходы агента на модели», "make this agent a local service", "make an online
-  dashboard a Fabric service", "add the well-known endpoint". NOT for a one-off script or cron job, a hosted product
-  with no agent, the provider manifest (adapting-projects-to-fabric), a new agent's design (creating-fabric-agents), a
-  session using Fabric or its board (working-with-fabric), or building the Dashboards app (window, tray).
+  Use when running an agent as a fabric-service/0.1 service, local or online: dashboard, auth, jobs, spend, board
+  requests. Triggers: "make this agent a local service", «сделай агенту дашборд», «локальный сервис агента». NOT
+  for a provider manifest (adapting-projects-to-fabric), a new agent (creating-fabric-agents) or a session
+  (working-with-fabric).
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits (Node.js 22+ for a Linux service's instance lock); the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.77.0"
+  version: "0.78.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "18f8d48762edc5bfb1433657cbfe1c16196df1a6"
@@ -32,6 +27,10 @@ Every rule below exists because a real service on this estate broke it. Treat th
 non-negotiable; the kit implements them so you call a function instead of
 re-deriving a rule.
 
+## When to use
+
+The description above stays short for the skill listing budget; the whole reach, every trigger included, is in [references/when-to-use.md](references/when-to-use.md).
+
 ## Boundary
 
 Use it to create a service, to bring an existing local server under the protocol, or
@@ -221,7 +220,9 @@ 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 **this** identity answers on this OS account's listener (HA-2).
-   A label the operator disabled stays disabled: only a first install enables.
+   A label the operator disabled stays disabled: only a first install enables. On a headless Mac (no GUI login after a
+   FileVault restart) install a LaunchDaemon instead: the plist in `/Library/LaunchDaemons` with `user_name`, as root
+   (the lifecycle reference, *The system domain*).
 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
@@ -244,28 +245,19 @@ while the operator types or a dialog is open, one panel's failure never blanks t
 others, and every error is a sentence with the next action. Read
 [the dashboard reference](references/dashboard.md) before building the page.
 
-The host shows the page in a pane beside the agent console that the operator can drag wide, so
-the page must hold from **360 CSS px** up: no sideways document scroll, navigation that wraps or
-folds into a More menu (never a tab strip that only scrolls sideways), wide tables and logs in
-their own focusable scroll box, sticky chrome at most 120 px, and the host's colour scheme and
-theme followed (`fabric-dashboard/0.1`, contract DEC-0036). **Build it from the dashboard kit**
-(`assets/dashboard-kit/`: `dashboard_kit.py install <static dir>`, seven AA themes, light and dark)
-and declare it with `extensions=fs.dashboard_extension()`. Read
-[the dashboard kit reference](references/dashboard-kit.md) for the markup, the themes, the
-declaration and how to upgrade a dashboard built before the kit: an upgrade you may make yourself,
-which the plugin's session-start notice offers in a repository that owns the service.
-
-**Every button has a tool** (`fabric-actions/0.1`, contract DEC-0121 AP-1). Each action the page lets a
-person take is a tool on the MCP surface with the same effect, checks, audit record and an idempotency key,
-registered with `server.add_tool(tool, handler, action={id, title, tool, gate})` (`gate` is `none`, `relayed`
-or `human` with its `humanStep`) and declared with `build_well_known(actions=server.action_table())` under
-`extensions/actions/0.1`. A `relayed` action called by the operator's own agent with their decision in
-`_meta.decision` is the operator's act: never answer it "operator session required" or send them to the page.
-A service adopts the relayed gate once Fabric's hub forwards decisions (CT-125), as the contract says; until then its tools
-answer as today, except the board responder's take-back action, declared `relayed` now: an agent whose client sets
-`_meta` calls it with the operator's decision; Claude Code and Codex reach it through the page until CT-125
-([board.md](references/board.md); the reference service's `board.take-back`). Read the interop reference's *Actions* section for when to adopt, the gate, its hooks and its
-refusals.
+The host shows the page in a pane the operator can drag wide, so it holds from **360 CSS px** up and follows the
+host's colour scheme and theme (`fabric-dashboard/0.1`, contract DEC-0036). **Build it from the dashboard kit**
+(`assets/dashboard-kit/`: `dashboard_kit.py install <static dir>`, seven AA themes, light and dark) and declare it with
+`extensions=fs.dashboard_extension()`. [The dashboard kit reference](references/dashboard-kit.md) has the layout rules,
+the markup, the themes, the declaration and how to upgrade a dashboard built before the kit, which the plugin's
+session-start notice offers in a repository that owns the service.
+
+**Every button has a tool** (`fabric-actions/0.1`, contract DEC-0121 AP-1): each action the page offers is an MCP tool
+with the same effect, checks, audit record and idempotency key, registered with
+`server.add_tool(tool, handler, action={id, title, tool, gate})` and declared with
+`build_well_known(actions=server.action_table())` under `extensions/actions/0.1`. A `relayed` action called with the
+operator's decision in `_meta.decision` is the operator's act, never answered "operator session required". When to
+adopt, the gates, the hooks, the board responder's take-back and the refusals: the interop reference's *Actions* section.
 
 **Say what the agent uses** (`fabric-connections/0.1`, DEC-0096) so Fabric Dashboards draws its chain: the other
 agents, models, connectors, stores and channels, each with its state, from
@@ -377,12 +369,8 @@ things change and the kits implement each:
    example is [`scripts/sample-remote-service.mjs`](scripts/sample-remote-service.mjs): it runs
    with its own TLS or behind a platform router.
 2. **Secrets live on the platform:** the service token and the session key (32 bytes) are
-   platform secrets, never in the repository, a URL or an argument vector. A provider key the
-   remote service needs is issued and kept in Project Observatory, pushed to the platform, and
-   the movement recorded with
-   `python3 "$(project-observatory full-path)/tools/vault.py" moved <project> <env> <NAME> --how "<what moved, where, evidence>" --at <provider>`,
-   so the platform's copy is known rather than invisible. Without Project Observatory, record
-   where the key lives in the person's own secret manager.
+   platform secrets, never in the repository, a URL or an argument vector; a provider key stays in Project
+   Observatory or the person's secret manager, its move recorded ([remote placement](references/remote-placement.md), *On the platform*).
 3. **Register it on the operator's computer**, the installer side, run there:
    `registerRemote({ id, name, origin, token, source })` / `register_remote(...)` writes the token file
    (0600) and the descriptor, with `source.repository` naming the code's repository; pass the token from a file or

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

@@ -60,6 +60,7 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | L0 | `fabric_identifiers` | identifier equality by normal form (DEC-0076) |
 | L0 | `fabric_secrets` | the contract's one credential detector (DEC-0044) |
 | L0 | `fabric_peer_owner` | which OS account owns each end of a loopback connection, from the computer's socket table (DEC-0154 HA-2, FAA-226): `listener`, `server_end`, `peer`, `CheckedHTTPConnection`; the Python file is Project Observatory's `peer_owner.py` 1.1.0 vendored from commit `f86f0622` with the readings its header names (`1.1.0+kit.3`), the Node twin reads netstat, `/proc` and the owner SID where Python reads `sysctl`, `/proc` and `GetExtendedTcpTable`; on a restricted macOS table (FAA-267) a caller may vouch with a pid it started, proved by `lsof -p` |
+| L0 | `fabric_tailnet` | who calls an agent behind `tailscale serve` and what that person may open (FAA-297): `Tailscale-User-Login` only on the agent's own serve listener from a loopback peer, groups from a generated `tailnet-perimeter/1` file, a personal SHA-256-stored key for MCP no wider than the groups; `authorize`, `load_perimeter`, `load_keys`, `hash_key`, refusals 401/403 with a code ([surfaces-and-auth.md](surfaces-and-auth.md#behind-tailscale-serve)) |
 | L1 | `fabric_crypto` | Ed25519 signing (a Montgomery ladder that does not branch on the key) and verification, P-256 verification, base64url, sha256 |
 | L1 | `fabric_base` | the protocol name, `ServiceError`, small shared helpers |
 | L1 | `fabric_platform` | Windows: named pipes, owner-only files (DEC-0032) |
@@ -85,7 +86,7 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | L3 | `fabric_auth` | the token, the network guard, login codes |
 | L3 | `fabric_events` | events, paging, the JSONL event log (DEC-0029) |
 | L3 | `fabric_logs` | rotating logs, the stop signal and the drain (LC-12) |
-| L3 | `fabric_supervisors` | launchd, systemd user units, Task Scheduler (DEC-0032, LC-14) |
+| L3 | `fabric_supervisors` | launchd (a LaunchAgent, or a LaunchDaemon in the system domain, FAA-278), systemd user units, Task Scheduler (DEC-0032, LC-14) |
 | L3 | `fabric_service` | the facade: every name 0.39.1 exported, re-exported from the modules above |
 | L3 | `fabric_profiles` | runner and model profiles ([profiles](profiles.md)) |
 | L3 | `fabric_interop_rules` | `fabric-interop/0.1` rules without a service: constants, `InteropError`, trace context, job limits (DEC-0087; FAA-92), a job's approval step under the mandate (`job_step`, C3.3) |

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

@@ -13,6 +13,7 @@ PassionCode.ai the same rules make up the organization's product lifecycle contr
 - [The rules](#the-rules)
 - [launchd plist](#launchd-plist-generate-it-with-launchd_plist-or-launchdplist-both-kits-write-the-same-bytes)
 - [Install, upgrade, uninstall](#install-upgrade-uninstall)
+- [The system domain](#the-system-domain)
 - [One copy under a supervisor](#one-copy-under-a-supervisor)
 - [An app's own descriptor and the node](#an-apps-own-descriptor-and-the-node)
 - [Directories](#directories)
@@ -49,7 +50,8 @@ carry a credential. Only `doctor` and `update` are commands a host may run.
 
 **Started is not ready.** Readiness is the well-known document, `GET /.well-known/fabric-service`: answered without
 authentication, from memory, in under 100 ms, with `service.id` and `service.instance` equal to the descriptor's,
-on a listener of this OS account (DEC-0154 HA-2: another account's listener is `foreign-user` whatever it answers).
+on a listener of this OS account (DEC-0154 HA-2: another account's listener is `foreign-user` whatever it answers; a
+LaunchDaemon's root installer reads it as *The system domain* says).
 `status` is `starting`, `ready`, `degraded` or `stopping`; `degraded` is always present, and an empty list asserts
 full health. A process that cannot serve does not answer, and a host derives `down`. An install or upgrade polls
 that document until `service.id` matches (at most 40 s) before it calls the service started (the launchd installers;
@@ -76,7 +78,7 @@ systemd and Task Scheduler do not poll yet, FAA-253).
 |---|---|---|
 | `Label` | reverse-DNS, stable (`com.example.example-agent`) | the host controls the job by label |
 | `ProgramArguments` | absolute interpreter + module/script inside a **release** directory | a worktree or checkout path breaks the day it moves |
-| `RunAtLoad` | `true` | back at every login |
+| `RunAtLoad` | `true` | back at every login (a LaunchDaemon: at every boot) |
 | `KeepAlive` | `true` | `{SuccessfulExit:false}` leaves a cleanly exited service down |
 | `ThrottleInterval` | `10` | bounds a crash loop |
 | `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 |
@@ -102,11 +104,13 @@ systemd and Task Scheduler do not poll yet, FAA-253).
    cannot prove reads `table-restricted` and the error names the way round it (FAA-267). The pid is the job's own, so a
    `ProgramArguments` wrapper that starts the server as a child (`sh -c` without `exec`, `uv run`, `npm start`) cannot
    vouch for it: on such a host start the server with `exec` or run the installer from Apple's `/usr/bin/python3`.
+   A LaunchDaemon reads its answer differently: *The system domain*, below.
 4. Upgrade = new release, rewrite the plist with the new path, `launchd_install`
    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` (Node: `await launchdUninstall(...)`) + `remove_descriptor`. Data stays; `purge=True`
-   (with `service_id`) removes data, logs and cache when the operator asks.
+   (with `service_id`) removes data, logs and cache when the operator asks; a LaunchDaemon refuses `purge` (*The system
+   domain*, below).
 
 **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
@@ -123,6 +127,68 @@ 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.
 
+## The system domain
+
+A `gui/<uid>` job (a LaunchAgent) runs only while its user is logged in. A headless Mac that a FileVault restart
+(`fdesetup authrestart`) leaves with no GUI login, or an SSH session of a user with no GUI login, has none: `bootstrap`
+answers error 125 ("Domain does not support specified action") and the installer's error says to remove the LaunchAgent
+it wrote (`launchd_uninstall`) and use the system domain (FAA-278). There the job is a **LaunchDaemon**: launchd starts
+it at boot, before any login, as the account its `UserName` names.
+
+- **The plist**: `launchd_plist(..., user_name="<short name>")` (Node: `userName`) writes `UserName`, which a system
+  install requires (without it the job would run as root, which every client refuses); the file goes in
+  `/Library/LaunchDaemons/<label>.plist`. A plist there is in the system domain by its path (the folder's case is
+  ignored); `domain="system"` (Node: `domain: 'system'`) says so for any path, and an explicit domain wins over the
+  path. Everything else is a LaunchAgent's.
+  `UserName` is the account whose Fabric and agents call the service: clients of another account refuse it (HA-2).
+- **Who runs which step.** The release, the descriptor and the service token are written as the `UserName` (steps 1 and
+  2 above, for example with `sudo -u <user> -H`), so they live in that user's home with its modes, and the plist's
+  working directory and log paths name that home; only the plist, `launchd_install` and `launchd_uninstall` run as root,
+  and at uninstall `remove_descriptor` runs as the `UserName` again. A service moved from a LaunchAgent is uninstalled
+  as one first, so launchd never holds both. The descriptor's `lifecycle.plist` names the path exactly,
+  `/Library/LaunchDaemons/<label>.plist`: a host that reads the folder by its spelling then knows the domain too.
+- **The label is the machine's.** `/Library/LaunchDaemons` and the system domain are shared by every account of the
+  Mac, so a LaunchDaemon's label is unique on the machine, not per account (put the account in it on a Mac with a
+  personal and an organization account); an install refuses, before writing anything, a label another plist holds
+  (the one launchd loaded the job from, or any plist of that label in the same folder) and the plist at its path when it
+  names another `UserName` or another label; an uninstall refuses a label another plist holds before its `bootout`,
+  which would stop that plist's job, so pass it the label the plist at its path names.
+- **Root installs and removes it.** `launchd_install` and `launchd_uninstall` in the system domain refuse, before writing
+  anything, in a process that is not root, and name the command to run as root (`launchctl bootstrap system <plist>`,
+  `launchctl bootout system/<label>`, removing the plist and `launchctl enable system/<label>`, as `launchd_uninstall`
+  does). `purge` is refused: the data belongs to the `UserName`, so remove it as that user. Upgrade is the same install
+  again as root, so a descriptor's `commands.update` for a LaunchDaemon runs as root, writes the new release (and any
+  descriptor it rewrites) as the `UserName` as an install does, and runs only the plist and `launchd_install` as root; a
+  host without root reports it as the operator's. A host's verbs need root too and keep LC-14 (off stays off, across a boot as well as a login): stop is
+  `bootout` + `disable system/<label>`, start is `enable` + `bootstrap system <plist>`, restart is
+  `kickstart -k system/<label>`; a host or broker without root reports the job read-only.
+- **Status and pid read without root**: `launchd_loaded(label, "system")` and `launchd_pid(label, "system")` ask
+  `launchctl print system/<label>`, and `launchd_override(label, "system")` asks `launchctl print-disabled system`
+  (Node: the `domain: 'system'` option), both of which any account may read; the probe's `lifecycle.one-copy` reads the
+  domain from the descriptor's plist the same way.
+- **The answer the installer waits for**: root reads the service's listener as another account's, so the installer takes
+  the job's pid from `launchctl print system/<label>` and reads the token-free well-known document only on a connection
+  that pid accepted, while the pid runs as the `UserName`'s uid (`ps`) and listens on exactly `127.0.0.1` (`lsof -p`);
+  an install refuses a `UserName` that is not a short name, no account of the Mac or root, and an origin other than
+  `http://127.0.0.1:<port>`, where nothing could prove it. Where the socket table is restricted it accepts a port that
+  pid listens on at exactly `127.0.0.1`, the weaker vouch SECURITY.md names (CT-261). A `ProgramArguments` wrapper that
+  starts the server as a child cannot pass either check, and the refusal says so: start the server with `exec`. An
+  install refused after its bootstrap leaves the job loaded, and its plist starts it again at boot; the error says so,
+  and as root `launchctl bootout system/<label>` and removing the plist (or `launchd_uninstall`) take it away. For hosts and the probe the domain comes from the plist's folder alone, so a LaunchDaemon's plist must live
+  in `/Library/LaunchDaemons` even when the installer is given `domain="system"`: the installer neither moves nor checks
+  it. A descriptor field for the domain is the contract's CT-234, open.
+- **A contract exception, accepted in principle.** At the pin, HA-2 reads a launch daemon's listener as another
+  account's and nothing it answers as the service's; the contract's later RT-3 vouches only for the caller's own uid. The
+  root installer reads its own job's token-free well-known answer anyway, proved by launchd's pid, that pid's uid and its
+  bind on exactly `127.0.0.1` (`lsof -p`, never a wildcard), and sends no credential; under a restricted socket table the
+  first proof is the CT-261 weaker vouch (the pid listens on the port; that it accepted the connection is not shown). The contract owner accepted this in
+  principle as DEC-0161 (RT-3 extended to launchd's system domain, the restricted-table vouch included; proposed, its
+  text after its readings), so it stays a departure from the pin until the next repin (FAA-288).
+  Every other client keeps HA-2 as written.
+- **Hosts.** A host or broker that reads launchd only in `gui/<uid>` sees a LaunchDaemon as not loaded and must not load
+  its plist into `gui/<uid>`. Fabric Dashboards from 0.8.39 takes the domain from the plist's folder and offers no verbs
+  for a system job; the lifecycle broker is still asked (FAA-287).
+
 ## One copy under a supervisor
 
 Started by hand, a copy that finds `service.lock` held prints one sentence naming the

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

@@ -212,7 +212,9 @@ Loopback is one per computer, not one per OS account. Before a client sends any
 `http://127.0.0.1:<port>` (a descriptor's token, a delegation token, a login code's request, a session cookie, a door's
 token), and before a host calls a local service healthy, it tells the owner of the server end of its own connection
 from the computer's socket table. A listener of another OS account, of root, SYSTEM or a service account, or one whose
-owner cannot be told, is `foreign-user`: nothing is sent and nothing it answers is read as the service's. The order of
+owner cannot be told, is `foreign-user`: nothing is sent and nothing it answers is read as the service's. One exception:
+a LaunchDaemon's root installer reads its own job's token-free well-known answer, proved by the job's pid, uid and exact
+`127.0.0.1` bind (lifecycle.md, *The system domain*; DEC-0161 accepted in principle, proposed; FAA-288). The order of
 a local service's states is `down`, `foreign-user`, `foreign` (`FAC-SEM-009`), then the well-known `status`; the
 well-known `process.pid` is never proof (`docs/specification/service.md#ha-2` at the pin).
 
@@ -232,14 +234,14 @@ listener of this account's pid on the port counts as this account's (`CheckedHTT
 `checkedSocket({vouchPid})`). The launchd installers vouch with their own job's pid; elsewhere a restricted table
 refuses (the probe, the hub client and `fabric_http` included, FAA-272), and Apple's `/usr/bin/python3` sees the
 whole table (FAA-267). A vouch is a weaker proof than the table's: it shows the job's pid listens on the port (`127.0.0.1` or the
-IPv4 wildcard), not that it accepted this connection, so a more specific bind by root over a wildcard job would pass;
+IPv4 wildcard for a LaunchAgent's installer, exactly `127.0.0.1` for a LaunchDaemon's), not that it accepted this connection, so a more specific bind by root over a wildcard job would pass;
 the contract's ruling on vouching is CT-261.
 
 Every kit client that sends a credential to loopback checks first: `check_service.py` (rule `listener.owner`, the first that reads the port for
 a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub client (`HubError` `foreign-user`),
 `fabric_http` / `fabric-http.mjs` for a plain `http://` loopback URL (`HttpError` kind `foreign-user`, never retried),
 `check_dashboard_layout.mjs` before a local login code, and the launchd installers' poll (a listener of another account
-is never a successful install; the systemd and Task Scheduler installers do not poll yet, FAA-253). A running board
+is never a successful install, except a LaunchDaemon's job as its root installer proves it; the systemd and Task Scheduler installers do not poll yet, FAA-253). A running board
 session reports a door another account holds as `board.down` with reason `unreachable` until FAA-252. On macOS the Node
 twin reads the pid from `netstat` and the uid from `ps` a few milliseconds apart, so a pid reused in between would be
 misread; the Python twin's `sysctl` reader takes both from one record. A service's own loopback server refusing another account's peer (HA-3) is FAA-227, and the port

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

@@ -79,6 +79,11 @@ watch the gate fail.
   "used before honoured" write); memory works for one process.
 - **Behind a router**: check the platform-set forwarded scheme; `Host` is preserved by common
   platforms and must equal the origin's host.
+- **A provider key** the remote service needs is issued and kept in Project Observatory, pushed to the platform, and
+  the movement recorded with
+  `python3 "$(project-observatory full-path)/tools/vault.py" moved <project> <env> <NAME> --how "<what moved, where, evidence>" --at <provider>`,
+  so the platform's copy is known rather than invisible. Without Project Observatory, record where the key lives in
+  the person's own secret manager.
 
 ## Checking it
 

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

@@ -5,6 +5,7 @@
 - [MCP for agents](#mcp-for-agents)
 - [CLI for people and scripts](#cli-for-people-and-scripts)
 - [A2A for remote agents](#a2a-for-remote-agents)
+- [Behind tailscale serve](#behind-tailscale-serve)
 - [Token](#token)
 - [Dashboard session](#dashboard-session)
 - [Headers every response carries](#headers-every-response-carries)
@@ -40,7 +41,9 @@
 
 ## CLI for people and scripts
 
-`<tool> service status|start|stop|restart` (launchctl on the label, then the
+`<tool> service status|start|stop|restart` (launchctl on the label in the domain `launchd_domain(plist)` names; for a
+LaunchDaemon start, stop and restart are root's, and a CLI without root reports the job read-only, lifecycle.md, The system
+domain; then the
 well-known document from this OS account's listener, else `foreign-user`: protocol.md, The listener's owner), `<tool> dashboard` (resolve the exact registered service with the `fabric-dashboards`
 MCP, run `check_dashboard_link.py` on the action, then open its `open_link` with the host's `open` and
 `fallback=never`; never `open <url>`, `open -a Safari`, `xdg-open` or `webbrowser.open`; an installed host that
@@ -82,6 +85,45 @@ A probe cannot see whether an interface would take the descriptor's token withou
 forbids, so it reads the card only and never calls an interface: an API-key scheme in the descriptor's own
 `auth.header` is a finding, and with `Authorization` (the default) the card cannot show it.
 
+## Behind tailscale serve
+
+An agent on a server (a VM, a teammate's machine) can reach people on the tailnet through `tailscale serve`, which
+proxies HTTPS on the node's tailnet name to a loopback listener and adds the caller's `Tailscale-User-Login`. The
+kit's `fabric_tailnet.py` / `fabric-tailnet.mjs` (FAA-297) turn that into a decision; the agent wires it into its own
+handler.
+
+- **A listener of serve's own.** Any process on the machine can send `Tailscale-User-Login` to a loopback port, so the
+  header is believed only on a listener that serve alone uses: a second loopback port, or, where the installed
+  `tailscale serve` can proxy to one, a Unix socket whose mode keeps other accounts out. Pass `listener="serve"` and the
+  connection's peer (`"unix"` for a socket). On any other listener a request carrying serve's headers is refused
+  (`serve-header-off-serve`); the Fabric listener keeps its session key and never reads them.
+- **A perimeter generated, not kept by hand.** `load_perimeter` / `loadPerimeter` take a `tailnet-perimeter/1`
+  document: `generatedFrom {registry, revision, at}` (required: a file without its source is refused,
+  `perimeter-not-generated`) and `groups {name: {members, dashboards, capabilities}}`. The organization's generator
+  writes it from its access registry; the agent reloads it when the file changes.
+- **A personal key for MCP.** `load_keys` / `loadKeys` take `[{id, login, sha256, capabilities}]`, the key's
+  `hash_key` / `hashKey` only. A call on the `mcp` surface needs `Authorization: Bearer <key>`; the key must belong to
+  the caller's login and its capabilities may not be wider than that login's groups.
+- **The answer.** `authorize(listener=, peer=, headers=, perimeter=, surface="dashboard"|"mcp", target=, keys=)`
+  answers `{allowed, status, code, login, groups}` (and `key`, the key's id, on an allowed MCP call). Send the
+  status and the code as they are; no answer carries a key or its hash.
+
+| Code | Status | When |
+|---|---|---|
+| `serve-header-off-serve` | 403 | serve's headers on a listener that is not serve's |
+| `peer-not-loopback` | 403 | the serve listener was reached from another address |
+| `identity-missing`, `identity-ambiguous`, `identity-malformed` | 401 | no login, two, or not a login |
+| `not-in-perimeter` | 403 | the login is in no group |
+| `dashboard-not-granted` | 403 | no group of the login lists the dashboard |
+| `key-required`, `key-unknown` | 401 | an MCP call without a bearer key, or with one not on the list |
+| `key-not-yours` | 403 | the key belongs to another login |
+| `key-wider-than-group` | 403 | the key's capabilities exceed the login's groups |
+| `capability-not-granted` | 403 | the key does not carry the capability called |
+
+A tagged node (a server, not a person) gets no identity header from serve and is refused `identity-missing`; a
+machine caller uses the estate's delegation tokens instead. The serve listener is an outward surface: watch it like
+the A2A tunnel above.
+
 ## Token
 
 - Created once with `ensure_token` at first start, after the instance lock.