@passioncode-ai/fabric-agent-adapter 0.79.1 → 0.81.0

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

@@ -125,6 +125,7 @@ action it also carries the operator's decision, [Actions](#actions)), act on eve
 (`jobs.quotaExhausted(id, message, {retryable, resetsAt})`, `jobCallerAction`, `intentIdempotencyKey`). The guidance
 for an agent's own design is in `creating-fabric-agents/references/resilience-and-autonomy.md`.
 
+<a id="a-nodes-call-queue"></a>
 **A node's call queue (DEC-0104).** A provider that queues refuses a start past its queue with `queue-full`: an `isError`
 result with one text item whose JSON is `{error: {code: "queue-full", message, data: {retryable, retryAfterSeconds}}}`,
 never `structuredContent`; the caller starts again after `retryAfterSeconds` under the same key. Read that refusal
@@ -132,9 +133,58 @@ from the start's own `isError` result, before any answer reaches `job_caller_act
 job, and `queue-full` never ends one, so they answer a job it ended `invalid` (`QUEUE_FULL` names the code, and the
 kit's job store refuses to end a job with it). The kit has no reader for the refusal yet (FAA-103). Through Fabric's hub
 a caller today sees `product-error` instead, kept under the key for 24 hours, until the hub relays `queue-full`
-(Fabric CO-376). The kit does not queue: it declares no load extension (`extensions/load/0.1`) and serves no
-`fabric.job.list`, so its `unknown-job` and repeated keys keep the rules above. A node that will queue needs
-`jobCallerKey`, the contract's `agent-network.json` vectors and the load report first (FAA-103).
+(Fabric CO-376). The kit's job store does not queue by itself: it declares no load extension (`extensions/load/0.1`)
+and serves no `fabric.job.list`, so its `unknown-job` and repeated keys keep the rules above.
+
+A node that queues takes the contract's reference functions from the kit instead of copying them (since 0.80.0,
+FAA-289): `fabric_load.py` and `fabric-load.mjs`, exported by both facades, held to the contract's
+`fixtures/vectors/agent-network.json` and its `job-queue`, `service-load` and `service-well-known-load` fixtures at the
+pin (vendored as `test/fixtures/contract/load-vectors.json` by `make_load_vectors.mjs`):
+
+| Python | Node | What |
+|---|---|---|
+| `job_caller_key(accepted, credential)` | `jobCallerKey` | the caller's opaque key: an accepted delegation's `principal`, `caller` and a partner organization ending the chain, else the credential; `None` / `undefined` for a refused or unreadable call |
+| `next_queued_job(queue, running, limits)` | `nextQueuedJob` | the id to start next per (agentRef, context): nothing at `concurrency`, a caller at `perCaller` waits, the caller running fewest first, then the oldest arrival, ties by id |
+| `admit_job(queue, running, job, limits, retry_after_seconds)` | `admitJob` | `{admit: True}` when the job would start at once or fewer than `queueMax` wait, else the `queue-full` error with `retryAfterSeconds` (1 to 3600, else 60) |
+| `queue_status_message(position, length)` | `queueStatusMessage` | a waiting job's `statusMessage`, `queued <position> of <length>` |
+| `read_queue_position(status_message)` | `readQueuePosition` | `{position, length}` from that message, or none |
+| `job_queue_rules(value)` | `jobQueueRules` | FAC-SEM-131 on `{queue, running, limits, started}` |
+| `load_report_rules(report)` | `loadReportRules` | FAC-SEM-132 on a `service-load/1` report: windows one `windowSeconds` apart, none after `generatedAt`, one row per context, p50 at most p95, a run time only where a job ended |
+| `load_report_problems(report)` | `loadReportProblems` | the report against `service-load.schema.json` (no caller, no job id, counts and durations only) |
+| `load_view(well_known)`, `load_extension_rules(well_known)` | `loadView`, `loadExtensionRules` | the declaration as a reader reads it, and FAC-SEM-133: an invalid one is treated as not declared and reported |
+| `load_extension(path, window_seconds, limits)` | `loadExtension({path, windowSeconds, limits})` | the `extensions` entry a service declares; raises `ServiceError` on one a reader would hide |
+
+Queue times are UTC instants (`T`, `Z`, at most three fraction digits); report times are RFC 3339 read strictly. A
+node keys every per-caller rule with `job_caller_key`, counts every started job that has not ended (`input_required`
+and paused ones too) as running, and answers another caller's job id `unknown-job`. The text-only `queue-full` result
+and `fabric.job.list` are still the node's own (FAA-103).
+
+### Work held by the service's own limits
+
+A service that holds work by a limit of its own (a daily quota, a per-caller share, a concurrency cap, a money cap)
+says so, so a hold is never seen only by a caller who waits (FAA-298). `fabric_holds` (Node `fabric-holds.mjs`) does
+the three parts:
+
+- **On the job.** `hold_job(jobs, job_id, reason, since, until, message)` (Node `holdJob`) pauses the job with the
+  statusMessage `waiting_message` writes: `quota-exhausted[ until <until>]: waiting <reason> since <since>[: <message>]`,
+  `reason` one of `daily-quota`, `caller-share`, `concurrency`, `money`. The pinned `interop-job` schema is closed
+  (`additionalProperties: false`), so `waiting {reason, since, until, message}` is carried in `statusMessage`, the
+  contract's pause grammar, never as a field of the job: every caller already reads it as wait (until `until` when
+  given), and `read_waiting(answer)` (Node `readWaiting`) gives the four parts back. A job waiting its normal turn in
+  the call queue keeps `queued <position> of <length>`; a hold is the service's own limit.
+- **One push per hold.** `HoldBook(path, events=log)` (Node `new HoldBook(file, {events})`) opens a hold per reason and
+  caller: `hold(caller=, work=, reason=, until=, job_id=)` returns `{hold, statusMessage, push}`, and only the call that
+  opens the hold pushes: one `limit.held` event, level `notice`, `notify: true`, naming the caller, the work, the reason
+  and when it frees by itself, and asking whether to raise the limit. More work held by the same limit for the same
+  caller joins the hold silently. A hold closes by `release`, when its `until` passes, or by a lift that covers it;
+  the next hold pushes again. Names that read as a credential are refused.
+- **The operator's answer as a scoped lift.** `lift(reason=, decision=, caller=, job_id=, jobs= | usd= | limit=,
+  until=)` records the operator's words (`fabric_actions.operator_decision("limit.lift", words)`) with its scope (this
+  order, one caller, or every caller) and its size: a number of jobs, an amount of money, or a raised limit for a window
+  (100 a day for today: `limit=100, until=<midnight>`), and writes `limit.lifted`. `admit(reason=, caller=, job_id=,
+  cost_usd=)` spends a jobs or money lift (the narrowest scope first) and answers whether the work may pass the limit;
+  pass its answer to `jobs.create(..., limit_holds=not admitted)` for a repeated key. `limit(reason=, base=, caller=)`
+  is the limit in force. A lift falls back by itself when its window ends or its amount is spent.
 
 <a id="actions"></a>
 
@@ -389,5 +439,6 @@ your own record, keep it (OA-6).
 | `interop.events-trace` | every event with a trace carries both `traceId` and `spanId`, well formed | no events page was read |
 | `interop.action-tools` | every action the well-known `extensions/actions/0.1` declares names a tool `tools/list` serves (DEC-0121 AP-1); one it does not serve is a `FAIL`, and so is a local service that declares actions with no MCP surface (beyond FAC-SEM-142, which reads only a present list) | no declaration, an unreadable one (`well-known.actions` reports it), no listing was read, or a remote service with no MCP surface (its twin may be on A2A or behind a gateway) |
 | `channel-agent.declaration` | a channel agent's declaration (DEC-0150) passes the contract's FAC-SEM-162 to 165 at the pin, read from `provider.extensions` of the manifest the descriptor names, else from `extensions` of the well-known answer (CA-1); a `FAIL` on the obligations of a declaration the reader still reads (FAC-SEM-164) or a string shaped like a credential (FAC-SEM-165, not a declaration too large to read for credentials) in the read declaration or in any copy beside it, the first five findings shown as code and path, never a declared value | nothing declared, the named manifest unreadable (`interop.manifest-link` fails it), or a key read as not declared (a manifest's own `extensions`, a capability's, another version's key, a well-known copy beside a manifest, a form the schema or FAC-SEM-163 refuses), each named in the evidence, never a failure while producers move to this revision unless a copy holds a string shaped like a credential (that fails in any copy the probe reads: a manifest's own `extensions`, a capability's, the well-known copy, CA-5); no line when the well-known answer is not read; credentials are read as the contract reads them, within its reading budget and under the `0.1` key only (a key of another version is named, not read); a well-known answer carrying the declaration at 75 % of the 2 MiB cap or over is named, never a failure (until the contract's CT-223) |
+| `limits.holds` | a service that declares limits (a load declaration's `limits`, the usage report's `budget` or `budgets`) holds work through `fabric_holds` (`HoldBook`, `waiting_message`, `hold_job`) in a tracked code file (`.py`, `.mjs`, `.js`, `.ts`) of its checkout outside the kit's copy, a vendored `check_service_rules.py` and the tests (FAA-298) | no limits declared, or no checkout found (`--repo` names it), git missing or out of time; and, since 0.81.0, a service that declares limits and holds none through the kit: a migration note naming `fabric_holds`, never a `FAIL`, since services built before the module could not have adopted it |
 
 `python3 scripts/check_service.py <id>` prints them with the rest; `--json` for a machine.

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

@@ -59,7 +59,7 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | L0 | `fabric_time` | strict RFC 3339, UTC days, formatting, day windows, the clock ([dates](#dates-and-times)) |
 | 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_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`, vendored from commit `f86f0622` (1.1.0) and read against `2180235c` (1.2.0, whose Linux rule it carries), with the readings its header names (`1.2.0+kit.5`; Observatory's 1.3.x libproc proof is FAA-292), 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 |
@@ -78,10 +78,11 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | L3 | `fabric_connections` | what an agent uses, `fabric-connections/0.1`: the reference reading and the declaration (DEC-0096, FAC-SEM-127) |
 | L3 | `fabric_a2a` | the reading side of an A2A Agent Card: `surfaces.a2a` as the schema reads it, and what a public card must not carry (DEC-0122) |
 | L3 | `fabric_page_links` | a service's pages as Fabric Dashboards' open_link: build and read it, a raw local address, FAC-SEM-143 on a link and on a URL-mode input request (DEC-0123); the Python twin reads URLs as WHATWG does by hand |
+| L3 | `fabric_load` | the call queue and the load report of DEC-0104 (FAA-289): `job_caller_key`, `next_queued_job`, `admit_job`, `queue_status_message`, `read_queue_position`, FAC-SEM-131 to 133, the `service-load/1` and `extensions/load/0.1` shapes, `load_extension`; imports `fabric_connections` for ajv's `date-time` ([interop](interop.md#a-nodes-call-queue)) |
 | L3 | `fabric_lock` | the instance lock and the supervisor marker (LC-01, DEC-0057) |
 | L3 | `fabric_usage` | usage receipts, the ledger, the usage report, attribution, spending limits ([usage](usage.md)) |
 | L3 | `fabric_backups` | settings backups (DEC-0025) |
-| L3 | `fabric_descriptor` | the descriptor, peers, app descriptors, the well-known document |
+| L3 | `fabric_descriptor` | the descriptor, peers, app descriptors, the well-known document, the loopback HTTP server that refuses another OS account's peer before reading it (`LoopbackHTTPServer`, Node `loopbackServer`; FAA-227) |
 | L3 | `fabric_context` | one instance per context (FAA-125, N-11): a context's instance, folders, descriptor, lock and marker; not in the facade, installed with `--module fabric_context` ([contexts](estate-record.md#one-instance-per-context-the-helper)) |
 | L3 | `fabric_auth` | the token, the network guard, login codes |
 | L3 | `fabric_events` | events, paging, the JSONL event log (DEC-0029) |
@@ -91,6 +92,7 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | 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) |
 | L3 | `fabric_interop` | `fabric-interop/0.1`: jobs, envelopes, MCP tools; re-exports the rule layer ([interop](interop.md)) |
