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

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

@@ -264,6 +264,15 @@ def make_handler(svc: Service):
                                   content_type="text/html; charset=utf-8")
             self._send(404, {"error": "Not found."})
 
+        def _length(self, cap: int) -> "int | None":
+            """The body's declared length, 0..cap; anything else answers 400 and reads nothing (finding 17)."""
+            raw = (self.headers.get("Content-Length") or "0").strip()
+            if raw.isdigit() and raw.isascii() and int(raw) <= cap:
+                return int(raw)
+            self.close_connection = True  # an unread body must not be taken for the next request
+            self._send(400, {"error": "Content-Length must be a whole number of bytes up to %d." % cap})
+            return None
+
         def do_POST(self) -> None:  # noqa: N802
             if not self._guard():
                 return
@@ -271,10 +280,12 @@ def make_handler(svc: Service):
             if url.path == "/mcp":
                 if not self._token_ok():
                     return
-                length = min(int(self.headers.get("Content-Length") or 0), 1048576)
+                length = self._length(1048576)
+                if length is None:
+                    return
                 try:
                     message = json.loads(self.rfile.read(length) or b"null")
-                except ValueError:
+                except (ValueError, RecursionError):
                     return self._send(400, {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error."}})
                 try:
                     with svc.drain.work():
@@ -300,11 +311,18 @@ def make_handler(svc: Service):
                     return self._send(401, {"error": "Sign in first."})
                 if self.headers.get("X-Fabric-Request") != "1":
                     return self._send(403, {"error": "Missing request header."})
-                length = min(int(self.headers.get("Content-Length") or 0), 65536)
-                body = json.loads(self.rfile.read(length) or b"{}")
-                event = svc.log.append(body.get("kind", "demo.note"), body.get("level", "info"),
-                                       body.get("text", "A note from the sample service."),
-                                       notify=bool(body.get("notify")), link=body.get("link"))
+                length = self._length(65536)
+                if length is None:
+                    return
+                try:
+                    body = json.loads(self.rfile.read(length) or b"{}")
+                    if not isinstance(body, dict):
+                        raise ValueError("not an object")
+                    event = svc.log.append(body.get("kind", "demo.note"), body.get("level", "info"),
+                                           body.get("text", "A note from the sample service."),
+                                           notify=bool(body.get("notify")), link=body.get("link"))
+                except (ValueError, RecursionError, fs.ServiceError) as exc:  # finding 17: a 400, never a crash
+                    return self._send(400, {"error": "The note is a JSON object the event log takes: %s" % exc})
                 return self._send(200, event)
             self._send(404, {"error": "Not found."})
 

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

@@ -1,11 +1,11 @@
 ---
 name: creating-fabric-agents
-description: Use when designing and building a NEW agent or provider that must be Fabric-compatible from its first commit, «создай агента, совместимого с фабрикой Passion Code», «новый агент под Fabric», "create a fabric-compatible agent", "build a new Fabric provider", "fabric-ready agent from scratch", «агент в облаке организации», "which models and OpenRouter key for a new Fabric agent". Runs the intake grill (capability, named consumer, workflow-or-agent, MCP/A2A/local-runner profile, effect declarations, where it runs, models, who pays, how it learns), distils source projects into a knowledge pack whose recorded failures become planted eval fixtures, scaffolds the pinned contract bundle, and sets the two-clock eval expectation with the conformance report. NOT for adapting an existing project (use adapting-projects-to-fabric), building the Fabric host or orchestrator, or generic agent design where Fabric compatibility is not part of the request.
+description: Use when designing and building a NEW agent or provider that must be Fabric-compatible from its first commit, «создай агента, совместимого с фабрикой Passion Code», «новый агент под Fabric», "create a fabric-compatible agent", "build a new Fabric provider", "fabric-ready agent from scratch", «агент в облаке организации», "which models and OpenRouter key for a new Fabric agent". Runs the intake grill (capability, named consumer, workflow or agent, profile, effects, where it runs, models, who pays, how it learns), turns source projects' recorded failures into planted eval fixtures, scaffolds the pinned contract bundle and sets the canary expectation. NOT for adapting an existing project (adapting-projects-to-fabric), making an agent a local or online Fabric service with a dashboard (building-fabric-services), a coding session working through Fabric or its board (working-with-fabric), the Fabric host or orchestrator, or agent design without Fabric.
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.39.1"
+  version: "0.41.0"
   contract-version: "0.1.0"
   contract-commit: "c55f2d5a11c9a0197e958e87212fca7ae1154769"
 ---
@@ -24,6 +24,10 @@ Use this skill to design and build a new provider. Do not use it to:
 
 - adapt a project that already has a stable API, MCP/A2A surface, or CLI: that is
   `adapting-projects-to-fabric`, and entering there skips nothing;
+- run an agent as a local or online service with a dashboard on its own: that is
+  `building-fabric-services` (step 4 hands over to it for a new agent that needs one);
+- work in a project through Fabric from a coding session (the board, claims): that is
+  `working-with-fabric`;
 - design the Fabric host, registry, scheduler, admission service, or binding runtime;
 - build a generic agent with no Fabric requirement: nothing here helps a project that
   will never be a provider;
@@ -99,30 +103,21 @@ authored now: it grows from real traces once the provider runs, and the step-1 f
 are its seed because a source project's recorded failures count as production.
 
 **For a PassionCode.ai repository**, the new agent's repository follows the organization's
-[repository standard](https://github.com/passioncode-ai/fabric-workspace/blob/main/knowledge/repository-standard.md) (`knowledge/repository-standard.md`
-in the organization's knowledge base; a clone has it at `fabric-workspace/knowledge/`) from its
-first commit:
-
-- `LICENSE`, `COMMERCIAL-LICENSE.md` and `CLA.md` copied byte for byte from the knowledge base's
-  `templates/`, and `AGPL-3.0-only OR LicenseRef-PassionCode-Commercial` in every manifest and
-  every SKILL.md `license:`; `SECURITY.md` when the repository is public;
-- a README whose first heading is the full name, with `## Quick start for a new teammate`
-  (Install; Configure, key names only; MCP, the registration command and one proving tool call,
-  verified with a real client in a temporary config; Develop) and `## License`;
-- an `AGENTS.md` that opens with the template's *Read first* block and closes with *After work*,
-  and a `CLAUDE.md` whose first line is `@AGENTS.md`.
-
-**Every credential the agent uses comes from Project Observatory, by name**, from its first
-commit: the README's Configure section lists key NAMES; the agent finds them with
-`observatory_credentials` and runs with `use_secret.py run --vault-only` (a long-running
-service: `use_secret.py serve`), with `OBSERVATORY_VAULT_ONLY=1` in its environment. No `.env`
-of its own, no key file beside its data, no value in code, configuration or a commit. A
-workflow names the keys it needs in its checkpoint (`credentials`), never their values.
-
-org-index `scripts/check_format.py` reports 0 findings for it before it is called done. **An agent
-someone builds for themselves is not a PassionCode.ai repository:** its licence is its owner's
-choice, nothing about it is published or listed by the organization, and none of these files is
-required of it, though the verified MCP quick start is still how anyone learns to drive it.
+repository standard (`knowledge/repository-standard.md`) from its first commit: the licence files,
+the README quick start verified with a real client, `AGENTS.md` and `CLAUDE.md`, as
+[the operator channel and the repository standard](references/operator-channel-and-repository.md)
+lists them. An agent someone builds for themselves is not a PassionCode.ai repository: its licence
+is its owner's choice and none of those files is required of it.
+
+**Every credential the agent uses is read by name, never held as a value**, from its first commit:
+the README's Configure section lists key NAMES. With Project Observatory installed, the agent finds
+them with `observatory_credentials` and runs under
+`python3 "$(project-observatory full-path)/tools/use_secret.py" run --vault-only <project> <NAME> -- <command>`
+(a long-running service: `use_secret.py serve`), with `OBSERVATORY_VAULT_ONLY=1` in its environment.
+Without it, the person's OS keychain or secret manager injects the key into the agent's environment
+at start. Either way: no `.env` of its own, no key file beside its data, no value in argv, code,
+configuration or a commit. A workflow names the keys it needs in its checkpoint (`credentials`),
+never their values.
 
 ## Step 3: scaffold the provider bundle
 
@@ -193,31 +188,11 @@ purpose. Then record one expectation the report must carry:
 ## 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.
+events, propose its operator channel (`fabric-operator-channel/0.1`, OC-11) to the operator once,
+now, as the shared reference linked at step 2 describes: the
+operator's four steps, the answer recorded and never asked again, and the bot, the token and
+enabling the channel left to the operator. An agent with neither stops nor notify events skips
+this step.
 
 ## Resilience and autonomy
 
@@ -239,12 +214,6 @@ operator channel answer (step 6); and the exact next command. Never summarize th
 
 ## Dashboard handoff: also for consumers
 
-When handing a registered service dashboard to a person, or writing the generated
-agent's completion/notification instructions, read and apply
-[dashboard links](references/dashboard-links.md): use the host's `open_link`,
-check the target device and host, and run the bundled output gate before delivery.
-An installed host failure never means browser fallback. This applies in Claude
-Code, Codex and other providers; it needs no host-specific hook. MCP unavailable:
-report the unresolved capability or use an approved project resolver; no automatic
-client configuration. Python unavailable: perform the reference's manual checks
-and report the executable gate NOT_RUN. Headless agents need no dashboard.
+When handing a registered service dashboard to a person, or writing the generated agent's
+completion or notification instructions, read and apply [dashboard links](references/dashboard-links.md)
+and run its output gate before delivery, in any host. Headless agents need no dashboard.

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/dashboard-links.md

@@ -83,8 +83,10 @@ or instructions alone do not prove all final answers from every agent are filter
   path is required. Skills must be activated/loaded; install does not intercept every answer.
 - MCP absent: report unresolved host capability once, use the project's approved
   resolver/CLI if available. Do not write machine or agent MCP config automatically.
-- Python absent: perform the comparisons above manually; mark the executable gate
-  NOT_RUN. Do not label the output mechanically validated.
+- Python absent: perform the comparisons above manually, including the gate's own rules (a
+  path with a `.` or `..` segment, an encoded or backslash separator, or a query or fragment
+  name or value that reads as a credential, such as `code`, `key`, `auth` or `api_key`, is
+  refused); mark the executable gate NOT_RUN. Do not label the output mechanically validated.
 
 Syntax is owned by Fabric Dashboards and `@passioncode-ai/fabric-service-host`:
 [ADR-0005](https://github.com/passioncode-ai/fabric-dashboards/blob/51a7a80acf42781d7bec304cc87c655d48cc309b/docs/adr/0005-service-links.md).

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/models-and-providers.md

@@ -87,6 +87,9 @@ change an embedding model without re-indexing every stored vector (search silent
 - **Show spend.** An agent's interface shows spend per day, per provider and per model for 30 days; spend nobody sees
   is spend nobody controls.
 - **Unknown cost is `null`, never 0** (DEC-0087, `fabric-interop/0.2`).
+- **The kit does this for a service.** `fabric_openrouter` (building-fabric-services, references/connectors.md): the
+  key from a named environment variable, the ceiling before every attempt at the full output budget, a receipt per
+  call, empty and `length` answers never returned as success, a fallback of another vendor required.
 - **Attribution is off by default.** A product may send OpenRouter's attribution headers only with its operator's
   setting and only for requests it originates (FAC-SEM-098); an agent a user built keeps the user's own.
 

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/operator-channel-and-repository.md

@@ -0,0 +1,55 @@
+# The operator channel and the repository standard
+
+Shared by `adapting-projects-to-fabric` and `creating-fabric-agents`; the two copies are byte-identical
+(`test/test_shared_references.py`). "The agent" is the provider being adapted or created.
+
+## 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, at the step that links here. 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 follows. Give the operator's four
+steps:
+
+1. create a bot with @BotFather;
+2. put its token into the operator's secret store (Project Observatory where it is installed) 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 to 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 its conformance
+report, and do not ask again; an agent that serves `surfaces.operatorChannel` also shows it as
+`proposal` in its status document. Creating the bot, storing the token and enabling the channel
+are the operator's action: never create the bot, ask for or store the token's value, or enable the
+channel yourself. The default pin carries DEC-0034 and DEC-0035: a served status document is
+checked against the pinned `schemas/operator-channel-status.schema.json`; the channel's runtime
+rules have no probe rule here yet, so report them `NOT_RUN`. An agent with neither stops nor notify
+events skips this.
+
+## The repository standard
+
+For a PassionCode.ai repository, the agent's repository follows the organization's
+[repository standard](https://github.com/passioncode-ai/fabric-workspace/blob/main/knowledge/repository-standard.md)
+(`knowledge/repository-standard.md` in the organization's knowledge base; a clone has it at
+`fabric-workspace/knowledge/`) from its first commit:
+
+- `LICENSE`, `COMMERCIAL-LICENSE.md` and `CLA.md` copied byte for byte from the knowledge base's
+  `templates/`, and `AGPL-3.0-only OR LicenseRef-PassionCode-Commercial` in every manifest and
+  every SKILL.md `license:`; `SECURITY.md` when the repository is public;
+- a README whose first heading is the full name, with `## Quick start for a new teammate`
+  (Install; Configure, key names only; MCP, the registration command and one proving tool call,
+  verified with a real client in a temporary config; Develop) and `## License`;
+- an `AGENTS.md` that opens with the template's *Read first* block and closes with *After work*,
+  and a `CLAUDE.md` whose first line is `@AGENTS.md`.
+
+org-index `scripts/check_format.py` reports 0 findings for it before it is called done. An agent
+someone builds for themselves is not a PassionCode.ai repository: its licence is its owner's
+choice, nothing about it is published or listed by the organization, and none of these files is
+required of it, though the verified MCP quick start is still how anyone learns to drive it.

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/scripts/check_dashboard_link.py

@@ -7,7 +7,7 @@ This is an output correctness gate, not authentication, discovery, or a relay.
 import json
 import re
 import sys
-from urllib.parse import parse_qs, urlsplit
+from urllib.parse import parse_qs, parse_qsl, unquote, urlsplit
 
 
 def require(condition, reason):
@@ -15,6 +15,63 @@ def require(condition, reason):
         raise ValueError(reason)
 
 
+# Credential names and values: the same rules as fabric-button.js (credentialName, secretValue).
+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 = {
+    '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,}'
+                          r'|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})', re.I | re.S)
+LONG_RUN = re.compile(r'[A-Za-z0-9+/=_-]{40,}')
+
+
+def name_words(name):
+    name = re.sub(r'([a-z0-9])([A-Z])', r'\1 \2', name)
+    name = re.sub(r'([A-Z]+)([A-Z][a-z])', r'\1 \2', name)
+    return [w.lower() for w in re.split(r'[\s._-]+', name) if w]
+
+
+def credential_name(name):
+    split = name_words(name)
+    words = set(split) | {w[:-1] for w in split if len(w) > 2 and w.endswith('s')}
+    if words & CREDENTIAL_WORDS:
+        return True
+    if len(split) == 1 and words & set(CREDENTIAL_PAIRS):
+        return True
+    return any(w in words and words & pairs for w, pairs in CREDENTIAL_PAIRS.items())
+
+
+def secret_value(value):
+    long_secret = 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))
+    return bool(JWT_SHAPE.search(value) or SECRET_VALUE.search(value) or long_secret)
+
+
+def carries_credential(text):
+    # A query or fragment whose names or values could be a credential: refused even with an empty value.
+    return (secret_value(text) or secret_value(unquote(text))
+            or any(credential_name(name) or secret_value(name) or secret_value(value)
+                   for name, value in parse_qsl(text, keep_blank_values=True)))
+
+
+def login_path(path):
+    # The path a server routes: refuse what normalises differently in different servers, then compare.
+    decoded = unquote(path)
+    require(not re.search(r'%2f|%5c', path, re.I) and '\\' not in decoded, 'encoded_separator')
+    segments = decoded.split('/')[1:]
+    require(not any(seg in ('.', '..') for seg in segments), 'dot_segment')
+    require(all(seg for seg in segments[:-1]), 'empty_segment')
+    return '/'.join([''] + [seg for seg in segments if seg]).lower() == '/fabric/v1/login'
+
+
 def safe_path(path):
     return (isinstance(path, str) and path.startswith('/') and not path.startswith('//')
             and len(path) <= 2048 and not re.search(r'[\\\x00-\x1f\x7f]', path))
@@ -42,10 +99,14 @@ def check(data):
             and not plain.username and not plain.password, 'invalid_http_fallback')
     http_page = plain.path + ('?' + plain.query if plain.query else '') + ('#' + plain.fragment if plain.fragment else '')
     require(safe_path(http_page) and http_page == (page or '/'), 'mismatched_page')
-    sensitive = {'token', 'access_token', 'refresh_token', 'password', 'secret', 'login_code'}
-    page_query = parse_qs(urlsplit(http_page).query)
-    require(not sensitive.intersection(k.lower() for k in page_query), 'credential_query')
-    require(urlsplit(http_page).path != '/fabric/v1/login', 'login_link_is_not_dashboard')
+    sensitive = {'token', 'access_token', 'refresh_token', 'password', 'secret', 'login_code', 'code', 'api_key',
+                 'apikey', 'key', 'auth'}
+    parts = urlsplit(http_page)
+    places = [parts.query, parts.fragment] + parts.fragment.split('?', 1)[1:]
+    require(not any(sensitive.intersection(k.lower() for k in parse_qs(p, keep_blank_values=True)) for p in places),
+            'credential_query')
+    require(not any(carries_credential(p) for p in places), 'credential_query')
+    require(not login_path(parts.path), 'login_link_is_not_dashboard')
     state = host.get('state')
     require(state in ('available', 'not_installed', 'unknown', 'incompatible', 'handler_mismatch', 'unsupported'), 'unknown_host_state')
     target, viewer = data.get('target_device'), data.get('viewer_device')

package/plugins/fabric-agent-adapter/skills/working-with-fabric/SKILL.md

@@ -19,7 +19,7 @@ compatibility: >-
   this plugin; Codex/Kimi use command hooks; Hermes/OpenCode/OpenClaw/Pi use native context plugins after opt-in.
 metadata:
   author: PassionCode.ai
-  version: "0.39.1"
+  version: "0.41.0"
 ---
 
 # Working with Fabric
@@ -225,8 +225,8 @@ and do the work without claiming Fabric saw it.
 In Claude Code this plugin ships four: at session start and `/clear` (not on compact or resume) the preamble above,
 or, when Fabric is down and the project uses Fabric, one line pointing at Step 1; after each turn the turn's facts (HEAD, files changed, lines added
 and removed) and the board's unread count; at each prompt one line only when that count rose; at the end, the
-release of what the session left claimed. The turn, prompt and end hooks act only when the running Fabric advertises
-`session-hooks/1`. All are silent in a session Fabric launched, never block the session and read no token. Read
+release of what the session left claimed. The turn, prompt and end hooks spool and call Fabric only when the running
+Fabric advertises `session-hooks/1`; the turn and end hooks always prune their own stale spool. All are silent in a session Fabric launched, never block the session and read no token. Read
 [session hooks](references/session-hooks.md) when a person asks what the hooks do, where they log, how to turn them
 off, or what they need from Fabric.
 

package/plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md

@@ -26,7 +26,7 @@ python3 <skill-dir>/scripts/fabric_session.py install-host-hooks --host opencode
 python3 <skill-dir>/scripts/fabric_session.py install-host-hooks --host opencode --remove
 ```
 
-Use `codex`, `kimi`, `hermes`, `opencode`, `openclaw` or `pi`. Default is a dry run. `--config` overrides the native destination, `--script` selects an absolute `fabric_session.py` in a **complete installed skill**. Keep that path stable; a versioned plugin cache disappears on updates. Reapply after moving the skill. The native installer checks the helper and every required host module before writing a loader.
+Use `codex`, `kimi`, `hermes`, `opencode`, `openclaw` or `pi`. Default is a dry run. `--config` overrides the native destination, `--script` selects an absolute `fabric_session.py` in a **complete installed skill**. Keep that path stable; a versioned plugin cache disappears on updates. Reapply after moving the skill: an install refuses a `--script` that is not an existing file, and Codex and Kimi Code rewrite their own hook in place to the new path (`updated`), finding a Kimi `[[hooks]]` table by the command it runs, not by its exact text. The native installer checks the helper and every required host module before writing a loader. Removal needs neither: it reads nothing from the skill it was installed from, so it works after that skill moved or lost its `hosts/` folder.
 
 | Host | Default destination |
 |---|---|
@@ -45,6 +45,7 @@ OpenCode and Pi loader files carry a managed marker. A foreign file at the same
 
 - Native bridges give the Python helper only a working directory and, when observed, a boolean Fabric registration. Hermes uses its native read-only config, OpenCode its resolved enabled MCP entry, OpenClaw its resolved MCP servers and Pi an exact callable `fabric_whoami` tool name. Config registration is not admission.
 - Missing helper/Python, malformed values, excessive output or a four-second deadline produce no context. Existing host errors and permission failures are not silenced globally.
+- OpenCode and OpenClaw ask for context on every request; their bridges keep the helper's answer per workspace and registration for the life of the host process, so Python runs once, not per request. A failed run (an error, a nonzero exit, a timeout, no `python3`) reads as `null`, distinct from an empty answer `''`, and is not kept, so the next request asks again. A Fabric started later is seen by a new host instance.
 - Fabric-launched sessions are silent. Other native events are not advertised: turn observations, unread counts and rejoin-only release remain Claude-specific and feature-gated.
 - A host in Switchboard's catalog may support MCP, proxy or launch while exposing no startup context hook. Never copy this configuration to another host solely because it can launch an agent.
 

package/plugins/fabric-agent-adapter/skills/working-with-fabric/references/session-hooks.md

@@ -20,7 +20,7 @@ need from Fabric. In Claude Code they live in the plugin's `hooks/hooks.json` an
 | Event | When it acts | What it does |
 |---|---|---|
 | SessionStart (`startup`, `clear`; the plugin's matcher, and the script ignores `compact` and `resume` for every host) | Claude Code has an MCP server named `fabric` (local, project or user scope) | Fabric running: adds the preamble: `fabric_whoami` first; `com.status` and `com.list`, `com.read_ack` only what was read; `fabric_work_list`, then `fabric_work_claim`; `fabric_work_release` at the end; ask another Project only through `com.submit`. Fabric down, in a project that uses Fabric (below): one line, skip `fabric_whoami` and the board, start Fabric through the lifecycle broker only if the task needs it. Fabric down anywhere else, or not registered: nothing. |
-| Stop (each turn) | as for SessionStart, and the running Fabric's `hub.json` lists `"session-hooks/1"` in `features` | spools one entry and starts a detached worker that sends `fabric_session_observe {event: "turn", head, filesChanged, linesAdded, linesRemoved, …}`, then reads `com.status` and keeps the unread count in the session's spool (`board.json`) |
+| Stop (each turn) | as for SessionStart, and the running Fabric's `hub.json` lists `"session-hooks/1"` in `features` | measures the turn's facts (HEAD, files changed, lines added and removed: counts and ids only, git sharing 1.5 s), spools them in one entry and starts a detached worker that sends `fabric_session_observe {event: "turn", head, filesChanged, linesAdded, linesRemoved, …}` as stored, then reads `com.status` and keeps the unread count in the session's spool (`board.json`) |
 | UserPromptSubmit | the session's spool holds a count | adds ONE line, `N unread on the project board: com.list`, only when the count rose since the last line; a fall or the same count says nothing. It reads two small files and never calls Fabric. |
 | SessionEnd | as for Stop | spools the end; the worker sends `fabric_work_release {claims: "session", outcome: "let-go", …}`, then `fabric_session_observe {event: "end", reason}`, and removes the session's spool |
 
@@ -31,8 +31,8 @@ outside a checkout; never above it); or a service descriptor whose `source.repos
 `remote.origin.url`. The machine's service descriptors are no longer counted into the session: the host's own
 instructions say how to read Fabric services (since 0.38.0).
 
-Without `session-hooks/1`, Stop and SessionEnd read `hub.json`, return, and write nothing, so UserPromptSubmit has
-nothing to show; `fabric_session.py status` says "Session hooks: inert". That is every Fabric before the release
+Without `session-hooks/1`, Stop and SessionEnd read `hub.json`, return, and spool nothing (they only remove stale
+session folders, below), so UserPromptSubmit has nothing to show; `fabric_session.py status` says "Session hooks: inert". That is every Fabric before the release
 that ships the dependencies below. A board that cannot be read (`unavailable`, a refusal) leaves no count, never a
 zero; a `degraded` board that still gives the count is read.
 
@@ -48,8 +48,10 @@ session id Fabric keeps with the enrollment, which only Claude Code supplies tod
 would add (never a value already in the file) and the `--apply --expect-sha256 <digest>` command. With `--apply` it
 backs the file up (`<file>.<UTC stamp>.bak`, never overwriting an earlier backup), keeps the file's mode, refuses a
 file whose shape is not `{"hooks": {"<Event>": [{"hooks": [...]}]}}` (Codex) or an array of `[[hooks]]` tables
-(Kimi Code, read back with `tomllib`: Python 3.11+), and refuses one that changed since the dry run. `--remove` takes
-the entry out again. Codex may ask the person to trust a new hook (`/hooks`) before it runs. Codex keys that trust by event, group and index, so
+(Kimi Code, read back with `tomllib`: Python 3.11+), and refuses one that changed since the dry run. It refuses a
+`--script` that is not an existing file. Our own entry, found by what it runs (for Kimi Code each `[[hooks]]` table is
+read on its own, so a hand-touched one is still found), is rewritten in place to the new script (`updated`) rather
+than added a second time. `--remove` takes the entry out again, stale or not, and needs no script. Codex may ask the person to trust a new hook (`/hooks`) before it runs. Codex keys that trust by event, group and index, so
 `--remove` names the SessionStart groups after the removed one that it moves, which Codex asks the person to approve
 again. The hook runs the
 `fabric_session.py` of the skills install (`~/.agents/skills/working-with-fabric/`) when there is one, else this
@@ -63,8 +65,10 @@ They consume the same context through their own APIs. They never use the Claude-
 `fabric_session.py watch-mail [--interval 60]` is for an idle Claude Code session waiting on the board; the agent
 starts it under a background watcher. It rejoins the session (`CLAUDE_CODE_SESSION_ID`, or `--session-id`) through
 `fabric-mcp --rejoin-only` for each look, prints one line each time the unread count rises, and waits `interval`
-± 20 % between looks (never under 10 s). While Fabric is down or the board unreadable it says so once and backs off,
-doubling to at most 15 minutes. It exits on its stdin's end (when started with a pipe), SIGTERM, SIGINT or SIGHUP,
+± 20 % between looks (after the jitter never under 10 s and never over 15 minutes). It shares the session's
+once-a-minute rejoin with the Stop worker: a look within a minute of the last rejoin (the worker's `rejoined` mark or
+its own) waits instead, and its own rejoin renews that mark when the session's folder exists. While Fabric is down or
+the board unreadable it says so once and backs off, doubling to at most 15 minutes. It exits on its stdin's end (when started with a pipe), SIGTERM, SIGINT or SIGHUP,
 or when its parent is gone. It refuses to start in a session Fabric launched, and without a `fabric` registration.
 
 ## A session Fabric launched
@@ -78,13 +82,18 @@ only variable names are looked at, never a value (two of them carry the session'
    `<Fabric's folder>/sessions/` (Codex).
 3. Claude Code launched by Fabric has no variable yet: its command line holds `--mcp-config
    <Fabric's folder>/sessions/<id>/mcp.json`. SessionStart, and Stop once per session, look for that in a few
-   ancestor processes (`ps`, bounded to 0.5 s each); only the match is used, nothing is kept or logged.
+   ancestor processes (`ps`, bounded to 0.5 s each); only the match is used, nothing is logged. A match is kept as
+   an empty `launched` file in the session's folder, so the walk runs once and nothing is spooled after it. A `ps`
+   that fails or runs out of time is "unknown", never "not launched": that hook spools nothing (so no worker can
+   release a launched session's claims) and the next one looks again.
 
 ## What they never do
 
 - **Block or slow the session.** Each hook has a 5 s ceiling in `hooks.json`; the script reads a few small files and
-  returns in tens of milliseconds. Every call to Fabric happens in a detached worker with a 10 s deadline. Every
-  hook exits 0, on every path.
+  returns in tens of milliseconds, plus the turn's git facts in Stop and SessionEnd (at most 1.5 s, shared by every
+  git call). Every call to Fabric happens in a detached worker with a 10 s deadline; at its end the worker closes
+  `fabric-mcp`'s stdin and then ends its whole process group, so a wrapper (`npx`, a shell script,
+  `fabric-mcp.cmd`) cannot keep it waiting. Every hook exits 0, on every path.
 - **Read a secret.** The hooks never open Fabric's door token or an enrollment credential; `fabric-mcp` holds
   those. Nothing secret is in argv (the worker's argv is the script and a spool folder) or in the log.
 - **Send or read content.** A turn is the HEAD commit, the number of files that differ from it (untracked included)
@@ -96,8 +105,10 @@ only variable names are looked at, never a value (two of them carry the session'
 - **Rejoin more than once a minute.** Every rejoin spends the agent's Fabric request budget, which every session of
   the machine shares. A turn within 60 s of the session's last successful rejoin (the worker marks it as `rejoined`
   in the session's folder) is spooled and waits for the next worker; the end of a session always starts one (FAA-53).
-- **Retry in a loop.** A refused call is logged by its error code and dropped; an answer that never came is logged
-  as `outcome=unknown`. The calls carry an `idempotencyKey`, so a repeat is the same event.
+- **Retry in a loop.** A refused call, or one answered with a JSON-RPC error, is logged by its error code and its
+  entry dropped; an entry that cannot be read is logged as `outcome=dropped` and dropped. The entries after it, the
+  end's release and the end observation still go out. An answer that never came is logged as `outcome=unknown` and
+  leaves the spool to the next worker. The calls carry an `idempotencyKey`, so a repeat is the same event.
 
 ## Where they log, and how to turn them off
 
@@ -106,7 +117,9 @@ One line per event that did something, never content: `~/Library/Caches/ai.passi
 `%LOCALAPPDATA%\fabric-agent-adapter\hooks.log` (Windows). Mode 0600, rotated at 1 MB to `hooks.log.1`. The
 per-session spool is `sessions/<session id>/` beside it (turn entries capped at 50, `board.json`, `board.shown`; a
 folder untouched for 7 days, whose worker failed or whose session ended without SessionEnd, is removed by the next
-spooling hook),
+Stop or SessionEnd hook, even while the hooks are inert; an end entry whose release or observation got no answer stays
+for the next worker, and the folder goes only once the end is delivered; a stale worker lock is taken by renaming it, never by a
+check and a delete),
 removed at the session's end.
 
 Turn them off with Claude Code's own switch (`/hooks`, or `"disableAllHooks": true` in settings), or remove the