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

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.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

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,
@@ -71,6 +73,10 @@ from fabric_session_mcp import (  # noqa: F401
     OBSERVE_TOOL,
     RELEASE_TOOL,
     WAITING_TOOL,
+    FACTS_BUDGET_S,
+    FACT_KEYS,
+    JsonRpcError,
+    stored_facts,
     git_facts,
     _count_status,
     McpStdio,

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,
@@ -29,12 +32,15 @@ from fabric_session_env import (  # noqa: E402 - the kit (FAA-65)
     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 +50,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 +145,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 +165,26 @@ 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"
+    # 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 +196,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)

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

@@ -57,7 +57,7 @@ SESSION_ID = re.compile(r"[A-Za-z0-9._:-]{1,128}")
 LOOPBACK_ORIGIN = re.compile(r"http://127\.0\.0\.1:(\d{1,5})")
 
 
-VERSION = "0.40.0"
+VERSION = "0.41.0"
 
 
 HOSTS = {"claude": "Claude Code", "codex": "Codex", "kimi": "Kimi Code",
@@ -401,24 +401,55 @@ def _process(pid: int) -> Tuple[Optional[str], int]:
         return None, 0
 
 
-def launched_by_ancestor(env: Optional[Dict[str, str]] = None, depth: int = 4) -> bool:
+def launched_by_ancestor(env: Optional[Dict[str, str]] = None, depth: int = 4,
+                         process: Optional[Callable[[int], Tuple[Optional[str], int]]] = None,
+                         platform: str = sys.platform) -> Optional[bool]:
     """A Claude Code Fabric launched runs with `--mcp-config <Fabric>/sessions/<id>/mcp.json` (sessionBundle.ts,
-    adapter mcp-config-flag) and no environment marker yet: look for that in this hook's few ancestors. Only the
-    path is matched; nothing read here is kept or logged."""
+    adapter mcp-config-flag) and no environment marker yet: look for that in this hook's few ancestors. True or False
+    once the walk is done; None when a process could not be read (a `ps` that failed or ran out of time), which is
+    "unknown", never "not launched" (FAA-68). Windows has no walk (`_process` reads no process there): False, so
+    only the environment signals count. Only the path is matched; nothing read here is kept or logged."""
+    if process is None and platform == "win32":
+        return False
     marker = os.path.normpath(str(fabric_root(env=env) / "sessions")) + os.sep
+    process = process or _process
     pid = os.getppid()
     for _ in range(depth):
         if pid <= 1:
             return False
-        command, parent = _process(pid)
+        command, parent = process(pid)
         if command is None:
-            return False
+            return None
         if "--mcp-config" in command and marker in command:
             return True
         pid = parent
     return False
 
 
+#: 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. The Stop worker and watch-mail both honour and renew the mark (FAA-68).
+REJOIN_MIN_INTERVAL_S = 60.0
+
+
+#: The file in a session's folder that says Fabric launched it: the ancestor walk ran once and found the launcher.
+LAUNCHED_MARK = "launched"
+
+
+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)."""
+    return rejoin_wait(directory, now) > 0
+
+
+def rejoin_wait(directory: Path, now: Optional[float] = None) -> float:
+    """Seconds until this session may rejoin again; 0 when it may now."""
+    try:
+        mark = (directory / "rejoined").stat().st_mtime
+    except OSError:
+        return 0.0
+    age = (time.time() if now is None else now) - mark
+    return REJOIN_MIN_INTERVAL_S - age if 0 <= age < REJOIN_MIN_INTERVAL_S else 0.0
+
+
 def log(line: str, env: Optional[Dict[str, str]] = None) -> None:
     """One structured line, 0600, rotated at 1 MB. Never raises."""
     try:

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 import hashlib
 import json
 import os
+import re
 import sys
 import time
 from pathlib import Path
@@ -101,6 +102,52 @@ def _kimi_block(command: str) -> str:
             "[[hooks]]\nevent = \"SessionStart\"\ncommand = %s\ntimeout = 5\n" % json.dumps(command))
 
 
+_KIMI_COMMENT = _kimi_block("").split("[[hooks]]", 1)[0].lstrip("\n").splitlines(True)  # our two comment lines
+
+
+def _kimi_spans(text: str, host: str) -> List[Tuple[int, int]]:
+    """Where each `[[hooks]]` table whose command is ours sits in `text`, as line ranges [header, end). A table ends at
+    the next header; trailing blank and comment lines belong to what follows. Each table is read on its own with
+    tomllib, so a hand-touched table (another order, a comment, another timeout) is still found by what it runs."""
+    lines = text.splitlines(True)
+    headers = [i for i, line in enumerate(lines) if line.startswith("[")]
+    spans = []
+    for n, start in enumerate(headers):
+        if not re.match(r"\[\[\s*hooks\s*\]\]\s*(#.*)?\Z", lines[start].rstrip("\r\n")):
+            continue
+        end = headers[n + 1] if n + 1 < len(headers) else len(lines)
+        while end > start + 1 and (not lines[end - 1].strip() or lines[end - 1].lstrip().startswith("#")):
+            end -= 1
+        try:
+            table = tomllib.loads("".join(lines[start:end]))["hooks"][0]
+        except (ValueError, KeyError, IndexError, TypeError):
+            continue
+        if isinstance(table, dict) and _is_ours(table.get("command"), host):
+            spans.append((start, end))
+    return spans
+
+
+def _kimi_edit(text: str, host: str, command: Optional[str]) -> str:
+    """`text` with our one `[[hooks]]` table pointed at `command`, or taken out (None) with the comment lines and the
+    blank line `_kimi_block` put before it. Refused when there is not exactly one."""
+    spans = _kimi_spans(text, host)
+    if len(spans) != 1:
+        raise Refused("found %d Fabric hook tables to edit; remove the extra ones by hand" % len(spans))
+    lines = text.splitlines(True)
+    start, end = spans[0]
+    if command is not None:
+        found = [i for i in range(start + 1, end) if re.match(r"\s*command\s*=", lines[i])]
+        if len(found) != 1:
+            raise Refused("the Fabric hook's command could not be found line by line; edit it by hand")
+        lines[found[0]] = "command = %s\n" % json.dumps(command)
+        return "".join(lines)
+    if lines[max(0, start - len(_KIMI_COMMENT)):start] == _KIMI_COMMENT:
+        start -= len(_KIMI_COMMENT)
+    if start > 0 and lines[start - 1] == "\n":
+        start -= 1
+    return "".join(lines[:start] + lines[end:])
+
+
 def _replace_file(path: Path, data: bytes, seen: Optional[bytes]) -> Optional[Path]:
     """Back the file up, then write `data` atomically with the file's own mode. Refused when the file changed
     since it was read. Returns the backup."""
@@ -163,9 +210,14 @@ def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] =
         path = Path(env.get("CODEX_HOME") or str(_home(env) / ".codex")) / "hooks.json"
     else:
         path = _home(env) / ".kimi-code" / "config.toml"
-    command = hook_command(str(args.script or default_hook_script(env)), args.host)
+    script = Path(args.script).expanduser().absolute() if args.script else default_hook_script(env)
+    command = hook_command(str(script), args.host)
     shifted = 0  # Codex hook groups after ours, whose position a removal moves
+    updated = False  # our own hook was there with another command, and is rewritten (FAA-69)
     try:
+        if not args.remove and not script.is_file():
+            # A hook pointing at nothing fails at every session start; removal needs no script.
+            raise Refused("--script %s is not a file; pass the fabric_session.py of a complete installed skill" % script)
         data = _read_bytes(path)
         digest = _digest(data)
         if args.expect_sha256 and args.expect_sha256 != digest:
@@ -201,37 +253,43 @@ def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] =
                     out("install-host-hooks: the Fabric preamble hook is already in %s; nothing to change" % path)
                     return 0
                 owned[0]["command"] = command
+                updated = True
                 new = (json.dumps(doc, indent=2) + "\n").encode("utf-8")
             else:
                 doc.setdefault("hooks", {}).setdefault("SessionStart", []).append(entry)
                 new = (json.dumps(doc, indent=2) + "\n").encode("utf-8")
-            change = "remove from hooks.SessionStart" if args.remove else "add to hooks.SessionStart"
+            change = ("remove from" if args.remove else "update in" if updated else "add to") + " hooks.SessionStart"
             shown = json.dumps(entry, indent=2)
         else:
             block = _kimi_block(command)
             text = (data or b"").decode("utf-8", "replace")
-            if not (args.apply or args.remove):
-                present = tomllib is not None and any(_is_ours(h.get("command"), args.host) for h in _kimi_hooks(data))
-            else:
-                present = any(_is_ours(h.get("command"), args.host) for h in _kimi_hooks(data))
+            # Our table is found by what it runs (_is_ours), not by its exact text, so a stale path is repaired and a
+            # hand-touched table is still removed (FAA-69). A dry run without a TOML reader shows the plain append.
+            readable = tomllib is not None or args.apply or args.remove
+            owned = [h for h in _kimi_hooks(data) if _is_ours(h.get("command"), args.host)] if readable else []
+            if len(owned) > 1:
+                raise Refused("multiple Fabric hooks are configured in %s; remove the extra ones by hand" % path)
             if args.remove:
-                if not present:
+                if not owned:
                     out("install-host-hooks: no Fabric preamble hook in %s; nothing to change" % path)
                     return 0
-                if block not in text:
-                    raise Refused("the Fabric hook in %s was edited by hand; remove its [[hooks]] table yourself" % path)
-                new_text = text.replace(block, "", 1)
-            elif present:
+                new_text = _kimi_edit(text, args.host, None)
+            elif owned and owned[0].get("command") == command:
                 out("install-host-hooks: the Fabric preamble hook is already in %s; nothing to change" % path)
                 return 0
+            elif owned:
+                new_text = _kimi_edit(text, args.host, command)
+                updated = True
             else:
                 new_text = text + ("" if not text or text.endswith("\n") else "\n") + block
             new = new_text.encode("utf-8")
             if args.apply or args.remove:
                 after = _kimi_hooks(new)
-                if len(after) != len(_kimi_hooks(data)) + (-1 if args.remove else 1):
+                mine = [h.get("command") for h in after if _is_ours(h.get("command"), args.host)]
+                growth = -1 if args.remove else 0 if updated else 1
+                if len(after) != len(_kimi_hooks(data)) + growth or mine != ([] if args.remove else [command]):
                     raise Refused("the edited file would not read back as expected; nothing was changed")
-            change = "remove from" if args.remove else "append to"
+            change = "remove from" if args.remove else "update in" if updated else "append to"
             shown = block.strip("\n")
         if not (args.apply or args.remove):
             out("install-host-hooks: dry run, nothing is written.")
@@ -248,6 +306,7 @@ def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] =
             return 0
         backup = _replace_file(path, new, data)
         out("install-host-hooks: %s %s %s." % ("removed the Fabric preamble hook from" if args.remove
+                                              else "updated the Fabric preamble hook in" if updated
                                               else "added the Fabric preamble hook to", path,
                                               "(backup: %s)" % backup if backup else "(new file)"))
         out("Undo: fabric_session.py install-host-hooks --host %s %s" % (args.host, "--apply" if args.remove else "--remove"))