@passioncode-ai/fabric-agent-adapter 0.74.0 → 0.76.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## 0.76.0 (2026-11-07)
+
+The contract pin stays `18f8d487`. Kit modules change: `fabric_peer_owner` and `fabric-peer-owner.mjs` (peer_owner
+`1.1.0+kit.2`), `fabric_supervisors` and `fabric-supervisors.mjs`, `fabric_http`, and the facades `fabric_service` and
+`fabric-service.mjs` (one more export each).
+
+### Fixed
+
+- **The launchd installers prove their own job on a restricted socket table** (FAA-267). macOS 27.2 shows an
+  ad-hoc-signed interpreter (a Homebrew Python) only its own sockets through sysctl and nothing through netstat, so
+  `launchd_install` refused a service it had just started (`foreign-user`, `no-row`). The sysctl calibration now also
+  requires a child process's listener; an empty netstat answers `unknown` with reason `table-restricted`, never another
+  account's. `CheckedHTTPConnection(vouch_pid=...)` and the Node `checkedSocket({vouchPid})` accept a listener on the
+  port that `lsof -p` shows belongs to that pid of this account; `launchd_install` and `launchdInstall` vouch with their
+  own job's pid (`launchd_pid`, `launchdPid`, read only after a `table-restricted` answer), and a refusal that remains reads `<origin> could not be proved this service's:
+  table-restricted: ...`: the Python installer names the way round it (Apple's `/usr/bin/python3`), the Node one asks for a runtime that sees the table
+  (no Node was measured). `lsof` is asked for IPv4 alone, so a v6-only wildcard never vouches for a `127.0.0.1`
+  connection, and a vouch is an integer pid. The calibration child (one short-lived interpreter per process) is bounded
+  by the table timeout, and a child that cannot be started or does not answer proves nothing. Measured on a host
+  agent's Mac (macOS 27.2) with a pre-release build: the install passes, a root listener on another port is still
+  refused, the method is netstat under Homebrew Python and sysctl under Apple's; the final form was not rerun there
+  ([record](docs/reports/2026-11-07-faa-267/README.md)).
+- **A release folder in a plist's or a supervisor file's environment is no credential** (FAA-266): `PYTHONPATH`
+  holding a release folder under Application Support was refused as a key. An environment value that reads as a path
+  (it starts with `/`, `~`, `.` or a drive, has at least two separators and one all-lower-case part such as
+  `example-agent`) is now read by the path-aware detector (`secret_argument`, `secretArgument`); any other value keeps
+  the strict `secret_value`, so a base64 key whose `/` splits it is still refused: of 60,000 random keys 20 pass,
+  against 13 for the strict detector alone ([record](docs/reports/2026-11-07-faa-267/README.md)). `adapt_project.py`'s LC-21 check reads a plugin MCP
+  server's `env` the same way. A path whose part after a space has no all-lower-case folder and holds a digit
+  run (`.../Application Support/ExampleAgent/Releases/2026-11-07`) is still refused, as in 0.75.0 (FAA-273).
+
+### Known limits
+
+- Only the launchd installers vouch. On a restricted table (macOS 27.2 under an ad-hoc-signed interpreter) every
+  other caller of the owner check still refuses a loopback listener whose owner cannot be told: the probe
+  (`check_service.py`, rule `listener.owner`), the hub client and so the board responder, `fabric_http` and so the
+  OpenRouter connector, `mcp-register`, the `dashboard` command, and the layout probe. The
+  probe and `fabric_http` say `foreign-user` and carry the `table-restricted` reason; the hub client says only
+  `unknown` (FAA-272). The way round for Python is Apple's `/usr/bin/python3`; a Node service has no measured way
+  round yet.
+- The vouch is the launchd job's own pid: a `ProgramArguments` wrapper that starts the server as a child (`sh -c`
+  without `exec`, `uv run`, `npm start`) cannot vouch for it. Start the server with `exec`, or use Apple's Python.
+
+### Upgrading
+
+- `wellKnownOf`'s `ForeignUserAnswer.reason` may start with `table-restricted` beside `foreign-user`. A
+  `launchd_install` or `launchdInstall` refusal on a restricted table now reads `<origin> could not be proved this
+  service's: table-restricted: ...` where it read `<origin> is not this service's: foreign-user: ...`: match the
+  reason as a substring, not the start of the message.
+- New optional arguments: `vouch_pid` on `CheckedHTTPConnection` and `own_connection`, `vouchPid` on `checkedSocket`, `CheckedAgent` and
+  `wellKnownOf`. The vouch is consulted only on macOS when the owner reads `table-restricted`; it never overrides
+  another account's listener or another unknown reason. New names in both peer-owner twins: `TABLE_RESTRICTED` (the
+  reason to match on), `LSOF`, `pid_listens` / `pidListens` and `parse_lsof_listeners` / `parseLsofListeners`; the facades export `launchd_pid` (`fabric_service`) and
+  `launchdPid` (`fabric-service.mjs`).
+- A service that vendored the 0.74.0 or 0.75.0 kit keeps refusing its own install on macOS 27.2 until its copies are
+  refreshed (`fabric_kit.py status` names them older).
+
+## 0.75.0 (2026-11-07)
+
+Guidance only: no kit module, probe rule or hook changes; the contract pin stays `18f8d487`.
+
+### Added
+
+- **The Fabric communication agent template** (FAA-262, the operator's decision of 2026-11-07):
+  `creating-fabric-agents/references/communication-agent-template.md`, a prompt a coding agent builds a channel agent
+  from (support, sales and leads, community, inbox, store reviews, an internal assistant). It carries the inbound
+  pipeline as one estate measured it on 56 real questions and 19 written batches: a code prefilter, a triage at low
+  thinking that answers only a batch with no ask, one call that analyses, plans and drafts (with the injection check
+  and the product-only scope), the actions, a final pass only when an action returned new facts or an injection is
+  suspected, then the pre-send gates with a checker of another vendor. It also carries the business patterns, the
+  knowledge and data connections (the handoff queue's «a person answered» signal, the account state and version facts
+  as tools of every turn, retrieval over the whole conversation), leads handed to a sales agent of their own that owns
+  the CRM, the learning loop, the model lanes, the Fabric integration and the acceptance with 18 adversarial batches, and maps its sections to the parts of an organization agent template one file can carry (fabric-workspace
+  `knowledge/system/templates.md`, S2; S2's operating rules A1 to A12 apply by reference until the folder, FAA-265). `SKILL.md` links it beside `agents-that-answer-people.md`.
+- A scenario eval (`a-channel-agent-starts-from-the-communication-template`) and a trigger query for it (measured with a
+  real client: creating-fabric-agents 28 of 31, the new query routed right;
+  [record](docs/evidence/evals/2026-11-07-trigger-run.md)), and `test/test_communication_template_prose.py`,
+  which pins the template phrases that scenario grades and checks every event kind it names against the kit's writer.
+
+### Changed
+
+- `references/models-and-providers.md`: a new agent's model key gets USD 100 a month unless the operator names a higher
+  one, and the agent's own stop sits a little under the key's limit (the operator's decision of 2026-11-07).
+  It also names the template's open-vendor rule (every route of a lane reading people's words, fallbacks included) as
+  narrower than DEC-0083, and excepts a channel agent's batch triage from the volume row.
+- The template is linked from the creating-fabric-agents grill row «Does it answer people?» (the row «Who pays?» names
+  the USD 100 default), `agents-that-answer-people.md` and `practices.md`, and named in building-fabric-services
+  `SKILL.md` and the support-agent recipe's README, which now says how the recipe serves the template: the plan's draft carries `[KB:<id>]`
+  markers and the agent runs `check_reply` on it; the checker of another vendor stays the agent's own.
+
+- `agents-that-answer-people.md` A1: every inbound message belongs to one turn; a burst the template batches is one
+  turn listing its message ids (it said every message is a turn). The support-agent recipe's README names what goes in
+  `check_reply`'s `given`: the ids placed in the prompt, never the plan's own list, with tool results as entries of their own.
+- The operator channel's first step (`operator-channel-and-repository.md`, in adapting-projects-to-fabric and
+  creating-fabric-agents) says an agent that answers people on Telegram gives the operator channel a bot of its own,
+  and its example slot is now `EXAMPLE_AGENT_OPERATOR_BOT_TOKEN`.
+- The support-agent recipe's `channel-agent.example.json` final text reads as the standard's final reply (6.6: «we
+  could not confirm this»), not as an answer.
+- `docs/backlog.md`: FAA-263 (SKILL.md word headroom), FAA-264 (the readings' follow-ups that block nothing) and
+  FAA-265 (organization agent templates as folders, W0-Q8).
+- building-fabric-services `references/usage.md`: the every-limit example calls `usage_report` over the ledger's
+  receipts, since the Python `ledger.report` takes no `budgets` (it showed a call that raised `TypeError` since 0.19.0);
+  `test/test_usage_reference_snippet.py` runs it.
+
+### Upgrading
+
+- An answering agent that adopts the template moves every route that reads people's text to an open-vendor model,
+  fallbacks included (template rule 6); one that does not adopt it keeps what DEC-0083 asks. Its monthly stop uses the
+  kit's OpenRouter client with `window="month"` (the default window is a day).
+- Adopting the template starts a new series for `nobodyDropped.turns` (batched turns) and the outcome shares
+  (`customer_silent` up, `no_reply_owed` down); say so in the owner's report, never inside `support.quality_daily`.
+- A declaration copied from the 0.74.0 support-agent example replaces its `texts.final`, which claimed an answer.
+- An agent whose operator channel shares its answering bot moves the operator channel to a bot of its own (a new token
+  slot and link code), and binds the operator's id on the answering bot by its own link code (CA-8).
+
 ## 0.74.0 (2026-11-07)
 
 The contract pin moves to `18f8d487` (`v0.1.0+2026-11-07.1`) from `eac1a594` (`v0.1.0+2026-11-06.1`); between them

package/README.md

@@ -70,7 +70,9 @@ installed into a service with `scripts/fabric_kit.py install` and checked with `
 the dates API); connectors for outbound HTTP and OpenRouter (`fabric_http`, `fabric_openrouter`: one deadline, safe
 retries, the agent's own key, a spend ceiling before every attempt, usage receipts, a fallback model;
 [connectors](plugins/fabric-agent-adapter/skills/building-fabric-services/references/connectors.md)); the draft-and-check step of a support agent as a
