@passioncode-ai/fabric-agent-adapter 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.18.0 - 2026-10-12
+
+Services on Linux and Windows in both kits (contract DEC-0032, DEC-0033; FAA-21): the supervisor files the
+contract names, and the Node kit on Windows.
+
+### Added
+
+- **The supervisor writers, in both kits.** They write byte-identical files, and a test holds them to that.
+  - **Linux — a systemd user unit.** `systemd_unit` / `systemdUnit` writes `Restart=always`, `RestartSec=10`,
+    `TimeoutStopSec` above the drain, `WantedBy=default.target` and `FABRIC_SERVICE_SUPERVISOR=systemd`.
+    `systemd_install` / `systemdInstall` runs `daemon-reload` and `enable --now`. `systemd_uninstall` /
+    `systemdUninstall` runs `disable --now`, removes the unit, then runs `daemon-reload`.
+  - **Windows — a per-user Scheduled Task.** `task_xml` / `taskXml` writes a logon trigger, least privilege,
+    restart every minute on failure, no time limit and `IgnoreNew`. `task_install` / `taskInstall` runs
+    `schtasks /Create` from a UTF-16 file it then removes, then `/Run`. `task_uninstall` / `taskUninstall` runs
+    `/End`, then `/Delete`.
+  - **No secret in a supervisor file.** The writers refuse a credential-shaped argument, environment name or
+    value, and any control character.
+  - **An upgrade restarts what runs; the operator's off stays off (LC-14).** A unit that `is-enabled` reports
+    disabled, or a task whose settings say `Enabled false`, is rewritten and left off unless `force_enable`.
+  - **Checked by the real readers:** `systemd-analyze verify` on the Linux job (a quoted `WorkingDirectory=` is
+    refused there, so it is written unquoted), and `schtasks /Create` of a throwaway task on the Windows job.
+- **The Node kit on Windows and Linux:**
+  - `servicesDir` and `serviceDirs` use `%LOCALAPPDATA%`.
+  - `expand` and `validateDescriptor` match the Python kit: all four managers, `unit` and `task` paired with
+    their manager, Windows paths, never a network share.
+  - The token file gets a protected ACL: written with `icacls`, read with Windows PowerShell 5.1. A refusal
+    names the SID.
+  - The instance lock is a named pipe on Windows (an abstract socket on Linux, as before).
+- **One copy across the kits.** The Python kit holds the Node kit's lock name (`lock_name` / `lockName`)
+  beside its file lock, so the two kits exclude each other on every system. `check_service.py` now reports the
+  lock as held when a Node service holds it. Before this release it failed every Node service on Linux.
+- **A copy under systemd backs off on a held lock** as one under launchd does (`supervised()`).
+- **The Windows CI job** runs the Node kit's platform, supervisor and service tests and the Python supervisor
+  tests.
+- **Docs:**
+  - `references/lifecycle.md`, *Linux and Windows*: the verbs per system and the Windows directories.
+  - `SKILL.md` step 4.
+  - `protocol.md`.
+
+  The scenario eval `linux-and-windows-supervision` and two triggers came first.
+- **The probe only looks** (`/proc/net/unix`, `WaitNamedPipeW`) and never takes the lock's name.
+- **An independent review** found 2 critical and 9 moderate defects before release; each is fixed with a test, except
+  that a Scheduled Task still cannot tell the service it is supervised (a task sets no environment; documented).
+- **Mutation testing:** 14 planted defects in the Python writers, 23 in the Node port, 7 in the lock name
+  and probe and a quoted `WorkingDirectory=` against `systemd-analyze` were all caught.
+
+## 0.17.0 - 2026-10-12
+
+The organisation's lifecycle rules LC-19 and LC-21 apply to what the adapter ships and checks (FAA-22, FAA-23):
+no plugin starts a stdio MCP server in every session, and no credential travels in argv or a URL query.
+
+### Added
+
+- **`adapt_project.py check`** refuses:
+  - **LC-19:** a Claude Code plugin in the project that declares a stdio MCP server, whether in its `.mcp.json` or in
+    `plugin.json` `mcpServers`, because it starts in every session that enables the plugin. An HTTP entry to a
+    resident service passes.
+  - **LC-21:** a launch argument or a URL that carries a credential, in the manifest's connections and in the plugin
+    servers' argv, URL and env.
+
+  `scaffold` refuses a runtime argument that carries a credential.
+- **`fabric_provider.py`** refuses a credential in `run.mcp.stdio.command` (LC-21, FAC-SEM-057). The key goes in
+  `env` as a secret reference.
+- **`test/validate.py` gate:** the adapter's own plugin declares no MCP server and no hook command carries a
+  credential.
+- The detector is the contract's (`fabric_secrets`, 0.16.0). The adapting skill carries an identical copy, so it
+  works installed alone, and a test keeps the two copies byte-identical.
+- Docs: the adapting skill's check step, `provider-entry.md`, and `surfaces-and-auth.md` (an HTTP registration
+  starts nothing per session). The scenario eval `plugin-and-argv-hygiene` came first. Five planted defects were
+  each caught.
+
 ## 0.16.0 - 2026-10-12
 
 Runner and model profiles in both kits (contract DEC-0046, Fabric ADR-0147; FAA-19). The contract's credential

