code-coordinator 0.5.80__tar.gz → 0.5.81__tar.gz

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.80
+Version: 0.5.81
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.80
+Version: 0.5.81
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.80",
+  "tag": "0.5.81",
   "distance": 0,
-  "node": "g8c6e8430b5fa1613efee27434db00b3e3b59d32b",
+  "node": "gf5568b98773fd08c6165236df1c398d57ecc9260",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-14"

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/coord/agent.py

@@ -756,13 +756,11 @@ def _graphify_update(repo_path: Path, *, timeout: float = 600.0) -> tuple[bool,
 # across N consecutive legs means the prompt instruction isn't landing.
 # Deliberately NOT a DB column: this is a cheap, best-effort signal, not a
 # gate anything blocks on, so it stays out of the Assignment schema/migrations.
-# Separators recognized before a command token: `;`, `&`, `|` (covers `&&`
-# and `||` too, since `\s*` after the class soaks up the second char) and a
-# bare newline — Claude Code's Bash tool very commonly emits multi-line
-# command strings (e.g. `cd repo\ngraphify query "foo"`) that aren't joined
-# with `;`/`&&`, so newline must count as a separator or those legs
-# undercount to 0 (#2212 review).
-_GRAPHIFY_INVOCATION_RE = re.compile(r"(?:^|[\n;&|]\s*)graphify(?:\s|$)")
+# #2236: the pattern itself now lives in `coord.worker_events`, which grew a
+# need for it when the summary parser started recording each query's OUTCOME
+# and not just the count. Imported lazily (like every other
+# `coord.worker_events` use in this module) rather than duplicated, so the two
+# halves of the measurement can never drift apart on what counts as a query.
 
 
 def _count_graphify_invocations(bash_commands: list[str]) -> int:
@@ -781,7 +779,68 @@ def _count_graphify_invocations(bash_commands: list[str]) -> int:
     b"`` counts once, not twice. Treat the result as an "at least one graph
     query this leg" signal, not an exact invocation tally.
     """
-    return sum(1 for cmd in bash_commands if cmd and _GRAPHIFY_INVOCATION_RE.search(cmd))
+    from coord.worker_events import is_graphify_command  # noqa: PLC0415
+
+    return sum(1 for cmd in bash_commands if is_graphify_command(cmd))
+
+
+def _worktree_graph_present(
+    worktree_path: str | None, repo_path_fallback: str | None = None
+) -> bool:
+    """True iff the worker's checkout has a **resolvable** ``graphify-out/graph.json``.
+
+    #2236: ``graphify_invocations=0`` is ambiguous on its own. Two of five
+    repos ship no graph and no ``.githooks/post-checkout``, so their worktrees
+    get an empty ``graphify-out/`` — and the worker prompt's own escape hatch
+    ("no graph? skip straight to grep, silently") then fires correctly and
+    says nothing. Those workers were *obeying* the rule, not ignoring it, and
+    the counter cannot tell them apart from a worker that had a graph and
+    never asked. Recording this alongside the count is what disambiguates.
+
+    *repo_path_fallback* mirrors the branch-capture logic a few hundred
+    lines up in ``_reap`` ("for legacy assignments (no worktree_path) we
+    fall back to the main repo clone"): a legacy/non-worktree assignment has
+    no ``worktree_path`` at all, but its worker still ran against
+    ``spec.repo_path`` directly, which may have a perfectly good graph.
+    Without this fallback, every legacy assignment logs ``graph_present=0``
+    regardless — conflating "no worktree" with "no graph".
+
+    ``exists()`` follows symlinks deliberately: a linked worktree's
+    ``graph.json`` is a symlink into the base checkout (see
+    ``coord/graph_health.py``), and a *dangling* symlink is exactly as
+    graph-blind as no file at all — so both must read as absent.
+    """
+    path = worktree_path or repo_path_fallback
+    if not path:
+        return False
+    try:
+        return (Path(path) / "graphify-out" / "graph.json").exists()
+    except OSError:
+        return False
+
+
+def _format_graphify_query_lines(queries: Iterable[Any]) -> list[str]:
+    """Render per-query ``# graphify_query …`` log lines (#2236).
+
+    ``graphify_invocations=N`` counts attempts but cannot distinguish
+    "queried and got a useful answer" from "queried, got nothing, fell back to
+    grep" — and those imply opposite fixes (a habit problem the prompt can
+    move, vs. a graph coverage/quality problem no amount of prompting helps).
+    One line per query, ``grep``-able on ``outcome=``, with the command text
+    last because it is the only free-form field.
+    """
+    lines: list[str] = []
+    for q in queries:
+        results = getattr(q, "results", None)
+        # `worker_events._truncate` already newline-strips and trims this
+        # when the `GraphifyQuery` entry is built — no need to redo it here.
+        command = str(getattr(q, "command", ""))
+        lines.append(
+            f"# graphify_query: outcome={getattr(q, 'outcome', 'unknown')} "
+            f"results={results if results is not None else '?'} "
+            f"cmd={command!r}\n"
+        )
+    return lines
 
 
 def _infer_repo_github_slug(repo_path: str) -> str | None:
@@ -7511,9 +7570,27 @@ class AgentServer:
                 _graphify_invocations = _count_graphify_invocations(
                     _worker_summary.bash_commands if _worker_summary is not None else []
                 )
+                # #2236: the count alone can't separate "didn't try" from
+                # "couldn't try" (no graph in this worktree — the prompt's own
+                # escape hatch fires silently) or from "tried, got nothing".
+                # `graph_present` answers the first; the per-query lines below
+                # answer the second. Read while the worktree still exists —
+                # `_cleanup_worktree` runs further down this same function.
+                _graph_present = _worktree_graph_present(
+                    getattr(assignment, "worktree_path", None) if assignment else None,
+                    getattr(assignment.spec, "repo_path", None) if assignment else None,
+                )
                 reopen.write(
                     f"# reap: done (exit_code={exit_code} status={final_status} "
-                    f"graphify_invocations={_graphify_invocations})\n"
+                    f"graphify_invocations={_graphify_invocations} "
+                    f"graph_present={int(_graph_present)})\n"
+                )
+                reopen.writelines(
+                    _format_graphify_query_lines(
+                        _worker_summary.graphify_queries
+                        if _worker_summary is not None
+                        else []
+                    )
                 )
         except (OSError, AttributeError):
             pass

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/coord/graph_health.py

@@ -280,6 +280,18 @@ def graph_status(repo_path: Path, default_branch: str = "main") -> GraphStatus:
     return st
 
 
+def hooks_file_present(repo_path: Path) -> bool:
+    """Does this repo TRACK ``.githooks/post-checkout`` at all?
+
+    Split out of :func:`hooks_path_status` (#2236) so callers that only need
+    "does the repo ship the hook file" — as opposed to the full
+    ``core.hooksPath`` configuration story — have one place to ask, instead
+    of independently re-running the same ``.is_file()`` check (a split-brain
+    the two would otherwise be one edit away from disagreeing on).
+    """
+    return (repo_path / HOOKS_PATH / "post-checkout").is_file()
+
+
 def hooks_path_status(repo_path: Path) -> tuple[bool, str]:
     """``(ok, detail)`` for this checkout's ``core.hooksPath``.
 
@@ -298,7 +310,7 @@ def hooks_path_status(repo_path: Path) -> tuple[bool, str]:
     except (subprocess.SubprocessError, OSError) as exc:
         return False, f"could not read core.hooksPath ({exc})"
     value = r.stdout.strip()
-    have_hook = (repo_path / HOOKS_PATH / "post-checkout").is_file()
+    have_hook = hooks_file_present(repo_path)
     if not value:
         if not have_hook:
             # The repo doesn't ship the bootstrap at all — telling the operator

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/coord/providers/opencode.py

@@ -830,6 +830,19 @@ def _update_opencode_summary(summary: WorkerSummary, data: dict) -> None:
             cmd = tool_input.get("command")
             if isinstance(cmd, str) and cmd:
                 summary.bash_commands.append(cmd)
+                # #2236: same graph-usage instrumentation the claude parser
+                # does. opencode carries the call and its output in one event,
+                # so the outcome settles here instead of on a later
+                # `tool_result`.
+                from coord.worker_events import record_graphify_call  # noqa: PLC0415
+
+                _out = state.get("output")
+                record_graphify_call(
+                    summary,
+                    cmd,
+                    output=_out if isinstance(_out, str) else None,
+                    is_error=state.get("status") == "error",
+                )
         elif tool in ("edit", "write"):
             fp = tool_input.get("filePath")
             if isinstance(fp, str) and fp:

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/coord/repo_onboard.py

@@ -144,6 +144,16 @@ class GraphFacts:
     detail: str | None = None
     hooks_installed: bool = False
     hooks_detail: str | None = None
+    # #2236: does the repo TRACK `.githooks/post-checkout` at all? Two
+    # distinct failures hide behind `hooks_installed=False`, and they take
+    # opposite fixes: a repo that ships the hook but hasn't pointed
+    # `core.hooksPath` at it needs one `git config`; a repo that never ported
+    # the hook (coord-portal, stick-demo) needs the files first — running
+    # `git config core.hooksPath .githooks` there points git at a directory
+    # that does not exist, which silently disables ALL hooks for that
+    # checkout. Telling an operator the wrong one is worse than saying
+    # nothing, so the fix line has to know which it is.
+    hooks_shipped: bool = False
 
 
 @dataclass
@@ -326,6 +336,13 @@ def gather_graph_facts(repo_path: Path | None, default_branch: str = "main") ->
         ok, detail = False, f"hooks probe failed: {exc}"
     facts.hooks_installed = bool(ok)
     facts.hooks_detail = detail
+    try:
+        # Same question `hooks_path_status` already answers internally —
+        # consume its `hooks_file_present` helper rather than re-running the
+        # `.is_file()` check independently (#2236 review: split-brain risk).
+        facts.hooks_shipped = graph_health.hooks_file_present(repo_path)
+    except OSError:
+        facts.hooks_shipped = False
     return facts
 
 
@@ -882,7 +899,27 @@ def evaluate_graph(facts: RepoFacts) -> list[Finding]:
             summary="graph artifact is current with HEAD",
         ))
 
-    if not g.hooks_installed:
+    if not g.hooks_installed and not g.hooks_shipped:
+        # #2236: the repo never ported the hook. `git config core.hooksPath
+        # .githooks` here would point git at a directory that does not exist
+        # and disable every hook in the checkout, so the fix is to bring the
+        # files over FIRST — worktrees of this repo get no linked graph until
+        # then, however the machine is configured.
+        out.append(Finding(
+            layer="graph", check="graph.hooks_not_ported", severity=WARN,
+            summary=(
+                f"this repo ships no .githooks/post-checkout — "
+                f"{g.hooks_detail or 'the worktree graph bootstrap does not exist here'}; "
+                "worktrees get no linked graph, so every worker on this repo "
+                "silently falls back to grep"
+            ),
+            fix=(
+                "port .githooks/ (_lib.sh, post-checkout, post-commit, post-merge) "
+                "from claude-coordinator into this repo, THEN "
+                "git config core.hooksPath .githooks  (see docs/GRAPHIFY_SETUP.md)"
+            ),
+        ))
+    elif not g.hooks_installed:
         out.append(Finding(
             layer="graph", check="graph.hooks_missing", severity=WARN,
             summary=(

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/coord/worker_events.py

@@ -44,6 +44,110 @@ class WorkerEvent:
         return {"type": self.type, "subtype": self.subtype, "raw": self.raw}
 
 
+# #2212/#2236: recognise a `graphify` CLI call inside a Bash command string.
+# Separators recognized before the command token: `;`, `&`, `|` (covers `&&`
+# and `||` too, since `\s*` after the class soaks up the second char) and a
+# bare newline — Claude Code's Bash tool very commonly emits multi-line
+# command strings (e.g. `cd repo\ngraphify query "foo"`) that aren't joined
+# with `;`/`&&`, so newline must count as a separator or those legs
+# undercount to 0 (#2212 review).  Anchoring on a separator is what keeps a
+# path mention (`cat graphify-out/graph.json`) from counting as a query.
+# Canonical home is here rather than in coord/agent.py (#2236) because the
+# summary parser now needs it too — agent.py imports this symbol.
+GRAPHIFY_INVOCATION_RE = re.compile(r"(?:^|[\n;&|]\s*)graphify(?:\s|$)")
+
+# Longest command text kept per query.  The point is to tell one query apart
+# from another when reading logs, not to replay it — a multi-KB heredoc in the
+# same Bash call would otherwise bloat every reap line.
+_GRAPHIFY_CMD_MAX = 200
+
+# graphify query prints a `… | 81 nodes found` traversal header; when the
+# header is absent (other subcommands, older builds) we fall back to counting
+# result rows, which are line-prefixed with the record kind.
+_GRAPHIFY_COUNT_RE = re.compile(r"(\d+)\s+(?:nodes?|results?|matches?)\s+found", re.I)
+_GRAPHIFY_ROW_RE = re.compile(r"^(?:NODE|EDGE|PATH|COMMUNITY)\b", re.M)
+
+# graphify's real zero-match phrasing: `graphify query` prints the literal
+# "No matching nodes found." (graphify/serve.py:435, vs. the "{N} nodes
+# found" header on a hit, graphify/serve.py:445) and `graphify affected`
+# prints "No affected nodes found." (graphify/affected.py:132). Neither has a
+# leading digit, so `_GRAPHIFY_COUNT_RE` never matches it, and neither is
+# NODE/EDGE/PATH/COMMUNITY-prefixed, so `_GRAPHIFY_ROW_RE` doesn't either —
+# without this, a real "ran the query, graph doesn't cover that" result fell
+# through to `None` ("unknown") instead of `0` ("empty"), which is precisely
+# the "tried and got nothing must not look like never tried" case #2236
+# exists to fix.
+_GRAPHIFY_EMPTY_RE = re.compile(r"No (?:matching|affected) \w+ found\.?", re.I)
+
+
+def is_graphify_command(cmd: str | None) -> bool:
+    """True iff *cmd* invokes the ``graphify`` CLI as a command token."""
+    return bool(cmd) and bool(GRAPHIFY_INVOCATION_RE.search(cmd or ""))
+
+
+def graphify_result_count(output: str | None) -> int | None:
+    """Best-effort "how many results did this graphify call return".
+
+    Reads the ``N nodes found`` traversal header graphify prints first; falls
+    back to counting ``NODE``/``EDGE``/``PATH``/``COMMUNITY`` result rows,
+    then to graphify's literal "No matching/affected ... found." zero-match
+    phrasing, and then to "0 for empty output". Returns ``None`` when the
+    output has content but no recognisable result shape (e.g. ``graphify
+    update .``, whose output is a build log) — ``None`` means "not
+    countable", which is deliberately distinct from ``0`` ("ran, returned
+    nothing"), because the whole point of #2236 is to tell *tried and got
+    nothing* apart from *didn't try*.
+    """
+    if output is None:
+        return None
+    if not output.strip():
+        return 0
+    m = _GRAPHIFY_COUNT_RE.search(output)
+    if m:
+        try:
+            return int(m.group(1))
+        except ValueError:  # pragma: no cover - regex guarantees digits
+            return None
+    rows = len(_GRAPHIFY_ROW_RE.findall(output))
+    if rows:
+        return rows
+    if _GRAPHIFY_EMPTY_RE.search(output):
+        return 0
+    return None
+
+
+@dataclass
+class GraphifyQuery:
+    """One ``graphify`` invocation by a worker, and what it returned (#2236).
+
+    ``graphify_invocations=N`` (#2212) counts attempts, which cannot separate
+    "queried and got a useful answer" from "queried, got nothing, fell back to
+    grep" — and those two imply opposite fixes (habit vs. graph coverage). So
+    each call is recorded with its command text and the outcome of its tool
+    result.
+
+    ``outcome`` is one of:
+
+    * ``"hit"`` — returned at least one countable result.
+    * ``"empty"`` — ran fine and returned nothing (graph coverage problem).
+    * ``"error"`` — the tool result was flagged as an error (e.g. no graph
+      built here, graphify not installed).
+    * ``"unknown"`` — no result was correlated (log truncated to a tail, or
+      output shape not countable, e.g. ``graphify update .``).
+    """
+
+    command: str
+    outcome: str = "unknown"
+    results: int | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "command": self.command,
+            "outcome": self.outcome,
+            "results": self.results,
+        }
+
+
 @dataclass
 class WorkerSummary:
     """Rolling summary built from a stream of WorkerEvents."""
@@ -60,6 +164,13 @@ class WorkerSummary:
     last_tool: str | None = None
     files_edited: list[str] = field(default_factory=list)
     bash_commands: list[str] = field(default_factory=list)
+    # #2236: one entry per `graphify` invocation, with the outcome of its tool
+    # result folded in when the log carries one.  See :class:`GraphifyQuery`.
+    graphify_queries: list[GraphifyQuery] = field(default_factory=list)
+    # tool_use_id -> index into `graphify_queries`, so a later `tool_result`
+    # can be attributed back to the call that produced it.  Internal bookkeeping
+    # for `update_summary`'s fold; deliberately excluded from `to_dict`.
+    pending_graphify: dict[str, int] = field(default_factory=dict, repr=False)
     duration_ms: int | None = None
     # Token counts from the result event (may be zero if the log predates
     # token reporting or the worker didn't emit usage data).
@@ -96,6 +207,7 @@ class WorkerSummary:
             "last_tool": self.last_tool,
             "files_edited": list(self.files_edited),
             "bash_commands": list(self.bash_commands),
+            "graphify_queries": [q.to_dict() for q in self.graphify_queries],
             "duration_ms": self.duration_ms,
             "input_tokens": self.input_tokens,
             "output_tokens": self.output_tokens,
@@ -495,6 +607,87 @@ def _assistant_text(event: WorkerEvent) -> str:
 # ── Streaming summary update ───────────────────────────────────────────────
 
 
+def record_graphify_call(
+    summary: WorkerSummary,
+    cmd: str | None,
+    *,
+    tool_use_id: object = None,
+    output: str | None = None,
+    is_error: bool = False,
+) -> None:
+    """Record a graphify shell call on *summary*, if *cmd* is one (#2236).
+
+    Providers whose log carries the call and its output in one event (e.g.
+    opencode) pass ``output``/``is_error`` and the outcome is settled
+    immediately. Claude's stream-json splits the two across a ``tool_use``
+    block and a later ``tool_result``, so it passes ``tool_use_id`` instead
+    and the outcome is filled in by :func:`_resolve_graphify_result`. A call
+    with neither stays ``outcome="unknown"``, which is the honest reading: we
+    saw the attempt and never saw what came back.
+    """
+    if not is_graphify_command(cmd):
+        return
+    entry = GraphifyQuery(command=_truncate(cmd or "", _GRAPHIFY_CMD_MAX))
+    summary.graphify_queries.append(entry)
+    if output is not None or is_error:
+        _apply_graphify_outcome(entry, output, is_error)
+        return
+    if isinstance(tool_use_id, str) and tool_use_id:
+        summary.pending_graphify[tool_use_id] = len(summary.graphify_queries) - 1
+
+
+def _apply_graphify_outcome(
+    entry: GraphifyQuery, output: str | None, is_error: bool
+) -> None:
+    if is_error:
+        entry.outcome = "error"
+        return
+    count = graphify_result_count(output)
+    entry.results = count
+    entry.outcome = "unknown" if count is None else ("hit" if count > 0 else "empty")
+
+
+def _resolve_graphify_result(
+    summary: WorkerSummary, tool_use_id: object, output: str | None, is_error: bool
+) -> None:
+    """Attribute a tool result back to the graphify call that issued it."""
+    if not isinstance(tool_use_id, str):
+        return
+    idx = summary.pending_graphify.pop(tool_use_id, None)
+    if idx is None or idx >= len(summary.graphify_queries):
+        return
+    _apply_graphify_outcome(summary.graphify_queries[idx], output, is_error)
+
+
+def _tool_result_output(block: dict, raw: dict) -> str | None:
+    """Text of a tool_result block, across the shapes claude emits.
+
+    ``content`` is either a plain string or a list of ``{"type": "text",
+    "text": ...}`` blocks; the sibling ``tool_use_result.stdout`` on the
+    envelope is used as a fallback for Bash calls whose content came through
+    empty.
+    """
+    content = block.get("content")
+    text: str | None = None
+    if isinstance(content, str):
+        text = content
+    elif isinstance(content, list):
+        parts = [
+            c.get("text")
+            for c in content
+            if isinstance(c, dict) and isinstance(c.get("text"), str)
+        ]
+        text = "\n".join(parts) if parts else None
+    if text:
+        return text
+    tur = raw.get("tool_use_result")
+    if isinstance(tur, dict):
+        stdout = tur.get("stdout")
+        if isinstance(stdout, str):
+            return stdout
+    return text
+
+
 def update_summary(summary: WorkerSummary, event: WorkerEvent) -> None:
     """Fold *event* into *summary* in-place."""
     raw = event.raw
@@ -525,6 +718,7 @@ def update_summary(summary: WorkerSummary, event: WorkerEvent) -> None:
                     cmd = _command_from_input(block.get("input"))
                     if cmd:
                         summary.bash_commands.append(cmd)
+                        record_graphify_call(summary, cmd, tool_use_id=block.get("id"))
                 elif name in ("Edit", "Write", "NotebookEdit"):
                     fp = _file_from_input(block.get("input"))
                     if fp:
@@ -540,12 +734,43 @@ def update_summary(summary: WorkerSummary, event: WorkerEvent) -> None:
             cmd = _bash_command_from_event(event)
             if cmd:
                 summary.bash_commands.append(cmd)
+                record_graphify_call(
+                    summary, cmd, tool_use_id=raw.get("id") or raw.get("tool_use_id")
+                )
         elif name in ("Edit", "Write", "NotebookEdit"):
             fp = _file_path_from_event(event)
             if fp:
                 summary.files_edited.append(fp)
         return
 
+    # #2236: tool results arrive either as `user` messages carrying
+    # `tool_result` content blocks (claude's stream-json shape) or as
+    # standalone `tool_result` events (older/other providers). Both are
+    # folded here purely to attribute an outcome to a pending graphify call —
+    # nothing else in the summary depends on results, so an unrecognised
+    # shape just leaves the entry `"unknown"`.
+    if event.type == "user":
+        message = raw.get("message") or {}
+        for block in _iter_content_blocks(message):
+            if block.get("type") != "tool_result":
+                continue
+            _resolve_graphify_result(
+                summary,
+                block.get("tool_use_id"),
+                _tool_result_output(block, raw),
+                bool(block.get("is_error")),
+            )
+        return
+
+    if event.type == "tool_result":
+        _resolve_graphify_result(
+            summary,
+            raw.get("tool_use_id"),
+            _tool_result_output(raw, raw),
+            bool(raw.get("is_error")),
+        )
+        return
+
     if event.type == "rate_limit_event":
         status, resets = _rate_limit_info(raw)
         if _is_rate_limit_throttled(status):

{code_coordinator-0.5.80 → code_coordinator-0.5.81}/docs/GRAPHIFY_SETUP.md

@@ -110,6 +110,50 @@ GRAPH_HEALTH: checkouts=3 stale=0
 
 If it reports STALE, run `graphify update .` in that checkout.
 
+## Measuring whether workers actually use it (#2212 / #2236)
+
+Every reaped worker's log ends with a line the agent writes itself:
+
+```
+# reap: done (exit_code=0 status=DONE graphify_invocations=1 graph_present=1)
+# graphify_query: outcome=hit results=81 cmd='graphify query "where is X handled"'
+```
+
+* **`graphify_invocations=N`** (#2212) — how many Bash calls this leg invoked the CLI in.
+* **`graph_present=0|1`** (#2236) — whether the worktree had a **resolvable**
+  `graphify-out/graph.json` at reap time. Without it, `graphify_invocations=0` is ambiguous:
+  the worker prompt tells workers with no graph to *"skip straight to grep, silently"*, so a
+  repo that never onboarded (no graph, no `.githooks/post-checkout` — coord-portal and
+  stick-demo, as of this writing) produces zero-invocation legs that were **obeying** the rule,
+  not ignoring it. `graphify_invocations=0 graph_present=0` is a coverage gap; `=0` with
+  `graph_present=1` is a habit gap. Only the second is something prompt wording can move.
+* **`# graphify_query:`** (#2236) — one line per call, with `outcome=hit|empty|error|unknown`,
+  the result count, and the command. `hit` vs `empty` separates *"queried and got an answer"*
+  from *"queried, got nothing, fell back to grep"* — opposite fixes: `empty` points at graph
+  coverage/quality, and no amount of prompting helps there.
+
+  `unknown` is honest, not a bug bucket — don't read it as "worker got no answer". Only
+  `graphify query` output is reliably countable (its `N nodes found` header, or a fallback
+  count of `NODE`/`EDGE`/`PATH`/`COMMUNITY` result rows, or graphify's own zero-match
+  phrasing, `"No matching/affected ... found."`). `graphify explain` and `graphify path` print
+  differently-shaped output with no countable header at all, so calls to those land in
+  `unknown` even when they returned a perfectly good answer. Skimming
+  `grep -c outcome=unknown` and reading it as "workers not getting answers" over-reads that
+  number — it may just mean "workers ran `explain`/`path`, not `query`".
+
+Count them straight off the fleet's logs:
+
+```bash
+grep -ho 'graphify_invocations=[0-9]* graph_present=[01]' ~/.coord/logs/*.log | sort | uniq -c
+grep -ho 'graphify_query: outcome=[a-z]*' ~/.coord/logs/*.log | sort | uniq -c
+```
+
+**`outcome=hit` means non-empty, not useful.** The counter cannot see relevance: a query
+against a graph that indexed the wrong things returns rows and scores as a hit. A run of `hit`
+outcomes that workers still abandon after one query is the signal that the graph's *content*,
+not the worker's habit, is what needs work — cross-check with `coord diagnose --graph` for a
+graph built from a stale SHA.
+
 ## Traps
 
 **`core.hooksPath` REPLACES `.git/hooks` wholesale.** Git stops looking in `.git/hooks`