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

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

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""Create a Fabric agent project with the contract built in, in one command (FAA-270, North Star G21).
+
+  python3 new_agent.py <folder> --id <agent-id> [--profile mcp|a2a|local-runner] [--service]
+                       [--capability NAME] [--effect CLASS] [--force] [--json]
+
+It writes, into an empty (or new) folder:
+
+- the provider bundle `adapt_project.py scaffold` writes, pinned to the contract (`fabric-agent.json`,
+  `fabric-contract.lock.json`, `fabric/`), every value it invents a sentinel `adapt_project.py check` names;
+- `fabric.source.json`, the agent's source manifest (DEC-0149, `fabric-source/1`): what is source, default deny, and the
+  slots an installation fills (the publisher's URI behind `provider.createdBy`, the placement record and, for a
+  service, its supervisor label and port), never a value;
+- the placement guard (`src/placement.py`, with its tests in `tests/`): at start the agent reads Project Observatory's
+  placement record (`observatory-placement/1`) and refuses to start where the record places it on another machine,
+  starts degraded when it cannot read it, and starts when there is none; `config/placement.example.json` shows the
+  record's shape on neutral values;
+- `README.md`, `LICENSE` (all rights reserved until the owner names the terms), `.gitignore`;
+- with `--service`: `service/`, the service kit's sample (`service.py`, a fabric-service/0.1 service with one capability
+  and a job) and the kit modules it imports, copied by `fabric_kit.py install`, whose digests `fabric_kit.py status`
+  checks later.
+
+A repeat with the same arguments in a folder this command made changes nothing and answers the same line. A folder that
+holds anything else is refused unless `--force`, which writes the planned files over it and leaves every other file as
+it is. The last stdout line is `{"folder": "<path>", "id": "<id>", "profile": "<profile>", "service": <bool>,
+"created": [<paths>], "repeated": <bool>}` (`--json` prints only it). Exit 0 made or already made, 1 refused (the
+reason on stderr), 2 usage. Writes nothing outside the folder; reads no key and no instance data. Standard library only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import re
+import shutil
+import sys
+from typing import Any, Dict, List, Optional, Sequence
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+import adapt_project as ap  # noqa: E402 - the scaffolder and the source manifest, beside this file
+
+VERSION = "0.1.0"
+RECORD = "fabric/new-agent.json"
+#: The agent's id: the package's `name` grammar (`fabric-package.schema.json#/$defs/name`), kebab case.
+AGENT_ID = re.compile(r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*\Z")
+CAPABILITY = re.compile(r"[a-z][a-z0-9._-]{1,127}\Z")
+KIT = HERE.parent.parent / "building-fabric-services" / "scripts"
+#: What the sample service imports; `fabric_kit.py install` copies each one's closure.
+SERVICE_MODULES = ("fabric_service", "fabric_interop", "fabric_board", "fabric_hub")
+
+
+class Refused(Exception):
+    """The folder cannot be made as asked; the reason is printed, never a value."""
+
+
+PLACEMENT_PY = '''"""The placement guard: at start, before the agent polls, schedules or listens, it reads Project Observatory's
+placement record and runs only on the machine that record names (creating-fabric-agents, where-agents-run.md).
+
+    verdict(service_id, label) -> {"state": "ok" | "placed-elsewhere" | "placement-unreadable", "machine"?}
+
+`placed-elsewhere`: the record's `elsewhere` list names this agent (its `serviceId` or its supervisor `label`) on a
+machine that is not this one: refuse to start, log one line, report it as degraded. `placement-unreadable`: the file is
+there and cannot be read, or is of another schema: start, and report it as degraded. No file: start.
+"""
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+SCHEMA = "observatory-placement/1"
+
+
+def placement_path(env: Optional[Dict[str, str]] = None) -> Path:
+    env = os.environ if env is None else env
+    base = env.get("XDG_DATA_HOME") or ""
+    root = Path(base) if os.path.isabs(base) else Path.home() / ".local" / "share"
+    return root / "project-observatory" / "placement.json"
+
+
+def verdict(service_id: str, label: str, path: Optional[Path] = None) -> Dict[str, Any]:
+    path = placement_path() if path is None else path
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        return {"state": "ok"}
+    except OSError:
+        return {"state": "placement-unreadable"}
+    try:
+        doc = json.loads(data.decode("utf-8"))
+    except ValueError:
+        return {"state": "placement-unreadable"}
+    if not isinstance(doc, dict) or doc.get("schema") != SCHEMA or not isinstance(doc.get("elsewhere"), list):
+        return {"state": "placement-unreadable"}
+    for entry in doc["elsewhere"]:
+        if not isinstance(entry, dict):
+            continue
+        ours = (service_id and entry.get("serviceId") == service_id) or (label and entry.get("label") == label)
+        if ours and entry.get("placedOn") and entry.get("placedOn") != doc.get("machine"):
+            return {"state": "placed-elsewhere", "machine": entry.get("placedOn")}
+    return {"state": "ok"}
+'''
+
+PLACEMENT_TEST = '''"""The placement guard: one copy placed elsewhere refuses, one with no file and one with a malformed file start."""
+import json
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+import placement  # noqa: E402
+
+EXAMPLE = Path(__file__).resolve().parents[1] / "config" / "placement.example.json"
+
+
+class PlacementTests(unittest.TestCase):
+    def setUp(self):
+        self.folder = tempfile.TemporaryDirectory()
+        self.addCleanup(self.folder.cleanup)
+        self.path = Path(self.folder.name) / "placement.json"
+
+    def test_placed_elsewhere_refuses(self):
+        self.path.write_text(EXAMPLE.read_text(encoding="utf-8"), encoding="utf-8")
+        found = placement.verdict("{service_id}", "{label}", self.path)
+        self.assertEqual(found["state"], "placed-elsewhere")
+
+    def test_no_file_starts(self):
+        self.assertEqual(placement.verdict("{service_id}", "{label}", self.path), {{"state": "ok"}})
+
+    def test_a_malformed_file_starts_degraded(self):
+        self.path.write_text("{{not json", encoding="utf-8")
+        self.assertEqual(placement.verdict("{service_id}", "{label}", self.path), {{"state": "placement-unreadable"}})
+        self.path.write_text(json.dumps({{"schema": "another/1"}}), encoding="utf-8")
+        self.assertEqual(placement.verdict("{service_id}", "{label}", self.path)["state"], "placement-unreadable")
+
+    def test_placed_on_this_machine_starts(self):
+        doc = json.loads(EXAMPLE.read_text(encoding="utf-8"))
+        doc["machine"] = doc["elsewhere"][0]["placedOn"]
+        self.path.write_text(json.dumps(doc), encoding="utf-8")
+        self.assertEqual(placement.verdict("{service_id}", "{label}", self.path), {{"state": "ok"}})
+
+
+if __name__ == "__main__":
+    unittest.main()
+'''
+
+README = '''# {agent_id}
+
+A Fabric agent made with the Fabric Agent Adapter's `new` command, contract `{contract}` at `{commit}`.
+
+## Layout
+
+- `fabric-agent.json`, `fabric-contract.lock.json`, `fabric/`: the provider bundle, pinned to the contract. Every value
+  the scaffold invented is a sentinel: `adapt_project.py check` names each one until it is replaced.
+- `fabric.source.json`: the agent's source manifest (DEC-0149): what is source, and the slots an installation fills,
+  never a value. `fabric_source_check.py check .` reads the source under it (exit 0 before every release).
+- `src/placement.py`: the placement guard the agent runs at start, before it polls, schedules or listens.
+{service_line}
+## Configure
+
+Keys are read by name from the environment or the secret store, never from a file of this repository. Slots:
+{slots}
+
+## Data
+
+The agent's data lives apart from this source, in its data home (`<agent>-data`, or the service kit's folders), from
+the first commit.
+'''
+
+GITIGNORE = """# the instance: real configuration, keys and what running the agent leaves
+config/*.json
+!config/*.example.json
+.env
+.env.*
+!.env.example
+*.token
+*.credential
+__pycache__/
+*.pyc
+"""
+
+
+def _placement_example(service_id: str, label: str) -> str:
+    return ap._json_text({"schema": "observatory-placement/1", "machine": "example-machine-a", "updatedAt": "2026-01-01T00:00:00Z",
+                          "elsewhere": [{"label": label, "serviceId": service_id, "placedOn": "example-machine-b",
+                                         "since": "2026-01-01T00:00:00Z", "by": "full machine-move leave"}]})
+
+
+def plan(args: argparse.Namespace) -> Dict[str, str]:
+    """Every file the command writes, by its path, with its text (the scaffold's own included)."""
+    agent_id = args.id
+    capability = args.capability or "%s.run" % agent_id.replace("-", "_")
+    if not CAPABILITY.match(capability):
+        raise Refused("--capability %r is not a capability name (lower case, `domain.action`)" % capability)
+    scaffold = argparse.Namespace(
+        profile=args.profile, provider_id="urn:fabric:provider:%s" % agent_id, provider_name=agent_id,
+        capability_id="urn:fabric:capability:%s" % capability, capability_name=capability,
+        schema_base="https://replace.invalid/%s/schemas" % agent_id, mcp_mode="streamable-http",
+        mcp_url="https://replace.invalid/mcp", agent_card_url="https://replace.invalid/.well-known/agent-card.json",
+        runner_kind="replace-me", executable_ref="urn:executable:replace-me", runtime_arg=[], effect=args.effect,
+        idempotency="none", cost_preset=[], default_cost_preset=None, job=False, created_by=None, identity_method=None,
+        data_class=[], probe_assertion=[])
+    files = dict(ap._generated_files(scaffold))
+    service_id = "%s.default" % agent_id
+    label = "com.example.%s" % agent_id
+    include = ["README.md", "LICENSE", ".gitignore", "src/", "tests/", "config/placement.example.json",
+               "fabric-agent.json", "fabric-contract.lock.json", "fabric/"] + (["service/"] if args.service else [])
+    manifest = ap.source_manifest(include, "%s, a Fabric agent" % agent_id, service=args.service)
+    slots = "\n".join("- `%s` (%s%s): %s" % (s["name"], s["kind"], ", optional" if s.get("optional") else "", s["purpose"])
+                      for s in manifest["slots"])
+    files.update({
+        ap.SOURCE_FILE: ap._json_text(manifest),
+        "README.md": README.format(agent_id=agent_id, contract=ap.CONTRACT_VERSION, commit=ap.CONTRACT_COMMIT[:12], slots=slots,
+                                   service_line="- `service/`: the service kit's sample, run as `python3 service/service.py "
+                                   "serve --id %s --port <port> --data-dir <data>`, and the kit modules it imports.\n" % agent_id
+                                   if args.service else ""),
+        "LICENSE": "Copyright (c) the owner of %s. All rights reserved, until the owner names other terms.\n" % agent_id,
+        ".gitignore": GITIGNORE,
+        "src/placement.py": PLACEMENT_PY,
+        "tests/test_placement.py": PLACEMENT_TEST.format(service_id=service_id, label=label),
+        "config/placement.example.json": _placement_example(service_id, label),
+    })
+    record = {"tool": "fabric-agent-adapter new %s" % VERSION, "id": agent_id, "profile": args.profile, "service": args.service,
+              "capability": capability, "effect": args.effect, "contract": ap.CONTRACT_COMMIT}
+    files[RECORD] = ap._json_text(record)
+    return files
+
+
+def _service_files(folder: Path) -> List[str]:
+    """Copy the kit's sample and the closure of what it imports into `service/` (fabric_kit.py install)."""
+    import importlib.util
+    found = importlib.util.spec_from_file_location("fabric_kit", KIT / "fabric_kit.py")  # the kit's own installer
+    fabric_kit = importlib.util.module_from_spec(found)
+    found.loader.exec_module(fabric_kit)  # type: ignore[union-attr]
+    target = folder / "service"
+    result = fabric_kit.install(target, "python", list(SERVICE_MODULES))
+    if result["refused"]:
+        raise Refused("service/ holds kit modules this kit does not recognise: %s" % ", ".join(result["refused"]))
+    shutil.copyfile(KIT / "sample_service.py", target / "service.py")
+    return ["service/" + name for name in result["copied"] + result["kept"]] + ["service/service.py"]
+
+
+def make(folder: Path, args: argparse.Namespace) -> Dict[str, Any]:
+    if not AGENT_ID.match(args.id) or len(args.id) > 64:
+        raise Refused("--id %r is not an agent id (lower case words joined by -, at most 64 characters)" % args.id)
+    files = plan(args)
+    answer = {"folder": str(folder), "id": args.id, "profile": args.profile, "service": args.service}
+    if folder.exists() and not folder.is_dir():
+        raise Refused("%s is not a folder" % folder.name)
+    present = sorted(p.relative_to(folder).as_posix() for p in folder.rglob("*")) if folder.is_dir() else []
+    if present:
+        record = folder / RECORD
+        try:
+            same = record.is_file() and json.loads(record.read_text(encoding="utf-8")) == json.loads(files[RECORD])
+        except ValueError:
+            same = False
+        if same and all((folder / path).is_file() for path in files) and not args.force:
+            return dict(answer, created=[], repeated=True)
+        if not args.force:
+            raise Refused("the folder is not empty and was not made by this command with these arguments: "
+                          "name another folder, or pass --force to write the planned files over it")
+    for path, text in files.items():
+        target = folder / path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding="utf-8")
+    created = sorted(files)
+    if args.service:
+        created = sorted(created + _service_files(folder))
+    return dict(answer, created=created, repeated=False)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="new_agent.py", description="Create a Fabric agent project with the contract built in.")
+    parser.add_argument("folder", type=Path)
+    parser.add_argument("--id", required=True, help="the agent's id, kebab case (example-agent)")
+    parser.add_argument("--profile", choices=("mcp", "a2a", "local-runner"), default="mcp")
+    parser.add_argument("--service", action="store_true", help="also wire the service kit's sample (fabric-service/0.1)")
+    parser.add_argument("--capability", help="its capability, `domain.action` (default <id>.run)")
+    parser.add_argument("--effect", choices=ap.EFFECT_CLASSES, default="none",
+                        help="the capability's effect class (default none: declare money, deletion or publication now)")
+    parser.add_argument("--force", action="store_true", help="write the planned files into a folder that holds others")
+    parser.add_argument("--json", action="store_true", help="print only the last line")
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    try:
+        args = build_parser().parse_args(argv)
+    except SystemExit as exc:
+        return exc.code if isinstance(exc.code, int) else 2
+    try:
+        answer = make(args.folder.expanduser().resolve(), args)
+    except (Refused, ap.AdaptationError, OSError) as exc:
+        print("new_agent.py: %s" % (exc if not isinstance(exc, OSError) else "the folder cannot be written (%s)"
+                                    % type(exc).__name__), file=sys.stderr)
+        return 1
+    if not args.json:
+        print("%s %s: %d file(s)%s" % ("already made" if answer["repeated"] else "made", args.id, len(answer["created"]),
+                                       "" if answer["repeated"] else "; next: replace the sentinels `adapt_project.py check` "
+                                       "names, then run fabric_source_check.py check on the folder"))
+    print(json.dumps(answer, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -9,10 +9,10 @@ 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.80.2"
+  version: "0.81.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "18f8d48762edc5bfb1433657cbfe1c16196df1a6"
+  extension-commit: "93e7db164c7829e2783b4b7705c4113bb5201131"
 ---
 
 # Building Fabric services
@@ -82,7 +82,9 @@ MCP registration into a client config, the login flow or the CSRF header.
 When other agents or Fabric call the service over MCP, it follows `fabric-interop/0.1`:
 each manifest capability is the tool of its name, long work is a job with a stable id,
 a question for a person is an elicitation, and every call carries one trace. A job a limit stops or pauses, and an
-effect nobody saw, have their own codes and a key per caller (DEC-0087). Read
+effect nobody saw, have their own codes and a key per caller (DEC-0087); work held by the service's own limits is
+said on the job, pushed to the operator once per hold and lifted by their scoped answer (`scripts/fabric_holds.py`,
+FAA-298). Read
 [the interop reference](references/interop.md) before writing an MCP tool; the helpers
 are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
 [`scripts/fabric-interop.mjs`](scripts/fabric-interop.mjs). When the callers are agents of the estate, the

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/README.md

@@ -2,7 +2,7 @@
 
 A service answers one inbound question from its own knowledge file, or hands it to a person. It is a step of an
 agent that answers people, not that agent: see the paragraph after the table. Under the creating-fabric-agents
-template (`communication-agent-template.md`) the plan-and-draft call writes the draft, not this recipe's `answer()`:
+template (`templates/communication-agent/`, read through `references/communication-agent-template.md`) the plan-and-draft call writes the draft, not this recipe's `answer()`:
 the draft carries a `[KB:<id>]` marker for each knowledge id the plan used, and the agent runs `check_reply(draft,
 question, prompt_ids, max_chars=..., sources=...)` on it for the code checks. `prompt_ids` are the ids of the items
 placed in the plan's prompt, never the plan's own list (an id the plan names outside them is held as a suspected

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

@@ -65,8 +65,8 @@ host's `open` with `fallback=never`. Never `open <url>`, `open -a Safari`,
 agent's pages. A browser only when `host_status` confirms `not_installed`, and
 a raw `http://127.0.0.1:<port>` address only after the listener on that port is
 this OS account's (DEC-0154 PL-3 and HA-2; the adapter's `building-fabric-services/scripts/fabric_peer_owner.py`: `server_end` of a connection it opens and sends nothing on; `check_service.py <id>.<instance>` prints it as `listener.owner`): a
-`foreign-user` listener is reported, never opened (the link gate below does not
-read the owner yet, FAA-251). An installed host that failed
+`foreign-user` listener is reported, never opened (the link gate below takes
+that owner as `listener_owner`). An installed host that failed
 to open is reported, not replaced by HTTP. Links
 carry no token or login code. Every completion and notification action passes
 the Fabric Agent Adapter's link gate before delivery: `check_dashboard_link.py`
@@ -119,7 +119,12 @@ Its trusted context is supplied by the host, not by untrusted model output:
 
 `native_link` must equal the resolved open_link, with an available host on the
 viewer's device. `browser_link` must equal http_url, with confirmed not_installed,
-if_absent policy and the same device. Contract DEC-0123 PL-3 also allows a browser
+if_absent policy, the same device and `"listener_owner": "this-account"`: the kind
+the host read for the listener on http_url's port (`fabric_peer_owner`'s
+`this-account`, `another-account`, `system`, `unknown`, `none`, or
+`check_service.py`'s `foreign-user`); any other, or none given, refuses the
+browser (DEC-0154 PL-3, FAA-251). The native link does not take it: Fabric
+Dashboards checks its own listener. Contract DEC-0123 PL-3 also allows a browser
 on `unsupported` (a system the host does not ship for); the gate treats
 `unsupported` as no fallback, by the operator's rule that a browser opens only on a
 confirmed `not_installed`, and macOS never reports it (FAA-137). `remote_open` instead contains `device_id`,

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

@@ -53,8 +53,11 @@ the same owner; **T2** everyone else, and any call relayed onto loopback from of
 hub forwarding a T2 caller). DL-26: a T0 or T1 caller is never required to present a token; pass the tier,
 `gate(tool, headers, tier="T0")` or `server.handle(message, headers, tier="T0")`, and the call passes with no
 delegation. On a computer with more than one counted OS account, a loopback caller with no token is T0 only after the
-door checks the peer's account (the pinned DEC-0154 HA-3 and DL-25; the kit's own peer check is FAA-227), so pass
-`tier="T0"` there only for a caller the descriptor token authenticated. A token such a caller presents is still verified and refused when invalid. A T2 caller takes the whole
+door checks the peer's account (the pinned DEC-0154 HA-3 and DL-25): the kit's `LoopbackHTTPServer` with `peer_check="strict"` (Node
+`loopbackServer(app, {peerCheck: 'strict'})`, [protocol.md](protocol.md#the-listeners-owner-dec-0154-ha-2)) is that check,
+for loopback peers: pass `tier="T0"` only when the handler's `self.server.peer_owner()` (`connectionOwner(req.socket)`)
+names an owner, since a peer off loopback is served without one and is T2;
+otherwise pass `tier="T0"` there only for a caller the descriptor token authenticated. A token such a caller presents is still verified and refused when invalid. A T2 caller takes the whole
 profile. Money limits and human gates bind at every tier.
 
 **The family and the agent network** (DEC-0130, wording settled by DEC-0137). The operator's family is every agent

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

@@ -159,6 +159,33 @@ node keys every per-caller rule with `job_caller_key`, counts every started job
 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>
 
 ## Actions
@@ -412,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.4`), 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 |
@@ -82,7 +82,7 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | 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) |
@@ -92,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) |

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

@@ -145,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
@@ -177,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
 

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