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

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

@@ -81,7 +81,7 @@ const answer = await client.chat(messages, { model, fallback, maxTokens: 800 });
 | Receipts | every status-200 answer records one, and so does an attempt that may have been billed without an answer to read (a timeout, a cut or refused connection, a 200 over the size cap or not JSON: no tokens, `costUsd: null`, `tokensMeasured: false`; over-counting a refused connection is the safe side): the served model, the provider's tokens (cache reads and writes kept apart), `costUsd` from `usage.cost`, else from the price list (`costBasis: price-list`), else `null` with `tokensMeasured: false`; `route: key`, the client's `project_id` and the call's `task_run_id`. A request the provider answered with a 4xx or 5xx records nothing: it was not billed |
 | What is an answer | `finish_reason` `stop` or `tool_calls` with content or tool calls; `error` is retried on the same model; `length` (the budget ran out, reasoning included), `content_filter` and empty content go to the fallback |
 | Retries | 408, 425, 429, 500, 502, 503, 504 and connection errors on the same model, `retries` times (default 1), `Retry-After` honoured, within one deadline (`deadline_s` 120) for the whole call |
-| Stop at once | 401, 402 and 403 (kinds `auth`, `payment`): a key, credit or permission problem is the same on every model |
+| Stop at once | 401, 402 and 403 (kinds `auth`, `payment`): a key, credit or permission problem is the same on every model; a loopback `base_url` another OS account's process holds (kind `foreign-user`, nothing sent, nothing counted): the fallback would reach the same listener (FAA-257) |
 | The fallback | required, of another vendor (the part before `/` differs) |
 | Content | text only: a string, null, or parts that are all `{"type": "text"}`; an image, audio or file part is refused (`config`), because what it is billed cannot be bounded from its bytes |
 | What the ceiling does not cover | the `provider` routing param can send a call to a provider priced above the catalog; two `Client` objects sharing one ledger each hold only their own calls in flight, so give an agent one client per key |
@@ -90,7 +90,7 @@ const answer = await client.chat(messages, { model, fallback, maxTokens: 800 });
 | Request body | `model`, `messages`, `max_tokens`, `usage: {include: true}` and your params (temperature, reasoning, response_format, tools); `stream`, `model`, `messages`, `max_tokens` and `usage` as params are refused |
 
 `OpenRouterError.attempts` lists every attempt as `{model, status, outcome}` (`answered`, `retry`, `error`,
-`length`, `filtered`, `empty`, `refused`, `bad-answer`, `auth`, `payment`); nothing in it holds the key or the
+`length`, `filtered`, `empty`, `refused`, `bad-answer`, `auth`, `payment`, `foreign-user`); nothing in it holds the key or the
 prompt. `totals(receipts)` gives calls, priced spend and unpriced calls for a dashboard line. Choosing the models
 themselves: creating-fabric-agents, `references/models-and-providers.md`.
 

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

@@ -59,7 +59,7 @@ Never edit the copied files: the page's own rules go in its own stylesheet, cons
 | Grids | `.fd-grid` (cards, 320 px columns), `.fd-grid--tiles` (160 px), `.fd-grid--wide` (480 px); `--fd-col` sets your own |
 | Wide content | `<div class="fd-scroll" data-fd-label="Jobs table"><table class="fd-table">…</table></div>`, `<pre class="fd-scroll">` |
 | Atoms | `.fd-card`, `.fd-tile`, `.fd-chip` + `.fd-dot` + `.fd-s-ok\|warn\|danger\|info`, `.fd-btn`, `.fd-btn--primary`, `.fd-input`, `.fd-select`, `.fd-banner`, `.fd-empty`, `.fd-pairs` |
