@passioncode-ai/fabric-agent-adapter 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.8.2 - 2026-10-10
+
+The Python service kit runs on Windows and Linux (contract DEC-0032, DEC-0033), and the contract pin moves to the DEC-0033 merge.
+
+### Changed
+
+- **Default contract pin → `78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5`** (DEC-0032, DEC-0033, FAA-16); the DEC-0031
+  merge joins `SUPPORTED_CONTRACT_COMMITS`. Both are additive: new managers, new optional fields, a wider path
+  grammar, and SYSTEM or Administrators admitted as a Windows token file's owner.
+
+### Added
+
+- **`fabric_service.py` on Windows** (DEC-0032): the services folder `%LOCALAPPDATA%\passioncode-fabric\services`
+  and per-service folders under `%LOCALAPPDATA%`; the instance lock through `msvcrt.locking` on one byte far
+  past the pid (released by the OS with the process); token files, descriptors and every kit write carry an
+  explicit protected ACL (this user, SYSTEM, Administrators); `read_token` applies service.md "Windows token
+  files" — a regular file in the profile, owned by this user, SYSTEM or Administrators (DEC-0033: an elevated
+  administrator's files are owned by Administrators, as `windows-latest` showed), every granting ACE on the allow-list, refusal by
+  SID; descriptors accept `systemd` (`unit`) and `task-scheduler` (`task`) with the contract's pairing rules,
+  Windows paths, and refuse network shares; launchd helpers refuse off macOS instead of calling `os.getuid`;
+  the kit's own log and ledger appends open in binary mode. `check_service.py` checks the lock and the
+  descriptor's privacy the Windows way.
+- **The operator channel proposal (FAA-15).** `creating-fabric-agents` (step 6) and
+  `adapting-projects-to-fabric` (step 8) propose an agent's own messenger channel to its
+  operator once, when the agent has human stops or `notify: true` events. They list the
+  operator's four steps (a bot from @BotFather, its token in the secret store by name, the
+  agent's link command, the code typed in the chat), record the answer (`accepted`, `declined`
+  or `later`), and never create a bot, store a token or enable the channel themselves. This is
+  rule OC-11 of `fabric-operator-channel/0.1` (contract DEC-0034, contract PR #25). It is newer
+  than the default pin, so the skills cite it by path and keep channel conformance `NOT_RUN`
+  until the pin moves. New scenario evals: `operator-channel-proposal` in both skills.
+
+### Fixed
+
+- **Two calls that do not exist or mean something else on Windows**, found by the first Windows run: the usage
+  ledger read its last byte with `os.pread` (absent on Windows, so every `record` raised) — it seeks and reads
+  there now; and `check_service.py`'s "state inside a release" rule looked for `/releases/` in a path whose
+  separators are backslashes — it reads the path's POSIX form.
+
+### Added (tests)
+
+- **A `windows` job in `validate.yml`** (dispatch, like the others) runs the platform cases on `windows-latest`.
+
 ## 0.8.1 - 2026-10-08
 
 The contract pin moves to Fabric Agent Contract `main` `623bf61` (DEC-0025 through DEC-0031); bundles issued

package/README.md

@@ -191,7 +191,7 @@ Scaffolding is non-destructive by default. It writes only the paths declared in
 The default pin for new bundles is [`fabric-contract.lock.json`](fabric-contract.lock.json):
 
 - version: `0.1.0`
-- commit: `623bf61358c339cb10297807b3f024b5d9f1f327`
+- commit: `78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5`
 
 Every other mention of the default contract revision — this section, the skills' metadata, the
 skill card, `adapt_project.py` — must equal it; `python3 test/validate.py` fails a tree
@@ -218,8 +218,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.8.1. 0.8.0 is the latest published GitHub/npm release (2026-10-05; 0.7.0 was never
-released); 0.8.1 is published by its `v0.8.1` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.8.2. 0.8.1 is the latest published GitHub/npm release (2026-10-08; 0.7.0 was never
+released); 0.8.2 is published by its `v0.8.2` 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.8.1",
+  "version": "0.8.2",
   "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.8.1",
+  "version": "0.8.2",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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

@@ -5,9 +5,9 @@ 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.8.1"
+  version: "0.8.2"
   contract-version: "0.1.0"
-  contract-commit: "623bf61358c339cb10297807b3f024b5d9f1f327"
+  contract-commit: "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5"
 ---
 
 # Adapting projects to Fabric
@@ -70,7 +70,7 @@ Use exactly:
 
 - contract version `0.1.0`;
 - repository `https://github.com/passioncode-ai/fabric-agent-contract`;
-- commit `623bf61358c339cb10297807b3f024b5d9f1f327`.
+- commit `78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5`.
 
 This is the default for new bundles. When checking an issued legacy bundle, preserve its
 explicit supported lock and use that exact clean checkout. Never silently upgrade or
@@ -185,6 +185,28 @@ unverified surfaces. If live Fabric admission/runtime does not yet exist, the la
 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.
+
+Record the answer — `accepted`, `declined` or `later` — in the agent's state and the
+conformance report, and do not ask again. 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. DEC-0034 is newer than the default pin: cite it by that path and id, and keep
+channel conformance `NOT_RUN` until the pin carries it. 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
@@ -215,6 +237,7 @@ Report:
 - contract version and commit;
 - gate table with `PASS`, `FAIL`, `NOT_RUN`, or `NOT_VERIFIED`;
 - remaining placeholders and blockers;
+- the operator channel answer (step 8), or why it was skipped;
 - the exact next command or runtime action.
 
 Never summarize the outcome as “Fabric-compatible” unless all required admission gates

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

@@ -16,10 +16,10 @@ from urllib.parse import urlparse
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
-CONTRACT_COMMIT = "623bf61358c339cb10297807b3f024b5d9f1f327"
+CONTRACT_COMMIT = "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5"
 # #region supported-contract-revisions — docs: README.md#contract-pin
 # Only this declaration may name a legacy revision in live files.
-SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
+SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "623bf61358c339cb10297807b3f024b5d9f1f327", "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
 # #endregion supported-contract-revisions
 INTEROP_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1"
 MCP_REVISION = "2026-07-28"

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

@@ -16,10 +16,10 @@ 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.
 metadata:
   author: PassionCode.ai
-  version: "0.8.1"
+  version: "0.8.2"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "623bf61358c339cb10297807b3f024b5d9f1f327"
+  extension-commit: "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5"
 ---
 
 # Building Fabric services

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

@@ -1,6 +1,6 @@
 # fabric-service/0.1 — wire reference
 
-Pinned to `fabric-agent-contract` commit `623bf61358c339cb10297807b3f024b5d9f1f327`
+Pinned to `fabric-agent-contract` commit `78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5`
 (`docs/specification/service.md`, DEC-0015; the usage report DEC-0021). The contract's schemas are normative;
 this page is the working summary. Extension key:
 `https://fabric.passioncode.ai/agent-contract/extensions/service/0.1`.

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

@@ -170,8 +170,14 @@ class Probe:
     def descriptor_rules(self) -> None:
         problems = fs.validate_descriptor(self.d)
         self.add("descriptor.valid", "FAIL" if problems else "PASS", "; ".join(problems) or str(self.path))
-        mode = stat.S_IMODE(os.stat(self.path).st_mode)
-        self.add("descriptor.private", "PASS" if mode & 0o077 == 0 else "FAIL", "mode %o" % mode)
+        if fs.WINDOWS:
+            # DEC-0032: on Windows the file's ACL is its privacy.
+            owner, granting = fs.windows_acl(self.path)
+            problem = fs.token_acl_problem(self.path, owner, granting, fs.windows_user_sid())
+            self.add("descriptor.private", "FAIL" if problem else "PASS", problem or "owner-only ACL")
+        else:
+            mode = stat.S_IMODE(os.stat(self.path).st_mode)
+            self.add("descriptor.private", "PASS" if mode & 0o077 == 0 else "FAIL", "mode %o" % mode)
         me = "%s.%s" % (self.d.get("id"), self.d.get("instance", "default"))
         clashes = []
         for path, other in fs.read_descriptors(self.dir):
@@ -602,7 +608,7 @@ class Probe:
         self.add("lifecycle.priority", "FAIL" if slow else "PASS",
                  "; ".join(slow) + " — macOS may starve the service under load and hosts then see an outage; use ProcessType Standard"
                  if slow else "%s: scheduled as a standard process" % plist_path.name)
-        if not shutil.which("launchctl"):
+        if sys.platform != "darwin" or not shutil.which("launchctl"):
             self.add("lifecycle.one-copy", "NOT_RUN", "launchctl is not available")
             return
         out = subprocess.run(["launchctl", "print", "gui/%d/%s" % (os.getuid(), life.get("label"))], capture_output=True, text=True)
@@ -623,7 +629,7 @@ class Probe:
         A repository that exists to version the data itself (a registry, a plan) is
         a store, not code; deleting the service's checkout does not touch it."""
         rule = "state.outside-code"
-        if "/releases/" in str(data):
+        if "/releases/" in data.as_posix():   # a Windows path's separators are backslashes
             self.add(rule, "FAIL", "%s is inside a release directory" % data)
             return
         if inside is None:
@@ -647,6 +653,23 @@ class Probe:
         if not lock.exists():
             self.add("lifecycle.instance-lock", "FAIL", "%s does not exist" % lock)
             return
+        if fs.WINDOWS:
+            import msvcrt
+
+            # The kit locks one byte at InstanceLock.WINDOWS_LOCK_OFFSET; try the same byte.
+            fd = os.open(str(lock), os.O_RDWR | getattr(os, "O_BINARY", 0))
+            try:
+                os.lseek(fd, fs.InstanceLock.WINDOWS_LOCK_OFFSET, os.SEEK_SET)
+                try:
+                    msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                except OSError:
+                    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)
+            finally:
+                os.close(fd)
+            return
         try:
             import fcntl
         except ImportError:

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

