@passioncode-ai/fabric-agent-adapter 0.40.0 → 0.42.1

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.40.0"
+  version: "0.42.1"
   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/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.40.0"
+  version: "0.42.1"
 ---
 
 # 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,9 +20,16 @@ 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 |
+| SessionEnd | as for Stop | spools the end; the worker sends `fabric_work_release {claims: "session", outcome: "let-go", …}` (with `observedAt`, the time the hook fired, where the tool's input schema names it: Fabric 0.3.9 then refuses an end from before the session enrolled), then `fabric_session_observe {event: "end", reason}`, and removes the session's spool. Reason `clear` ends nothing: `/clear` keeps the agent process and its fabric-mcp, so no claim is released and no end observed; turns already spooled still go out (since 0.42.0) |
+
+**A resumed session and a session Fabric does not hold** (since 0.42.0, board thread `02bf19c5`). `claude --resume`
+keeps the session id, so an end that was kept for a retry (its release got no answer) would be delivered to the resumed
+process and release its live claims: the worker drops, with a log line, every end followed by a later turn of the same
+id, and keeps the retry only while the end is the newest entry. When `fabric-mcp --rejoin-only` exits 3 (Fabric 0.3.9:
+no session holds the id), the worker drops the spool, writes a `no-session` mark in the session's folder and logs it
+once; for 15 minutes the hooks spool nothing for that id (an end removes the folder), then one rejoin tries again.
 
 **A project that uses Fabric** (`project_uses_fabric`), cheapest sign first: `fabric` registered at local or project
 scope for the folder (user scope is every folder's, so it says nothing about this one); a `fabric-agent.json`,
@@ -31,8 +38,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 +55,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 +72,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 +89,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 +112,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 +124,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
@@ -121,8 +141,8 @@ launched-session check exact.
 | # | Need | Shape |
 |---|---|---|
 | D1 | `fabric-mcp` enrolls with the runtime session id | for `--runner claude-code`, `runtimeSessionId` = env `CLAUDE_CODE_SESSION_ID` in `fabric.session.enroll {cwd, runtimeSessionId}` (Claude Code 2.1.296 gives MCP stdio servers and Bash commands that variable, equal to the hooks' `session_id`) |
-| D2 | rejoin only | `fabric-mcp --runner claude-code --rejoin-only --runtime-session-id <id>` attaches to that runtime session's live enrolled session; never asks, never mints; otherwise only `fabric_whoami`, as not enrolled |
+| D2 | rejoin only | `fabric-mcp --runner claude-code --rejoin-only --runtime-session-id <id>` attaches to that runtime session's live enrolled session; never asks, never mints; otherwise only `fabric_whoami`, as not enrolled; Fabric 0.3.9 exits 3 at once when no session holds the id |
 | D3 | the flag | `hub.json` `"features": ["session-hooks/1"]` once D1, D2, D4 and D5 ship |
 | D4 | `fabric_session_observe` | `{event: "turn" or "end", runtime: "claude-code", runtimeSessionId, observedAt, head, filesChanged, linesAdded, linesRemoved, reason (end only), idempotencyKey}` → `session.turn.observed@1`, `session.ended@1` |
-| D5 | release a whole session | `fabric_work_release {claims: "session", outcome: "let-go", reason, idempotencyKey}` |
+| D5 | release a whole session | `fabric_work_release {claims: "session", outcome: "let-go", reason, idempotencyKey}`; `observedAt` too where its input schema names it (Fabric 0.3.9: `stale-end` for an end observed before the session enrolled) |
 | D6 | a launched-session marker | `FABRIC_LAUNCHED_SESSION=1` in the environment of every session Fabric launches, whatever its adapter; until then, the inference above |

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session.py

@@ -34,6 +34,8 @@ from fabric_session_env import (  # noqa: F401
     LAUNCH_SIGNALS,
     FABRIC_MARKERS,
     UNREAD_LINE,
+    LAUNCHED_MARK,
+    rejoin_wait,
     _home,
     fabric_root,
     state_root,
@@ -65,12 +67,19 @@ from fabric_session_env import (  # noqa: F401
     lock_held,
     spawn_worker,
     _remove_tree,
+    NO_SESSION_MARK,
+    NO_SESSION_HOLD_S,
+    no_session_held,
 )
 from fabric_session_mcp import (  # noqa: F401
     RUNNER,
     OBSERVE_TOOL,
     RELEASE_TOOL,
     WAITING_TOOL,
+    FACTS_BUDGET_S,
+    FACT_KEYS,
+    JsonRpcError,
+    stored_facts,
     git_facts,
     _count_status,
     McpStdio,
@@ -81,6 +90,8 @@ from fabric_session_mcp import (  # noqa: F401
     board_unread,
     deliver,
     _wait_for_session_tools,
+    NO_SESSION_EXIT,
+    NoSessionError,
 )
 from fabric_session_mail import (  # noqa: F401
     WATCH_MIN_INTERVAL_S,

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session_cli.py

@@ -11,9 +11,12 @@ from pathlib import Path
 from fabric_session_env import (  # noqa: E402 - the kit (FAA-65)
     HOOK_FEATURE,
     HOSTS,
+    LAUNCHED_MARK,
     NATIVE_PLUGIN_HOSTS,
+    REJOIN_MIN_INTERVAL_S,
     SESSION_ID,
     UNREAD_LINE,
+    _remove_tree,
     _write_private,
     claude_registration,
     codex_registered,
@@ -26,15 +29,19 @@ from fabric_session_env import (  # noqa: E402 - the kit (FAA-65)
     locate_hub,
     lock_held,
     log,
+    no_session_held,
     project_uses_fabric,
     prune_stale_sessions,
     read_small,
+    rejoined_recently,
     session_dir,
     spawn_worker,
     spool,
 )
 from fabric_session_mcp import (  # noqa: E402 - the kit (FAA-65)
+    FACTS_BUDGET_S,
     deliver,
+    git_facts,
 )
 from fabric_session_mail import (  # noqa: E402 - the kit (FAA-65)
     watch_mail_cli,
@@ -44,11 +51,6 @@ from fabric_session_hosts import (  # noqa: E402 - the kit (FAA-65)
 )
 
 
-#: A session rejoins at most once in this span (FAA-53): every rejoin spends Fabric's per-agent request budget, which
-#: every session of the machine shares; a turn inside it waits in the spool for the next worker, an end never waits.
-REJOIN_MIN_INTERVAL_S = 60.0
-
-
 PREAMBLE = (
     "[fabric-agent-adapter] Fabric is running and this {host} has its MCP server `fabric` registered. "
     "Registration is not proof of connection or admission. "
@@ -144,15 +146,17 @@ def hook_user_prompt_submit(payload: Dict[str, Any], env: Optional[Dict[str, str
 
 
 def hook_spool(payload: Dict[str, Any], event: str, env: Optional[Dict[str, str]] = None, spawn=spawn_worker) -> str:
-    """Stop (`turn`) and SessionEnd (`end`): spool one entry and start the worker. Returns what happened, for the
-    tests. Nothing runs, and nothing is written, unless the running Fabric advertises `session-hooks/1` and
-    `fabric` is registered — hub.json is read first because it is the cheap check that fails for every Fabric
-    before the one that ships the hooks' dependency (`status` says so: "Session hooks: inert")."""
+    """Stop (`turn`) and SessionEnd (`end`): spool one entry, with the turn's facts measured now, and start the worker.
+    Returns what happened, for the tests. Nothing is spooled and no worker runs unless the running Fabric advertises
+    `session-hooks/1` and `fabric` is registered: hub.json is read first because it is the cheap check that fails for
+    every Fabric before the one that ships the hooks' dependency (`status` says so: "Session hooks: inert"). Stale
+    session folders are pruned before that check, so an inert Fabric does not keep them (FAA-68)."""
     session_id = payload.get("session_id")
     if not isinstance(session_id, str) or not SESSION_ID.fullmatch(session_id):
         return "skipped: no session id"
     if fabric_launched(env):
         return "skipped: launched by Fabric"
+    prune_stale_sessions(env, keep=session_id)
     hub = locate_hub(fabric_root(env=env))
     if hub["state"] != "running":
         return "inert: Fabric is not running"
@@ -162,12 +166,39 @@ def hook_spool(payload: Dict[str, Any], event: str, env: Optional[Dict[str, str]
     if not claude_registration(cwd, env):
         return "skipped: fabric is not registered"
     directory = session_dir(session_id, env)
-    # The ancestor check costs a process-table read or two: only once per session, when its folder is first made.
-    if not directory.is_dir() and launched_by_ancestor(env):
+    if (directory / LAUNCHED_MARK).exists():
+        if event == "end":
+            _remove_tree(directory)
         return "skipped: launched by Fabric"
+    if event == "end" and payload.get("reason") == "clear":
+        # /clear keeps the agent process and its fabric-mcp; Fabric 0.3.9 renames the session to the new id (board
+        # thread 02bf19c5, ask 2). No claim is released and no end observed; turns already spooled still go out.
+        # Spawned even while a worker runs: that one may have read the spool before the last turn landed, and no
+        # later hook comes for this id. The new worker waits for the lock and finds an empty spool at worst.
+        if any(directory.glob("*-turn.json")):
+            spawn(directory)
+        return "skipped: /clear keeps the Fabric session"
+    if no_session_held(directory):
+        # A rejoin found no Fabric session for this id (02bf19c5, ask 4): recorded once, never retried every turn.
+        if event == "end":
+            _remove_tree(directory)
+        return "skipped: Fabric holds no session for it"
+    # The ancestor check costs a process-table read or two: only once per session, when its folder is first made. A
+    # positive answer is kept in the folder; an unknown one (a `ps` that failed) spools nothing, so no worker can
+    # release a launched session's claims, and is asked again at the next hook.
+    if not directory.is_dir():
+        launched = launched_by_ancestor(env)
+        if launched is None:
+            return "skipped: whether Fabric launched this session is unknown"
+        if launched:
+            if event != "end":
+                directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+                _write_private(directory / LAUNCHED_MARK, "")
+            return "skipped: launched by Fabric"
+    # The turn's own facts, measured when it ended (counts and ids only, never a path), not when a worker runs.
     entry = {"event": event, "runtimeSessionId": session_id, "cwd": str(cwd),
-             "observedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
-    prune_stale_sessions(env, keep=session_id)
+             "observedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+             "facts": git_facts(cwd, budget_s=FACTS_BUDGET_S)}
     if event == "end" and isinstance(payload.get("reason"), str):
         entry["reason"] = payload["reason"][:64]
     spool(directory, entry)
@@ -179,15 +210,6 @@ def hook_spool(payload: Dict[str, Any], event: str, env: Optional[Dict[str, str]
     return "spooled: worker started"
 
 
-def rejoined_recently(directory: Path, now: Optional[float] = None) -> bool:
-    """Whether this session's last rejoin succeeded within REJOIN_MIN_INTERVAL_S (the worker marks it)."""
-    try:
-        mark = (directory / "rejoined").stat().st_mtime
-    except OSError:
-        return False
-    return 0 <= (time.time() if now is None else now) - mark < REJOIN_MIN_INTERVAL_S
-
-
 def status(cwd: Path, env: Optional[Dict[str, str]] = None, platform: str = sys.platform) -> Dict[str, Any]:
     root = fabric_root(platform, env)
     binary = find_fabric_bin(platform, env)