swarph-cli 0.61.0__tar.gz → 0.63.0__tar.gz

{swarph_cli-0.61.0/src/swarph_cli.egg-info → swarph_cli-0.63.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.61.0
+Version: 0.63.0
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -148,6 +148,7 @@ swarph guide                      # the whole guide
 swarph guide channels             # one topic
 swarph guide --list               # every topic, with the commands it teaches
 swarph guide --search subscribe   # find a topic by INTENT, not by its name
+swarph guide doctrine             # the standard of evidence a cell is held to (v0.63.0)
 ```
 
 Three ways in, because a new cell does not know which word it has:

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/README.md

@@ -100,6 +100,7 @@ swarph guide                      # the whole guide
 swarph guide channels             # one topic
 swarph guide --list               # every topic, with the commands it teaches
 swarph guide --search subscribe   # find a topic by INTENT, not by its name
+swarph guide doctrine             # the standard of evidence a cell is held to (v0.63.0)
 ```
 
 Three ways in, because a new cell does not know which word it has:

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.61.0"
+version = "0.63.0"
 description = "The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }
@@ -146,6 +146,7 @@ swarph_cli = ["systemd/*.service", "systemd/*.timer", "systemd/*.default",
               "systemd/*.path",
               "scripts/*.sh", "scripts/*.ps1", "guide/*.md",
               "payloads/postcompact/*.sh", "payloads/postcompact/*.cmd",
+              "payloads/opencode/*.js",
     "skills/*/SKILL.md", "skills/*/LICENSE"]
 # v0.15: ship the bundled mesh-gateway schema so `swarph gateway serve`
 # can apply it at startup via MESH_SCHEMA_PATH (defaults next to server.py).

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.61.0"
+__version__ = "0.63.0"
 
 __all__ = ["__version__"]

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/src/swarph_cli/cell.py

@@ -66,7 +66,7 @@ _validate_uuid = validate_uuid_str  # historical helper name
 # ONE swarph-cli release, and entry into swarph_shared.VALID_PROVIDERS only in a
 # later one. spawn.py's guard is `VALID_PROVIDERS ⊆ MEMBRANES`, so this direction
 # is inert while the reverse raises at import for every fresh install (#247).
-CLI_ENABLED_PROVIDERS = VALID_PROVIDERS | {"muse", "cursor"}
+CLI_ENABLED_PROVIDERS = VALID_PROVIDERS | {"muse", "cursor", "opencode"}
 
 
 def _config_root() -> Path:

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/src/swarph_cli/commands/board.py

@@ -390,8 +390,38 @@ def _thread_url(gateway: str, card_id: int, *, limit: Optional[int] = None) -> s
     return f"{base}?limit={limit}" if limit else base
 
 
-def _thread_recipient(card: dict, explicit_to: Optional[str]) -> str:
-    """Who a card-thread post is addressed to. `--to` wins, else the assignee.
+def _project_owner_orchestrator(gw: str, token: str, project_id) -> Optional[str]:
+    """Resolve ``projects.owner_orchestrator`` for a card's project_id.
+
+    >>> THE CARD PAYLOAD DOES NOT CARRY THE OWNER (#864). <<< Measured
+    2026-09-17: GET /board/cards/{id} has assignee/project_id and no owner
+    field; GET /board/projects rows carry ``owner_orchestrator`` (NOT NULL on
+    the server). A second call is required — inventing a sentinel peer is the
+    #259 failure mode this helper exists to avoid.
+    """
+    if project_id is None:
+        return None
+    st, data = _http_get_json(f"{gw.rstrip('/')}/board/projects", token)
+    if st != 200:
+        return None
+    rows = data if isinstance(data, list) else (data or {}).get("projects", [])
+    for row in rows or []:
+        if row.get("id") == project_id or str(row.get("id")) == str(project_id):
+            owner = (row.get("owner_orchestrator") or "").strip()
+            return owner or None
+    return None
+
+
+def _thread_recipient(
+    card: dict,
+    explicit_to: Optional[str],
+    *,
+    owner_orchestrator: Optional[str] = None,
+) -> "tuple[str, str]":
+    """Who a card-thread post is addressed to, and why.
+
+    Order: ``--to`` > card assignee > project ``owner_orchestrator`` (#864).
+    Returns ``(to_node, reason)`` so the confirmation line can name the choice.
 
     >>> RAISES RATHER THAN INVENTING A SENTINEL. <<< POST /messages requires
     exactly one of {to_node, channel}, so a card post needs a real recipient. The
@@ -401,18 +431,21 @@ def _thread_recipient(card: dict, explicit_to: Optional[str]) -> str:
     A placeholder here would manufacture that defect once per card post.
     """
     if explicit_to:
-        return explicit_to
+        return explicit_to, "--to"
     assignee = card.get("assignee")
     if assignee:
-        return assignee
+        return assignee, "card assignee"
+    if owner_orchestrator:
+        return owner_orchestrator, "project owner_orchestrator"
     raise RuntimeError(
-        f"card #{card.get('id')} has no assignee, so there is no default recipient "
-        f"for a thread post — pass --to <peer>. (A card post is still a DM on the "
-        f"wire; it needs someone to be addressed to.)"
+        f"card #{card.get('id')} has no assignee and project owner_orchestrator "
+        f"is unresolvable, so there is no default recipient for a thread post — "
+        f"pass --to <peer>. (A card post is still a DM on the wire; it needs "
+        f"someone to be addressed to.)"
     )
 
 
-def _say_line(resp: dict, card_id, to_node: str) -> str:
+def _say_line(resp: dict, card_id, to_node: str, *, reason: Optional[str] = None) -> str:
     """The post confirmation — AND any obligation the post just DISCHARGED.
 
     >>> THE GATEWAY ALREADY SAID SO AND THIS CLI THREW IT AWAY. <<< POST
@@ -435,7 +468,11 @@ def _say_line(resp: dict, card_id, to_node: str) -> str:
     POLICY (that is #562's own question) -- it is the fix for the holder not
     being told, which is what made six hours of divergence possible.
     """
-    line = f"posted id={resp.get('id')} onto card #{card_id} (to {to_node})"
+    if reason:
+        line = (f"posted id={resp.get('id')} onto card #{card_id} "
+                f"(to {to_node}; {reason})")
+    else:
+        line = f"posted id={resp.get('id')} onto card #{card_id} (to {to_node})"
     closed = resp.get("closed_obligations") or []
     if closed:
         ids = ", ".join(f"#{i}" for i in closed)
@@ -855,7 +892,8 @@ def _build_parser() -> argparse.ArgumentParser:
     add_content_args(cy)
     cy.add_argument("--kind", default="fyi", help="status|question|answer|unblock|fyi")
     cy.add_argument("--to", dest="to_node", default=None,
-                    help="recipient peer (default: the card's assignee)")
+                    help="recipient peer (default: card assignee, else project "
+                         "owner_orchestrator; refused if neither resolves)")
     _add_common(cy)
 
     ck = cards.add_parser(
@@ -1278,8 +1316,15 @@ def run_board(argv: list[str]) -> int:
                       f"(it predates #181a). Run scripts/migrate_card_threads.py on "
                       f"the gateway host.", file=sys.stderr)
                 return 1
+            # #864: card GET has no owner field — only fetch projects when the
+            # cheaper defaults (explicit --to, card assignee) are absent.
+            owner = None
+            if not args.to_node and not card.get("assignee"):
+                owner = _project_owner_orchestrator(gw, token, card.get("project_id"))
             try:
-                to_node = _thread_recipient(card, args.to_node)
+                to_node, reason = _thread_recipient(
+                    card, args.to_node, owner_orchestrator=owner,
+                )
             except RuntimeError as exc:
                 print(f"swarph board cards say: {exc}", file=sys.stderr)
                 return 1
@@ -1293,7 +1338,9 @@ def run_board(argv: list[str]) -> int:
             # explicit `propose` grant. `_out` passes `detail` through whole; it does
             # not need help, and a second copy of that logic is a second thing to
             # keep in sync.
-            return _out(st, d, lambda x: _say_line(x, args.id, to_node), aj)
+            return _out(
+                st, d, lambda x: _say_line(x, args.id, to_node, reason=reason), aj,
+            )
         if args.command == "ready":
             st, d = _patch_json(f"{gw}/board/cards/{args.id}", {"actor": self_name, "move_ready": not args.clear}, token)
             return _out(st, d, lambda x: f"card #{x.get('id')} move_ready -> {x.get('move_ready')}", aj)

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/src/swarph_cli/commands/codegraph.py

@@ -37,12 +37,65 @@ import sys
 from swarph_cli.commands.codegraph_hook import _match_quality
 
 DEFAULT_INDEX = os.path.expanduser("~/.swarph/codegraph/index.db")
-# NOTE: named DEFAULT_CALLER_CELL, not "*_CALLER" — this is an A8 caller-CELL
-# identity (sensitivity-gate scoping), not a SwarphCall `role.subrole.specific`
-# caller tag, and must NOT trip the repo-wide caller-convention meta-guard
-# (tests/test_caller_meta_guard.py) which validates every `*_CALLER` constant
-# against that unrelated dotted-slug convention.
-DEFAULT_CALLER_CELL = "lab-ovh"
+# >>> THERE IS NO DEFAULT IDENTITY ANY MORE. THIS CONSTANT IS GONE ON PURPOSE. <<<
+#
+# It used to read `DEFAULT_CALLER_CELL = "lab-ovh"`, and that one line meant every
+# unconfigured caller on lab-ovh queried with the ORCHESTRATOR'S READ AUTHORITY.
+#
+# MEASURED 2026-09-18 (science-claude, mesh 43183/43186/43188). The gateway was never
+# bypassed and nothing was ever spoofed: `_query_via_gateway` sends NO caller field, so
+# the server binds identity from the bearer token, correctly. What the default did was
+# pick WHICH REAL TOKEN got presented — `_resolve_token(self_name, ...)` reads the file
+# that name points at. A cell asking a question on this box authenticated AS lab-ovh,
+# with lab-ovh's genuine credential, and got a full, plausible, correctly-authorised
+# answer belonging to somebody else.
+#
+# >>> A WRONG-IDENTITY WRITE ANNOUNCES ITSELF — a DM arrives signed by the wrong cell
+# and someone notices. A WRONG-IDENTITY READ ANNOUNCES NOTHING. <<< It was found only
+# because a repo its owner KNEW they owned was missing from their own results.
+#
+# WHY REFUSE RATHER THAN WARN (commander, 2026-09-18 04:44Z): a warning on a read that
+# returns a correct-looking answer is a line of text above a result the caller already
+# believes. And the cost of refusing was measured first, not assumed — of 8 executable
+# `swarph` invocations in systemd + cron on lab-ovh, 7 already pass `--as` or
+# `--token-file`, and the 8th (`monitor reexec-on-change`) cannot authenticate at all:
+# no --gateway, no --token-file, no --as exists on that verb. SCHEDULED WORK BREAKS IN
+# ZERO PLACES. The population that pays is interactive use, which is the population
+# that was silently mis-attributed.
+#
+# $SWARPH_SELF STILL WORKS AND IS THE INTENDED PATH. It is a DECLARED identity. What is
+# refused is the *undeclared* case, where a package-level guess stood in for one.
+IDENTITY_UNSET = object()  # sentinel: argparse default when --caller-cell is omitted
+
+
+class IdentityNotDeclared(RuntimeError):
+    """No caller identity was declared and there is no default to fall back to."""
+
+
+def require_caller_cell(explicit=None, *, verb: str) -> str:
+    """Resolve the caller cell, or REFUSE.
+
+    Order: explicit flag -> $SWARPH_SELF -> $SWARPH_CELL -> refuse.
+
+    The refusal names the verb and every way to satisfy it, because an error that
+    says only "identity unset" moves the work to the reader.
+    """
+    if explicit not in (None, IDENTITY_UNSET) and str(explicit).strip():
+        return str(explicit).strip()
+    for var in ("SWARPH_SELF", "SWARPH_CELL"):
+        v = (os.environ.get(var) or "").strip()
+        if v:
+            return v
+    raise IdentityNotDeclared(
+        f"swarph {verb}: NO CALLER IDENTITY DECLARED, and there is no default.\n"
+        f"  This used to fall back to 'lab-ovh', which meant an undeclared caller\n"
+        f"  queried with that cell's read authority and got somebody else's answer.\n"
+        f"  Declare one of:\n"
+        f"    --caller-cell <cell>      for this invocation\n"
+        f"    SWARPH_SELF=<cell>        for this shell or unit\n"
+        f"    SWARPH_CELL=<cell>        (MCP hosts)\n"
+        f"  It is NOT guessable: this box hosts several cells under one uid."
+    )
 
 # NOT 1 and NOT 2. A distinct code so "nothing was searched" can never be confused
 # with a crash or a usage error, and so a caller can branch on it specifically.
@@ -332,7 +385,7 @@ def _query_via_gateway(gateway: str, query: str, limit: int, token_file):
     from swarph_cli.commands.mesh import _post_json, _resolve_token  # local import: keeps
     # the local-only path free of any mesh dependency, so an offline cell still works.
 
-    self_name = os.environ.get("SWARPH_SELF") or DEFAULT_CALLER_CELL
+    self_name = require_caller_cell(verb="codegraph")
     token = _resolve_token(self_name, token_file)
     body = {"query": query, "limit": max(1, min(int(limit), 25))}
     status, payload = _post_json(gateway.rstrip("/") + "/codegraph", body, token)
@@ -352,7 +405,9 @@ def run_codegraph(argv) -> int:
                     "is configured (the server searches and returns the answer); falls back to a local index.")
     ap.add_argument("query", help="natural-language query, e.g. 'which function escapes HTML'")
     ap.add_argument("--index", default=DEFAULT_INDEX, help=f"index db (default {DEFAULT_INDEX})")
-    ap.add_argument("--caller-cell", default=DEFAULT_CALLER_CELL, help="A8 caller identity (default lab-ovh)")
+    ap.add_argument("--caller-cell", default=IDENTITY_UNSET,
+                    help="A8 caller identity. NO DEFAULT — else $SWARPH_SELF / $SWARPH_CELL, "
+                         "else the command REFUSES rather than guessing (it used to guess lab-ovh).")
     ap.add_argument("--limit", type=int, default=8)
     ap.add_argument("--json", action="store_true", help="machine-readable JSON output")
     ap.add_argument("--gateway", default=None,

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/src/swarph_cli/commands/guide.py

@@ -130,6 +130,38 @@ def _commands_in(section: str) -> "list[str]":
     return out
 
 
+def verbs_in_guide(topics: "dict[str, str] | None" = None) -> "set[str]":
+    """#547: the verbs the guide TEACHES, counted PER VERB (a topic count said 11 and
+    meant nothing). A verb is covered when some section's commands include it."""
+    topics = topics if topics is not None else _split_topics(_load_guide())
+    out: set[str] = set()
+    for body in topics.values():
+        for cmd in _commands_in(body):
+            parts = cmd.split()
+            if len(parts) >= 2:
+                out.add(parts[1])
+    return out
+
+
+def _registry() -> "list[str]":
+    # Lazy: main dispatches handlers by dotted path and does not import this module,
+    # but keep the direction one-way anyway.
+    from swarph_cli.main import registered_verbs
+    return registered_verbs()
+
+
+def _verb_entry(topics: "dict[str, str]", verb: str) -> "list[tuple[str, str]]":
+    """The line in each topic that teaches `swarph <verb>` -- one per topic, first hit."""
+    pat = re.compile(r"`swarph " + re.escape(verb) + r"(?:[ `])")
+    hits: list[tuple[str, str]] = []
+    for name, body in topics.items():
+        for raw in body.splitlines():
+            if pat.search(raw):
+                hits.append((name, raw.strip()))
+                break
+    return hits
+
+
 _TERM_RE = re.compile(r"\*\*(.+?)\*\*")
 
 
@@ -262,13 +294,21 @@ def run_guide(argv: "list[str]") -> int:
         # `apropos`: an LLM arrives with an INTENT ("subscribe to updates"), not the
         # topic's name ("channels"). Requiring the name is the #520 discovery defect
         # reproduced inside its own fix.
+        term = args.search.strip().lower()
+        # #547: a VERB name resolves to the verb's own entry first -- `--search highlight`
+        # used to answer with a topic list that did not contain it.
+        verb_hits = _verb_entry(topics, term) if term in _registry() else []
         hits = _search(topics, args.search)
-        if not hits:
+        if not hits and not verb_hits:
             print_safe(f"swarph guide: nothing matches {args.search!r}. "
                        f"Topics: {', '.join(topics)}", stream=sys.stderr)
             return 2
-        for name, line in hits:
+        for name, line in verb_hits:
             print_safe(f"{name:<22} {line}")
+        shown = {name for name, _ in verb_hits}
+        for name, line in hits:
+            if name not in shown:
+                print_safe(f"{name:<22} {line}")
         return 0
 
     if not args.topic:
@@ -279,6 +319,19 @@ def run_guide(argv: "list[str]") -> int:
     if key in topics:
         print_safe(topics[key])
         return 0
+    if key in _registry():
+        # #547: every registered verb resolves, per verb (tests/test_547 pins the set):
+        # the lines that teach it, then -- when the name is also a topic's substring
+        # (`channel` -> channels) -- that one topic, as before.
+        for name, line in _verb_entry(topics, key):
+            print_safe(f"{name:<22} {line}")
+        near = [k for k in topics if key in k]
+        if len(near) == 1:
+            print_safe("")
+            print_safe(topics[near[0]])
+        else:
+            print_safe(f"\n  more:  swarph {key} --help")
+        return 0
 
     # Substring fallback before failing: `swarph guide channel` should find `channels`.
     hits = [k for k in topics if key in k]

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/src/swarph_cli/commands/init.py

@@ -37,6 +37,7 @@ _LLM_BLURBS = {
     "grok": "xAI Grok — grok membrane",
     "muse": "Muse — muse membrane",
     "vibe": "Vibe — vibe membrane",
+    "opencode": "OpenCode — opencode membrane (XDG config+data isolation)",
 }
 
 

swarph_cli-0.63.0/src/swarph_cli/commands/install_opencode_plugin.py

@@ -0,0 +1,173 @@
+"""``swarph install-opencode-plugin`` — the OpenCode plugin that wires swarph hooks.
+
+Part 2 of the opencode membrane. opencode has NO command-hook surface — its only
+hook surface is a JavaScript plugin loaded from the config dir's ``plugins/``
+tree (auto-loaded, no ``opencode.json`` ``plugin`` entry required; measured:
+``~/.config/opencode/plugin/opensling.js`` loads against a config containing only
+``$schema``). This verb renders the package payload (baking the pinned Python
+interpreter, the same reason ``install_codex_hooks`` pins it: PATH presence is
+not a liveness proof) and writes it as ``swarph-opencode.js``:
+
+* ``--scope user``    → ``~/.config/opencode/plugins/swarph-opencode.js`` —
+  the OPERATOR's bare ``opencode`` sessions (outside a swarph cell).
+* ``--scope project`` → ``<cwd>/.opencode/plugins/swarph-opencode.js`` — a
+  per-project wiring.
+
+The swarph CELL does NOT read either of those locations: its membrane relocates
+``XDG_CONFIG_HOME`` to ``<cwd>/.opencode-cell/config``, so its plugin lives at
+``<cwd>/.opencode-cell/config/opencode/plugins/swarph-opencode.js`` and is
+written by the membrane's ``_opencode_env`` via ``ensure_cell_plugin`` — a
+spawned cell is wired without a separate onboarding step.
+
+Identity (SWARPH_SELF / SWARPH_MEMORY_DIR) is read by the plugin from env AT
+RUNTIME, not baked — the membrane already stamps SWARPH_SELF into the cell env,
+and a bare-session install inherits the operator's env at hook time.
+
+Idempotent, ``--uninstall``, ``--dry-run``, write-landed assert — the same
+operator contract as every other hook installer (#527 task 3).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib import resources
+from pathlib import Path
+
+from swarph_cli.cell import _atomic_write_text
+
+_PAYLOAD = "swarph_cli.payloads.opencode"
+_PLUGIN_NAME = "swarph-opencode.js"
+
+
+def _payload_text() -> str:
+    """Read the plugin FROM THE PACKAGE — never a source-tree path, so tests
+    exercise the same importlib.resources lookup an installed wheel depends on
+    (the 0.39.3 undeclared-package-data lesson)."""
+    return resources.files(_PAYLOAD).joinpath("plugin.js").read_text(encoding="utf-8")
+
+
+def _render_plugin(interpreter: str) -> str:
+    r"""Render the plugin with @PYTHON@ replaced by ``interpreter`` AS A JS STRING.
+
+    >>> shlex.quote is WRONG here, and it was the shipped defect (#423 review).
+    The placeholder sits on the RHS of ``const PY = @PYTHON@;`` — a JavaScript
+    string literal position, NOT shell text. ``shlex.quote`` wraps in single
+    quotes and leaves backslashes raw, so on Windows
+    ``C:\Program Files\Python\python.exe`` became
+    ``const PY = "'C:\Program Files\Python\python.exe'";`` — invalid escapes, and
+    the single quotes land INSIDE the double quotes, so the value is a wrong path
+    even where it parses. json.dumps produces a valid JS string literal (double
+    quoted, backslashes escaped as ``\\``), which a JS parser accepts and decodes
+    back to the exact path. The template leaves the quotes to the substitution
+    (``const PY = @PYTHON@;``) so they are never doubled. <<<
+    """
+    return _payload_text().replace("@PYTHON@", json.dumps(interpreter))
+
+
+def _render() -> str:
+    """The rendered plugin, with @PYTHON@ pinned to THIS interpreter."""
+    return _render_plugin(str(Path(sys.executable).resolve()))
+
+
+def _target(scope: str) -> Path:
+    if scope == "project":
+        return Path.cwd() / ".opencode" / "plugins" / _PLUGIN_NAME
+    return Path.home() / ".config" / "opencode" / "plugins" / _PLUGIN_NAME
+
+
+def cell_plugin_path(cwd: Path) -> Path:
+    """Where a cell's plugin lives inside its isolated config dir.
+
+    Mirrors ``_OPENCODE_CELL_SUBDIR`` + the XDG_CONFIG_HOME layout the membrane
+    sets in ``_opencode_env`` — kept here (not imported from spawn) so spawn can
+    call back into it without a cycle.
+    """
+    return cwd / ".opencode-cell" / "config" / "opencode" / "plugins" / _PLUGIN_NAME
+
+
+def ensure_cell_plugin(cwd: Path) -> None:
+    """Write the cell's plugin if absent or changed. Idempotent + best-effort:
+    a failure must not block the spawn (worst case the cell runs unhooked)."""
+    try:
+        rendered = _render()
+        target = cell_plugin_path(cwd)
+        if target.exists() and target.read_text(encoding="utf-8") == rendered:
+            return
+        target.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write_text(target, rendered)
+    except Exception:
+        pass
+
+
+def _read_existing(target: Path) -> str:
+    return target.read_text(encoding="utf-8") if target.exists() else ""
+
+
+def run_install_opencode_plugin(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[2:]
+
+    p = argparse.ArgumentParser(prog="swarph install-opencode-plugin")
+    p.add_argument("--scope", choices=("user", "project"), default="user")
+    p.add_argument("--uninstall", action="store_true")
+    p.add_argument("--dry-run", action="store_true")
+    args = p.parse_args(argv)
+
+    target = _target(args.scope)
+
+    if args.dry_run:
+        print(f"# swarph install-opencode-plugin --dry-run", file=sys.stderr)
+        print(f"#   scope:  {args.scope}", file=sys.stderr)
+        print(f"#   target: {target}", file=sys.stderr)
+        print(f"#   action: {'uninstall' if args.uninstall else 'install'}", file=sys.stderr)
+        if not args.uninstall:
+            print(_render())
+        return 0
+
+    if args.uninstall:
+        existed = target.exists()
+        if existed:
+            target.unlink()
+        print(
+            f"swarph install-opencode-plugin: uninstalled {_PLUGIN_NAME} from "
+            f"{target} ({'removed' if existed else 'was absent'}).",
+            file=sys.stderr,
+        )
+        return 0
+
+    rendered = _render()
+    if _read_existing(target) == rendered:
+        print(
+            f"swarph install-opencode-plugin: no change needed at {target} "
+            "(plugin already in desired state).",
+            file=sys.stderr,
+        )
+        return 0
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write_text(target, rendered)
+    # The #527 task-3 assert: "installed" is a claim about the filesystem.
+    if target.read_text(encoding="utf-8") != rendered:
+        print(
+            f"swarph install-opencode-plugin: WRITE DID NOT LAND — {target} "
+            "re-reads as different content than was written. The install is NOT "
+            "in effect.",
+            file=sys.stderr,
+        )
+        return 2
+    print(
+        f"swarph install-opencode-plugin: installed {_PLUGIN_NAME} at {target}.",
+        file=sys.stderr,
+    )
+    print(
+        "NOTE: opencode loads the plugin table at session start. Already-open "
+        "sessions keep the pre-edit table — open a FRESH session before testing.",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_install_opencode_plugin(sys.argv[1:]))

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/src/swarph_cli/commands/mcp_server.py

@@ -151,7 +151,8 @@ def _codegraph_query(query: str, *, limit: int = 8) -> list[dict]:
 
     Delegates to :func:`codegraph.structural_query` against the module-level
     ``_CODEGRAPH_INDEX`` path, using ``SWARPH_CELL`` (else
-    ``codegraph.DEFAULT_CALLER_CELL``) as the A8 caller identity and the
+    ``codegraph.require_caller_cell``, which REFUSES rather than defaulting) as
+    the A8 caller identity and the
     default operate-what-you-own allowlist (``allowlist=None``).
 
     NEVER raises — any exception (missing index, corrupt db, bad query, or
@@ -162,7 +163,13 @@ def _codegraph_query(query: str, *, limit: int = 8) -> list[dict]:
     to keep the tool output tight for the calling agent.
     """
     try:
-        caller_cell = os.environ.get("SWARPH_CELL", codegraph.DEFAULT_CALLER_CELL)
+        # NO DEFAULT IDENTITY (2026-09-18). `codegraph.DEFAULT_CALLER_CELL` is gone;
+        # an undeclared caller used to become lab-ovh and receive that cell's read
+        # authority. require_caller_cell raises IdentityNotDeclared, which the
+        # NEVER-RAISES contract below turns into an empty result — FAIL-CLOSED: the
+        # MCP host gets nothing rather than somebody else's answer.
+        caller_cell = codegraph.require_caller_cell(
+            os.environ.get("SWARPH_CELL"), verb="mcp codegraph_query")
         rows = codegraph.structural_query(
             query,
             index_path=_CODEGRAPH_INDEX,

{swarph_cli-0.61.0 → swarph_cli-0.63.0}/src/swarph_cli/commands/memory_emit_hook.py

@@ -67,15 +67,37 @@ def _memory_slug(file_path: str) -> Optional[str]:
 
 
 def _snippet(path: Path) -> str:
-    """First non-empty line, de-headed, collapsed, truncated. Unreadable file →
-    empty snippet (the pointer still emits — the write happened either way)."""
+    """One-line summary of a memory: its frontmatter `description`, else the first body
+    line. Unreadable file → empty snippet (the pointer still emits — the write happened).
+
+    Every memory file opens with YAML frontmatter, so "first non-empty line" returned the
+    literal `---` delimiter. That is a NON-EMPTY STRING, so the caller's `if snippet` guard
+    passed and the timeline took `memory cached: ---`. MEASURED 2026-09-15: 21 such entries
+    on the shared timeline between 2026-08-25 and 2026-09-15, every one of them useless.
+    An emptiness guard cannot catch a delimiter; the fix has to be here, not at the guard.
+    """
     try:
-        for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
-            s = line.strip().lstrip("#").strip()
-            if s:
-                return " ".join(s.split())[:_SNIPPET_CHARS]
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
     except Exception:
-        pass
+        return ""
+    body = lines
+    if lines and lines[0].strip() == "---":
+        for i, line in enumerate(lines[1:], start=1):
+            if line.strip() == "---":
+                # `description:` exists precisely to be a one-line summary — prefer it.
+                for fm in lines[1:i]:
+                    if fm.strip().lower().startswith("description:"):
+                        d = fm.split(":", 1)[1].strip().strip('"').strip("'")
+                        if d:
+                            return " ".join(d.split())[:_SNIPPET_CHARS]
+                body = lines[i + 1:]
+                break
+        else:
+            body = lines[1:]          # unterminated frontmatter: skip the opening delimiter
+    for line in body:
+        s = line.strip().lstrip("#").strip()
+        if s and s != "---":          # a stray delimiter is never a summary
+            return " ".join(s.split())[:_SNIPPET_CHARS]
     return ""