@@ -74,6 +74,16 @@ PLACEMENTS = ("local", "remote")
 _CODE = re.compile(r"^[A-Za-z0-9_-]{16,256}$")
 _TRACE_ID = re.compile(r"^(?!0{32}$)[0-9a-f]{32}$")
 _SPAN_ID = re.compile(r"^(?!0{16}$)[0-9a-f]{16}$")
+# DEC-0032: a local path is POSIX (`/…`, `~/…`) or Windows (`C:\…`, `C:/…`, `~\…`); a network
+# share (`\\server\…`, `\\?\…`) is never a local path.
+_LOCAL_PATH = re.compile(r"^(~[\\/]|/(?!/)|[A-Za-z]:[\\/])")
+# DEC-0032: the supervisor per system and the field that names its job.
+MANAGERS = ("launchd", "systemd", "task-scheduler", "none")
+_UNIT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9:_.@-]{0,250}\.service$")
+_TASK = re.compile(r"^\\[A-Za-z0-9 ._\\-]{1,254}$")
+WINDOWS = os.name == "nt"
+# Without O_BINARY a Windows descriptor is in text mode and every LF written becomes CRLF.
+_O_BINARY = getattr(os, "O_BINARY", 0)
 
 
 class ServiceError(Exception):
@@ -93,7 +103,10 @@ def now_iso() -> str:
 
 
 def expand(path: str) -> Path:
-    """Paths in a descriptor may start with ~/; everything else must be absolute."""
+    """Paths in a descriptor may start with ~/ (or ~\\ on Windows); everything else must be
+    absolute, and a network share is never a local path (DEC-0032)."""
+    if not _LOCAL_PATH.match(str(path)):
+        raise ServiceError("Path %r must be absolute or start with ~/." % path)
     p = Path(os.path.expanduser(path))
     if not p.is_absolute():
         raise ServiceError("Path %r must be absolute or start with ~/." % path)
@@ -110,6 +123,9 @@ def services_dir() -> Path:
     home = Path.home()
     if sys.platform == "darwin":
         return home / "Library/Application Support/ai.passioncode.fabric/services"
+    if sys.platform == "win32":
+        # DEC-0032: LOCALAPPDATA, not APPDATA, so token files never roam with the profile.
+        return _local_app_data() / "passioncode-fabric" / "services"
     base = os.environ.get("XDG_DATA_HOME") or str(home / ".local/share")
     return Path(base) / "passioncode-fabric/services"
 
@@ -124,15 +140,35 @@ def service_dirs(service_id: str) -> Dict[str, Path]:
             "logs": home / "Library/Logs" / service_id,
             "cache": home / "Library/Caches" / service_id,
         }
+    if sys.platform == "win32":
+        data = _local_app_data() / service_id
+        return {"data": data, "logs": data / "Logs", "cache": data / "Cache"}
     data = Path(os.environ.get("XDG_DATA_HOME") or home / ".local/share") / service_id
     state = Path(os.environ.get("XDG_STATE_HOME") or home / ".local/state") / service_id
     cache = Path(os.environ.get("XDG_CACHE_HOME") or home / ".cache") / service_id
     return {"data": data, "logs": state / "logs", "cache": cache}
 
 