+| L3 | `fabric_holds` | work a service holds by its own limits (FAA-298): the held job's `statusMessage` in the pause grammar (`waiting_message`, `read_waiting`, `hold_job`), one push per hold and the operator's scoped lift (`HoldBook`: `hold`, `release`, `lift`, `admit`, `limit`) ([interop](interop.md#work-held-by-the-services-own-limits)) |
 | L4 | `fabric_hub` | the Fabric hub's door (`fabric-hub/0.1`) |
 | L4 | `fabric_board_shapes` | the project board's wire: constants, refusal codes, shapes |
 | L4 | `fabric_board_link` | the board's link: the MCP session over the hub, the fsynced checkpoint, a claimed request as data, and the operator's mandate a request carries (FAA-135, imports `fabric_mandate` and `fabric_interop_rules` for the FAA-139 reading) |
@@ -105,7 +107,8 @@ Beside the kit, not in `kit.json`: the probe (`check_service.py`, `check_service
 `check_service_channel_agent.py`, `check_service_channel_agent_schema.py` and the
 `service-channel-agent-extension.schema.json` it reads at run time), the sample
 (`sample_service.py`, `sample-remote-service.mjs`), `fabric_kit.py` itself and the dashboard tools. Recipes built on
-the kit live in `../recipes/` ([the draft-and-check step of a support agent](../recipes/support-agent/README.md)).
+the kit live in `../recipes/` ([the draft-and-check step of a support agent](../recipes/support-agent/README.md), [a service that is only a
+dashboard](../recipes/dashboard-only/README.md), [a key-delivery door](../recipes/key-delivery-door/README.md)).
 
 ## What 0.39 code keeps
 

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

@@ -45,7 +45,8 @@ Starting, stopping and restarting go through the supervisor and nothing else:
 atomic, mode 0600) and the uninstaller removes it; a running service never writes its own, except an app
 ([below](#an-apps-own-descriptor-and-the-node)). It names the supervisor and its file (`label` and `plist`, `unit`,
 or `task`; none for `node` and `person`), the `origin` `http://127.0.0.1:<port>` (a port is a claim: an installer
-refuses a port another instance declares), the service's directories, and commands as argument arrays that never
+refuses a port another instance declares, and one another OS account listens on, read with the kit's
+`fabric_peer_owner`, FAA-225; the recorded port per account and its claim file wait on contract DEC-0160), the service's directories, and commands as argument arrays that never
 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
@@ -144,27 +145,34 @@ it at boot, before any login, as the account its `UserName` names.
   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.
+  path, except that an install refuses a pair launchd would contradict: `domain="system"` with a plist in a
+  `LaunchAgents` folder (launchd also loads that into `gui/<uid>` at login) and `domain="gui"` with a plist in
+  `/Library/LaunchDaemons` (launchd loads it at boot as root). A domain name given as the plist path (`"system"`,
+  `"gui"`) is refused, never read as a relative path (FAA-286). 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,
+  as one first, so launchd never holds both: the install refuses a plist of the same label left in the `UserName`'s
+  `~/Library/LaunchAgents`, and the probe's `lifecycle.one-copy` fails a label loaded in both domains (FAA-286). 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.
+  which would stop that plist's job, so pass it the label the plist at its path names; in either domain an uninstall
+  refuses a plist at its path that names another label, before its `bootout` (FAA-286).
 - **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
+  host without root reports it as the operator's. Its commands name absolute paths: `~` would be root's home, and the
+  probe's `lifecycle.plist` fails a LaunchDaemon command that starts with `~`, as it fails a LaunchDaemon plist without
+  `UserName` (FAA-286). 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
@@ -176,23 +184,32 @@ it at boot, before any login, as the account its `UserName` names.
   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
+  pid listens on at exactly `127.0.0.1`, the weaker vouch SECURITY.md names (DEC-0155 RT-3). 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
+  and as root `launchctl bootout system/<label>` and removing the plist (or `launchd_uninstall`) take it away. A
+  bootstrap that fails all five tries removes the plist the call wrote, and names one that was there before, which
+  would load at the next boot (FAA-286). A plist that does not parse is refused as such before anything is written,
+  never as a missing `UserName`; the Node installer refuses a binary plist and reads only the root dict's keys. 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
+  account's and nothing it answers as the service's; the pin's RT-3 (DEC-0155) 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
+  first proof is the RT-3 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).
+  for a system job; the lifecycle broker is still asked (FAA-287). A product with its own launchd reader (a status
+  page's `launchd_pid`, an installer of its own in another language) that asks only `gui/<uid>` reports a LaunchDaemon
+  as not loaded: move that reader to the plist's domain before the product moves to the system domain (FAA-286).
+- **Off macOS the twins differ, on purpose.** Python's `launchd_domain()` answers `gui/<uid>` on Linux (it refuses only
+  Windows), so the kit's launchd tests run on Linux CI against a fake `launchctl`; Node's `launchdDomain()` refuses off
+  `darwin` unless a test passes `platform: 'darwin'`. Neither runs launchd off macOS: install with
+  `systemd_install` / `task_install` there (FAA-286 item 5, recorded rather than aligned).
 
 ## One copy under a supervisor
 