package/README.md

@@ -230,8 +230,8 @@ FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/curren
 ```
 
 Without both environment variables, those tests explicitly skip as `NOT_RUN`.
-This source checkout is 0.16.0. 0.15.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
-were never released); 0.16.0 is published by its `v0.16.0` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.18.0. 0.17.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
+were never released); 0.18.0 is published by its `v0.18.0` tag. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/package.json

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

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

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.16.0"
+  version: "0.18.0"
   contract-version: "0.1.0"
   contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
 ---
@@ -173,6 +173,12 @@ python3 <skill-dir>/scripts/adapt_project.py check <project-root> \
   --contract /path/to/fabric-agent-contract --json
 ```
 
+The local check also refuses two lifecycle faults (LC-19, LC-21): a Claude Code plugin in
+the project that declares a stdio MCP server — it starts in every session that enables the
+plugin; serve it over HTTP from one resident process or register it at project scope — and a
+credential in a launch argument or a URL query, where every process and every log can read it.
+Fix both at their cause; never weaken the check.
+
 Load [verification](references/verification.md) before interpreting or publishing the
 result. Fix every local error. Fix every placeholder warning or record why the bundle is
 still a draft. Do not convert `NOT_RUN` or `NOT_VERIFIED` to `PASS` without the named

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/provider-entry.md

@@ -35,7 +35,8 @@ python3 scripts/fabric_provider.py remove example-agent      # the uninstaller
 `--stdio` takes the rest of the line as the argument array; there is no shell string. An entry may carry
 `run.mcp.stdio.scope` (DEC-0044): `project` (started for the sessions of a project that binds it) or `on-demand`;
 `session` — a server in every coding session — is refused (FAC-SEM-056, LC-19). The validator accepts the field; the
-writer does not set it until Fabric reads it.
+writer does not set it until Fabric reads it. An argument that carries a credential is refused
+(LC-21, FAC-SEM-057): a key goes in `env` as a `secret-ref:<name>`, never in argv.
 
 It refuses, with one sentence that never quotes a value:
 

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

@@ -15,6 +15,9 @@ import sys
 from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
 from urllib.parse import urlparse
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_secrets as _secrets  # noqa: E402 - the contract's credential detector (DEC-0044, LC-21), beside this file
+
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
@@ -230,6 +233,8 @@ def _generated_files(args: argparse.Namespace) -> Dict[str, str]:
         lowered = runtime_arg.lower().replace("_", "").replace("-", "")
         if any(term in lowered for term in ("password", "apikey", "accesstoken", "clientsecret")):
             raise AdaptationError("runtime arguments must not contain secret-like values or names")