+def _read_at(fd: int, n: int, offset: int) -> bytes:
+    """`os.pread` where it exists; Windows has none, so seek and read (the descriptor's appends
+    still go to the end: O_APPEND moves to it before every write)."""
+    if hasattr(os, "pread"):
+        return os.pread(fd, n, offset)
+    os.lseek(fd, offset, os.SEEK_SET)
+    return os.read(fd, n)
+
+
+def _local_app_data() -> Path:
+    value = os.environ.get("LOCALAPPDATA")
+    return Path(value) if value else Path.home() / "AppData" / "Local"
+
+
 def ensure_private_dir(path: Path) -> Path:
     path.mkdir(parents=True, exist_ok=True)
-    os.chmod(path, 0o700)
+    if WINDOWS:
+        _win_protect(path, folder=True)
+    else:
+        os.chmod(path, 0o700)
     return path
 
 
@@ -145,7 +181,12 @@ def atomic_write(path: Path, data: bytes, mode: int = 0o600) -> None:
             handle.write(data)
             handle.flush()
             os.fsync(handle.fileno())
-        os.chmod(tmp, mode)
+        if WINDOWS:
+            # The file's ACL is its privacy (DEC-0032): set explicitly and protected, so it does
+            # not depend on what the folder hands down. A rename keeps it.
+            _win_protect(Path(tmp), folder=False)
+        else:
+            os.chmod(tmp, mode)
         os.replace(tmp, path)
     except BaseException:
         try:
@@ -169,16 +210,28 @@ class InstanceLock:
         self.path = Path(data_dir) / "service.lock"
         self._fd: Optional[int] = None
 
-    def acquire(self) -> "InstanceLock":
-        import fcntl
+    #: Windows locks a byte range, not the file: one byte far past the pid the file holds, so the
+    #: holder may rewrite the pid and another process may still read it (locking past the end of
+    #: a file is allowed there).
+    WINDOWS_LOCK_OFFSET = 1 << 30
 
+    def acquire(self) -> "InstanceLock":
         ensure_private_dir(self.path.parent)
-        fd = os.open(str(self.path), os.O_RDWR | os.O_CREAT, 0o600)
+        fd = os.open(str(self.path), os.O_RDWR | os.O_CREAT | _O_BINARY, 0o600)
         try:
-            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            if WINDOWS:
+                import msvcrt
+
+                os.lseek(fd, self.WINDOWS_LOCK_OFFSET, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                os.lseek(fd, 0, os.SEEK_SET)
+            else:
+                import fcntl
+
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
         except OSError as exc:
             os.close(fd)
-            if exc.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
+            if exc.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES, getattr(errno, "EDEADLOCK", -1)):
                 raise AlreadyRunning(_read_pid(self.path), self.path) from None
             raise
         os.ftruncate(fd, 0)
@@ -239,6 +292,163 @@ def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *
             delay = min(delay * 2, LOCK_BACKOFF_MAX_SECONDS)
 
 
+# --- Windows ACLs (DEC-0032) ---------------------------------------------------
+
+#: The trustees a token file may grant anything to besides the current user: LocalSystem and the
+#: Administrators group — the same trust as root reading a 0600 file on POSIX.
+WINDOWS_TRUSTED = ("S-1-5-18", "S-1-5-32-544")
+
+
+def token_acl_problem(path: Path, owner: str, granting: Sequence[str], user: str) -> Optional[str]:
+    """service.md "Windows token files", rules 2 and 3, on SIDs already read: the owner is the
+    current user, SYSTEM or Administrators (DEC-0033: a file an elevated administrator creates is
+    owned by Administrators), and every SID an allow ACE grants anything to is one of those three.
+    Deny ACEs are not passed in: they do not change the decision."""
+    if owner != user and owner not in WINDOWS_TRUSTED:
+        return "Token file %s is owned by %s, not by this user (%s), SYSTEM or Administrators." % (path, owner or "nobody", user)
+    for sid in granting:
+        if sid != user and sid not in WINDOWS_TRUSTED:
+            return "Token file %s grants access to %s; only this user, SYSTEM and Administrators may hold any." % (path, sid)
+    return None
+
+
+if WINDOWS:  # pragma: no cover - exercised by the Windows CI job
+    import ctypes
+    from ctypes import wintypes
+
+    _advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
+    _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    _PVOID = ctypes.c_void_p
+    _SE_FILE_OBJECT, _OWNER_INFO, _DACL_INFO, _PROTECTED_DACL = 1, 0x1, 0x4, 0x80000000
+    _REPARSE_POINT = 0x400
+    _advapi32.GetNamedSecurityInfoW.argtypes = [wintypes.LPCWSTR, ctypes.c_int, wintypes.DWORD] + [ctypes.POINTER(_PVOID)] * 5
+    _advapi32.GetNamedSecurityInfoW.restype = wintypes.DWORD
+    _advapi32.SetNamedSecurityInfoW.argtypes = [wintypes.LPWSTR, ctypes.c_int, wintypes.DWORD] + [_PVOID] * 4
+    _advapi32.SetNamedSecurityInfoW.restype = wintypes.DWORD
+    _advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW.argtypes = [
+        _PVOID, wintypes.DWORD, wintypes.DWORD, ctypes.POINTER(wintypes.LPWSTR), ctypes.POINTER(wintypes.ULONG)]
+    _advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW.argtypes = [
+        wintypes.LPCWSTR, wintypes.DWORD, ctypes.POINTER(_PVOID), ctypes.POINTER(wintypes.ULONG)]
+    _advapi32.GetSecurityDescriptorDacl.argtypes = [_PVOID, ctypes.POINTER(wintypes.BOOL), ctypes.POINTER(_PVOID),
+                                                    ctypes.POINTER(wintypes.BOOL)]
+    _advapi32.OpenProcessToken.argtypes = [wintypes.HANDLE, wintypes.DWORD, ctypes.POINTER(wintypes.HANDLE)]
+    _advapi32.GetTokenInformation.argtypes = [wintypes.HANDLE, ctypes.c_int, _PVOID, wintypes.DWORD,
+                                              ctypes.POINTER(wintypes.DWORD)]
+    _advapi32.ConvertSidToStringSidW.argtypes = [_PVOID, ctypes.POINTER(wintypes.LPWSTR)]
+    _advapi32.ConvertStringSidToSidW.argtypes = [wintypes.LPCWSTR, ctypes.POINTER(_PVOID)]
+    _kernel32.GetCurrentProcess.restype = wintypes.HANDLE
+    _kernel32.LocalFree.argtypes = [_PVOID]
+    _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    _ACE = re.compile(r"\(([^;()]*);([^;()]*);([^;()]*);([^;()]*);([^;()]*);([^;()]*)(?:;[^()]*)?\)")
+    _CANONICAL: Dict[str, str] = {}
+
+    def _win_error(what: str, code: Optional[int] = None) -> OSError:
+        code = ctypes.get_last_error() if code is None else code
+        return OSError(code, "%s: %s" % (what, ctypes.FormatError(code).strip()))
+
+    def _sid_text(sid: Any) -> str:
+        text = wintypes.LPWSTR()
+        if not _advapi32.ConvertSidToStringSidW(sid, ctypes.byref(text)):
+            raise _win_error("ConvertSidToStringSidW")
+        try:
+            return text.value
+        finally:
+            _kernel32.LocalFree(text)
+
+    def _canonical_sid(trustee: str) -> str:
+        """SDDL writes well-known accounts by alias (SY, BA, LA, OW); compare SIDs."""
+        if trustee not in _CANONICAL:
+            sid = _PVOID()
+            if _advapi32.ConvertStringSidToSidW(trustee, ctypes.byref(sid)):
+                try:
+                    _CANONICAL[trustee] = _sid_text(sid)
+                finally:
+                    _kernel32.LocalFree(sid)
+            else:
+                _CANONICAL[trustee] = trustee
+        return _CANONICAL[trustee]
+
+    def windows_user_sid() -> str:
+        token = wintypes.HANDLE()
+        if not _advapi32.OpenProcessToken(_kernel32.GetCurrentProcess(), 0x8, ctypes.byref(token)):
+            raise _win_error("OpenProcessToken")
+        try:
+            size = wintypes.DWORD()
+            _advapi32.GetTokenInformation(token, 1, None, 0, ctypes.byref(size))
+            buf = ctypes.create_string_buffer(size.value)
+            if not _advapi32.GetTokenInformation(token, 1, buf, size, ctypes.byref(size)):
+                raise _win_error("GetTokenInformation")
+            return _sid_text(ctypes.cast(buf, ctypes.POINTER(_PVOID))[0])
+        finally:
+            _kernel32.CloseHandle(token)
+
+    def _sddl(path: Path) -> str:
+        sd = _PVOID()
+        refs = [_PVOID() for _ in range(4)]
+        code = _advapi32.GetNamedSecurityInfoW(str(path), _SE_FILE_OBJECT, _OWNER_INFO | _DACL_INFO,
+                                               *[ctypes.byref(r) for r in refs], ctypes.byref(sd))
+        if code:
+            raise _win_error("GetNamedSecurityInfoW", code)
+        try:
+            text = wintypes.LPWSTR()
+            if not _advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW(
+                    sd, 1, _OWNER_INFO | _DACL_INFO, ctypes.byref(text), None):
+                raise _win_error("ConvertSecurityDescriptorToStringSecurityDescriptorW")
+            try:
+                return text.value or ""
+            finally:
+                _kernel32.LocalFree(text)
+        finally:
+            _kernel32.LocalFree(sd)
+
+    def windows_acl(path: Path) -> Tuple[str, List[str]]:
+        """(owner SID, SIDs of every allow ACE on the object itself); a missing or NULL list grants
+        everyone everything, reported as Everyone (S-1-1-0)."""
+        text = _sddl(path)
+        owner = text.split("O:", 1)[1].split("G:", 1)[0].split("D:", 1)[0] if "O:" in text else ""
+        dacl = text.split("D:", 1)[1] if "D:" in text else ""
+        if not dacl or dacl.startswith("NO_ACCESS_CONTROL"):
+            return _canonical_sid(owner) if owner else "", ["S-1-1-0"]
+        granting = [_canonical_sid(trustee) for kind, flags, _r, _o, _i, trustee in _ACE.findall(dacl)
+                    if kind in ("A", "OA", "XA", "ZA") and "IO" not in flags]
+        return (_canonical_sid(owner) if owner else ""), granting
+
+    def _win_protect(path: Path, folder: bool) -> None:
+        """A protected list (inheritance off): this user, SYSTEM, Administrators, full control;
+        inherited by what a folder holds."""
+        inherit = "OICI" if folder else ""
+        sddl = "D:P" + "".join("(A;%s;FA;;;%s)" % (inherit, who) for who in (windows_user_sid(), "SY", "BA"))
+        sd = _PVOID()
+        if not _advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(sddl, 1, ctypes.byref(sd), None):
+            raise _win_error("ConvertStringSecurityDescriptorToSecurityDescriptorW")
+        try:
+            present, defaulted, dacl = wintypes.BOOL(), wintypes.BOOL(), _PVOID()
+            if not _advapi32.GetSecurityDescriptorDacl(sd, ctypes.byref(present), ctypes.byref(dacl), ctypes.byref(defaulted)):
+                raise _win_error("GetSecurityDescriptorDacl")
+            code = _advapi32.SetNamedSecurityInfoW(str(path), _SE_FILE_OBJECT, _DACL_INFO | _PROTECTED_DACL,
+                                                   None, None, dacl, None)
+            if code:
+                raise _win_error("SetNamedSecurityInfoW", code)
+        finally:
+            _kernel32.LocalFree(sd)
+
+    def _win_token_problem(path: Path, info: os.stat_result) -> Optional[str]:
+        if getattr(info, "st_file_attributes", 0) & _REPARSE_POINT or not stat.S_ISREG(info.st_mode):
+            return "Token file %s is not a regular file (a link or junction); refusing it." % path
+        profile = os.path.normcase(os.path.realpath(os.environ.get("USERPROFILE") or str(Path.home())))
+        real = os.path.normcase(os.path.realpath(str(path)))
+        if os.path.commonpath([profile, real]) != profile:
+            return "Token file %s lies outside the user's profile; refusing it." % path
+        owner, granting = windows_acl(path)
+        return token_acl_problem(path, owner, granting, windows_user_sid())
+else:
+    def _win_protect(path: Path, folder: bool) -> None:  # noqa: ARG001 - POSIX uses modes
+        raise ServiceError("Windows ACLs exist only on Windows")
+
+    def _win_token_problem(path: Path, info: os.stat_result) -> Optional[str]:  # noqa: ARG001
+        raise ServiceError("Windows token rules apply only on Windows")
+
+
 # --- token -------------------------------------------------------------------
 
 def ensure_token(path: Path) -> str:
@@ -253,15 +463,24 @@ def ensure_token(path: Path) -> str:
 
 
 def read_token(path: Path) -> str:
-    """Refuse a symlink, a file owned by someone else, or one others can read."""
+    """Refuse a symlink, a file owned by someone else, or one others can read.
+
+    On Windows the rule is service.md "Windows token files" (DEC-0032, DEC-0033): a regular file
+    whose real path is in the profile, owned by the current user, SYSTEM or Administrators, every
+    granting ACE naming one of those three; a refusal names the SID, never the contents."""
     path = Path(path)
     info = os.lstat(path)
     if stat.S_ISLNK(info.st_mode):
         raise ServiceError("Token file %s is a symlink; refusing it." % path)
-    if info.st_uid != os.getuid():
-        raise ServiceError("Token file %s belongs to another user." % path)
-    if info.st_mode & 0o077:
-        raise ServiceError("Token file %s is readable by others; set mode 0600." % path)
+    if WINDOWS:
+        problem = _win_token_problem(path, info)
+        if problem:
+            raise ServiceError(problem)
+    else:
+        if info.st_uid != os.getuid():
+            raise ServiceError("Token file %s belongs to another user." % path)
+        if info.st_mode & 0o077:
+            raise ServiceError("Token file %s is readable by others; set mode 0600." % path)
     token = path.read_text().strip()
     if len(token) < 16:
         raise ServiceError("Token file %s holds no usable token." % path)
@@ -354,21 +573,38 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
     auth = descriptor.get("auth") or {}
     if "tokenFile" not in auth:
         problems.append("auth.tokenFile is required")
+    elif not _LOCAL_PATH.match(str(auth["tokenFile"])):
+        problems.append("auth.tokenFile must be a local path, never a network share")
+    paths = descriptor.get("paths") or {}
+    for value in ([paths["data"]] if "data" in paths else []) + list(paths.get("logs") or []):
+        if not _LOCAL_PATH.match(str(value)):
+            problems.append("paths must be local paths, never a network share: %r" % value)
     header = auth.get("header", "Authorization")
     scheme = auth.get("scheme", "Bearer")
     if header != "Authorization" and scheme != "none":
         problems.append("a custom auth header carries the raw token: scheme must be none")
     life = descriptor.get("lifecycle") or {}
-    if life.get("manager") not in ("launchd", "none"):
-        problems.append("lifecycle.manager must be launchd or none")
-    if life.get("manager") == "launchd" and not (life.get("label") and str(life.get("plist", "")).endswith(".plist")):
+    manager = life.get("manager")
+    if manager not in MANAGERS:
+        problems.append("lifecycle.manager must be launchd, systemd, task-scheduler or none")
+    if manager == "launchd" and not (life.get("label") and str(life.get("plist", "")).endswith(".plist")):
         problems.append("a launchd service declares label and plist")
+    if "plist" in life and not _LOCAL_PATH.match(str(life["plist"])):
+        problems.append("lifecycle.plist must be a local path")
+    # DEC-0032: `unit` goes with systemd and `task` with Task Scheduler, and with nothing else.
+    for field, owner, pattern in (("unit", "systemd", _UNIT), ("task", "task-scheduler", _TASK)):
+        if manager == owner and field not in life:
+            problems.append("a %s service declares %s" % (owner, field))
+        if field in life and manager != owner:
+            problems.append("lifecycle.%s belongs to manager %s only" % (field, owner))
+        if field in life and not pattern.match(str(life[field])):
+            problems.append("lifecycle.%s must match %s" % (field, pattern.pattern))
     if remote:
-        if life.get("manager") != "none":
+        if manager != "none":
             problems.append("a remote service is supervised by its platform: lifecycle.manager must be none")
-        for field in ("label", "plist"):
+        for field, of in (("label", "launchd"), ("plist", "launchd"), ("unit", "systemd"), ("task", "Task Scheduler")):
             if field in life:
-                problems.append("a remote service has no launchd %s" % field)
+                problems.append("a remote service has no %s %s" % (of, field))
         if "update" in (descriptor.get("commands") or {}):
             problems.append("a remote service declares no update command")
     for name, argv in (descriptor.get("commands") or {}).items():
@@ -376,7 +612,7 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
             problems.append("unknown command %s" % name)
         elif not isinstance(argv, list) or not argv or not all(isinstance(a, str) for a in argv):
             problems.append("command %s must be an argument array" % name)
-        elif not re.match(r"^(~/|/)", argv[0]):
+        elif not _LOCAL_PATH.match(argv[0]):
             problems.append("command %s must start with an absolute or ~/ executable" % name)
     return problems
 
@@ -699,10 +935,10 @@ class JsonlUsageLedger:
         line = json.dumps(receipt, separators=(",", ":")) + "\n"
         with self._lock:
             ensure_private_dir(self.path.parent)
-            fd = os.open(str(self.path), os.O_RDWR | os.O_CREAT | os.O_APPEND, 0o600)
+            fd = os.open(str(self.path), os.O_RDWR | os.O_CREAT | os.O_APPEND | _O_BINARY, 0o600)
             try:
                 size = os.fstat(fd).st_size
-                if size and os.pread(fd, 1, size - 1) != b"\n":
+                if size and _read_at(fd, 1, size - 1) != b"\n":
                     line = "\n" + line  # a killed writer left a torn line: never glue a receipt to it
                 os.write(fd, line.encode("utf-8"))
             finally:
@@ -779,7 +1015,7 @@ class RotatingLog:
                 size = 0
             if size and size + len(data) > self.max_bytes:
                 self._rotate()
-            fd = os.open(str(self.path), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+            fd = os.open(str(self.path), os.O_WRONLY | os.O_APPEND | os.O_CREAT | _O_BINARY, 0o600)
             try:
                 os.write(fd, data)
             finally:
@@ -1114,6 +1350,9 @@ def _launchctl(*args: str, timeout: int = 30) -> subprocess.CompletedProcess:
 
 
 def _domain() -> str:
+    if sys.platform == "win32":
+        # DEC-0032: launchd is macOS's supervisor; Windows has Task Scheduler, and no uid.
+        raise ServiceError("launchd exists only on macOS; this system's supervisor is Task Scheduler.")
     return "gui/%d" % os.getuid()
 
 

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/SKILL.md

@@ -5,9 +5,9 @@ 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. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.8.1"
+  version: "0.8.2"
   contract-version: "0.1.0"
-  contract-commit: "623bf61358c339cb10297807b3f024b5d9f1f327"
+  contract-commit: "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5"
 ---
 
 # Creating Fabric-compatible agents
@@ -119,7 +119,7 @@ python3 <plugin-dir>/skills/adapting-projects-to-fabric/scripts/adapt_project.py
   --schema-base <immutable-base-uri>
 ```
 
-Pin exactly contract `0.1.0` at commit `623bf61358c339cb10297807b3f024b5d9f1f327` and
+Pin exactly contract `0.1.0` at commit `78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5` and
 read the pinned guide before implementing protocol details. If this skill is installed
 without its sibling, the scaffolder is absent: create the bundle by hand from the pinned
 contract's `docs/guides/connecting-compatible-agents.md` and mark the structural check
@@ -164,13 +164,35 @@ purpose. Then record one expectation the report must carry:
 > checker on its output and a budget cap — regardless of who wrote it. Unsupervised
 > operation is a later, recorded promotion citing eval results and run history.
 
+## Step 6 — 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 secret store (Project Observatory) 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.
+
+Record the answer — `accepted`, `declined` or `later` — in the agent's state and in the
+report, and do not ask again. 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. DEC-0034 is newer than the default pin: cite it by that path and id, and keep
+channel conformance `NOT_RUN` until the pin carries it. An agent with neither stops nor notify
+events skips this step.
+
 ## Completion format
 
 Report: capability, consumer, profile with the step-0 grill answers; the knowledge pack
 and which traps became fixtures; created files; contract version and commit; the gate
-table with `PASS`, `FAIL`, `NOT_RUN`, or `NOT_VERIFIED`; remaining placeholders; and the
-exact next command. Never summarize the outcome as "Fabric-compatible" unless every
-required admission gate passed against the real provider.
+table with `PASS`, `FAIL`, `NOT_RUN`, or `NOT_VERIFIED`; remaining placeholders; the
+operator channel answer (step 6); and the exact next command. Never summarize the outcome as
+"Fabric-compatible" unless every required admission gate passed against the real provider.
 
 ## Dashboard handoff — also for consumers