@@ -205,6 +222,10 @@ if the holder leaves, and exits 75 only when the wait runs out: a few starts an
 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.
 
+A context refusal (`fabric_context`, exit 78: no record, a revoked grant, a folder of another context) is the same
+loop under `KeepAlive`, so a supervised copy waits the same back-off, holding nothing and with the lock released,
+before it exits 78 (FAA-279); started by hand it exits 78 at once.
+
 The marker (contract DEC-0057, CT-01) is the variable `FABRIC_SERVICE_SUPERVISOR=<manager>` or
 the argument `--fabric-supervisor <manager>` (also `--fabric-supervisor=<manager>`), after the
 executable and before any `--`; `<manager>` is `launchd`, `systemd`, `task-scheduler` or `node`
@@ -323,7 +344,7 @@ descriptor says `"lifecycle": {"manager": "systemd", "unit": "<id>.<instance>.se
 
 | 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` |
+| 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`. With `origin` and `service_id` it then polls the well-known answer as `launchd_install` does until this account's listener answers (another account's is refused, DEC-0154 HA-2; FAA-253); Node's `systemdInstall` then returns a promise |
 | stop, keep off | `systemctl --user disable --now <unit>` |
 | uninstall | `systemd_uninstall` / `systemdUninstall`: `disable --now`, remove the unit, `daemon-reload` |
 
@@ -340,7 +361,7 @@ CI job has the real `schtasks` create, read back and delete such a task. The des
 
 | 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` |