-| Navigation that folds | with the script, links that do not fit move into **More** (`data-fd-more-label` names it, `data-fd-no-fold` keeps a nav as is); the summary names the current section (`aria-current`) or counts the folded links, and the fit is measured with that text in place. Moving `aria-current` refits on its own; after changing the links' text call `FabricDashboard.refreshNav(nav)` (since 1.1.3) |
+| Navigation that folds | with the script, links that do not fit move into **More** (`data-fd-more-label` names it, `data-fd-no-fold` keeps a nav as is); the summary names the current section (`aria-current`) or counts the folded links, and the fit is measured with that text in place. Moving `aria-current` refits on its own; after changing the links' text call `FabricDashboard.refreshNav(nav)` (since 1.1.3). Since 1.1.6 a resize refits in the next animation frame and only when the nav's width changed, and the chrome's `--fd-chrome-h` and `--fd-chrome-top` are written the same way and only when they change, so no observer resizes what it watches inside its own callback (WebKit's "ResizeObserver loop completed with undelivered notifications" at 390 px, seen on a service page) |
 | Own appearance controls | `<select data-fd-theme-picker>`, `<select data-fd-scheme-picker>` (the script fills them; hidden while the host owns appearance) |
 
 Tokens are the workbench layer (`--bg`, `--panel`, `--panel-2`, `--ink`, `--muted`, `--border`,

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

@@ -125,11 +125,43 @@ its acceptance does not authorize or deliver it. Enforce grants/dedup/expiry in
 the transport. Unknown or failed host status produces no executable local action.
 A separately labelled copyable link for diagnosis is not an open action.
 
-Add this check to the generated project's dashboard completion/notification
-renderer before delivery. A raw-HTTP primary action with an available host is the
-negative fixture; a valid native action is the positive one. Keep diagnostics
-separate. This gate checks structured actions, not arbitrary prose: a CLI invocation
-or instructions alone do not prove all final answers from every agent are filtered.
+The gate is **agent-side**: the agent runs it from this skill's directory before it
+delivers an action. It is never copied into the generated project and never run by
+that project's CI: the adapter's versioned plugin folder has no stable path there, so
+its result in a project's pipeline would always be NOT_RUN. A raw-HTTP primary action
+with an available host is the gate's negative fixture; a valid native action is the
+positive one. Keep diagnostics separate. This gate checks structured actions, not
+arbitrary prose: a CLI invocation or instructions alone do not prove all final answers
+from every agent are filtered.
+
+The generated project pins the same negative fixture in its own test suite, without
+calling the gate: a test that renders its completion and notification output with an
+available host and fails when a raw loopback `http_url` or a legacy `open?service=`
+link appears in it. The snippet is self-contained; `render` stands for the project's
+own renderer:
+
+```python
+import re
+import unittest
+
+RAW_LOOPBACK = re.compile(r"https?://(?:127\.0\.0\.1|localhost|\[::1\])")
+LEGACY = "fabric-dashboards://open?service="
+RESOLVED = {"service": "example-agent.default",
+            "open_link": "fabric-dashboards://service/example-agent.default?path=%2Fdashboard",
+            "http_url": "http://127.0.0.1:47195/dashboard"}
+
+
+def render(resolved, host_state):  # replace with the project's completion/notification renderer
+    raise NotImplementedError
+
+
+class RenderedDashboardLinks(unittest.TestCase):
+    def test_rendered_output_has_no_raw_loopback_or_legacy_link(self):
+        out = render(RESOLVED, host_state="available")
+        self.assertIn(RESOLVED["open_link"], out)
+        self.assertIsNone(RAW_LOOPBACK.search(out), out)
+        self.assertNotIn(LEGACY, out)
+```
 
 ## Degradation
 

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

@@ -127,7 +127,10 @@ page as Fabric Dashboards' `open_link`; both kits carry the same sentence. The g
 
 `JwksCache` holds the estate's key set at most 10 minutes and, on a `kid` it does not hold, re-reads at most once
 a minute (DL-15), and waits 10 s after a failed read before trying again; after 10 minutes without a successful read it answers nothing, and the verifier says
-`issuer-unavailable`. It reads https, http on loopback only, or a file; a URL with credentials is refused. The
+`issuer-unavailable`. It reads https, http on loopback only, or a file; a URL with credentials is refused. On loopback
+http it tells the listener's owner from the socket table before a byte is sent and reads no key set another OS
+account's process serves (DEC-0154 HA-2, `fabric_peer_owner`; the read fails `foreign-user`, so the set stays unread,
+FAA-255); no proxy from the environment is used there. Where the socket table hides other processes (macOS 27.2 with an ad-hoc-signed Homebrew Python, FAA-267), the owner cannot be told, so a loopback key set fails `foreign-user` and every delegated call is refused `issuer-unavailable`: run the service on Apple's `/usr/bin/python3`, or give the verifier the key set as a file. The
 Python kit also refuses, https included, a URL holding a space or ASCII control character before its first `#` (it
 reads the URL up to there, as Node does), or a character outside ASCII in its path or query (urllib would send it
 and every read fail; a trailing ASCII space or line break is trimmed as urllib reads it; a Unicode space ending the

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

@@ -51,7 +51,12 @@ carry a credential. Only `doctor` and `update` are commands a host may run.
 **Started is not ready.** Readiness is the well-known document, `GET /.well-known/fabric-service`: answered without
 authentication, from memory, in under 100 ms, with `service.id` and `service.instance` equal to the descriptor's,
 on a listener of this OS account (DEC-0154 HA-2: another account's listener is `foreign-user` whatever it answers; a
-LaunchDaemon's root installer reads it as *The system domain* says).
+LaunchDaemon's root installer reads it as *The system domain* says). `well_known_of(origin)` / `wellKnownOf(origin)` read
+it so a status tells HA-2's order apart: None / null when nothing answers (`down`), a `ForeignUserAnswer` whose
+`reason` starts `foreign-user` or `table-restricted`, else the document; `fetch_well_known` keeps answering None for
+both (FAA-259). Every loopback spelling of an origin (`127.0.0.1`, another `127/8` address, `localhost`, `[::1]`) is read
+on a checked connection (FAA-257). `launchd_install` takes an injected reader, `fetch_well_known=` and
+`fetch_job_well_known=`, as the Node `launchdInstall` takes `fetchWellKnown` and `fetchJobWellKnown`.
 `status` is `starting`, `ready`, `degraded` or `stopping`; `degraded` is always present, and an empty list asserts
 full health. A process that cannot serve does not answer, and a host derives `down`. An install or upgrade polls
 that document until `service.id` matches (at most 40 s) before it calls the service started (the launchd installers;

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>`
 

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,
@@ -179,6 +180,7 @@ export {
   launchdPlist,
   SYSTEM_DAEMONS,
   launchdDomain,
+  wellKnownOf,
   jobWellKnownOf,
   ForeignUserAnswer,
   launchdLoaded,

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

@@ -490,8 +490,20 @@ 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, { vouchPid = null } = {}) {
-  const m = /^http:\/\/127\.0\.0\.1:([0-9]{1,5})$/.exec(origin);
+// Every loopback spelling (127.0.0.1, another 127/8 address, localhost, [::1]) goes on a checked connection, never the
+// unchecked way (FAA-257): the host, without brackets, and the port, or null.
+function loopbackOrigin(origin) {
+  let url;
+  try { url = new URL(String(origin)); } catch { return null; }
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  const loop = host === 'localhost' || host === '::1' || (net.isIPv4(host) && host.startsWith('127.'));
+  if (url.protocol !== 'http:' || !loop) return null;
+  // new URL drops a default port: http://127.0.0.1:80 has port '', read as 80 as Python's urlsplit reads it (0.79.0 seam)
+  return { host, port: Number(url.port || 80) };
+}
+
+export async function wellKnownOf(origin, { vouchPid = null, ask = undefined } = {}) {
+  const m = loopbackOrigin(origin);
   if (!m) {
     try {
       const response = await fetch(`${origin}/.well-known/fabric-service`, { signal: AbortSignal.timeout(2000) });
@@ -502,14 +514,14 @@ export async function wellKnownOf(origin, { vouchPid = null } = {}) {
   }
   // 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.
-  return loopbackWellKnown(Number(m[1]), new CheckedAgent({ keepAlive: false, vouchPid }));
+  return loopbackWellKnown(m.port, new CheckedAgent({ keepAlive: false, vouchPid, ...(ask ? { ask } : {}) }), m.host);
 }
 
 // The well-known answer at 127.0.0.1:<port> over `agent`, whose connections check their server end: null when nothing
 // answers or the answer is not JSON, a ForeignUserAnswer when the agent refused the listener.
-function loopbackWellKnown(port, agent) {
+function loopbackWellKnown(port, agent, host = '127.0.0.1') {
   return new Promise((resolve) => {
-    const req = http.request({ host: '127.0.0.1', port, path: '/.well-known/fabric-service', agent,
+    const req = http.request({ host, port, path: '/.well-known/fabric-service', agent,
       timeout: 2000 }, (res) => {
       const chunks = [];
       res.on('data', (c) => chunks.push(c));

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

@@ -16,6 +16,12 @@ PROTOCOL = "fabric-service/0.1"
 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).
+PRIMARY_CAPABILITY = "project.work"
+
+
 # Lifecycle rules: references/lifecycle.md, the rule for this kit's users, which implements the public
 # contract's service specification (Lifecycle). A launchd-supervised copy that finds the lock held backs
 # off in-process for this long before its exit 75 (LC-03, F8): under KeepAlive with ThrottleInterval 10

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

@@ -52,6 +52,9 @@ class BoardSession:
                              timeout=timeout if timeout is not None and timeout > 0 else self.timeout,
                              method=method, protocol_version=self.protocol_version if self.mcp_session else None)
         except _hub.HubError as exc:
+            if exc.code == "foreign-user":  # FAA-252: another OS account's process holds the port; nothing was sent
+                raise BoardError("foreign-user", "The hub's port is held by another OS account's process; nothing was sent.",
+                                 True) from exc
             raise BoardError("unreachable", "Fabric's hub did not answer; a write may have been stored, so send it again with "
                              "the same idempotency key.", True) from exc
 

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

@@ -148,6 +148,9 @@ class Responder(SlotKeeper):
         caps = list(capabilities)
         if not caps or any(not isinstance(c, str) or not _CAPABILITY.fullmatch(c) for c in caps) or len(set(caps)) != len(caps):
             raise BoardError("invalid_arguments", "Name each capability once, [a-z][a-z0-9._-]{1,127}.")
+        if _fs.PRIMARY_CAPABILITY in caps:  # FAA-244: DEC-0140 PR-1, a session's slot, never a service's
+            raise BoardError("invalid_arguments", "%s is a Project's primary responder's, a session's: a service answers "
+                             "the capabilities it declares (DEC-0140 PR-1)." % _fs.PRIMARY_CAPABILITY)
         self.hub, self.project = hub, _hub._project(project_id)
         #: FAA-135: read the operator's mandate from a trusted request of his own Project (opt-in; None reads none).
         self.mandate_from, self.agent_id, self.wall = _link.mandate_options(agent_id, mandate_from), agent_id, wall
@@ -258,7 +261,7 @@ class Responder(SlotKeeper):
         status = self._status()
         if missing:
             self._emit("board.access.needed", "warning", "The operator has not let this service answer %s on this Project; ask in "
-                       "Fabric (Agents & access)." % ", ".join(missing), notify=True, episode=",".join(missing),
+                       "Fabric (Settings → Agent access)." % ", ".join(missing), notify=True, episode=",".join(missing),
                        capabilities=missing)
         self.slots = {}
         self._recover(status, [c for c in self.capabilities if c in grant.capabilities])
@@ -430,7 +433,8 @@ class Responder(SlotKeeper):
         try:
             self._receipt("com.reply", self._call("com.reply", dict(self._reply_extra(entry), fence=self._fence(old, probe["key"]))))
         except BoardError as exc:
-            if exc.code in ("unreachable", "session-ended", "authority_changed", "not_authorized", "not_available", "capacity_exceeded"):
+            if exc.code in ("unreachable", "foreign-user", "session-ended", "authority_changed", "not_authorized", "not_available",
+                            "capacity_exceeded"):  # foreign-user: nothing was sent now, so nothing is known (0.79.0 seam)
                 raise
         else:
             entry["replied"] = True
@@ -549,7 +553,7 @@ class Responder(SlotKeeper):
             self.state = "not-authorized"
             self._drop_session()
             self._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,
+                       "has to allow it in Fabric (Settings → Agent access). Nothing is claimed until then.", notify=True,
                        episode="access", reason=code)
         elif code == "held":
             self.state = "paused"
@@ -564,9 +568,13 @@ class Responder(SlotKeeper):
         else:
             self.state = "down"
             # In recovery with no slot held a refusal reconnects (seam 6); with some held they are served (seam 7).
-            if (connecting or code in ("session-ended", "unreachable", "not-running", "not-a-hub", "hub-unavailable", "protocol")) and not keep:
+            if (connecting or code in ("session-ended", "unreachable", "not-running", "not-a-hub", "hub-unavailable", "protocol",
+                                       "foreign-user")) and not keep:
                 self._drop_session()
-            self._emit("board.down", "warning", "Fabric's board cannot be reached; the responder tries again with a growing pause.",
+            # FAA-252: a port another OS account holds is said as such; nothing was sent there
+            self._emit("board.down", "warning", "Fabric's board port is held by another OS account's process; nothing was sent, "
+                       "and the responder tries again with a growing pause." if code == "foreign-user" else
+                       "Fabric's board cannot be reached; the responder tries again with a growing pause.",
                        episode="down", reason=code)
         return wait