@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,208 @@
 # Changelog
 
+## 0.41.0 (2026-10-22)
+
+The 2026-10-22 audit, closed (FAA-68 to FAA-81; [report](docs/reports/2026-10-22-adapter-audit/README.md),
+[brief](docs/evidence/specs/2026-10-22-audit-fixes-brief.md)). Its 53 findings fell into six classes; each class got
+its fixes and a guard that fails the next instance. Each fix has a test; the builders' reports and the commit
+messages name the ones seen failing before the fix. Three blind readings (unit, seam, product) certified the result
+and their findings are fixed here too.
+
+### Fixed
+
+- **Session hooks and the delivery worker** (FAA-68). One JSON-RPC error or unreadable spool entry no longer blocks
+  a session's spool for good: the entry is logged by its code and dropped, and the end, the claim release and the end
+  observation still go out. `fabric-mcp` runs in its own process group and the whole group is ended at the deadline,
+  so a wrapper (`npx`, a shell script, `fabric-mcp.cmd`) cannot hold the worker for a minute. A process walk that
+  cannot read the processes spools nothing and releases nothing; a launched session is remembered. Turn facts are
+  measured when the turn ends (counts only). watch-mail keeps its delay between 10 s and 15 min after the jitter and
+  honours the once-a-minute rejoin mark. Stale spool folders are pruned even while the hooks are inert; a stale
+  worker lock is taken by an atomic rename, and its identity includes the write time and size (Linux reuses a freed
+  inode number at once). An end whose release got no answer stays for the next worker. On Windows a bare `fabric-mcp`
+  resolves to `fabric-mcp.cmd`.
+- **Host installers and the dashboard notice** (FAA-69). The SessionStart notice asks whether the repository owns a
+  service before it reads the tree, all within one 3.5 s budget. The Kimi installer repairs or removes a stale script
+  path; Kimi and Codex require the script to exist; Hermes `--remove` works without the source folder; the OpenCode
+  and OpenClaw bridges run the helper once per workspace, not per request, and never keep a failed run.
+- **The service kit's Python twin** (FAA-70). `launchd_plist` refuses what the Node twin refuses: a secret-shaped
+  argument or environment value, a bad label, an empty argv, an `ExitTimeOut` under the drain. `JobStore` and the
+  event log hold a lock per store path (one idempotency key made two jobs; a cancelled job became completed; 41 of
+  160 events were kept). `pause` checks for a terminal job first (both twins). The JWKS fetch has one 5 s deadline,
+  runs outside the cache lock and turns a garbage answer into `issuer-unavailable`. Whole-value patterns end in
+  `\Z`, so a trailing newline no longer validates. An origin written with its default port is accepted as Node
+  accepts it. A socket timeout is a timeout on Python 3.9. Non-object MCP params answer -32602. systemd
+  `Environment=` no longer doubles `$`. The sample service answers 400 to a bad `Content-Length` or body.
+- **The board responder** (FAA-77). A lost reply answer no longer leaves a request `accepted` for good: a transfer
+  re-derives the per-attempt keys after re-sending the old reply under its old key, and `idempotency_conflict` is its
+  own `board.blocked` event. One fenced call per entry at a time, and a `revision_conflict` on renew re-reads the
+  revision. An effect lost while the session holds the slot is observed and completed, or its slot is replaced so the
+  board records `outcome_unknown`. One lost answer keeps the session while the lease holds. Every transferred request
+  resumes, and a transfer survives a second lost answer (the request completes with one reply). The session's link
+  (MCP session, checkpoint, request) is its own module, `fabric_board_link` / `fabric-board-link.mjs`.
+- **Interop job keys** (FAA-70, FAA-77). A key admits only the intent it was first used for: another capability or
+  input is `idempotency-conflict` in `create` and `conflict` in `repeat`, which now takes the intent. A key file
+  written before 0.41.0 is answered with its job, and runs again only for the intent its job stored.
+- **Package, delegation and estate twins** (FAA-78). Both kits refuse a package path holding a control character,
+  U+2028 or U+2029, whatever the schema's pattern lets through (the contract owner was told). An unreadable folder
+  entry is refused instead of skipped (Python) or crashing (Node). Files are opened without following links. Node
+  reads JSON as strict UTF-8 and keeps a top-level `__proto__`; both cap nesting at 256 levels; dates take ASCII
+  digits. An explicit `null` estate, applied mark or revocation list fails closed in both kits. JWKS `x` must be
+  canonical base64url in both. Python Ed25519 signing is a Montgomery ladder that does not branch on the key. The
+  hub's loopback origin takes ASCII digits only. On Windows, `fabric.package.json` is written with `\n` like the Node
+  kit's, and the command line answers in UTF-8 whatever the console's code page.
+- **The adapting skill's scripts** (FAA-71). `fabric_provider.py write` refuses what the pinned provider schema
+  refuses (ports under 100, a non-URI repository, an argument over 1024 characters), refuses `--env` with `--url`
+  and a writer option after `--stdio`. `check` names every template value still present and keeps
+  `readyForAdmission` false; `check --contract` calls the checkout's own `tsx`, never `pnpm exec`; a client
+  `.mcp.json` is not an MCP surface; a non-UTF-8 manifest is a typed receipt. `scaffold --dry-run` prints the writes
+  and a diff of each collision.
+- **Dashboard probes and the link gate** (FAA-79). The layout probe never prints a login code (it starts the browser
+  before asking for one); ED-3 checks vertical clipping; ED-4 says NOT_RUN past its element cap. The handoff-link
+  gate normalises the path and refuses `code`, `api_key` and the other credential names. The "Get Fabric" menu link is
+  reachable by keyboard; the dashboard kit is 1.1.2.
+- **Installers** (FAA-80). `install.sh` leaves an existing copy alone without `--force` and never copies
+  `__pycache__`; both installers build a new copy beside the old and rename it, report each failure and exit 1.
+- **The support-agent recipe** (FAA-81). A reply carrying a link (bare host names included), address, phone number,
+  amount or number its cited entries do not contain goes to a person; links and addresses are compared by equality,
+  never as substrings; the customer's message reaches the model as fenced data. A promise written in words is not
+  caught, and the README says so. Decisions are an
+  append-only log; `prune --keep-days N` deletes old rows; the README says the outbox keeps customer text.
+
+### Changed
+
+- **CI follows the organization's rule** (FAA-72). `validate.yml` runs nightly on `main` and on dispatch, with job
+  timeouts and a concurrency group; a `contract` job installs the contract at the pin and at the legacy revision and
+  runs the tests that used to skip (one of them had rotted); a `floors` job runs Python 3.9 and Node 18; a `macos` job
+  runs both suites; Windows runs the session tests and the whole Node suite (16 tests that assumed POSIX now check
+  the Windows ACL or say why they skip). `engines.node` is `>=18` (the npm CLI); the Node service kit needs 20, and on
+  Linux its instance lock needs 22: Node 18 and early 20 collapse every abstract socket name into one, and later 20
+  pads it so no Python copy or probe sees it, so the kit refuses to start there with a sentence naming Node 22.
+- **The release path** (FAA-73). The tarball smoke test runs before the GitHub release is created; every action is
+  pinned to a commit SHA; npm and the Claude Code CLI are pinned; release titles carry no em dash; the dead
+  private-repository branch is gone. Moving npm publishing to trusted publishing (and removing `NPM_TOKEN`) waits on
+  the operator's npmjs.com sign-in.
+- **Skills and documents** (FAA-74, FAA-75). SECURITY.md and SKILL-CARD say what the probe and the kit really reach
+  and write; the `vault.py moved` command is correct; the secret tools have a path and a fallback; each skill's
+  NOT-for list names its siblings; shared blocks live in one reference; the building skill's description is 799
+  characters. `test/evals/run_evals.py` runs the trigger evals against a real client when asked; its first run scored
+  25/25 on `adapting-projects-to-fabric`.
+
+### Guards (each fails on a planted defect)
+
+- `validate.py` refuses a `$`-anchored whole-value pattern in every skill's scripts (R1; it found a real one in
+  `adapt_project`'s cost preset id), an em dash under
+  `.github/` (R6), and a workflow that floats an action, uses `@latest`, lacks a timeout, drops the nightly or gated
+  jobs, gains a push or PR trigger, or creates the release before the smoke test (R5).
+- Shared hostile-input fixtures run by both twins: `kit-hostile-inputs-core.json`, `kit-hostile-inputs-package.json`,
+  `kit-hostile-inputs-estate.json` (R1).
+- Fault-injection tests for the spool, the worker, the responder and the package walk (R2); concurrency tests for every
+  store a threaded server reaches (R3).
+- `test_a_released_version_keeps_its_digests`: a release's `kit.json` history entry stays what the release shipped (a
+  build before the version moved on had rewritten 0.40.0's, which would have read genuine 0.40.0 copies as modified).
+  It runs in a clone that has the release tags (a full local clone); the shallow hosted checkout skips it (FAA-82).
+- Two timing tests no longer fail on a loaded host: the runner probe's positive cases take the most a probe may take,
+  and the interop probe test lets the machine-timing verdict be the one that fails.
+
+### Upgrading
+
+- **A service built on the copied kit:** `fabric_kit.py status <dir>` names the modules to update; `fabric_kit.py install
+  <dir>` brings the closure, `fabric_board_link` included. Passing `estate=None` (or `estate_applied=None`,
+  `estate_revocations=None`) on purpose now refuses every token as `estate-unreadable`: leave the option out instead.
+- **A Linux service on the Node kit:** run it on Node 22 or later; on 18 or 20 it stops at start with a sentence saying so.
+- **A scaffolded bundle:** new scaffolds write a `urn:fabric:adapter:template` block into `fabric-agent.json` and take
+  `--data-class`, `--created-by`, `--identity-method` and `--probe-assertion`. Rerun `check`: an older bundle that still
+  holds the template's author, schemas or assertions now reads `readyForAdmission: false` until they are replaced.
+- **A dashboard on kit 1.1.1:** the SessionStart notice now points at 1.1.2; `dashboard_kit.py install` updates it.
+- **The support recipe:** its state moves to `decisions.jsonl` (an old `decisions.json` is still read); handoff rows gain
+  `question` and `at`, and new reasons `unsupported:url|email|phone|amount|number`. Run `prune --keep-days N` once, then
+  delete `decisions.json`.
+- **Links you hand out:** the gate now refuses a query or fragment name such as `code`, `key`, `auth` or `api_key`, and
+  a path with a dot segment or an encoded separator.
+- **Installing:** a copy already in the hub is kept unless `--force` (both installers); the npm installer reports each
+  skill `up to date`, `differs` or installed, and never copies Python bytecode.
+- **Open human step:** moving npm publishing to trusted publishing and deleting `NPM_TOKEN` needs the operator's
+  npmjs.com sign-in.
+
+
+## 0.40.0 - 2026-10-21
+
+The kits as production modules (FAA-65). Every name a kit module made public at 0.39.1 is still there; a service that
+copies the kit now installs it with `fabric_kit.py install` (one file is no longer enough, see below).
+
+### Added
+
+- **A shared core, once per language** (layer L0 and L1): `fabric_jsvalue` / `fabric-jsvalue.mjs` (JavaScript's view
+  of JSON values: `show`, `js_to_number`, `same`, `json_equal`, `jcs` and the rest), `fabric_time` / `fabric-time.mjs`
+  (strict RFC 3339, UTC days, formatting, day windows, an injectable clock: the public dates API, on shared cases) and
+  `fabric_crypto` / `fabric-crypto.mjs` (Ed25519 and P-256 checks, small-order keys, base64url, sha256). They used to
+  live, twice, inside the estate and delegation readers; every reader now imports them.
+- **The kit is a manifest-listed set, installable as one.** `kit.json` lists every module in dependency order, with the
+  kit modules it imports, its sha256 and the sha256 of every release since 0.8.0. `fabric_kit.py install <dir>`
+  copies a module's closure (data files included); `status <dir>` says `current`, `older` (with its release) or
+  `modified`, and names a module a copy imports but lacks. SKILL.md said the kit was "one self-contained file"; it was
+  not, and a one-file copy of `fabric_service.py` failed in `usage_findings`.
+- **Connectors** (layer L4, both languages, shared cases): `fabric_http` (one deadline across attempts, bounded
+  retries with jittered backoff only when repeating is safe, `Retry-After` up to a cap, a response size cap, redirects
+  answered and never followed, plain http refused off loopback, redacted URLs in errors) and `fabric_openrouter` (the
+  agent's own key from a named environment variable, a spend ceiling checked before every attempt at the worst case
+  with calls in flight reserved, one usage receipt per answered call, empty, `length`, `error` and filtered answers
+  never returned as success, a fallback of another vendor required, 401/402/403 stop at once, attribution off by
+  default). References: `kit-modules.md`, `connectors.md`.
+- **A support-agent recipe** (`building-fabric-services/recipes/support-agent/`): answers a question from a knowledge
+  file through `fabric_openrouter`, accepts a reply only when code proves it (citations exist and were given, no em
+  dash or substitute, the question's script, a length limit), otherwise hands it to a person with the failed checks
+  named; idempotent per message id. `test/validate.py` lets a recipe import the kit modules `kit.json` lists.
+- **Layering held by tests**: a module imports only modules listed before it (a planted cycle is caught), none is over
+  1000 lines across every skill's scripts, the core is defined once, every module is in the module map, and the
+  0.39.1 public API of both facades is a snapshot test.
+
+### Changed
+
+- `fabric_service` / `fabric-service.mjs` and `fabric_board` / `fabric-board.mjs` are facades over modules split by
+  responsibility (base, platform, paths, protocols, lock, usage, backups, descriptor, auth, events, logs, supervisors;
+  board shapes, session, fixture). The probe's rules moved to `check_service_rules.py`. In working-with-fabric,
+  `fabric_session.py` is a facade over `fabric_session_{env,mcp,mail,hosts,cli}.py`; the hooks, the worker and
+  `install-host-hooks` still run the facade.
+- No import cycle is left: `fabric_estate` no longer imports `fabric_delegation`, in both languages.
+- A Node service that imported a module-private helper of `fabric-service.mjs` or `fabric-board.mjs` (not exported at
+  0.39.1, so outside the snapshot) imports it from the module that holds it now.
+- The probe runs the board responder's self-check in a clean Python (`-E -s`, its own working directory), so it reads
+  the kit it names and not a copy already imported.
+
+### Fixed
+
+- **Found by the release review (three blind readings) and fixed before release:** the OpenRouter ceiling counted
+  only the messages, so a large `tools` list could pass it (the worst case now bounds the messages and every param;
+  `models`, `route`, `plugins` and `web_search_options` are refused); an attempt that may have been billed without an
+  answer to read (a timeout, a 200 over the size cap or not JSON) left no receipt (it now records one with no tokens
+  and no cost, counted at the worst case); the Python transport could overrun its deadline on a slowly trickled body
+  (it reads in chunks against one deadline); the twins differed on a lone surrogate, NaN in a body, a transport bug and
+  `http://127.1` (both now behave the same, on shared cases); `fabric_service.py` could not be loaded by its path from
+  another folder (every kit module now puts its own folder on `sys.path`, tested from `/`); `fabric_kit.py status`
+  judged an older copy by the current release's imports and named only direct ones (it now reads each copy's own
+  imports and follows the closure); an unknown `--module` is a usage error (exit 2); the facade keeps `_number`,
+  `_DAY_MS` and `_utc_date_ms`; `install-host-hooks` requires the session helper's new modules; the recipe hands off a
+  message holding bytes a terminal could not decode instead of exiting, and its dash check also catches U+2012 and
+  U+2015.
+- **Found by the second review round and fixed:** a connection cut after a call may have been billed left no receipt
+  (every connection error now records an unmeasured one); `max_completion_tokens` and `n` could raise the output past
+  the bound (refused); an unmeasured call was counted at the current call's worst case (now at its own, while the
+  client runs); Node read a blank or hex price as a number (both twins now read a plain decimal or a number only);
+  Python's deadline started after the headers (it now covers them); `fabric_kit.py status` raised on a copy it could
+  not parse (it reports it `modified`) and now names a missing module's data files; `fabric_http` writes a JSON body
+  byte for byte as `JSON.stringify` (numbers and key order too, through the core's `json_stringify`); loopback edge
+  forms agree in both twins; the recipe's dash check covers U+2E3A, U+2E3B, U+FE58 and no-break spaces, and no longer
+  flags `1 - 2`.
+- **Found by the third review round and fixed:** an answer with no usage was counted at the next call's worst case
+  (now at its own); image, audio and file parts could be sent past the bound (only text content is sent); Python
+  raised outside `OpenRouterError` and kept no receipt on a 400-digit count or cost or JSON nested too deep (both read
+  as unmeasured now); Python's deadline could be held by trickled headers (a watchdog shuts the socket at the
+  deadline); `Response.json()` reads a byte order mark and refuses `NaN` as `JSON.parse` does; a `Retry-After` year
+  before 1000 is no date in either twin.
+- **A usage receipt's project id is checked the same way in both kits.** `fabric_service.py` defined its URI pattern
+  twice and the second won: Python accepted `project_id="urn:"` where Node refused it. Now one pattern per module, and
+  both kits refuse it (a test in each).
+
 ## 0.39.1 - 2026-10-21
 
 Fixes from two rounds of blind review of 0.39.0 (FAA-64).