+| 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`. With `origin` and `service_id` it then polls as `launchd_install` does and returns the answer (FAA-253); Node's `taskInstall` then returns a promise |
 | stop, keep off | `schtasks /End /TN <task>`, then `schtasks /Change /TN <task> /DISABLE` |
 | uninstall | `task_uninstall` / `taskUninstall`: `/End`, then `/Delete /F` |
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/migrating-a-service.md

@@ -31,4 +31,5 @@ Order matters: each step leaves the service answering.
 | Data, logs or caches inside the repository | the OS data, log and cache directories; the old tree read-only for one release |
 | `KeepAlive {SuccessfulExit:false}`, a plist pointing at a checkout or a worktree | a plist generated by `launchd_plist`, pointing at a release |
 | A port another service already uses by default | the port claim at install; move the newcomer |
+| A port held by socket activation (launchd `Sockets`, a systemd `.socket` unit) or by a root proxy in front of the service | the service binds `127.0.0.1:<port>` itself as its own account; launchd's or root's socket reads as `system` and the hosts' and the probe's `listener.owner` refuse it (DEC-0154 HA-2) |
 | An event log in a private shape | the events view over it, with one sentence per event |

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

@@ -42,6 +42,16 @@ python3 scripts/fabric_package.py pack <folder>           # a dry run: the packa
 python3 scripts/fabric_package.py pack <folder> --apply   # writes fabric.package.json when nothing is wrong
 ```
 