-[recipe](plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/README.md);
+[recipe](plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/README.md)
+(the whole agent starts from creating-fabric-agents'
+[communication agent template](plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/communication-agent-template.md));
 a complete `scripts/sample_service.py`; and `scripts/check_service.py`, a live probe. A service that answers
 requests other Projects post to its Project on Fabric's project board uses the board responder
 (`scripts/fabric_hub.py` and `scripts/fabric_board.py`, Node `fabric-hub.mjs` and `fabric-board.mjs`): the
@@ -190,6 +192,8 @@ python3 "$KIT/sample_service.py" serve --port 47190 --data-dir "$DATA" &
 python3 "$KIT/sample_service.py" register --port 47190 --data-dir "$DATA" --services-dir "$SERVICES"
 # The probe exits 0 (no FAIL); only then is the service registered for one client run (listener.owner proves the port
 # is this account's, and the client cannot check it). The token goes in a header, never in argv.
+# On macOS 27.2 run these with Apple's /usr/bin/python3: an ad-hoc-signed Python, such as Homebrew's, sees no other
+# process's sockets (FAA-272).
 python3 "$KIT/check_service.py" sample --services-dir "$SERVICES" && \
 python3 - "$DATA/service.token" "$WORK/mcp.json" <<'EOF'
 import json, os, sys
@@ -204,9 +208,10 @@ EOF
 kill %1
 ```
 
-Verified 2026-10-01 from the published npm package 0.5.4 (`npx` into a throwaway hub, `KIT`
-pointing at the installed skill) with Claude Code 2.1.286: the probe reported 27 rules, 0 FAIL;
-the CLI connected to the sample over streamable HTTP, called `sample.echo` and printed `ping`. The probe prints one line per rule
+Verified 2026-11-07 from the published npm package 0.75.0 (`npm pack` into a throwaway folder, `KIT`
+pointing at its skill) with Claude Code 2.1.299: the probe reported 44 rules, 0 FAIL, `listener.owner` PASS;
+the CLI connected to the sample over streamable HTTP, called `sample.echo` and printed `ping`
+([record](docs/evidence/runs/2026-11-07-0.75.0-quick-start.md)). The probe prints one line per rule
 (`PASS`, `FAIL` or `NOT_RUN` with its evidence) and exits 1 on any `FAIL`; run it against your
 own service by its id once its installer has written the descriptor.
 `FABRIC_REAL_CLIENT=1 python3 -m unittest discover -s test -p test_real_client.py` repeats the connection check

package/SECURITY.md

@@ -41,7 +41,11 @@ bounded and non-publishing until explicit scoped grants exist in a project bindi
   -anv -p tcp` and `/bin/ps -o uid= -p <pid>` (the Node twin always); Linux
   `/proc/net/tcp` and `/proc/net/tcp6`; Windows `GetExtendedTcpTable` and the process
   token (Python), or `netstat -ano`, `whoami /user` and one PowerShell `GetOwnerSid` query
-  per new connection (Node). A token-free loopback door is not yet protected against
+  per new connection (Node). On macOS the Python reader calibrates once per process with a
+  short-lived child of its own interpreter listening on a random `127.0.0.1` port; when the
+  table is restricted (macOS 27.2, FAA-267) the launchd installers also run `/usr/sbin/lsof
+  -nP -a -p <pid> -i4TCP -sTCP:LISTEN -Fn` on their own job's pid. That vouch shows the job listens on the port, not that it accepted
+  the connection (a more specific bind by root over a wildcard job would pass; contract CT-261). A token-free loopback door is not yet protected against
   another account's process (HA-3, FAA-227). An MCP client (Claude Code, Codex) sends the
   token it was registered with on every later connection without this check (the contract's
   residue "a coding agent's bearer"): when the port may have changed hands, rotate the token

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.74.0",
+  "version": "0.76.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.74.0",
+  "version": "0.76.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.74.0"
+  version: "0.76.0"
   contract-version: "0.1.0"
   contract-commit: "18f8d48762edc5bfb1433657cbfe1c16196df1a6"
 ---

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/operator-channel-and-repository.md

@@ -12,9 +12,10 @@ its stops with buttons: `fabric-operator-channel/0.1` (contract DEC-0034,
 `docs/specification/operator-channel.md`), whose rule OC-11 this follows. Give the operator's four
 steps:
 