package/README.md

@@ -38,8 +38,8 @@ resume) puts that preamble into the session when the MCP server `fabric` is regi
 is down it adds one line (skip `fabric_whoami`, start Fabric through the broker if the task needs it), and only in a
 project that uses Fabric; Stop records each turn's facts (HEAD, files changed, lines added and removed, never content)
 and the board's unread count; UserPromptSubmit adds one line only when that count rose; SessionEnd releases what the
-session left claimed. Stop, UserPromptSubmit and SessionEnd act only when the running Fabric advertises
-`session-hooks/1`. All are silent in a session Fabric launched, never block the session, read no token and always
+session left claimed. Stop, UserPromptSubmit and SessionEnd spool and call Fabric only when the running Fabric
+advertises `session-hooks/1`; Stop and SessionEnd always prune their own stale spool folders. All are silent in a session Fabric launched, never block the session, read no token and always
 exit 0. `fabric_session.py watch-mail` waits for board mail under a background watcher, and `install-host-hooks
 --host codex|kimi|hermes|opencode|openclaw|pi` installs each host's native context bridge (dry run unless `--apply`).
 Codex receives structured SessionStart JSON; Hermes, OpenCode, OpenClaw and Pi use native plugin APIs.
@@ -54,9 +54,15 @@ that is always alive, runs as one copy, keeps its state through a reinstall and
 in Fabric Dashboards by itself: the `fabric-service/0.1` extension. It also makes an **online** agent
 or dashboard (an `https` origin on a platform) a Fabric service (the remote placement, DEC-0019): the same
 four routes behind the token, a `__Host-` session cookie, and one descriptor on the operator's computer;
-`scripts/sample-remote-service.mjs` is the complete example. It ships Python and
-Node reference kits (`scripts/fabric_service.py`, `scripts/fabric-service.mjs`), a
-complete `scripts/sample_service.py`, and `scripts/check_service.py`, a live probe. A service that answers
+`scripts/sample-remote-service.mjs` is the complete example. It ships the service kit in Python and
+Node: layered modules listed in `scripts/kit.json` behind the `fabric_service` / `fabric-service.mjs` facades,
+installed into a service with `scripts/fabric_kit.py install` and checked with `fabric_kit.py status`
+([kit modules](plugins/fabric-agent-adapter/skills/building-fabric-services/references/kit-modules.md), including
+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)); a ready
+[support-agent recipe](plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/README.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
 `board.respond` grant, enroll, claim, accept the exact digest, complete, a checkpoint before every step, and restarts
@@ -123,8 +129,13 @@ then restart your agents. Alone, without any account:
 ```bash
 npx @passioncode-ai/fabric-agent-adapter        # installs every skill into the agents hub ~/.agents/skills
 npx @passioncode-ai/fabric-agent-adapter --prune-shadow   # remove ~/.claude/skills copies that shadow the plugin
+npx @passioncode-ai/fabric-agent-adapter --force          # update a copy already in the hub (a launcher link is never replaced)
 ```
 
+A copy already in the hub is left alone unless `--force` is given; with it, the new copy is built beside the old one
+and renamed into place, so a failed run leaves the old copy or nothing. `install.sh --force` from a checkout does the
+same.
+
 Claude Code plugin marketplace:
 
 ```text
@@ -183,7 +194,8 @@ own service by its id once its installer has written the descriptor.
 
 ### Develop
 
-There is no build step and no dependency beyond Python 3.9+ and Node.js:
+There is no build step and no dependency beyond Python 3.9+ and Node.js. The npm CLI (installer, `pack`, `sign`,
+`verify`) needs Node.js 18+, the Node service kit 20+, and a Linux service's instance lock 22+:
 
 ```bash
 npm test                     # validate.py, the Python unit tests, the Node kit tests

package/SECURITY.md

@@ -11,13 +11,34 @@ bounded and non-publishing until explicit scoped grants exist in a project bindi
 ## What the installers and scripts touch
 
 - `npx @passioncode-ai/fabric-agent-adapter` and `install.sh` write only
-  `~/.agents/skills/<skill>`; `--target claude` writes `~/.claude/skills/<skill>` and is
+  `~/.agents/skills/<skill>` (and, while replacing a copy with `--force`, the sibling folders
+  `.<skill>.installing-*` and `.<skill>.replaced-*`, removed when the run ends; a killed run can
+  leave one behind); `--target claude` writes `~/.claude/skills/<skill>` and is
   refused while the plugin is installed; `--prune-shadow` moves shadowing copies into
   `~/.claude/skills-shadow-backup/`.
 - `building-fabric-services/scripts/check_service.py` reads a descriptor and the token
-  file it names, talks only to `127.0.0.1:<port>`, and redeems one login code it asked
-  for itself (creating one dashboard session). It never prints the token.
+  file it names, and redeems one login code it asked for itself (creating one dashboard
+  session). It never prints the token. For a local service it talks only to
+  `127.0.0.1:<port>`; for a remote placement it talks to the service's own `https` origin
+  named in the descriptor (`--ca-file` and `--connect` only change which CA it trusts and
+  which address it dials, for tests).
 - The service kits create the service token (0600) and the instance lock in the
-  service's own data directory, and write a launchd plist and a descriptor only when an
-  installer calls them. The token is readable by any process of the same user; the
-  protocol defends against web pages and mistakes, not against hostile local code.
+  service's own data directory, and write supervisor files only when an installer calls
+  them: a launchd plist in `~/Library/LaunchAgents` (macOS), a systemd user unit (Linux) or
+  a per-user Scheduled Task (Windows), plus one descriptor in the services directory. The
+  token is readable by any process of the same user; the protocol defends against web pages
+  and mistakes, not against hostile local code.
+- The kits' connectors (`fabric_http`, `fabric_openrouter` and their Node twins) reach the
+  external APIs the service's author configures, such as OpenRouter, with keys the service
+  reads by name at run time; the kit itself calls no outside host on its own. A board
+  responder talks only to Fabric's hub on loopback.
+- The working-with-fabric session hooks run as the person: Stop and SessionEnd run `git`
+  in the session's folder (counts only, at most 1.5 s), read the process table to tell a
+  session Fabric launched, write their spool and log under the user's cache folder (0600),
+  and the delivery worker starts `fabric-mcp` in its own process group and ends that group
+  (`killpg`, or `taskkill /T /F` on Windows) at its 10 s deadline. They read no token.
+- `adapting-projects-to-fabric/scripts/adapt_project.py` reads the target project without
+  executing it and writes only the seven documented bundle paths (`scaffold --dry-run`
+  writes nothing); `check --contract` runs the contract checkout's own
+  `node_modules/.bin/tsx` and installs nothing. `fabric_provider.py write` writes one
+  entry (0600) in the providers directory.

package/bin/fabric-agent-adapter.js

@@ -6,8 +6,9 @@
  * ~/.agents/skills/<name> (read by Codex, Cursor, Gemini, OpenCode and others).
  * Claude Code gets the skills through the plugin, never through a plain copy:
  * a copy in ~/.claude/skills shadows the plugin and serves its frozen version
- * forever. Idempotent; an existing install is skipped unless --force.
- * Zero dependencies.
+ * forever. Idempotent; an existing install is skipped unless --force. Each skill is
+ * copied into a sibling temporary folder and renamed into place, so a failure
+ * leaves the old copy or nothing, never half of each. Zero dependencies.
  */
 'use strict';
 
@@ -46,9 +47,13 @@ Every PassionCode.ai skill for every agent at once:
   npx @passioncode-ai/passioncode@latest update`);
 }
 
+// Bytecode a checkout's own runs left behind is not part of a skill.
+function bytecode(name) { return name === '__pycache__' || name.endsWith('.pyc'); }
+
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (bytecode(entry.name)) continue;
     const s = path.join(src, entry.name);
     const d = path.join(dest, entry.name);
     if (entry.isDirectory()) copyDir(s, d);
@@ -56,6 +61,54 @@ function copyDir(src, dest) {
   }
 }
 
+// The same files with the same bytes: what "already installed" means.
+function sameTree(src, dest) {
+  let a;
+  let b;
+  try {
+    a = fs.readdirSync(src, { withFileTypes: true }).filter((e) => !bytecode(e.name));
+    // The same filter on both sides: an installed skill whose Python ran has its own __pycache__.
+    b = fs.readdirSync(dest, { withFileTypes: true }).filter((e) => !bytecode(e.name));
+  } catch {
+    return false;
+  }
+  if (a.length !== b.length) return false;
+  const there = new Map(b.map((e) => [e.name, e]));
+  return a.every((e) => {
+    const d = there.get(e.name);
+    if (!d || e.isDirectory() !== d.isDirectory() || d.isSymbolicLink()) return false;
+    const s = path.join(src, e.name);
+    const t = path.join(dest, e.name);
+    if (e.isDirectory()) return sameTree(s, t);
+    try { return fs.readFileSync(s).equals(fs.readFileSync(t)); } catch { return false; }
+  });
+}
+
+// Copy beside, then rename over: the old copy stays until the new one is whole.
+function installSkill(src, dest) {
+  const stamp = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+  const temp = path.join(path.dirname(dest), `.${path.basename(dest)}.installing-${stamp}`);
+  const old = path.join(path.dirname(dest), `.${path.basename(dest)}.replaced-${stamp}`);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  try {
+    copyDir(src, temp);
+    if (fs.existsSync(dest)) {
+      fs.renameSync(dest, old);
+      try {
+        fs.renameSync(temp, dest);
+      } catch (err) {
+        fs.renameSync(old, dest);
+        throw err;
+      }
+      fs.rmSync(old, { recursive: true, force: true });
+    } else {
+      fs.renameSync(temp, dest);
+    }
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+}
+
 // A link in the hub belongs to whoever made it: 'launcher' for the PassionCode launcher's
 // ~/.passioncode/... links, 'other' for any other link, null for a directory or nothing.
 function linkOwner(dest) {
@@ -144,6 +197,7 @@ function main(argv) {
   }
 
   const destRoot = target === 'claude' ? path.join(home, '.claude', 'skills') : path.join(home, '.agents', 'skills');
+  const failed = [];
   for (const name of names) {
     const dest = path.join(destRoot, name);
     const owner = linkOwner(dest);
@@ -155,13 +209,24 @@ function main(argv) {
         : `skip: ${name} at ${dest} is a link managed elsewhere; remove the link first to install a copy here`);
       continue;
     }
+    const src = path.join(skillRoot, name);
     if (fs.existsSync(dest) && !force) {
-      console.log(`skip: ${name} already installed at ${dest} (rerun with --force to overwrite)`);
+      console.log(sameTree(src, dest)
+        ? `up to date: ${name} at ${dest}`
+        : `skip: ${name} at ${dest} differs from this version (rerun with --force to replace it)`);
       continue;
     }
-    fs.rmSync(dest, { recursive: true, force: true });
-    copyDir(path.join(skillRoot, name), dest);
-    console.log(`Installed ${name} -> ${dest}`);
+    try {
+      installSkill(src, dest);
+      console.log(`Installed ${name} -> ${dest}`);
+    } catch (err) {
+      failed.push(name);
+      console.error(`error: ${name} was not installed (${err.code || 'error'}: ${err.message}); ${fs.existsSync(dest) ? 'the copy that was there is unchanged' : 'nothing was left at ' + dest}`);
+    }
+  }
+  if (failed.length) {
+    console.error(`error: ${failed.length} of ${names.length} skill(s) failed: ${failed.join(', ')}`);
+    return 1;
   }
   if (target === 'agents' && !hasPlugin) {
     console.log(`Claude Code reads plugins, not the hub:\n  claude plugin marketplace add ${REPO} && claude plugin install ${PLUGIN_ID}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.39.1",
+  "version": "0.41.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'"
@@ -31,7 +31,7 @@
     "url": "https://passioncode.ai/"
   },
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "keywords": [
     "fabric",

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.39.1",
+  "version": "0.41.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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

@@ -1,11 +1,11 @@
 ---
 name: adapting-projects-to-fabric
-description: Use when adapting an existing agent, MCP server, A2A peer, HTTP service, or terminal CLI to the Fabric Agent Contract (choosing MCP/A2A/local-runner, scaffolding a provider bundle, or checking Fabric compatibility); also for «подключить проект к Fabric» or «сделать агента совместимым с Fabric». NOT for building the Fabric host/orchestrator, configuring an MCP client, or a brand-new agent (that is creating-fabric-agents).
+description: Use when adapting an existing agent, MCP server, A2A peer, HTTP service, or terminal CLI to the Fabric Agent Contract (choosing MCP/A2A/local-runner, scaffolding a provider bundle, or checking Fabric compatibility); also for «подключить проект к Fabric» or «сделать агента совместимым с Fabric». NOT for building the Fabric host/orchestrator, configuring an MCP client, a brand-new agent (creating-fabric-agents), running an agent as a local or online Fabric service with a dashboard (building-fabric-services), or a coding session working through Fabric, its board or claims, «подключись к Fabric» (working-with-fabric).
 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.39.1"
+  version: "0.41.0"
   contract-version: "0.1.0"
   contract-commit: "c55f2d5a11c9a0197e958e87212fca7ae1154769"
 ---
@@ -25,7 +25,11 @@ Use this skill to adapt or assess a provider project. Do not use it to:
 - answer wire-level MCP or A2A questions (transports, sessions, auth handshakes, task
   states on the wire): that is `agent-interop` (agent-stack); the pinned contract stays
   normative for what Fabric requires;
-- design a new agent from scratch: that is the sibling skill creating-fabric-agents;
+- design a new agent from scratch: that is the sibling skill `creating-fabric-agents`;
+- run the agent as a resident service with a dashboard, a descriptor and launchd: that is
+  `building-fabric-services`;
+- work in a project through Fabric from a coding session (registering `fabric-mcp`, the board,
+  claims): that is `working-with-fabric`;
 - claim admission merely because generated files or a valid manifest exist.
 
 If the project has only a browser interface and no stable API, MCP/A2A surface, or CLI,
@@ -57,7 +61,9 @@ python3 <skill-dir>/scripts/adapt_project.py inspect <project-root> --json
 ```
 
 The inspector samples repository files but does not execute the project. Verify its
-evidence manually. Existing runtime documentation and code outrank filename heuristics.
+evidence manually. Existing runtime documentation and code outrank filename heuristics. A
+client configuration (`.mcp.json`, an `mcpServers` block) lists servers the project calls, not one
+it serves: inspect reports it as `mcp-client-config` and asks instead of choosing `mcp`.
 
 If the inspector returns `undetermined`, answer its lifecycle question before creating
 files. A repository can expose multiple surfaces; choose a profile per capability, not
@@ -110,12 +116,18 @@ target paths. It refuses any collision.
 `charge`, `delete`, `merge`, `deploy`, `change-policy`), read from what the code does or asked of the author. Choose
 `--idempotency required|supported|none` for an external effect on purpose. When a run's cost varies, give the
 launcher fixed options (DEC-0037): `--cost-preset ID MAX_USD LABEL` per option and `--default-cost-preset ID`; the
-amounts come from the author or measured runs, never invented. Do not use `--force` unless the user explicitly
-authorizes replacement after the exact conflicting files and diff are shown.
+amounts come from the author or measured runs, never invented. Pass what the author knows so it is not written as a
+scaffold default: `--data-class` (repeat), `--created-by URI`, `--identity-method`, `--probe-assertion` (repeat).
 
-The generated zero hash, `.invalid` endpoints, `replace-me` values, generic schemas, and
-assertions are deliberate blockers. Replace them with implementation-backed facts. A
-template that still contains one is not ready for admission.
+On a collision run `scaffold --dry-run` first: it writes nothing and prints the planned writes and a unified diff of
+each existing file. Use `--force` only when the user authorizes replacing exactly those files.
+
+Every value the scaffold invents is a sentinel that `check` names: the zero hash, `.invalid` endpoints,
+`replace-me` values, `urn:fabric:adapter:author`, the generic schemas (marked `fabric-adapter-template`), the
+generic fixture and assertions, and each value listed under the manifest's `urn:fabric:adapter:template`
+extension (the defaulted `dataClasses`, a defaulted `tls` identity method). Replace each with an
+implementation-backed fact, then remove it from that list and the block when it is empty. While one remains,
+`readyForAdmission` is false.
 
 ### 4. Implement the adapter seam
 
@@ -138,11 +150,14 @@ Treat all provider output as untrusted until schemas and semantic assertions pas
 
 ### 4b. Announce an agent that is not a service
 
-An agent Fabric reaches as a CLI or a stdio MCP server gets a provider entry, written by
-its installer with [`scripts/fabric_provider.py`](scripts/fabric_provider.py) and removed
-by its uninstaller: argv arrays only, env values as `secret-ref:` references, never the
-id of an existing service, and a `providerId` equal to the manifest's `provider.id`. Load [provider entries](references/provider-entry.md). An
-agent that runs as a service uses a descriptor instead (`building-fabric-services`).
+An agent Fabric reaches as a stdio MCP server, or as an MCP server on a loopback URL that is not
+a service, gets a provider entry, written by its installer with
+[`scripts/fabric_provider.py`](scripts/fabric_provider.py) and removed by its uninstaller: argv
+arrays only, env values as `secret-ref:` references, never the id of an existing service, and a
+`providerId` equal to the manifest's `provider.id`. Load [provider entries](references/provider-entry.md).
+A provider entry only describes an MCP server: a CLI that does not speak MCP gets no entry; it is
+announced by its `local-runner` manifest (step 3). An agent that runs as a service uses a
+descriptor instead (`building-fabric-services`).
 
 ### 5. Make probes safe and meaningful
 
@@ -195,58 +210,25 @@ Update `fabric/FABRIC-CONFORMANCE.md` with dated receipts for:
 
 Include commands and exit codes, immutable endpoint or artifact identities, and explicit
 unverified surfaces. If live Fabric admission/runtime does not yet exist, the last gates
-remain `NOT VERIFIED`; the completed deliverable is an adaptation-ready provider bundle,
+remain `NOT_VERIFIED`; the completed deliverable is an adaptation-ready provider bundle,
 not a connected provider.
 
 ### 8. Propose the operator channel
 
 If the agent has a human stop (a choice, an approval, a confirmation) or emits `notify: true`
-events, propose its **operator channel** to the operator once, now. The channel is the agent's
-own messenger channel, first Telegram, that sends those events and answers its stops with
-buttons: `fabric-operator-channel/0.1` (contract DEC-0034,
-`docs/specification/operator-channel.md`), whose rule OC-11 this step follows. Give the
-operator's four steps:
-
-1. create a bot with @BotFather;
-2. put its token into the operator's secret store under the name the agent reads (for example
-   `EXAMPLE_AGENT_TELEGRAM_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.
-
-In a group shared with other bots the channel follows OC-14…OC-17 (DEC-0035): it stays silent
-unless addressed (`/command@ThisBot`, a reply to its own message or a press of its own button; a
-bare `/command` in a group is not addressed), and a channel nobody receives on is `degraded`
-(`receiver-missing`). Say so in the proposal when the operator means to bind a shared group.
-
-Record the answer (`accepted`, `declined` or `later`) in the agent's state and the
-conformance report, and do not ask again; an agent that serves `surfaces.operatorChannel` also
-shows it as `proposal` in its status document. Creating the bot, storing the token and enabling the
-channel are the operator's action: never create the bot, ask for or store the token's value, or
-enable the channel yourself. The default pin carries DEC-0034 and DEC-0035: a served status document is checked
-against the pinned `schemas/operator-channel-status.schema.json`; the channel's runtime rules have
-no probe rule here yet, so report them `NOT_RUN`. An agent with neither stops nor notify
-events skips this step.
+events, propose its operator channel (`fabric-operator-channel/0.1`, OC-11) to the operator once,
+now, as [the operator channel and the repository standard](references/operator-channel-and-repository.md)
+describes: the operator's four steps, the answer recorded and never asked again, and the bot, the
+token and enabling the channel left to the operator. An agent with neither stops nor notify events
+skips this step.
 
 ## The repository around the provider
 
 **For a PassionCode.ai repository**, the adapted project's repository follows the organization's
-[repository standard](https://github.com/passioncode-ai/fabric-workspace/blob/main/knowledge/repository-standard.md) (`knowledge/repository-standard.md`
-in the organization's knowledge base; a clone has it at `fabric-workspace/knowledge/`) from its
-first commit:
-
-- `LICENSE`, `COMMERCIAL-LICENSE.md` and `CLA.md` copied byte for byte from the knowledge base's
-  `templates/`, and `AGPL-3.0-only OR LicenseRef-PassionCode-Commercial` in every manifest and
-  every SKILL.md `license:`; `SECURITY.md` when the repository is public;
-- a README whose first heading is the full name, with `## Quick start for a new teammate`
-  (Install; Configure, key names only; MCP, the registration command and one proving tool call,
-  verified with a real client in a temporary config; Develop) and `## License`;
-- an `AGENTS.md` that opens with the template's *Read first* block and closes with *After work*,
-  and a `CLAUDE.md` whose first line is `@AGENTS.md`.
-
-org-index `scripts/check_format.py` reports 0 findings for it before it is called done. **An agent
-someone builds for themselves is not a PassionCode.ai repository:** its licence is its owner's
-choice, nothing about it is published or listed by the organization, and none of these files is
-required of it, though the verified MCP quick start is still how anyone learns to drive it.
+repository standard (`knowledge/repository-standard.md`) from its first commit: the licence files,
+the README quick start verified with a real client, `AGENTS.md` and `CLAUDE.md`, listed in the
+shared reference above. An agent someone builds for themselves is not a PassionCode.ai repository:
+its licence is its owner's choice and none of those files is required of it.
 
 ## Completion format
 
@@ -265,12 +247,6 @@ passed against a real provider and the project binding is valid.
 
 ## Dashboard handoff: also for consumers
 
-When handing a registered service dashboard to a person, or writing the generated
-agent's completion/notification instructions, read and apply
-[dashboard links](references/dashboard-links.md): use the host's `open_link`,
-check the target device and host, and run the bundled output gate before delivery.
-An installed host failure never means browser fallback. This applies in Claude
-Code, Codex and other providers; it needs no host-specific hook. MCP unavailable:
-report the unresolved capability or use an approved project resolver; no automatic
-client configuration. Python unavailable: perform the reference's manual checks
-and report the executable gate NOT_RUN. Headless agents need no dashboard.
+When handing a registered service dashboard to a person, or writing the generated agent's
+completion or notification instructions, read and apply [dashboard links](references/dashboard-links.md)
+and run its output gate before delivery, in any host. Headless agents need no dashboard.