+When the folder carries the agent's source manifest, `fabric.source.json` (contract DEC-0149, `fabric-source/1`), `pack`
+writes `secrets[]` from its `secret` slots (name, purpose and `optional`) and `state[]` from its `store` slots' paths,
+says so in its notes, and lists the manifest in `files[]` like any other file; `pack`, `sign` and `verify` refuse a
+package whose `secrets[]` or `state[]` differ from the slots (FAC-SEM-160). A hand-written `secrets[]` naming a secret
+the manifest has no slot for is never dropped: `pack` refuses (rule `source`, `/secrets`) and names each one, so add
+it as a `secret` slot (or take it out) and pack again. An author's `state: []` is a copy packed
+without state and is kept. A manifest that is no `fabric-source/1` object is refused. The manifest's own rules and the
+tree check under it are the source check's (`references/source-and-instance.md` of adapting-projects-to-fabric, *The
+source manifest*).
+
 Run `adapting-projects-to-fabric/scripts/fabric_source_check.py check <folder> --every-file` on the folder you pack first (a floor under your own
 review, not a secret scanner): a package carries
 the source, and the instance (the owner's paths, keys, strings) stays out of it (`references/source-and-instance.md` of

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

@@ -1,6 +1,6 @@
 # fabric-service/0.1: wire reference
 
-Pinned to `fabric-agent-contract` commit `18f8d48762edc5bfb1433657cbfe1c16196df1a6`
+Pinned to `fabric-agent-contract` commit `93e7db164c7829e2783b4b7705c4113bb5201131`
 (`docs/specification/service.md`, DEC-0015; the usage report DEC-0021; Windows and Linux supervision
 DEC-0032 and DEC-0033; the operator channel DEC-0034 and DEC-0035; the embedded dashboard DEC-0036;
 delegation and the operator session's lifetime DEC-0039; the meter's call window DEC-0041; session handoff DEC-0042;
@@ -224,7 +224,8 @@ well-known `process.pid` is never proof (`docs/specification/service.md#ha-2` at
 The kit's module is `fabric_peer_owner` / `fabric-peer-owner.mjs` (layer L0, [kit modules](kit-modules.md)): `listener(port)`,
 `server_end(sock)` / `serverEnd(socket)`, `peer`, and a connection checked before a byte is written
 (`CheckedHTTPConnection`; Node `checkedSocket`, `CheckedAgent`). Python reads macOS through `sysctl
-net.inet.tcp.pcblist_n` (calibrated on a connected pair of its own, else `netstat -anv`), Linux through `/proc/net/tcp`
+net.inet.tcp.pcblist_n` (calibrated on a connected pair of its own, else `netstat -anv`; the pinned HA-2 table names
+`netstat -anv` and `pcblist64`, an older record layout of the same kernel table), Linux through `/proc/net/tcp`
 and `/proc/net/tcp6`, Windows through `GetExtendedTcpTable` and the owner's token SID; Node reads `netstat -anv` and `ps`
 on macOS, the same `/proc` files on Linux, and `netstat -ano` with the owner SID from PowerShell `GetOwnerSid` against `whoami /user` on Windows (SIDs, never names). Fail closed: everything but
 `this-account` refuses, `unknown` included.
@@ -238,17 +239,34 @@ listener of this account's pid on the port counts as this account's (`CheckedHTT
 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 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.
+the pin's ruling on vouching is DEC-0155 RT-3 (the contract's CT-261), which vouches only for a listen on exactly
+`127.0.0.1`: the kit's IPv4 wildcard vouch for a LaunchAgent departs from it until a later release (filed by FAA-258).
 
 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),
+a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub client (`HubError` `foreign-user`, its
+`data.reason` and sentence the owner's reason: `table-restricted`, then not retryable, or the owner's kind or `no-row`, FAA-272),
+`fabric_http` / `fabric-http.mjs` for a plain `http://` loopback URL (`HttpError` kind `foreign-user` with the same `reason`, 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, 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
-claim file (HA-1) waits on the contract's CT-228.
+misread; the Python twin's `sysctl` reader takes both from one record. The server side (HA-2, HA-3; FAA-227): the kit's `LoopbackHTTPServer` and Node's `loopbackServer(httpServer)` tell
+each accepted connection's peer (`peer`) before a byte of the request is read, in the connection's own thread or
+while the socket is still paused. `peer_check` / `peerCheck` (`PEER_CHECKS`): `refuse`, the default, closes a peer of
+another OS account unread and serves the rest; `strict` also refuses an owner nobody can tell (a restricted table
+included) and a system account other than root (uid 0, which can read every account's files anyway and installs a
+LaunchDaemon; a Windows service account is refused); `off` reads no table. The check applies to loopback peers
+(127.0.0.0/8, `::1`, either IPv4-mapped): HA-2 is about another account of this computer, so a peer at any other
+address (a service bound to `0.0.0.0`) is served under `refuse` and `strict` alike without a table read, and its
+owner is none (`peer_owner()` None, `connectionOwner` null); such a peer is never T0 or T1. Use `strict` for a dashboard, an MCP
+surface or a token-free door on a computer with several counted accounts, where the interpreter sees the whole
+table (Apple's `/usr/bin/python3`, not an ad-hoc-signed one on macOS 27.2). A refusal writes one line on stderr
+(kind, uid, pid, never the peer's bytes); a handler finds its peer's owner with `self.server.peer_owner()` or
+`connectionOwner(req.socket)`. The cost is one table read per connection, not per request: a few milliseconds from
+`sysctl` or `/proc` in-process; Node on macOS and Windows runs `netstat` and `ps` or PowerShell for each, tens to
+hundreds of milliseconds, so a Node service there that answers the well-known read within 100 ms keeps its
+connections alive or chooses `off` where one account uses the computer. The port claim file (HA-1) waits on the
+contract's CT-228.
 
 ## Semantic rules a host applies
 

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

@@ -10,6 +10,7 @@ DEC-0019, at the commit this skill pins. This page is the how-to.
 - [On the platform](#on-the-platform)
 - [Checking it](#checking-it)
 - [What a host does and will not do](#what-a-host-does-and-will-not-do)
+- [Registered from several hosts](#registered-from-several-hosts)
 - [Rotation](#rotation)
 
 ## Is it a remote service?
@@ -68,8 +69,9 @@ watch the gate fail.
 ## On the platform
 
 - **Token**: a random value of at least 16 characters (32 bytes recommended), set as a secret;
-  the same value is written on the operator's computer by `registerRemote`. Compare in constant
-  time (`tokenMatches`).
+  the same value is written on the registering host by `registerRemote`. Compare in constant
+  time (`tokenMatches`). A service registered from more than one host holds one token per host
+  ([Registered from several hosts](#registered-from-several-hosts)).
 - **Session key**: 32 random bytes, a separate secret; rotating it signs every operator out.
 - **Codes and sessions**: `MemoryCodeStore`: a restart forgets every outstanding code, so none
   can be replayed, and every session record, so a deploy signs the operator out (DEC-0039: the
@@ -122,10 +124,49 @@ The login rules keep every `Set-Cookie` of the answer and judge the session cook
 | start, stop, restart, update | not offered |
 | a host older than the remote placement | shows the service as invalid and never contacts it |
 
+## Registered from several hosts
+
+One cloud service is often registered from more than one host: the operator's two computers, or an organization's
+space beside a personal one (FAA-280). Each registering host gets **its own token**; a token is never copied from one
+host to another, so one host can be revoked or rotated without touching the others.
+
+- **On the platform**, keep one secret per host (`FABRIC_HOST_TOKEN_<HOST>`, each at least 16 characters) and accept
+  a request whose bearer matches any of them. Compare it with every token, each with `tokenMatches` /
+  `token_matches`, with no early return, so the answer's timing does not say which host's token matched:
+
+  ```python
+  def host_of(authorization, tokens):  # tokens: {host name: token}; the kit's comparison, once per token
+      matched = [host for host, token in sorted(tokens.items()) if fs.token_matches(authorization, token)]
+      return matched[0] if matched else None  # None: a 401 with an empty body, as with one token
+  ```
+
+  `well_known_allowed` / `wellKnownAllowed` take one token: call it once per token the same way, or gate the route on
+  `host_of(...) is not None`.
+- **On each host**, run `registerRemote` / `register_remote` with that host's token only. The descriptor is the same
+  on every host but its `tokenFile`, which holds that host's value and nothing else (0600, never printed).
+- **Sign-in**: `LoginCodes` binds a session to one token's revision. Give each host its own `LoginCodes` with
+  `token=` that host's token and its own store (`MemoryCodeStore`, or a durable row per host); the session key may be
+  shared. Issue the login code from the instance whose token the bearer matched; redeem a code and check a session by
+  trying each instance in turn (a code another instance issued is not in its store, and a session cookie carries
+  another token's revision, so neither changes anything there). Removing or rotating one host's token then ends that
+  host's sessions only. One `LoginCodes` whose `token=` is a callable returning every token joined also works, and
+  signs every host out when any one rotates.
+- **The probe**: `check_service.py <id>` run on a host sends that host's token, so `well-known.requires-token` passes
+  on each; the request without a token, or with a value no host holds, still gets the `401` with an empty body.
+- **Revoking a host**: delete its secret on the platform and restart; that host then sees `401` and shows the service
+  `down`, never `foreign`. Remove its descriptor there with `remove_descriptor` / `removeDescriptor`.
+- **Adding a host**: create its secret, restart, then `registerRemote` on the new host. The other hosts' tokens and
+  sessions do not change.
+
+A token per host still gives each host the descriptor token's whole authority over the service. A remote surface no
+host token reaches (callers with their own delegation, the page opened only with Fabric Dashboards' one-time code)
+is the "local and cloud" form, FAA-204, which waits on the contract recording that form.
+
 ## Rotation
 
 Rotate the token by setting the new value on the platform and re-running `registerRemote` on the
-operator's computer with it; the old token stops working the moment the platform restarts with the
+registering host with it (on a service registered from several hosts, only that host's token,
+[above](#registered-from-several-hosts)); the old token stops working the moment the platform restarts with the
 new value, and so does every session begun under it when `LoginCodes` has `token=`. The re-run keeps the
 installed `source` when it passes none (one the kit refuses, edited by hand, is dropped with the warning); pass
 `runner`, `peer`, `summary`, `doctor` and `installedBy` / `installed_by` again, since a re-run writes only what it is

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_dashboard_layout.mjs

@@ -127,6 +127,25 @@ async function serviceTarget(spec, dir) {
   return { url, declared, name: `${id}.${instance}` };
 }
 
+// DEC-0154 PL-3 and HA-2 (FAA-260 items 2 and 14): a raw loopback address opens in the browser only while its port's
+// listener is this OS account's, read from the socket table just before the page opens. The browser connects on its
+// own, so this is the listener's owner, not that connection's: a listener swapped in between stays a residue
+// (SECURITY.md). A copy of this file alone cannot tell the owner and opens no loopback page.
+async function loopbackRefusal(target) {
+  let url;
+  try { url = new URL(target); } catch { return null; }
+  if (url.protocol !== 'http:') return null;
+  const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (!(host === 'localhost' || host.endsWith('.localhost') || /^127\./.test(host) || host === '::1'
+    || host === '0.0.0.0' || /^::ffff:(127\.|7f)/.test(host))) return null;
+  const po = await import('./fabric-peer-owner.mjs').catch(() => null);
+  if (!po) return 'fabric-peer-owner.mjs is not beside this file: the loopback listener\'s owner cannot be told, so the page is not opened (DEC-0154 HA-2)';
+  const port = Number(url.port || 80);
+  const who = await po.listener(port);
+  if (who.kind === po.THIS_ACCOUNT) return null;
+  return `foreign-user: the listener on port ${port} reads as ${who.kind}${who.reason ? ` (${who.reason})` : ''}, so the page is not opened (DEC-0154 PL-3, HA-2)`;
+}
+
 // Runs inside the page. Everything it reports is measured from the rendered layout.
 function measure([floor, cap]) {
   const de = document.documentElement;
@@ -319,6 +338,8 @@ async function main(argv) {
   try {
     const context = await browser.newContext({ viewport: { width: Math.max(...opts.widths), height: opts.height } });
     const page = await context.newPage();
+    const refused = await loopbackRefusal(target);
+    if (refused) return notRun(refused);
     const response = await page.goto(target, { waitUntil: 'load' });
     if (response && !response.ok()) {
       return notRun(`the page answered HTTP ${response.status()}`);

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

@@ -28,8 +28,14 @@ CREDENTIAL_PAIRS = {
     'session': {'token', 'id'},
     'code': {'login', 'auth', 'access', 'session'}}
 JWT_SHAPE = re.compile(r'eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*')
-SECRET_VALUE = re.compile(r'(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}'
-                          r'|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})', re.I | re.S)
+# The contract's SECRET_VALUE at the pin (DEC-0151): `Bearer ` at a value's start in any case, or a provider key with its
+# prefix in its canonical case after a boundary (the start, a character that is no ASCII letter or digit, or an escape);
+# an `sk-` key holds a digit and an upper-case letter with 16 or more characters, or a digit with 32 or more.
+SECRET_VALUE = re.compile(r'(^[Bb][Ee][Aa][Rr][Ee][Rr]\s.+|(?:^|[^A-Za-z0-9]|%[0-9A-Fa-f]{2}|\\[nrt"\']|\\u[0-9A-Fa-f]{4}'
+                          r'|\\x[0-9A-Fa-f]{2}|\\[bfv0ae]|\\[0-7]{1,3}|%25[0-9A-Fa-f]{2}|\x1b\[[0-9;:]*m'
+                          r'|(?:\\u001[bB]|\\x1[bB]|\\e|\\033|\\33)\[[0-9;:]*m)'
+                          r'(?:sk-(?=[A-Za-z0-9_-]{0,255}?[0-9])(?:(?=[A-Za-z0-9_-]{0,255}?[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})'
+                          r'|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}))', re.S)
 LONG_RUN = re.compile(r'[A-Za-z0-9+/=_-]{40,}')
 
 
@@ -115,6 +121,11 @@ def check(data):
     require(all(isinstance(v, str) and 0 < len(v) <= 200 for v in (target, viewer)), 'missing_device')
     fallback = data.get('fallback', 'if_absent')
     require(fallback in ('if_absent', 'never'), 'invalid_fallback')
+    # DEC-0154 PL-3 and HA-2 (FAA-251): who listens on http_url's port, as the host read it from the socket table
+    # (fabric_peer_owner's kinds, or check_service.py's foreign-user). A browser opens a raw loopback address only
+    # after that listener is this OS account's; absent, it is unknown.
+    owner = data.get('listener_owner', 'unknown')
+    require(owner in ('this-account', 'another-account', 'system', 'unknown', 'none', 'foreign-user'), 'invalid_listener_owner')
     kind = action.get('kind')
     if kind == 'remote_open':
         require(set(action) <= {'kind', 'device_id', 'service', 'path'}, 'unexpected_action_field')
@@ -128,17 +139,26 @@ def check(data):
         require(set(action) == {'kind', 'url'} and action.get('url') == http, 'not_resolved_http_url')
         require(viewer == target, 'wrong_viewer_device')
         require(state == 'not_installed' and fallback == 'if_absent', 'browser_fallback_forbidden')
+        require(owner == 'this-account', 'listener_not_this_account')
     else:
         raise ValueError('unsupported_dashboard_action')
     return {'ok': True, 'kind': kind}
 
 
+def read_input(limit=65536):
+    # The handoff's bytes, decoded as UTF-8 with a byte order mark dropped: Windows before Python 3.15 decodes a text
+    # stdin with its code page, which misreads a Cyrillic handoff (FAA-210). A stream without bytes is read as text.
+    stream = getattr(sys.stdin, 'buffer', None)
+    raw = stream.read(limit + 1) if stream is not None else sys.stdin.read(limit + 1)
+    require(len(raw) <= limit, 'input_too_large')
+    return raw.decode('utf-8-sig') if isinstance(raw, bytes) else raw.lstrip('\ufeff')
+
+
 def main():
     try:
-        raw = sys.stdin.read(65537)
-        require(len(raw) <= 65536, 'input_too_large')
-        result = check(json.loads(raw))
-    except (ValueError, TypeError, KeyError, AttributeError):
+        result = check(json.loads(read_input()))
+    # RecursionError: Python 3.9 to 3.13 raise it on a deeply nested document under the cap
+    except (ValueError, TypeError, KeyError, AttributeError, RecursionError):
         # Fixed reasons only: never echo a submitted URL, token or JSON blob.
         result = {'ok': False, 'reason': 'dashboard_handoff_refused'}
     print(json.dumps(result))