+        if _secrets.secret_argument(runtime_arg):
+            raise AdaptationError("a runtime argument carries a credential; argv is visible to every process (LC-21): read it from a secret reference instead")
 
     created_at = dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
     manifest = {
@@ -465,6 +470,58 @@ import {SCHEMA_PREFIX} from './src/contract.ts';
     return "PASS", ["manifest validated by selected contract schema at %s" % selected_commit]
 
 
+def _credential_problems(manifest: Dict[str, Any]) -> List[str]:
+    """LC-21 (FAA-23): no credential in a launch argument or in a URL the manifest names."""
+    problems: List[str] = []
+    for index, capability in enumerate(manifest.get("capabilities") or []):
+        connection = ((capability or {}).get("profile") or {}).get("connection") if isinstance(capability, dict) else None
+        if not isinstance(connection, dict):
+            continue
+        for arg in connection.get("args") or []:
+            if isinstance(arg, str) and _secrets.secret_argument(arg):
+                problems.append("LC-21: capability[%d] passes a credential in a launch argument; argv is visible to every process" % index)
+        for field in ("url", "agentCardUrl"):
+            if isinstance(connection.get(field), str) and _secrets.secret_url(connection[field]):
+                problems.append("LC-21: capability[%d].%s carries a credential in the URL; a query lands in every log" % (index, field))
+    return problems
+
+
+_PLUGIN_SKIP = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", ".worktrees"}
+
+
+def _plugin_problems(root: Path) -> List[str]:
+    """LC-19 (FAA-22) and LC-21 for the Claude Code plugins in the project: a plugin's stdio MCP server starts in
+    every session that enables the plugin; serve it over HTTP from one resident process, or register it at project
+    scope instead. No server entry carries a credential in its argv, URL or env."""
+    problems: List[str] = []
+    for top, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in _PLUGIN_SKIP]
+        here = Path(top)
+        if here.name != ".claude-plugin" or "plugin.json" not in files:
+            continue
+        plugin = here.parent
+        name = plugin.relative_to(root).as_posix() or "."
+        servers: Dict[str, Any] = {}
+        for source in (here / "plugin.json", plugin / ".mcp.json"):
+            try:
+                doc = json.loads(source.read_text(encoding="utf-8")) if source.is_file() else {}
+            except (OSError, ValueError):
+                continue
+            block = doc.get("mcpServers") if isinstance(doc, dict) else None
+            if isinstance(block, dict):
+                servers.update({k: v for k, v in block.items() if isinstance(v, dict)})
+        for server, entry in sorted(servers.items()):
+            if "command" in entry:
+                problems.append("LC-19: plugin %s declares the stdio MCP server %s, which starts in every session that enables the plugin; serve it over HTTP from one resident process or register it at project scope" % (name, server))
+            argv = [entry.get("command")] + list(entry.get("args") or [])
+            if any(isinstance(a, str) and _secrets.secret_argument(a) for a in argv) or (isinstance(entry.get("url"), str) and _secrets.secret_url(entry["url"])):
+                problems.append("LC-21: plugin %s's MCP server %s carries a credential in its argv or URL" % (name, server))
+            env = entry.get("env") if isinstance(entry.get("env"), dict) else {}
+            if any(isinstance(v, str) and _secrets.secret_value(v) for v in env.values()):
+                problems.append("LC-21: plugin %s's MCP server %s writes a credential value in env; reference it instead" % (name, server))
+    return problems
+
+
 def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
     errors: List[str] = []
     warnings: List[str] = []
@@ -534,6 +591,7 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
                 errors.append("secret-like field is forbidden in manifest: %s" % key)
             if isinstance(value, str) and ("replace-me" in value or ".invalid" in value):
                 warnings.append("placeholder:%s" % key)
+        errors.extend(_credential_problems(manifest))
         provider = manifest.get("provider")
         if isinstance(provider, dict) and provider.get("contentHash") == "sha256:" + ("0" * 64):
             warnings.append("placeholder:provider.contentHash")
@@ -545,6 +603,7 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
     elif contract is not None and manifest_path.is_file():
         shape_status, shape_receipts = _contract_shape(manifest_path, contract, lock["commit"])
 