-1. create a bot with @BotFather;
+1. create a bot with @BotFather (for an agent that answers people on Telegram, a bot of its own, never
+   the bot that answers people: the contract's channel-agent.md);
 2. put its token into the operator's secret store (Project Observatory where it is installed) under
-   the name the agent reads (for example `EXAMPLE_AGENT_TELEGRAM_BOT_TOKEN`), never into a chat, a
+   the name the agent reads (for example `EXAMPLE_AGENT_OPERATOR_BOT_TOKEN`), never into a chat, a
    file or the bundle;
 3. run the agent's link command;
 4. type the code it shows in the chat with the bot.

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

@@ -586,6 +586,15 @@ def _credential_problems(manifest: Dict[str, Any]) -> List[str]:
 _PLUGIN_SKIP = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", ".worktrees"}
 
 
+def _secret_env_value(value: str) -> bool:
+    """An MCP server's environment value: path-aware only when it reads as a path (it starts as one, has two separators
+    and a lower-case word between them), as the kit's supervisor writers read one (FAA-266); else `secret_value`."""
+    pieces = re.split(r"[\\/]", value)
+    path = bool(re.match(r"(?:[/~.]|[A-Za-z]:[\\/])", value)) and len(pieces) >= 3 and any(
+        re.fullmatch(r"[a-z][a-z0-9_-]{2,}", x) for x in pieces)
+    return _secrets.secret_argument(value) if path else _secrets.secret_value(value)
+
+
 def _plugin_problems(root: Path) -> List[str]:
     """LC-19 (FAA-22) and LC-21 for the Claude Code plugins in the project: a plugin's stdio MCP server starts in
     every session that enables the plugin; serve it over HTTP from one resident process, or register it at project
@@ -614,7 +623,7 @@ def _plugin_problems(root: Path) -> List[str]:
             if any(isinstance(a, str) and _secrets.secret_argument(a) for a in argv) or (isinstance(entry.get("url"), str) and _secrets.secret_url(entry["url"])):
                 problems.append("LC-21: plugin %s's MCP server %s carries a credential in its argv or URL" % (name, server))
             env = entry.get("env") if isinstance(entry.get("env"), dict) else {}
-            if any(isinstance(v, str) and _secrets.secret_value(v) for v in env.values()):
+            if any(isinstance(v, str) and _secret_env_value(v) for v in env.values()):  # path-aware for a path (FAA-266)
                 problems.append("LC-21: plugin %s's MCP server %s writes a credential value in env; reference it instead" % (name, server))
     return problems
 

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

@@ -14,7 +14,7 @@ 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.74.0"
+  version: "0.76.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "18f8d48762edc5bfb1433657cbfe1c16196df1a6"
@@ -168,8 +168,8 @@ handler.
 Calling out: [the connectors reference](references/connectors.md) (`fabric_http` with one
 deadline, safe retries and a size cap; `fabric_openrouter` with the agent's own key, a
 spend ceiling before every attempt, receipts and a fallback). The draft-and-check step of a
-support agent on the kit: [`recipes/support-agent/`](recipes/support-agent/README.md); what the whole agent carries is
-creating-fabric-agents' `references/agents-that-answer-people.md`.
+support agent on the kit: [`recipes/support-agent/`](recipes/support-agent/README.md); the whole agent starts from
+creating-fabric-agents' `references/communication-agent-template.md` (parts: `agents-that-answer-people.md`).
 
 Startup order is the part that goes wrong; keep it exactly:
 
@@ -419,9 +419,10 @@ this estate needs.
 
 ## Gotchas
 
-- `lsof` shows `*:<port>` or `0.0.0.0` → the bind is wrong even if the Host check works.
+- `lsof` shows `*:<port>` or `0.0.0.0` → the bind is wrong.
 - HTTP 200 alone accepts any program on the port: compare `service.id` and `service.instance`, read only from
-  this OS account's listener. On `listener.owner` FAIL (`foreign-user`) send that port nothing.
+  this OS account's listener. On `listener.owner` FAIL (`foreign-user`) send that port nothing; reason
+  `table-restricted`: `references/protocol.md`.
 - `launchctl bootstrap` right after `bootout` fails with I/O error 5: wait for the unload, then retry.
 - Under launchd `PATH` is bare. Pin the interpreter by absolute path; set `PATH`
   explicitly in the plist; never copy the whole shell environment into it.

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

@@ -1,7 +1,19 @@
 # Recipe: the draft-and-check step of a support agent
 
 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. Built only on the service
+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()`:
+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
+injection); each tool result of the turn enters both under an id of its own, with its system-of-record fields only, never one
+a customer wrote (`tool.order`; the citation takes letters,
+digits, dot, dash and underscore, no colon; knowledge ids too, so map one that does not). Every template turn that went through the plan runs
+`check_reply` on its final text, except an off-topic plan, a plan whose only actions are ask_clarification or handoff,
+and a triage reply: the route decides, never the draft's markers. The final pass keeps the markers. A handle
+(`@name`) is not one of `check_reply`'s claims: it is the agent's own gate. Repair of a plan draft, and the
+checker of another vendor, stay the agent's own (agents-that-answer-people.md): the recipe's `repair=` reruns only its
+own `answer()` draft, and it has no checker. Built only on the service
 kit: `fabric_openrouter` for the model, `fabric_usage` for receipts, `fabric_paths` for private, atomic state.
 Tests: `test/test_support_agent_recipe.py` (a fake model; no network, no key).
 
@@ -130,7 +142,7 @@ FAC-SEM-162 to 165 (rule `channel-agent.declaration`).
 | `stateDir` | the decisions (`decisions.jsonl`), the handoff outbox (`handoffs.jsonl`) and the usage ledger (`usage.jsonl`) |
 | `model`, `fallback` | two models of different vendors; a lane that reads what customers write runs on an open-vendor model (DEC-0083) |
 | `keyEnv` | the environment variable that holds the agent's own OpenRouter key; never a value in the file |
-| `ceilingUsd`, `window` | the spend ceiling per UTC `day` or `month` |
+| `ceilingUsd`, `window` | the spend ceiling per UTC `day` or `month` (`month` under the communication agent template, under the key's monthly limit) |
 | `prices` or `catalog` | USD per token per model. The example's prices are placeholders, not OpenRouter's: take them from `GET https://openrouter.ai/api/v1/models` (a saved catalog file named in `catalog` is read with `prices_from_catalog`). A model without a price is never called |
 | `maxTokens`, `maxChars` | the output budget per call and the reply's length limit |
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/channel-agent.example.json

@@ -59,7 +59,7 @@
                 "en": "Thank you, we are looking into it and will answer here."
               },
               "final": {
-                "en": "Here is the answer to your question. Write again if anything is still unclear."
+                "en": "We could not confirm this. Please write to the support address on our site."
               }
             }
           }

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.1`), the Node twin reads netstat, `/proc` and the owner SID where Python reads `sysctl`, `/proc` and `GetExtendedTcpTable` |
+| 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.2`), 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` |
 | L1 | `fabric_crypto` | Ed25519 signing (a Montgomery ladder that does not branch on the key) and verification, P-256 verification, base64url, sha256 |
 | L1 | `fabric_base` | the protocol name, `ServiceError`, small shared helpers |
 | L1 | `fabric_platform` | Windows: named pipes, owner-only files (DEC-0032) |

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

@@ -97,7 +97,11 @@ systemd and Task Scheduler do not poll yet, FAA-253).
    until `launchctl print gui/<uid>/<label>` fails, `bootstrap` with up to five retries,
    then poll the well-known document until it answers with this `id.instance` on a listener of this OS account
    (DEC-0154 HA-2: another account's listener, or one whose owner cannot be told, is `foreign-user` and never a
-   successful install; the error names it).
+   successful install; the error names it). Where the socket table hides other processes (macOS 27.2 under an
+   ad-hoc-signed interpreter), the installer vouches with its own job's pid from `launchctl print`; a listener it
+   cannot prove reads `table-restricted` and the error names the way round it (FAA-267). The pid is the job's own, so a
+   `ProgramArguments` wrapper that starts the server as a child (`sh -c` without `exec`, `uv run`, `npm start`) cannot
+   vouch for it: on such a host start the server with `exec` or run the installer from Apple's `/usr/bin/python3`.
 4. Upgrade = new release, rewrite the plist with the new path, `launchd_install`
    again, then `prune_releases(releases_dir, current=<new release>)`: the running release
    and the one before it stay for rollback, older ones go (LC-11, LC-15).

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

@@ -224,6 +224,17 @@ and `/proc/net/tcp6`, Windows through `GetExtendedTcpTable` and the owner's toke
 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.
 
+macOS 27.2 shows an ad-hoc-signed interpreter (a Homebrew Python, measured; a Homebrew Node is ad-hoc-signed too and was not measured) only its own sockets: sysctl lists this
+process alone and netstat prints nothing. The Python calibration therefore also asks for a child process's listener,
+and an empty netstat is `unknown` with reason `table-restricted` (never another account's). A caller that started the
+server itself may vouch with that pid: `lsof -p <pid>` asks the process, which the restriction leaves readable, and a
+listener of this account's pid on the port counts as this account's (`CheckedHTTPConnection(vouch_pid=...)`, Node
+`checkedSocket({vouchPid})`). The launchd installers vouch with their own job's pid; elsewhere a restricted table
+refuses (the probe, the hub client and `fabric_http` included, FAA-272), and Apple's `/usr/bin/python3` sees the
+whole table (FAA-267). A vouch is a weaker proof than the table's: it shows the job's pid listens on the port (`127.0.0.1` or the
+IPv4 wildcard), not that it accepted this connection, so a more specific bind by root over a wildcard job would pass;
+the contract's ruling on vouching is CT-261.
+
 Every kit client that sends a credential to loopback checks first: `check_service.py` (rule `listener.owner`, the first that reads the port for
 a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub client (`HubError` `foreign-user`),
 `fabric_http` / `fabric-http.mjs` for a plain `http://` loopback URL (`HttpError` kind `foreign-user`, never retried),

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

@@ -66,10 +66,12 @@ left out.
 it, and the host only shows it.
 
 **Every limit (DEC-0027).** Pass `budgets` to list every spending limit the service applies,
-enforced or not, so the spend view shows all of them; the operator asked for that on 2026-10-07:
+enforced or not, so the spend view shows all of them; the operator asked for that on 2026-10-07. In Python
+`ledger.report` takes no `budgets`, so call `usage_report` over the ledger's receipts (Node's `ledger.report` passes
+them through):
 
 ```python
-ledger.report(service_id=ID, budget={"period": "month", "limitUsd": 100}, budgets=[
+fabric_usage.usage_report(ledger.receipts(), service_id=ID, instance=INSTANCE, budget={"period": "month", "limitUsd": 100}, budgets=[
     {"id": "machine.monthly", "scope": "machine", "kind": "monthly", "period": "month", "limitUsd": 100, "enforced": True},
     {"id": "project.demo.daily", "scope": "project", "subject": "demo", "kind": "daily", "windowSeconds": 86400,
      "limitUsd": 5, "spentUsd": 0.31, "enforced": True},

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

@@ -45,7 +45,7 @@ import http from 'node:http';
 import net from 'node:net';
 import os from 'node:os';
 
-export const PEER_OWNER_VERSION = '1.1.0+kit.1'; // the Python twin's, Observatory's 1.1.0 with the kit's differences
+export const PEER_OWNER_VERSION = '1.1.0+kit.2'; // the Python twin's, Observatory's 1.1.0 with the kit's differences
 export const THIS_ACCOUNT = 'this-account';
 export const ANOTHER_ACCOUNT = 'another-account';
 export const SYSTEM = 'system';
@@ -58,6 +58,10 @@ export const WINDOWS_TIMEOUT_MS = 5000;
 export const LISTENER_TTL_MS = 1000;
 export const NETSTAT = '/usr/sbin/netstat';
 export const PS = '/bin/ps';
+export const LSOF = '/usr/sbin/lsof';
+// The reason a socket table hides other processes' sockets from this one (FAA-267): macOS 27.2 gives an ad-hoc-signed
+// runtime an empty netstat.
+export const TABLE_RESTRICTED = 'table-restricted';
 export const SERVER_NOT_OWN = 'server-not-own';
 export const SERVER_UNVERIFIED = 'server-unverified';
 export const SERVER_NOT_THIS_WORKSPACE = 'server-not-this-workspace';
@@ -143,6 +147,7 @@ function netstatAddress(text) {
 // leading and the trailing columns, both counted from the header; a header without process:pid is unreadable.
 export function parseNetstat(text) {
   const lines = String(text).split(/\r?\n/);
+  if (!lines.some((line) => line.trim())) throw new TableUnreadable(`${TABLE_RESTRICTED}: netstat printed nothing to this process`);
   const header = lines.findIndex((line) => line.includes('process:pid') && line.includes('Proto'));
   if (header < 0) throw new TableUnreadable('netstat-format: no process:pid column');
   const names = lines[header].split(/\s+/).filter(Boolean);
@@ -165,6 +170,18 @@ export function parseNetstat(text) {
   return rows;
 }
 
+// `lsof -nP -a -p PID -i4TCP -sTCP:LISTEN -Fn`: the `n` lines, 127.0.0.1:47480, *:47480 or [::1]:47480.
+export function parseLsofListeners(text) {
+  const found = [];
+  for (const line of String(text).split(/\r?\n/)) {
+    if (!line.startsWith('n') || !line.includes(':')) continue;
+    const at = line.lastIndexOf(':');
+    const port = line.slice(at + 1);
+    if (/^[0-9]+$/.test(port)) found.push([normHost(line.slice(1, at).replace(/^\[|\]$/g, '')), Number(port)]);
+  }
+  return found;
+}
+
 // `ps -o uid= -p PID`: one number, or nothing when the process is gone.
 export function parsePsUid(text) {
   const t = String(text).trim();
@@ -497,10 +514,25 @@ export function refusal(who, port, expectPid = null) {
   return null;
 }
 
+// macOS, when the socket table is restricted (FAA-267): whether process `pid`, this account's, listens on 127.0.0.1:<port>
+// or the IPv4 wildcard (IPv4 alone: a v6-only wildcard never vouches for a 127.0.0.1 connection). `lsof -p` asks the process itself, which the restriction does not hide. Only a caller that started
+// `pid` itself (a launchd job it installed) may vouch with it.
+export async function pidListens(pid, port, { run = runProgram, platform = process.platform, ownUid: mine } = {}) {
+  if (platform !== 'darwin' || !Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    const uid = parsePsUid(await run(PS, ['-o', 'uid=', '-p', String(pid)]));
+    if (uid === null || uid !== (mine ?? ownUid())) return false;
+    const out = await run(LSOF, ['-nP', '-a', '-p', String(pid), '-i4TCP', '-sTCP:LISTEN', '-Fn']);
+    return parseLsofListeners(out).some(([host, p]) => (host === '127.0.0.1' || host === '*') && p === port);
+  } catch {
+    return false;
+  }
+}
+
 // A connected socket to host:port whose server end is this account's (and, with expectPid, that process's). The check
 // runs on the very socket the caller then writes on, so no listener can change between the check and the request.
 // Rejects with ListenerRefused (the socket destroyed, nothing written) or with the connection's own error.
-export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, expectPid = null, ...ask } = {}) {
+export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, expectPid = null, vouchPid = null, ...ask } = {}) {
   return new Promise((resolveSocket, reject) => {
     const socket = net.connect({ host, port, noDelay: true }); // as a plain http.Agent's socket
     const timer = setTimeout(() => socket.destroy(Object.assign(new Error('connect timeout'), { code: 'ETIMEDOUT' })), timeoutMs);
@@ -515,6 +547,11 @@ export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, exp
         // A reader that throws (an injected one; the readers themselves answer unknown) fails closed.
         who = owner(UNKNOWN, { method: method(), reason: `check: ${err?.name ?? 'Error'}` });
       }
+      if (who.kind === UNKNOWN && String(who.reason ?? '').startsWith(TABLE_RESTRICTED) && vouchPid
+        && await pidListens(vouchPid, port, ask)) {
+        // The table hides other processes (FAA-267); the process this caller started holds the listener.
+        who = owner(THIS_ACCOUNT, { uid: ask.ownUid ?? ownUid(), pid: vouchPid, method: 'lsof-pid' });
+      }
       const refused = refusal(who, port, expectPid);
       if (refused) {
         socket.destroy();
@@ -532,14 +569,15 @@ export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, exp
 // when it is made. A refusal reaches the request as its 'error', a ListenerRefused. Free sockets do not keep the process
 // alive (Node unrefs them).
 export class CheckedAgent extends http.Agent {
-  constructor({ expectPid = null, ask = {}, ...options } = {}) {
+  constructor({ expectPid = null, vouchPid = null, ask = {}, ...options } = {}) {
     super(options);
     this.expectPid = expectPid;
+    this.vouchPid = vouchPid;
     this.ask = ask;
   }
 
   createConnection(options, callback) {
     checkedSocket(Number(options.port), { host: options.host ?? '127.0.0.1', timeoutMs: options.timeout ?? 10000,
-      expectPid: this.expectPid, ...this.ask }).then((socket) => callback(null, socket), (err) => callback(err));
+      expectPid: this.expectPid, vouchPid: this.vouchPid, ...this.ask }).then((socket) => callback(null, socket), (err) => callback(err));
   }
 }

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

@@ -177,6 +177,7 @@ export {
   taskUninstall,
   launchdPlist,
   launchdLoaded,
+  launchdPid,
   launchdOverride,
   launchdInstall,
   launchdUninstall,

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

@@ -9,7 +9,7 @@ import { DRAIN_SECONDS, SUPERVISOR_ENV, ServiceError, TASK, UNIT } from './fabri
 import { atomicWrite, instanceDirs } from './fabric-paths.mjs';
 import { SUPERVISOR_ARG, markerArguments } from './fabric-lock.mjs';
 import { URI } from './fabric-backups.mjs';
-import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
 import http from 'node:http';
 
 export const DEFAULT_EXIT_TIMEOUT = 15;
@@ -55,13 +55,22 @@ function noMarkerArgument(argv) {
   if (markerArguments(argv).length) throw new ServiceError(`${SUPERVISOR_ARG} is written by the supervisor file's writer; leave it out of the program arguments.`);
 }
 
+// An environment value: read path-aware (secretArgument) only when it reads as a path (it starts as one, has at least two
+// separators and a lower-case word between them), so a release folder under Application Support is no key (FAA-266) while
+// a base64 key whose `/` splits it stays one; any other value keeps the strict secretValue.
+const secretEnvValue = (value) => {
+  const pieces = value.split(/[\\/]/);
+  const path = /^(?:[/~.]|[A-Za-z]:[\\/])/.test(value) && pieces.length >= 3 && pieces.some((x) => /^[a-z][a-z0-9_-]{2,}$/.test(x));
+  return path ? secretArgument(value) : secretValue(value);
+};
+
 function noSecretInSupervisorFile(argv, environment) {
   // No supervisor file carries a secret (service.md): not in an argument, an environment name or its value.
   for (const arg of argv) {
     if (secretArgument(arg)) throw new ServiceError('An argument carries a credential; a supervisor file never does (read it from the token file or a secret reference).');
   }
   for (const [name, value] of Object.entries(environment ?? {})) {
-    if (credentialName(name) || secretValue(String(value))) throw new ServiceError(`Environment ${name} looks like a credential; a supervisor file never carries one.`);
+    if (credentialName(name) || secretEnvValue(String(value))) throw new ServiceError(`Environment ${name} looks like a credential; a supervisor file never carries one.`);
   }
 }
 
@@ -264,7 +273,7 @@ export function launchdPlist(label, programArguments, { workingDirectory, stdout
   const env = { ...environment };
   for (const [name, value] of Object.entries(env)) {
     if (/(TOKEN|SECRET|PASSWORD|KEY)$/.test(name) && !name.endsWith('_FILE')) throw new ServiceError(`Environment variable ${name} looks like a secret; pass a *_FILE path instead.`);
-    if (secretValue(String(value))) throw new ServiceError(`Environment ${name} holds a value shaped like a credential; a plist never carries one.`);
+    if (secretEnvValue(String(value))) throw new ServiceError(`Environment ${name} holds a value shaped like a credential; a plist never carries one.`);
   }
   for (const arg of argv) {
     if (secretArgument(arg)) throw new ServiceError('An argument carries a credential; a plist never does (read it from the token file or a secret reference).');
@@ -302,6 +311,14 @@ export function launchdLoaded(label, { run = defaultRun, platform = process.plat
   return run(['launchctl', 'print', `${launchdDomain(platform, uid)}/${launchdLabel(label)}`])?.status === 0;
 }
 
+// The running pid of this account's launchd job `label`, or null (not running, or not readable).
+export function launchdPid(label, { run = defaultRun, platform = process.platform, uid } = {}) {
+  const result = run(['launchctl', 'print', `${launchdDomain(platform, uid)}/${launchdLabel(label)}`]);
+  if (result?.status !== 0) return null;
+  const hit = /^\s*pid\s*=\s*([0-9]+)\s*$/m.exec(String(result.stdout ?? ''));
+  return hit ? Number(hit[1]) : null;
+}
+
 const OVERRIDE_ROW = /^\s*"([^"]+)"\s*=>\s*(\S+)\s*$/;
 
 /**
@@ -326,7 +343,7 @@ export class ForeignUserAnswer {
 // The well-known answer at a loopback origin, read only on a connection whose server end is this OS account's process
 // (DEC-0154 HA-2): null when nothing answers or the answer is not JSON, a ForeignUserAnswer when the listener is another
 // account's or its owner cannot be told.
-export async function wellKnownOf(origin) {
+export async function wellKnownOf(origin, { vouchPid = null } = {}) {
   const m = /^http:\/\/127\.0\.0\.1:([0-9]{1,5})$/.exec(origin);
   if (!m) {
     try {
@@ -338,7 +355,7 @@ export async function wellKnownOf(origin) {
   }
   // A CheckedAgent without keep-alive: the request goes on the very socket it checked, and the socket closes after the
   // answer, so a poll leaves no connection open behind it.
-  const agent = new CheckedAgent({ keepAlive: false });
+  const agent = new CheckedAgent({ keepAlive: false, vouchPid });
   return new Promise((resolve) => {
     const req = http.request({ host: '127.0.0.1', port: Number(m[1]), path: '/.well-known/fabric-service', agent,
       timeout: 2000 }, (res) => {
@@ -350,7 +367,9 @@ export async function wellKnownOf(origin) {
       res.on('error', () => resolve(null));
     });
     req.on('timeout', () => req.destroy());
-    req.on('error', (err) => resolve(err instanceof ListenerRefused ? new ForeignUserAnswer(`foreign-user: ${err.message}`) : null));
+    req.on('error', (err) => resolve(err instanceof ListenerRefused
+      ? new ForeignUserAnswer(`${String(err.owner?.reason ?? '').startsWith(TABLE_RESTRICTED) ? TABLE_RESTRICTED : 'foreign-user'}: ${err.message}`)
+      : null));
     req.end();
   }).finally(() => agent.destroy());
 }
@@ -390,13 +409,18 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
   }
   const deadline = Date.now() + timeout * 1000;
   let foreign = null;
+  let vouchPid = null;
   while (Date.now() < deadline) {
-    const doc = await fetchWellKnown(origin);
+    const doc = await fetchWellKnown(origin, { vouchPid });
     foreign = doc instanceof ForeignUserAnswer ? doc.reason : null;
+    if (foreign?.startsWith(TABLE_RESTRICTED)) vouchPid = launchdPid(label, opts); // only a restricted table needs it (FAA-267)
     if (!foreign && doc?.service?.id === serviceId && doc?.service?.instance === instance) return doc;
     await sleep(500);
   }
   // DEC-0154 HA-2 and service.md's Install row: a listener of another account is never a successful install.
+  if (foreign?.startsWith(TABLE_RESTRICTED)) {
+    throw new ServiceError(`${origin} could not be proved this service's: ${foreign} (DEC-0154 HA-2); this runtime sees no other process's sockets and the job's pid did not show the listener: run the installer from a runtime that sees them, or read the job's log.`);
+  }
   if (foreign) {
     throw new ServiceError(`${origin} is not this service's: ${foreign} (DEC-0154 HA-2); the port is another OS account's or its owner cannot be told.`);
   }

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

@@ -354,6 +354,7 @@ class _CheckedHTTPConnection(_po.CheckedHTTPConnection):
                  **kwargs: Any) -> None:
         http.client.HTTPConnection.__init__(self, host, port, timeout=timeout, **kwargs)
         self.expect_pid = None
+        self.vouch_pid = None  # a loopback URL is never a process this caller started (FAA-267)
 
 
 def _opener(watchdog: _Watchdog, direct: bool = False) -> urllib.request.OpenerDirector: