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

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

@@ -157,6 +157,9 @@ No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
   `auth.delegation {issuer, jwks}` is then required. With `own` or `delegation` the descriptor's
   token is not an MCP credential: a host and the probe never call `/mcp` with it as a caller.
   The kits verify them with `fabric_delegation` / `fabric-delegation.mjs` ([delegation](delegation.md)).
+- `surfaces.mcp.capabilities` and an action's `tool` never name `project.work` (`PRIMARY_CAPABILITY`): DEC-0140 PR-1
+  reserves it for a Project's primary responder, a session, and no service serves or declares it. `build_well_known`
+  / `buildWellKnown` refuse it with `ServiceError` (FAA-244); a longer name such as `project.workspace` is not reserved.
 
 ## Events page: `GET /fabric/v1/events?after=<cursor>&limit=<n>`
 
@@ -212,7 +215,9 @@ Loopback is one per computer, not one per OS account. Before a client sends any
 `http://127.0.0.1:<port>` (a descriptor's token, a delegation token, a login code's request, a session cookie, a door's
 token), and before a host calls a local service healthy, it tells the owner of the server end of its own connection
 from the computer's socket table. A listener of another OS account, of root, SYSTEM or a service account, or one whose
-owner cannot be told, is `foreign-user`: nothing is sent and nothing it answers is read as the service's. The order of
+owner cannot be told, is `foreign-user`: nothing is sent and nothing it answers is read as the service's. One exception:
+a LaunchDaemon's root installer reads its own job's token-free well-known answer, proved by the job's pid, uid and exact
+`127.0.0.1` bind (lifecycle.md, *The system domain*; DEC-0161 accepted in principle, proposed; FAA-288). The order of
 a local service's states is `down`, `foreign-user`, `foreign` (`FAC-SEM-009`), then the well-known `status`; the
 well-known `process.pid` is never proof (`docs/specification/service.md#ha-2` at the pin).
 
@@ -232,14 +237,14 @@ listener of this account's pid on the port counts as this account's (`CheckedHTT
 `checkedSocket({vouchPid})`). The launchd installers vouch with their own job's pid; elsewhere a restricted table
 refuses (the probe, the hub client and `fabric_http` included, FAA-272), and Apple's `/usr/bin/python3` sees the
 whole table (FAA-267). A vouch is a weaker proof than the table's: it shows the job's pid listens on the port (`127.0.0.1` or the
-IPv4 wildcard), not that it accepted this connection, so a more specific bind by root over a wildcard job would pass;
+IPv4 wildcard for a LaunchAgent's installer, exactly `127.0.0.1` for a LaunchDaemon's), not that it accepted this connection, so a more specific bind by root over a wildcard job would pass;
 the contract's ruling on vouching is CT-261.
 
 Every kit client that sends a credential to loopback checks first: `check_service.py` (rule `listener.owner`, the first that reads the port for
 a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub client (`HubError` `foreign-user`),
 `fabric_http` / `fabric-http.mjs` for a plain `http://` loopback URL (`HttpError` kind `foreign-user`, never retried),
 `check_dashboard_layout.mjs` before a local login code, and the launchd installers' poll (a listener of another account
-is never a successful install; the systemd and Task Scheduler installers do not poll yet, FAA-253). A running board
+is never a successful install, except a LaunchDaemon's job as its root installer proves it; the systemd and Task Scheduler installers do not poll yet, FAA-253). A running board
 session reports a door another account holds as `board.down` with reason `unreachable` until FAA-252. On macOS the Node
 twin reads the pid from `netstat` and the uid from `ps` a few milliseconds apart, so a pid reused in between would be
 misread; the Python twin's `sysctl` reader takes both from one record. A service's own loopback server refusing another account's peer (HA-3) is FAA-227, and the port

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

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

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

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

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

@@ -0,0 +1,5 @@
+# When to use building-fabric-services
+
+The skill's full trigger description, kept here so the front matter's `description` stays within the client's skill listing budget (about 350 characters a skill). Read it when choosing between this skill and a neighbour.
+
+Use when running an agent as a Fabric service (fabric-service/0.1, its kits and probe): a local service (launchd, systemd, Windows), an ONLINE agent or dashboard on https, its dashboard link and kit (narrow panel, themes), data and cache paths, how callers reach and authenticate it, long jobs (fabric.job.*), spend report and limits, runner routes and model profiles, the estate record and delegation tokens, answering a Project's board requests, or packing and signing it. «сделай агенту дашборд», «локальный сервис агента», «подключи агента к Fabric Dashboards», «отвечать на запросы с доски проекта», «расходы агента на модели», "make this agent a local service", "make an online dashboard a Fabric service", "add the well-known endpoint". NOT for a one-off script or cron job, a hosted product with no agent, the provider manifest (adapting-projects-to-fabric), a new agent's design (creating-fabric-agents), a session using Fabric or its board (working-with-fabric), or building the Dashboards app (window, tray).

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

@@ -833,11 +833,12 @@ class Probe:
         if sys.platform != "darwin" or not shutil.which("launchctl"):
             self.add("lifecycle.one-copy", "NOT_RUN", "launchctl is not available")
             return
-        out = subprocess.run(["launchctl", "print", "gui/%d/%s" % (os.getuid(), life.get("label"))], capture_output=True, text=True)
+        domain = fs.launchd_domain(plist_path)  # a plist in /Library/LaunchDaemons is a LaunchDaemon (FAA-278)
+        out = subprocess.run(["launchctl", "print", "%s/%s" % (domain, life.get("label"))], capture_output=True, text=True)
         match = re.search(r"^\s*pid = (\d+)", out.stdout, re.MULTILINE)
         served = ((self.wk or {}).get("process") or {}).get("pid")
         if out.returncode != 0:
-            self.add("lifecycle.one-copy", "FAIL", "launchd job %s is not loaded" % life.get("label"))
+            self.add("lifecycle.one-copy", "FAIL", "launchd job %s is not loaded in %s" % (life.get("label"), domain))
         elif not match:
             self.add("lifecycle.one-copy", "FAIL", "launchd job loaded but not running")
         else:

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

@@ -11,6 +11,11 @@ export const PROTOCOL = 'fabric-service/0.1';
 
 export const EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/service/0.1';
 
+// DEC-0140 PR-1 (contract project-comms.md, interop.md's C3.1 amendment): the capability of a Project's primary
+// responder, a session's. No service serves it as a tool or declares it (surfaces.mcp.capabilities, an action's tool),
+// and the board kit never enrolls a service's responder for it (FAA-244).
+export const PRIMARY_CAPABILITY = 'project.work';
+
 // Lifecycle rules: references/lifecycle.md (the rule for this kit's users; it implements the public
 // contract's service specification, Lifecycle), the same values as fabric_service.py.
 // A launchd-supervised copy that finds the lock held backs off in-process before its exit 75 (LC-03).

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

@@ -30,6 +30,8 @@ export class BoardSession {
     try {
       return await this.post(this.grant.origin, body, this.grant.bearer(), { session: this.mcpSession, timeout: timeout > 0 ? timeout : this.timeout, method, protocolVersion: this.mcpSession ? this.protocolVersion : undefined });
     } catch (e) {
+      // FAA-252: another OS account's process holds the port; nothing was sent
+      if (e instanceof HubError && e.code === 'foreign-user') throw new BoardError('foreign-user', 'The hub\'s port is held by another OS account\'s process; nothing was sent.', true);
       if (e instanceof HubError) throw new BoardError('unreachable', 'Fabric\'s hub did not answer; a write may have been stored, so send it again with the same idempotency key.', true);
       throw e;
     }

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

@@ -3,7 +3,7 @@
 // Part of the Node board connector (FAA-65, layer L4); the twin of fabric_board_session.py. Node 20+, no dependency.
 import crypto from 'node:crypto';
 import { Backoff, HubError, normalProject } from './fabric-hub.mjs';
-import { acceptedRevisions, feedDataProblems, negotiateRevision } from './fabric-service.mjs';
+import { PRIMARY_CAPABILITY, acceptedRevisions, feedDataProblems, negotiateRevision } from './fabric-service.mjs';
 import { BoardError, CAPABILITY, LEASE_SECONDS, REQUEST_STATES, SUMMARY_MAX, Stopped, isInt, isObj, outcomeProblems, receiptProblems } from './fabric-board-shapes.mjs';
 import { BoardRequest, BoardSession, Checkpoint, PERSONAL_BOARD, covers, mandateOptions, readMandate } from './fabric-board-link.mjs';
 import { HOLD_RETRY_MAX_SECONDS, LEASE_MARGIN_SECONDS, SESSION_CODES, SlotKeeper } from './fabric-board-slots.mjs';
@@ -87,6 +87,8 @@ export class Responder extends SlotKeeper {
     if (typeof admit !== 'function' || typeof handler !== 'function') throw new BoardError('invalid_arguments', 'A responder needs the service\'s own input gate (admit) and a handler.');
     const caps = [...(capabilities ?? [])];
     if (!caps.length || caps.some((c) => typeof c !== 'string' || !CAPABILITY.test(c)) || new Set(caps).size !== caps.length) throw new BoardError('invalid_arguments', 'Name each capability once, [a-z][a-z0-9._-]{1,127}.');
+    // FAA-244: DEC-0140 PR-1, a session's slot, never a service's
+    if (caps.includes(PRIMARY_CAPABILITY)) throw new BoardError('invalid_arguments', `${PRIMARY_CAPABILITY} is a Project's primary responder's, a session's: a service answers the capabilities it declares (DEC-0140 PR-1).`);
     Object.assign(this, { hub, capabilities: caps, credentialFile, handler, admit, observe, emitTo: emit, now, rand });
     this.project = normalProject(projectId);
     // FAA-135: read the operator's mandate from a trusted request of his own Project (opt-in; null reads none)
@@ -196,7 +198,7 @@ export class Responder extends SlotKeeper {
     this.session = session;
     const status = await this.status();
     if (missing.length) {
-      this.emit('board.access.needed', 'warning', `The operator has not let this service answer ${missing.join(', ')} on this Project; ask in Fabric (Agents & access).`, { notify: true, episode: missing.join(','), capabilities: missing });
+      this.emit('board.access.needed', 'warning', `The operator has not let this service answer ${missing.join(', ')} on this Project; ask in Fabric (Settings → Agent access).`, { notify: true, episode: missing.join(','), capabilities: missing });
     }
     this.slots = {};
     await this.recover(status, this.capabilities.filter((c) => grant.capabilities.includes(c)));
@@ -375,7 +377,8 @@ export class Responder extends SlotKeeper {
     try {
       this.receipt('com.reply', await this.call('com.reply', { ...this.replyExtra(entry), fence: this.fence({ ...entry, generation, attempt, digest, revision }, key) }));
     } catch (e) {
-      if (['unreachable', 'session-ended', 'authority_changed', 'not_authorized', 'not_available', 'capacity_exceeded'].includes(e.code) || !(e instanceof BoardError)) throw e;
+      // foreign-user: nothing was sent now, so whether the old reply was stored is unknown (0.79.0 seam reading)
+      if (['unreachable', 'foreign-user', 'session-ended', 'authority_changed', 'not_authorized', 'not_available', 'capacity_exceeded'].includes(e.code) || !(e instanceof BoardError)) throw e;
       replied = false;
     }
     if (replied) entry.replied = true;
@@ -496,7 +499,7 @@ export class Responder extends SlotKeeper {
     if (['not_authorized', 'authority_changed', 'credential'].includes(code)) {
       this.state = 'not-authorized';
       await this.dropSession();
-      this.emit('board.access.needed', 'warning', 'This service may not answer requests for this Project: the operator has to allow it in Fabric (Agents & access). Nothing is claimed until then.', { notify: true, episode: 'access', reason: code });
+      this.emit('board.access.needed', 'warning', 'This service may not answer requests for this Project: the operator has to allow it in Fabric (Settings → Agent access). Nothing is claimed until then.', { notify: true, episode: 'access', reason: code });
     } else if (code === 'held') {
       this.state = 'paused';
       this.emit('board.held', 'info', 'The operator holds new work on this Project; the responder waits and asks again with a growing pause.', { episode: 'held', reason: code });
@@ -508,8 +511,11 @@ export class Responder extends SlotKeeper {
     } else {
       this.state = 'down';
       // A refusal in recovery that left no slot held reconnects (seam 6); one that left some held serves them (seam 7).
-      if ((connecting || ['session-ended', 'unreachable', 'not-running', 'not-a-hub', 'hub-unavailable', 'protocol'].includes(code)) && !keep) await this.dropSession();
-      this.emit('board.down', 'warning', 'Fabric\'s board cannot be reached; the responder tries again with a growing pause.', { episode: 'down', reason: code });
+      if ((connecting || ['session-ended', 'unreachable', 'not-running', 'not-a-hub', 'hub-unavailable', 'protocol', 'foreign-user'].includes(code)) && !keep) await this.dropSession();
+      // FAA-252: a port another OS account holds is said as such; nothing was sent there
+      this.emit('board.down', 'warning', code === 'foreign-user'
+        ? 'Fabric\'s board port is held by another OS account\'s process; nothing was sent, and the responder tries again with a growing pause.'
+        : 'Fabric\'s board cannot be reached; the responder tries again with a growing pause.', { episode: 'down', reason: code });
     }
     return wait;
   }

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

@@ -14,7 +14,7 @@ export const HOLD_RETRY_MAX_SECONDS = 900;
 
 /** Refusals that are about the board session, not one capability: they end recovery and go to the responder's fault. */
 export const SESSION_CODES = Object.freeze(new Set(['unreachable', 'session-ended', 'not_authorized', 'authority_changed', 'credential', 'no-epoch',
-  'schema-unsupported', 'checkpoint', 'receipt-shape', 'idempotency_conflict', 'not-running', 'not-a-hub', 'hub-unavailable', 'protocol', 'not_available']));
+  'schema-unsupported', 'checkpoint', 'receipt-shape', 'idempotency_conflict', 'not-running', 'not-a-hub', 'hub-unavailable', 'protocol', 'not_available', 'foreign-user']));
 
 const sameRecord = (a, b) => JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
 
@@ -83,7 +83,7 @@ export class SlotKeeper {
         const moved = isInt(before, 1) && isInt(rest.generation, 1) && before > rest.generation;
         if (isInt(generation, 1) && (answer.repeated === true || !moved)) record = { project: this.project, generation };
       } catch (e) {
-        if (LOST.includes(e.code)) throw e;
+        if (LOST.includes(e.code) || e.code === 'foreign-user') throw e; // foreign-user: the earlier ask is unknown
         if (e.code === 'idempotency_window_expired') record = {}; // a retired epoch: unknown, so a first start, no move
       }
     }

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

@@ -12,9 +12,11 @@
 
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import http from 'node:http';
 import net from 'node:net';
 import { hubKeyCertified } from './fabric-estate.mjs';
 import { atomicWrite } from './fabric-paths.mjs'; // the kit's private writer (FAA-85)
+import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs'; // a loopback key set from this account's listener only (FAA-255)
 import { effectClosure } from './fabric-mandate.mjs'; // defined once beside the mandate that reads it too (DEC-0125)
 
 export const REFUSAL_CODES = Object.freeze([
@@ -411,8 +413,34 @@ export const actionDigest = (action) => `sha256:${crypto.createHash('sha256').up
 
 const loopback = (host) => host === 'localhost' || (net.isIP(host.replace(/^\[|\]$/g, '')) !== 0 && (/^127\./.test(host) || host.replace(/^\[|\]$/g, '') === '::1'));
 
+const KEY_SET_MAX = 65536;
+const KEY_SET_AGENT = new CheckedAgent({ keepAlive: false });
+
+// Plain http, which a key set source allows on loopback only: through a CheckedAgent, so the listener's owner is told
+// before a byte is written and keys another OS account's process serves are never read (DEC-0154 HA-2, FAA-255).
+function loopbackKeySet(source, agent) {
+  return new Promise((resolve, reject) => {
+    const request = http.get(source.split('#')[0], { agent, headers: { Accept: 'application/json' }, timeout: 5000 }, (response) => {
+      if (response.statusCode < 200 || response.statusCode > 299) { response.resume(); reject(new Error(`HTTP ${response.statusCode}`)); return; }
+      let text = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => { text += chunk; if (text.length > KEY_SET_MAX) { request.destroy(); reject(new Error('the key set is too large')); } });
+      response.on('end', () => { try { resolve(JSON.parse(text)); } catch (e) { reject(e); } });
+      response.on('error', reject);
+    });
+    request.on('timeout', () => request.destroy(new Error('the key set did not arrive within 5 s')));
+    request.on('error', (e) => reject(e instanceof ListenerRefused ? new Error(`foreign-user: ${e.message}`) : e));
+  });
+}
+
+/** Read a key set source: an https URL (fetch, no redirect), a loopback http URL (checked listener) or a file. */
+export async function fetchKeySet(source, { agent = KEY_SET_AGENT } = {}) {
+  if (/^http:\/\//.test(source)) return loopbackKeySet(source, agent);
+  return defaultFetch(source);
+}
+
 async function defaultFetch(source) {
-  if (/^https?:\/\//.test(source)) {
+  if (/^https:\/\//.test(source)) {
     const response = await fetch(source, { headers: { Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(5000) });
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
     if (Number(response.headers.get('content-length') ?? 0) > 65536) throw new Error('the key set is too large');
@@ -428,7 +456,7 @@ async function defaultFetch(source) {
  * `await get(kid)` answers null when no set younger than 10 minutes can be had (issuer-unavailable).
  */
 export class JwksCache {
-  constructor(source, { fetch: fetcher = defaultFetch, clock = () => Date.now() / 1000 } = {}) {
+  constructor(source, { fetch: fetcher = fetchKeySet, clock = () => Date.now() / 1000 } = {}) {
     if (typeof source !== 'string' || !source) throw new Error('the key set needs a source');
     if (/^https?:\/\//.test(source)) {
       const url = new URL(source);

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

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { credentialName, repositoryCredential, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
-import { ID, INSTANCE, LOCAL_PATH, PROTOCOL, ServiceError, TASK, UNIT, expand } from './fabric-base.mjs';
+import { ID, INSTANCE, LOCAL_PATH, PRIMARY_CAPABILITY, PROTOCOL, ServiceError, TASK, UNIT, expand } from './fabric-base.mjs';
 import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
 import { protocolsFindings } from './fabric-protocols.mjs';
 import { CONNECTIONS_EXTENSION_KEY, connectionsView } from './fabric-connections.mjs';
@@ -15,7 +15,7 @@ import { ROUTES } from './fabric-usage.mjs';
 // document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
 export const DASHBOARD_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1';
 
-export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.5';
+export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.6';
 
 export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 
@@ -418,6 +418,9 @@ export function configurationProblems(doc) {
 // `a2a` (DEC-0122) is surfaces.a2a, where the service serves its public Agent Card (a2aSurface builds one); passed here
 // or in `surfaces`, never both, and refused when it is not the schema's. A reader pinned before DEC-0122 refuses the
 // member, so a service carries it only once its readers are pinned at or after it.
+// FAA-244: DEC-0140 PR-1 reserves the primary responder's capability; a service never publishes it.
+const reserved = (where) => `${where}: ${PRIMARY_CAPABILITY} is reserved for a Project's primary responder, a session (DEC-0140 PR-1); a service never serves it as a tool or declares it.`;
+
 export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration, protocols, actions, a2a }) {
   if (!STATUSES.includes(status)) throw new ServiceError(`status must be one of ${STATUSES.join(', ')}.`);
   if (!surfaces?.events) throw new ServiceError('surfaces.events is required.');
@@ -430,6 +433,7 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
     const problems = a2aSurfaceProblems(surfaces.a2a);
     if (problems.length) throw new ServiceError(`surfaces.a2a: ${problems.join('; ')}.`);
   }
+  if (Array.isArray(surfaces.mcp?.capabilities) && surfaces.mcp.capabilities.includes(PRIMARY_CAPABILITY)) throw new ServiceError(reserved('surfaces.mcp.capabilities'));
   if (!(build?.commit || build?.digest)) throw new ServiceError('build needs a commit or a digest.');
   const doc = {
     protocol: PROTOCOL,
@@ -461,6 +465,7 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
       // compared with the capabilities this document's MCP surface lists.
       const findings = actionsExtensionRules({ extensions: { [ACTIONS_EXTENSION_KEY]: extensions[ACTIONS_EXTENSION_KEY] }, surfaces });
       if (findings.length) throw new ServiceError(`Actions declaration: ${findings.map((f) => f.message).join('; ')}.`);
+      if ((extensions[ACTIONS_EXTENSION_KEY]?.actions ?? []).some((a) => a?.tool === PRIMARY_CAPABILITY)) throw new ServiceError(reserved("an action's tool"));
     }
     doc.extensions = { ...extensions };
   }

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

@@ -27,6 +27,9 @@ export class AlreadyRunning extends ServiceError {
 }
 
 export class InstanceLock {
+  /** How many times acquire re-opens service.lock that moved under it before it gives up (FAA-293). */
+  static INODE_RETRIES = 3;
+
   constructor(dataDir) {
     this.path = path.join(dataDir, 'service.lock');
     this.fd = null;
@@ -36,27 +39,12 @@ export class InstanceLock {
   async acquire() {
     ensurePrivateDir(path.dirname(this.path));
     if (process.platform === 'darwin') {
-      const flags = fs.constants.O_RDWR | fs.constants.O_CREAT | O_EXLOCK | fs.constants.O_NONBLOCK;
-      try {
-        this.fd = fs.openSync(this.path, flags, 0o600);
-      } catch (error) {
-        if (error.code === 'EAGAIN' || error.code === 'EWOULDBLOCK') throw new AlreadyRunning(readPid(this.path), this.path);
-        throw error;
-      }
-      try {
-        fs.ftruncateSync(this.fd, 0);
-        fs.writeSync(this.fd, String(process.pid));
-        fs.fsyncSync(this.fd);
-      } catch (error) { // a full disk or an I/O error: let the lock go, or nobody can (the caller drops this object)
-        const fd = this.fd;
-        this.fd = null;
-        try {
-          fs.closeSync(fd);
-        } catch { // a deferred write error (NFS) at the close: the lock still goes, the first error stands
-        }
-        throw error;
+      // FAA-293: a folder swapped under service.lock (a data import) leaves this copy holding a file that is no longer
+      // at the path while another copy holds the one that is. Re-open a bounded number of times, then fail clearly.
+      for (let attempt = 0; attempt < InstanceLock.INODE_RETRIES; attempt += 1) {
+        if (this.acquireDarwinOnce()) return this;
       }
-      return this;
+      throw new ServiceError(`${this.path} kept moving while it was locked (a folder swapped under the data folder?): no copy holds a file that is no longer at its path; start again once the folder is settled.`);
     }
     // Linux: an abstract unix socket; Windows: a named pipe. Each is exclusive, has no file, and dies
     // with the process. The Python kit holds the same name beside its file lock (fabric_service.lock_name).
@@ -90,6 +78,52 @@ export class InstanceLock {
     return this;
   }
 
+  lockedFileIsAtPath(fd) {
+    let here;
+    try {
+      here = fs.statSync(this.path);
+    } catch (error) {
+      if (error.code === 'ENOENT') return false;
+      throw error;
+    }
+    const held = fs.fstatSync(fd);
+    return here.dev === held.dev && here.ino === held.ino;
+  }
+
+  acquireDarwinOnce() {
+    const flags = fs.constants.O_RDWR | fs.constants.O_CREAT | O_EXLOCK | fs.constants.O_NONBLOCK;
+    try {
+      this.fd = fs.openSync(this.path, flags, 0o600);
+    } catch (error) {
+      if (error.code === 'EAGAIN' || error.code === 'EWOULDBLOCK') throw new AlreadyRunning(readPid(this.path), this.path);
+      throw error;
+    }
+    if (!this.lockedFileIsAtPath(this.fd)) { // another copy may hold the file at the path: re-open that one
+      fs.closeSync(this.fd);
+      this.fd = null;
+      return false;
+    }
+    try {
+      fs.ftruncateSync(this.fd, 0);
+      fs.writeSync(this.fd, String(process.pid));
+      fs.fsyncSync(this.fd);
+    } catch (error) { // a full disk or an I/O error: let the lock go, or nobody can (the caller drops this object)
+      const fd = this.fd;
+      this.fd = null;
+      try {
+        fs.closeSync(fd);
+      } catch { // a deferred write error (NFS) at the close: the lock still goes, the first error stands
+      }
+      throw error;
+    }
+    if (!this.lockedFileIsAtPath(this.fd)) { // swapped while the pid was written: this copy holds nothing real
+      fs.closeSync(this.fd);
+      this.fd = null;
+      return false;
+    }
+    return true;
+  }
+
   release() {
     if (this.fd !== null) fs.closeSync(this.fd);
     if (this.server) this.server.close();

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

@@ -277,6 +277,9 @@ export class Client {
         }
         attempts.push({ model: current, status: result.status, outcome: result.outcome });
         if (result.answer) return { ...result.answer, attempts };
+        if (result.outcome === 'foreign-user') { // FAA-257: the fallback would go to the same refused listener
+          throw new OpenRouterError('The base URL\'s port is held by another OS account\'s process, or its owner cannot be told; nothing was sent (DEC-0154 HA-2)', { kind: 'foreign-user', attempts });
+        }
         if (Object.values(STOP_AT_ONCE).includes(result.outcome)) {
           throw new OpenRouterError(`OpenRouter refused the key or the request (${result.status})`, { kind: result.outcome, attempts });
         }
@@ -299,6 +302,7 @@ export class Client {
         // may have been billed (a cut connection looks like a refused one from here): counted, never as $0
         this.ledger.record(this.unmeasured(asked, taskRunId, worst));
       }
+      if (err.kind === 'foreign-user') return { outcome: 'foreign-user', status: err.status }; // nothing sent, nothing billed (FAA-257)
       return { outcome: ['connection', 'timeout'].includes(err.kind) ? 'retry' : 'refused', status: err.status };
     }
     const { status } = response;

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

@@ -534,7 +534,9 @@ export async function pidListens(pid, port, { run = runProgram, platform = proce
 // 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, vouchPid = null, ...ask } = {}) {
   return new Promise((resolveSocket, reject) => {
-    const socket = net.connect({ host, port, noDelay: true }); // as a plain http.Agent's socket
+    // autoSelectFamily: Node 18 connects to the first address only, and localhost resolves to ::1 first on Linux, so a
+    // listener on 127.0.0.1 was never reached; Python tries every address, as Node 20 and later do by default.
+    const socket = net.connect({ host, port, noDelay: true, autoSelectFamily: true }); // as a plain http.Agent's socket
     const timer = setTimeout(() => socket.destroy(Object.assign(new Error('connect timeout'), { code: 'ETIMEDOUT' })), timeoutMs);
     socket.once('error', (err) => { clearTimeout(timer); reject(err); });
     socket.once('connect', async () => {

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

@@ -66,7 +66,10 @@ export function rawValues(query) {
     if (piece === '') continue;
     const at = piece.indexOf('=');
     const name = [...new URLSearchParams(at < 0 ? piece : piece.slice(0, at)).keys()][0] ?? '';
-    values.set(name, [...(values.get(name) ?? []), at < 0 ? '' : decodeKeepingPlus(piece.slice(at + 1))]);
+    const value = at < 0 ? '' : decodeKeepingPlus(piece.slice(at + 1));
+    const list = values.get(name);
+    if (list) list.push(value); // appended in place: copying the list per piece made a long query quadratic (FAA-245)
+    else values.set(name, [value]);
   }
   return values;
 }

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

@@ -5,6 +5,7 @@
 export {
   PROTOCOL,
   EXTENSION_KEY,
+  PRIMARY_CAPABILITY,
   SUPERVISOR_ENV,
   DRAIN_SECONDS,
   ServiceError,
@@ -177,6 +178,11 @@ export {
   taskInstall,
   taskUninstall,
   launchdPlist,
+  SYSTEM_DAEMONS,
+  launchdDomain,
+  wellKnownOf,
+  jobWellKnownOf,
+  ForeignUserAnswer,
   launchdLoaded,
   launchdPid,
   launchdOverride,