+    errors.extend(_plugin_problems(root))
     local_status = "PASS" if not errors else "FAIL"
     ready = local_status == "PASS" and shape_status == "PASS" and not warnings
     return {

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

@@ -29,6 +29,9 @@ import sys
 import tempfile
 from typing import Any, Dict, List, Optional
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_secrets as _secrets  # noqa: E402 - the contract's credential detector (DEC-0044, LC-21), beside this file
+
 PROTOCOL = "fabric-provider/0.1"
 _ID = re.compile(r"^[a-z][a-z0-9-]{1,62}$")
 _ENV_NAME = re.compile(r"^[A-Z_][A-Z0-9_]*$")
@@ -124,6 +127,8 @@ def _run_problems(run: Any) -> List[str]:
     command = stdio["command"]
     if not isinstance(command, list) or not 1 <= len(command) <= 32 or not all(isinstance(a, str) and a for a in command):
         problems.append("run.mcp.stdio.command is an argument array, never a shell string")
+    elif any(_secrets.secret_argument(a) for a in command):
+        problems.append("run.mcp.stdio.command carries a credential in an argument; argv is visible to every process (LC-21, FAC-SEM-057): pass it as a secret reference in env")
     env = stdio.get("env", {})
     if not isinstance(env, dict):
         return problems + ["run.mcp.stdio.env is an object"]

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""The contract's one credential detector (Fabric Agent Contract DEC-0044, `src/secret-shape.ts` at the pin): a name
+that can only carry a credential, a value shaped like one, a launch argument that carries one, and a URL that does
+(LC-21). A port held to the contract's own answers by test/fixtures/contract/profile-vectors.json. Standard library
+only. The dashboard kit's fabric-button.js carries its own copy of the name and value checks (FL-4)."""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List
+import urllib.parse
+
+CREDENTIAL_WORDS = (
+    "token", "secret", "password", "passwd", "pass", "passphrase", "credential", "credentials", "cookie", "authorization",
+    "bearer", "jwt", "otp", "apikey", "signature", "sig",
+    "accesstoken", "idtoken", "authtoken", "refreshtoken", "sessionid", "sessiontoken", "logincode", "authcode", "privatekey",
+    "clientsecret", "secretkey", "accesskey",
+)
+CREDENTIAL_PAIRS: Dict[str, tuple] = {
+    "key": ("private", "api", "access", "secret", "session", "auth", "signing", "encryption", "master", "client", "login", "refresh"),
+    "auth": ("token", "code", "header"),
+    "session": ("token", "id"),
+    "code": ("login", "auth", "access", "session"),
+}
+JWT_SHAPE = re.compile(r"eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*")
+SECRET_VALUE = re.compile(r"(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})",
+                          re.IGNORECASE | re.DOTALL)
+_LONG_RUN = re.compile(r"[A-Za-z0-9+/=_-]{40,}")
+_BEARER_INSIDE = re.compile(r"\bbearer\s+(?=[A-Za-z0-9._~+/-]*\d)[A-Za-z0-9._~+/-]{12,}=*", re.IGNORECASE)
+_PATH_LIKE = re.compile(r"^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*://)", re.IGNORECASE)
+_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
+
+def name_words(name: str) -> List[str]:
+    """A name's words: split at `.`, `_`, `-` and camelCase humps, lowercased (`APIKey` is `api key`)."""
+    spaced = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", name)
+    spaced = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1 \2", spaced)
+    return [w.lower() for w in re.split(r"[\s._-]+", spaced) if w]
+
+
+def _with_singulars(words: List[str]) -> List[str]:
+    return words + [w[:-1] for w in words if len(w) > 2 and w.endswith("s")]
+
+
+def credential_name(name: str) -> bool:
+    """Whether a name — a parameter, a header, an environment variable, a config key — can only carry a credential."""
+    split = name_words(name)
+    words = _with_singulars(split)
+    if any(w in CREDENTIAL_WORDS for w in words):
+        return True
+    if len(split) == 1 and any(w in CREDENTIAL_PAIRS for w in words):
+        return True
+    return any(word in words and any(p in words for p in partners) for word, partners in CREDENTIAL_PAIRS.items())
+
+
+def _long_secret(value: str) -> bool:
+    return any(re.search(r"[a-z]", run) and re.search(r"[A-Z]", run) and re.search(r"[0-9]", run) for run in _LONG_RUN.findall(value))
+
+
+def secret_value(value: str) -> bool:
+    """A JWT anywhere, a provider key or `Bearer …`, or a long base64 run mixing upper case, lower case and digits."""
+    return bool(JWT_SHAPE.search(value) or SECRET_VALUE.search(value) or _long_secret(value))
+
+
+def _path_like(piece: str) -> bool:
+    return bool(_PATH_LIKE.match(piece)) or (
+        bool(re.search(r"[\\/]", piece))
+        and (bool(re.search(r"\.[A-Za-z0-9]{1,8}$", piece)) or any(re.fullmatch(r"[a-z][a-z0-9_-]{2,}", s) for s in re.split(r"[\\/]", piece))))
+
+
+def secret_argument(value: str) -> bool:
+    """The same for a launch argument or a server's command and URL: a long run is looked for between path separators,
+    so a folder path holding a session id is not taken for a key."""
+    if JWT_SHAPE.search(value) or SECRET_VALUE.search(value) or _BEARER_INSIDE.search(value):
+        return True
+    for piece in re.split(r"[\s=]", value):
+        if _path_like(piece):
+            if any(_long_secret(part) for part in re.split(r"[\\/]", piece)):
+                return True
+        elif _long_secret(piece):
+            return True
+    return False
+
+
+def _decode_keeping_plus(raw: str) -> str:
+    """decodeURIComponent: a malformed escape or bytes that are not UTF-8 leave the raw text."""
+    if re.search(r"%(?![0-9A-Fa-f]{2})", raw):
+        return raw
+    try:
+        return urllib.parse.unquote_to_bytes(raw).decode("utf-8")
+    except UnicodeDecodeError:
+        return raw
+
+
+def _form_name(text: str) -> str:
+    pairs = urllib.parse.parse_qsl(text, keep_blank_values=True)
+    return pairs[0][0] if pairs else ""
+
+
+def raw_values(query: str) -> Dict[str, List[str]]:
+    """Each query or fragment piece's raw value by its decoded name, with `+` kept."""
+    values: Dict[str, List[str]] = {}
+    for piece in query.split("&"):
+        if piece == "":
+            continue
+        at = piece.find("=")
+        name = _form_name(piece if at < 0 else piece[:at])
+        values.setdefault(name, []).append("" if at < 0 else _decode_keeping_plus(piece[at + 1:]))
+    return values
+
+
+def secret_url(value: str) -> bool:
+    """Whether a URL an MCP entry or a launch names carries a credential (LC-21): anything secret_argument finds, a
+    password in its user information, or a query or fragment parameter whose name can only carry a credential and has
+    a value, or whose value is shaped like one. A string that is not an absolute URL is checked as an argument only."""
+    if secret_argument(value):
+        return True
+    if not _SCHEME.match(value.strip()):
+        return False  # not an absolute URL (WHATWG URL parsing refuses it)
+    try:
+        parts = urllib.parse.urlsplit(value.strip())
+    except ValueError:
+        return False
+    if not parts.scheme:
+        return False
+    if parts.password:
+        return True
+    for part in (parts.query, parts.fragment):
+        for name, raws in raw_values(part).items():
+            if any((raw != "" and credential_name(name)) or secret_value(raw) for raw in raws):
+                return True
+    return False

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

@@ -13,10 +13,10 @@ description: >-
   kits, a TLS sample, live and layout probes. NOT for a one-off script or cron job, a hosted product with no agent
   behind it, the provider manifest (adapting-projects-to-fabric), or building Fabric Dashboards.
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
-compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only (Linux services use lifecycle manager none until a systemd adapter exists). Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
+compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.16.0"
+  version: "0.18.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
@@ -190,10 +190,14 @@ The installer, not the service, owns the plist and the descriptor. Sequence:
 4. After an upgrade, `prune_releases(releases_dir, current=…)` keeps the running release
    and the one before it.
 
+On Linux the supervisor is a systemd user unit (`systemd_unit` + `systemd_install`), on
+Windows a per-user Scheduled Task (`task_xml` + `task_install`); the Node kit has the same
+writers (`systemdUnit`, `taskXml`, …) and both kits write identical files.
+
 Code runs from an immutable release directory; an upgrade writes a new release,
 rewrites the plist and restarts. Read [the lifecycle reference](references/lifecycle.md)
 for the plist fields, the release layout, log rotation, behaving under a host lifecycle broker
-and the Linux case.
+and the Linux and Windows supervisors.
 
 ## Step 5 — the dashboard and the events
 

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

@@ -8,23 +8,23 @@ wins and this page is the defect. The rule each section serves:
 | Contract rule | Here | Kit (Python / Node) |
 |---|---|---|
 | LC-01 quit reaches exit within a deadline | [Shutdown](#shutdown) | `Drain` / `Drain` |
-| LC-03 a job is bounded and exclusive | [one copy under launchd](#one-copy-under-launchd) | `hold_single_instance` / `holdSingleInstance` |
-| LC-09 the footprint is declared | the descriptor and the plist; the service's own `AGENTS.md` names its label and port | `write_descriptor`, `launchd_plist` |
+| LC-03 a job is bounded and exclusive | [one copy under a supervisor](#one-copy-under-a-supervisor) | `hold_single_instance` / `holdSingleInstance` |
+| LC-09 the footprint is declared | the descriptor and the plist, unit or task; the service's own `AGENTS.md` names its label (unit, task) and port | `write_descriptor`, `launchd_plist`, `systemd_unit` / `systemdUnit`, `task_xml` / `taskXml` |
 | LC-11 previous release kept, older pruned | [Install, upgrade, uninstall](#install-upgrade-uninstall) | `prune_releases` / `pruneReleases` |
 | LC-12 every file is bounded | [Logs](#logs) | `RotatingLog`, `cap_stdout_log` / `RotatingLog`, `capStdoutLog` |
-| LC-14 operator intent wins; uninstall is symmetric | [Install, upgrade, uninstall](#install-upgrade-uninstall) | `launchd_install`, `launchd_uninstall` (Python) |
+| LC-14 operator intent wins; uninstall is symmetric | [Install, upgrade, uninstall](#install-upgrade-uninstall), [Linux and Windows](#linux-and-windows) | `launchd_install`, `launchd_uninstall` (Python); `systemd_install` / `systemdInstall`, `task_install` / `taskInstall` and their uninstalls |
 | LC-15 builds clean up after themselves | release pruning runs inside the installer, not later | `prune_releases` / `pruneReleases` |
 
 ## Contents
 
 - [launchd plist](#launchd-plist-generate-it-with-launchd_plist)
 - [Install, upgrade, uninstall](#install-upgrade-uninstall)
-- [One copy under launchd](#one-copy-under-launchd)
+- [One copy under a supervisor](#one-copy-under-a-supervisor)
 - [Directories](#directories)
 - [Logs](#logs)
 - [Shutdown](#shutdown)
 - [Being managed by a host lifecycle broker](#being-managed-by-a-host-lifecycle-broker)
-- [Linux](#linux)
+- [Linux and Windows](#linux-and-windows)
 
 ## launchd plist (generate it with `launchd_plist`)
 
@@ -70,24 +70,24 @@ that deletes an override, and a leftover `disabled` would make a later fresh ins
 off. Tests use a throwaway label or a fake `launchctl` first on `PATH` — never the
 operator's real jobs.
 
-## One copy under launchd
+## One copy under a supervisor
 
 Started by hand, a copy that finds `service.lock` held prints one sentence naming the
 holder and exits 75 at once. Under launchd that exit is a respawn every `ThrottleInterval`
-(10 s), forever. So a copy whose plist carries `FABRIC_SERVICE_SUPERVISOR=launchd` backs
-off in-process — 0.5 s doubling to 30 s, 300 s in all — takes over if the holder leaves,
+(10 s), forever, and under systemd one every `RestartSec`. So a copy whose plist or unit
+carries `FABRIC_SERVICE_SUPERVISOR=launchd` (or `systemd`) backs off in-process — 0.5 s doubling to 30 s, 300 s in all — takes over if the holder leaves,
 and exits 75 only when the wait runs out: a few starts an hour instead of 360. It touches
 nothing while it waits. Two installs sharing one data directory are still the defect to
 remove; the back-off only stops the loop from costing the machine.
 
 ## Directories
 
-| What | macOS | Linux |
-|---|---|---|
-| data + config | `~/Library/Application Support/<id>/` | `${XDG_DATA_HOME:-~/.local/share}/<id>/` |
-| logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` |
-| cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` |
-| code | `~/.local/share/<id>/releases/…` | same |
+| What | macOS | Linux | Windows (DEC-0032) |
+|---|---|---|---|
+| data + config | `~/Library/Application Support/<id>/` | `${XDG_DATA_HOME:-~/.local/share}/<id>/` | `%LOCALAPPDATA%\<id>\` |
+| logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` | `%LOCALAPPDATA%\<id>\Logs\` |
+| cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` | `%LOCALAPPDATA%\<id>\Cache\` |
+| code | `~/.local/share/<id>/releases/…` | same | under `%LOCALAPPDATA%` too, never a network share |
 
 A repository that versions the data itself (a registry, a plan) may hold the data; the
 service's own code checkout and its releases may not. Directories 0700, secret files 0600. A store carries a schema version and the service
@@ -140,8 +140,58 @@ has to survive being driven from outside:
   well-known document for a service, a process-level answer for a plain app — and keep it honest
   while the app is still starting.
 
-## Linux
-
-Until a systemd adapter exists, declare `lifecycle.manager: "none"`. A `systemd --user`
-unit with `Restart=always` gives the same guarantees; the host will control it once the
-adapter ships. Everything else in this skill applies unchanged.
+## Linux and Windows
+
+Both kits write and install the supervisor file the contract names (DEC-0032, service.md
+*Supervisor*); the two kits write byte-identical files. A supervisor file never carries a
+secret: the writers refuse a credential-shaped argument, environment name or value, and any
+control character (a line break would end a unit line early).
+
+**Linux — a systemd user unit.** `systemd_unit(unit, argv, working_directory=…)` /
+`systemdUnit(unit, argv, {workingDirectory})` writes `Restart=always`, `RestartSec=10`,
+`TimeoutStopSec` above the drain (15 s default), `KillMode=mixed`, `WantedBy=default.target`
+and `FABRIC_SERVICE_SUPERVISOR=systemd`, quoting every argument (`%` → `%%`, `$` → `$$`).
+`WorkingDirectory=` is written unquoted: systemd reads it as the rest of the line, so quotes would
+become part of the path and the unit would be refused (`systemd-analyze verify` checks it in CI). The
+descriptor says `"lifecycle": {"manager": "systemd", "unit": "<id>.<instance>.service"}`.
+
+| Verb | Command |
+|---|---|
+| install, upgrade | `systemd_install` / `systemdInstall`: write `~/.config/systemd/user/<unit>`, `daemon-reload`, `enable`, `restart` (so the new unit is what runs). A unit already installed that `is-enabled` reports `disabled` stays off: the file is rewritten and nothing starts (LC-14), unless `force_enable` |
+| stop, keep off | `systemctl --user disable --now <unit>` |
+| uninstall | `systemd_uninstall` / `systemdUninstall`: `disable --now`, remove the unit, `daemon-reload` |
+
+A user unit runs while the person is logged in; one that must run without a session needs
+`loginctl enable-linger <user>`, which is the operator's decision, not the installer's.
+
+**Windows — a per-user Scheduled Task.** `task_xml(task, argv, working_directory=…)` /
+`taskXml(task, argv, {workingDirectory})` writes a task with a logon trigger for the current
+user, `InteractiveToken` and `LeastPrivilege` (no administrator rights), restart on failure
+every minute, no execution time limit and `MultipleInstancesPolicy` `IgnoreNew`, its settings in the
+order `schtasks` exports them; the arguments are quoted the way the C runtime parses them. The Windows
+CI job has the real `schtasks` create, read back and delete such a task. The descriptor says
+`"lifecycle": {"manager": "task-scheduler", "task": "\\PassionCode\\<id>.<instance>"}`.
+
+| Verb | Command |
+|---|---|
+| install, upgrade | `task_install` / `taskInstall`: `schtasks /Create /TN <task> /XML <file> /F` from a UTF-16 file it then removes, then `/End` (when it existed) and `/Run`. A task already installed and disabled stays off: it is recreated and disabled again (LC-14), unless `force_enable` |
+| stop, keep off | `schtasks /End /TN <task>`, then `schtasks /Change /TN <task> /DISABLE` |
+| uninstall | `task_uninstall` / `taskUninstall`: `/End`, then `/Delete /F` |
+
+A task cannot set an environment variable, so a copy Task Scheduler restarts does not back off
+in-process; `IgnoreNew` keeps the scheduler from starting a second copy, and a hand-started copy
+holding the lock makes the scheduled one exit 75 once a minute until it leaves.
+
+**One copy on each system.** The Python kit takes `flock` (Linux) or a locked byte
+(Windows); the Node kit cannot, so it holds a name instead — an abstract unix socket on Linux,
+a named pipe on Windows (`lock_name` / `lockName`), each gone with the process. The Python kit
+holds the same name beside its file lock, so the two kits exclude each other everywhere, and
+`check_service.py` reports the lock held when either is. The probe only looks (`/proc/net/unix`,
+`WaitNamedPipeW`); it never takes the name, so it cannot make a service that is starting fail.
+
+**Token files on Windows.** The privacy of `service.token` is its ACL (service.md *Windows
+token files*): the kits write a protected list — the user, SYSTEM and Administrators, set before the
+token's bytes go in, any entry already there dropped — and refuse
+on read a link, a file outside the profile, another owner, or any other granted SID, naming the
+SID. The Node kit reads the list with Windows PowerShell 5.1 (.NET, no modules) and writes it
+with `icacls`; the path goes through the environment, never a command line.

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

@@ -31,7 +31,7 @@ File `<id>.<instance>.json`, mode 0600 (on Windows a protected ACL), atomic.
 | `name`, `summary` | ≤ 80 and ≤ 200 characters |
 | `origin` | `http://127.0.0.1:<port>`; the port is a machine-wide claim |
 | `auth` | `tokenFile` (0600; on Windows a protected ACL — owner and every granting entry the current user, SYSTEM or Administrators: service.md *Windows token files*, DEC-0032, DEC-0033); `header` default `Authorization` with `scheme` `Bearer`; any other header carries the raw token with `scheme: "none"` |
-| `lifecycle` | `manager` `launchd` (then `label` and `plist`), `systemd` (then `unit`, a `systemctl --user` unit), `task-scheduler` (then `task`, a per-user Scheduled Task) or `none`; `unit` and `task` are refused beside any other manager (DEC-0032). The Python kit and the probe accept all four; the Node kit still accepts only `launchd` and `none` (FAA-16) |
+| `lifecycle` | `manager` `launchd` (then `label` and `plist`), `systemd` (then `unit`, a `systemctl --user` unit), `task-scheduler` (then `task`, a per-user Scheduled Task) or `none`; `unit` and `task` are refused beside any other manager (DEC-0032). Both kits and the probe accept all four; both kits write the unit and the task (`systemd_unit`, `task_xml` / `systemdUnit`, `taskXml`) |
 | `paths` | `data` (required), `logs[]`, optional `config`, `cache` |
 | `commands` | only `doctor` and `update`, argument arrays whose first item is an absolute or `~/` path (Windows: also `C:\…`, `C:/…` or `~\…`, never a network share — DEC-0032) |
 | `source.repository`, `fabricManifest` | optional |

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

@@ -21,7 +21,9 @@
   (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
   atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
   goes in `headers`, never in the URL — every log that records a URL prints its query
-  string.
+  string. An HTTP registration starts nothing per session: every client session talks to the
+  one resident service (LC-19). A stdio server, by contrast, is a process per session — keep
+  one only at project scope.
 - Ship server `instructions` that tell a caller where to start and that every answer
   carries `degraded`.
 

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

@@ -730,7 +730,7 @@ class Probe:
                     self.add("lifecycle.instance-lock", "PASS", "held by the running service")
                 else:
                     msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
-                    self.add("lifecycle.instance-lock", "FAIL", "%s exists but nobody holds it" % lock)
+                    self.lock_free(lock)
             finally:
                 os.close(fd)
             return
@@ -747,10 +747,17 @@ class Probe:
             self.add("lifecycle.instance-lock", "PASS" if held else "FAIL", "held by the running service" if held else str(exc))
         else:
             fcntl.flock(fd, fcntl.LOCK_UN)
-            self.add("lifecycle.instance-lock", "FAIL", "%s exists but nobody holds it" % lock)
+            self.lock_free(lock)
         finally:
             os.close(fd)
 
+    def lock_free(self, lock: Path) -> None:
+        """The file lock is free; a Node kit service holds the lock's name instead (fs.lock_name)."""
+        if fs.lock_name_held(lock):
+            self.add("lifecycle.instance-lock", "PASS", "held by the running service (the lock's name, %s)" % ("a named pipe" if fs.WINDOWS else "an abstract socket"))
+        else:
+            self.add("lifecycle.instance-lock", "FAIL", "%s exists but nobody holds it" % lock)
+
     def run(self) -> List[Result]:
         self.descriptor_rules()
         if not self.port: