@passioncode-ai/passioncode 0.1.31 → 0.1.33

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

@@ -40,6 +40,11 @@ import urllib.request
 
 PROTOCOL = "fabric-service/0.1"
 EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/service/0.1"
+# The embedded dashboard declaration (fabric-dashboard/0.1, DEC-0036 ED-9), under the well-known
+# document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
+DASHBOARD_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1"
+DASHBOARD_KIT = "fabric-dashboard-kit@1.0.0"
+REFERENCE_THEMES = ("graphite", "fabric", "paper", "forest", "ocean", "ember", "contrast")
 EXIT_ALREADY_RUNNING = 75
 # Lifecycle contract (fabric-workspace knowledge/lifecycle.md). A launchd-supervised copy that finds
 # the lock held backs off in-process for this long before its exit 75 (LC-03, F8): under KeepAlive
@@ -74,6 +79,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 +108,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 +128,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 +145,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 +186,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 +215,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 +297,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 +468,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 +578,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 +617,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
 
@@ -465,11 +706,63 @@ def build_info(repo_root: Optional[Path] = None, package_file: Optional[Path] =
     return info
 
 
+_THEME_ID = re.compile(r"^[a-z][a-z0-9-]{0,31}$")
+_KIT_REF = re.compile(r"^[a-z][a-z0-9-]{0,63}@(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$")
+
+
+def dashboard_extension_problems(value: Any) -> List[str]:
+    """What makes value not a valid ED-9 declaration (service-dashboard-extension.schema.json)."""
+    if not isinstance(value, dict):
+        return ["the declaration is not an object"]
+    out: List[str] = []
+    extra = sorted(set(value) - {"minWidth", "appearance", "themes", "kit"})
+    if extra:
+        out.append("unknown field(s): %s" % ", ".join(extra))
+    width = value.get("minWidth")
+    if isinstance(width, bool) or not isinstance(width, int):
+        out.append("minWidth is required and must be a whole number of CSS pixels")
+    elif not 360 <= width <= 1280:
+        out.append("minWidth %d is outside 360…1280" % width)
+    if "appearance" in value:
+        a = value["appearance"]
+        if not isinstance(a, list) or len(a) > 2 or len(set(map(str, a))) != len(a) or any(x not in ("scheme", "theme") for x in a):
+            out.append("appearance is a list of distinct fields from scheme, theme")
+    if "themes" in value:
+        t = value["themes"]
+        if not isinstance(t, list) or not 1 <= len(t) <= 32 or len(set(map(str, t))) != len(t) \
+                or any(not isinstance(x, str) or not _THEME_ID.match(x) for x in t):
+            out.append("themes is 1…32 distinct theme ids matching ^[a-z][a-z0-9-]{0,31}$")
+    if "kit" in value and not (isinstance(value["kit"], str) and _KIT_REF.match(value["kit"])):
+        out.append("kit is name@semver, for example %s" % DASHBOARD_KIT)
+    return out
+
+
+def dashboard_extension(min_width: int = 360, appearance: Sequence[str] = ("scheme", "theme"),
+                        themes: Optional[Sequence[str]] = REFERENCE_THEMES,
+                        kit: Optional[str] = DASHBOARD_KIT) -> Dict[str, Any]:
+    """The `extensions` entry a dashboard built from the kit declares (DEC-0036 ED-9). Declare it only
+    when the page meets ED-1…ED-6 — check_dashboard_layout.mjs measures that."""
+    value: Dict[str, Any] = {"minWidth": min_width}
+    if appearance:
+        value["appearance"] = list(appearance)
+    if themes:
+        value["themes"] = list(themes)
+    if kit:
+        value["kit"] = kit
+    problems = dashboard_extension_problems(value)
+    if problems:
+        raise ServiceError("Dashboard declaration: %s." % "; ".join(problems))
+    return {DASHBOARD_EXTENSION_KEY: value}
+
+
 def build_well_known(*, service_id: str, instance: str, name: str, version: str, build: Dict[str, Any],
                      started_at: str, status: str, degraded: Sequence[Dict[str, str]],
                      surfaces: Dict[str, Any], summary: Optional[Sequence[Dict[str, Any]]] = None,
-                     update_available: Optional[str] = None, pid: Optional[int] = None) -> Dict[str, Any]:
-    """The unauthenticated identity answer. `degraded` is always present; ready means empty."""
+                     update_available: Optional[str] = None, pid: Optional[int] = None,
+                     extensions: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """The unauthenticated identity answer. `degraded` is always present; ready means empty.
+    `extensions` is kept as given (a reader ignores keys it does not know); a dashboard declaration
+    in it must be valid (dashboard_extension builds one)."""
     if status not in STATUSES:
         raise ServiceError("status must be one of %s." % ", ".join(STATUSES))
     degraded = list(degraded)
@@ -488,6 +781,12 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
     }
     if summary:
         doc["summary"] = list(summary)[:6]
+    if extensions:
+        if DASHBOARD_EXTENSION_KEY in extensions:
+            problems = dashboard_extension_problems(extensions[DASHBOARD_EXTENSION_KEY])
+            if problems:
+                raise ServiceError("Dashboard declaration: %s." % "; ".join(problems))
+        doc["extensions"] = dict(extensions)
     return doc
 
 
@@ -699,10 +998,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 +1078,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 +1413,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/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/sample_service.py

@@ -29,10 +29,21 @@ import fabric_service as fs  # noqa: E402
 import fabric_interop as fi  # noqa: E402
 
 VERSION = "0.1.0"
+# The dashboard is built from the dashboard kit (fabric-dashboard/0.1, DEC-0036) and declares it
+# in the well-known document only when the kit is there to serve.
+KIT_DIR = Path(__file__).resolve().parent.parent / "assets" / "dashboard-kit"
+KIT_FILES = {"/kit/fabric-dashboard.css": ("fabric-dashboard.css", "text/css; charset=utf-8"),
+             "/kit/fabric-dashboard.js": ("fabric-dashboard.js", "text/javascript; charset=utf-8")}
 PAGE = """<!doctype html><html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1"><title>{name}</title>
-<style>body{{font:15px system-ui;margin:2rem;color:#e9e4ec;background:#0a070d}}li{{margin:.3rem 0}}</style>
-</head><body><h1>{name}</h1><p>Status: {status}</p><ul>{rows}</ul></body></html>"""
+<link rel="stylesheet" href="/kit/fabric-dashboard.css"><script src="/kit/fabric-dashboard.js" defer></script>
+</head><body><div class="fd-chrome"><header class="fd-header"><p class="fd-title">{name}</p>
+<span class="fd-chip fd-s-ok"><span class="fd-dot"></span>Status: {status}</span></header>
+<nav class="fd-nav" aria-label="Sections"><ul class="fd-nav-list"><li><a href="#events" aria-current="page">Events</a></li>
+<li><a href="#about">About</a></li></ul></nav></div>
+<main class="fd-page"><section id="events"><h2>Events</h2><ul>{rows}</ul></section>
+<section id="about"><h2>About</h2><p class="fd-hint">A sample fabric-service/0.1 service built on the kit.</p></section></main>
+</body></html>"""
 
 
 def _schema(name: str, body: Dict[str, Any]) -> Dict[str, Any]:
@@ -130,6 +141,7 @@ class Service:
             surfaces={"dashboard": {"path": "/", "login": True}, "events": {"path": "/fabric/v1/events"},
                       "mcp": {"path": "/mcp", "transport": "streamable-http", "capabilities": [c["name"] for c in CAPABILITIES]},
                       "usage": {"path": fs.USAGE_PATH}},
+            extensions=fs.dashboard_extension() if (KIT_DIR / "fabric-dashboard.css").is_file() else None,
         )
 
 
@@ -148,7 +160,7 @@ def make_handler(svc: Service):
             self.send_response(status)
             self.send_header("Cache-Control", "no-store")
             self.send_header("X-Content-Type-Options", "nosniff")
-            self.send_header("Content-Security-Policy", "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'self'")
+            self.send_header("Content-Security-Policy", "default-src 'none'; style-src 'self'; script-src 'self'; frame-ancestors 'self'")
             if body is not None:
                 self.send_header("Content-Type", content_type)
                 self.send_header("Content-Length", str(len(payload)))
@@ -203,6 +215,12 @@ def make_handler(svc: Service):
                 if not cookie:
                     return self._send(403, "This sign-in link was already used or has expired.", content_type="text/plain")
                 return self._send(302, None, {"Location": "/", "Set-Cookie": fs.session_cookie_header(cookie)})
+            if url.path in KIT_FILES:
+                name, kind = KIT_FILES[url.path]
+                try:
+                    return self._send(200, (KIT_DIR / name).read_text(encoding="utf-8"), content_type=kind)
+                except OSError:
+                    return self._send(404, {"error": "Not found."})
             if url.path == "/":
                 if not self._session_ok():
                     return self._send(401, "Open this dashboard from Fabric Dashboards.", content_type="text/plain")

package/payload/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.9.0"
   contract-version: "0.1.0"
-  contract-commit: "623bf61358c339cb10297807b3f024b5d9f1f327"
+  contract-commit: "a83bec6b47776af688402c18efec507143061f68"
 ---
 
 # 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 `a83bec6b47776af688402c18efec507143061f68` 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,42 @@ 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.
+
+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 in the
+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.
+
 ## 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
 

package/payload/plugins/passioncode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "passioncode",
   "displayName": "PassionCode.ai",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check at session start that keeps the PassionCode.ai skill set current.",
   "author": {
     "name": "PassionCode.ai",